Cisco SCMS SM Java API Programmer's Guide

For brevity, <installdir> refers to the installation directory sm-java-api-vvv.bb.

The <installdir>/javadoc folder contains the API JAVADOC documentation.

The <installdir>/lib folder contains the smapi.jar file, which is the API Executable. It also contains additional jar files necessary for the API operation.

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 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 Appendix A of the SCMS Subscriber Manager User Guide.

Additional constructors are available for the Non-blocking API. For more information, see Non-blocking API Construction.

To set up the Blocking API, you need to set an operation timeout value. For more information, see the Blocking API chapter.

To set up the Non-blocking API you are required to set a disconnect listener. For more details, see the Non-blocking API chapter.

The login method adds or modifies a domain, mappings, and possibly properties of a subscriber that already exists in the SM database. It can be called with partial data; for example, with only mappings or only properties provided and NULL put in the unchanged fields.

If another subscriber with the same (or colliding) mappings already exists in the same domain, the colliding mappings will be removed from the other subscriber and assigned to the new subscriber.

If the subscriber does not exist in the SM database, it will be created with the data provided.

subscriberName—See explanation of subscriber name format.

mappings—See explanation of mappings and mapping types. If no mappings are specified, and the isMappingAdditive flag is TRUE, the previous mappings will be retained. If no such mappings exist, the operation will fail.

mappingTypes—See explanation of mappings and mapping types.

propertyKeys—See explanation of property keys and values in the General API Concepts chapter.

propertyValues—See explanation of property keys and values in the General API Concepts chapter.

domain—See explanation of domains in the General API Concepts chapter. If domain is NULL, but the subscriber already has a domain, the existing domain will be retained.

isMappingAdditive:

autoLogoutTime—Applies only to mappings provided as arguments to this method.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

None.

To add the IP address 192.168.12.5 to an existing subscriber named john without affecting existing mappings:

To add the IP address 192.168.12.5 overriding previous mappings:

To extend the auto logout time of 192.168.12.5 that was previously assigned to john:

To modify a dynamic property of john (e.g. package ID):

To add the IP address 192.168.12.5 to an existing subscriber named john without affecting existing mappings and modify a dynamic property of john (e.g. package ID):

Locates the subscriber in the database and removes mappings from it. If the subscriber does not exist, it does nothing.

subscriberName—See explanation of subscriber name format.

mappings—See explanation of mappings and mapping types. If no mappings are specified, all the subscriber mappings will be removed.

mappingTypes—See explanation of mappings and mapping types.

The following is the list of error codes that this method might return:

For a description error codes, see Appendix A - List of Error Codes.

To remove IP address 192.168.12.5 of subscriber john:

To remove all IP addresses of subscriber john:

public boolean logoutByNameFromDomain(String subscriberName,
                                      String[] mappings,
                                      short[] mappingTypes,
                                      String domain)
throws InterruptedException, OperationTimeoutException, RpcErrorException

Similar to logoutByName, but also lets the caller provide the name of the domain to which the subscriber belongs. When the subscriber domain is known, use this method to get improved performance.

subscriberName—See explanation of subscriber name format.

mappings—See explanation of mappings and mapping types. If no mappings are specified, all the subscriber mappings will be removed.

mappingTypes—See explanation of mappings and mapping types.

domain—See explanation of domains in the General API Concepts chapter. The operation will fail if either of the following conditions exists:

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

To remove IP address 192.168.12.5 of subscriber john from domain subscribers:

To remove all IP addresses of subscriber john from domain subscribers:

Locates a subscriber based on domain and mapping, and removes the mapping (the subscriber stays in the database).

mapping—See explanation of mappings and mapping types.

mappingType—See explanation of mappings and mapping types.

domain—See description in logoutByNameFromDomain operation.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

To remove IP address 192.168.12.5 from domain subscribers:

A login method adapted for the cable environment (calls the cable support module in the SM). This method is designed to log in CPEs and CMs to the SM. To log in a CPE, specify its CM MAC in the CM argument and the CPE MAC in the CPE argument. To log in a CM, specify the CM MAC address in both CPE and CM arguments. Note that the login of a CPE whose CM does not exist in the SM database will be ignored: the CM has to exist in the database, either by import or by a CM login operation. For additional information, see the Cable Environment Appendix of the SCMS Subscriber Manager User Guide.

CPE—A unique identifier of the CPE (usually a MAC address)

CM—A unique identifier of the cable modem (usually a MAC address)

IP—The CPE IP address

lease—The CPE lease time

domain—See explanation of domains. The domain will usually be CMTS IP.

propertyKeys—See explanation of property keys and values. If the CPE is provided with partial or no application properties, the values for the missing application properties will be copied from the application properties of the CM to which this CPE belongs. Each CM application property thus serves as a default for the CPE under it.

propertyValues—See explanation of property keys and values.

None.

None

To add the IP address 192.168.12.5 to a CM called CM1 with 2 hours lease time:

To add the IP address 192.168.12.50 to a CPE called CPE1 which is behind CM1 with lease time of 1 hours:

Indicates a logout (CPE becoming offline) event to the SM cable support module.

CPE—See description in the loginCable method.

CM—See description in the loginCable method.

IP—See description in the loginCable method.

domain—See description in the loginCable method.

None.

To remove the IP address 192.168.12.5 from CPE1 which is behind CM1:

Creates a new subscriber record according and adds the record to the SM database.

If a subscriber by this name already exists, it will be removed before the new one is added. In contrast to login, which modifies fields and leaves unspecified fields unchanged, addSubscriber sets the subscriber exactly as specified by the parameters passed to it.

Subscriber AB, already set up in the subscriber database, has a single IP mapping: IP1.

If an addSubscriber operation for AB is called with no mappings specified (NULL in both the mappings and mappingTypes fields), AB will be left with no mappings.

However, calling the login operation with these NULL-value parameters will not change AB's mappings; AB will still have its previous IP mapping of IP1.

subscriberName—See explanation of subscriber name format.

mappings—See explanation of mappings and mapping types.

mappingTypes—See explanation of mappings and mapping types.

propertyKeys—See explanation of property keys and values.

propertyValues—See explanation of property keys and values.

customPropertyKeys—See explanation of custom property keys and values.

customPropertyValues—See explanation of custom property keys and values.

domain—See explanation of domains. A NULL value indicates that the subscriber is domain-less.

None.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

To add a new subscriber, john, with some custom properties:

Removes a subscriber completely from the SM database.

subscriberName—See explanation of subscriber name format.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

To remove subscriber john entirely from the database:

public void removeAllSubscribers()
throws InterruptedException, OperationTimeoutException, RpcErrorException

Removes all subscribers from the SM, leaving the database with no subscribers.

None.

None.

Retrieves the total number of subscribers in the SM database.

The number of subscribers in the SM.

None

Retrieves the number of subscribers in a subscriber domain.

domain—A name of a subscriber domain that exists in the SM's domain repository.

The number of subscribers in the domain provided.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Retrieves a subscriber record. Each field is formatted as an integer, string, or string array, as described below in the Return Value section for this method. If the subscriber does not exist in the SM database, an exception will be returned.

subscriberName—See explanation of subscriber name format.

An Object Array with nine elements. The following table lists the index values. No array element is NULL.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

To retrieve the subscriber record of john:

Verifies that a subscriber exists in the SM database.

subscriberName—See explanation of subscriber name format.

None.

Checks whether a subscriber that already exists in the SM database is logged in; i.e., if the subscriber also exists in an SCE database.

When the SM is configured to work in Pull mode, a TRUE value returned by this method does not guarantee that the subscriber actually exists in an SCE database, but rather the subscriber is available to be pulled by an SCE if needed.

If the subscriber does not exist in the SM database, an exception will be thrown.

subscriberName—See explanation of subscriber name format.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Finds a subscriber name according to a mapping and a domain.

mapping—See explanation of mappings and mapping types.

mappingType—See explanation of mappings and mapping types.

domain—The name of the domain to which the subscriber belongs. The operation will fail if either of the following conditions exists:

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Gets a bulk of subscriber names from the SM database, starting with lastBulkEnd followed by the next numOfSubscribers subscribers (in alphabetical order).

If lastBulkEnd is NULL, the (alphabetically) first subscriber name that exists in the SM database will be used.

lastBulkEnd—Last subscriber name from last bulk. Use NULL to start with the first (alphabetic) subscriber.

numOfSubscribers—Limit on number of subscribers that will be returned. If this value is higher than the SM limit (1000), the SM limit will be used.

An array of subscriber names ordered alphabetically.

The method will return as many subscribers as are found in the SM database, starting at the requested subscriber. The array size is limited by the minimum between numOfSubscribers and the SM limit (1000).

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Gets subscribers in the SM database that are associated with the specified domain.

The semantics of this operation are the same as the semantics of the getSusbcriberNames operation.

lastBulkEnd—See description in getSusbcriberNames operation.

numOfSubscribers—See description in getSusbcriberNames operation.

domain—The name of a subscriber domain that exists in the SM domain repository.

An alphabetically ordered array of subscriber names that belong to the domain provided.

See also the documentation of the Return Value section of the getSusbcriberNames operation.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Gets subscribers in the SM database whose name begins with a specified prefix.

The semantics of this operation are the same as the semantics of the getSusbcriberNames operation.

lastBulkEnd—See description in getSusbcriberNames operation.

numOfSubscribers—See description in getSusbcriberNames operation.

prefix—A case-sensitive string that marks the prefix of the required subscriber names.

An alphabetically ordered array of subscriber names that start with the prefix required.

See also the documentation of the Return Value section of the getSusbcriberNames operation.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Gets subscribers in the SM database whose names end with the specified suffix.

The semantics of this operation are the same as the semantics of the getSusbcriberNames operation.

lastBulkEnd—See description in getSusbcriberNames operation

numOfSubscribers—See description in getSusbcriberNames operation.

suffix—A case-sensitive string that marks the suffix of the required subscriber names.

An alphabetically ordered array of subscriber names that end with the suffix required.

See also the documentation of the Return Value section of the getSusbcriberNames operation.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Provides the list of current subscriber domains in the SM domain repository.

A complete list of subscriber domain names in the SM.

None.

Resets the specified application properties of a subscriber. If an application is installed, the relevant application properties will be set to the default value of the properties according to the currently loaded application information. If an application is not installed, a java.lang.IllegalStateException will be returned.

subscriberName—See explanation of subscriber name format.

properties—See explanation of property keys and values.

None.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

Resets the specified custom properties of a subscriber.

subscriberName—See explanation of subscriber name format.

CustomProperties—See explanation of custom property keys and values.

None.

The following is the list of error codes that this method might return:

For a description of error codes, see Appendix A - List of Error Codes.

The operation functionality is the same as the matching Blocking API operation.

The operation functionality is the same as the matching Blocking API operation.

The operation functionality is the same as the matching Blocking API operation.

The operation functionality is the same as the matching Blocking API operation.

The operation functionality is the same as the matching Blocking API operation.

The operation functionality is the same as the matching Blocking API operation.