8.3 Further Options

The Agent creates threads as necessary to handle incoming requests, and multiple threads may enter a servlet at the same time. Objects supplied as parameters to the overridden virtual methods are guaranteed to be active in only a single thread. However, if the servlet maintains state, it must take appropriate precautions to ensure thread safety. See Section 7.5, "Recovering Session State," in the HydraExpress Servlet Development Guide for details.

Because services created with HydraExpress run in multiple threads, it is recommended that you allocate objects on the heap rather than the stack, a general "best practice" for multithreaded applications. This prevents problems with thread stack size.

For an example of creating a secure service, see Chapter 4, "Extending Your Web Service."

---

Using the HTTPS protocol results in a dependence on the OpenSSL third-party library.

---

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 file.

For a discussion on exceptions for both the client and server, as well as WSDL-defined faults, see Section 7.3.3, "WSDL-Defined Faults," in the HydraExpress User Guide.

HydraExpress allows you to implement your service as a standalone server, independent from the Agent. To take advantage of this feature, use the -standalone option when generating code in order to generate a sample standalone server.

For more information, see Section 23.3, "Standalone Server Implementations."

For server-side code, use the Agent logger, which is best for logging events from services, connectors, transports, and handlers. This book does not include a detailed discussion on using the Agent logger; rather, please see Section 6.2.2, "Using the Default Logger in a Service," in the HydraExpress User Guide.

The Web services logger may provide some use while debugging, as it logs some Fatal and Error level messages. See Section 12.4.2 for more information.

The server-side code generated by HydraExpress provides support for session management in Web services. For information on session management in the HydraExpress-generated classes, see Chapter 18, "Sessions and State."

You can generate code using the -wrapped option, as follows:

prompt>rwsfgen -wrapped -projectname Wrapped MyWSDL.wsdl

The resulting generated service operation method for the prevDay operation would not include the complex type sns::PreviousDay at all, instead using its elements Unit and identifier as parameters:

void BusinessDayPortTypeImp::prevDay( rwsf::CallInfo& callInfo, const std::string& Unit_in, int identifier_in) { ... }

By comparison, the same WSDL without the -wrapped option results in a generated service operation method that takes an input parameter of type sns::PreviousDay, as follows:

void BusinessDayPortTypeImp::prevDay(rwsf::CallInfo& callInfo, sns::PrevDay input_in);

Some WSDLs cannot be used with the -wrapped option. If this is the case, the HydraExpress Agent will return an error:

WARNING: WSDL file: C:\RogueWave\HydraExpress\examples\webservices\DayOfWeek\DayO fWeek.wsdl is NOT eligible for wrapped style.

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 in the service's handler configuration file. (For more customizations to configuration files, see Section 8.3.11).

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

To reset this property on the server side, set the RWSF:doEscape property to false in the server-side configuration file <servicecontextname>_handlers.xml. (For more information on this handlers file, see Section 8.3.11.3.)

By default the RWSF:doEscape property is "true".

To turn off text escaping, add the RWSF:doEscape property to <servicecontextname>__handlers.xml and set it to "false". For instance, given the DayofWeek example:

<configuration> <service name="DayOfWeekPortService"> <request-handlers> <handler name="http://localhost:8090/dayofweek/DayOfWeekSkeleton"> <property name="RWSF:doEscape" value="false" /> </handler> </request-handlers> ... </service> </configuration>

The service implementation may access the URL for requests that arrive via HTTP or HTTPS from the rwsf::CallInfo object.

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, so you don't have to deal with them unless you wish to customize your application.

The ability to use configuration files to link a transport with a service, or a service with a binding, effectively decouples these objects in your application. This allows you to change how your service works without changing your binding, or to use a new service with the same binding, or to change any number of other elements in your application without having to regenerate code or recompile.

The primary configuration files on the server side are

• the transports configuration file: transports.xml

• the servlet configuration file: servicecontextname_web.xml

• the service chains configuration file: servicecontextname_handlers.xml

• the named objects configuration file: servicecontextname_objects.xml

The transports.xml file includes all available transports for your service. This file is not generated, but rather copied from the template files in the <installdir>\conf\webservice directory each time the code generator is invoked. Use this file to configure additional transports that you have included in your application, or to customize existing transports.

For more information, see Chapter 11, "Custom Transports and Listeners."

The <servicecontextname>_web.xml file includes servlet configuration information. This includes

• a definition of the servlet

• the name of the configuration file that defines the particular service (or services) that the servlet uses

• other optional parameters

When you deploy your service, HydraExpress copies all config files, including this <servicecontextname>_web.xml file to the appropriate context directory in your <installdir>\apps\servlets directory.

For more information on this file and defining servlets, see Section 23.4, "About the Servlet Used by the Service."

Following is the contents of dayofweek_web.xml.

<web-apps> <servlet> <servlet-name>DayOfWeekPortService</servlet-name> 1 <servlet-class>rwsf_webservice_servlet.createWebServiceServlet </servlet-class> <init-param> <param-name>configFile</param-name> 2 <param-value>handlers.xml</param-value> </init-param> <init-param> <param-name>serviceName</param-name> 3 <param-value>DayOfWeekPortService</param-value> </init-param> <init-param> <param-name>wsdlFileName</param-name> 4 <param-value>DayOfWeek.wsdl</param-value> </init-param> <servlet-mapping> 5 <servlet-name>DayOfWeekPortService</servlet-name> <url-pattern>/DayOfWeek/*</url-pattern> </servlet-mapping> </servlet> ... </web-apps>

For more information on setting a timeout value for your session, see Section 18.4, "Configuring Session Timeouts." For more information, on error pages, see Section 4.11, "Configure Error Pages," in the HydraExpress Servlet Development Guide.

The configuration file <servicecontextname>_handlers.xml is generated as part of the server side components. It chains together the handlers for this service and contains initialization parameters. For more information on handlers, see Chapter 14, "SOAP Message Handlers."

Following is an excerpt from dayofweek_handlers.xml:

<configuration> <service name='DayOfWeekPortService'> 1 <request-handlers> 2 <handler name='http://localhost:8090/dayofweek/DayOfWeekSkeleton'/> </request-handlers> <transport-handlers/> <service-endpoint name='http://localhost:8090/dayofweek/DayOfWeek'/> 3 <response-handlers/> <fault-handlers/> </service> </configuration>

A named object is a unit of compiled code with a name that allows it to be found and used by any service within a given service context. The configuration file for defining named objects is <servicecontextname>_objects.xml.

HydraExpress uses this mechanism for service execution. You can also use it to load and use objects that extend your services in a limitless variety of ways. The code can be a small, self-contained bit of functionality, or it might be an entry point to a large back end application, or anything in between.

For more information on named objects, see Chapter 16, "Named Objects."

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

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.