Table Of Contents
InventoryQueryResult Interface
Cisco PTC API Reference
Java API and Services
The Java API defines general interfaces that provide these major functions:
•Inventory query and retrieval—this includes navigating the object model to retrieve objects by containment relationship (with scoping and simple filtering) and association relationship
The Java API currently consists of one major remote interface:
•ServiceManager—provides functions for object query (synchronous operation) in a secured fashion. At runtime, when a client is authenticated, a ServiceManager object is created on behalf of the client application. The ServiceManager maintains the session data (security token) of the client and performs an authorization check on all the operations invoked by the client.
The Java API also includes these auxiliary remote interfaces and Java classes:
•InventoryQueryResult—a Java Class that defines the result of an inventory query operation
•ServiceManagerHome—a remote interface that authenticates a client application (with username and password) and creates a ServiceManager for the client (if authenticated).
Figure 4-1 illustrates the interaction between a typical client application and the API layer.
Figure 4-1 Interaction Between a Client Application and the API Layer
ServiceManager Interface
The ServiceManager Interface defines these methods:
•setSessionContext()—used by ServiceManagerHome to pass the security token. The security token is used for an authorization check on subsequent method invocations.
•queryContained()—provides bulk inventory retrieval function. It allows the client to bulk retrieve the entire subtree of objects contained under a specified scope. The supported object retrieval scope is zero. In addition to scoping, it also supports object retrieval based on the following filtering criteria:
–filter by class condition—return objects whose class matches the one specified
•the query returns an InventoryQueryResult object, which provides methods for the client to:
–fetch the first batch of query results, returned as an XML string (encoded as "InventoryQueryResult" in an XML DTD)
The following bulk retrieval requests are supported:
–Retrieve all objects in a region. The API returns the containing DGK Group and virtual zones, plus the entire subtree of objects contained under them.
–Retrieve all objects in a virtual zone. The API returns the GK Group and virtual gateways that make up the virtual zone, plus the entire subtree of objects contained under them.
–Retrieve all objects in a Virtual Gateway (VG). The API returns the gateway, SC Complex, Q.931/RLM path, and virtual voice ports in the VG. It also returns all objects contained under the gateway including voice port, Q.931/RLM TP, IVR/VoiceXML, SNMP NTP, RADIUS Group, Access List, and Interface; and all objects under the SC complex including SLTs, LAN Switches, and SC hosts, plus the signaling and trunking components under the SC hosts.
–Retrieve all objects in a GK/DGK Group. The API returns the GKs/DGKs in the GK/DGK Group, plus all objects contained under each GK/DGK, including SNMP, NTP, RADIUS Group, Access List, and Interface.
•The operation is synchronous and the results returned are encoded as XML strings (defined as "ConfigResult" in an XML DTD). The following provisioning services are supported:
–Region Configuration—configure RADIUS Group, SNMP, and NTP
–Virtual Zone Configuration—config H.235 security options, RADIUS Group, OSP, SNMP, and NTP
–Virtual Gateway Configuration—Q.931/RLM signaling path, voice port, RADIUS Group, OSP, IVR/VoiceXML, DNIS Map for VoiceXML, SNMP, NTP, Access List, Interface, T.37/T.38 Fax Application, and H.323 parameters
–GK/DGK Configuration—HSRP options, RADIUS Group, SNMP, NTP, Access List, and Interface
–Dial Plan provisioning.
ServiceManagerHome Interface
The ServiceManagerHome interface serves the bootstrapping and authentication purposes for client applications. ServiceManagerHome objects (usually one per server) are registered at a registry (such as the Java Naming server). The client bootstraps by locating an appropriate ServiceManagerHome from the registry.
•create()—a client initiates a session by invoking this operation on ServiceManagerHome along with their username and password. ServiceManagerHome authenticates the client with the Security server, which returns a security token, if authenticated. ServiceManagerHome creates a ServiceManager object on behalf of the client, and then passes the security token to the ServiceManager (by setting its session). The token is used by ServiceManager to perform an authorization check on method invocation.
InventoryQueryResult Interface
The InventoryQueryResult interface defines the following operations:
•getInitBatch()
•setInitBatch()