3.3.1. Web Service Components

This specification defines two means for implementing a Web service, which runs in a J2EE environment, but does not restrict Web service implementations to just those means. The first is a container based extension of the JAX-RPC programming model which defines a Web service as a Java class running in the Web container. The second uses a constrained implementation of a stateless session EJB in the EJB container. Other service implementations are possible, but are not defined by this specification.

3.3.2. Web Service Containers

The container provides for life cycle management of the service implementation, concurrency management of method invocations, and security services. A container provides the services specific to supporting Web services in a J2EE environment. This specification does not require that a new container be implemented. Existing J2EE containers may be used and indeed are expected to be used to host Web services. Web service instance life cycle and concurrency management is dependent on which container the service implementation runs in. A JAX-RPC Service Endpoint implementation in a Web container follows standard servlet life cycle and concurrency requirements and an EJB implementation in an EJB container follows standard EJB life cycle and concurrency requirements.

3.6.1. JAX-RPC

JAX-RPC provides run-time services for marshalling and demarshalling Java data and objects to and from XML SOAP messages. In addition, JAX-RPC defines the WSDL to Java mappings for a Service Endpoint Interface and a Service class.

3.8.1. Scope

• The scope of this specification is limited to Web service standards that are widely documented and accepted in the industry. These include:

  • SOAP 1.1 and SOAP with Attachments

  • WSDL 1.1

  • UDDI 1.0

• This specification is limited to defining support for SOAP over HTTP 1.1 or HTTPS protocols and communication APIs for Web services (vendors are free to support additional transports).

• These standards are expected to continue to change and evolve. Future versions of this JSR will accommodate and address future versions of these standards. In this specification, all references to SOAP, WSDL, and UDDI are assumed to be the versions defined above.

3.8.2. Not in Scope

• The most glaring deficiency of SOAP over HTTP is basic reliable message semantics. Despite this deficiency, this JSR does not consider Message Reliability or Message Integrity to be in scope. Other JSRs, like the evolution and convergence of JAX-M and JMS, as well as activities in W3C and other standard bodies will define these capabilities.

• Persistence of XML data.

• Workflow and data flow models.

• Arbitrary XML transformation.

• Client programming model for Web service clients which do not conform to this specification.

4.2.1. Service Lookup

The client developer is required to define a logical JNDI name for the Web service called a service reference. This name is specified in the deployment descriptor for the client. It is recommended, but not required that all service reference logical names be organized under the service subcontext of a JNDI name space. The container must bind the Service Interface implementation under the client's environment context, java:comp/env, using the logical name of the service reference. In the following examples, the logical service name declared in the client deployment descriptor is service/AddressBookService.

The container acts as a mediator on behalf of the client to ensure a Service Interface is available via a JNDI lookup. More specifically, the container must ensure that an implementation of the required Service Interface is bound at a location in the JNDI namespace of the client's choosing as declared by the service reference in the Web services client deployment descriptor. This is better illustrated in the following code segment:

     InitialContext ic = new InitialContext ();
     Service abf = (Service)ic.lookup(
          "java:comp/env/service/AddressBookService");
			

In the above example, the container must ensure that an implementation of the generic Service Interface, javax.xml.rpc.Service, is bound in the JNDI name space at a location specified by the developer. A similar code fragment is used for access to an object that implements a Generated Service Interface such as AddressBookService.

     InitialContext ic = new InitialContext ();
     AddressBookService abf = (AddressBookService)ic.lookup(
          "java:comp/env/service/AddressBookService"); 
			

A J2EE product provider is required to provide Service lookup support in the Web, EJB, and application client containers.

4.2.2. Service Interface

The Service Interface is used by a client to get a stub or dynamic proxy or a DII Call object for a Port. A container provider is required to support all methods of the Service interface except for the getHandlerRegistry() and getTypeMappingRegistry() methods as described in sections 4.2.2.7 and 4.2.2.8.

A client developer must declare the Service Interface type used by the application in the client deployment descriptor.

4.2.2.1 Stub/proxy access

The client may use the following Service Interface methods to obtain a static stub or dynamic proxy for a Web service:

     java.rmi.Remote getPort(QName portName, Class serviceEndpointInterface) throws ServiceException;
     java.rmi.Remote getPort(java.lang.Class serviceEndpointInterface) throws ServiceException;
				

The client may also use the additional methods of the Generated Service Interface to obtain a static stub or dynamic proxy for a Web service.

The container must provide at least one of static stub or dynamic proxy support for these methods as described in section 4.2.3. Port Stub and Dynamic Proxy. The container must ensure the stub or dynamic proxy is fully configured for use by the client, before it is returned to the client. The deployment time choice of whether a stub or dynamic proxy is returned by the getPort or get<port name> methods is out of the scope of this specification. Container providers are free to offer either one or both.

The container provider must provide Port resolution for the getPort(java.lang.Class serviceEndpointInterface) method. This is useful for resolving multiple WSDL ports that use the same binding or when ports are unknown at development time. A client must declare its dependency on container Port resolution for a Service Endpoint Interface in the client deployment descriptor. If a dependency for resolving the interface argument to a port is not declared in the client deployment descriptor, the container may provide a default resolution capability or throw a ServiceException.

4.2.2.2 Dynamic Port access

A client may use the following DII methods of a Service Interface located by a JNDI lookup of the client's environment to obtain a Call object:

     Call createCall() throws ServiceException;
     Call createCall(QName portName) throws ServiceException;
     Call createCall(QName portName, String operationName) throws ServiceException;
     Call createCall(QName portName, QName operationName) throws ServiceException;
     Call[] getCalls(QName portName) throws ServiceException;
				

A DII Call object may or may not be pre-configured for use depending on the method used to obtain it. See the [JAX-RPC] specification for details.

4.2.2.3 ServiceFactory

The JAX-RPC ServiceFactory class is not supported in a Web Services for J2EE product. The client must obtain a Service Interface using JNDI lookup as described in section 4.2.1. Service Lookup.

4.2.2.4 Service method use with full WSDL

A client developer may use all methods of the Service Interface (except as described in sections 4.2.2.7 and 4.2.2.8) if a full WSDL description and JAX-RPC mapping file are declared in the client deployment descriptor. The port address attribute may be absent from the WSDL or may be a dummy value.

4.2.2.5 Service method use with partial WSDL

A client developer may use the following methods of the Service Interface if a partial WSDL definition is declared in the client deployment descriptor:

Call createCall() throws ServiceException;
java.rmi.Remote getPort(java.lang.Class serviceEndpointInterface) throws ServiceException;
java.net.URL getWSDLDocumentLocation()
				

A partial WSDL definition is defined as a fully specified WSDL document which contains no service or port elements. The JAX-RPC mapping file specified by the developer will not include a service-interface-mapping in this case.

The container must throw a java.lang.UnsupportedOperationException if other methods of the Service Interface are called and the developer specifies a partial WSDL definition.

4.2.2.6 Service method use with no WSDL

A client developer may use the following methods of the Service Interface if no WSDL definition is specified in the client deployment descriptor:

     Call createCall() throws ServiceException;
				

If the wsdl-file is not specified in the deployment descriptor, the jaxrpc-mapping-file must not be specified.

The container must throw a java.lang.UnsupportedOperationException if other methods of the Service Interface are called and the developer does not specify a WSDL definition.

4.2.2.7 Handlers

Components should not use the getHandlerRegistry() method. A container provider must throw a java.lang.UnsupportedOperationException from the getHandlerRegistry() method of the Service Interface. Handler support is documented in Chapter 6. Handlers.

4.2.2.8 Type Mapping

Components should not use the getTypeMappingRegistry() method. A container provider must throw a java.lang.UnsupportedOperationException from the getTypeMappingRegistry() method of the Service Interface.

4.2.3. Port Stub and Dynamic Proxy

4.2.3.1 Identity

The Port Stub and Dynamic Proxy are a client's representation of a Web service. The Port that a stub or proxy communicates with has no identity within the client view. The equals() method cannot be used to compare two stubs or proxy instances to determine if they represent the same Port. The results of the equals(), hash(), and toString() methods for a stub are unspecified. There is no way for the client to ensure that a Port Stub, Dynamic Proxy, or Call will access a particular Port instance or the same Port instance for multiple invocations.

4.2.3.2 Type narrowing

Although the stub and dynamic proxy classes are considered Remote objects, a client is not required to use PortableRemoteObject.narrow(...). However, clients are encouraged to use PortableRemoteObject.narrow(...) to prevent confusion with client use of other Remote objects.

4.2.4. JAX_RPC Properties

The J2EE container environment changes the requirements for supporting the Stub/proxy properties defined within JAX-RPC.

4.2.4.1 Optional properties

Container providers are not required to support the following properties on the javax.xml.rpc.Stub and javax.xml.rpc.Call interfaces. If a setProperty() method call is made using the following properties and the Stub implementation does not support the property, the stub must throw a java.lang.UnsupportedOperationException exception.

USERNAME_PROPERTY & PASSWORD_PROPERTY - the client managed credential propogation properties.

A container provider is not required to support the USERNAME_PROPERTY and PASSWORD_PROPERTY properties on the Stub implementation. Container providers are responsible for obtaining credential information and passing it to the server based on authentication requirements for a given request. For example, when submitting a HTTP request to access a Web service and the server is configured to require HTTP Basic authentication, the container must obtain a userid and password and add a HTTP Authorization header to the HTTP request. In the case where a client certificate is required for an HTTP request, the container is responsible for establishing a HTTPS connection with mutual SSL by making the client certificate available to the underlying SSL layer.

The J2EE 1.3 specification section 9.2 describes the mechanism by which a client may programmatically supply authentication information to the container by implementing the javax.security.auth.callback.CallbackHandler interface.

SESSION_MAINTAIN_PROPERTY - session management configuration.

A container provider is not required to support the SESSION_MAINTAIN_PROPERTY property on the Stub implementation. The container management and configuration of participation in an HTTP Session is specific to the container implementation and end user requirements. Containers are expected to provide a means for an end user to select whether or not they want to participate in an HTTP Session, but there is no standard requirement for defining this.

Participation in an HTTP Session is specific to the JAX-RPC Service Endpoint model and does not necessarily pertain the Session EJB model for implementing a Web service. A client may receive an error if it invokes a Web service that requires HTTP Session participation and the client is configured not to participate in an HTTP Session.

4.2.4.2 Required properties

ENDPOINT_ADDRESS_PROPERTY - dynamic endpoint address assignment.

A container provider is required to support the ENDPOINT_ADDRESS_PROPERTY to allow components to dynamically redirect a Stub/proxy to a different URI.

4.2.5. JAX-RPC Custom Serializers / Deserializers

The use of JAX-RPC custom serializers / deserializers is out of scope for this version of the specification. JAX-RPC customer serializers / deserializers are not portable across Web Services for J2EE providers and are therefore not included as part of the portable deployment unit. It is expected that vendors will provide proprietary solutions to this problem until it has been addressed by a future version of JAX-RPC.

4.2.6. Packaging

The developer is responsible for packaging, either by containment or reference, the WSDL file, Service Endpoint Interface class, Generated Service Interface class (if used), their dependent classes, and JAX-RPC Mapping Files, along with a Web services client deployment descriptor in a J2EE module. The location of the Web services client deployment descriptor in the module is module specific. WSDL files are located relative to the root of the module and are typically co-located with the module's deployment descriptor. JAX-RPC Mapping Files are located relative to the root of the module and are typically co-located with the WSDL file. The developer must not package generated stubs.

5.3.1. Service Endpoint Interface

The Service Endpoint Interface (SEI) must follow the JAX-RPC rules for WSDL<->Java mapping. The SEI is related to the WSDL PortType and WSDL bindings by these rules. The SEI is required for use by the deployment tools and parallel client development. The Port component developer is responsible for providing both the WSDL document with a minimum of the PortType and binding defined and the SEI and for keeping the two in sync with each other.

JAX-RPC defines Holders as non-serializable classes which cannot be implemented by the remote interface of an Enterprise JavaBean. Therefore, support for an SEI which uses Holders for parameters is not required for Port components deployed in the EJB container.

5.3.2. Service Implementation Bean

There are two ways a Service Implementation Bean can be implemented. This includes a Stateless Session EJB and JAX-RPC service endpoint as defined by Chapter 10 of the [JAX-RPC] specification. The two programming models are fully defined in sections 5.3.2.1 and 5.3.2.2.

A container may use any bean instance to service a request.

5.3.2.1 EJB container programming model

A Stateless Session Bean, as defined by sections 7.8-7.10 of the [EJB] specification, can be used to implement a Web service to be deployed in the EJB container.

A Stateless Session Bean does not have to worry about multi-threaded access. The EJB container is required to serialize request flow through any particular instance of a Service Implementation Bean.

The requirements for creating a Service Implementation Bean as a Stateless Session EJB are repeated in part here.

• The Service Implementation Bean must have a default public constructor.

• The Service Implementation Bean may implement the Service Endpoint Interface, but it is not required to do so. The bean must implement all the method signatures of the SEI. The Service Implementation Bean methods are not required to throw javax.rmi.RemoteException. The business methods of the bean must be public and must not be final or static. It may implement other methods in addition to those defined by the SEI.

• A Service Implementation Bean must be a stateless object. A Service Implementation Bean must not save client specific state across method calls either within the bean instance's data members or external to the instance.

• The class must be public, must not be final and must not be abstract.

• The class must not define the finalize() method.

• Currently, it must implement the ejbCreate() and ejbRemove() methods which take no arguments. This is a requirement of the EJB container, but generally can be stubbed out with an empty implementations.

5.3.2.1.1 The required SessionBean interface

Currently, a Stateless Session Bean must implement the javax.ejb.SessionBean interface either directly or indirectly.

This interface allows the container to notify the Service Implementation Bean of impending changes in its state. The full requirements of this interface are defined in the Enterprise JavaBeans specification 2.0 section 7.5.1.

5.3.2.1.2 Allowed access to container services

The [EJB] specification section 7.8.2 defines the allowed container service access requirements.

5.3.2.1.3 Exposing an existing EJB

An existing Enterprise JavaBean may be used as a Service Implementation Bean if it meets the following requirements:

• The business methods of the EJB bean class must meet the Service Implementation Bean requirements defined in section 5.3.1. Service Endpoint Interface.

• The Service Endpoint Interface methods must be a subset of the remote interface methods of the EJB and the SEI must meet the requirements described in the [JAX-RPC] specification for Java->WSDL mapping.

• The transaction attributes of the SEI methods must not include Mandatory.

The developer must package the Web service as described in section 5.4. Packaging and must specify an ejb-link from the port in the Web services deployment descriptor to the existing EJB.

5.3.2.2 Web container programming model

The term JAX-RPC Service Endpoint used within the [JAX-RPC] specification is somewhat confusing since both Service Implementation Beans require the use of a JAX-RPC run time. However, in this case it refers to the programming model defined within the [JAX-RPC] specification that is used to create Web services that run within the Web container. The requirements are repeated here with clarification. Changes from the JAX-RPC defined programming model are required for running in a J2EE container-managed environment.

A JAX-RPC Service Endpoint can be single or multi-threaded. The concurrency requirement is declared as part of the programming model. A JAX-RPC Service Endpoint must implement javax.servlet.SingleThreadModel if single threaded access is required by the component. A container must serialize method requests for a Service Implementation Bean that implements the SingleThreadModel interface.

The Service Implementation Bean must follow the Service Developer requirements outlined in the [JAX-RPC] specification and are listed below except as noted.

• The Service Implementation Bean must have a default public constructor.

• The Service Implementation Bean may implement the Service Endpoint Interface, but it is not required to do so. The bean must implement all the method signatures of the SEI. The business methods of the bean must be public and must not be final or static. It may implement other methods in addition to those defined by the SEI.

• A Service Implementation must be a stateless object. A Service Implementation Bean must not save client specific state across method calls either within the bean instance's data members or external to the instance. A container may use any bean instance to service a request.

• The class must be public, must not be final and must not be abstract.

• The class must not define the finalize() method.

5.3.2.2.1 The optional ServiceLifecycle Interface

A Service Implementation Bean for the Web container may implement the java.xml.rpc.server.ServiceLifeCycle interface:

     package javax.xml.rpc.server;
     public interface ServiceLifecycle {
     void init(Object context) throws ServiceException;
     void destroy();
     }
					

The ServiceLifeCycle interface allows the Web container to notify a Service Implementation Bean instance of impending changes in its state. The bean may use the notification to prepare its internal state for the transition. If the bean implements the ServiceLifeCycle interface, the container is required to call the init and destroy methods as described below.

The container must call the init method before it can start dispatching requests to the SEI methods of the bean. The init method parameter value provided by the container is described by the [JAX-RPC] specification. The bean may use the container notification to ready its internal state for receiving requests.

The container must notify the bean of its intent to remove the bean instance from the container's working set by calling the destroy method. A container may not call the destroy method while a request is being processed by the bean instance. The container may not dispatch additional requests to the SEI methods of the bean after the destroy method is called.

5.3.2.2.2 Allowed access to container services

The container provides certain services based on the life cycle state of the Service Implementation Bean. The table below describes the services that may be accessed within the various methods of the bean. If the bean attempts to access container services which are not allowed, a java.lang.IllegalStateException will be thrown.

Table 1: Allowed access to container services

Bean Method	Allowed container support
constructor
init	JNDI lookup of java:comp/env
destroy Business methods of the SEI	ServletEndpointContext methods resource managers enterprise beans.

5.3.3. Service Implementation Bean Life Cycle

The life cycle of a Service Implementation Bean is controlled by the container and is illustrated in Figure 6. The methods called by the container are container/bean specific, but in general are quite similar. Figure 6 illustrates the life cycle in the Web container. The EJB container life cycle may be found in the [EJB] specification section 7.8.1.

Figure 6 Service Implementation Bean life cycle in the Web container

The container services requests defined by a WSDL port. It does this by creating a listener for the WSDL port address, receiving requests and dispatching them on a Service Implementation Bean. Before a request can be serviced, the container must instantiate a Service Implementation Bean and ready it for method requests.

A container readies a bean instance by first calling newInstance on the Service Implementation Bean class to create an instance. The container then calls the life cycle methods on the Service Implementation Bean that are specific to the container. For the Web container, it calls the init method on the instance if the Service Implementation Bean class implements the ServiceLifecycle interface. For the EJB container, it calls the setSessionContext and ejbCreate methods.

A Service Implementation Bean instance has no identity.

A container may pool method ready instances of a Service Implementation Bean and dispatch a method request on any instance in a method ready state.

The container notifies a Service Implementation Bean instance that it is about to be removed from Method Ready state by calling container/bean specific life cycle methods on the instance. For the Web container, the destroy method is called. For the EJB container, the ejbRemove method is called.

5.3.4. JAX-RPC Custom Serializers / Deserializers

The use of JAX-RPC custom serializers / deserializers is out of scope for this version of the specification. JAX-RPC customer serializers / deserializers are not portable across Web Services for J2EE providers and are therefore not included as part of the portable deployment unit. It is expected that vendors will provide proprietary solutions to this problem until it has been addressed by a future version of JAX-RPC.

5.4.1. EJB Module Packaging

Stateless Session EJB Service Implementation Beans are packaged in an EJB-JAR that contains the class files and WSDL files. The packaging rules follow those defined by the Enterprise JavaBeans specification. In addition, the Web services deployment descriptor location within the EJB-JAR file is META-INF/webservices.xml.

5.4.2. Web App Module Packaging

JAX-RPC Service Endpoints are packaged in a WAR file that contains the class files and WSDL files. The packaging rules for the WAR file are those defined by the Servlet specification. A Web services deployment descriptor is located in a WAR at WEB-INF/webservices.xml.

5.4.3. Assembly within an EAR file

Assembly of modules containing port components into an EAR file follows the requirements defined by the J2EE specification.

6.2.1. Scenarios

Handlers must be able to support the following scenarios:

Scenario 1: Handlers must be able to transform the SOAP header. One example is the addition of a SOAP header for application specific information, like customerId, by the handler.

Scenario 2: Handlers must be able to transform just parts of the body. This might include changing part values within the SOAP body. Encryption of some parameter values is an example of this scenario.

Scenario 3: Handlers must be able to just read a message where no additions, transformations, or modification to the message is made. Common scenarios are logging, metering, and accounting.

6.2.2. Programming Model

A Web Services for J2EE provider is required to provide the following interfaces and classes of the javax.xml.rpc.handler package.

• Handler

• HandlerRegistry

• MessageContext

• GenericHandler

• HandlerInfo

The HandlerChain interface is not required. The HandlerChain functionality is provided in a container specific manner. It is not used by application code. A container provider is not required to use the HandlerChain interface to implement the chain functionality.

The HandlerInfosetHandlerConfig() and getHandlerConfig() methods do not affect the container's Handler request processing.

A Web Services for J2EE provider is not required to provide an implementation of HandlerRegistry. This functionality is specific to the container.

A Web Services for J2EE provider is required to provide an implementation of MessageContext.

A Web Services for J2EE provider is required to provide all the interfaces of the javax.xml.rpc.handler.soap package. The provider must also provide an implementation of the SOAPMessageContext interface.

The programming model of a Port component can be single-threaded or multi-threaded as defined in sections 5.3.2.1 EJB container programming model and 5.3.2.2. Web container programming model. The concurrency of a JAX-RPC Handler must match the concurrency of the business logic it is associated with. Client handlers may need to support multi-threaded execution depending on the business logic which is accessing the Port.

Handlers must be loaded using the same class loader the application code was loaded with. The class loading rules follow the rules defined for the container the Handler is running in.

6.2.2.1 Handler Life Cycle

The life cycle of a Handler is controlled by the container and is illustrated in Figure 7.

Figure 7 Handler life cycle

The init and destroy methods of the Handler interface allows the container to notify a Handler instance of impending changes in its state. The Handler may use the notification to prepare its internal state for the transition. The container is required to call the init and destroy methods as described below.

The container must call the init method before it can start dispatching requests to the handleRequest(), handleResponse(), and handleFault() methods of the Handler. The Handler may use the container notification to ready its internal state for receiving requests.

The container must notify the Handler of its intent to remove the instance from the container's working set by calling the destroy method. A container must not call the destroy method while a request is being processed by the Handler instance. The container must not dispatch additional requests to the Handler interface methods after the destroy method is called.

As defined by JAX-RPC, a RuntimeException (other than SOAPFaultException) thrown from any method of the Handler results in the destroy method being invoked and transition to the "Does Not Exist" state.

Pooling of Handler instances is allowed, but is not required. If Handler instances are pooled, they must be pooled by Port component. This is because Handlers may retain non-client specific state across method calls that are specific to the Port component. For instance, a Handler may initialize internal data members with Port component specific environment values. These values may not be consistent when a single Handler type is associated with multiple Port components. Any pooled instance of a Port component's Handler in a Method Ready state may be used to service the handleRequest(), handleResponse(), and handleFault() methods. It is not required that the same Handler instance service both the handleRequest() and handleResponse() or handleFault() method invocations of any given request.

6.2.2.2 Security

Handlers associated with a Port component run after authorization has occurred and before the business logic method of the Service Implementation bean is dispatched to. For JAX-RPC Service endpoints, Handlers run after the container has performed the security constraint checks associated with the servlet element that defines the Port component. For EJB based service implementations, Handlers run after method level authorization has occurred.

A Handler must not change the message in any way that would cause the previously executed authorization check to execute differently. A Handler.handleRequest() method must not change the operation name, number of parts in the message, or types of the message parts. A container must throw a java.rmi.MarshalException or java.rmi.UnmarshalException back to the client if the Handler does this. Although, not strictly required for security reasons, a Handler.handleResponse() method must not change the number of parts in the message, or types of the message parts. A container must throw a MarshalException or UnmarshalException back to the client if the Handler does this. A container should log occurrences of these errors since the client may not be expecting a response (i.e. it may be a one-way invocation).

A handler may perform programmatic authorization checks if the authorization is based solely on the MessageContext and the component's environment values. A Handler cannot perform role based programmatic authorization checks nor can a Handler access the Principal associated with the request.

The Java 2 security permissions of a Handler follow the permissions defined by the container it runs in. The application client, Web, and EJB containers may have different permissions associated with them. If the provider allows defining permissions on a per application basis, permissions granted to a Handler are defined by the permissions granted to the application code it is packaged with. See section J2EE.6.2.3 of the J2EE 1.3 specification for more details.

6.2.2.3 Transactions

Handlers run under an unspecified transaction context.

In general Handlers follow the same requirements as Servlet filters regarding transactions. Handlers must not demarcate transactions using the javax.transaction.UserTransaction interface. Handlers may use transactional resources in a local transaction mode, but should not use transactional resources in the methods of any objects used to wrap the MessageContext.

6.2.3. Developer Responsibilities

A developer is not required to implement a Handler. Handlers are another means of writing business logic associated with processing a Web services request. A developer may implement zero or more Handlers that are associated with a Port component and/or a Service reference. If a developer implements a Handler, they must follow the requirements outlined in this section.

A Handler is implemented as a stateless instance. A Handler does not maintain any message processing (client specific) related state in its instance variables across multiple invocations of the handle method.

A Handler class must implement the java.xml.rpc.handler.Handler interface.

A Handler.handleXXX() method may access the component's environment entries by using JNDI lookup of the "java:comp/env" contenxt and accessing the env-entry-names defined in the deployment descriptor by performing a JNDI lookup. See chapter 20 of the [EJB] specification for details. The container may throw a java.lang.IllegalStateException if the environment is accessed from any other Handler method and the environment is not available. In addition, the Handler may use HandlerInfo.getHandlerConfig() method to access the Handler's init-params declared in the deployment descriptor.

The Handler.init() method must retain the information defined by HandlerInfo.getHeaders().

A Handler implementation must implement the getHeaders() method to return the results of the HandlerInfo.getHeaders() method. The headers that a Handler declares it will process (i.e. those returned by the Handler.getHeaders() method must be defined in the WSDL definition of the service.

A Handler implementation should test the type of the MessageContext passed to the Handler in the handle<action>() methods. Although this specification only requires support for SOAP messages and the container will pass a SOAPMessageContext in this case, some providers may provide extensions that allow other message types and MessageContext types to be used. A Handler implementation should be ready to accept and ignore message types which it does not understand.

A Handler implementation must use the MessageContext to pass information to other Handler implementations in the same Handler chain and, in the case of the JAX-RPC service endpoint, to the Service Implementation Bean. A container is not required to use the same thread for invoking each Handler or for invoking the Service Implementation Bean.

A Handler may access the complete SOAP message and can process both SOAP header blocks and body if the handle<action>() method is passed a SOAPMessageContext.

A SOAPMessageContext Handler may add or remove headers from the SOAP message. A SOAPMessageContext Handler may modify the header of a SOAP message if it is not mapped to a parameter or if the modification does not change value type of the parameter if it is mapped to a parameter. A Handler may modify part values of a message if the modification does not change the value type.

A Handler may access transactional resources in a local transaction mode.

Handlers that define application specific headers should declare the header schema in the WSDL document for the component they are associated with, but are not required to do so.

6.2.4. Container Provider Responsibilities

A Handler chain is processed according to the [JAX-RPC] specification section 12.2.2. The process order defaults to the order the handlers are defined in the deployment descriptor and follow the [JAX-RPC] specification section 12.1.4 processing order.

A container is required to provide an instance of a java.util.Map object in the HandlerInfo instance. The HandlerInfo.getHeaders() method must return the set of soap-headers defined in the deployment descriptor. The Map object must provide access to each of the Handler's init-param name/value pairs declared in the deployment descriptor as java.lang.String values. The container must provide a unique HandlerInfo instance and Map config instance for each Handler instance. A unique Handler instance must be provider for each Port component declared in the deployment descriptor.

The container must call the init() method within the context of a Port component's environment. The container must ensure the Port component's env-entrys are setup for the init method to access.

The container must provide a MessageContext type unique to the request type. For example, the container must provide a SOAPMessageContext to the handle<action>() methods of a Handler in a handler chain when processing a SOAP request. The SOAPMessageContext must contain the complete SOAP message.

The container must share the same MessageContext instance across all Handler instances and the target endpoint that are invoked during a single request and response or fault processing on a specific node.

The container must setup the Port component's execution environment before invoking the handle<action>() methods of a handler chain. Handlers run under the same execution environment as the Port component's business methods. This is required so that handlers have access to the Port component's java:comp/env context.

A container provider is not required to support Handlers for Port component's that run in the EJB container. It is expected this will be required when this specification is included in J2EE 1.4.

6.4.1. Client Web service method access

Figure 8 Client method invoke handler OID

6.4.2. EJB Web service method invocation

Figure 9 EJB Web service method invocation handler processing part 1

7.1.1. Overview

The webservices.xml deployment descriptor file defines the set of Web services that are to be deployed in a Web Services for J2EE enabled container. The packaging of the webservices.xml deployment descriptor file is defined in sections 5.4.1. EJB Module Packaging and 5.4.2. Web App Module PackagingWeb services are defined by WSDL documents as described by section 3.2. Web Service. The deployment descriptor defines the WSDL port to Port component relationship. Port components are defined in Chapter 5. Server Programming Model.

7.1.2. Developer responsibilities

The developer is responsible not only for the implementation of a Web service, but also for declaring its deployment characteristics. The deployment characteristics are defined in both the module specific deployment descriptor and the webservices.xml deployment descriptor. Service Implementations using a stateless session bean must be defined in the ejb-jar.xml deployment descriptor file using the session element. Service Implementations using a JAX-RPC Service Endpoint must be defined in the web.xml deployment descriptor file using the servlet-class element. See the [EJB] and Servlet 2.3 specifications for additional details on developer requirements for defining deployment descriptors. The developer is also required to provide structural information that defines the Port components within the webservices.xml deployment descriptor file. The developer is responsible for providing the set of WSDL documents that describe the Web services to be deployed, the Java classes that represent the Web services, and the mapping that correlates the two.

The developer is responsible for providing the following info