Using JAX-WS handlers

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 have set the sandbox.cfg variable SUPPRESS_JAXWS_HANDLERS to true

About the default JAX-WS handlers

Sterling Order Management System Software applies default handlers for JAX-WS based web services whenever customized handlers are not provided and the sandbox variable to suppress handlers is not enabled. The handler chain xml and handler classes provided are different for the server side and client side.

Default server side handler

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

The default server side handler is a logical handler. The payload for JAX-WS based web services contains an <env element with username, password and token information on it, which can be used by the handler as follows:
  1. The default handler intercepts the payload and introspects the environment XML provided.
  2. If there is no token, it parses the userId and password from the environment.
  3. The authentication details are used to invoke the login API.
  4. Assuming the login executes successfully, the token is taken from the login API response and put into the environment.
  5. The modified environment gets put back into the payload and the desired API is then called.

Default client side handler

For client generation, Sterling Order Management System Software applies a default handler chain, or you can provide custom handlers.

Sterling Order Management System Software provides a client generator for JAX-WS web services. When run, the client generator checks for custom handlers. If they are available, they will get plugged in Sterling Order Management System Software.

By default, Sterling Order Management System Software will inject a default set of non-operational client side handlers. Add the platform_afc.jar to the classpath to provide the Sterling Order Management System Software default handler classes.

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 into the jaxwsclient directory that can be used to provide the Handler XML. This jar is install_dir/jaxwsclient/output/BeanName/BeanName.jar.

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

Customizing handlers

Handlers can be used to perform a variety of security related tasks. The out of the box handlers provided by Sterling Order Management System Software give a basic application level authentication and api-security tie-ins without requiring invocation of the login api. This provides a minimum level of security out of the box. But it does not provide a means of calling out to an external system of record for users. Nor does it provide any level of confidentiality for the message itself except with transport security is used.

It is recommended that additional custom handlers by applied which authenticate through a external system such as LDAP depending upon site requirements. An additional level of confidentiality can also be achieved by adding custom handlers which use hashing and/or shared key encryption techniques to obfuscate/encrypt the payload of the message.