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.

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 “The Asynchronous API” which discusses the shipped example located in the directory <installdir>\examples\webservices\Async.

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.

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:

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

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.

For an example using a secure transport, see “Add a Secure Transport.”

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:

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:

For a secure client to work, the service it is calling must be run on a server that understands HTTPS. See “Service Security”.

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.

See “Faults,” in Chapter 7 of the HydraExpress User Guide for more information.

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

There are five logging levels:

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

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:

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

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

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 “Architecture of the Notification Classes.”

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 “Client-Side Logging” for more information on client logging.