com.pcube.management.api
Class SMBlockingApi

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

public class SMBlockingApi
extends java.lang.Object

Subscriber Manager blocking API.

The purpose of this API is to be used by user interface systems to view & edit subscriber data on Cisco Service Control's subscriber manager.

Usage examples: TBD

For Support TBD

Constructor Summary

SMBlockingApi()
Default constructor.

SMBlockingApi(java.lang.String legName)
Constructor.

Method Summary

void	addSubscriber(java.lang.String subscriberName, java.lang.String[] mappings, short[] mappingTypes, java.lang.String[] propertyKeys, java.lang.String[] propertyValues, java.lang.String[] customPropertyKeys, java.lang.String[] customPropertyValues, java.lang.String domain) Creates a new subscriber record according to the given data and adds it to the SM database.
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.
java.lang.String	getClientVersion() provides the rpc-client version with which this Java SM API was compiled.
java.lang.String[]	getDomains() Provides the list of current subscriber domains in the SM domain repository.
int	getNumberOfSubscribers() Retrieves the total number of subscribers in the SM database
int	getNumberOfSubscribersInDomain(java.lang.String domain) Retrieves the number of subscribers in a subscriber domain
java.lang.String	getSMVersion() gets the (peer) SM version
java.lang.Object[]	getSubscriber(java.lang.String subscriberName) Retrieves subscriber record.
java.lang.String	getSubscriberNameByMapping(java.lang.String mapping, short mappingType, java.lang.String domain) Finds a subscriber name according to a mapping and a domain.
java.lang.String[]	getSubscriberNames(java.lang.String lastBulkEnd, int numOfSubscribers) Gets names of subscribers in the SM database, starting with lastBulkEnd followed by the next numOfSubscribers subscribers (in alphabetical order).
java.lang.String[]	getSubscriberNames(java.lang.String lastBulk, java.lang.String propName, java.lang.String propValue, int numOfSubs) Gets names of logged in subscribers in the SM database, starting with lastBulkEnd and having the propertyName, propertyValue pair followed by the next numOfSubscribers subscribers (in alphabetical order).
java.lang.String[]	getSubscriberNamesByPackageID(java.lang.String lastBulk, java.lang.String propName, java.lang.String propValue, int numOfSubs) the getSubscriberNamesByPackageID retrives the subscribers based on the packageId.
java.lang.String[]	getSubscriberNamesInDomain(java.lang.String lastBulkEnd, int numOfSubscribers, java.lang.String domain) Gets subscribers in the SM database that are associated with the specified domain.
java.lang.String[]	getSubscriberNamesWithPrefix(java.lang.String lastBulkEnd, int numOfSubscribers, java.lang.String prefix) Gets subscribers in the SM database whose name begins with a specified prefix.
java.lang.String[]	getSubscriberNamesWithSuffix(java.lang.String lastBulkEnd, int numOfSubscribers, java.lang.String suffix) Gets subscribers in the SM database whose names end with the specified suffix.
void	init(java.util.Properties properties) Initiates some configuration parameters of the client.
boolean	isConnected() tests whether the client is connected
void	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.
void	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).
boolean	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).
boolean	logoutByName(java.lang.String subscriberName, java.lang.String[] mappings, short[] mappingTypes) Locates the subscriber in the database and removes mappings from it
boolean	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.
boolean	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	removeAllSubscribers() Removes all subscribers from the SM, leaving the database with no subscribers.
void	removeCustomProperties(java.lang.String subscriberName, java.lang.String[] customProperties) remove the specified custom properties of a subscriber.
boolean	removeSubscriber(java.lang.String subscriberName) Removes a subscriber completely from the SM database.
void	setDisconnectListener(DisconnectListener disconnectListener) Sets a disconnect listener.
void	setPropertiesToDefault(java.lang.String subscriberName, java.lang.String[] properties) Resets the specified application properties of a subscriber.
void	setReplyTimeout(long _timeout) sets a timeout, after which the methods of this API will return (with an exception) if the result has not yet arrived.
boolean	subscriberExists(java.lang.String subscriberName) Verifies that a subscriber exists in the SM database.
boolean	subscriberLoggedIn(java.lang.String subscriberName) Checks whether a subscriber that already exists in the SM database is logged in, that is, if the subscriber also exists in some SCE database.
java.lang.String	toString() Automatically generated method: toString

Methods inherited from class java.lang.Object

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

Constructor Detail

SMBlockingApi

public SMBlockingApi()

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

SMBlockingApi

public SMBlockingApi(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.

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.

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 disconnceting)

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 -

setReplyTimeout

public final void setReplyTimeout(long _timeout)

sets a timeout, after which the methods of this API will return (with an exception) if the result has not yet arrived. The defulat timeout is to wait for ever.

The timeout can be set again and again before each method call.

Parameters:

_timeout - either a positive number which is the number of miliseconds to wait or zero - wait forever

login

public void 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,
                  OperationTimeoutException,
                  RpcErrorException

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, 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.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

logoutByName

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

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:

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 or logout operation neglected due to different mapping types in same call.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

logoutByNameFromDomain

public boolean logoutByNameFromDomain(java.lang.String subscriberName,
                                      java.lang.String[] mappings,
                                      short[] mappingTypes,
                                      java.lang.String domain)
                               throws java.lang.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.

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:

TRUE: if the subscriber was found and removed from the subscriber database FALSE: if the subscriber was not found in the subscriber database or logout operation neglected due to different mapping types in same call.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

logoutByMapping

public boolean logoutByMapping(java.lang.String mapping,
                               short mappingType,
                               java.lang.String domain)
                        throws java.lang.InterruptedException,
                               OperationTimeoutException,
                               RpcErrorException

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:

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 the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

loginCable

public void 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,
                       OperationTimeoutException,
                       RpcErrorException

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 Subscriber 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.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

logoutCable

public boolean logoutCable(java.lang.String CPE,
                           java.lang.String CM,
                           java.lang.String IP,
                           java.lang.String domain)
                    throws java.lang.InterruptedException,
                           OperationTimeoutException,
                           RpcErrorException

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:

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 the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

addSubscriber

public void addSubscriber(java.lang.String subscriberName,
                          java.lang.String[] mappings,
                          short[] mappingTypes,
                          java.lang.String[] propertyKeys,
                          java.lang.String[] propertyValues,
                          java.lang.String[] customPropertyKeys,
                          java.lang.String[] customPropertyValues,
                          java.lang.String domain)
                   throws java.lang.InterruptedException,
                          OperationTimeoutException,
                          RpcErrorException

Creates a new subscriber record according to the given data and adds it 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 provided to it and leaves unspecified fields unchanged, addSubscriber sets the subscriber exactly as specified by the parameters passed to it. Note that with addSubscriber the auto-logout feature is always disabled; to enable it, use login.

Example:
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), A will be left with no mappings. However, calling the login operation with these NULL-value parameters will not change AB's mappings. A will be left with the previous IP mapping: IP1.

Parameters:

subscriberName - See the susbcriber name section in the overview

mappings - See the mappings section in the overview.

mappingTypes - See the mappings section in the overview.

propertyKeys - See the properties section in the overview.

propertyValues - See the properties section in the overview.

customPropertyKeys - See the custom-properties section in the overview.

customPropertyValues - See the custom-properties section in the overview.

domain - See the domains section in the overview. A NULL value indicates that the subscriber is domain-less.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

removeSubscriber

public boolean removeSubscriber(java.lang.String subscriberName)
                         throws java.lang.InterruptedException,
                                OperationTimeoutException,
                                RpcErrorException

Removes a subscriber completely from the SM database.

Parameters:

subscriberName - See the susbcriber name section in the overview

Returns:

TRUE: if the subscriber was found in the database and successfully removed. FALSE: on any other occasion.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getSubscriberNames

public java.lang.String[] getSubscriberNames(java.lang.String lastBulk,
                                             java.lang.String propName,
                                             java.lang.String propValue,
                                             int numOfSubs)
                                      throws java.lang.InterruptedException,
                                             OperationTimeoutException,
                                             RpcErrorException

Gets names of logged in subscribers in the SM database, starting with lastBulkEnd and having the propertyName, propertyValue pair 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.
Note: There is no guarantee that the total number of subscribers (in all bulks) will equal the value returned from getNumOfSubscribers at any time. They may differ, for example, if some subscribers are added or removed while bulks are being retrieved.

Parameters:

lastBulkEnd - : Last subscriber name from last bulk.
NULL: to start with the first (alphabetically) subscriber.

propName - The property Name on which the subscribers needs to be retrived

propValue - The value of the above property

numOfSubscribers - Limit on number of subscribers that will be returned. If this value is higher then the SM limit (1000), the SM limit will be used. Note: Providing values higher than 500 to this parameter is not recommended.

Returns:

An array of logged in 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).

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getSubscriberNamesByPackageID

public java.lang.String[] getSubscriberNamesByPackageID(java.lang.String lastBulk,
                                                        java.lang.String propName,
                                                        java.lang.String propValue,
                                                        int numOfSubs)
                                                 throws java.lang.InterruptedException,
                                                        OperationTimeoutException,
                                                        RpcErrorException

the getSubscriberNamesByPackageID retrives the subscribers based on the packageId. ie when the getSubscriberNamesByPackageID with lastbulk,packageId=1 then the subscribers with the base packageID 1 is retrived,and when in case add on packages is enabled the getSubscriberNamesByPackageID will return the extact match of the packageID. eg: >> Subscriber PackageID AddonPackages Results sub1 1 2,3 getSubscriberNamesByPackageID("sub","packageID","1,2,3") --> sub1 sub2 1 getSubscriberNamesByPackageID("sub","packageID","1,2,3") --> null sub2 1 getSubscriberNamesByPackageID("sub","packageID","1") --> sub2 sub3 2 getSubscriberNamesByPackageID("sub","packageID","2") --> sub3 sub4 2 4,5 getSubscriberNamesByPackageID("sub","packageID","2") --> sub3

Throws:

java.lang.InterruptedException

OperationTimeoutException

RpcErrorException

removeAllSubscribers

public void removeAllSubscribers()
                          throws java.lang.InterruptedException,
                                 OperationTimeoutException,
                                 RpcErrorException

Removes all subscribers from the SM, leaving the database with no subscribers.
Note: This method may take time to execute. To avoid operation timeout exceptions, set high operation timeout (up to 5 minutes) before calling this method.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getNumberOfSubscribers

public int getNumberOfSubscribers()
                           throws java.lang.InterruptedException,
                                  OperationTimeoutException,
                                  RpcErrorException

Retrieves the total number of subscribers in the SM database

Returns:

The number of subscribers in the SM.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getNumberOfSubscribersInDomain

public int getNumberOfSubscribersInDomain(java.lang.String domain)
                                   throws java.lang.InterruptedException,
                                          OperationTimeoutException,
                                          RpcErrorException

Retrieves the number of subscribers in a subscriber domain

Parameters:

domain - A name of a subscriber domain that exists in the SM's domain repository. See the domains section in the overview.

Returns:

The number of subscribers in the domain provided.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getSubscriber

public java.lang.Object[] getSubscriber(java.lang.String subscriberName)
                                 throws java.lang.InterruptedException,
                                        OperationTimeoutException,
                                        RpcErrorException

Retrieves 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 thrown.

Parameters:

subscriberName - See the susbcriber name section in the overview

Returns:

An Object Array with nine elements. The values for each index are listed below. No array element is null.

index 0: subscriber name (java.lang.String)

index 1: array of mappings (java.lang.String[])

index 2: array of mapping types (short[])

index 3: domain name (java.lang.String)

index 4: array of property names (java.lang.String[])

index 5: array of property values (java.lang.String[])

index 6: array of custom property names (java.lang.String[])

index 7: array of custom property values (java.lang.String[])

index 8: auto-logout time, seconds from now or -1 if not set (Integer)

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

subscriberExists

public boolean subscriberExists(java.lang.String subscriberName)
                         throws java.lang.InterruptedException,
                                OperationTimeoutException,
                                RpcErrorException

Verifies that a subscriber exists in the SM database.

Parameters:

subscriberName - See the susbcriber name section in the overview

Returns:

TRUE: if the subscriber was found in the SM database. FALSE: if the subscriber could not be found.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

subscriberLoggedIn

public boolean subscriberLoggedIn(java.lang.String subscriberName)
                           throws java.lang.InterruptedException,
                                  OperationTimeoutException,
                                  RpcErrorException

Checks whether a subscriber that already exists in the SM database is logged in, that is, if the subscriber also exists in some 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 some SCE database, but rather that 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.

Parameters:

subscriberName - See the susbcriber name section in the overview

Returns:

TRUE: if the subscriber is logged in. FALSE: if the subscriber is not logged in.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getSubscriberNameByMapping

public java.lang.String getSubscriberNameByMapping(java.lang.String mapping,
                                                   short mappingType,
                                                   java.lang.String domain)
                                            throws java.lang.InterruptedException,
                                                   OperationTimeoutException,
                                                   RpcErrorException

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

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:

subscriber name, or null if not found

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getSubscriberNames

public java.lang.String[] getSubscriberNames(java.lang.String lastBulkEnd,
                                             int numOfSubscribers)
                                      throws java.lang.InterruptedException,
                                             OperationTimeoutException,
                                             RpcErrorException

Gets names of subscribers in 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.
Note: There is no guarantee that the total number of subscribers (in all bulks) will equal the value returned from getNumOfSubscribers at any time. They may differ, for example, if some subscribers are added or removed while bulks are being retrieved.

Parameters:

lastBulkEnd - : Last subscriber name from last bulk.
NULL: to start with the first (alphabetically) subscriber.

numOfSubscribers - Limit on number of subscribers that will be returned. If this value is higher then the SM limit (1000), the SM limit will be used. Note: Providing values higher than 500 to this parameter is not recommended.

Returns:

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).

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

getSubscriberNamesInDomain

public java.lang.String[] getSubscriberNamesInDomain(java.lang.String lastBulkEnd,
                                                     int numOfSubscribers,
                                                     java.lang.String domain)
                                              throws java.lang.InterruptedException,
                                                     OperationTimeoutException,
                                                     RpcErrorException

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 getSubscriberNames operation.

Parameters:

lastBulkEnd - See the getSubscriberNames method

numOfSubscribers - See the getSubscriberNames method

domain - The name of a subscriber domain that exists in the SM domain repository. See the domains section in the overview.

Returns:

An alphabetically ordered array of subscriber names that belong to the domain provided. See also the documentation of the Return Value section of the getSubscriberNames operation

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants, getSubscriberNames(java.lang.String, java.lang.String, java.lang.String, int)

getSubscriberNamesWithPrefix

public java.lang.String[] getSubscriberNamesWithPrefix(java.lang.String lastBulkEnd,
                                                       int numOfSubscribers,
                                                       java.lang.String prefix)
                                                throws java.lang.InterruptedException,
                                                       OperationTimeoutException,
                                                       RpcErrorException

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 getSubscriberNames operation.

Parameters:

lastBulkEnd - See the getSubscriberNames method

numOfSubscribers - See the getSubscriberNames method

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

Returns:

An alphabetically ordered array of subscriber names that start with the prefix required. See also the documentation of the Return Value section of the getSubscriberNames operation

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants, getSubscriberNames(java.lang.String, java.lang.String, java.lang.String, int)

getSubscriberNamesWithSuffix

public java.lang.String[] getSubscriberNamesWithSuffix(java.lang.String lastBulkEnd,
                                                       int numOfSubscribers,
                                                       java.lang.String suffix)
                                                throws java.lang.InterruptedException,
                                                       OperationTimeoutException,
                                                       RpcErrorException

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 getSubscriberNames operation.

Parameters:

lastBulkEnd - See the getSubscriberNames method

numOfSubscribers - See the getSubscriberNames method

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

Returns:

An alphabetically ordered array of subscriber names that end with the suffix required. See also the documentation of the Return Value section of the getSubscriberNames operation

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants, getSubscriberNames(java.lang.String, java.lang.String, java.lang.String, int)

getDomains

public java.lang.String[] getDomains()
                              throws java.lang.InterruptedException,
                                     OperationTimeoutException,
                                     RpcErrorException

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

Returns:

A complete list of subscriber domain names in the SM.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

setPropertiesToDefault

public void setPropertiesToDefault(java.lang.String subscriberName,
                                   java.lang.String[] properties)
                            throws java.lang.InterruptedException,
                                   OperationTimeoutException,
                                   RpcErrorException

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 thrown.

Parameters:

subscriberName - See the susbcriber name section in the overview

properties - See the properties section in the overview. Defines which application properties to reset

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants

removeCustomProperties

public void removeCustomProperties(java.lang.String subscriberName,
                                   java.lang.String[] customProperties)
                            throws java.lang.InterruptedException,
                                   OperationTimeoutException,
                                   RpcErrorException

remove the specified custom properties of a subscriber.

Parameters:

subscriberName - See the susbcriber name section in the overview

customProperties - Defines which custom properties to remove.
See the custom-properties section in the overview.

Throws:

java.lang.InterruptedException - See the reply timeout and operation timeout exception section in the overview.

OperationTimeoutException - See the reply timeout and operation timeout exception section in the overview.

RpcErrorException - See the exceptions section in the overview.

See Also:

SMApiConstants