Supported operating systems are Windows 2000 and Windows XP.
The SOAP server is a Windows NT Service and is controlled via the "Services"
applet. In Win2K and XP, this is found under the "Administrative Tools" folder
in the Control Panel. Here the server can be started, stopped, etc.
The C++ SOAP server control panel app is found in the "White Mesa SOAP Server"
Program Group found in the Start Menu under "Programs". Of course the server
must be running for it to connect.
The browser based control panel app is available by pointing you browser to the
file cp_app.htm found in the docroot subdirectory. For remote
access, the SOAP server itself will gladly serve it up for you. If the server
is running on a host named "example.org" on port 80 then point your browser at
the URL "http://example.org/cp_app.htm".
Links to the browser based test clients for:
-
SOAP 1.1 "rpc" style tests (test-soap11/interop_index.htm)
-
SOAP 1.1 "document" style tests (test-soap11/interopdoc_index.htm)
-
SOAP 1.2 Test Collection (test-soap12/soap12-test-index.htm)
-
WS-Routing test (test-soap11/echoString_ws-rp.htm)
-
SOAP Digest Authentication tests (test-soap11/digest_auth_index.htm)
-
SOAP 1.1 and 1.2 "rpc/literal" tests (test-rpc-lit/rpc-lit-test-index.htm)
are found in the "White Mesa SOAP Server" Program Group found in the Start Menu
under "Programs".
The C++ DIME test client app is found in the Start Menu under "Programs", in
the same Program Group as the SOAP server control panel.
The installation will provide the WSDL files for supporting various services.
In the "port" element, contained within the "services" element of each of these
files, the URL for service access is given. As installed, these URL's will use
"localhost" (normally mapped to the loopback address 127.0.0.1) as the
hostname. It's a good idea to edit the URL (use Notepad) to replace this with
the proper hostname (mapped to the network IP address of the server machine).
Since the C++ control panel client app relies on finding the service URL in the
WSDL file for the control panel service, this must be done if it is to be run
on a different machine than the server. In this way remote monitoring and
control of the server is possible.
The control panel requires a user name and password that are used for the
Digest Authentication scheme. Such pairs are stored on the server machine in
the XML configuration file for the SOAP Digest Authentication Server auth-config.xml.
The installation creates a single such pair (or account) in which the user name
is "admin" and the password is "foo". This account exists in the security realm
"wmss@localhost", and the Control Panel application is assigned to this
security realm. Connecting to the server with the control panel app
immediately after installation requires typing "admin" in the "User ID" and
"foo" in the "Password" fields on the login dialog opened by the the control
panel when the "Connect" button is clicked.
To change the password, or create a new account, simply update the XML file auth-config.xml,
which is decribed in the documentation for the White
Mesa SOAP Digest Authentication Server. The authentication scheme is a
good demonstration of the server's header processing mechanism.
The server's configuration file:
This is found in the root installation directory along with the main server
executable file wmsoapsvc.exeand is named wmss-config.xml. The
server will not function if this file is renamed or is not present in the same
directory as the executable. It's a good idea to back it up regularly. Here is
an example configuration file as it would appear immediately after
installation. It can be divided into three sections:
-
A global properties section.
-
A list of service endpoint definitions.
-
A list of MIME type to file extension mappings.
Global properties:
-
The listenAddress
element may be used to specify the IP address (in dotted quad form, e.g.
127.0.0.1) of the interface that the SOAP Server is bound to at startup. If
empty then the first available interface is used. There is no default. It is a
value of type "string".
-
The listenPort
element contains the TCP port number at which the SOAP Server will be
listening. 80 is the default. It is an integer value.
-
The numWorkThreads
element specifies the number of working threads that will be spawned at startup
to handle socket i/o for the SOAP Server. 8 is the default. It is value of type
"int".
-
The maxClients
element specifies the number of concurrent client HTTP connections that are
allowed at any time. Once the number of active connections reaches this value,
the SOAP Server refuses further HTTP connection requests. The default is 16,
you may wish to tweak this to suit your situation. It is a value of type "int".
-
The clientTimeout
element specifies the maximum time in seconds that a client HTTP connection
will be kept open. Connections that exceed this time are forcibly closed by the
SOAP Server. The default is 60, you may wish to tweak this value to suit your
situation. It is a value of type "int".
-
The watchdogInterval
element specifies the interval in seconds between invocations of the watchdog
function which performs periodic housekeeping chores within the SOAP Server,
such as flushing log file buffers, etc. The default is 15. It is a value of
type "unsigned int".
-
The wsdlCacheSize
element specifies the size of the WSDL document cache. WSDL descriptions (or
rather the internal representation resulting from parsing the WSDL file) are
cached by the server to speed up processing, so that subsequent invocations of
the same service endpoint don't require a load and parse of the WSDL doc. You
may wish to tweak this value to suit your situation. The default is 20. It is a
value of type "int".
-
The docBasePath
element specifies the document root directory used by the SOAP Server when
servicing HTTP GET requests for document resources. The default is the path to
the "docroot" directory created by the installation program. It is a value of
type "string".
-
The defaultDocument
element specifies the default document to be returned for HTTP GET requests
when none is specified. The default is the path to the file "default.htm"
created by the installation program. It is a value of type "string".
-
The enableNameLookup
element specifies whether or not the SOAP Server will attempt to perform a
reverse DNS lookup on the IP address of a connecting client in order to write
it into the HTTP log. Enabling this feature results in a significant
performance degradation at runtime. The default is "false". It is a value of
type "boolean".
-
The enableServerLog
element specifies whether or not the SOAP Server's HTTP request log is enabled.
The default is "true". It is a value of type "boolean".
-
The serverLogPath
element specifies the path to the SOAP Server's HTTP request log. The default
is the path to the file "server.log" created by the installation program. It is
a value of type "string".
-
The enableTraceLog
element specifies whether or not the SOAP Server's SOAP message trace log is
enabled. The default is "false". It is a value of type "boolean".
-
The traceLogPath
element specifies the path to the SOAP Server's SOAP trace log. The default is
the path to the file "trace.log" created by the installation program. It is a
value of type "string".
-
The enableUserAgentLog
element specifies whether or not the SOAP Server's User Agent log is enabled.
The default is "false". It is a value of type "boolean".
-
The userAgentLogPath
element specifies the path to the SOAP Server's User Agent log. The default is
the path to the file "useragent.log.log" created by the installation program.
It is a value of type "string".
-
The logRotationInterval element specifies the interval in HOURS at which
any open log files are rotated. If the value is "0" then log rotation is
disabled. Rotated logs are renamed with the date and time of rotation encoded
in the filename. If a log named "server.log" is rotated, it will be named as
follows: server_yymmddHHMMGMT.log where "yy" is the year without century, "mm"
the month as a number 0-12, "dd" is the day as a number 1-31, "HH" the hour
0-24, "MM" the minute, and "GMT" indicates that this is GMT time. The default
is "0", i.e. no rotation. It is a value of type "unsigned int".
Service endpoint definitions:
These are created when configuring an new service with the Control Panel
application, and are usually maintained in the same way. Alternatively the same
may be done by editing the configuration file directly. Ill-formed service
endpoint definitions will be ignored by the SOAP Server.
-
The requestURI
element specifies the relative URI by which the service endpoint will be
invoked. For instance, if a service is defined with request URI "/foo" on host
"example.org" then a client would access the service using URL
"http://example.org/foo". URIs of the form "/foo/*" are allowed to support the
SOAP 1.2 "Web Method" feature. The significance of the wildcard character "*"
is that the SOAP Server will map any incoming request URI beginning with the
path component "/foo" to the service defined as "/foo/*". So a SOAP message
sent to URL "http://example.org/foo/bar/whatever" would be dispatched to that
service endpoint. The value must always begin with a leading "/" character. It
is a value of type "anyURI".
-
The wsdlService
element specifies the name of the WSDL "service" definition which applies to
the service endpoint. It is a value of type "string".
-
The wsdlPort
element specifies the name of the WSDL "port" definition which applies to the
service endpoint. The WSDL "port" must be contained within the WSDL "service"
definition mentioned above. It is a string value.
-
The wsdlDocURL
element specifies the URL of the WSDL document which contains the WSDL
"service" and "port" definitions mentioned above. The URL schemes "http://" and
"file://" are supported. The White Mesa SOAP Server and client side libraries
use this URL to load the WSDL document for the service at runtime. It is a
value of type "anyURI".
-
The bodyProcessingProgId
element specifies the ProgId of the COM component designated to process the
contents of the SOAP Body element for the service. It will implement the
methods of an "rpc" style service, or process the literal Body element contents
for a "document" style service. It may be empty for a service acting only as an
intermediary. It is a value of type "string".
-
The headerProcessingProgIds
element specifies a list of zero or more ProgIds identifying Header processors
to be called by the SOAP Server during message processing. The list consists of
a sequence of "progId" elements, of type "string".
-
The roles
element specifies a list of zero or more URIs whose purpose is establish which
roles are supported by the service. The SOAP Server uses this information to
determine which Header blocks are targeted at the service during Header
processing. The list consists of a sequence of "uri" elements of type "anyURI".
-
The nodeURI
element specifies the absolute URI of the service. The SOAP Server uses this
information when generating Fault messages for the service if it is acting as
an intermediary. For instance, if a service is defined with request URI "/foo"
on host "example.org" then the nodeURI should be specified as
"http://example.org/foo". This value may be empty if the service acts only as
the ultimate receiver in a message path. It is a value of type "anyURI".
-
The nextHopURL
element specifies the URL of the next SOAP processing node in the message path
if the service is intended to act as an intermediary. This value MUST be empty
if the service acts only as the ultimate receiver in a message path. It is a
value of type "anyURI".
-
The enabled
element specifies whether or not the service is enabled. If the value is
"false", request messages directed at the service endpoint result in an HTTP
404 "Not Found" error. In this way a service can be turned "on" or "off" as
needed. It is a value of type "boolean".
-
The enableExplictTyping
element specifies whether or not the SOAP Server places explicit typing
information (e.g. xsi:type="xsd:string") on accessor elements in SOAP RPC
response messages. This is a "compatibility" mode which may be necessary to
interoperate with clients who depend on the presence of explicitly typed method
parameters to process the response correctly. This setting has effect only if
the service is an "rpc" style service. The default is "false". It is a value of
type "boolean".
-
The enableNodeType element specifies whether or not the SOAP Server
places SOAP 1.2 "nodeType" information (e.g. enc:nodeType="struct") on accessor
elements in SOAP RPC response messages. This is a "compatibility" mode which
may be necessary to interoperate with clients who depend on the presence of
this information to process the response correctly. This setting has effect
only if the service is a SOAP 1.2 "rpc" style service. The default is "false".
It is a value of type "boolean".
MIME type mappings:
The mimeMappings element contains a sequence of "item" elements, each of
which specify an association between a MIME media type and a filename
extension. The filename extension is found in the "extension" element, and the
associated MIME type in a "mimeType" element. Normally these mappings are
maintained using the Control Panel application. The SOAP Server uses this
information when processing HTTP GET requests for document resources. A number
of mappings for common filename extensions are created by the installation
program.
