Setting the handler chain in the Web Service

To set the handler chain in the Web Service, annotate the SEI, Web Service Implementation Class, or the Provider Implementation Class using the javax.jws.HandlerChain annotation and specify the handler chain setup file using the file element of the javax.jws.HandlerChain annotation.

The following is an example of annotating the Web Service Implementation Class using the javax.jws.HandlerChain annotation:

package com.sample;
 
@javax.jws.WebService
@javax.jws.HandlerChain(file="handlers.xml")
public class AddNumbersImpl{
 
 public int add( int number1, int number2 ) throws AddNumbersFault{
 ...
 }
 
}

In this example, the handler chain defined in the handler chain setup file handlers.xml is linked with the Web Service Implementation Class com.sample.AddNumbersImpl.

A handler chain setup file is required for each Web Service. A handler chain setup file might also be shared by multiple Web Services, but in that case, the same settings are applied.

For details about the javax.jws.HandlerChain annotation, see the subsection 16.2.3 javax.jws.HandlerChain annotation.

Organization of this subsection: (1) Handler chain setup file; (2) SOAP role and actor settings; (3) soap:mustUnderstand attribute settings

The handler chain setup file defines the handler chain configuration when the handler is used to add processing for the Web Service. The file is specified using the file element of the javax.jws.HandlerChain annotation.

For details about the support range of the handler chain setup file, see the subsection 19.4 Support range of the handler chain setup file. This point describes the syntax and deployment of the handler chain setup file.

(a) Syntax of the handler chain setup file

Code the syntax of the handler chain setup file in the range supported by the standard schema of Java EE 5 specifications (Java EE Web Services Metadata Handler Chain Schema) and the Cosminexus JAX-WS functionality.

You can reference the standard schema by accessing the namespace URI of Java EE 5 (http://java.sun.com/xml/ns/javaee/). The following is an example of coding of the handler chain setup file:

<?xml version="1.0" encoding="UTF-8"?>
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
 <handler-chain>
 <handler>
 <handler-class>org.test.handler.LoggingHandler</handler-class>
 </handler>
 </handler-chain>
</handler-chains>

(b) Deployment of the handler chain setup file

Store the handler chain setup file at the following locations:

In POJO Web Services: Under the WEB-INF directory of WAR file.
In EJB Web Services: EJB JAR

The deployment of the file complies with the file system limitations for the OS and Java EE 5 specifications, and if the file can be stored in the WAR file or EJB JAR file, there are no limitations on the file name, the directory name below the WEB-INF directory, EJB JAR directory name, and the path length.

36.9.1 Setting the handler chain in the Web Service

(1) Handler chain setup file

(a) Syntax of the handler chain setup file

(b) Deployment of the handler chain setup file

(2) SOAP role and actor settings

(3) soap:mustUnderstand attribute settings