com.cisco.provisioning.cpe
Interface PACEConnection

All Superinterfaces:

ProvAPIEventManager

public interface PACEConnection
extends ProvAPIEventManager

This interface defines the methods to use by the clients to create and manage communication with the PACE Server inclusing creating, posting, and joining batches, as well as registering and distributing events to clients.

Sample Usage:

       ...
      // Create a new PACE connection to the RDU
      PACEConnection connection =
          PACEConnectionFactory.newInstance(
              "localhost", 49187, "admin", "changeme");

      // Get a new Batch from the connection object
      Batch batch = connection.newBatch();

      // Add a new DOCSIS device
      List devIds = new ArrayList();
      devIds.add(DeviceID.getInstance("1,6,00:00:00:00:00:99", 
                KeyType.MAC_ADDRESS));
      batch.add(DeviceType.DOCSIS, devIds,
                "testHost", "testIsp.com", "testOwnerID", "testCoS",
                "testDhcpCriteria", null);

      // Submit the batch asynchronously to the RDU for processing
      batch.postNoStatus();

      // Join the batch to get the results.
      // NOTE - in real code this would probably be joined by
      // NOTE - another thread.  Real code to do this would
      // NOTE - most likely use batch.post() and not use join()
      BatchStatus status = batch.join(batch.getBatchID());

      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }

      // Release the PACEConnection object when finished using it
      connection.releaseConnection();
       ...
 

See Also:

ProvAPIEventManager

Method Summary

String	getHost() Returns the hostName of the RDU to which this PACEConnection connects.
int	getPort() Returns the RDU port number to which this PACEConnection connects.
String	getUsername() Returns the username used in making PACEConnection connect.
boolean	isAlive() Determines whether the connection the RDU has been opened.
BatchStatus	joinBatch(String batchID) Retrieves the results of a previously posted batch.
BatchStatus	joinBatch(String batchID, long timeout) Retrieves the results of a previously posted batch.
Batch	newBatch() Creates a new batch with a globally-unique batch ID.
Batch	newBatch(ActivationMode activation) Gets a new batch with a globally-unique batch ID and the specified ActivationMode The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION The PublishingMode defaults to PublishingMode.NO_PUBLISHING
Batch	newBatch(ActivationMode activation, ConfirmationMode confirmation) Gets a new batch with a globally-unique batch ID and the specified ActivationMode and ConfirmationMode The PublishingMode defaults to PublishingMode.NO_PUBLISHING
Batch	newBatch(ActivationMode activation, ConfirmationMode confirmation, PublishingMode publishing) Gets a new batch with a globally-unique batch ID and the specified ActivationMode, ConfirmationMode, and PublishingMode
Batch	newBatch(ActivationMode activation, PublishingMode publishing) Gets a new batch with a globally-unique batch ID with the specified ActivationMode and PublishingMode The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION
Batch	newBatch(PublishingMode publishing) Gets a new batch with a globally-unique batch ID with the specified PublishingMode The ActivationMode defaults to ActivationMode.NO_ACTIVATION The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION
Batch	newBatch(String batchID) Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted).
Batch	newBatch(String batchID, ActivationMode activation) Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION The PublishingMode defaults to PublishingMode.NO_PUBLISHING
Batch	newBatch(String batchID, ActivationMode activation, ConfirmationMode confirmation) Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode and ConfirmationMode The PublishingMode defaults to PublishingMode.NO_PUBLISHING
Batch	newBatch(String batchID, ActivationMode activation, ConfirmationMode confirmation, PublishingMode publishing) Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode, ConfirmationMode, and PublishingMode
Batch	newBatch(String batchID, ActivationMode activation, PublishingMode publishing) Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode and PublishingMode The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION
Batch	newBatch(String batchID, PublishingMode publishing) Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified PublishingMode The ActivationMode defaults to ActivationMode.NO_ACTIVATION The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION
boolean	openConnection() Open a connection to the RDU.
BatchStatus	postBatch(Batch batch) Sends a batch to the RDU for execution.
BatchStatus	postBatch(Batch batch, long timeout) Sends a batch to the RDU for execution.
void	postBatchNoStatus(Batch batch) Sends a batch to the RDU for execution.
void	releaseConnection() Release this RDU connection.

Methods inherited from interface com.cisco.provisioning.cpe.events.ProvAPIEventManager

addBatchListener, addCOSListener, addCRSCompleteListener, addDeviceListener, addDeviceTypeListener, addDHCPCriteriaListener, addFileListener, addMessagingListener, addProvGroupListener, addSystemConfigListener, fireBatchEvent, fireCOSEvent, fireCRSCompleteEvent, fireDeviceEvent, fireDeviceTypeEvent, fireDHCPCriteriaEvent, fireMessagingEvent, fireNodeEvent, fireNodeTypeEvent, fireProvGroupEvent, fireSystemConfigEvent, removeBatchListener, removeCOSListener, removeCRSCompleteListener, removeDeviceListener, removeDeviceTypeListener, removeDHCPCriteriaListener, removeFileListener, removeMessagingListener, removeNodeListener, removeNodeTypeListener, removeProvGroupListener, removeSystemConfigListener

Method Detail

openConnection

boolean openConnection()

Open a connection to the RDU. This will re-register any listeners that have been registered with the RDU. This is called automatically when a batch is posted and the connection to the RDU was never opened or is not currently open.

Returns:

true is returned if the connection is successfully established, else false.

Throws:

PACEConnectionException - if this method is called after PACEConnection.releaseConnection has been called.

AuthenticationException - if the authentication parameters specified when creating the connection are invalid.

releaseConnection

void releaseConnection()

Release this RDU connection. Call this when finished using this connection to allow resources to be properly cleaned up and released. Once this is called, this PACE connection can no longer be used to submit batches.

getHost

String getHost()

Returns the hostName of the RDU to which this PACEConnection connects.

Returns:

the hostname of the RDU to which this PACEConnection connects.

getPort

int getPort()

Returns the RDU port number to which this PACEConnection connects.

Returns:

the RDU port number to which this PACEConnection connects.

getUsername

String getUsername()

Returns the username used in making PACEConnection connect.

Returns:

the username used in making PACEConnection connect.

isAlive

boolean isAlive()

Determines whether the connection the RDU has been opened.

Note: The value is an instantaneous value of the PACEConnection state when the isAlive() method is called.

Returns:

true if the connection to the RDU is open, otherwise false.

newBatch

Batch newBatch()

Creates a new batch with a globally-unique batch ID.

The ActivationMode defaults to ActivationMode.NO_ACTIVATION

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

The PublishingMode defaults to PublishingMode.NO_PUBLISHING

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(String batchID)

Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted).

The ActivationMode defaults to ActivationMode.NO_ACTIVATION

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

The PublishingMode defaults to PublishingMode.NO_PUBLISHING

Parameters:

batchID - user-supplied batch ID

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(ActivationMode activation)

Gets a new batch with a globally-unique batch ID and the specified ActivationMode

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

The PublishingMode defaults to PublishingMode.NO_PUBLISHING

Parameters:

activation - the ActivationMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(String batchID,
               ActivationMode activation)

Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

The PublishingMode defaults to PublishingMode.NO_PUBLISHING

Parameters:

batchID - user-supplied batch ID

activation - the ActivationMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(ActivationMode activation,
               ConfirmationMode confirmation)

Gets a new batch with a globally-unique batch ID and the specified ActivationMode and ConfirmationMode

The PublishingMode defaults to PublishingMode.NO_PUBLISHING

Parameters:

activation - the ActivationMode for this batch.

confirmation - the ConfirmationMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(String batchID,
               ActivationMode activation,
               ConfirmationMode confirmation)

Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode and ConfirmationMode

The PublishingMode defaults to PublishingMode.NO_PUBLISHING

Parameters:

batchID - user-supplied batch ID

activation - the ActivationMode for this batch.

confirmation - the ConfirmationMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(PublishingMode publishing)

Gets a new batch with a globally-unique batch ID with the specified PublishingMode

The ActivationMode defaults to ActivationMode.NO_ACTIVATION

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

Parameters:

publishing - the PublishingMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(String batchID,
               PublishingMode publishing)

Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified PublishingMode

The ActivationMode defaults to ActivationMode.NO_ACTIVATION

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

Parameters:

batchID - user-supplied batch ID

publishing - the PublishingMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(ActivationMode activation,
               PublishingMode publishing)

Gets a new batch with a globally-unique batch ID with the specified ActivationMode and PublishingMode

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

Parameters:

activation - the ActivationMode for this batch.

publishing - the PublishingMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(String batchID,
               ActivationMode activation,
               PublishingMode publishing)

Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode and PublishingMode

The ConfirmationMode defaults to ConfirmationMode.NO_CONFIRMATION

Parameters:

batchID - user-supplied batch ID

activation - the ActivationMode for this batch.

publishing - the PublishingMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(ActivationMode activation,
               ConfirmationMode confirmation,
               PublishingMode publishing)

Gets a new batch with a globally-unique batch ID and the specified ActivationMode, ConfirmationMode, and PublishingMode

Parameters:

activation - the ActivationMode for this batch.

confirmation - the ConfirmationMode for this batch.

publishing - the PublishingMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

newBatch

Batch newBatch(String batchID,
               ActivationMode activation,
               ConfirmationMode confirmation,
               PublishingMode publishing)

Gets a new batch, using a user-supplied batch ID, which must be unique (or the batch will fail to execute when it is posted) and the specified ActivationMode, ConfirmationMode, and PublishingMode

Parameters:

batchID - user-supplied batch ID

activation - the ActivationMode for this batch.

confirmation - the ConfirmationMode for this batch.

publishing - the PublishingMode for this batch.

Returns:

a newly created Batch object to be submitted to the RDU this PACEConnection is connected to

postBatch

BatchStatus postBatch(Batch batch)
                      throws ProvisioningException

Sends a batch to the RDU for execution. This call will wait synchronously until the batch completes and the results are returned.

If the batch submitted is was marked as a reliable batch and the connection to the RDU is interrupted, the connection will reestablish and obtain the results for the batch. Otherwise, an unrecognized batch ID error will be returned in the BatchStatus error message.

Note: There is a limitation as to the number of batch results the RDU will store. In order to prevent the RDU from consuming all available resources, the RDU will store the most recent 1000 batch results that were marked to be reliable and have not been retrieved. If the batch results are dropped and the results are later asked for, an unrecognized batch ID error will be returned in the BatchStatus error message.

Parameters:

batch - the Batch to send to the RDU for processing

Returns:

The BatchStatus object containing status and resuults from the processing of the specified batch.

Throws:

ProvisioningException - If there is an error communicating with the RDU. This exception is NOT thrown if there is an error while processing the specified batch. That type of error is reflected in the BatchStatus object returned.

Events fired:

BatchListener.BATCH_COMPLETE

postBatch

BatchStatus postBatch(Batch batch,
                      long timeout)
                      throws ProvisioningException

Sends a batch to the RDU for execution. This call will wait up to the specified timeout parameter before returning. If the timeout is reached an no reply has been received, the BatchStatus status code will be set to BatchStatusCode.BATCH_POST_TIMEOUT. Even though the batch post timed out, the RDU is still processing the batch and will fire a BatchListener.BATCH_COMPLETE event when it finishes processing the batch. After the timeout, the results may also be retrieved using the PACEConnection.joinBatch(String) or PACEConnection.joinBatch(String, long) method.

If the batch submitted is was marked as a reliable batch and the connection to the RDU is interrupted before the timeout is reached, the connection will attempt to reestablish the connection and obtain the results for the batch. Otherwise, an unrecognized batch ID error will be returned in the BatchStatus error message if the connection is interrupted.

If the conneciton to the RDU is interrupted and cannot be reestablished before the timeout parameter expires, then a BatchStatus object will be returned with the status code set to BatchStatusCode.BATCH_POST_TIMEOUT

Note: There is a limitation as to the number of batch results the RDU will store. In order to prevent the RDU from consuming all available resources, the RDU will store the most recent 1000 batch results that were marked to be reliable and have not been retrieved. If the batch results are dropped and the results are later asked for, an unrecognized batch ID error will be returned in the BatchStatus error message.

Parameters:

batch - the Batch to send to the RDU for processing

timeout - the maximum time to wait for a reply in milliseconds.

Returns:

An object containing status from this posting.

Throws:

ProvisioningException - If there is an error communicating with the RDU. This exception is NOT thrown if there is an error while processing the specified batch. That type of error is reflected in the BatchStatus object returned.

Events fired:

BatchListener.BATCH_COMPLETE

postBatchNoStatus

void postBatchNoStatus(Batch batch)
                       throws ProvisioningException

Sends a batch to the RDU for execution. This call will return immediately. Use this method to post batches asynchronously. Results can be retrieved by registering and listening for the BatchListener.BATCH_COMPLETE event or by calling the PACEConnection.joinBatch(String) or PACEConnection.joinBatch(String, long) method with the batch ID of the batch submitted.

Parameters:

batch - the Batch to send to the RDU for processing

Throws:

ProvisioningException - If there is an error communicating with the RDU. This exception is NOT thrown if there is an error while processing the specified batch. That type of error is reflected in the BatchStatus object.

Events fired:

BatchListener.BATCH_COMPLETE

joinBatch

BatchStatus joinBatch(String batchID)
                      throws ProvisioningException

Retrieves the results of a previously posted batch. This method waits synchronously until the RDU responds with the results.

Note: There is a limitation as to the number of batch results the RDU will store. In order to prevent the RDU from consuming all available resources, the RDU will store the most recent 1000 batch results that were marked to be reliable and have not been retrieved. If the batch results are no longer stored by the RDU, then an a ProvisioningException is thrown with a message describing that the RDU does not know about the specified batch ID.

Parameters:

batchID - ID of the Batch to retrieve the results for

Returns:

An object containing status from the posting.

Throws:

ProvisioningException - If there was a problem communicating with the RDU or if the specified batch ID is unknown to the RDU. This could occur if the posted batch was not specified to be reliable and the RDU was restarted after the batch was posted but before the results were retrieved.

Events fired:

BatchListener.BATCH_COMPLETE

joinBatch

BatchStatus joinBatch(String batchID,
                      long timeout)
                      throws ProvisioningException

Retrieves the results of a previously posted batch. This method waits at most until the specified timeout has expired for the results. If the timeout is reached an no reply has been received, the BatchStatus status code will be set to BatchStatusCode.BATCH_POST_TIMEOUT. Even though the join timed out, the RDU is still processing the batch and will still fire a BatchListener.BATCH_COMPLETE event when it finishes processing the batch.

Note: There is a limitation as to the number of batch results the RDU will store. In order to prevent the RDU from consuming all available resources, the RDU will store the most recent 1000 batch results that were marked to be reliable and have not been retrieved. If the batch results are no longer stored by the RDU, then an a ProvisioningException is thrown with a message describing that the RDU does not know about the specified batch ID.

Parameters:

batchID - ID of the Batch to retrieve the results for

timeout - the time to wait for a reply in milliseconds

Returns:

An object containing status from this posting.

Throws:

ProvisioningException - If there was a problem communicating with the RDU or if the specified batch ID is unknown to the RDU. This could occur if the posted batch was not specified to be reliable and the RDU was restarted after the batch was posted but before the results were retrieved.

Events fired:

BatchListener.BATCH_COMPLETE