Managing Services

Needs to be updated for 2.1!

Apache-SOAP provides an administration tool to manage services. There are two clients to service manager: an HTML one used via a browser and a command-line tool.

NOTE: If you had previously deployed services to an Apache-SOAP server, then this version will not recognize those services because the class that was being serialized to represent services has changed.

Running the Server Side Admin Tool to Manage Services

With the Apache-SOAP Administration Tools it is possible to use a Web browser to deploy and un-deploy services and to review the list and the definitions of the services deployed on a given SOAP server.

Point your browse to http://hostname:port/soap (see above) and you will get the "Apache-SOAP Admin" screen with three options:

• Deploy to deploy a new service.
• Un-deploy to remove a deployed service.
• List shows the list of services currently deployed in the server.

The usage of these functions is immediate once one understands the nature of the information required for deploying a service. In the next section we describe this information.

Service Deployment Information

We review here the information that defines a deployed service. This information must be provided when using the Deploy function, and can be browsed using the List function. We refer to this information as "properties" of the service.

• ID. An URN uniquely identifies the service to clients. It must be unique among the deployed services, and be encoded as a URI. We commonly use the format: urn:UniqueServiceID . It corresponds to the target object ID, in the terminology of the SOAP specification.
• Scope. Defines the lifetime of the object serving the invocation request. This corresponds scope attribute of the <jsp:useBean> tag in the JavaServer Pages. It may thus have the following possible values:
  • page: the object is available until the target JSP page (in this case the rpcrouter.jsp) sends a response back or the request is forwarded to another page (if you are using the standard deployment mechanism this is unlikely to happen).
  • request: the object is available for the complete duration of the request, regardless of forwarding.
  • session: the object is available for the complete duration of the session.
  • application: any page within the application may access the object. In particular, successive service invocations belonging to different sessions will share the same instance of the object. It is important to observe that the value of this attribute can have important security implications. The page and request scopes assure the isolation of successive calls. On the other extreme, application scope implies that all service objects are shared among different users of the SOAP server. A document describing usage scenarios for different scopes will be forthcoming.
• Method list. Defines the names of the method that can be invoked on this service object.
• Provider type. Indicates whether the service is implemented using Java or a scripting language.
• For Java services, Provider class. Fully specified class name of the target object servicing the request.
• For Java services, Use static class. If set to "Yes" the class method that is made available is a static method, and thus no object will be instantiated. When static invocation is used, the "scope" property is not applicable.
• For script services, Script language. Indicates the scripting language used to implement the service.
• For script services, Script filename. Name of file containing the script, or
• For script services, Script. The actual script to run.
• Type mappings. In order to control the serialization and deserialization of specific Java types to and from XML in a particular encoding style, it may be necessary to provide serialization and deserialization classes that know how to perform the correct conversions for those types. The Apache-SOAP server already includes serialization classes for most basic types in the SOAP encoding style, as well as a Bean encoding class that can provide a generic serialization of a bean in terms of its properties. It also includes XMI serializer/deserializer classes to support the XMI encoding style. Since different types may require additional support for correct serialization, the Apache-SOAP maintains a registry of Serializers and Deserializers. The registry is accessible to service administrators through the Apache-SOAP administration tool, as well as through a program API. In order to register a (de)serializer class, the class must implement the Serializer or Deserializer interfaces, see JavaDocs for org.apache.soap.util.xml.Serializer and com.org.apache.soap.util.Deserializer .
• Default Mapping Registry. Fully-qualified classname of a customized registry that will manage the serializer/deserializers for the service. Must be a subclass of org.apache.soap.encoding.SOAPMappingRegistry. In the XML deployment descriptor, this can be specified in a "defaultRegistryClass" attribute of the "isd:mappings" element

Using the Command Line Tool to Manage Services

The command line tool is run by typing java org.apache.soap.server.ServiceManagerClient. Running this yields:

% java org.apache.soap.server.ServiceManagerClient
Usage: java org.apache.soap.server.ServiceManagerClient url operation arguments
where
        url is the Apache-SOAP router's URL whose services are managed
        operation and arguments are:
                deploy deployment-descriptor-file.xml
                list
                query service-name
                undeploy service-name

To deploy a service, for example, type:

% java org.apache.soap.server.ServiceManagerClient http://hostname:port/soap/servlet/rpcrouter deploy foo.xml

where foo.xml is the deployment descriptor and the URL is appropriate for your installation.