Cisco Broadband Access Center Integration Developer s Guide, Release 3.5
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
- Updated:
- October 30, 2013
Chapter: Getting Started with the BAC API
Getting Started with the BAC API
This chapter describes the startup process involving system configuration and API execution.
The sections in this chapter are:
•
Startup Process for API Client.
Startup Process for API Client
The startup process for an API client interaction involves:
Configuring the System
Before executing a simple client, ensure that you have completed the tasks listed in this section.
Note These tasks are part of an initial configuration workflow that you must complete before executing a simple client for the first time. Thereafter, you can execute any number of simple clients.
Executing the API Client
To execute a simple API client:
Note This procedure uses the AddDeviceExample.java classfile as an example.
Step 1 Compile the API classfile using the following code:
javac -classpath .:bpr.jar:bacbase.jar class_file
For example:
javac -classpath .:bpr.jar:bacbase.jar AddDeviceExample.java
Note This example assumes that the bpr.jar and bacbase.jar files exist in the local directory.
Step 2 Execute the API classfile using the following code:
java -cp .:bpr.jar:bacbase.jar class_file
For example:
java -cp .:bpr.jar:bacbase.jar AddDeviceExample.java
Step 3 Verify the results.
For example, the AddDeviceExample will print success or failure messages. If there is no error, the following message appears:
Successfully provisioned device with identifier [OUI-serial-12345]
You can also verify the results for the device record from the administrator user interface from the Devices > Manage Device page. For more information, see Cisco Broadband Access Center Administrator's Guide 3.5, 3.5.1, 3.5.2.
Creating an API Client
This section describes how you can connect to the RDU, create a batch, post the batch to the RDU, and verify the result.
Note This procedure uses the AddDeviceExample.java classfile as an example.
Step 1 Create a connection to the Provisioning API Command Engine (PACE).
// The PACE connection to use throughout the example. When
// executing multiple batches in a single process, it is advisable
// to use a single PACE connection that is retrieved at the start
// of the application. When done with the connection, YOU MUST
// explicitly close the connection with the releaseConnection()
// method call.
PACEConnection connection = null;
// -----------------------------------------------------------------
//
// 1) Connect to the Regional Distribution Unit (RDU).
//
// The parameters defined at the beginning of this class are
// used here to establish the connection. Connections are
// maintained until releaseConnection() is called. If
// multiple calls to getInstance() are called with the same
// arguments, you must still call releaseConnection() on each
// connection you received.
//
// The call can fail for one of the following reasons:
// - The hostname / port is incorrect.
// - The authentication credentials are invalid.
//
// -----------------------------------------------------------------
try
{
connection = PACEConnectionFactory.getInstance(
// RDU host
rduHost,
// RDU port
rduPort,
// User name
userName,
// Password
password);
}
catch (PACEConnectionException pce)
{
// failed to get a connection
System.out.println("Failed to establish a PACEConnection to ["
+ userName + "@" + rduHost + ":" + rduPort + "]; " +
pce.getMessage());
throw new RuntimeException(pce.getMessage());
}
catch (RDUAuthenticationException bae)
{
// failed to get a connection
System.out.println("Failed to establish a PACEConnection to ["
+ userName + "@" + rduHost + ":" + rduPort + "]; " +
bae.getMessage());
throw new RuntimeException(bae.getMessage());
}
// -----------------------------------------------------------------
Step 2 Get a new batch instance.
// -----------------------------------------------------------------
//
// 2) Get a new batch instance.
//
// To perform any operations in the Provisioning API, you must
// first start a batch. As you make commands against the batch,
// nothing will actually start until you post the batch.
// Multiple batches can be started concurrently against a
// single connection to the RDU.
//
// -----------------------------------------------------------------
Batch myBatch = connection.newBatch(
// No reset
ActivationMode.NO_ACTIVATION,
// No need to confirm activation
ConfirmationMode.NO_CONFIRMATION,
// No publisining to external database
PublishingMode.NO_PUBLISHING);
// -----------------------------------------------------------------
Step 3 Register the AddDeviceExample( ) call with the batch.
// -----------------------------------------------------------------
//
// 3) Register the add(...) call with the batch.
//
// Add to the batch the add(...) call. This will make
// the batch add the device during the post() operation. If
// multiple methods are added to a batch, they will be executed
// in the order they are registered. For example, you could
// add a device and then modify it successfully in a batch.
//
// The host name and domain name only needs to be specified if the
// device should have an explicit name assigned to it -- and this is
// only really useful if you have dynamic DNS enabled in DHCP/CNR.
// Properties can be used to store additional information that
// should be maintained by BAC. This data will be returned as a
// response to a query for device details.
//
// -----------------------------------------------------------------
// A CWMP device requires the following properties to
// be populated.
//
Map<String, Object> propMap = new HashMap<String, Object>();
propMap.put(IPDeviceKeys.HOME_PROV_GROUP, provisioningGroup);
myBatch.add(
// Device type
DeviceType.CWMP,
// Device identifier
new CWMPDeviceID(deviceId),
// Host name - Not used in this example
null,
// Domain Name - Not used in this example
null,
// ownerID
ownerId,
// classOfService - Use default COS
null,
// properties
propMap);
// -----------------------------------------------------------------
Step 4 Post a batch to the RDU.
//
// 4) Post the batch to the server.
//
// Executes the batch against the RDU. All of the
// methods are executed in the order entered and the data
// changes are applied against the embedded database in RDU.
//
// -----------------------------------------------------------------
BatchStatus batchStatus = null;
try
{
batchStatus = myBatch.post();
}
catch (ProvisioningException pe)
{
System.out.println("Failed to provision device with identifer ["
+ deviceId + "]; " + pe.getMessage());
throw new RuntimeException(pe.getMessage());
}
// -----------------------------------------------------------------
Step 5 Verify the result of the connection.
//
// 5) Check to see if the batch was successfully posted.
//
// Verify if any errors occurred during the execution of the
// batch. Exceptions occur during post() for truly exception
// situations such as failure of connectivity to RDU.
// Batch errors occur for inconsistencies such as no lease
// information for a device requiring activiation. Command
// errors occur when a particular method has problems, such as
// trying to add a device that already exists.
//
// -----------------------------------------------------------------
if (batchStatus.isError())
{
// Batch error occurred.
// we need to determine if it was a batch error or a
// command error that caused this failure
if (batchStatus.getFailedCommandIndex() == -1)
{
// this is a batch only error
// get the error code and get the error message
final StringBuilder msg = new StringBuilder(128);
msg.append("Batch with ID [");
msg.append(batchStatus.getBatchID());
msg.append("] failed with error code [");
msg.append(batchStatus.getStatusCode());
msg.append("]. [");
msg.append(batchStatus.getErrorMessage());
msg.append("].");
// throw an exception or log the message
System.out.println("Failed to add device with identifier ["
+ deviceId + "]; " + msg.toString());
}
else
{
// this is a batch error caused by a command
final CommandStatus commandStatus =
batchStatus.getFailedCommandStatus();
// get the error code and get the error message
final StringBuilder msg = new StringBuilder(128);
msg.append("Batch with ID [");
msg.append(batchStatus.getBatchID());
msg.append("] failed with command error code [");
msg.append(commandStatus.getStatusCode());
msg.append("]. [");
msg.append(commandStatus.getErrorMessage());
msg.append("].");
// throw an exception or log the message
System.out.println("Failed to add device with identifier ["
+ deviceId + "]; " + msg.toString());
}
}
else
{
// Successfully added device
System.out.println("Successfully added device with identifier ["
+ deviceId + "]");
}
Step 6 Release the connection to the RDU.
// -----------------------------------------------------------------
//
// 6) Release the connection to the RDU.
//
// Once the last batch has been executed, the connection can
// be closed to the RDU. It is important to explictly
// close connections since it helps ensure clean shutdown of
// the Java virtual machine.
//
// -----------------------------------------------------------------
connection.releaseConnection();
Feedback