Usage |
|
Usage |
|
|
To use the Wrapper program, you first need to initialize it with one or more service configurations. If you're going to be using message signing or encryption you also need a key/public certificate pair which will be accepted by whichever services you're going to use. Then you just need to submit requests to the Wrapper with some header information to identify the target service and, optionally, proxy configuration information for accessing the service. The response from the Wrapper for each request includes both completion information from the Wrapper and the actual response from the service, if appropriate. The Wrapper stores its key/certificate pair and service configuration information in the file system. You can work directly with these files, but generally it's easier to control these parameters via the Web management console. The Web management console also provides control over the logging level, and allows you to test service operation. Web Management ConsoleThe Web management console is hosted at http://{host}:{port}/control, where {host} is the name or IP address of the system hosting the Wrapper and {port} is the configured port number (see Configuration). Several different aspects of the Wrapper configuration and operation are controlled via the console. Wrapper CertificateThe Wrapper program needs to use a private key and public certificate pair for signing messages sent to a service, and for decrypting messages received back from a service. The first item shown on the Web management console is the details of the certificate currently in use by the Wrapper. Along with this is an option to "Upload Replacement Certificate". This option leads to a separate page where you can select a zip file to be uploaded, containing a private key and certificate pair in the form of a file with a .pfx extension and the corresponding password in the form of a file with a .txt extension. The most-recently uploaded wrapper configuration zip file is stored to the file system as wrapper-conf.zip in the root directory of the Wrapper installation. If present, this file is read when the Wrapper begins execution to set the initial certificate information. Configured ServicesThe second item shown in the Web management console is the list of configured services. For each service, the certificate information is shown along with the message security property settings. A "Delete" link is also provided, which lets you remove the service from the Wrapper's configuration. Service configurations are stored in zip files. The name of the zip file is the alias of the service (converted to lowercase to prevent issues with filesystems which don't support mixed case names). Each service configuration consists of a required file with the .properties extension (the actual name doesn't matter, only the extension) along with any of several optional files. The optional files are:
The .properties values control the security handling used for messages to and from the service. The defined properties are:
Service configuration zip files are stored in the services subdirectory of the Wrapper installation root directory. Normally the zip files in this subdirectory are managed by the Web management console, but they can also be accessed directly (though any changes will only take effect when the Wrapper is restarted). Following the list of configured services the Web management console gives a link for "Upload service configuration". This link lets you add a service configuration zip file using the browser interface. When a service configuration is added using this link it is stored to the services subdirectory so that it is present when the Wrapper is restarted. The Wrapper associates service configurations with particular Web services by matching the alias name given (the name of the configuration zip file) with the service name in the WSDL service definition (the "name" attribute value on the <wsdl:service> element start tag). The name comparison is done with both names converted to lowercase. Audit ControlFollowing the service information, the Web management console gives a section of logging controls. The first set of controls give a choice of logging levels, as either "Debug", "Info", or "Error". These are the same as the logging levels defined by the log4j.properties file (see Configuration), but while the properties file is only read when the Wrapper begins execution the selection buttons here take effect immediately. Selecting the "Debug" setting means the raw message text is included in the logs. The second set of controls just switch persisting of incoming message on ("Enable") and off ("Disabled"). When enabled, the most recent incoming message is saved to a file sent2wrapper.xml in the root directory of the Wrapper installation. Logging or dumping message text is a significant security risk, since it preserves the message data in raw form on the system hosting the Wrapper. These options are intended only for use in debugging. TestingThe final portion of the Web management console display gives a link for testing a service. This takes you to a separate web page where you can enter a service WSDL URL, optional proxy configuration, and an actual request message to be sent to a service. This web page allows you to simulate a client application using the Wrapper to access a service. The service WSDL URL and the actual test message are persisted by the Wrapper, so when you come to this page you'll see the same values you entered the last time you tested a service. Submitting a requestTo send a request to the Wrapper (and on to the destination service), you need to issue an HTTP POST request to the URL http://{host}:{port}/wrapper, where {host} is the host name or IP address and {port} is the configured port number (see the Configuration page for details on this). The POST data is an XML message in a particular form, with a <request> root element and a <service> child element, optionally followed by a <proxy> element, and then by the request data to be sent to the service (the content for the <SOAP:Body> element of the request). The Wrapper code includes a test program that gives example code for making
the request and processing a response, the
POST /wrapper HTTP/1.1 Content-type: text/xml Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.5.0_07 Host: 127.0.0.1:7123 Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 1020 <request> <service>http://example.com/webservices/DRI-DriServiceX509-Tst-01.00.00.wsdl</service> <Message xmlns="urn:moe:dri:driservice:2.0.0"> <type>1</type> <version>1</version> <parameters> <meta> <location>Paraparaumu</location> <user>Dennis</user> <date>2005-12-30</date> <time>23:50:40</time> </meta> </parameters> <data> <message>abcdefghijklmnop</message> </data> </Message> </request> The first part of the capture shows the actual HTTP headers, followed by the XML message to the Wrapper (the <request> element and content). The <service> element gives the location of the WSDL service description, which must be accessible to the Wrapper. The Wrapper reads this WSDL in order to find both the service name (the "name" attribute value on the <wsdl:service> element start tag) and the endpoint address to use to access the service (the "location" attribute value on the <soap:address> element, within the <wsdl:port> element, within the <wsdl:service> element). In this case the <service> element in the request message is directly followed by the message data to be sent to the service, the <Message> element and content. This works fine as long as both the WSDL and the actual service endpoint are directly accessible to the Wrapper. If a proxy is needed for access to either the WSDL or the service, you can give the proxy configuration information to the Wrapper using a <proxy> element immediately following the <service> element in the request. Here's the format of this element:
<proxy>
<address>192.168.1.17</address>
<port>127</port>
<user>username</user>
<pass>password</pass>
</proxy>
If the <proxy> element is used, the <address> and <port> child elements are always required. The <user> and <pass> elements are optional, but if one is present they both must be present. All the child elements must be in the order shown. Receiving a responseThe Wrapper returns a response to your request once it has completed processing of the message (which may take anywhere from several seconds to potentially minutes, depending on the size of your message data and the speed of the connection to the service). The response indicates success or failure, and also gives the returned data from the service in the case of success, or an error code and message in the case of failure. Here's the capture of a response returned to the test program:
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Connection: keep-alive
Server: Jetty(6.0.1)
C0
<response>
<success>
<MessageResponse xmlns="urn:moe:dri:driservice:2.0.0">
<MessageResult>
<ack>
<code>0</code>
<info>OK</info>
</ack>
</MessageResult>
</MessageResponse>
</success>
</response>
0
This response is reporting the successful completion of the request to the service, with the <MessageResponse> element and content the actual data returned by the service (the content of the <SOAP:Body> element of the response). The "C0" value before the XML response, and the "0" after, come from the HTTP/1.1 chunked encoding, and are not part of the actual data. As a failure response example, the following is the XML body (with HTTP headers and chunking removed) returned by an attempt to access a WSDL from an invalid host name:
<response>
<fail>
<error-code>WSDL01</error-code>
<error-text>Error reading service WSDL: xxx.example.com</error-text>
</fail>
</response>
The <error-code> gives a simple code name for the problem, while the <error-text> gives specific details of the problem encountered. The full list of error codes reported by the Wrapper are defined in the following table. Error codes and causes
|