com.cisco.provisioning.cpe
Interface Batch

All Superinterfaces:

Configuration, IPDevice, ProvAPI

public interface Batch
extends IPDevice, Configuration

The Batch object gives access to all the Provisioning API commands in BPR. It may be posted only once; attempting to add calls or re-post the batch after it has already been posted will result in a runtime exception.

Example how to use the batch:

 // Obtain an authenticated PACE connection to the RDU
 PACEConnection connection =
     PACEConnectionFactory.getInstance(
         "localhost", 49187, "admin", "changeme");

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

 // Make a call to add a DOCSIS Modem to the database
 // Since the Batch object implements the IPDevice interface, the "add"
 // method exists on the batch object
 
 List devIds = new ArrayList();
     devIds.add(new MACAddress("1,6,00:00:00:00:00:99"));
     devIds.add(new DUID("00:03:00:01:00:02:FC:A5:DC:1C"));
      
 String dhcpCriteria = "unprovisioned-docsis";
      
 batch.add(DeviceType.DOCSIS, devIds,
           "testHost", "testIsp.com", "testOwnerID", "testCoS", dhcpCriteria, null);
 // Add more API calls to the batch as desired on IPDevice or other API
 // implemented by the Batch object

 // post the batch to get the results
 BatchStatus status = batch.post();

 // Process the results
 if (status.isError())
 {
    ....
 }
 

As you can see, this newer method does not require object to be cast to the various interfaces. It is recommended that new code be written using this method whenever possible. Please note that the old and new methods can be used interchangably, even within the same batch, without any side effects.

See Also:

BatchStatus, PACEConnection, PACEConnectionFactory

Method Summary

void	addAPICall(com.cisco.provisioning.cpe.internal.APICall call) Adds an APICall object to the batch's list of method calls.
boolean	createdByClient() Indicates whether the Batch was created by the client API rather than a BPR server.
void	ensureConsistency(List oidRevNumbers) Sends a list of OID revision numbers to validate before processing the batch.
void	forceBatchReliable() Force the batch to be reliable.
ActivationMode	getActivationMode() Gets the ActivationMode of this batch
com.cisco.provisioning.cpe.internal.APICall	getAPICall(int index) Gets an APICall object from the batch's list of method calls.
int	getAPICallCount() Gets the count of APICall objects stored in the batch.
String	getBatchID() Gets the batch ID associated with this batch.
int	getBatchPriority() Returns an int value specifying the priority of this batch.
ConfirmationMode	getConfirmationMode() Gets the ConfirmationMode of this batch.
List	getOIDRevNumbersToValidate() Returns the list of OID revision numbers that are to be validated by the RDU before processing the batch.
PublishingMode	getPublishingMode() Gets the PublishingMode of this batch.
String	getUsername() Returns the username used in making PACEConnection connection.
boolean	isBatchReliable() Indicates whether the Batch will be completed even if the RDU goes down while the batch is processing or waiting to be processed.
BatchStatus	post() Sends this batch to the RDU for execution.
BatchStatus	post(long timeout) Sends this batch to the RDU for execution.
void	postNoStatus() Sends this batch to the RDU for execution.
boolean	wasPosted() Indicates whether this batch has been posted yet.

Methods inherited from interface com.cisco.provisioning.cpe.api.IPDevice

add, addDeviceType, addNode, addNodeType, changeClassOfService, changeDefaults, changeDeviceID, changeDHCPCriteria, changeDomainName, changeHostName, changeNodeName, changeNodeProperties, changeNodeTypeProperties, changeOwnerID, changeProperties, delete, deleteDeviceType, deleteNode, deleteNodeType, getAllBehindDevice, getAllDeviceTypes, getAllForIPAddress, getAllForIPAddress, getAllForOwnerID, getAllNodeTypes, getDefaults, getDetails, getNodeProperties, getNodeTypeProperties, performOperation, regenConfigs, relateToIPDevice, relateToNode, searchDevice, searchNode, unregister, unrelateFromIPDevice, unrelateFromNode

Methods inherited from interface com.cisco.provisioning.cpe.api.Configuration

addClassOfService, addCustomPropertyDefinition, addDHCPCriteria, addFile, addLicenseKey, addUser, changeClassOfServiceProperties, changeDHCPCriteriaClientClass, changeDHCPCriteriaExcludeSelectionTags, changeDHCPCriteriaIncludeSelectionTags, changeDHCPCriteriaProperties, changeDPEDefaults, changeExtensionPointSettings, changeFileProperties, changeProvGroupProperties, changePublishingPluginSettings, changeRDUDefaults, changeSystemDefaults, changeUser, deleteClassOfService, deleteCNR, deleteDHCPCriteria, deleteDPE, deleteFile, deleteLicenseKey, deleteProvisioningGroup, deleteUser, disablePublishingPlugin, enablePublishingPlugin, getAllClassesOfService, getAllCNRs, getAllCustomPropertyDefinitions, getAllDHCPCriterias, getAllDPEs, getAllFileTypes, getAllLicenseInfo, getAllProvGroups, getAllRDUs, getAllSystemPropertyDefinitions, getAllUsers, getClassOfServiceProperties, getCNRDetails, getDHCPCriteriaDetails, getDPEDefaults, getDPEDetails, getExtensionPointSettings, getFileBytes, getFileProperties, getLicenseKeyData, getMatchingFilenames, getProvGroupDetails, getPublishingPlugins, getPublishingPluginSettings, getRDUDefaults, getRDUDetails, getSystemDefaults, getUserDetails, removeCustomPropertyDefinition, replaceFile

Method Detail

createdByClient

boolean createdByClient()

Indicates whether the Batch was created by the client API rather than a BPR server.

Returns:

true if the batch was created by the client API.

isBatchReliable

boolean isBatchReliable()

Indicates whether the Batch will be completed even if the RDU goes down while the batch is processing or waiting to be processed. This flag is set automatically if the ActivationMode is ActivationMode.AUTOMATIC or the PublishingMode is PublishingMode.PUBLISHING_NO_CONFIRMATION or PublishingMode.PUBLISHING_CONFIRMATION or if the Batch.forceReliableBatch method was called on this batch.

Note: A reliable batch incurs extra processing overhead on the RDU. It forces at least one extra disk write per batch and therefore takes longer to process.

Returns:

true if the batch will be processed as a reliable batch on the RDU

forceBatchReliable

void forceBatchReliable()

Force the batch to be reliable. This indicated that the Batch will complete even if the RDU goes down while the batch is processing or waiting to be processed. Batches that contain only queries (methods that return data), cannot be forced to be reliable. These batches will return an error when they are submitted to the RDU.

Note: A reliable batch incurs extra processing overhead on the RDU. It forces at least one extra disk write per batch and therefore takes longer to process.

getBatchID

String getBatchID()

Gets the batch ID associated with this batch.

Returns:

the batch ID associated with this batch.

getActivationMode

ActivationMode getActivationMode()

Gets the ActivationMode of this batch

Returns:

the ActivationMode of this batch

getConfirmationMode

ConfirmationMode getConfirmationMode()

Gets the ConfirmationMode of this batch.

Returns:

the ConfirmationMode of this batch

getPublishingMode

PublishingMode getPublishingMode()

Gets the PublishingMode of this batch.

Returns:

the PublishingMode of this batch.

wasPosted

boolean wasPosted()

Indicates whether this batch has been posted yet. If so, it must be discarded and a new batch constructed as batches cannot be reused.

Returns:

true if the batch was ever posted.

ensureConsistency

void ensureConsistency(List oidRevNumbers)

Sends a list of OID revision numbers to validate before processing the batch. This ensures that the objects specified have not been modified since they were last retrieved. The OID revision number for a device can be retrieved in the Map returned from the IPDevice.getDetails(DeviceID, List) method using the key GenericObjectKeys.OID_REVISION_NUMBER.

Parameters:

oidRevNumbers - List of OID rev number String object to validate in the RDU before processing the batch.

getUsername

String getUsername()

Returns the username used in making PACEConnection connection.

Returns:

the username used in making PACEConnection connection.

getOIDRevNumbersToValidate

List getOIDRevNumbersToValidate()

Returns the list of OID revision numbers that are to be validated by the RDU before processing the batch. This will return the values set by the Batch.ensureConsistency method.

Returns:

List of OID revisionNumbers set using ensureConsistency(). If ensureConsistency() was not called, the null is returned.

addAPICall

void addAPICall(com.cisco.provisioning.cpe.internal.APICall call)

Adds an APICall object to the batch's list of method calls.

Note: This method is for BPR-internal use only -- it should not be called by BPR API clients.

Parameters:

call - the APICall object being added to the batch.

getAPICallCount

int getAPICallCount()

Gets the count of APICall objects stored in the batch.

Note: This method is for BPR-internal use only -- it should not be called by BPR API clients.

Returns:

the count of APICall objects stored in the batch.

getAPICall

com.cisco.provisioning.cpe.internal.APICall getAPICall(int index)

Gets an APICall object from the batch's list of method calls.

Note: This method is for BPR-internal use only -- it should not be called by BPR API clients.

Parameters:

index - the index of the APICall object being retrieved from the batch.

Returns:

the indexed APICall.

post

BatchStatus post()
                 throws ProvisioningException

Sends this batch to the RDU for execution. This call will wait synchronously until this batch completes and the results are returned. This method is equivalent to calling PACEConnection.postBatch(Batch).

If this batch is 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.

Returns:

The BatchStatus object containing status and results 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

post

BatchStatus post(long timeout)
                 throws ProvisioningException

Sends this 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. This method is equivalent to calling PACEConnection.postBatch(Batch, long).

If this batch 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.

Parameters:

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 this batch. That type of error is reflected in the BatchStatus object returned.

Events fired:

BatchListener.BATCH_COMPLETE

postNoStatus

void postNoStatus()
                  throws ProvisioningException

Sends this 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.

Throws:

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

Events fired:

BatchListener.BATCH_COMPLETE

getBatchPriority

int getBatchPriority()

Returns an int value specifying the priority of this batch. Client batch priority is based on the ActivationMode specified on the batch. This value is used by the RDU to prioritize and schedule batch execution to optimize system throughput.