Customizing JAX-WS handlers for web services

You can set up custom server and client side handlers for JAX-WS web services.

By default, Sterling™ Order Management System Software applies handlers to JAX-WS web services. When JAX-WS web services are created (during ear build), one of the following scenarios occurs:
  • Default handlers are applied (default scenario)
  • Custom handlers that you provided are applied
  • Handlers are not applied because you set the sandbox.cfg variable SUPPRESS_JAXWS_HANDLERS to true
This topic includes information to help you set up customized server and client side handlers for JAX-WS web services.

Using custom server-side handlers

During the ear build, when JAX-WS web service creation occurs, Sterling Order Management System Software looks for custom extensions and uses them if they exist. You can provide extensions per each JAX-WS bean. To use custom handlers, you must provide two files:
  • install_dir/extensions/webservices/BeanName/server/BeanName/Handlers.xml - the handler chain XML file for the server.
  • install_dir/extensions/webservices/BeanName/server/BeanName/Handlers.jar - a JAR file that contains the classes mentioned in the handler chain xml file.

The Handlers.xml file is not optional. It must be supplied on a per bean basis. However, the build scripts do not fail if the JAR file is not provided. This enables you to give a single JAR file that implements the handlers for multiple different beans. In case the same handlers are used across beans, copy and rename the Handlers.xml file into each JAX-WS bean extension directory that is mentioned above.

Additional jar files (which might be required by the custom implementation to call into third party libraries) are also picked up from the following location:
install_dir/extensions/webservices/BeanName/server/
Note: The libraries that you provide are placed in the WEB-INF/lib of the JAX-WS war file. Overlapping JAR file names are not permitted unless the JAR files are identical.

During the ear build, when JAX-WS web service creation occurs, Sterling Order Management System Software looks for custom extensions and use them if they exist. If they do not exist, default handler XML and handler classes are built into the ear and used.

Using custom client side handlers

By default, Sterling Order Management System Software injects a default set of non-operational client side handlers, or you can use custom handlers.

To use custom handlers, provide the following two files:
  • install_dir/extensions/webservices/BeanName/client/BeanName/Handlers.xml - the handler chain XML file for the client
  • install_dir/extensions/webservices/BeanName/client/BeanName/Handlers.jar - a jar file that contains the classes mentioned in the handler chain xml file
Note: Because Sterling Order Management System Software builds annotations into the web services client service classes, the handler XML and associated classes must be available at runtime.

Sterling Order Management System Software builds a JAR file into the jaxwsclient directory that can be used to provide the handler XML. This JAR file is install_dir/jaxwsclient/output/BeanName/BeanName.jar.

You must add this JAR file to the classpath for any command line scripts or debug runtimes for JAX-WS clients.

If you want custom handlers, the author of the client code should provide the classes called out by the handler XML.