|
|
Table Of Contents
Information About the Blocking API/Non-blocking API
Information About API Initialization
Connecting to the Subscriber Manager
Information About Network ID Mappings
Information About the DisconnectListener Interface
DisconnectListener Interface Example
General API Concepts
This module describes the various concepts that are used while working with the SM Java API.
•
Information About the Blocking API/Non-blocking API
•
•
•
Information About the Blocking API/Non-blocking API
This section describes the differences between the Blocking API and the Non-blocking API operations.
Blocking API
In a Blocking API operation, which is the most common, every method returns after its operation has been performed.
The SM Blocking Java API provides a wide range of operations. It contains most of the functionality of the Non-blocking API and many functions that the Non-blocking API does not provide. The Blocking API does not support reliability and auto-reconnect functionality.
Non-blocking API
In a Non-blocking Java API operation, every method returns immediately , even before the completion of its operation. The operation results are either returned to an Observer object (Listener) or not returned at all.
The Non-blocking API method is advantageous when the operation is lengthy and involves I/O. Performing the operation in a separate thread allows the calling program to continue doing other tasks and it improves overall system performance.
The SM Non-blocking Java API contains a small number of non-blocking operations. The API supports retrieval of operation results using a result listener.
The SM Non-blocking Java API supports two modes: reliable and non-reliable. For more information about the reliability modes, see Information About Reliability Support, page 4-1.
Information About API Initialization
There are three main steps to initialize the API:
•
•
•
The following sectinos describe these three steps.
Initizlization examples can be found within the code examples sections under each API.
•
API Construction
Blocking and Non-blocking APIs have two common constructors:
•
•
Constructor that Accepts a LEG Name
Set the LEG name if you intend to turn on the SM-LEG failure handling options in the SM. You should read about the LEG software components and SM-LEG failure handling in the Cisco SCMS Subscriber Manager User Guide .
The SM will use the LEG name when recovering from a connection failure. A constant string that identifies the API will be appended to the LEG name as follows:
•
•
Example (Blocking API)
If the provided LEG name is my-leg.10.1.12.45-version-1.0 , the actual LEG name will be my-leg.10.1.12.45-version-1.0.B.SM-API.J.
If no name is set, the LEG uses the hostname of the machine as the prefix of the name.
For additional information about LEG-SM failure handling, see the "Configuration File Options" module of the Cisco SCMS Subscriber Manager User Guide .
Additional constructors are available for the Non-blocking API. For more information, see Non-blocking API Construction, page 4-3.
Setup Operations
The setup operations differ for the two APIs. Both APIs support setting a disconnect listener, described in detail in the "Information About the DisconnectListener Interface" section.
Blocking API Setup
To set up the Blocking API, you need to set an operation timeout value. For more information, see "Blocking API".
Non-blocking API Setup
To set up the Non-blocking API you are required to set a disconnect listener. For more details, see Non-blocking API, page 4-1.
Connecting to the Subscriber Manager
To connect to the SM, use one of the following connect methods.
•
connect(String host)•
connect(String host, int port)For both methods, the host parameter can be either an IP address or a reachable hostname.
At any time during the API operation, you can check if the API is connected by using the isConnected method.
API Finalization
To free the resources of both server and client, use the disconnect method.
It is recommended that you use a finally statement in your main class; for example:
public static void main(String [] args) throws Exception {SMNonBlockingApi smnbapi = new SMNonBlockingApi();try {...}finally {smnbapi.disconnect();}}Subscriber Name Format
Most methods of both APIs require the subscriber name as an input parameter. This section lists the formatting rules of a subscriber name.
It can contain up to 64 characters. All printable characters with an ASCII code between 32 and 126 (inclusive) can be used; except for 34 ("), 39 ('), and 96 (`).
Information About Network ID Mappings
A network ID mapping is a network identifier that the SCE device can relate to a specific subscriber record. A typical example of a network ID mapping (or simply mapping) is an IP address. Currently, the Cisco Service Control solution supports IP address, IP range, and VLAN mappings.
Both Blocking and Non-blocking APIs contain operations that accept mappings as a parameter. Examples are:
•
•
When passing mappings to an API method, the caller is requested to provide two parameters:
•
•
When passing arrays, the mappingTypes array must contain either the same number of elements as the mappings array, or a single element. If the mappingTypes array contains a single element, all mappings have the same type, specified by this single element.
The API supports the following subscriber mapping types:
•
•
For additional information, see the Cisco SCMS Subscriber Manager User Guide .
•
Specifying IP Address Mapping
The string format of an IP address is the commonly used decimal notation:
IP-Address=[0-255].[0-255].[0-255].[0-255]Examples:
•
216.109.118.66•
–
–
Specifying IP Range Mapping
The string format of an IP range is an IP address in decimal notation and a decimal specifying the number of 1s in a bit mask:
IP-Range=[0-255].[0-255].[0-255].[0-255]/[0-32]Examples:
•
•
Note
Specifying VLAN Tag Mapping
The string format for VLAN tag mapping is VLAN-tag = 0-4095.
The value is a decimal in the specified range.
The com.pcube.management.api.SMApiConstants interface also provides the mapping type:
•
•
Subscriber Domains
The Cisco SCMS Subscriber Manager User Guide explains in detail the domain concept. Briefly, a domain is an identifier that tells the SM which SCE devices to update with the subscriber record.
A domain name is of type String. During system installation, the network administration determines the system domain names, which therefore vary between installations. The APIs include methods that specify to which domain a subscriber belongs and allow queries about the system's domain names. If an API operation specifies a domain name that does not exist in the SM domain repository, it is considered an error and an RpcErrorException will be returned.
The SM's Automatic Domain Roaming feature allows subscribers to be moved between domains by calling the method for a subscriber with an updated domain parameter.
Note
Subscriber Properties
Several operations manipulate subscriber properties. A subscriber property is a key-value pair that affects the way the SCE analyzes and reacts to network traffic generated by the subscriber.
More information about properties can be found in the Cisco SCMS Subscriber Manager User Guide and in the Cisco Service Control Application for Broadband User Guide . The application user guide provides application-specific information; it lists the subscriber properties that exist in the application running on your system, the allowed value set, and the significance of each property value.
To format subscriber properties for Java API operations, use the String arrays propertyKeys and propertyValues.
Note
Example:
If the property keys array is {"packageId","monitor"} and the property values array is {"5","1"} , the properties will be packageId=5 , monitor=1.
Custom Properties
Some operations manipulate custom properties. Custom properties are similar to subscriber properties, but do not affect how the SCE analyzes and manipulates the subscriber's traffic. The application management modules use custom properties to store additional information for each subscriber.
To format custom properties, use the String arrays customPropertyKeys and customPropertyValues , the same as in formatting Subscriber Properties.
Information About the DisconnectListener Interface
Both APIs (Blocking and Non-blocking) allow setting a disconnect listener. The disconnect listener is an interface with a single method:
public interface DisconnectListener {/*** called when the connection with the server is down.*/public void connectionIsDown();}Implement this interface to be notified when the API is disconnected from the SM.
To set a disconnect listener, use the setDisconnectListener method.
DisconnectListener Interface Example
The following example is a simple implementation of a disconnect listener that prints a message to stdout and exits.
import com.pcube.management.framework.rpc.DisconnectListener;public class MyDisconnectListener implements DisconnectListener {public void connectionIsDown(){System.out.println("Message: connection is down.");System.exit(0);}}Exceptions
The same Java class, com.pcube.management.framework.rpc.RpcErrorException , provides all of the functional errors of the SM Java API. This is contrary to the normal Java usage. This approach was chosen because of the "cross-language" nature of the SM API. It allows all SM API implementations (Java, C, and C++) to look and feel the same.
Each exception provides the following information:
•
•
•
The error code can be interpreted using com.pcube.management.api.SMApiConstants. See the List of Error Codes, page A-1 for more details about error codes and their significance.
Note
Practical Tips
When implementing the code that integrates the API with your application, you should consider the following practical tips:
•
•
•
•
•
•
•
•
•
Posted: Thu May 31 06:32:13 PDT 2007
All contents are Copyright © 1992--2007 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.
