API for Dynamic Service Activator
This section contains information that developers need to create gateway clients and that administrators need to manage gateway clients and their interactions with the gateway.
Public SOAP Interfaces of Web Applications
When you have installed Dynamic Service Activator, you can access a Web Services Description Language (WSDL) file for the application. The WSDL file defines the SOAP properties that you or your customers can use to develop a gateway client. The URL for Dynamic Service Activator is:
http://<host>:<portNumber>/dsa/services/DynamicServiceActivation ?wsdl
- <host>—IP address or name of the host that supports Dynamic Service Activator
- <portNumber>—Number of the TCP port
Methods for the Dynamic Service Activator SOAP Interface
This section describes the methods associated with Dynamic Service Activator, and provides information additional to that in the WSDL file.
invokeGwExtension
- Creates a self-contained servlet to be deployed in the Advanced Services Gateway Web application server. The servlet can be a standalone application, or it can be part of a WAR or EAR file.
When deployed, servlets created with InvokeGwExtension should be accessible only from the local host.
- extensionName—String that contains the name of the servlet that the gateway client invokes
- extensionArguments—String array of arguments that the gateway client passes to the servlet
- Guidelines—The names in the following components and properties must be the same as the name of the extensionName argument:
- The name of the WAR file that is the gateway extension servlet
- In the WEB-INF/web.xml file in the servlet section, the servlet name
- In WEB-INF/web.xml file in the servlet-mapping section, the URL pattern in the format /servlet/<extensionName>
- Expected output—String returned by the extension
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
invokeScript
- Manages all operations involved with invoking scripts: retrieves requests to invoke scripts from the gateway client, authenticates the gateway client, verifies the arguments supplied by the gateway client, communicates with other SDX components, and returns values to the gateway client. For a complete description of Dynamic Service Activator's interactions with the gateway client and other components, see Dynamic Service Activator Operation.
- Arguments
- scriptName—String that contains the name of the script that the gateway client wants to invoke
- scriptArgs—String array of arguments that the gateway client passes to the script
- Expected output—String returned by the script
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_readSubscription
- Determines whether a subscriber accesses services through the SDX owner's network and obtains all of that subscriber's subscriptions; returns the result in a one-dimensional array.
- Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI)
- Expected output—Multidimensional array of Attr objects that contain the subscriptions for the subscriber
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_readSubscription_retAttrSeq
- Determines whether a subscriber accesses services through the SDX owner's network and obtains all of that subscriber's subscriptions; returns the result in a multidimensional array.
- Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI)
- Expected output—One-dimensional array of AttrSeq objects that contain the subscriptions for the subscriber
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_activateService
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI)
- subscriptionName—String that contains the name of the subscription
- sessionName—String that contains the name of the service session; default string is default
- activationAttributes—Array of one or more of the following attributes that can be specified for the subscription:
- sessionTimeout
- downstreamBandwidth
- upstreamBandwidth
- sessionTag
- subscriptionUsername
- subscriptionPassword
- substitutions
For information about these attributes, see Subscription Attributes.
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_deactivateService
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI)
- subscriptionName—String that contains the name of the subscription
- sessionName—String that contains the name of the service session; default string is default
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_modifyService
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI)
- subscriptionName—String that contains the name of the subscription
- sessionName—String that contains the name of the service session; default string is default
- optionalAttributes—Array of one or more of the following attributes that can be modified for the subscription:
For information about these attributes, see Subscription Attributes.
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_login
- Logs in subscribers
NOTE: This method supports only subscribers who are identified by their IP addresses. This method does not support subscribers who are identified by the names they use to log in or by their DNs.
. - Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI)
- Expected output—Boolean operator that indicates success
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Subscriber_logout
- Logs out subscribers. This method supports only subscribers who are identified by their IP addresses or the names they use to log in. This method does not support subscribers who are identified by their DNs.
- Arguments
- subURI—String that contains the subscriber's URI (see Format of the Subscriber's URI)
- Expected output—None
- SOAP fault codes—See SOAP Fault Codes for Dynamic Service Activator
Format of the Subscriber's URI
Many of Dynamic Service Activator's methods require the argument subURI, the subscriber's uniform resource identifier (URI). This argument comprises two portions: the type of subscriber (subscriber-type) and a list of the subscriber's attributes (subscriber-comp). The syntax for the subURI argument is:
<subscriber-type>:<subscriber-comp> [& <subscriber-comp>]*
The <subscriber-type> variable is the name of the Subscriber Type instance that is defined in the directory during the Dynamic Service Activator configuration (see Configuring Subscriber Types for Dynamic Service Activator). For example, the sample data provides these Subscriber Type instances for the <subscriber-type> value:
- ip—The sidType is SIT_ADDRESS
- dn—The sidType is SIT_DN
- login—The sidType is SIT_LOGIN_NAME
- assignedIp—The sidType is SIT_ADDR_IF_NAME
- intName—The sidType is SIT_IF_NAME
- intIndex—The sidType is SIT_IF_INDEX
The <subscriber-comp> variable has the format <type>=<value>.
- ipAddress—Subscriber's IP address; mandatory when the sidType is SIT_ADDRESS or SIT_ADDR_IF_NAME
- timestamp—Time at which the request was sent; optional when the sidType is SIT_ADDRESS
- dn—Subscriber's DN; mandatory when the sidType is SIT_DN
- intfName—Name of the interface on which the subscriber logs in; mandatory when the sidType is SIT_IF_NAME, optional when the sidType is SIT_ADDR_IF_NAME
- vrfName—Name of the VRF associated with the subscriber; mandatory when the sidType is SIT_IF_NAME or SIT_IF_INDEX, optional when the sidType is SIT_ADDR_IF_NAME
- login_name—Name with which the subscriber logs in; mandatory when the sidType is SIT_LOGIN_NAME
- intfIndex—SNMP index of the interface on which the subscriber logs in; mandatory when the sidType is SIT_IF_INDEX
- primary_user_name—Primary username; mandatory when the sidType is SIT_PRIMARY_USER_NAME
; | / | ? | : | @ | & | = | + | $ | ,
For example, you can use the following subscriber's URI to look up a subscriber by IP address as specified by the sample data:
The sample data defines a subscriber type named ip, whose sidType is SIT_ADDRESS and nicProxyNamespace is /nicProxies/ip. As a result, ip is the value of the <subscriber-type> variable. Because the sidType is SIT_ADDRESS, ipAddress is mandatory for the <type> component, and the subscriber's IP address is the <value> component of the <subscriber-comp> variable.
Subscription Attributes
Some methods take attributes for subscriptions, as described below.
sessionTimeout
- Timeout for the service.
- Value—Number of milliseconds in the range -1-2147483647
- Guideline— -1 indicates no timeout.
- Example—600
downstreamBandwidth
- Traffic rate between the subscriber and the network.
- Value—Number of bits per second in the range 0-2147483647
- Example—10000
upstreamBandwidth
- Traffic rate between the network and subscriber.
- Value—Number of bits per second in the range 0-2147483647
- Example—5000
sessionTag
- Tag that the software uses to track a session for accounting purposes.
- Value—Text string
- Example—News:Joe
subscriptionUsername
subscriptionPassword
substitutions
- Attributes and values that the method should substitute for existing settings.
- Value—Array of strings; each array has the format <substutionType>=<substitutionValue>
- Example—Port=9999
SOAP Fault Codes for Dynamic Service Activator
When Dynamic Service Activator receives a SOAP request that it cannot handle, it returns a SOAP fault message to the gateway client. This message contains a text string that specifies a SOAP fault code and a text string that provides additional information about the fault.
Dynamic Service Activator returns the following SOAP fault codes. If the SOAP fault code has the format client.<variables>, you must correct the gateway client. However, if the SOAP fault code has the format server.<variables>, record the error code and notify the gateway administrator.
Client.InvalidArguments
- Specifies that one or more of the arguments for the script or method is an empty string or has a null value.
- Classification of call—Denied
- Action—Check that all arguments are correct.
Client.InvalidSubscriberFormat
- Specifies that the subURI argument, which the client passes to all methods except invokeScript, is invalid.
- Classification of call—Denied
- Action—Check that subURI arguments are correct.
Server.AccessDenied
- Specifies that the client does not have permission to make the request because of one or more of the following errors:
- Advanced Services Gateway does not recognize the client.
- Supplied name of the method or script is incorrect.
- Number or value of the arguments supplied for the script or method is incorrect.
- Classification of call—Denied
- Action—Check that the values are correct. If they are, contact the gateway administrator.
Server.AccessControlMisconfiguration
- Specifies that the gateway administrator did not configure Dynamic Service Activator correctly, in one of the following ways:
- The saeLocatorArg is not an integer.
- The number of arguments is less than the value of the saeLocatorArg parameter.
- The regular expressions are not correctly defined.
Server.Misconfiguration
- Specifies that the gateway administrator did not configure the Web application to authenticate SOAP clients, and an unauthenticated client has passed a request to Dynamic Service Activator, which refuses unauthenticated requests.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAEUnreachable
- Specifies that the gateway client either cannot identify the SAE server or cannot reach it through CORBA. This SAE can be one on which the subscriber has logged in or one on which the client wants to invoke a script.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAE.UnkownSAEUser
- Specifies that the SAE on which Dynamic Service Activator tried to run a method or script cannot identify the subscriber. Dynamic Service Activator may have retained in its cache an SAE that is no longer current for the subscriber.
- Classification of call—Failed
- Action—Try this operation again. If it fails again, contact the gateway administrator.
Server.SAE.UserNotUniqueToSAE
- Specifies that the subscriber is already active on the SAE on which Dynamic Service Activator tried to run a method or script. Dynamic Service Activator may have retained in its cache an SAE that is no longer current.
- Classification of call—Failed
- Action—Try this operation again. If it fails again, contact the gateway administrator.
Server.SAE.UnknownService
- Specifies that the SAE cannot identify the service that a subscription specifies.
- Classification of call—Failed
- Action—Check the service parameter for the following methods:
Server.SAE.UnknownSubscription
- Specifies that the SAE cannot identify the subscription that the subscriber wants to activate.
- Classification of call—Failed
- Action—Check the service parameter for the following methods:
Server.SAE.ServiceAuthenticationError
- Specifies that the service the subscriber wants to activate requires authentication.
- Classification of call—Failed
- Action—Check the activation attributes. If they are correct, contact the gateway administrator.
Server.SAE.UnknownServiceSession
- Specifies that the SAE cannot identify the service session that the subscriber wants to modify.
- Classification of call—Failed
- Action—Check the serviceId and sessionName parameters.
Server.SAE.LoginError
- Specifies that the subscriber could not log in successfully.
- Failed
- Action—Check the subURI, username, and userPassword arguments.
Server.SAE.Exception
- Specifies that the SAE raised an exception after Dynamic Service Activator tried to run a method or script on the SAE.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAE.Overload
- Specifies that the SAE raised an overload exception after Dynamic Service Activator tried to run a method or script on the SAE.
- Classification of call—Failed
- Action—Contact the gateway administrator.
Server.SAE.ScriptProcessorError
- Specifies that the SAE's script processor failed to invoke the script. This error could occur for many reasons, such as:
- Gateway administrator did not deploy the script on the SAE host.
- Gateway administrator did not configure the script processor correctly.