Configuration information may be passed to
the Apache SOAP server via an XML-based configuration
file. By default, the server will look in
the current working directory for a file
called "soap.xml." If a different
file is to be used, the default path and
name can be overridden by specifying a parameter
that the transport listener (i.e. RPCRouterServlet)
passes along to the SOAP server during startup.
(All transport listeners should call the
org.apache.soap.server.ServiceManager's static
method setConfigFileName(...) before invoking
the SOAP server.)
For HTTP transport listeners, this option
can be set in the configuration file for
the rpcrouter servlet by adding an init-parameter
called ConfigFile to the servlet's deployment properties file.
A servlet deployment properties file with
this modification would look like the following:
<servlet>
<servlet-name>rpcrouter</servlet-name>
<display-name>Apache-SOAP RPC Router</display-name>
<description>no description</description>
<servlet-class>
org.apache.soap.server.http.RPCRouterServlet
</servlet-class>
<init-param>
<param-name>faultListener</param-name>
<param-value>org.apache.soap.server.DOMFaultListener</param-value>
</init-param>
<init-param>
<param-name>ConfigFile</param-name>
<param-value>config-file</param-value>
</init-param>
</servlet>
where config-file is the path (either fully qualified or relative)
and filename of the SOAP configuration file.
There is only one setting currently allowed in the SOAP server configuration file: information about the pluggable configuration manager. A SOAP server configuration file which sets information about the provider would look like the following:
<!-- Sample Apache SOAP Server Configuration File -->
<soapServer>
<!-- This section defines the same thing you get if you don't -->
<!-- specify anything at all - aka the default -->
<configManager value="config-manager" >
[<option name="option-name" value="option-value"/>]*
</configManager>
</soapServer>
where config-manager is the fully qualified class name of the configuration manager which should be used by the SOAP server. Additional information may be passed to the configuration manager through the use of <option> elements, with option-name and option-value acting as key/value pairs.
The SOAP configuration manager is responsible
for saving the current list of deployed services
to persistent storage, so that when the SOAP
server is stopped and restarted, the services
will not need to be redeployed.
If no configuration manager is specified
in the server configuration file, or if the
specified configuration manager cannot be
loaded, then the org.apache.soap.server.DefaultConfigManager
is used. The DefaultConfigManger saves the
list of deployed services to a file called
DeployedServices.ds in the current working
directory (or in the file specified by the
<option> element in the server configuration
file,) each time that a service is deployed
or undeployed. Upon initialization, the DefaultConfigManager
will attempt to read from this file to restore
its state information.
If you want to override the path and/or filename of the deployed services storage file for the DefaultConfigManager, then your SOAP server configuration file would look like the following:
<!-- Apache SOAP Server Configuration File -->
<soapServer>
<configManager value="org.apache.soap.server.DefaultConfigManager">
<option name="filename" value="config-file"/>
</configManager>
</soapServer>
where config-file is the path (either fully qualified or relative) and filename of the deployed services storage file.
If you find that the DefaultConfigurationManager is not meeting your needs, then you should create your own and use that one instead. All configuration managers must implement the org.apache.soap.util.ConfigManager interface, which is as follows:
public interface ConfigManager
{
public void setContext(ServletContext context);
public void setOptions( Hashtable options ) throws SOAPException ;
public void init() throws SOAPException ;
public void deploy( DeploymentDescriptor dd ) throws SOAPException ;
public String[] list() throws SOAPException ;
public DeploymentDescriptor undeploy( String id ) throws SOAPException ;
public DeploymentDescriptor query(String id) throws SOAPException ;
}
The methods:
void setOptions(Hashtable options) throws SOAPException
This method will be called with a Hashtable of name/value pairs that were specified via the <option> elements in the configuration file. In the event of an error a SOAPException should be thrown.
void init() throws SOAPException
This method will be called after the ConfigManager object is created, allowing any initialization to be done. For example, reading the DeployedServices.ds file. In the event of an error a SOAPException should be thrown.
void deploy(DeploymentDescriptor dd) throws SOAPException
This method will be called when a service is deployed (or redeployed). The service should be added to whatever internal data structure is used to store the list of services and that list should be persisted so that if the server is stopped the list can be reloaded upon startup. In the event of an error a SOAPException should be thrown.
String[] list() throws SOAPException
This method should return an array of String objects, one for each deployed service. In the event of an error a SOAPException should be thrown.
DeploymentDescriptor undeploy(String id) throws SOAPException
This method will be called when a service is undeployed. The should should be removed from whatever internal data structure is used to store the list and that list should be persisted so that if the server is stopped the list can be reloaded upon startup. In the event of an error a SOAPException should be thrown.
DeploymentDescriptor query(String id)throws SOAPException
This method should return a DeploymentDescriptor object representing the metadata about a service. In the event of an error a SOAPException should be thrown.
As is noted in the section above, your configuration manager can be passed parameters via <option> elements in the SOAP server configuration file.
Last updated 5/20/2001 by Bill Nagy <nagy@watson.ibm.com>.