Cisco Service Control Subscriber Manager Java API Programmer Guide

Transcription

1 Cisco Service Control Subscriber Manager Java API Programmer Guide Release 4.1.x December 23, 2013 Cisco Systems, Inc. Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the Cisco website at Text Part Number:

2 THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R) Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental Cisco Systems, Inc. All rights reserved.

3 CONTENTS About this Guide ix Introduction ix Document Revision History ix Organization x Related Documentation x Conventions x Obtaining Documentation and Submitting a Service Request xi CHAPTER 1 Getting Started 1-1 Introduction 1-1 The Java API 1-1 Introduction 1-1 Platforms 1-2 Package Content 1-2 Installing the Java API 1-2 Cisco Service Control Subscriber Manager Setup 1-3 Installing on a UNIX Platform 1-3 Installing on a Windows Platform 1-3 Compiling and Running a Program That Uses API 1-4 CHAPTER 2 General API Concepts 2-1 Introduction 2-1 Blocking API and the Nonblocking API 2-1 Blocking API 2-1 Nonblocking API 2-2 API Initialization 2-2 API Construction 2-2 Constructor that Accepts a LEG Name 2-2 Blocking API Example 2-3 Setup Operations 2-3 Blocking API Setup 2-3 Nonblocking API Setup 2-3 Connecting to the Cisco Service Control Subscriber Manager 2-3 i

4 Contents API Finalization 2-3 Subscriber Name Format 2-4 Network ID Mappings 2-4 Specifying IP Address Mapping 2-5 Specifying IPv6 Address Mapping 2-5 Specifying IP Range Mapping 2-5 Specifying Private IP Address or Private IP Range over VPN Mapping 2-6 Specifying VLAN Tag Mapping 2-6 Subscriber Domains 2-6 Subscriber Properties 2-7 Custom Properties 2-7 DisconnectListener Interface 2-7 DisconnectListener Interface Example 2-8 Exceptions 2-8 Practical Tips 2-8 CHAPTER 3 Blocking API 3-1 Introduction 3-1 Multithreading Support 3-1 ReplyTimeout and OperationTimeout Exception 3-2 Cisco Service Control Subscriber Manager Blocking API Methods 3-2 login 3-4 Syntax 3-4 Description 3-4 Parameters 3-4 RPC Exception Error Codes 3-5 Return Value 3-5 Examples 3-5 logoutbyname 3-7 Syntax 3-7 Description 3-8 Parameters 3-8 Return Value 3-8 RPC Exception Error Codes 3-8 Examples 3-8 logoutbynamefromdomain 3-9 Syntax 3-9 Description 3-9 ii

5 Contents Parameters 3-9 Return Value 3-9 RPC Exception Error Codes 3-10 Example 3-10 logoutbymapping 3-10 Syntax 3-10 Description 3-11 Parameters 3-11 Return Value 3-11 RPC Exception Error Codes 3-11 Example 3-11 logincable 3-12 Syntax 3-12 Description 3-12 Parameters 3-12 Return Value 3-13 RPC Exception Error Codes 3-13 Examples 3-13 logoutcable 3-14 Syntax 3-14 Description 3-14 Parameters 3-14 Return Value 3-14 RPC Exception Error Codes 3-14 Example 3-15 addsubscriber 3-15 Syntax 3-15 Description 3-15 Example 3-16 Parameters 3-16 Return Value 3-16 RPC Exception Error Codes 3-16 Examples 3-17 removesubscriber 3-17 Syntax 3-17 Description 3-17 Parameters 3-17 Return Value 3-18 RPC Exception Error Codes 3-18 Example 3-18 iii

6 Contents removeallsubscribers 3-18 Syntax 3-18 Description 3-18 Return Value 3-18 RPC Exception Error Codes 3-19 getnumberofsubscribers 3-19 Syntax 3-19 Description 3-19 Return Value 3-19 RPC Exception Error Codes 3-19 getnumberofsubscribersindomain 3-19 Syntax 3-19 Description 3-20 Parameters 3-20 Return Value 3-20 RPC Exception Error Codes 3-20 getsubscriber 3-20 Syntax 3-20 Description 3-21 Parameters 3-21 Return Value 3-21 RPC Exception Error Codes 3-21 Example 3-21 subscriberexists 3-22 Syntax 3-22 Description 3-22 Parameters 3-22 Return Value 3-22 RPC Exception Error Codes 3-22 subscriberloggedin 3-23 Syntax 3-23 Description 3-23 Parameters 3-23 Return Value 3-23 RPC Exception Error Codes 3-23 getsubscribernamebymapping 3-24 Syntax 3-24 Description 3-24 Parameters 3-24 Return Value 3-24 iv

7 Contents RPC Exception Error Codes 3-24 getsubscribernames (all) 3-25 Syntax 3-25 Description 3-25 Parameters 3-25 Return Value 3-26 RPC Exception Error Codes 3-26 Example 3-26 getsubscribernames (filter by property) 3-26 Syntax 3-27 Description 3-27 Parameters 3-27 Return Value 3-27 RPC Exception Error Codes 3-27 getsubscribernamesindomain 3-28 Syntax 3-28 Description 3-28 Parameters 3-28 Return Value 3-28 RPC Exception Error Codes 3-28 getsubscribernameswithprefix 3-29 Syntax 3-29 Description 3-29 Parameters 3-29 Return Value 3-29 RPC Exception Error Codes 3-29 getsubscribernameswithsuffix 3-30 Syntax 3-30 Description 3-30 Parameters 3-30 Return Value 3-30 RPC Exception Error Codes 3-30 getdomains 3-31 Syntax 3-31 Description 3-31 Return Value 3-31 RPC Exception Error Codes 3-31 setpropertiestodefault 3-31 Syntax 3-31 Description 3-32 v

8 Contents Parameters 3-32 Return Value 3-32 RPC Exception Error Codes 3-32 removecustomproperties 3-32 Syntax 3-32 Description 3-33 Parameters 3-33 Return Value 3-33 RPC Exception Error Codes 3-33 Quota Manager Blocking API Methods 3-33 addsubscriberquota 3-34 Syntax 3-34 Description 3-34 Parameters 3-34 RPC Exception Error Codes 3-34 setsubscriberquota 3-34 Syntax 3-35 Description 3-35 Parameters 3-35 RPC Exception Error Codes 3-35 replenishsubscriberquota 3-35 Syntax 3-35 Description 3-36 Parameters 3-36 RPC Exception Error Codes 3-36 getsubscriberquotainformation 3-36 Syntax 3-36 Description 3-36 Parameters 3-36 Return Value 3-37 RPC Exception Error Codes 3-37 getsubscriberquotaprofileid 3-37 Syntax 3-38 Description 3-38 Parameters 3-38 Return Value 3-38 RPC Exception Error Codes 3-38 getbreachedsubscribernames 3-38 Syntax 3-38 Description 3-39 vi

9 Contents Parameters 3-39 Return Value 3-39 RPC Exception Error Codes 3-39 getpenaltysubscribernames 3-39 Syntax 3-39 Description 3-39 Parameters 3-40 Return Value 3-40 RPC Exception Error Codes 3-40 Blocking API Code Examples 3-40 Getting Number of Subscribers 3-40 Adding a Subscriber, Printing Information, and Removing a Subscriber 3-41 Getting Subscriber Quota Information 3-42 CHAPTER 4 Nonblocking API 4-1 Introduction 4-1 Reliability Support 4-1 Reliable Mode 4-1 Nonreliable Mode 4-2 Autoreconnect Support 4-2 Multithreading Support 4-2 ResultHandler Interface 4-2 ResultHandler Interface Example 4-3 Nonblocking API Construction 4-4 Nonblocking API Syntax 4-4 Nonblocking API Arguments 4-4 Nonblocking API Examples 4-4 Nonblocking API Initialization 4-5 Nonblocking API Initialization Syntax 4-5 Nonblocking API Initialization Parameters 4-5 Nonblocking API Initialization Example 4-5 Nonblocking API Methods 4-6 login 4-6 Syntax 4-6 logoutbyname 4-7 Syntax 4-7 logoutbynamefromdomain 4-7 Syntax 4-7 logoutbymapping 4-7 vii

10 Contents Syntax 4-7 logincable 4-8 Syntax 4-8 logoutcable 4-8 Syntax 4-8 Nonblocking API Code Examples 4-8 Login and Logout 4-8 APPENDIX A List of Error Codes A-1 Introduction A-1 List of Error Codes A-1 viii

11 About this Guide Published: December 23, 2013, Introduction This document describes the Cisco Service Control Subscriber Manager Java API. You use the Cisco Service Control Subscriber Manager Java API to update, query, and configure the Cisco Service Control Subscriber Manager. The API has of two parts, which you can use separately or together without restriction: Cisco Service Control Subscriber Manager Nonblocking Java API High-performance API with low visibility to errors and other operation results. Supports automatic integrations with operations support (OSS) systems and authentication, authorization, and accounting (AAA) systems. Cisco Service Control Subscriber Manager Blocking Java API Supports user-interface applications for accessing and managing the Cisco Service Control Subscriber Manager. Note A set of APIs with the same functionality is also available for the C/C++ environment. This document is for networking or computer technicians who are responsible for configuring the Cisco Service Control Subscriber Manager. It is also intended for operators who manage Cisco Service Control Engine (Cisco SCE) platforms. Document Revision History The following Document Revision History table records the changes made to this document. Table 1 Revision Document Revision History Cisco Service Control Release and Date Release 4.1.x December 23, 2013 Change Summary First version of this document (new for the Release 4.1.x train). ix

12 Organization This guide contains the following sections. Table 2 Document Organization Section Title Description Chapter 1 Getting Started Describes the platforms on which you can use the Java API. This chapter also describes how to install, compile, and run the Java API component. Chapter 2 General API Concepts Describes various concepts that pertain to working with the Cisco Service Control Subscriber Manager Java API. Chapter 3 Blocking API Describes the features and operation of the blocking API and provides code examples. Chapter 4 Nonblocking API Describes the features and operation of the nonblocking API and provides code examples. Appendix A List of Error Codes Lists error codes that are used in the Java API. Related Documentation Use this document in conjunction with all the Cisco Service Control Subscriber Manager user, API, and reference guides. Conventions This document uses the following conventions. Table 3 Conventions Convention bold font italic font Indication Commands and keywords and user-entered text appear in bold font. Document titles, new or emphasized terms, and arguments for which you supply values are in italic font. [ ] Elements in square brackets are optional. {x y z Required alternative keywords are grouped in braces and separated by vertical bars. [ x y z ] Optional alternative keywords are grouped in brackets and separated by vertical bars. string A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks. courier font Terminal sessions and information the system displays appear in courier font. < > Nonprinting characters such as passwords are in angle brackets. x

13 Table 3 Conventions (continued) [ ] Default responses to system prompts are in square brackets.!, # An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line. Note Means reader take note. Tip Means the following information will help you solve a problem. Caution Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data. Timesaver Means the described action saves time. You can save time by performing the action described in the paragraph. Warning Means reader be warned. In this situation, you might perform an action that could result in bodily injury. Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: Subscribe to What s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0. xi

14 xii

15 CHAPTER 1 Getting Started Published: December 23, 2013, Introduction This chapter identifies the platforms on which you can use the Java API. The chapter also describes how to install, compile, and run the API. This chapter consists of the following sections: The Java API, page 1-1 Installing the Java API, page 1-2 Compiling and Running a Program That Uses API, page 1-4 The Java API The following sections provide information about the Java API: Introduction, page 1-1 Platforms, page 1-2 Package Content, page 1-2 Introduction The Java API enables you to update, query, and configure the Cisco Service Control Subscriber Manager. The API has two parts, which you can use separately or together without restriction. Cisco Service Control Subscriber Manager Nonblocking Java API High-performance API with low visibility to errors and other operation results. This API supports automatic integrations with OSS/AAA systems. Cisco Service Control Subscriber Manager Blocking Java API Supports user-interface applications that enable you to access and manage the Cisco Service Control Subscriber Manager. 1-1

16 Platforms Chapter 1 Getting Started Platforms The Cisco Service Control Subscriber Manager Java API was developed and tested on a Windows platform, but it is operable on any platform that supports Java Version 5.0. Package Content For brevity, <installdir> refers to the installation directory, sm-java-api-vvv.bb. The <installdir>/javadoc folder contains the API JAVADOC documentation. The <installdir>lib folder contains the smapi.jar file, which is the API executable. It also contains additional JAR files that are required to operate the API. Table 1-1 provides the layout of the installation directory. Table 1-1 Layout of Installation Directory Path Name Description <installdir> README API readme file <installdir>/javadoc index.html Index of all API specifications (API specification files, and so API specification documents on.) <installdir>/lib smapi.jar Cisco Service Control Subscriber Manager API executable asn1rt.jar Utility jar used by the API jdmkrt.jar Utility jar used by the API log4j.jar Utility jar used by the API log4j.properties Property file needed for the API logging functionalities xerces.jar Utility jar used by the API jce-jdk jar Provides an implementation of the Java Cryptography Extension API Installing the Java API The Java API is part of the Cisco Service Control Subscriber Manager Login Event Generator (LEG) distribution file and is located in the SM_API directory. The Cisco Service Control Subscriber Manager Java API is packaged in a UNIX tar file. The API is compiled with log4j 1.2. You can extract the Java API by using the UNIX tar utility or most Windows compression utilities: 1-2

17 Chapter 1 Getting Started Cisco Service Control Subscriber Manager Setup Cisco Service Control Subscriber Manager Setup, page 1-3 Installing on a UNIX Platform, page 1-3 Installing on a Windows Platform, page 1-3 Cisco Service Control Subscriber Manager Setup The API connects to the Proprietary Remote Procedure Call (PRPC) server on the Cisco Service Control Subscriber Manager. To enable the API to operate, the following conditions must be met: The Cisco Service Control Subscriber Manager must be operating, and reachable from the machine that hosts the API. The PRPC server must be started. The PRPC server is a proprietary RPC protocol designed by Cisco. For more information about the PRPC server, see the Cisco Service Control Management Suite Subscriber Manager User Guide. Installing on a UNIX Platform Note The abbreviations vvv and bb represent the Cisco Service Control Subscriber Manager Java API version and build number. To install Cisco Service Control Subscriber Manager Java API: Step 1 Step 2 Step 3 Step 4 Extract the Cisco Service Control Subscriber Manager LEG distribution file. Locate the Cisco Service Control Subscriber Manager Java API distribution tar, sm-java-api-dist.tar. Extract the Cisco Service Control Subscriber Manager Java API distribution tar and obtain sm-java-api-vvv.bb.tar. #>tar -xvf sm-java-api-dist.tar Extract the Cisco Service Control Subscriber Manager Java API package tar. #>tar -xvf sm-java-api-vvv.bb.tar Installing on a Windows Platform Use a zip extractor (such as WinZip). 1-3

18 Compiling and Running a Program That Uses API Chapter 1 Getting Started Compiling and Running a Program That Uses API To compile and run a program that uses the Cisco Service Control Subscriber Manager Java API, smapi.jar must be in the CLASSPATH. For example, if the program source is in SMApiProgram.java, use the following command to compile the program: #>javac -classpath smapi.jar SMApiProgram.java After compiling the program, use the following command to run the program: #>java -cp.;<installdir>/lib/smapi.jar SMApiProgram 1-4

19 CHAPTER 2 General API Concepts Published: December 23, 2013, Introduction This chapter describes the concepts that pertain to working with the Cisco Service Control Subscriber Manager Java API. This chapter consists of the following sections: Blocking API and the Nonblocking API, page 2-1 API Initialization, page 2-2 API Finalization, page 2-3 Subscriber Name Format, page 2-4 Network ID Mappings, page 2-4 Subscriber Domains, page 2-6 Subscriber Properties, page 2-7 Custom Properties, page 2-7 DisconnectListener Interface, page 2-7 Exceptions, page 2-8 Practical Tips, page 2-8 Blocking API and the Nonblocking API This section describes the differences between the Blocking API and the Nonblocking API. Blocking API, page 2-1 Nonblocking API, page 2-2 Blocking API In a Blocking API operation, which is the most common, every method returns after its operation is performed. 2-1

20 Nonblocking API Chapter 2 General API Concepts The Cisco Service Control Subscriber Manager Blocking Java API provides a wide range of operations. It contains most of the functionality of the Nonblocking API and many functions that the Nonblocking API does not provide. The Blocking API does not support reliability and autoreconnect functionality. Nonblocking API In a Nonblocking Java API operation, every method returns immediately, even before the completion of its operation. The operation results are either returned to an observer object (listener) or not returned at all. The Nonblocking API method is preferred when the operation is lengthy and involves I/O. When the operation is performed in a separate thread, the calling program can continue performing other tasks, which improves the overall system performance. The Cisco Service Control Subscriber Manager Nonblocking Java API contains a small number of nonblocking operations. The API supports the retrieval of operation results by using a result listener. The Cisco Service Control Subscriber Manager Nonblocking Java API supports two modes reliable and nonreliable. For more information about the reliability modes, see the Reliability Support section on page 4-1. API Initialization To initialize the API, you must complete three tasks: Construct the API by using one of its constructors. For details, see the API Construction section on page 2-2. Perform the API-specific setup operations. For details, see the Setup Operations section on page 2-3. Connect the API to the Cisco Service Control Subscriber Manager. For details, see the Connecting to the Cisco Service Control Subscriber Manager section on page 2-3. API Construction Blocking and Nonblocking APIs have two constructors: An Empty constructor A Constructor that accepts a Login Event Generator (LEG) name as a parameter. Constructor that Accepts a LEG Name Set the LEG name if you intend to turn on the Cisco Service Control Subscriber Manager LEG failure processing options in the Cisco Service Control Subscriber Manager. For more information about the LEG software components and SM-LEG failure handling, see the Cisco Service Control Management Suite Subscriber Manager User Guide. The Cisco Service Control Subscriber Manager uses the LEG name when recovering from a connection failure. A constant string that identifies the API is appended to the LEG name as follows: For blocking API.B.SM-API.J For nonblocking API.NB.SM-API.J 2-2

21 Chapter 2 General API Concepts Setup Operations Blocking API Example If the provided LEG name is my-leg version-1.0, the actual LEG name is my-leg version-1.0.b.sm-api.j. If no name is set, the LEG uses the hostname of the machine as the prefix of the name. Additional constructors are available for the Nonblocking API. For more information, see the Nonblocking API Construction section on page 4-4. Setup Operations Blocking API Setup The setup operations differ for the two APIs. Both APIs support setting a disconnect listener, which is described in detail in the DisconnectListener Interface section on page 2-7. Blocking API Setup, page 2-3 Nonblocking API Setup, page 2-3 To set up the Blocking API, you must set an operation timeout value. For more information, see Chapter 3, Blocking API. Nonblocking API Setup To set up the Nonblocking API, you must set a disconnect listener. For more details, see Chapter 4, Nonblocking API. Connecting to the Cisco Service Control Subscriber Manager To connect to the Cisco Service Control Subscriber Manager, use one of the following connect methods. Use the following method to connect to the Cisco Service Control Subscriber Manager by using the default remote procedure call (RPC) TCP port (14374): connect(string host) Use the following method to allow the caller to set the TCP port to which the API connects: connect(string host, int port) For both methods, the host parameter can be either an IP address or a reachable hostname. At any time during the API operation, you can check if the API is connected by using the isconnected method. API Finalization To free the resources of both the server and the client, use the disconnect method. Use a finally statement in your main class, as follows: public static void main(string [] args) throws Exception { 2-3

22 Subscriber Name Format Chapter 2 General API Concepts SMNonBlockingApi smnbapi = new SMNonBlockingApi(); try {... finally { smnbapi.disconnect(); Subscriber Name Format Most methods of both APIs require the subscriber name as an input parameter. A subscriber name can contain up to 64 characters. You can use all printable characters with an ASCII code between 32 and 126 (inclusive), except for 34 ("), 39 ('), and 96 (`). Network ID Mappings A network ID mapping is a network identifier that the Service Control Engine (SCE) device can map to a specific subscriber record. A typical example of a network ID mapping (or simply, mapping) is an IP address. Currently, the Cisco Service Control solution supports IP address, IP range, private IP address over VPN, private IP range over VPN, and VLAN mappings. Both Blocking and Nonblocking APIs contain operations that accept mappings as a parameter, such as the following: The addsubscriber operation (Blocking API) The login method (Blocking or Nonblocking API) When passing mappings to an API method, the caller is requested to provide two parameters: The java.lang.string mapping identifier or array of mapping types The short mapping type or array of mapping types When passing arrays, the mappingtypes array must contain either the same number of elements as the mappings array or a single element. If the mappingtypes array contains a single element, all the mappings have the same type, specified by this single element. Note Only one mapping type is allowed in a call to any of the APIs. APIs supports the following subscriber mapping types: IP addresses or IP ranges (From Cisco Service Control Subscriber Manager, Release 3.8.5) IPv6 address Private IP addresses or private IP ranges over VPN VLAN tags (From Cisco Service Control Subscriber Manager, Release 3.8.5) IPv6 addresses or IPv6 prefix For additional information, see the Cisco Service Control Management Suite Subscriber Manager User Guide. 2-4

23 Chapter 2 General API Concepts Specifying IP Address Mapping Specifying IP Address Mapping The string format of an IP address is the commonly used decimal notation: IP-Address=[0-255].[0-255].[0-255].[0-255] Example: The mapping type of an IP address is provided in the com.pcube.management.api.smapiconstants interface: com.pcube.management.api.smapiconstants.mapping_type_ip specifies a single IP mapping that matches the mapping identifier with the same index in the mapping identifier array. com.pcube.management.api.smapiconstants.all_ip_mappings specifies that all the entries in the mapping identifier array are IP mappings. Specifying IPv6 Address Mapping The string format of an IP address is the commonly used hexadecimal colon-separated notation: IPV6-Address=[0000-FFFF]:[0000-FFFF]:[0000-FFFF]:[0000-FFFF]:[0000-FFFF]:[0000-FFFF]:[0000 -FFFF]:[0000-FFFF]/[32-64] Note The prefix value of all IPv6 addresses should be between 32 and 64. Only the first 64-bit of the IPv6 address is considered. The mapping type of an IP address is provided in the com.pcube.management.api.smapiconstants interface: com.pcube.management.api.smapiconstants.mapping_type_ipv6 specifies a single IP mapping that matches the mapping identifier with the same index in the mapping identifier array. com.pcube.management.api.smapiconstants.all_ipv6_mappings specifies that all entries in the mapping identifier array are IPv6 mappings. Example: 2001:db8:85a3::8a2e:370:7334/64 Specifying IP Range Mapping The string format of an IP range is an IPv4 address in decimal notation and a decimal specifying the number of 1s in a bit mask: IP-Range=[0-255].[0-255].[0-255].[0-255]/[0-32] Examples: /32 is an IP range with a complete mask, that is, a regular IP address /24 is an IP range with a 24-bit mask, that is, all the addresses ranging between and

24 Specifying Private IP Address or Private IP Range over VPN Mapping Chapter 2 General API Concepts Note The mapping type of an IP range is identical to the mapping type of the IP address. Specifying Private IP Address or Private IP Range over VPN Mapping The string format of an IPv4 address and an IP range are described in the Specifying IP Address Mapping section on page 2-5 and in the Specifying IP Range Mapping section on page 2-5. When the network ID mapping uses an IP address or range over VPN, the string format includes the VPN name. Examples: @VPN1 is an IP address over the VPN named VPN /24@VPN2 is an IP range with a 24-bit mask, that is, all of the addresses in the range from to over the VPN named VPN2. Note The mapping type of an IP address or IP range over VPN is identical to the mapping type of the IP address. Specifying VLAN Tag Mapping The string format for VLAN tag mapping is VLAN-tag = 0 to The value is a decimal in the specified range. The com.pcube.management.api.smapiconstants interface also provides the mapping type: com.pcube.management.api.smapiconstants.mapping_type_vpn specifies a single VLAN mapping that matches the mapping identifier with the same index in the mapping identifier array. com.pcube.management.api.smapiconstants.all_vpn_mappings specifies that all the entries in the mapping identifiers array are VLAN mappings. Note The SMApiConstants.TYPE_VLAN and SMApiConstants.ALL_VLAN_MAPPINGS constants are deprecated. You should use the SMApiConstants.TYPE_VPN and SMApiConstants.ALL_VPN_MAPPINGS constants instead. Subscriber Domains The Cisco Service Control Management Suite Subscriber Manager User Guide defines the domain concept. Briefly, a domain identifies for the Cisco Service Control Subscriber Manager the Cisco SCE devices to which it updates subscriber records. A domain name is a type of String. During system installation, the network administrator determines the system domain names, which, therefore, vary between installations. The APIs include methods that specify the domain to which a subscriber belongs. The APIs also provide methods that enable queries about system domain names. If an API operation specifies a domain name that does not exist in the Cisco Service Control Subscriber Manager domain repository, it is considered an error and RpcErrorException is returned. 2-6

25 Chapter 2 General API Concepts Subscriber Properties The Cisco Service Control Subscriber Manager automatic domain roaming feature enables you to move subscribers between domains by calling the login method for a subscriber with an updated domain parameter as described in the login section on page 3-4. Note Automatic domain roaming is not backward compatible with previous versions of the Cisco Service Control Subscriber Manager API. Previous versions did not permit changing the domain of the subscriber. Subscriber Properties Several operations manipulate subscriber properties. A subscriber property is a key/value pair that affects the way the Cisco SCE analyzes and reacts to network traffic generated by the subscriber. For information about properties, see the Cisco Service Control Management Suite Subscriber Manager User Guide and the Cisco Service Control Application for Broadband User Guide. The latter provides application-specific information; it lists the subscriber properties that exist in the application running on your system, the allowed value set, and the significance of each property value. To format subscriber properties for Java API operations, use the String arrays propertykeys and propertyvalues. Note The arrays must be of the same length, and NULL entries are forbidden. Each key in the keys array has a matching entry in the values array; the value for propertykeys[j] resides in propertyvalues[j]. The mapping type of an IP range is identical to the mapping type of the IP address. Example: If the property keys array is {"packageid","monitor" and the property values array is {"5","1", the properties are packageid=5, monitor=1. Custom Properties Some operations manipulate custom properties. Custom properties are similar to subscriber properties, but do not affect how the SCE analyzes and manipulates the subscriber traffic. The application management modules use custom properties to store additional information for each subscriber. To format custom properties, use the String arrays custompropertykeys and custompropertyvalues. This formatting is the same as in the subscriber properties formatting described in the Subscriber Properties section on page 2-7. DisconnectListener Interface Both APIs (Blocking and Nonblocking) enable you to set a disconnect listener. The disconnect listener is an interface with a single method: public interface DisconnectListener { /** * called when the connection with the server is down. */ 2-7

26 DisconnectListener Interface Example Chapter 2 General API Concepts public void connectionisdown(); Implement this interface to be notified when the API is disconnected from the Cisco Service Control Subscriber Manager. To set a disconnect listener, use the setdisconnectlistener method. DisconnectListener Interface Example The following example is a basic implementation of a disconnect listener that prints a message to stdout and exits: import com.pcube.management.framework.rpc.disconnectlistener; public class MyDisconnectListener implements DisconnectListener { public void connectionisdown(){ System.out.println("Message: connection is down."); System.exit(0); Exceptions The same Java class, com.pcube.management.framework.rpc.rpcerrorexception, provides all of the functional errors of the Cisco Service Control Subscriber Manager Java API. This is contrary to the normal Java usage. This approach was chosen because of the cross-language nature of the Cisco Service Control Subscriber Manager API. It enables all Cisco Service Control Subscriber Manager API implementations (Java, C, and C++) to appear similar. Each exception provides the following information: Unique error code (long) Informative message (java.lang.string) Server-side stack trace (java.lang.string) The error code can be interpreted by using com.pcube.management.api.smapiconstants. See Appendix A, List of Error Codes for details about error codes and their significance. Note Several types of errors can occur only if you use the Blocking API. These are operational errors that are related to operation-timeout handling. These errors are described in Chapter 3, Blocking API. Practical Tips When implementing the code that integrates the API with your application, consider the following practical tips: Connect to the Cisco Service Control Subscriber Manager once and maintain an open API connection to the Cisco Service Control Subscriber Manager at all times, using the API many times. Establishing a connection is a timely procedure, which allocates resources on the Cisco Service Control Subscriber Manager side and the API client side. 2-8

27 Chapter 2 General API Concepts Practical Tips Share the API connection between your threads. It is best to have one connection per LEG. Multiple connections require more resources on the Cisco Service Control Subscriber Manager side and client side. Do not implement synchronization of the calls to the API. The client automatically synchronizes calls to the API. Place the API clients (LEGs) in the same order as the Cisco Service Control Subscriber Manager machine processor number. If the LEG application has bursts of login operations, enlarge the internal buffer size accordingly to hold these bursts (Nonblocking API). During the integration, set the Cisco Service Control Subscriber Manager logon_logging_enabled configuration parameter to enable viewing the API operations in the Cisco Service Control Subscriber Manager log. Setting this parameter enables you to troubleshoot the integration, if any problems arise. Use the debug mode for the LEG application that logs the return values of the nonblocking operations. Use the automatic reconnect feature to improve the resiliency of the connection to the Cisco Service Control Subscriber Manager. In cluster setups, connect the API by using the virtual IP address of the cluster and not the management IP address of one of the machines. 2-9

28 Practical Tips Chapter 2 General API Concepts 2-10

29 CHAPTER 3 Blocking API Published: December 23, 2013, Introduction This chapter introduces the Reply Timeout, a feature unique to the Blocking API. The chapter also lists all the operations of the Blocking API, and provides code examples. Note If you need to develop only an automatic integration, skip this chapter and go directly to Chapter 4, Nonblocking API. This chapter consists of the following sections: Multithreading Support, page 3-1 ReplyTimeout and OperationTimeout Exception, page 3-2 Cisco Service Control Subscriber Manager Blocking API Methods, page 3-2 Quota Manager Blocking API Methods, page 3-33 Blocking API Code Examples, page 3-40 Multithreading Support The Blocking API supports an 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 might be performed before operation-0, as shown in Figure 3-1 (the vertical scale is time): 3-1

30 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 Cisco Service Control Subscriber Manager allocates five threads to manage each API instance. 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 is retrieved from the Cisco Service Control Subscriber Manager. If a networking malfunction or other error prevents the operation result from being retrieved, the caller waits indefinitely. The Cisco Service Control Subscriber Manager API provides a means of working around this situation. The reply timeout feature (the setreplytimeout method) enables the caller to set a timeout. It will generate 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, stop responding) 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; java.lang.interruptedexception will then be returned to the caller. Cisco Service Control Subscriber Manager Blocking API Methods This section lists the methods of the Cisco Service Control Subscriber Manager Blocking API. The description of each method includes its syntax, input parameters, and return values. 3-2

31 Chapter 3 Blocking API Cisco Service Control Subscriber Manager Blocking API Methods 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 generate java.lang.illegalstateexception when called before the API establishes a connection with the Cisco Service Control Subscriber Manager. The Blocking API methods are classified as follows: Dynamic IP and property allocation Use the following methods to integrate the Cisco Service Control Subscriber Manager API with an authentication, authorization, and accounting (AAA) system. These methods are not designed to add or remove subscribers from the database. Instead, they 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 or Manual Subscriber configuration Use the following methods for a GUI: addsubscriber, page 3-15 removesubscriber, page 3-17 removeallsubscribers, page 3-18 setpropertiestodefault, page 3-31 removecustomproperties, page 3-32 Use the following methods for simple read-only operations, performed independently in the subscriber awareness mode: getnumberofsubscribers, page 3-19 getnumberofsubscribersindomain, page 3-19 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-26 getsubscribernamesindomain, page 3-28 getsubscribernameswithprefix, page 3-29 getsubscribernameswithsuffix, page 3-30 getdomains, page 3-31 You can mix methods from different categories in a single application. The classification is presented only for clarity. 3-3

32 login Chapter 3 Blocking API login The following sections provide information about the login operation: Syntax, page 3-4 Description, page 3-4 Parameters, page 3-4 RPC Exception Error Codes, page 3-5 Return Value, page 3-5 Examples, page 3-5 Syntax The login syntax is as follows: public void login(string subscribername, String[] mappings, short[] mappingtypes, String[] propertykeys, String[] propertyvalues, String domain, boolean ismappingadditive, int autologouttime) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The login method adds or modifies a domain, mappings, and possibly properties of a subscriber that already exists in the Cisco Service Control Subscriber Manager database. The login method can be called with partial data; for example, it might provide mappings or properties only, and put NULL ++++ in the unchanged fields. If another subscriber with the same (or conflicting) mappings already exists in the same domain, the conflicting mappings are removed from the other subscriber and assigned to the new subscriber. If the subscriber does not exist in the Cisco Service Control Subscriber Manager database, the login method creates it with the data provided. Parameters The parameters of the login method are as follows: subscribername See the description of subscriber name formatting in the Subscriber Name Format section on page 2-4. mappings See the description of mappings and mapping types in the Network ID Mappings section on page 2-4. If no mappings are specified, and the ismappingadditive parameter is TRUE, the previous mappings are retained. If no such mappings exist, the operation fails. mappingtypes See the description of mappings and mapping types in the Network ID Mappings section on page 2-4. propertykeys See the description of property keys in the Subscriber Properties section on page

33 Chapter 3 Blocking API login RPC Exception Error Codes Return Value propertyvalues See the description of property values in the Subscriber Properties section on page 2-7. domain See the description 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 from the domain that was previously assigned to the subscriber, the subscriber is removed automatically from the Cisco 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. autologouttime Applies only to the mappings provided as arguments to this method. Positive value (N) Automatically logs out the mappings (similar to calling a logout method) after N seconds. 0 value Maintains the current expiration time for the given mappings. Negative value Disables any expiration time set for the given mappings. The following list presents the error codes the login 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 parameter settings: NULL value for the domain parameter for the subscriber that does not exist or does not have a domain Invalid values for the 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", new String[]{" ", SMApiConstants.ALL_IP_MAPPINGS, // subscriber name 3-5

34 login Chapter 3 Blocking API 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 To extend the auto logout time of , which 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 to 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); To add the IPv6 address 2000:2001:2002:abcd::/64 to an existing subscriber named alpha without affecting existing mappings: login( "alpha", // subscriber name new String[]{"2000:2001:2002:abcd::/64", SMApiConstants.ALL_IPV6_MAPPINGS, null, null, "subscribers", // domain true, // ismappingadditive is true -1); // autologouttime set to infinite To add the IPv6 address 2000:2001:2002:abcd::/64 overriding previous mappings: login( 3-6

35 Chapter 3 Blocking API logoutbyname "alpha", // subscriber name new String[]{"2000:2001:2002:abcd::/64", SMApiConstants.ALL_IPV6_MAPPINGS, null, null, "subscribers", // domain false, // ismappingadditive is false -1); // autologouttime set to infinite To extend the auto logout time of 2000:2001:2002:abcd::/64 that was previously assigned to alpha: login( "alpha", //the previously assigned IP new String[]{"2000:2001:2002:abcd::/64", SMApiConstants.ALL_IPV6_MAPPINGS, null, null, "subscribers", // domain false, // ismappingadditive 300); // autologouttime set to 300 seconds To add the IPv6 address 2000:2001:2002:abcd::/64 to an existing subscriber named alpha without affecting the existing mappings, and to modify a dynamic property of alpha,for example, package ID: login( "alpha", new String[]{"2000:2001:2002:abcd::/64", SMApiConstants.ALL_IPV6_MAPPINGS, new String[]{"packageId", // property key new String[]{"10", // property value "subscribers", // domain true, // ismappingadditive is set to true -1); logoutbyname Syntax The following sections provide information about the logoutbyname operation: Syntax, page 3-7 Description, page 3-8 Parameters, page 3-8 Return Value, page 3-8 RPC Exception Error Codes, page 3-8 Examples, page 3-8 The logoutbyname syntax is as follows: public boolean logoutbyname(string subscribername, String[] mappings, short[] mappingtypes) throws InterruptedException, OperationTimeoutException, RpcErrorException 3-7

36 logoutbyname Chapter 3 Blocking API Description The logoutbyname method locates the subscriber in the database and removes mappings from it. If the subscriber does not exist, the logoutbyname operation does not do anything. Parameters The parameters of the logoutbyname method are as follows: subscribername See the description of subscriber name formatting in the Subscriber Name Format section on page 2-4. mappings See the description of mappings in the Network ID Mappings section on page 2-4. If no mappings are specified, all subscriber mappings are removed. mappingtypes See the description of mapping types in the Network ID Mappings section on page 2-4. Return Value RPC Exception Error Codes Examples TRUE If the subscriber was found and the subscriber mappings were removed from the subscriber database FALSE If the subscriber was not found in the subscriber database The following list presents the error codes the logoutbyname 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

37 Chapter 3 Blocking API logoutbynamefromdomain logoutbynamefromdomain Syntax The following sections provide information about the logoutbynamefromdomain operation: Syntax, page 3-9 Description, page 3-9 Parameters, page 3-9 Return Value, page 3-9 RPC Exception Error Codes, page 3-10 Example, page 3-10 The logoutbynamefromdomain syntax is as follows: public boolean logoutbynamefromdomain(string subscribername, String[] mappings, short[] mappingtypes, String domain) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The logoutbynamefromdomain similar to logoutbyname, but this method also enables the caller to provide the name of the domain to which the subscriber belongs. When the subscriber domain is known, use this method to improve performance. Parameters Return Value The parameters of the logoutbynamefromdomain method are as follows: subscribername See the description of subscriber name formatting in the Subscriber Name Format section on page 2-4. mappings See the description of mappings in the Network ID Mappings section on page 2-4. If no mappings are specified, all subscriber mappings are removed. mappingtypes See the description of mapping types in the Network ID Mappings section on page 2-4. domain See the description 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

38 logoutbymapping Chapter 3 Blocking API RPC Exception Error Codes Example The following list presents error codes the logoutbynamefromdomain 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 Syntax The following sections provide information about the logoutbymapping operation: Syntax, page 3-10 Description, page 3-11 Parameters, page 3-11 Return Value, page 3-11 RPC Exception Error Codes, page 3-11 Example, page 3-11 The logoutbymapping syntax is as follows: public boolean logoutbymapping(string mapping, short mappingtype, String domain) throws InterruptedException, OperationTimeoutException, RpcErrorException 3-10

39 Chapter 3 Blocking API logoutbymapping Description The logoutbymapping locates a subscriber based on domain and mapping, and removes the mapping (the subscriber stays in the database). Parameters The parameters of the logoutbymapping method are as follows: mapping See the description of mappings in the Network ID Mappings section on page 2-4. mappingtype See the description of mapping types in the Network ID Mappings section on page 2-4. domain See the description of the logoutbynamefromdomain operation in the Parameters section on page 3-9. Return Value RPC Exception Error Codes 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 list presents error codes the logoutbymapping 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"); To remove IPv6 address 2001:db8:85a3::8a2e:370:7334/64 from domain subscribers: boolean isexist = logoutbymapping( "2001:db8:85a3::8a2e:370:7334/64", SMApiConstants. MAPPING_TYPE_IPV6, "subscribers"); 3-11

40 logincable Chapter 3 Blocking API logincable The following sections provide information about the logincable operation: Syntax, page 3-12 Description, page 3-12 Parameters, page 3-12 Return Value, page 3-13 RPC Exception Error Codes, page 3-13 Examples, page 3-13 Syntax The logincable syntax is as follows: public void logincable(string CPE, String CM, String IP, int lease, String domain, String[] propertykeys, String[] propertyvalues) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The logincable method is an operation adapted for the cable environment; it calls the cable support module in the Cisco Service Control Subscriber Manager. This method is designed to log in the customer premise equipment (CPE) and content managers to the Cisco Service Control Subscriber Manager. To log in a CPE, specify its cable modem (CM) MAC in the CM argument and the CPE MAC in the CPE argument. To log in a cable modem, specify the cable modem MAC address in both CPE and CM arguments. Note that the login of a CPE whose CM does not exist in the Cisco Service Control Subscriber Manager 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 Cisco Service Control Subscriber Manager database is the concatenation of the CPE and CM values with two underscore characters ( _ ) between them. The caller must ensure that the lengths of CPE and CM add up to no more than 38 characters. Parameters The parameters of the logincable method are as follows: 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 (IPv4 address or IPv6 address) lease CPE lease time 3-12

41 Chapter 3 Blocking API logincable domain See the description of the subscriber domains in the Subscriber Domains section on page 2-6. The domain is usually cable modem termination system (CMTS) IP. Note Domain aliases must be set on the Cisco Service Control Subscriber Manager so that the cable modem termination system (CMTS) IP is correctly interpreted as a domain name. For information about configuring aliases, see the Default Domains Configuration section of Cisco SCMS Subscriber Manager User Guide. propertykeys See the description of property keys 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 cable modem to which this CPE belongs. Each cable modem application property thus serves as a default for the CPE with which it is associated. propertyvalues See the description of property values in the Subscriber Properties section on page 2-7. Return Value None. RPC Exception Error Codes None. Examples To add the IP address to a cable modem called CM1 with two hours of 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 a lease time of one hour: logincable( "CPE1", "CM1", " ", 3600, // lease time in seconds "subscribers", null, null); To add the IPv6 address 2001:db8:85a3::8a2e:370:7334/64 to a cable modem called CM1 with two hours of lease time: logincable( "CM1", "CM1", "2001:db8:85a3::8a2e:370:7334/64", 7200, // lease time in seconds 3-13

42 logoutcable Chapter 3 Blocking API "subscribers", null, null); logoutcable The following sections provide information about the logoutcable operation: Syntax, page 3-14 Description, page 3-14 Parameters, page 3-14 Return Value, page 3-14 RPC Exception Error Codes, page 3-14 Example, page 3-15 Syntax The logoutcable syntax is as follows: public boolean logoutcable(string CPE, String CM, String IP, String domain) Description The logoutcable method indicates to the Cisco Service Control Subscriber Manager cable support module that a logout event has happened. Parameters The parameters of the logoutcable method are as follows: CPE See the description in the Parameters section on page CM See the description in the Parameters section on page IP See the description in the Parameters section on page domain See the description in the Parameters section on page Return Value RPC Exception Error Codes TRUE If the CPE was found and removed from the subscriber database FALSE If the CPE was not found in the subscriber database None. 3-14

43 Chapter 3 Blocking API addsubscriber Example To remove the IP address from CPE1, which is associated with CM1: boolean isexist = logoutcable( "CPE1", "CM1", " ", "subscribers"); addsubscriber Syntax The following sections provide information about the addsubscriber operation: Syntax, page 3-15 Description, page 3-15 Example, page 3-16 Parameters, page 3-16 Return Value, page 3-16 RPC Exception Error Codes, page 3-16 Examples, page 3-17 The addsubscriber syntax is as follows: public void addsubscriber(string subscribername, String[] mappings, short[] mappingtypes, String[] propertykeys, String[] propertyvalues, String[] custompropertykeys, String[] custompropertyvalues, String domain) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The addsubscriber method creates a new subscriber record according to the method parameters and adds the record to the Cisco Service Control Subscriber Manager database. When adding a new subscriber name, if the name already exists in Cisco Service Control Subscriber Manager database, the first instance of the name is removed before the new one is added. In contrast to login method, which modifies fields and leaves unspecified fields unchanged, the addsubscriber method sets the subscriber exactly as specified by the parameters passed to it. Note Use the call login method for existing subscribers, instead of the addsubscriber command. You should set dynamic mappings and properties by using the login command. Set static mappings and properties the first time the subscriber is created by using the addsubscriber command. 3-15

44 addsubscriber Chapter 3 Blocking API Note With the addsubscriber command, the autologout feature is always disabled. To enable autologout, use the login command. 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 does not change the subscriber mappings of AB; AB retains its previous IP mapping of IP1. Parameters The parameters of the addsubscriber method are as follows: subscribername See the description in the Subscriber Name Format section on page 2-4. mappings See the description in the Network ID Mappings section on page 2-4. mappingtypes See the description of mapping types in the Network ID Mappings section on page 2-4. propertykeys See the description of property keys in the Subscriber Properties section on page 2-7. propertyvalues See the description of property values in the Subscriber Properties section on page 2-7. custompropertykeys See the description of custom property keys in the Custom Properties section on page 2-7. custompropertyvalues See the description of custom property values in the Custom Properties section on page 2-7. domain See the description of subscriber domains in the Subscriber Domains section on page 2-6. A NULL value indicates that the subscriber has no domain. If domain is NULL, but the subscriber already has a domain, the existing domain is retained. Return Value None. RPC Exception Error Codes The following list presents error codes that the addsubscriber method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE_SUBSCRIBER_ALREADY_EXISTS 3-16

45 Chapter 3 Blocking API removesubscriber ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION ERROR_CODE_UNKNOWN This error code might indicate invalid values that were supplied for the propertyvalues parameter. ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. Examples The following example code adds 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 Syntax The following sections provide information about the removesubscriber operation: Syntax, page 3-17 Description, page 3-17 Parameters, page 3-17 Return Value, page 3-18 RPC Exception Error Codes, page 3-18 Example, page 3-18 The removesubscriber syntax is as follows: public boolean removesubscriber(string subscribername) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The removesubscriber method removes a subscriber completely from the Cisco Service Control Subscriber Manager database. Parameters The only parameter of the removesubscriber method is as follows: subscribername See the description in the Subscriber Name Format section on page

46 removeallsubscribers Chapter 3 Blocking API Return Value RPC Exception Error Codes 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 list presents error codes that the removesubscriber method 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. The following example code removes subscriber alpha entirely from the database: boolean isexist = removesubscriber("alpha"); removeallsubscribers Syntax The following sections provide information about the removeallsubscribers operation: Syntax, page 3-18 Description, page 3-18 Return Value, page 3-18 RPC Exception Error Codes, page 3-19 The removeallsubscribers syntax is as follows: public void removeallsubscribers() throws InterruptedException, OperationTimeoutException, RpcErrorException Description The removeallsubscribers method removes all subscribers from the Cisco Service Control Subscriber Manager, leaving the database with no subscribers. Note This method might take time to execute. To avoid operation timeout exceptions, set a high operation timeout (up to 5 minutes) before calling this method. Return Value None. 3-18

47 Chapter 3 Blocking API getnumberofsubscribers RPC Exception Error Codes None. getnumberofsubscribers Syntax The following sections provide information about the getnumberofsubscribers operation: Syntax, page 3-19 Description, page 3-19 Return Value, page 3-19 RPC Exception Error Codes, page 3-19 The getnumberofsubscribers syntax is as follows: public int getnumberofsubscribers() throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getnumberofsubscribers method retrieves the total number of subscribers in the Cisco Service Control Subscriber Manager database. Return Value The number of subscribers in the Cisco Service Control Subscriber Manager. RPC Exception Error Codes None. getnumberofsubscribersindomain Syntax The following sections provide information about the getnumberofsubscribersindomain operation: Syntax, page 3-19 Description, page 3-20 Parameters, page 3-20 Return Value, page 3-20 RPC Exception Error Codes, page 3-20 The getnumberofsubscribersindomain syntax is as follows: 3-19

48 getsubscriber Chapter 3 Blocking API public int getnumberofsubscribersindomain(string domain) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getnumberofsubscribersindomain method retrieves the number of subscribers in a subscriber domain. Parameters The only parameter of the getnumberofsubscribersindomain method is as follows: domain Name of a subscriber domain that exists in the Cisco Service Control Subscriber Manager domain repository. Return Value The number of subscribers in the provided domain. RPC Exception Error Codes The following list presents the error codes that the getnumberofsubscribersindomain 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 Syntax The following sections provide information about the getsubscriber operation: Syntax, page 3-20 Description, page 3-21 Parameters, page 3-21 Return Value, page 3-21 RPC Exception Error Codes, page 3-21 Example, page 3-21 The getsubscriber syntax is as follows: public Object[] getsubscriber(string subscribername) throws InterruptedException, OperationTimeoutException, RpcErrorException 3-20

49 Chapter 3 Blocking API getsubscriber Description The getsubscriber method retrieves a subscriber record. Each field is formatted as an integer, string, or string array. If the subscriber does not exist in the Cisco Service Control Subscriber Manager database, the operation returns an exception. Parameters The only parameter of the getsubscriber method is as follows: subscribername See the description in the Subscriber Name Format section on page 2-4. Return Value An object array with nine elements. Table 3-1 lists the index values and descriptions. No array element has a NULL value. Table 3-1 Indexes and Descriptions Index Value Index 0 Index 1 Index 2 Index 3 Index 4 Index 5 Index 6 Index 7 Index 8 Description 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, in seconds from the present time, or -1 if not set (long[]) RPC Exception Error Codes Example The following list presents error codes that the getsubscriber method 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. The following example code retrieves the subscriber record of alpha: 3-21

50 subscriberexists Chapter 3 Blocking API 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 Syntax The following sections provide information about the subscriberexists operation: Syntax, page 3-22 Description, page 3-22 Parameters, page 3-22 Return Value, page 3-22 RPC Exception Error Codes, page 3-22 The subscriberexists syntax is as follows: public boolean subscriberexists(string subscribername) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The subscriberexists method verifies that a subscriber exists in the Cisco Service Control Subscriber Manager database. Parameters Return Value RPC Exception Error Codes The only parameter of the subscriberexists method is as follows: subscribername See the description in the Subscriber Name Format section on page 2-4. TRUE If the subscriber was found in the Cisco Service Control Subscriber Manager database. FALSE If the subscriber was not found. None. 3-22

51 Chapter 3 Blocking API subscriberloggedin subscriberloggedin Syntax The following sections provide information about the subscriberloggedin operation: Syntax, page 3-23 Description, page 3-23 Parameters, page 3-23 Return Value, page 3-23 RPC Exception Error Codes, page 3-23 The subscriberloggedin syntax is as follows: public boolean subscriberloggedin(string subscribername) throws InterruptedException, OperationTimeoutException, RpcErrorException Description Parameters Return Value RPC Exception Error Codes The subscriberloggedin method checks whether a subscriber that already exists in the Cisco Service Control Subscriber Manager database is logged in, that is, if the subscriber also exists in a Cisco SCE database. When the Cisco Service Control Subscriber Manager 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 Cisco Service Control Subscriber Manager database, an exception is generated. The only parameter of the subscriberloggedin method is as follows: subscribername See the description 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 list presents error codes that the subscriberloggedin 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

52 getsubscribernamebymapping Chapter 3 Blocking API getsubscribernamebymapping Syntax The following sections provide information about the getsubscribernamebymapping operation: Syntax, page 3-24 Description, page 3-24 Parameters, page 3-24 Return Value, page 3-24 RPC Exception Error Codes, page 3-24 The getsubscribernamebymapping syntax is as follows: public String getsubscribernamebymapping(string mapping, short mappingtype, String domain) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getsubscribernamebymapping method finds a subscriber name according to a mapping and a domain. Parameters Return Value RPC Exception Error Codes The parameters of the getsubscribernamebymapping method are as follows: mapping See the description of mappings in the Network ID Mappings section on page 2-4. mappingtype See the description of mapping types in the 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. The specified domain is incorrect. Subscriber name If a subscriber record was found. NULL If no subscriber record was found. The following list presents error codes that the getsubscribernamebymapping method might return: ERROR_CODE_DOMAIN_NOT_FOUND ERROR_CODE _BAD_SUBSCRIBER_MAPPING ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN 3-24

53 Chapter 3 Blocking API getsubscribernames (all) ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. getsubscribernames (all) Syntax The following sections provide information about the getsubscribernames (all) operation: Syntax, page 3-25 Description, page 3-25 Parameters, page 3-25 Return Value, page 3-26 RPC Exception Error Codes, page 3-26 Example, page 3-26 The getsubscribernames (all) syntax is as follows: public String[] getsubscribernames(string lastbulkend, int numofsubscribers) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getsubscribernames (all) method retrieves a bulk of subscriber names from the Cisco Service Control Subscriber Manager database, starting with lastbulkend followed by numofsubscribers (in alphabetical order). If lastbulkend is NULL, the first subscriber name (alphabetically) that exists in the Cisco Service Control Subscriber Manager database is retrieved. 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 might differ if some subscribers are added or removed when the bulks are being retrieved. Parameters The parameters of the getsubscribernames (all) method are as follows: 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 Cisco Service Control Subscriber Manager limit (1000), the operation uses the Cisco Service Control Subscriber Manager limit. Note Do not provide a value of more than 500 subscribers. 3-25

54 getsubscribernames (filter by property) Chapter 3 Blocking API Return Value RPC Exception Error Codes Example An array of subscriber names, alphabetically ordered. The getsubscribernames (all) method returns as many subscribers as are found in the Cisco Service Control Subscriber Manager database, starting at the requested subscriber. The array size is limited by the smaller of these values numofsubscribers or the Cisco Service Control Subscriber Manager limit (1000). The following list presents error codes that the getsubscribernames (all) 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. The following example code returns an array of subscriber names: 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); getsubscribernames (filter by property) The following sections provide information about the getsubscribernames (filter by property) operation: Syntax, page 3-27 Description, page 3-27 Parameters, page 3-27 Return Value, page 3-27 RPC Exception Error Codes, page

55 Chapter 3 Blocking API getsubscribernames (filter by property) Syntax The getsubscribernames (filter by property) method syntax is as follows: public String[] getsubscribernames(string lastbulkend,string propertyname,string propertyvalue,int numofsubscribers) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getsubscribernames (filter by property) method retrieves a bulk of subscriber names from the Cisco Service Control Subscriber Manager database, starting with lastbulkend followed by numofsubscribers (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 Cisco Service Control Subscriber Manager database is retrieved. 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 might differ if some subscribers are added or removed when the bulks are being retrieved. Parameters The parameters of the getsubscribernames (filter by property) method are as follows: 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 the number of subscribers that is returned. If this value is higher than the Cisco Service Control Subscriber Manager limit (1000), the operation uses the Cisco Service Control Subscriber Manager limit. Note Do not provide a value of more than 500 subscribers. Return Value An array of alphabetically ordered subscriber names that matches the property name and its given value. The method returns as many subscribers as are found in the Cisco Service Control Subscriber Manager database, starting at the requested subscriber. The array size is limited by the smaller of these values numofsubscribers or the Cisco Service Control Subscriber Manager limit (1000). RPC Exception Error Codes The following list presents error codes that the getsubscribernames (filter by property) method might return: ERROR_CODE_DATABASE_EXCEPTION ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME 3-27

56 getsubscribernamesindomain Chapter 3 Blocking API For a description of error codes, see Appendix A, List of Error Codes. getsubscribernamesindomain Syntax The following sections provide information about the getsubscribernamesindomain operation: Syntax, page 3-28 Description, page 3-28 Parameters, page 3-28 Return Value, page 3-28 RPC Exception Error Codes, page 3-28 The getsubscribernamesindomain syntax is as follows: public String[] getsubscribernamesindomain(string lastbulkend, int numofsubscribers, String domain) throws InterruptedException, OperationTimeoutException, RpcErrorException Description Parameters Return Value RPC Exception Error Codes The getsubscribernamesindomain method retrieves subscribers in the Cisco Service Control Subscriber Manager database that are associated with the specified domain. The semantics of this operation are the same as that of the getsubscribernames operation described in the getsubscribernames (all) section on page The parameters of the getsubscribernamesindomain method are as follows: lastbulkend See the description in the Parameters section on page numofsubscribers See description in the Parameters section on page domain The name of a subscriber domain that exists in the Cisco Service Control Subscriber Manager domain repository. An alphabetically ordered array of subscriber names that belong to the domain provided. See the Return Value section on page 3-26 (the getsubscribernames (all) operation). The following list presents the error codes that the getsubscribernamesindomain method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE _DOMAIN_NOT_FOUND 3-28

57 Chapter 3 Blocking API getsubscribernameswithprefix ERROR_CODE_DATABASE_EXCEPTION For a description of error codes, see Appendix A, List of Error Codes. getsubscribernameswithprefix Syntax The following sections provide information about the getsubscribernameswithprefix operation: Syntax, page 3-29 Description, page 3-29 Parameters, page 3-29 Return Value, page 3-29 RPC Exception Error Codes, page 3-29 The getsubscribernameswithprefix syntax is as follows: public String[] getsubscribernameswithprefix(string lastbulkend, int numofsubscribers, String prefix) throws InterruptedException, OperationTimeoutException, RpcErrorException Description Parameters Return Value RPC Exception Error Codes The getsubscribernameswithprefix method retrieves subscribers in the Cisco Service Control Subscriber Manager database whose name begins with a specified prefix. The semantics of this operation are the same as that of the getsubscribernames operation described in the getsubscribernames (all) section on page The parameters of the getsubscribernameswithprefix method are as follows: lastbulkend See the description in the Parameters section on page numofsubscribers See the description in the Parameters section on page prefix Case-sensitive string that marks the prefix of the required subscriber names. An alphabetically ordered array of subscriber names that begin with the required prefix. See, the Return Value section on page The following list presents error codes that the getsubscribernameswithprefix method might return: ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME ERROR_CODE_DATABASE_EXCEPTION 3-29

58 getsubscribernameswithsuffix Chapter 3 Blocking API For a description of error codes, see Appendix A, List of Error Codes. getsubscribernameswithsuffix Syntax The following sections provide information about the getsubscribernameswithsuffix operation: Syntax, page 3-30 Description, page 3-30 Parameters, page 3-30 Return Value, page 3-30 RPC Exception Error Codes, page 3-30 The getsubscribernameswithsuffix syntax is as follows: public String[] getsubscribernameswithsuffix(string lastbulkend, int numofsubscribers, String suffix) throws InterruptedException, OperationTimeoutException, RpcErrorException Description Parameters Return Value RPC Exception Error Codes The getsubscribernameswithsuffix method retrieves subscribers in the Cisco Service Control Subscriber Manager database whose names end with the specified suffix. The semantics of this operation are the same as that of the getsubscribernames (all) operation described in the getsubscribernames (all) section on page The parameters of the getsubscribernameswithsuffix method are as follows: lastbulkend See the description in the Parameters section on page numofsubscribers See the description in the Parameters section on page suffix Case-sensitive string that represents the suffix of the required subscriber names. An alphabetically ordered array of subscriber names that end with the required suffix. See, the Return Value section on page 3-26 (the getsubscribernames (all) operation). The following list presents error codes that the getsubscribernameswithsuffix 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-30

59 Chapter 3 Blocking API getdomains getdomains The following sections provide information about the getdomains operation: Syntax, page 3-31 Description, page 3-31 Return Value, page 3-31 RPC Exception Error Codes, page 3-31 Syntax The getdomains syntax is as follows: public String[] getdomains() throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getdomains method provides the list of current subscriber domains in the Cisco Service Control Subscriber Manager domain repository. Return Value A complete list of subscriber domain names in the Cisco Service Control Subscriber Manager. RPC Exception Error Codes None. setpropertiestodefault Syntax The following sections provide information about the setpropertiestodefault operation: Syntax, page 3-31 Description, page 3-32 Parameters, page 3-32 Return Value, page 3-32 RPC Exception Error Codes, page 3-32 The setpropertiestodefault syntax is as follows: public void setpropertiestodefault(string subscribername, String[] properties) throws InterruptedException, OperationTimeoutException, RpcErrorException 3-31

60 removecustomproperties Chapter 3 Blocking API Description The setpropertiestodefault method resets the specified application properties of a subscriber. If an application is installed, the relevant application properties are set to the default values of the properties according to the currently loaded application information. If an application is not installed, the operation returns java.lang.illegalstateexception. Parameters The parameters of the setpropertiestodefault method are as follows: subscribername See the description of subscriber name formatting in the Subscriber Name Format section on page 2-4. properties See the description of property keys and values in the Subscriber Properties section on page 2-7. Return Value None. RPC Exception Error Codes The following list presents error codes that the setpropertiestodefault 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. removecustomproperties Syntax The following sections provide information about the removecustomproperties operation: Syntax, page 3-32 Description, page 3-33 Parameters, page 3-33 Return Value, page 3-33 RPC Exception Error Codes, page 3-33 The removecustomproperties syntax is as follows: public void removecustomproperties(string subscribername, String[] customproperties) 3-32

61 Chapter 3 Blocking API Quota Manager Blocking API Methods throws InterruptedException, OperationTimeoutException, RpcErrorException Description The removecustomproperties method resets the specified custom properties of a subscriber. Parameters The parameters of the removecustomproperties method are as follows: subscribername See the description of subscriber name formatting in the Subscriber Name Format section on page 2-4. CustomProperties See the description of custom property keys and values in the Custom Properties section on page 2-7. Return Value None. RPC Exception Error Codes The following list presents error codes that the removecustomproperties 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. Quota Manager Blocking API Methods This section lists the methods of the Quota Manager (QM) Blocking API. The description of each method includes the syntax, input parameters, and return values. Use the following methods for static or manual subscriber quota configuration: addsubscriberquota, page 3-34 setsubscriberquota, page 3-34 replenishsubscriberquota, page 3-35 Use the following methods for basic read-only operations: getsubscriberquotainformation, page 3-36 getsubscriberquotaprofileid, page 3-37 getbreachedsubscribernames, page 3-38 getpenaltysubscribernames, page

62 addsubscriberquota Chapter 3 Blocking API addsubscriberquota Syntax The following sections provide information about the addsubscriberquota operation: Syntax, page 3-34 Description, page 3-34 Parameters, page 3-34 RPC Exception Error Codes, page 3-34 The addsubscriberquota syntax is as follows: public void addsubscriberquota(string subscribername,int bucketid,long bucketsize) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The addsubscriberquota method adds the quota for the given bucket ID of a subscriber. Parameters RPC Exception Error Codes The parameters of the addsubscriberquota method are as follows: subscribername See the description in the Subscriber Name Format section on page 2-4. bucketid An integer value for the bucket ID to add. bucketsize A long value for the bucket size to add. The following list presents error codes that the addsubscriberquota 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: Syntax, page 3-35 Description, page 3-35 Parameters, page 3-35 RPC Exception Error Codes, page

63 Chapter 3 Blocking API replenishsubscriberquota Syntax The setsubscriberquota syntax is as follows: public void setsubscriberquota(string subscribername,int bucketid,long bucketsize) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The setsubscriberquota method updates the quota for the given bucket ID of a subscriber. Parameters RPC Exception Error Codes The parameters of the setsubscriberquota method are as follows: subscribername See the description 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. The following list presents error codes that the setsubscriberquota 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 Syntax The following sections provide information about the replenishsubscriberquota operation: Syntax, page 3-35 Description, page 3-36 Parameters, page 3-36 RPC Exception Error Codes, page 3-36 The replenishsubscriberquota syntax is as follows: public void replenishsubscriberquota(string subscribername) throws InterruptedException, OperationTimeoutException, RpcErrorException 3-35

64 getsubscriberquotainformation Chapter 3 Blocking API Description The replenishsubscriberquota method replenishes the quota for the given subscriber. Parameters RPC Exception Error Codes The only parameter of the replenishsubscriberquota method is as follows: subscribername See the description in the Subscriber Name Format section on page 2-4. The following list presents error codes that the replenishsubscriberquota 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 getsubscriberquotainformation Syntax The following sections provide information about the getsubscriberquotainformation operation: Syntax, page 3-36 Description, page 3-36 Parameters, page 3-36 Return Value, page 3-37 RPC Exception Error Codes, page 3-37 The getsubscriberquotainformation syntax is as follows: public Object[] getsubscriberquotainformation(string subscribername) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getsubscriberquotainformation method gets a bulk of quota information for a specified subscriber. Parameters The only parameter of the getsubscriberquotainformation method is as follows: subscribername See the description in the Subscriber Name Format section on page

65 Chapter 3 Blocking API getsubscriberquotaprofileid Return Value An object array with five elements. Table 3-2 lists the index values and descriptions. None of the array elements have a NULL value. Table 3-2 Indexes and Descriptions Index Value Index 0 Index 1 Index 2 Index 3 Index 4 Description Package ID (java.lang.string) Last replenish time (java.lang.string) Last SCE that consumed quota (java.lang.string) 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) RPC Exception Error Codes The following list presents error codes that the getsubscriberquotainformation 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: Syntax, page 3-38 Description, page 3-38 Parameters, page 3-38 Return Value, page

66 getbreachedsubscribernames Chapter 3 Blocking API RPC Exception Error Codes, page 3-38 Syntax The getsubscriberquotaprofileid syntax is as follows: public int getsubscriberquotaprofileid(string subscribername) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getsubscriberquotaprofileid method returns the quota profile ID for the specified subscriber. Parameters The only parameter of the getsubscriberquotaprofileid method is as follows: subscribername See the description in the Subscriber Name Format section on page 2-4. Return Value Quota profile ID. RPC Exception Error Codes The following list presents error codes that the getsubscriberquotaprofileid 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 Syntax The following sections provide information about the getbreachedsubscribernames operation: Syntax, page 3-38 Description, page 3-39 Parameters, page 3-39 Return Value, page 3-39 RPC Exception Error Codes, page 3-39 The getbreachedsubscribernames syntax is as follows: public String[] getbreachedsubscribernames(string lastbulkend,int numofsubscribers) throws InterruptedException, OperationTimeoutException, RpcErrorException 3-38

67 Chapter 3 Blocking API getpenaltysubscribernames Description The getbreachedsubscribernames method retrieves the breached subscriber names. Parameters The parameters of the getbreachedsubscribernames method are as follows: 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 will be returned. If this value is higher than the Cisco Service Control Subscriber Manager limit (1000), the operation uses the Cisco Service Control Subscriber Manager limit. Return Value An array of alphabetically ordered subscriber names that belong to a breached state. This method returns all the subscribers found in the Cisco Service Control Subscriber Manager database starting with the requested subscriber. The array size is limited by the smaller of these values numofsubscribers or the Cisco Service Control Subscriber Manager limit (1000). RPC Exception Error Codes The getbreachedsubscribernames method might return the ERROR_CODE _DATABASE_EXCEPTION error code. getpenaltysubscribernames Syntax The following sections provide information about the getpenaltysubscribernames operation: Syntax, page 3-39 Description, page 3-39 Parameters, page 3-40 Return Value, page 3-40 RPC Exception Error Codes, page 3-40 The getpenaltysubscribernames syntax is as follows: public String[] getpenaltysubscribernames(string lastbulkend,int numofsubscribers) throws InterruptedException, OperationTimeoutException, RpcErrorException Description The getpenaltysubscribernames method retrieves the subscriber names in a penalty state. 3-39

68 Blocking API Code Examples Chapter 3 Blocking API Parameters The parameters of the getpenaltysubscribernames method are as follows: 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 will be returned. If this value is higher than the Cisco Service Control Subscriber Manager limit (1000), the operation uses the Cisco Service Control Subscriber Manager limit. Return Value An array of alphabetically ordered subscriber names that belong to a penalty state. This method returns all the subscribers found in the Cisco Service Control Subscriber Manager database starting with the requested subscriber. The array size is limited by the smaller of these values numofsubscribers or the Cisco Service Control Subscriber Manager limit (1000). RPC Exception Error Codes The getpenaltysubscribernames method might return the ERROR_CODE _DATABASE_EXCEPTION error code. Blocking API Code Examples This section includes the following code examples: Getting Number of Subscribers, page 3-40 Adding a Subscriber, Printing Information, and Removing a Subscriber, page 3-41 Getting Subscriber Quota Information, page 3-42 Getting Number of Subscribers The following example prints to stdout the total number of subscribers in the Cisco Service Control Subscriber Manager 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 "+ 3-40

69 Chapter 3 Blocking API Adding a Subscriber, Printing Information, and Removing a Subscriber 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(); Adding a Subscriber, Printing Information, and Removing a Subscriber The following program adds a subscriber to the subscriber database. It then gets its information and prints it to stdout. Finally, the program 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) { 3-41

70 Getting Subscriber Quota Information Chapter 3 Blocking API System.err.println( "usage: java AddPrintRemove <SM-address>"+ " <subscriber-name> <IP mapping> <property-key>"+ " <property-value> <domain>"); System.exit(1); Getting Subscriber Quota Information The following example gets subscriber quota information, sets subscriber quota, and lists subscribers in the breached state: package blocking; import com.pcube.management.api.quotamanagerapi; public class PrintQuotaInfo { /** args Exception */ public static void main(string[] args) throws Exception { QuotaManagerApi qmapi = new QuotaManagerApi(); checkarguments(args); String smip=args[0]; //initiation try { qmapi.setreplytimeout(300000); //set timeout for 5 minutes qmapi.connect(smip); // connect to the SM //operations //getsubscriberquotainformation Object []subquotainfo = qmapi.getsubscriberquotainformation(args[1]); for(int i=0;i<subquotainfo.length;i++){ System.out.println(subQuotaInfo[i]); //getsubscriberquotaprofileid int profileid = qmapi.getsubscriberquotaprofileid(args[1]); System.out.println(profileID); //addsubscriberquota qmapi.addsubscriberquota(args[1], 1,300); subquotainfo = qmapi.getsubscriberquotainformation(args[1]); for(int i=0;i<subquotainfo.length;i++){ System.out.println(subQuotaInfo[i]); //setsubscriberquota qmapi.setsubscriberquota(args[1], 1,300); subquotainfo = qmapi.getsubscriberquotainformation(args[1]); for(int i=0;i<subquotainfo.length;i++){ System.out.println(subQuotaInfo[i]); //getbreachedsubscribernames String []breachsubsnames=qmapi.getbreachedsubscribernames(null, 10); for(int i=0;i<breachsubsnames.length;i++){ System.out.println(breachSubsNames[i]); finally{ //finaliztion qmapi.disconnect(); 3-42

71 Chapter 3 Blocking API Getting Subscriber Quota Information static void checkarguments(string[] args) throws Exception{ if (args.length!= 2) { System.err.println( "usage: java PrintQuotaInfo <SM-address> <subscriber-name> "); System.exit(1); 3-43

72 Getting Subscriber Quota Information Chapter 3 Blocking API 3-44

73 CHAPTER 4 Nonblocking API Published: December 23, 2013, Introduction This chapter introduces features unique to the Nonblocking API. It presents all Nonblocking API methods and provides code examples for each method. This chapter consists of the following sections: Reliability Support, page 4-1 Autoreconnect Support, page 4-2 Multithreading Support, page 4-2 ResultHandler Interface, page 4-2 Nonblocking API Construction, page 4-4 Nonblocking API Initialization, page 4-5 Nonblocking API Methods, page 4-6 Nonblocking API Code Examples, page 4-8 Reliability Support The Nonblocking API can work in two different modes reliable and nonreliable. When the mode is not specified, the default is reliable mode. Reliable Mode, page 4-1 Nonreliable Mode, page 4-2 Reliable Mode In reliable mode, the API ensures that no requests to the Cisco Service Control Subscriber Manager are lost. The API maintains an internal storage for all API requests that are sent to the Cisco Service Control Subscriber Manager. After a reply from the Cisco Service Control Subscriber Manager is received, the request is considered committed and the API can remove the request from its internal storage. If the connection between the API and the Cisco Service Control Subscriber Manager fails, the API 4-1

74 Nonreliable Mode Chapter 4 Nonblocking API accumulates all requests in its internal storage until the connection to the Cisco Service Control Subscriber Manager is established. On reconnection, the API resends all noncommitted and committed requests to the Cisco Service Control Subscriber Manager, so that no requests are lost. Note In reliable mode, the order of resending requests is guaranteed. The API resends the requests in the order in which they were called. Nonreliable Mode In nonreliable mode, the API does not ensure that requests sent to the Cisco Service Control Subscriber Manager are executed. In addition, all requests that are sent by the API when the connection to the Cisco Service Control Subscriber Manager is down are lost unless an external reliability mechanism is implemented. Autoreconnect Support The Nonblocking API supports autoreconnection to the Cisco Service Control Subscriber Manager to address connection failures. When this option is activated, the API can determine when the connection to the Cisco Service Control Subscriber Manager is lost. When the connection is lost, the API activates a reconnection task that tries to reconnect to the Cisco Service Control Subscriber Manager until it is successful. Note The autoreconnect support option can be activated in both reliability modes. Multithreading Support The Nonblocking API supports an unlimited number of threads calling its methods simultaneously. Note In a multithreaded scenario for the Nonblocking API, the order of invocation is guaranteed. The API performs operations in the same order in which they were called. ResultHandler Interface The Nonblocking API enables you to set a result handler. A result handler is an interface with two methods, handlesuccess and handleerror, as represented in the following code: public interface ResultHandler { /** * handle a successful result */ public void handlesuccess(long handle, Object result); /** * handle a failure result */ 4-2

75 Chapter 4 Nonblocking API ResultHandler Interface Example public void handleerror(long handle, Object result); You should implement this interface if you want to be informed about the success or error results of operations performed through the API. Note This is the only interface for retrieving results. Results cannot be returned immediately after the API method has returned to the caller. Note To receive operation results, set the result handler of the API before calling API methods for which you want to receive results. Set the result handler after the API is connected (as in the ResultHandler Interface Example section on page 4-3). Both handlesuccess and handleerror methods accept two parameters: Handle Each API operation return-value is a handle of type long. This handle enables correlation between operation calls and their results. When a handle operation is called with a handle of value X, the result will match the operation that returned the same handle value (X) to the caller. Result Actual result of the operation. Some operations may return a result of NULL. ResultHandler Interface Example The following example is a simple implementation of a result handler that prints a message to stdout (when the result is successful) or to stderr (when the result is a failure). This main method initiates the API and assigns a result handler. For correct operation of the result handler, follow the code sequence presented in this example. Note This example does not demonstrate the use of callback handles. import com.pcube.management.framework.rpc.resulthandler; import com.pcube.management.api.smnonblockingapi; public class ResultHandlerExample implements ResultHandler{ public void handlesuccess(long handle, Object result) { System.out.println("success: handle="+handle+", result="+result); public void handleerror(long handle, Object result) { System.err.println("error: handle="+handle+", result="+result); public static void main (String args[]) throws Exception{ if (args.length!= 1) { System.err.println("usage: ResultHandlerExample <sm-ip>"); System.exit(1); //note the order of operations! SMNonBlockingApi nbapi = new SMNonBlockingApi(); nbapi.connect(args[0]); nbapi.setresulthandler(new ResultHandlerExample()); 4-3

76 Nonblocking API Construction Chapter 4 Nonblocking API nbapi.login(...); Nonblocking API Construction In addition to the constructors described in the API Construction section on page 2-2, the Nonblocking API provides constructors that enable you to set the reconnect period and the reliability mode. Nonblocking API Syntax The syntax for the additional Nonblocking API constructors is as follows: public SMNonBlockingApi(long autoreconnectinterval) public SMNonBlockingApi(boolean reliable, long autoreconnectinterval) public SMNonBlockingApi(String legname, long autoreconnectinterval) public SMNonBlockingApi(String legname, boolean reliable, long autoreconnectinterval) Nonblocking API Arguments The following list describes the constructor arguments for the additional Nonblocking API constructors: autoreconnectinterval Defines the interval (in milliseconds) between attempts to reconnect, as follows: If the value is 0 or less, the reconnection task is not activated (no autoreconnect is attempted). If the value is greater than 0 and if there is a connection failure, the reconnection task is activated every autoreconnectinterval milliseconds. Default value is 1 (no autoreconnect is attempted). Note To enable the autoreconnect support, the connect method of the API must be activated at least once. For more information, see the Nonblocking API Code Examples section on page 4-8. reliable An argument that defines whether the API should work in reliable mode, as follows: TRUE The API works in reliable mode. FALSE The API works in nonreliable mode. Default value is TRUE (the API works in reliable mode). legname The name of the LEG, as described in the API Construction section on page 2-2. Nonblocking API Examples The following example constructs a reliable API with an autoreconnection interval of 10 seconds: SMNonBlockingAPI nbapi = SMNonBlockingAPI(10000); nbapi.connect(<sm IP address>); The following example constructs a reliable API without autoreconnection support: 4-4

77 Chapter 4 Nonblocking API Nonblocking API Initialization // API construction SMNonBlockingAPI nbapi = SMNonBlockingAPI(); // Connect to the API nbapi.connect(<sm IP address>); The following example constructs a nonreliable API with autoreconnection support: // API construction SMNonBlockingAPI nbapi = SMNonBlockingAPI(false,10000); // Initial connection - to enable the reconnect task nbapi.connect(<sm IP address>); Nonblocking API Initialization The Nonblocking API enables you to initialize certain internal properties to customize the API. This initialization is performed by using the API init method. Note For the settings to take effect, the init method must be called before the connect method. You can set the following properties: Output queue size The internal buffer size that limits the maximum number of requests that can be accumulated by the API until they are sent to the Cisco Service Control Subscriber Manager. The default is Operation timeout The desired timeout (in milliseconds) on a nonresponding proprietary remote procedure call (PRPC) protocol connection. The default is 45 seconds. Nonblocking API Initialization Syntax The syntax for the Nonblocking API init method is as follows: public void init(properties properties) Nonblocking API Initialization Parameters The Nonblocking API init method has the following parameters: properties (java.util.properties) Enables setting the following properties described previously: To set the output queue size, use prpc.client.output.machinemode.recordnum. To set the operation timeout, use prpc.client.operation.timeout. Nonblocking API Initialization Example The following Nonblocking API code illustrates how to customize properties during initialization. Note that the init method is called before the connect method. // API construction SMNonBlockingAPI nbapi = SMNonBlockingAPI(10000); // API initialization java.util.properties p = new java.util.properties(); p.setproperty("prpc.client.output.machinemode.recordnum", 2048); 4-5

78 Nonblocking API Methods Chapter 4 Nonblocking API p.setproperty("prpc.client.operation.timeout", 60000);// 1 minute nbapi.init(p); // initial connect to the API to enable the reconnect task nbapi.connect(<sm API address>); Nonblocking API Methods This section describes the methods of the Nonblocking API. All methods return a handle of type long that can be used to correlate operation calls and their results. See the ResultHandler Interface section on page 4-2. The operation results passed to the result handler are similar to the return values described in the same method in the Chapter 3, Blocking API, except for the following: Basic types are converted to their Java class representation. For example, int is translated to java.lang.integer. Return values of Void are translated to NULL. Note An error is passed to the result handler only if the matching operation in the Blocking API generates an exception with the same arguments that correspond to the state of the Cisco Service Control Subscriber Manager database at the time of the call. All methods will generate java.lang.illegalstateexception if called before a connection with the Cisco Service Control Subscriber Manager is established. This section describes the following methods: login, page 4-6 logoutbyname, page 4-7 logoutbynamefromdomain, page 4-7 logoutbymapping, page 4-7 logincable, page 4-8 logoutcable, page 4-8 login This section provides the syntax for the login operation. Syntax The login syntax is as follows: public long login(string subscribername, String[] mappings, short[] mappingtypes, String[] propertykeys, String[] propertyvalues, String domain, boolean ismappingadditive, int autologouttime) 4-6

79 Chapter 4 Nonblocking API logoutbyname The operation functionality is the same as the matching Blocking API operation. See the login section on page 3-4 for more information. logoutbyname This section provides the syntax for the logoutbyname operation. Syntax The logoutbyname syntax is as follows: public long logoutbyname(string subscribername, String[] mappings, short[] mappingtypes) The operation functionality is the same as the matching Blocking API operation. See the logoutbyname section on page 3-7 for more information. logoutbynamefromdomain This section provides the syntax for the logoutbynamefromdomain operation. Syntax The logoutbynamefromdomain syntax is as follows: public long logoutbynamefromdomain(string subscribername, String[] mappings, short[] mappingtypes, String domain) The operation functionality is the same as the matching Blocking API operation. See the logoutbynamefromdomain section on page 3-9 for more information. logoutbymapping This section provides the syntax for logoutbymapping operation. Syntax The logoutbymapping syntax is as follows: public long logoutbymapping(string mapping, short mappingtype, String domain) The operation functionality is the same as the matching Blocking API operation. See the logoutbymapping section on page 3-10 for more information. 4-7

80 logincable Chapter 4 Nonblocking API logincable This section provides the syntax for the logincable operation. Syntax The logincable syntax is as follows: public long logincable(string CPE, String CM, String IP, int lease, String domain, String[] propertykeys, String[] propertyvalues) The operation functionality is the same as the matching Blocking API operation. See the logincable section on page 3-12 for more information. logoutcable This section provides the syntax for the logoutcable operation. Syntax The logoutcable syntax is as follows: public long logoutcable(string CPE, String CM, String IP, String domain) The operation functionality is the same as the matching Blocking API operation. See the logoutcable section on page 3-14 for more information. Nonblocking API Code Examples This section presents example code for logging in and logging out subscribers. Login and Logout The following example logs in a predefined number of subscribers to the Cisco Service Control Subscriber Manager and then logs them out. Note the implementation of a disconnect listener and a result handler. package nonblocking; import com.pcube.management.framework.rpc.disconnectlistener; import com.pcube.management.framework.rpc.resulthandler; import com.pcube.management.api.smnonblockingapi; import com.pcube.management.api.smapiconstants; class LoginLogoutDisconnectListener implements DisconnectListener { 4-8

81 Chapter 4 Nonblocking API Login and Logout public void connectionisdown() { System.err.println("disconnect listener:: connection is down"); class LoginLogoutResultHandler implements ResultHandler { int count = 0; //prints a success result every 100 results public synchronized void handlesuccess(long handle, Object result) { Object tmp = null; if (++count%100 == 0) { tmp = result instanceof Object[]? ((Object[])result)[0] : result; System.out.println("\tresult "+count+":\t"+tmp); //prints every error that occurs public synchronized void handleerror(long handle, Object result) { System.err.println("\terror: "+count+":\t"+ result); ++count; //waits for result number 'last result' to arrive public synchronized void waitforlastresult(int lastresult) { while (count<lastresult) { try { wait(100); catch (InterruptedException ie) { ie.printstacktrace(); public class LoginLogout { public static void main (String args[]) throws Exception{ //check arguments checkarguments(args); int numsubscriberstologin = Integer.parseInt(args[2]); //instantiation SMNonBlockingApi nbapi = new SMNonBlockingApi(); try { //initation nbapi.setdisconnectlistener( new LoginLogoutDisconnectListener()); nbapi.connect(args[0]); LoginLogoutResultHandler resulthandler = new LoginLogoutResultHandler(); nbapi.setresulthandler(resulthandler); //login System.out.println("login of "+numsubscriberstologin +" subscribers"); for (int i=0; i<numsubscriberstologin; i++) { nbapi.login("subscriber"+i, //subscriber name getmappings(i), //a single ip mapping new short[]{ SMApiConstants.MAPPING_TYPE_IP, null, //no properties null, args[1], //domain false, //mappings are not additive -1); //disable autologout 4-9

82 Login and Logout Chapter 4 Nonblocking API resulthandler.waitforlastresult(numsubscriberstologin); //logout System.out.println("logout of "+numsubscriberstologin +" subscribers"); for (int i=0; i<numsubscriberstologin; i++) { nbapi.logoutbymapping(getmappings(i)[0], SMApiConstants.MAPPING_TYPE_IP, args[1]); resulthandler.waitforlastresult(numsubscriberstologin*2); finally { nbapi.disconnect(); static void checkarguments(string[] args) throws Exception{ if (args.length!= 3) { System.err.println("usage: java LoginLogout "+ "<SM-address> <domain> <num-susbcribers>"); System.exit(1); //'automatic' mapping generator private static String[] getmappings(int i) { return new String[]{ "10." +((int)i/65536)%256 + "." + ((int)(i/256))%256 + "." + (i%256); The following example logs in a predefined number of IPv6 subscribers to the Cisco Service Control Subscriber Manager and then logs them out. Note the implementation of a disconnect listener and a result handler. package nonblocking; import com.pcube.management.framework.rpc.disconnectlistener; import com.pcube.management.framework.rpc.resulthandler; import com.pcube.management.api.smnonblockingapi; import com.pcube.management.api.smapiconstants; class LoginLogoutDisconnectListener implements DisconnectListener { public void connectionisdown() { System.err.println("disconnect listener:: connection is down"); class LoginLogoutResultHandler implements ResultHandler { int count = 0; //prints a success result every 100 results public synchronized void handlesuccess(long handle, Object result) { Object tmp = null; if (++count%100 == 0) { tmp = result instanceof Object[]? ((Object[])result)[0] : result; System.out.println("\tresult "+count+":\t"+tmp); //prints every error that occurs public synchronized void handleerror(long handle, Object result) { System.err.println("\terror: "+count+":\t"+ result); ++count; //waits for result number 'last result' to arrive public synchronized void waitforlastresult(int lastresult) { while (count<lastresult) { try { wait(100); catch (InterruptedException ie) { 4-10

83 Chapter 4 Nonblocking API Login and Logout ie.printstacktrace(); public class LoginLogout { public static void main (String args[]) throws Exception{ //check arguments checkarguments(args); int numsubscriberstologin = Integer.parseInt(args[2]); //instantiation SMNonBlockingApi nbapi = new SMNonBlockingApi(); try { //initation nbapi.setdisconnectlistener( new LoginLogoutDisconnectListener()); nbapi.connect(args[0]); LoginLogoutResultHandler resulthandler = new LoginLogoutResultHandler(); nbapi.setresulthandler(resulthandler); //login System.out.println("login of "+numsubscriberstologin +" subscribers"); int subscount = 0; outer:for(int j=0x0;j<=0xf;j++) { for(int i=0x0000; i<=0xffff;i++) { nbapi.login("sub"+subscount,new String[]{"2001:200:"+Integer.toHexString(j)+":"+Integer.toHexString(i)+"::/64", new short[]{smapiconstants.mapping_type_ipv6, new String[]{"upVlinkId",new String[]{ "85", "subscribers", true, -1); subscount++; if(subscount == numsubscriberstologin) break outer; resulthandler.waitforlastresult(numsubscriberstologin*2); //logout subscount = 0; System.out.println("logout of "+numsubscriberstologin +" subscribers"); outer:for(int j=0x0;j<=0xf;j++) { for(int i=0x0000; i<=0xffff;i++) { nbapi.logoutbymapping("2001:200:"+integer.tohexstring(j)+":"+integer.tohexstring(i)+"::/64 ", SMApiConstants.MAPPING_TYPE_IPV6, args[1]); subscount++; if(subscount == numsubscriberstologin) break outer; resulthandler.waitforlastresult(numsubscriberstologin*2); finally { nbapi.disconnect(); 4-11

84 Login and Logout Chapter 4 Nonblocking API static void checkarguments(string[] args) throws Exception{ if (args.length!= 3) { System.err.println("usage: java LoginLogout "+ "<SM-address> <domain> <num-susbcribers>"); System.exit(1); //'automatic' mapping generator private static String[] getmappings(int i) { return new String[]{ "10." +((int)i/65536)%256 + "." + ((int)(i/256))%256 + "." + (i%256); 4-12

85 APPENDIXA List of Error Codes Published: December 23, 2013, Introduction This appendix provides a list of error codes that are used in the Java API. List of Error Codes Error codes interpret the actual error for which RpcErrorException was returned. Use the geterrorcode method to extract the error code. The error code enumeration is given in the com.pcube.management.api.smapiconstants interface. Table A-1 gives a list of the error codes and their descriptions. Table A-1 List of Error Codes Error Code ERROR_CODE_ARRAY_ACCESS ERROR_CODE_ATTRIBUTE_NOT_FOUND ERROR_CODE_BAD_SUBSCRIBER_MAPPING ERROR_CODE_CLASS_CAST ERROR_CODE_CLASS_NOT_FOUND ERROR_CODE_CLIENT_INTERNAL_ERROR ERROR_CODE_CLIENT_OUT_OF_THREADS ERROR_CODE_DATABASE_EXCEPTION Description Internal Cisco Service Control Subscriber Manager error. Internal Cisco Service Control Subscriber Manager error. A mapping was formatted badly or assigned to the subscriber illegally. Internal Cisco Service Control Subscriber Manager error. Internal Cisco Service Control Subscriber Manager error. Internal error. Internal error. Internal Cisco Service Control Subscriber Manager error database error occurred during the operation. A-1