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 Web application's configuration
file. The option, ConfigFile, may be specified as either a context parameter
within the Web application, in which case
all of the servlets (and JSPs) will use the
value, or as a servlet initialization parameter,
in which case only that particular servlet
will see the value. If it is set in both
places, the servlet initialization parameter
value will override the value of the context
parameter for that particular servlet. (Note:
these parameters are set in the web-app
configuration file web.xml.) It
is recommended that you set the value via
a context parameter; the servlet initialization
parameter support was maintained mostly for
backwards compatibility. A servlet deployment
properties file with this modification would
look like the following:
<context-param>
<param-name>ConfigFile</param-name>
<param-value>config-file</param-value>
</context-param>
<context-param>
<param-name>XMLParser</param-name>
<param-value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</param-value>
</context-param>
<context-param>
<param-name>EnvelopeEditorFactory</param-name>
<param-value>class-implementing-org.apache.soap.transport.EnvelopeEditorFactory</param-value>
</context-param>
<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>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 are two settings currently allowed in the SOAP server configuration file: information about the Service Manager and information about the pluggable configuration manager. A SOAP server configuration file which sets information about both the Service Manager and the configuration manager 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 -->
<serviceManager>
<option name="SOAPInterfaceEnabled" value="boolean-value" />
</serviceManager>
<configManager value="config-manager" >
[<option name="option-name" value="option-value"/>]*
</configManager>
</soapServer>
where boolean-value is either true or false, depending upon whether or not you want the SOAP interface to the Service Manager to be enabled, and 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.
Although the SOAP interface for deploying/undeploying services can be very useful during development, it is not always desirable to expose such capabilities in a runtime environment. Apache SOAP provides the ability to enable/disable the SOAP interface to the ServiceManager by setting a boolean flag in the configuration file. If the flag is set to true, or if it is not present, then the SOAP interface is enabled. If it is set to false, then the ServiceManagerClient, as well as any other client which uses that interface, will not be able to communicate with the ServiceManager. However, anything which communicates with the ServiceManager directly, such as the admin JSP pages, will still be able to alter the state of the ServiceManager.
Access to the admin JSP pages can be controlled in a number of ways.
For maximum security, of course, the pages (and the entire admin
directory) can be removed from the deployment. Alternatively,
they can be secured through the web-app configuration file
web.xml. The following snippet, for example, can protect
the pages with a password. (Note: the method for defining users and roles can vary
between servlet containers.)
<!-- Define a Security Constraint on the Admin pages -->
<security-constraint>
<web-resource-collection>
<web-resource-name>Apache SOAP Administrator</web-resource-name>
<url-pattern>/admin/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<!-- NOTE: This role is not present in the default Tomcat users file -->
<role-name>manager</role-name>
</auth-constraint>
</security-constraint>
<!-- Define the Login Configuration for this Application -->
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Apache SOAP</realm-name>
</login-config>
Individual servlet containers and/or Web servers will typically have additional methods to limit access based on parameters such as client address. Tomcat 4, for example, has Valves for remote address and remote host filters.
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.