1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<HEAD>
<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
<TITLE>Configuring the Apache SOAP Server</TITLE>
</HEAD>
<BODY bgcolor="#ffffff">
<h2 align="center">Configuring the Apache SOAP Server</h2>
<h3> Configuration File </h3>
<P>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.)<BR>
</P>
<P>For HTTP transport listeners, this option
can be set in the configuration file for
the rpcrouter servlet by adding an init-parameter
called <I>ConfigFile</I> to the servlet's deployment properties file.
A servlet deployment properties file with
this modification would look like the following:<BR>
</P>
<pre> <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><B><I>config-file</I></B></param-value>
</init-param>
</servlet></pre>
<P>where <B><I>config-file</I></B> is the path (either fully qualified or relative)
and filename of the SOAP configuration file.<BR>
</P>
<p><A name="configfile"></A>There are two settings currently allowed
in the SOAP server configuration file: information
about the Service Manager and information
about the <a href="#pcm">pluggable configuration manager</a>. A SOAP server configuration file which
sets information about both the Service Manager
and the configuration manager would look
like the following:<pre> <!-- 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="<B><I>boolean-value</I></B>" />
</serviceManager>
<configManager value="<B><I>config-manager</I></B>" >
[<option name="<B><I>option-name</I></B>" value="<B><I>option-value</I></B>"/>]*
</configManager>
</soapServer></pre>
<P>where <B><I>boolean-value</I></B> is either true or false, depending upon
whether or not you want the SOAP interface
to the Service Manager to be enabled, and
<B><I>config-manager</I></B> 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 <B><I>option-name</I></B> and<B><I> option-value</I></B> acting as key/value pairs.</P>
<HR>
<H3><A name="smaccess">Controlling Access to the ServiceManager</A></H3>
<P>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 <A href="#configfile">configuration file</A>. 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.
</P>
<HR>
<h3><A name="pcm"/>Pluggable Configuration Manager</A></h3>
<P>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.<BR>
<BR>
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.</P>
<P>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:</P>
<PRE> <!-- Apache SOAP Server Configuration File -->
<soapServer>
<configManager value="org.apache.soap.server.DefaultConfigManager">
<option name="filename" value="<B><I>config-file</I></B>"/>
</configManager>
</soapServer></PRE>
<P>where <B><I>config-file</I></B> is the path (either fully qualified or relative)
and filename of the deployed services storage
file.</P>
<H4>Creating a Configuration Manager</H4>
<P>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:</P>
<PRE>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 ;
}</PRE>
<p>
<b>The methods:</b>
<blockquote><p>
<code><b>void setOptions(Hashtable options) throws SOAPException</b></code><br>
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.</blockquote><p>
<blockquote><p>
<code><b>void init() throws SOAPException</b></code><br>
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.</blockquote><p>
<blockquote><p>
<code><b>void deploy(DeploymentDescriptor dd) throws SOAPException</b></code><br>
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.
</blockquote><blockquote><p>
<code><b>String[] list() throws SOAPException</b></code><br>
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.
</blockquote><p>
<blockquote><p>
<code><b>DeploymentDescriptor undeploy(String id) throws SOAPException</b></code><br>
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.
</blockquote><p>
<blockquote><p>
<code><b>DeploymentDescriptor query(String id)throws SOAPException</b></code><br>
This method should return a DeploymentDescriptor object representing the
metadata about a service. In the event of an error a SOAPException
should be thrown.
</blockquote><p>As is noted in the section <A href="#configfile">above</A>, your configuration manager can be passed
parameters via <option> elements in
the SOAP server configuration file.
<P>Last updated 6/28/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
</HTML>
|
