com.pcube.management.api
Class SMNonBlockingApi

java.lang.Object
  com.pcube.management.api.SMNonBlockingApi

public class SMNonBlockingApi
extends java.lang.Object

Subscriber Manager non-blocking API.

The purpose of this API is to be used by automatic systems to provide subscriber data to Cisco Service Control's subscriber manager.

Usage examples: TBD

For Support TBD

Field Summary

static long

DEFAULT_TIMEOUT

Constructor Summary

SMNonBlockingApi()
Default constructor.

SMNonBlockingApi(boolean _reliable, long autoReconnectInterval)
Constructor.

SMNonBlockingApi(long autoReconnectInterval)
Constructor.

SMNonBlockingApi(java.lang.String legName)
Constructor.

SMNonBlockingApi(java.lang.String legName, boolean _reliable, long autoReconnectInterval)
Constructor.

SMNonBlockingApi(java.lang.String legName, long autoReconnectInterval)
Constructor.

Method Summary

void	connect(java.lang.String _hostname) connect to the subscriber manager using the default port.
void	connect(java.lang.String _hostname, int _port) connect to the subscriber manager to a user specified port.
void	disconnect() disconnects from the susbcriber manager.
void	finalize()
java.lang.String	getClientVersion() provides the rpc-client version with which this Java SM API was compiled.
java.lang.String	getSMVersion() gets the (peer) SM version
void	init(java.util.Properties properties) Initiates some configuration parameters of the client.
boolean	isConnected() tests whether the client is connected
long	login(java.lang.String subscriberName, java.lang.String[] mappings, short[] mappingTypes, java.lang.String[] propertyKeys, java.lang.String[] propertyValues, java.lang.String domain, boolean isMappingAdditive, int autoLogoutTime) The login method adds or modifies a domain, mappings and possibly properties of a subscriber that already exists in the SM database.
long	loginCable(java.lang.String CPE, java.lang.String CM, java.lang.String IP, int lease, java.lang.String domain, java.lang.String[] propertyKeys, java.lang.String[] propertyValues) A log-in method adapted for the cable environment (calls the cable support module in the SM).
long	logoutByMapping(java.lang.String mapping, short mappingType, java.lang.String domain) Locates a subscriber based on domain and mapping, and removes the mapping (the subscriber stays in the database).
long	logoutByName(java.lang.String subscriberName, java.lang.String[] mappings, short[] mappingTypes) Locates the subscriber in the database and removes mappings from it
long	logoutByNameFromDomain(java.lang.String subscriberName, java.lang.String[] mappings, short[] mappingTypes, java.lang.String domain) Similar to logoutByName, but also lets the caller provide the name of the domain to which the subscriber belongs.
long	logoutCable(java.lang.String CPE, java.lang.String CM, java.lang.String IP, java.lang.String domain) Indicates a logout (CPE becoming offline) event to the SM cable support module.
void	setDisconnectListener(DisconnectListener _disconnectListener) Sets a disconnect listener.
void	setResultHandler(ResultHandler resultHandler) Sets a result handler that will receive the results of the api calls in this API
void	stopReconnectingThread() requests the reconnect thread to stop.
java.lang.String	toString() Automatically generated method: toString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_TIMEOUT

public static final long DEFAULT_TIMEOUT

See Also:

Constant Field Values

Constructor Detail

SMNonBlockingApi

public SMNonBlockingApi()

Default constructor. The name generated by this constructor (to be used in the SM configuration file p3sm.cfg for failure detection) is NB.SM-API.J

SMNonBlockingApi

public SMNonBlockingApi(long autoReconnectInterval)

Constructor. Lets the caller set the auto-reconnect interval.

Parameters:

autoReconnectInterval - Defines the interval for connection attempts of the reconnect task Note: value <= 0 : no auto-reconnect task value > 0 : auto-reconnect task tries to reconnect every interval

SMNonBlockingApi

public SMNonBlockingApi(boolean _reliable,
                        long autoReconnectInterval)

Constructor. Lets the caller set the auto-reconnect interval.

Parameters:

_reliable - Defines whether the API should work in reliable mode

autoReconnectInterval - Defines the interval for connection attempts of the reconnect task Note: value <= 0 : no auto-reconnect task value > 0 : auto-reconnect task tries to reconnect every interval

SMNonBlockingApi

public SMNonBlockingApi(java.lang.String legName,
                        boolean _reliable,
                        long autoReconnectInterval)

Constructor. Lets the caller set the legName.

Note:: The LEG name will be appended with the following suffix: .B.SM-API.J

For example,

If the legName is 'my-leg.10.1.12.45-version-1.0' then the actual legName sent at the greeting to the RPC server is 'my-leg.10.1.12.45-version-1.0.B.SM-API.J'

Parameters:

legName - the name describing this LEG for failover. to enable several API instances to work from several hosts, it is recommended to include the hostname as part of the LEG name.

_reliable - Defines whether the API should work in reliable mode

autoReconnectInterval - Defines the interval for connection attempts of the reconnect task Note: value <= 0 : no auto-reconnect task value > 0 : auto-reconnect task tries to reconnect every interval

SMNonBlockingApi

public SMNonBlockingApi(java.lang.String legName)

Constructor. Lets the caller set the legName.

Note:: The LEG name will be appended with the following suffix: .B.SM-API.J

For example,

If the legName is 'my-leg.10.1.12.45-version-1.0' then the actual legName sent at the greeting to the RPC server is 'my-leg.10.1.12.45-version-1.0.B.SM-API.J'

Parameters:

legName - the name describing this LEG for failover. to enable several API instances to work from several hosts, it is recommended to include the hostname as part of the LEG name.

SMNonBlockingApi

public SMNonBlockingApi(java.lang.String legName,
                        long autoReconnectInterval)

Constructor. Lets the caller set the legName and define auto-reconnect interval.

Note:: The LEG name will be appended with the following suffix: .B.SM-API.J

For example,

If the legName is 'my-leg.10.1.12.45-version-1.0' then the actual legName sent at the greeting to the RPC server is 'my-leg.10.1.12.45-version-1.0.B.SM-API.J'

Parameters:

legName - the name describing this LEG for failover. to enable several API instances to work from several hosts, it is recommended to include the hostname as part of the LEG name.

autoReconnectInterval - Interval for reconnection attempts of the auto-reconnect task

Method Detail

toString

public java.lang.String toString()

Automatically generated method: toString

Overrides:

toString in class java.lang.Object

init

public void init(java.util.Properties properties)

Initiates some configuration parameters of the client. Using this method is optional. use it only if you have a good reason to change the configuration parameters from their defualt.

This method should called immediatly after the client was instantiated and before it is connected Otherwise the parameters may not take effect.

Parameters:

properties - To find out which properties are configurable using this API please address Cisco's support.

connect

public void connect(java.lang.String _hostname)
             throws java.lang.Exception

connect to the subscriber manager using the default port. The connect method can be called also after disconnect has been called (there is no need to create a new API after disconnceting)

Parameters:

_hostname - a host running the SM software

Throws:

java.lang.Exception

connect

public void connect(java.lang.String _hostname,
                    int _port)
             throws java.lang.Exception

connect to the subscriber manager to a user specified port. usefull when SM doesn't listen on the default port. The connect method can be called also after disconnect has been called (there is no need to create a new API after disconnecting)

Parameters:

_hostname - a host running the SM software

_port - the port number on which the SM's rpc server listens

Throws:

java.lang.Exception

disconnect

public void disconnect()

disconnects from the susbcriber manager. The connect method can be called also after disconnect has been called (there is no need to create a new API after disconnceting).

isConnected

public boolean isConnected()

tests whether the client is connected

Returns:

true/false if connected/not connected

getClientVersion

public java.lang.String getClientVersion()

provides the rpc-client version with which this Java SM API was compiled. This method doesn't require a connection to work.

Returns:

A version string.

getSMVersion

public java.lang.String getSMVersion()

gets the (peer) SM version

Returns:

the version of the SM as received in the connection negotiation

setDisconnectListener

public void setDisconnectListener(DisconnectListener _disconnectListener)

Sets a disconnect listener.

The API supports only a single disconnect listener. The listener is notified when the API looses connection with the SM.

Important Note:The disconnect listener should not perform long operations from the calling thread. Performing long operations due to a disconnection event should be done in a separate thread. Not following this (strong) recommendation might result in resource leakage on the client side.

Parameters:

_disconnectListener -

setResultHandler

public void setResultHandler(ResultHandler resultHandler)

Sets a result handler that will receive the results of the api calls in this API

.

Each method in this API returns a 'long' value which can be used to map between operation calls to results served to the result handler interface.

Note: This method should be called only immediatly after the client is connected and before any operation was invoked

Important Note:The result handler should not perform long operations from the calling thread. Performing long operations that process invocation results should be done in a spearate thread. If long operations are performed from the calling thread, it will result in overall API performance slow down.

Parameters:

resultHandler -

login

public long login(java.lang.String subscriberName,
                  java.lang.String[] mappings,
                  short[] mappingTypes,
                  java.lang.String[] propertyKeys,
                  java.lang.String[] propertyValues,
                  java.lang.String domain,
                  boolean isMappingAdditive,
                  int autoLogoutTime)
           throws java.lang.InterruptedException

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 the subscriber does not exist in the SM database, it will be created with the data provided. If another subscriber with the same (or colliding) mappings already exists in the same domain, the colliding mappings will be removed from the other subscribers and assigned to the new subscribers.

Parameters:

subscriberName - See the susbcriber name section in the overview

mappings - See the mappings section in the overview. 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 the mappings section in the overview.

propertyKeys - See the properties section in the overview.

propertyValues - See the properties section in the overview.

domain - See the domains section in the overview. If domain is NULL, but the subscriber already has a domain, the existing domain will be retained.

isMappingAdditive - TRUE: adds the mappings provided by this call to the subscriber record. FALSE: overrides the mappings provided by this call with mappings that already exist in the subscriber record.

autoLogoutTime - Applies only to mappings provided as arguments to this method. Positive value (N): automatically logs out the mappings (similar to a logout method being called) after N seconds. 0 value: maintains current expiration time for the given mappings if already exist in SM. Negative value: disables any expiration time that might have been set for these mappings.

Returns:

A handback to be used by the result handler for the result of the execution of this method. The return value that should be expected is void.

Throws:

java.lang.InterruptedException

See Also:

SMApiConstants

logoutByName

public long logoutByName(java.lang.String subscriberName,
                         java.lang.String[] mappings,
                         short[] mappingTypes)
                  throws java.lang.InterruptedException

Locates the subscriber in the database and removes mappings from it

Parameters:

subscriberName - See the susbcriber name section in the overview.

mappings - See the mappings section in the overview. If no mappings are specified, all the subscriber mappings will be removed.

mappingTypes - See the mappings section in the overview.

Returns:

A handback to be used by the result handler for the result of the execution of this method:
TRUE: if the subscriber was found and the subscriber's mappings were removed from the subscriber database. FALSE: if the subscriber was not found in the subscriber database.

Throws:

java.lang.InterruptedException

See Also:

SMApiConstants

logoutByNameFromDomain

public long logoutByNameFromDomain(java.lang.String subscriberName,
                                   java.lang.String[] mappings,
                                   short[] mappingTypes,
                                   java.lang.String domain)
                            throws java.lang.InterruptedException

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.

Parameters:

subscriberName - See the susbcriber name section in the overview

mappings - See the mappings section in the overview. If no mappings are specified, all the subscriber mappings will be removed.

mappingTypes - See the mappings section in the overview.

domain - See the domains section in the overview. The operation will fail if: The domain is null, but the subscriber exists in the database and belongs to a domain. OR The domain specified is incorrect.

Returns:

A handback to be used by the result handler for the result of the execution of this method:
TRUE: if the subscriber was found and removed from the subscriber database FALSE: if the subscriber was not found in the subscriber database.

Throws:

java.lang.InterruptedException

See Also:

SMApiConstants

logoutByMapping

public long logoutByMapping(java.lang.String mapping,
                            short mappingType,
                            java.lang.String domain)
                     throws java.lang.InterruptedException

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

Parameters:

mapping - See the mappings section in the overview.

mappingType - See the mappings section in the overview.

domain - See the domains section in the overview.

Returns:

A handback to be used by the result handler for the result of the execution of this method:
TRUE: if the subscriber was found and removed from the subscriber database. FALSE: if the subscriber was not found in the subscriber database.

Throws:

java.lang.InterruptedException

See Also:

SMApiConstants

loginCable

public long loginCable(java.lang.String CPE,
                       java.lang.String CM,
                       java.lang.String IP,
                       int lease,
                       java.lang.String domain,
                       java.lang.String[] propertyKeys,
                       java.lang.String[] propertyValues)
                throws java.lang.InterruptedException

A log-in method adapted for the cable environment (calls the cable support module in the SM). This method is designed to add log-in CPEs to the SM. To log in a CM, specify the CM MAC address in both CPE and CM arguments. For additional information, see the appendix Cable Environmant of the smartSUB Manager User Guide.

Note: The name of the CPE in the SM database is the concatenation of the CPE and CM values with two underscore ['_'] characters between them. The caller must make sure that the lengths of CPE and CM add up to no more than 38 characters.

Parameters:

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

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

IP - the CPE IP address. See the mappings section in the overview for formatting specification.

lease - the CPE lease time in seconds

domain - See the domains section in the overview. the CPE domain is usually a CMTS name. Note: Domain aliases must be set on the SM in order for the CMTS IP to be correctly interpreted as a domain name.

propertyKeys - See the properties section in the overview. 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 the properties section in the overview.

Returns:

A handback to be used by the result handler for the result of the execution of this method:
The return value that should be expected is void.

Throws:

java.lang.InterruptedException

See Also:

SMApiConstants

logoutCable

public long logoutCable(java.lang.String CPE,
                        java.lang.String CM,
                        java.lang.String IP,
                        java.lang.String domain)
                 throws java.lang.InterruptedException

Indicates a logout (CPE becoming offline) event to the SM cable support module. The cable support module will clear the CPE from the SCE device.

Parameters:

CPE - See the loginCable method

CM - See the loginCable method

IP - See the loginCable method

domain - See the loginCable method

Returns:

A handback to be used by the result handler for the result of the execution of this method:
TRUE: if the CPE was found and removed from the subscriber database. FALSE: if the CPE was not found in the subscriber database.

Throws:

java.lang.InterruptedException

See Also:

SMApiConstants

finalize

public void finalize()
              throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

stopReconnectingThread

public void stopReconnectingThread()

requests the reconnect thread to stop.