Further Options

HydraExpress Web Service Development Guide
Rogue Wave web site: Home Page | Main Documentation Page

7.3 Further Options

A production application that uses a client proxy may require the addition of various features, such as asynchronous processes, multithreading, dynamic transports, and error handling. This section discusses various options available when creating a client.

7.3.1 The Asynchronous Client API

In a typical synchronous process, the client sends a request to the server and the server responds. The requestor, or client, blocks and waits for the response. This process works well when the server response is immediate. However, if the response is delayed, client execution halts until it arrives.

In an asynchronous process, the client can perform other work while waiting for a response that may be delayed. The asynchronous API implements this by creating a thread for each call to a service operation method. The method returns a handle to an object that can be polled to determine when the response is available. Once the response is available, a <servicecontextname>End() method is used to retrieve the response data.

For a discussion on how to create an asynchronous client, see Section 13.2, "The Asynchronous API," which discusses the shipped example located in the directory <installdir>\examples\webservices\Async.

7.3.2 Multithreading

A HydraExpress client proxy is multithread-hot. A proxy may create threads as necessary to handle requests to the server. However, the proxy itself is not designed to accept simultaneous requests from multiple threads. A multithreaded application that shares a client proxy amongst threads must protect the proxy from simultaneous access.

If you are a SourcePro customer, we recommend using the classes provided by the Threads Module of SourcePro Core, to synchronize access to a proxy shared among threads.

7.3.3 Transports

By default, the client proxy uses the transport specified in the WSDL. The transport is not code generated and is not hard-coded into the proxy; instead, each type of transport is provided separately in a shared library, and the transport configuration file is copied to your <project-directory>\conf directory at code generation from the templates in <installdir>\conf\webservices.

Transports for clients are defined in the configuration file client-transports.xml. This file contains definitions for HTTP, HTTPS, and AJP13, and you can also create other, custom transports (Chapter 11). At runtime, the client executable processes the client-transports.xml file so it knows what transports are available to it.

You have two options to use a non-default transport with your client:

When calling the client application, specify an alternative location on the command line. If the location implies a different transport, the client uses that transport to send the message.
In the client implementation, obtain a particular transport object based on its name attribute in the client-transports.xml file, and pass that transport in the call to the proxy's make() method.

7.3.4 Client Security

HydraExpress supports security on the client in two ways: through authorization, and through support for HTTPS.

7.3.4.1 Authorization

The generated client proxy supports authorization through two properties set on the transport. If you set these properties on the transport before invoking the service, the request is sent with an HTTP authorization header.

proxy.setTransportProperty("user", myUser);
proxy.setTransportProperty("password", myPassword);

For an example using a secure transport, see Section 4.2, "Add a Secure Transport."

7.3.4.2 HTTPS Support

Nothing special is required to generate a service that supports a secure client. An HTTPS transport is one of the standard transports supplied with HydraExpress. If the WSDL for a service designates an HTTPS port in its location attribute, such as:

location="https://localhost:8443/<path_to_service>"

then the sample client generated by HydraExpress uses the HTTPS transport by default.

The HTTPS transport can also be selected at runtime in either of two ways:

by invoking the client with a location that specifies an HTTPS port:

by explicitly selecting the HTTPS transport in the client implementation:

rwsf::Transport transport;
transport = rwsf::TransportManager::findTransport("HTTPS");
MyServiceProxy proxy = MyServiceProxy::make(transport);

For a secure client to work, the service it is calling must be run on a server that understands HTTPS. See Section 8.3.2.

Using the HTTPS protocol results in a dependence on the OpenSSL third-party library. In addition, the HTTPS transport sets the application to ignore SIGPIPE signals in order to prevent failures when attempting to perform SSL handshakes on closed sockets.

7.3.5 Error Reporting and Faults

HydraExpress handles server and client exceptions through rwsf::Exception or one of its derived classes, and SOAP faults through an instance of rwsf::SoapFaultException or one of its generated derivations if a fault is specified in the WSDL.

A WSDL file can define faults to be handled in the server and returned to the client.

One or more faults may be defined for each operation defined in the WSDL. HydraExpress creates a class for each unique fault message type defined. Several faults can use the same message format, so messages are the critical definition needed by HydraExpress to create a mechanism for returning faults to the client.

If faults are defined in the WSDL, the client-side sample application code HydraExpress generates contains catch blocks for each operation, with one catch block for each defined fault message type.

This discussion reflects a traditional request-response operation. For a solicit-response operation, faults would be handled on the client and returned to the server.

See Section 7.3, "Faults," in the HydraExpress User Guide for more information.

7.3.6 Client-Side Logging

HydraExpress supports both client-side and server-side logging. Logging is implemented in the sample applications by default.

There are five logging levels:

None
Info
Warning
Error
Fatal

The default logging level is info, resulting in all messages reported. See Chapter 12, "Web Service Logging," for detail on using or customizing loggers.

7.3.7 Turning off Text Escaping to Improve Performance

If you are certain that the data you are sending will not contain any special characters that must be escaped, you may get better performance in your applications by setting the property RWSF:doEscape to false.

This property controls whether or not the client escapes content when writing responses. The default is true.

To reset this property on the client side, call the setProperty() method from the proxy, as follows:

proxy.setProperty("RWSF:doEscape","false");

To turn escaping back on, call setProperty() again:

proxy.setProperty("RWSF:doEscape","true");

7.3.8 Customizing the Client Configuration Files

Among the generated files are a series of XML-based configuration files. Using the configuration files allows you to build a high degree of flexibility into your application. HydraExpress generates these configuration files automatically based on default values in the WSDL.

The primary configuration files on the client side are

the transports configuration file: client-transports.xml, discussed in Section 7.3.3

handlers configuration file: client-handlers.xml

In addition, a client-objects.xml file is generated if the WSDL provided to HydraExpress at code generation includes the message pattern notification. This section discusses the above two files. For more information on notification and the client-objects.xml file, see Section 9.3, "Architecture of the Notification Classes."

7.3.8.1 Handlers Configuration File: client-handlers.xml

The configuration file client-handlers.xml is generated as part of the client side components. While this file chains handlers on the server side, on the client side it is used only to configure a logger for the client. See Section 7.3.6, "Client-Side Logging," for more information on client logging.

The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.