Chapter 19. The javax.xml.rpc.soap Package

   

---

ServletEndpointContext

javax.xml.rpc.server

---

JAX-RPC 1.0; JWSDP 1.0, J2EE 1.4

 public interface ServletEndpointContext {  // Public Instance Methods  public abstract javax.servlet.http.HttpSession getHttpSession(  );     public abstract javax.xml.rpc.handler.MessageContext getMessageContext(  );      public abstract javax.servlet.ServletContext getServletContext(  );      public abstract java.security.Principal getUserPrincipal(  );  } 

A servlet container that provides a server-side implementation of JAX-RPC must create an object of type ServletEndpointContext and pass it to the init( ) method of any service that declares that it implements the ServiceLifecyle interface. The service class typically stores the object passed to it, and uses it to obtain context information as necessary during the invocation of its service endpoint interface methods.

The getServletContext( ) method returns the ServletContext for the web application of which the web service implementation is a part. The ServletContext provides methods that allow the service to access initialization parameters, delegate service implementation to other servlets or JSPs, and so on. This is the only method that returns a meaningful value if called outside of a service endpoint interface method (e.g., in init( ) ).

The getHttpSession( ) method returns the HttpSession object that corresponds to the active session maintained by the hosting web container for the client invoking a remote service endpoint interface method, or null if the client is not in a session with the server. A JAX-RPC client must explicitly enable the use of sessions by setting the SESSION_MAINTAIN_PROPERTY of its javax.xml.rpc.Stub or javax.xml.rpc.Call object to true. The ability of other types of clients to establish a session is dependent on the client's software environment.

The getUserPrincipal( ) method returns a java.security.Principal that identifies the caller of a service endpoint interface method. A meaningful value is returned only if the web container has authenticated the calling user as the result of the use of an auth-constraint element in the web.xml file for the hosting servlet. If authentication is not performed, then null is returned.

The getMessageContext( ) method returns the javax.xml.rpc.handler.MessageContext object for the SOAP message that caused the service's executing service endpoint interface method to be invoked. The MessageContext can be used to allow a service implementation class to share property values with SOAP message handlers that are designated to be included on the server-side processing path . A service implementation might make use of this facility by reading a value extracted by a message handler from a SOAP header that was part of the incoming message, or by saving a value that a handler should write into the reply message, while not itself becoming dependent on the actual message structure. If the MessageContext is an instance of javax.xml.rpc.handler.soap.SOAPMessageContext , the service implementation class may use it to gain direct access to the message itself, although this is not recommended.

Even though a single ServletEndpointContext object is passed to a given servlet instance, the values that it returns depend on the execution context of the service endpoint interface method within which it is used. For example, the same ServletEndpointContext object used concurrently in two different threads by the same service instance might return different values from the getHttpSession( ) method if the callers are in separate sessions with the web container. This is possible because the ServletEndpointContext methods return information obtained from context that is held within the servlet container on a per-thread basis.

---