GlassFish Project - Web Services Deployment and Dispatching home page

 New to GlassFish | Community Guidelines  | Downloads | FAQ How-Tos


Welcome to the Web Services Deployment and Dispatching page. This page is dedicated to discussing the Web Services deployment and message dispatching in GlassFish.

Page Contents

Annotation Processing

The classes that process Web Services annotations at deployment time are found in appserv-commons/src/java/com/sun/enterprise/deployment/annotation/handlers. For example, the WebServiceHandler class processes the @WebService annotation.

During deployment of a service, all deployment descriptors (if any) are loaded and then the annotations are processed. On seeing an @WebService, for example, the annotation framework calls WebServiceHandler which processes the annotation. While processing the annotation, we check if there a deployment descriptor entry already available (e.g., from webservices.xml) and if so, the annotation values will not override the equivalent defined in the descriptor. At the end of the annotation processing phase, we have all the information required with which we generate WSDLs and other portable artifacts (if not packaged).

Servlet Endpoint Deployment and Dispatching

While the classes in appserv-core/src/java/com/sun/enterprise/deployment/backend take care of generic deployment activities for all artifacts being deployed, the appserv-core/src/java/com/sun/enterprise/deployment/backend/WebServiceDeployer.java class takes care of webservice specific deployment actions (like publishing of WSDL, routing all webservice request through a single point of entry as detailed below). The classes in appserv-core/src/java/com/sun/enterprise/webservice take care of runtime actions for a webservice request (like initializing JAXWS runtime, taking care of security, taking care of EJB specific features like container managed transactions etc).

At the time of deployment of a WAR, we generate a web.xml which directs the HTTP request containing the payload (SOAP/HTTP or just XML in the case of a RESTful service deployed with the XML/HTTP binding) to JAXWSServlet. You can see the generatd web.xml and other deployment artifacts if you look in $GLASSFISH_HOME/domains/domain1/generated/xml/j2ee-modules//WEB-INF

More specifically, in the JAX-WS case, when you deploy a WAR with a servlet endpoint:

  1. The GlassFish container creates a web.xml to deploy an instance of JAXWSServlet. If your WAR contained a web.xml, the generated web.xml is built from your original web.xml, but the servlet-class is replaced with JAXWSServlet. In addition, the webservices.xml deployment descriptor is generated (if it doesn't already exist) and the service-endpoint-interface references the class being deployed which you specified in your web.xml's servlet-class. Note that webservices.xml is not required by JAX-WS, but generated for internal use.
  2. When the JAXWSServlet instance is deployed, and initialized, the following happens:
    1. It creates a com.sun.enterprise.webservice.monitoring.WebServiceEngine instance.
    2. The WebServiceEngine creates an endpoint implementation (com.sun.enterprise.webservice.monitoring.JAXWSEndpointImpl) from the port-component as defined by the deployment descriptor and annotations. The description of this port-component is represented internally as an instance of com.sun.enterprise.deployment.WebServiceEndpoint. The JAXWSEndpointImpl instance is what processes the MessageContext containing the SOAP request/response.
    3. It registers the endpoint implementation with the JAX-WS runtime. The registry is an instance of com.sun.enterprise.webservice.JAXWSRuntimeEpiRegistry. The endpoint object that gets registered is an instance of com.sun.xml.ws.spi.runtimeRuntimeEndpointInfo, and it includes (among other things): an instance of the application defined class implementing the endpoint (i.e., the oneclass annotated with @WebService or @WebServiceProvider), a WebServiceContext instance, an associated WSDL file (either packaged or generated from annotations), an instance of the the protocol binding (i.e., javax.xml.ws.Binding), and the handler chain.

When the JAXWSServlet instance receives a SOAP/HTTP or XML/HTTP message (as HTTPServletRequest), it does the following:

  1. Creates the MessageContext (including a reference to the ServletContext).
  2. Passes the HTTP request/response objects, along with the RuntimeEndpointInfo, to an instance of com.sun.xml.ws.spi.runtime.Tie - the entry point for the JAX-WS runtime system.
  3. The JAX-WS runtime decodes the SOAP request, applying the JAX-WS and JAXB XML/Java bindings, to get the parameters that are used to invoke the endpoint implementation class.
  4. Then, the flow is reversed and the returned object is serialized back out to the HTTP response.

EJB Endpoint Deployment and Dispatching

The classes that handle the EJB endpoint's runtime behavior are found in the same place as the servlet endpoint classes: appserv-core/src/java/com/sun/enterprise/webservice. EjbWebServiceServlet is the class used to handle requests to services deployed as EJB endpoints. EjbWebServiceServlet uses an instance EjbMessageDispatcher to dispatch HTTP requests containing the payload (SOAP/HTTP or just XML in the case of a RESTful service deployed with the XML/HTTP binding)requests to the appropriate endpoint.

At the time of deployment of an EJB-JAR, the webservice endpoint is registered. When the EJB webservice endpoint is registered, there is a listener (an instance of EjbWebServiceRegistryListener) that registers the endpoint's path (i.e., the endpoint-address-uri from the generated deployment descriptor) as an ad-hoc path with the web container, along with the ad-hoc servlet (i.e., EjbWebServiceServlet) responsible for servicing any requests on this path. An ad-hoc path is the GlassFish term for a servlet path that is mapped to a servlet not declared in the web module's deployment descriptor. GlassFish calls a web module all of whose mappings are for ad-hoc paths an ad-hoc web module. The EjbWebServiceServlet instance that receives SOAP or XML over HTTP on behalf of an EJB endpoint is deployed in an ad-hoc web module. As a result, you won't find a web.xml for this servlet or see it on the Admin Console.

More specifically, in the JAX-WS case, when you deploy a EJB-JAR with an EJB endpoint, among other things the follow occur:

  1. The GlassFish container creates the deployment descriptors necessary for deployment, including:
    • An ejb-jar.xml to deploy your service implementation bean (i.e., the class you have annotated with @Stateless and @WebService). If your EJB-JAR already contains an ejb-jar.xml, the generated ejb-jar.xml is built from your original ejb-jar.xml as a starting point. In the generated ejb-jar.xml, the ejb-class references your service implementation bean, and the ejb-name is the value specified by @Stateless.name. ??!! In GlassFish, it is also forced to be the name of the web service (wsdl:portType for WSDL 1.1) as specified by the @WebService.name annotation. !!??
    • A webservices.xml where the service-endpoint-interface references the service implementation bean unless the @WebService.endpointInterface annotation indicates a service endpoint interface. The port-component-name is the name of the web service and it comes from the @WebService.name annotation (wsdl:portType for WSDL1.1). Note that webservices.xml is not required by JAX-WS, but generated for internal use.
    • A sun-ejb-jar.xml (created from the one supplied with your EJB-JAR, if any). The ejb-name is the value specified by the @Stateless.name. The endpoint-address-uri specifies the endpoint path. You can change the default deployment path of an EJB endpoint by providing a sun-ejb-jar.xml with this information in your EJB-JAR. You can also configure security using this deployment descriptor.
  2. An instance of com.sun.enterprise.webservice.EjbContainerPreHandler is created and inserted first in the handler chain for the endpoint. This class performs the security authorization, prior to invoking any deployed handers or the endpoint itself. This is a JSR-109 Section 9 requirement.

When the EjbWebServiceServlet instance receives a SOAP/HTTP or XML/HTTP message (as HTTPServletRequest), it does the following:

  1. Looks up the endpoint descriptor (EjbRuntimeEndpointInfo) from the EJB endpoint registry (WebServiceEjbEndpointRegistry).
  2. Performs authentication as described in JSR-109 Section 9.
  3. Passes the HTTPServletRequest and HTTPServletResponse, along with the endpoint descriptor to an appropriate (i.e., either JAX-RPC or JAX-WS) dispatcher (EjbMessageDispatcher) for processing

The EjbMessageDispatcher processing is similar to the dispatching performed by JAXWSServlet, and includes the following steps:

  1. Creates the MessageContext (without a reference to the ServletContext).
  2. Passes the HTTP request/response objects, along with the RuntimeEndpointInfo, to an instance of com.sun.xml.ws.spi.runtime.Tie - the entry point for the JAX-WS runtime system.
  3. The JAX-WS runtime decodes the SOAP request, applying the JAX-WS and JAXB XML/Java bindings, to get the parameters that are used to invoke the endpoint implementation class.
  4. Then, the flow is reversed and the returned object is serialized back out to the HTTP response.

Supporting Documentation

This sections contains pointers to useful documents and information about the web services deployment and dispatching technologies in GlassFish.

Specifications:

Other Links:

General information:

Include any documentation that is useful for developers.  Design docs and functional specs will be stored under the Documents and Files link in the left nav bar.  There is alot of good documentation available on java.sun.com so linclude llinks to that too.

ToDo List

TBD: Maintain a list of things to do in Issue tracker so all can figure out what needs to be done.

ToDo list will be maintained using Issue Tracker Task issue type. You can query Issue Tracker using issue type Task or click here to check out the ToDo list.