Blocking API. Introduction. Multithreading Support CHAPTER

Transcription

1 CHAPTER 3 Blocking API Revised: November 8, 2010, Introduction This chapter introduces the Reply Timeout, a feature unique to the Blocking Application Programming Interface (API). The rest of the chapter lists all operations of the Blocking API, and provides code examples. Note If you only need to develop an automatic integration, skip this chapter and go directly to Chapter 4, Nonblocking API. Multithreading Support, page 3-1 ReplyTimeout and OperationTimeout Exception, page 3-2 Information About SM Blocking API Methods, page 3-3 Information About QM Blocking API Methods, page 3-34 Blocking API Code Examples, page 3-41 Multithreading Support The Blocking API supports unlimited number of threads calling its methods simultaneously. Note In a multithreaded scenario for the Blocking API, the order of invocation is not guaranteed. Example: Thread-0 calls operation-0 at time-0, and thread-1 calls operation-1 at time-1, where time-1 is later than time-0. In this example, it is possible that operation-1 may be performed before operation-0, as shown in Figure 3-1 (the vertical scale is time): 3-1

2 ReplyTimeout and OperationTimeout Exception Chapter 3 Blocking API Figure 3-1 Multithreading Support Thread 0 : Thread 1 : SM Blocking API : op-0 : operation op-1 : operation op-1 : result op-0 : result The Subscriber Manager (SM) allocates five threads to handle each API instance. It is recommended to develop a multithreaded application that uses the API with several threads in the order of the five threads. Implementing with more threads might result in longer delays for the calling threads. ReplyTimeout and OperationTimeout Exception A blocking operation returns only when the operation result has been retrieved from the SM. If a networking malfunction or other error prevents the operation result from being retrieved, the caller will wait indefinitely. The SM API provides means of working around this situation. The reply timeout feature (the setreplytimeout method) lets the caller set a timeout. It will fire a com.pcube.management.framework.rpc.operationtimeoutexception when a reply does not return within the timeout period. Calling the setreplytimeout method with a long value sets a reply timeout. The reply timeout is interpreted in milliseconds. A zero value indicates that the operation should wait (freeze, hang) until a result arrives - or indefinitely, if no result arrives. There is an alternative way to release a method call that is blocking the caller, who is waiting for a result to arrive: Call the interrupt method of the calling thread: a java.lang.interruptedexception will then be returned to the caller. 3-2

3 Chapter 3 Blocking API Information About SM Blocking API Methods Information About SM Blocking API Methods This section lists the methods of the SM Blocking API. The syntax of each method is followed by a description of each method s input parameters and return values. The Blocking API is a superset of the Nonblocking API. Except for differences in return values and result handling, identical operations in both APIs have the same functions and syntax structure. All the methods throw a java.lang.illegalstateexception when called before a connection with the SM is established. The Blocking API methods can be classified into the following categories: Dynamic IP and property allocation For using the SM API for integration with an authentication, authorization, and accounting (AAA) system, the following methods are relevant. These methods are not designed to add or remove subscribers from the database, but to modify dynamic parameters (such as IP addresses) of the existing subscribers: login, page 3-4 logoutbyname, page 3-7 logoutbynamefromdomain, page 3-9 logoutbymapping, page 3-10 logincable, page 3-12 logoutcable, page 3-14 Static/Manual Subscriber configuration For example, for GUI usage, the following methods are relevant: addsubscriber, page 3-15 removesubscriber, page 3-17 removeallsubscribers, page 3-18 setpropertiestodefault, page 3-32 removecustomproperties, page 3-33 For simple read-only operations, performed independently on the subscriber awareness mode, the following methods are relevant: getnumberofsubscribers, page 3-19 getnumberofsubscribersindomain, page 3-20 getsubscriber, page 3-20 subscriberexists, page 3-22 subscriberloggedin, page 3-23 getsubscribernamebymapping, page 3-24 getsubscribernames (all), page 3-25 getsubscribernames (filter by property), page 3-27 getsubscribernamesindomain, page 3-28 getsubscribernameswithprefix, page 3-29 getsubscribernameswithsuffix, page 3-30 getdomains, page

4 login Chapter 3 Blocking API It is possible to mix methods from different categories in a single application. The classification is presented only for clarification purposes. login, page 3-4 logoutbyname, page 3-7 logoutbynamefromdomain, page 3-9 logoutbymapping, page 3-10 logincable, page 3-12 logoutcable, page 3-14 addsubscriber, page 3-15 removesubscriber, page 3-17 removeallsubscribers, page 3-18 getnumberofsubscribers, page 3-19 getnumberofsubscribersindomain, page 3-20 getsubscriber, page 3-20 subscriberexists, page 3-22 subscriberloggedin, page 3-23 getsubscribernamebymapping, page 3-24 getsubscribernames (all), page 3-25 getsubscribernames (filter by property), page 3-27 getsubscribernamesindomain, page 3-28 getsubscribernameswithprefix, page 3-29 getsubscribernameswithsuffix, page 3-30 getdomains, page 3-31 setpropertiestodefault, page 3-32 removecustomproperties, page 3-33 login The following sections provide login operation information:, page 3-5, page 3-5, page 3-5, page 3-6, page 3-6 Examples, page

5 Chapter 3 Blocking API login The login syntax: public void login(string subscribername, String[] mappings, short[] mappingtypes, String[] propertykeys, String[] propertyvalues, 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. 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 are removed from the other subscriber and assigned to the new subscriber. If the subscriber does not exist in the SM database, it is created with the data provided. subscribername See the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. mappings See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. If no mappings are specified, and the ismappingadditive flag is TRUE, the previous mappings are retained. If no such mappings exist, the operation fails. mappingtypes See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. propertykeys See the explanation of property keys and values in the Subscriber Properties section on page 2-7. propertyvalues See the explanation of property keys and values in the Subscriber Properties section on page 2-7. domain See the explanation of subscriber domains in the Subscriber Domains section on page 2-6. If domain is NULL, but the subscriber already has a domain, the existing domain is retained. If the domain is different to the domain that was previously assigned to the subscriber, the subscriber is removed automatically from the SCEs of the previous domain and moved to the SCEs of the new domain. 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. 3-5

6 login Chapter 3 Blocking API 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. Negative value Disables any expiration time that might have been set for the mappings given. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_BAD_SUBSCRIBER_MAPPING ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION ERROR_CODE_DATABASE_EXCEPTION ERROR_CODE_UNKNOWN This error can be caused by the following: NULL value for domain parameter for the subscriber that does not exist or does not have a domain Invalid values for propertyvalues parameter For a description of error codes, see Appendix A, List of Error Codes. None. Examples To add the IP address to an existing subscriber named alpha without affecting existing mappings: login( "alpha", // subscriber name new String[]{" "}, SMApiConstants.ALL_IP_MAPPINGS, null, null, "subscribers", // domain true, // ismappingadditive is true -1); // autologouttime set to infinite To add the IP address overriding previous mappings: login( "alpha", // subscriber name new String[]{" "}, SMApiConstants.ALL_IP_MAPPINGS, null, null, "subscribers", // domain false, // ismappingadditive is false -1); // autologouttime set to infinite 3-6

7 Chapter 3 Blocking API logoutbyname To extend the auto logout time of that was previously assigned to alpha: login( "alpha", //the previously assigned IP new String[]{" "}, SMApiConstants.ALL_IP_MAPPINGS, null, null, "subscribers", // domain false, // ismappingadditive 300); // autologouttime set to 300 seconds To modify a dynamic property of alpha (for example. package ID): login( "alpha", null, null, new String[]{"packageId"}, // property key new String[]{"10"}, // property value "subscribers", // domain false, -1); To add the IP address to an existing subscriber named alpha without affecting existing mappings and modify a dynamic property of alpha (for example. package ID): login( "alpha", new String[]{" "}, SMApiConstants.ALL_IP_MAPPINGS, new String[]{"packageId"}, // property key new String[]{"10"}, // property value "subscribers", // domain true, // ismappingadditive is set to true -1); logoutbyname The following sections provide logoutbyname operation information:, page 3-7, page 3-8, page 3-8, page 3-8, page 3-8 Examples, page 3-8 The logoutbyname syntax: public boolean logoutbyname(string subscribername, String[] mappings, short[] mappingtypes) 3-7

8 logoutbyname Chapter 3 Blocking API Locates the subscriber in the database and removes mappings from it. If the subscriber does not exist, it does nothing. subscribername See the explanation of the subscriber name formatting in the Subscriber Name Format section on page 2-4. mappings See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. If no mappings are specified, all subscriber mappings are removed. mappingtypes See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. Examples TRUE If the subscriber was found and the subscribers mappings were removed from the subscriber database. FALSE If the subscriber was not found in the subscriber database. The following is the list of error codes that this method might return: ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. To remove IP address of subscriber alpha: boolean isexist = logoutbyname( "alpha", new String[]{" "}, SMApiConstants.ALL_IP_MAPPINGS); To remove all IP addresses of subscriber alpha: boolean isexist = logoutbyname("alpha", null, null); 3-8

9 Chapter 3 Blocking API logoutbynamefromdomain logoutbynamefromdomain The following sections provide logoutbynamefromdomain operation information:, page 3-9, page 3-9, page 3-9, page 3-9, page 3-10 Example, page 3-10 The logoutbynamefromdomain syntax; public boolean logoutbynamefromdomain(string subscribername, String[] mappings, short[] mappingtypes, String domain) 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 the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. mappings See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. If no mappings are specified, all the subscriber mappings are removed. mappingtypes See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. domain See the explanation of subscriber domains in the Subscriber Domains section on page 2-6. The operation fails if either of the following conditions exists: Domain is null, but the subscriber exists in the database and belongs to a domain. Domain specified is incorrect. TRUE If the subscriber was found and removed from the subscriber database. FALSE If the subscriber was not found in the subscriber database. 3-9

10 logoutbymapping Chapter 3 Blocking API Example The following is the list of error codes that this method might return: ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. To remove IP address of subscriber alpha from domain subscribers: boolean isexist = logoutbynamefromdomain( "alpha", new String[]{" "}, SMApiConstants.ALL_IP_MAPPINGS, "subscribers"); boolean isexist = logoutbynamefromdomain( "alpha", null, null, "subscribers"); logoutbymapping The following sections provide logoutbymapping operation information:, page 3-10, page 3-11, page 3-11, page 3-11, page 3-11 Example, page 3-11 The logoutbymapping syntax: public boolean logoutbymapping(string mapping, short mappingtype, String domain) 3-10

11 Chapter 3 Blocking API logoutbymapping Locates a subscriber based on domain and mapping, and removes the mapping (the subscriber stays in the database). mapping See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. mappingtype See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. domain See the description in the section on page 3-9 of the logoutbynamefromdomain operation. Example TRUE If the subscriber was found and removed from the subscriber database. FALSE If the subscriber was not found in the subscriber database. The following is the list of error codes that this method might return: ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. To remove IP address from domain subscribers: boolean isexist = logoutbymapping( " ", SMApiConstants. MAPPING_TYPE_IP, "subscribers"); 3-11

12 logincable Chapter 3 Blocking API logincable The following sections provide logincable operation information:, page 3-12, page 3-12, page 3-12, page 3-13, page 3-13 Examples, page 3-13 The logincable syntax: public void logincable(string CPE, String CM, String IP, int lease, String domain, String[] propertykeys, String[] propertyvalues) The logincable method is an operation adapted for the cable environment (calls the cable support module in the SM). This method is designed to log in the Customer Premise Equipment (CPE) and Content Managers (CMs) to the SM. To log in a CPE, specify its CM Media Access Control (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 is ignored: the CM has to exist in the database, either by import or by a CM login operation. For additional information, see the CPE as Subscriber in Cable Environment chapter of Cisco Service Control Management Suite 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. CPE Unique identifier of the CPE (usually a MAC address) CM Unique identifier of the cable modem (usually a MAC address) IP CPE IP address lease CPE lease time domain See the explanation of the subscriber domains in the Subscriber Domains section on page 2-6. The domain is usually CMTS IP. 3-12

13 Chapter 3 Blocking API logincable Note Domain aliases must be set on the SM in order for the CMTS IP to be correctly interpreted as a domain name. For information about aliases configuration see the Default Domains Configuration section of Cisco SCMS Subscriber Manager User Guide. propertykeys See the explanation of property keys and values in the Subscriber Properties section on page 2-7. If the CPE is provided with partial or no application properties, the values for the missing application properties are 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 explanation of property keys and values in the Subscriber Properties section on page 2-7. None. None. Examples To add the IP address to a CM called CM1 with 2 hours lease time: logincable( "CM1", "CM1", " ", 7200, // lease time in seconds "subscribers", null, null); To add the IP address to a CPE called CPE1 which is behind CM1 with lease time of 1 hour: logincable( "CPE1", "CM1", " ", 3600, // lease time in seconds "subscribers", null, null); 3-13

14 logoutcable Chapter 3 Blocking API logoutcable The following sections provide logoutcable operation information:, page 3-14, page 3-14, page 3-14, page 3-14, page 3-14 Example, page 3-14 The logoutcable syntax: public boolean logoutcable(string CPE, String CM, String IP, String domain) Indicates a logout (CPE becoming offline) event to the SM cable support module. CPE See the description in the section on page 3-12 of the logincable method. CM See the description in the section on page 3-12 of the logincable method. IP See the description in the section on page 3-12 of the logincable method. domain See the description in the section on page 3-12 of the logincable method. TRUE If the CPE was found and removed from the subscriber database. FALSE If the CPE was not found in the subscriber database. None. Example To remove the IP address from CPE1, which is behind CM1: boolean isexist = logoutcable( "CPE1", "CM1", " ", "subscribers"); 3-14

15 Chapter 3 Blocking API addsubscriber addsubscriber The following sections provide addsubscriber operation information:, page 3-15, page 3-15 Example, page 3-16, page 3-16, page 3-16, page 3-17 Examples, page 3-17 The addsubscriber syntax: public void addsubscriber(string subscribername, String[] mappings, short[] mappingtypes, String[] propertykeys, String[] propertyvalues, String[] custompropertykeys, String[] custompropertyvalues, String domain) Creates a new subscriber record according to the method parameters and adds the record to the SM database. If a subscriber by this name already exists, it is removed before the new one is added. In contrast to login, which modifies fields and leaves unspecified fields unchanged, the addsubscriber command sets the subscriber exactly as specified by the parameters passed to it. Note It is recommended to call login method for existing subscribers, instead of the addsubscriber command. Dynamic mappings and properties should be set by using the login command. Static mappings and properties should be set the first time the subscriber is created by using the addsubscriber command. Note With the addsubscriber command, the autologout feature is always disabled. To enable autologout, use the login command. 3-15

16 addsubscriber Chapter 3 Blocking API 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), AB is left with no mappings. However, calling the login operation with these NULL-value parameters will not change ABs mappings; AB will still have its previous IP mapping of IP1. subscribername See the explanation of subscriber name format in the Subscriber Name Format section on page 2-4. mappings See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. mappingtypes See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. propertykeys See the explanation of property keys and values in the Subscriber Properties section on page 2-7. propertyvalues See the explanation of property keys and values in the Subscriber Properties section on page 2-7. custompropertykeys See the explanation of custom property keys and values in the Custom Properties section on page 2-7. custompropertyvalues See the explanation of custom property keys and values in the Custom Properties section on page 2-7. domain See the explanation of subscriber domains in the Subscriber Domains section on page 2-6. A NULL value indicates that the subscriber is domain-less. If domain is NULL, but the subscriber already has a domain, the existing domain is retained. None. 3-16

17 Chapter 3 Blocking API removesubscriber Examples The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE_SUBSCRIBER_ALREADY_EXISTS ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION ERROR_CODE_UNKNOWN This error code may indicate invalid values that were supplied for propertyvalues parameter. ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. To add a new subscriber, alpha, with some custom properties: addsubscriber("alpha", null, null, // dynamic mappings will be set by login null, null // dynamic properties will be set by login new String[]{ // custom property keys "work phone", "home phone"}, new String[]{ // custom property values " " " "}, "subscribers"); // default domain removesubscriber The following sections provide removesubscriber operation information:, page 3-17, page 3-18, page 3-18, page 3-18, page 3-18 Example, page 3-18 The removesubscriber syntax: public boolean removesubscriber(string subscribername) 3-17

18 removeallsubscribers Chapter 3 Blocking API Removes a subscriber completely from the SM database. subscribername See the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. Example TRUE If the subscriber was found in the database and successfully removed. FALSE If the conditions for TRUE were not met; in other words, the subscriber was not found in the database, or the subscriber was found but was not successfully removed. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. To remove subscriber alpha entirely from the database: boolean isexist = removesubscriber("alpha"); removeallsubscribers The following sections provide removeallsubscribers operation information:, page 3-18, page 3-19, page 3-19, page 3-19 The removeallsubscribers syntax: public void removeallsubscribers() 3-18

19 Chapter 3 Blocking API getnumberofsubscribers 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 a high operation timeout (up to 5 minutes) before calling this method. None. None. getnumberofsubscribers The following sections provide getnumberofsubscribers operation information:, page 3-19, page 3-19, page 3-19, page 3-19 The getnumberofsubscribers syntax: public int getnumberofsubscribers() Retrieves the total number of subscribers in the SM database. The number of subscribers in the SM. None. 3-19

20 getnumberofsubscribersindomain Chapter 3 Blocking API getnumberofsubscribersindomain The following sections provide getnumberofsubscribersindomain operation information:, page 3-20, page 3-20, page 3-20, page 3-20, page 3-20 The getnumberofsubscribersindomain syntax: public int getnumberofsubscribersindomain(string domain) Retrieves the number of subscribers in a subscriber domain. domain Name of a subscriber domain that exists in the SMs domain repository. The number of subscribers in the domain provided. The following is the list of error codes that this method might return: ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN ERROR_CODE _DOMAIN_NOT_FOUND For a description of error codes, see Appendix A, List of Error Codes. getsubscriber The following sections provide getsubscriber operation information:, page 3-21, page 3-21, page 3-21, page 3-21, page 3-21 Example, page

21 Chapter 3 Blocking API getsubscriber The getsubscriber syntax: public Object[] getsubscriber(string subscribername) Retrieves a subscriber record. Each field is formatted as an integer, string, or string array, as described below in the section for this method. If the subscriber does not exist in the SM database, an exception is returned. subscribername See the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. An Object Array with nine elements. Table 3-1 lists the index values and descriptions. No array element is NULL. Table 3-1 Indexes and s Index Value Index 0 Index 1 Index 2 Index 3 Index 4 Index 5 Index 6 Index 7 Index 8 subscriber name (java.lang.string) array of mappings (java.lang.string[]) array of mapping types (short[]) domain name (java.lang.string) array of property names (java.lang.string[]) array of property values (java.lang.string[]) array of custom property names (java.lang.string[]) array of custom property values (java.lang.string[]) autologout time, as seconds from now, or -1 if not set (long[]) The following is the list of error codes that this method might return: ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. 3-21

22 subscriberexists Chapter 3 Blocking API Example To retrieve the subscriber record of alpha: Object[] subrecord = getsubscriber("alpha"); String[] mappings = (String[])subRecord[1] short[] mappingtypes = {short[])subrecord[2]; String domainname = (String)subRecord[3]; String[] propertynames = (String[])subRecord[4]; String[] propertyvalues = (String[])subRecord[5]; String[] custompropertyname = (String[])subRecord[6]; String[] custompropertyvalues = (String[])subRecord[7]; long[] autologouttime = (long[])subrecord[8]; subscriberexists The following sections provide subscriberexists operation information:, page 3-22, page 3-22, page 3-22, page 3-22, page 3-22 The subscriberexists syntax: public boolean subscriberexists(string subscribername) Verifies that a subscriber exists in the SM database. subscribername See the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. TRUE If the subscriber was found in the SM database. FALSE If the subscriber could not be found. None. 3-22

23 Chapter 3 Blocking API subscriberloggedin subscriberloggedin The following sections provide subscriberloggedin operation information:, page 3-23, page 3-23, page 3-23, page 3-23, page 3-23 The subscriberloggedin syntax: public boolean subscriberloggedin(string subscribername) Checks whether a subscriber that already exists in the SM database is logged in; in other words, 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 is thrown. subscribername See the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. TRUE If the subscriber is logged in. FALSE If the subscriber is not logged in. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. 3-23

24 getsubscribernamebymapping Chapter 3 Blocking API getsubscribernamebymapping The following sections provide getsubscribernamebymapping operation information:, page 3-24, page 3-24, page 3-24, page 3-24, page 3-25 The getsubscribernamebymapping syntax: public String getsubscribernamebymapping(string mapping, short mappingtype, String domain) Finds a subscriber name according to a mapping and a domain. mapping See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. mappingtype See the explanation of mappings and mapping types in the Information About Network ID Mappings section on page 2-4. domain Name of the domain to which the subscriber belongs. The operation fails if either of the following conditions exists: Domain is null, but the subscriber exists in the database and belongs to a domain. Specified domain is incorrect. Subscriber name If a subscriber record was found. NULL If no subscriber record could be found. 3-24

25 Chapter 3 Blocking API getsubscribernames (all) The following is the list of error codes that this method might return: ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. getsubscribernames (all) The following sections provide information about the getsubscribernames (all) operation:, page 3-25, page 3-25, page 3-26, page 3-26, page 3-26 Example, page 3-26 The getsubscribernames (all) syntax: public String[] getsubscribernames(string lastbulkend, int numofsubscribers) Retrieves 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 first subscriber name (alphabetically) that exists in the SM database is used. Note There is no guarantee that the total number of subscribers (in all the bulks) will equal the value returned from getnumofsubscribers at any time. The values may differ if some subscribers are added or removed while the bulks are being retrieved. 3-25

26 getsubscribernames (all) Chapter 3 Blocking API lastbulkend The last subscriber name from the last bulk. Use NULL to start with the first (alphabetic) subscriber. numofsubscribers The limit on the number of subscribers that is returned. If this value is higher than the SM limit (1000), the SM limit is used. Note It is recommended that you do not provide a value of more than 500 subscribers. Example An array of subscriber names alphabetically ordered. The getsubscribernames (all) method returns as many subscribers as are found in the SM database, starting at the requested subscriber. The array size is limited by the smaller value between numofsubscribers and the SM limit (1000). The following are the error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. boolean hasmoresubscribers; String lastbulkend = null; int bulksize = 100; do { String[] subscribers = smapi.getsubscribernames(lastbulkend, bulksize); hasmoresubscribers = false; if (subscribers!= null) { for (int i = 0; i < subscribers.length; i++) { // do something with subscribers[i] } if (subscribers.length == bulksize) { hasmoresubscribers = true; lastbulkend = subscribers[bulksize - 1]; } } } while (hasmoresubscribers); 3-26

27 Chapter 3 Blocking API getsubscribernames (filter by property) getsubscribernames (filter by property) The following sections provide information about the getsubscribernames (filter by property) operation:, page 3-27, page 3-27, page 3-27, page 3-28, page 3-28 The getsubscribernames (filter by property) syntax: public String[] getsubscribernames(string lastbulkend,string propertyname,string propertyvalue,int numofsubscribers) Retrieves a bulk of subscriber names from the SM database, starting with lastbulkend followed by the next numofsubscribers subscribers (in alphabetical order), and based on the property name and property value. If lastbulkend is NULL, the first subscriber name (alphabetically) that exists in the SM database is used. Note There is no guarantee that the total number of subscribers (in all the bulks) will equal the value returned from getnumofsubscribers at any time. The values may differ if some subscribers are added or removed while the bulks are being retrieved. lastbulkend The last subscriber name from the last bulk. Use NULL to start with the first (alphabetic) subscriber. propertyname The property name of the string type used to filter subscriber names. propertyvalue The property value of the string type used to filter subscriber names. numofsubscribers The limit on number of subscribers that is returned. If this value is higher than the SM limit (1000), the SM limit is used. Note It is recommended that you do not provide a value of more than 500 subscribers. 3-27

28 getsubscribernamesindomain Chapter 3 Blocking API An array of alphabetically ordered subscriber names that matches the property name and its value provided. The method returns as many subscribers as are found in the SM database, starting at the requested subscriber. The array size is limited by the smaller value between numofsubscribers and the SM limit (1000). The following are the error codes that this method might return: ERROR_CODE_DATABASE_EXCEPTION ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME For a description of error codes, see Appendix A, List of Error Codes. getsubscribernamesindomain The following sections provide information about the getsubscribernamesindomain operation:, page 3-28, page 3-28, page 3-28, page 3-29, page 3-29 The getsubscribernamesindomain syntax: public String[] getsubscribernamesindomain(string lastbulkend, int numofsubscribers, String domain) 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 described in the getsubscribernames (all) section on page lastbulkend See description in the section on page 3-26 of the getsusbcribernames operation. numofsubscribers See description in the section on page 3-26 of the getsusbcribernames operation. domain The name of a subscriber domain that exists in the SM domain repository. 3-28

29 Chapter 3 Blocking API getsubscribernameswithprefix An alphabetically ordered array of subscriber names that belong to the domain provided. See also the section on page 3-26 of the getsubscribernames operation. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _DOMAIN_NOT_FOUND ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. getsubscribernameswithprefix The following section provide getsubscribernameswithprefix operation information:, page 3-29, page 3-29, page 3-29, page 3-30, page 3-30 The getsubscribernameswithprefix syntax: public String[] getsubscribernameswithprefix(string lastbulkend, int numofsubscribers, String prefix) 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 described in the getsubscribernames (all) section on page lastbulkend See the description in the section on page 3-26 of the getsusbcribernames operation. numofsubscribers See the description in the section on page 3-26 of the getsusbcribernames operation. prefix Case-sensitive string that marks the prefix of the required subscriber names. 3-29

30 getsubscribernameswithsuffix Chapter 3 Blocking API An alphabetically ordered array of subscriber names that start with the prefix required. See also the section on page 3-26 of the getsubscribernames operation. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. getsubscribernameswithsuffix The following sections provide getsubscribernameswithsuffix operation information:, page 3-30, page 3-30, page 3-30, page 3-31, page 3-31 The getsubscribernameswithsuffix syntax: public String[] getsubscribernameswithsuffix(string lastbulkend, int numofsubscribers, String suffix) 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 described in the getsubscribernames (all) section on page lastbulkend See the description in the section on page 3-26 of the getsusbcribernames operation. numofsubscribers See the description in the section on page 3-26 of the getsusbcribernames operation. suffix Case-sensitive string that marks the suffix of the required subscriber names. 3-30

31 Chapter 3 Blocking API getdomains An alphabetically ordered array of subscriber names that end with the suffix required. See also the section on page 3-26 of the getsubscribernames operation. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. getdomains The following sections provide getdomains operation information:, page 3-31, page 3-31, page 3-31, page 3-31 The getdomains syntax: public String[] getdomains() Provides the list of current subscriber domains in the SM domain repository. A complete list of subscriber domain names in the SM. None. 3-31

32 setpropertiestodefault Chapter 3 Blocking API setpropertiestodefault The followining sections provide setpropertiestodefault operation information:, page 3-32, page 3-32, page 3-32, page 3-32, page 3-32 The setpropertiestodefault syntax: public void setpropertiestodefault(string subscribername, String[] properties) Resets the specified application properties of a subscriber. If an application is installed, the relevant application properties is 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 is returned. subscribername See the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. properties See the explanation of property keys and values in the Subscriber Properties section on page 2-7. None. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. 3-32

33 Chapter 3 Blocking API removecustomproperties removecustomproperties The following section provide removecustomproperties operation information:, page 3-33, page 3-33, page 3-33, page 3-33, page 3-33 The removecustomproperties syntax: public void removecustomproperties(string subscribername, String[] customproperties) Resets the specified custom properties of a subscriber. subscribername See the explanation of subscriber name formatting in the Subscriber Name Format section on page 2-4. CustomProperties See the explanation of custom property keys and values in the Custom Properties section on page 2-7. None. The following is the list of error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. 3-33

34 Information About QM Blocking API Methods Chapter 3 Blocking API Information About QM Blocking API Methods This section lists the methods of the QM Blocking API. The syntax of each method is followed by a description of each method s input parameters and return values. For static or manual subscriber quota configuration, the following methods are relevant: addsubscriberquota, page 3-34 setsubscriberquota, page 3-35 replenishsubscriberquota, page 3-36 For simple read-only operations, the following methods are relevant: getsubscriberquotainformation, page 3-37 getsubscriberquotaprofileid, page 3-38 getbreachedsubscribernames, page 3-39 getpenaltysubscribernames, page 3-40 addsubscriberquota The following sections provide information about the addsubscriberquota operation:, page 3-34, page 3-34, page 3-34, page 3-35 The addsubscriberquota syntax: public void addsubscriberquota(string subscribername,int bucketid,long bucketsize) The addsubscriberquota method adds the quota for the given bucket ID of a subscriber. subscribername See the explanation for the subscriber name format in the Subscriber Name Format section on page 2-4. bucketid An integer value of the bucket ID to add. bucketsize A long value of the bucket size to add. 3-34

35 Chapter 3 Blocking API setsubscriberquota The following are the error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _DATABASE_EXCEPTION ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_NO_QUOTA_INFO_FOR_SUBSCRIBER ERROR_CODE_INVALID_BUCKETID ERROR_CODE_INVALID_BUCKETSIZE setsubscriberquota The following sections provide information about the setsubscriberquota operation:, page 3-35, page 3-35, page 3-35, page 3-36 The setsubscriberquota syntax: public void setsubscriberquota(string subscribername,int bucketid,long bucketsize) The setsubscriberquota method updates the quota for the given bucket ID of a subscriber. subscribername See the explanation for the subscriber name format in the Subscriber Name Format section on page 2-4. bucketid An integer value of the bucket ID to update. bucketsize A long value of the bucket size to update. 3-35

36 replenishsubscriberquota Chapter 3 Blocking API The following are the error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _DATABASE_EXCEPTION ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_NO_QUOTA_INFO_FOR_SUBSCRIBER ERROR_CODE_INVALID_BUCKETID ERROR_CODE_INVALID_BUCKETSIZE replenishsubscriberquota The following sections provide information about the replenishsubscriberquota operation:, page 3-36, page 3-36, page 3-36, page 3-36 The replenishsubscriberquota syntax: public void replenishsubscriberquota(string subscribername) The replenishsubscriberquota method replenishes the quota for the given subscriber. subscribername See the explanation for the subscriber name format in the Subscriber Name Format section on page 2-4. The following are the error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _DATABASE_EXCEPTION ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_NO_QUOTA_INFO_FOR_SUBSCRIBER ERROR_REPLENISH_FAILED 3-36

37 Chapter 3 Blocking API getsubscriberquotainformation getsubscriberquotainformation The following sections provide information about the getsubscriberquotainformation operation:, page 3-37, page 3-37, page 3-37, page 3-37, page 3-38 The getsubscriberquotainformation syntax: public Object[] getsubscriberquotainformation(string subscribername) Get a bulk of quota information for a specified subscriber. subscribername See the explanation for the subscriber name format in the Subscriber Name Format section on page 2-4. An object array with five elements. Table 3-2 lists the index values and descriptions. No array element is NULL. Table 3-2 Indexes and s Index Value Index 0 Index 1 Index 2 package ID (java.lang.string) last replenish time (java.lang.string) last SCE that consumed quota (java.lang.string) 3-37

38 getsubscriberquotaprofileid Chapter 3 Blocking API Table 3-2 Index Value Index 3 Index 4 Indexes and s (continued) aggregation period end (java.lang.string) quota buckets (java.lang.object[][]) Bucket 1: [0][0]=500 (quota size) [0][1]=500 (remaining quota) [0][2]=50 (last quota reported by SCE) [0][3]=time not set (penalty start) [0][4]=time not set (next penalty monitor) Bucket 2: [1][0]=500 (quota size) [1][1]=500 (remaining quota) [1][2]=50 (last quota reported by SCE) [1][3]=time not set (penalty start) [1][4]=time not set (next penalty monitor) The following are the error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _DATABASE_EXCEPTION ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_NO_QUOTA_INFO_FOR_SUBSCRIBER getsubscriberquotaprofileid The following sections provide information about the getsubscriberquotaprofileid operation:, page 3-38, page 3-39, page 3-39, page 3-39, page 3-39 The getsubscriberquotaprofileid syntax: public int getsubscriberquotaprofileid(string subscribername) 3-38

39 Chapter 3 Blocking API getbreachedsubscribernames The getsubscriberquotaprofileid method returns the quota profile ID for the specified subscriber. subscribername See the explanation for the subscriber name format in the Subscriber Name Format section on page 2-4. Quota profile ID. The following are the error codes that this method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _DATABASE_EXCEPTION ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST ERROR_CODE_SUBSCRIBER_NOT_ASSIGNED_PROFILE getbreachedsubscribernames The following sections provide information about the getbreachedsubscribernames operation:, page 3-39, page 3-39, page 3-40, page 3-40, page 3-40 The getbreachedsubscribernames syntax: public String[] getbreachedsubscribernames(string lastbulkend,int numofsubscribers) The getbreachedsubscribernames method retrieves the breached subscriber names. 3-39

40 getpenaltysubscribernames Chapter 3 Blocking API lastbulkend The last subscriber name from the last bulk. Use NULL to start with the first (alphabetic) subscriber. numofsubscribers The limit on number of subscribers that will be returned. If this value is higher than the SM limit (1000), then the SM limit is used. An array of alphabetically ordered subscriber names that belong to a breached state. This method returns all the subscribers found in the SM database starting with the requested subscriber. The array size is limited by the smaller value between numofsubscribers and the SM limit (1000). The getbreachedsubscribernames method might return an ERROR_CODE _DATABASE_EXCEPTION error code. getpenaltysubscribernames The following sections provide information about the getpenaltysubscribernames operation:, page 3-40, page 3-40, page 3-40, page 3-41, page 3-41 The getpenaltysubscribernames syntax: public String[] getpenaltysubscribernames(string lastbulkend,int numofsubscribers) The getpenaltysubscribernames method retrieves the subscriber names in a penalty state. lastbulkend The last subscriber name from the last bulk. Use NULL to start with the first (alphabetic) subscriber. numofsubscribers The limit on number of subscribers that will be returned. If this value is higher than the SM limit (1000), then the SM limit is used. 3-40

41 Chapter 3 Blocking API Blocking API Code Examples An array of alphabetically ordered subscriber names that belong to a penalty state. This method returns all the subscribers found in the SM database starting with the requested subscriber. The array size is limited by the smaller value between numofsubscribers and the SM limit (1000). The getpenaltysubscribernames method might return an ERROR_CODE _DATABASE_EXCEPTION error code. Blocking API Code Examples This section contains three code examples: Getting Number of Subscribers, page 3-41 Adding a Subscriber, Printing Information, and Removing a Subscriber, page 3-42 Getting Subscriber Quota Information, page 3-43 Getting Number of Subscribers The following example prints to stdout the total number of subscribers in the SM database and the number of subscribers in each subscriber domain: package blocking; import com.pcube.management.api.smblockingapi; public class PrintInfo { public static void main (String args[]) throws Exception { SMBlockingApi bapi = new SMBlockingApi(); try { //initiation bapi.setreplytimeout(300000); //set timeout for 5 minutes bapi.connect(args[0]); // connect to the SM } } //operations String[] domains=bapi.getdomains(); int totalsubscribers=bapi.getnumberofsubscribers(); System.out.println( "number of susbcribers in the database:\t\t "+ totalsubscribers); for (int i=0; i<domains.length; i++) { int numberofsusbcribersindomain= bapi.getnumberofsubscribersindomain(domains[i]); System.out.println( "number of susbcribers domain "+domains[i]+ ":\t\t "+numberofsusbcribersindomain); } } finally { //finalization bapi.disconnect(); } 3-41

42 Adding a Subscriber, Printing Information, and Removing a Subscriber Chapter 3 Blocking API Adding a Subscriber, Printing Information, and Removing a Subscriber The following program adds a subscriber to the subscriber database, then gets its information and prints it to stdout, and finally removes the subscriber from the subscriber database: package blocking; import com.pcube.management.api.smblockingapi; import com.pcube.management.api.smapiconstants; public class AddPrintRemove { public static void main (String args[]) throws Exception { checkarguments(args); SMBlockingApi bapi = new SMBlockingApi(); try { //initiation bapi.setreplytimeout(10000); //set timeout for 10 seconds bapi.connect(args[0]); // connect to the SM //add subscriber System.out.println("+ adding subscriber to SM"); bapi.addsubscriber( args[1], //name new String[]{args[2]}, //mapping SMApiConstants.ALL_IP_MAPPINGS, new String[]{args[3]}, //property key new String[]{args[4]}, //property value new String[]{"custom-key"}, //custom property key new String[]{"10"}, //custom property value args[5]); //domain //Print subscriber System.out.println("+ Printing subscriber"); Object[] subfields = bapi.getsubscriber(args[1]); System.out.println("\tname:\t\t"+subfields[0]); System.out.println("\tmapping:\t"+ ((String[])subfields[1])[0]); System.out.println("\tdomain:\t\t"+subfields[3]); System.out.println("\tautologout:\t"+subfields[8]); //Remove subscriber System.out.println("+ removing subscriber from SM"); bapi.removesubscriber(args[1]); } finally { //finalization bapi.disconnect(); } } } static void checkarguments(string[] args) throws Exception{ if (args.length!= 6) { System.err.println( "usage: java AddPrintRemove <SM-address>"+ " <subscriber-name> <IP mapping> <property-key>"+ " <property-value> <domain>"); System.exit(1); } } 3-42