Chapter 9. Developing Web Services

Describe the steps required to configure, package, and deploy J2EE Web services and service clients, including a description of the packaging formats, such as .ear, .war, .jar, deployment descriptor settings, the associated Web Services description file, RPC mapping files, and service reference elements used for EJB and servlet endpoints.

Packaging

Port components may be packaged in a WAR file, or EJB JAR file. Port components packaged in a WAR file must use a JAX-RPC Service Endpoint for the Service Implementation Bean. Port components packaged in a EJB-JAR file must use a Stateless Session Bean for the Service Implementation Bean. The developer is responsible for packaging, either by containment or reference, the WSDL file, Service Endpoint Interface class, Service Implementation Bean class, and their dependent classes, JAX-RPC mapping file along with a Web services deployment descriptor in a J2EE module. The location of the Web services deployment descriptor in the module is module specific. WSDL files are located relative to the root of the module and are typically located in the wsdl directory that is co-located with the module deployment descriptor or a subdirectory of it. Mapping files are located relative to the root of the module and are typically co-located with the WSDL file.

The wsdl directory is a well-known location that contains WSDL files and any relative content the WSDL files may reference. WSDL files and their relative references will be published during deployment.

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. The wsdl directory is located at META-INF/wsdl.

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. The wsdl directory is located at WEB-INF/wsdl.

Directory Structure for JAX-RPC Web Services

The structure of WAR file is shown below (hello-web.war):


/WEB-INF  <-------- "special" directory, its content is not accessible for HTTP clients
/WEB-INF/web.xml  <------------- servlet container info and service endpoint implementation
/WEB-INF/webservices.xml  <--------- describes the Web Service part of the application
/WEB-INF/wsdl/HelloService.wsdl  <--- wsdl is the Web Service contract published externally
/WEB-INF/mapping.xml  <----------- maps the wsdl to the Service Endpoint Interface [SEI]
/WEB-INF/classes/HelloServiceSEI.class  <----- compiled Service Endpoint Interface [SEI]
/WEB-INF/classes/HelloServiceImpl.class  <--- compiled Service Implementation class

					

The webservices.xml captures all the information that the container needs to deploy Web service applications. It provides:

  • the location of WSDL - wsdl-file

  • the mapping file jaxrpc-mapping-file

  • the port-component corresponding to the ports in WSDL

  • the Java Service Endpoint Interface (SEI) service-endpoint-interface

  • the Java representation of the WSDL

  • the servlet name servlet-link which acts as the SOAP HTTP listener for it

webservices.xml :

<webservices>
    <webservice-description>
        <webservice-description-name>HelloService</webservice-description-name>
        <wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
        <jaxrpc-mapping-file>WEB-INF/mapping.xml</jaxrpc-mapping-file>
        <port-component>
            <port-component-name>HelloInterfacePort</port-component-name>
            <wsdl-port xmlns:my="http://hello">my:HelloInterfacePort</wsdl-port>
            <service-endpoint-interface>HelloServiceSEI</service-endpoint-interface>
            <service-impl-bean>
                <servlet-link>HelloInterfacePort</servlet-link> 
            </service-impl-bean>
        </port-component>
    </webservice-description>
</webservices> 
					 
					 

Web Container Deployment Descriptor /WEB-INF/web.xml is shown below:


<web-app>
    ...
    <servlet>
        <servlet-name>HelloInterfacePort</servlet-name>
        <display-name>HelloInterfacePort</display-name>
        <description>JAX-RPC endpoint - HelloInterfacePort</description>
        <servlet-class>HelloServiceImpl</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    ...
    <servlet-mapping>
        <servlet-name>HelloInterfacePort</servlet-name>
        <url-pattern>/HelloService</url-pattern>
    </servlet-mapping>
    ...
</web-app> 
					 
					 

Observe that the servlet-link of webservices.xml refers to the servlet-name present in web.xml. This allows the Web service implementation to be exposed by a servlet, and hence over HTTP (SOAP over HTTP).

NOTE: the servlet-class in web.xml actually refers to the Java class (in this case HelloServiceImpl) implementing the Web service SEI (service-endpoint-interface in webservices.xml). It is not actually a Servlet.

Directory Structure for EJB 2.1 Web Services

The structure of JAR (ejb-jar) file is shown below (hello-ejb.jar):


/META-INF
/META-INF/ejb-jar.xml   <----------------------- EJB Container deployment descriptor
/META-INF/webservices.xml  <--------- describes the Web Service part of the application
/META-INF/wsdl/HelloServiceEJB.wsdl <--- wsdl is the Web Service contract published externally
/META-INF/mapping.xml <------------- maps the wsdl to the Service Endpoint Interface [SEI]
/HelloServiceSEI.class  <----------------------- compiled Service Endpoint Interface [SEI]
/HelloServiceBean.class  <--------------------- compiled EJB class (Stateless Session Bean)

					

Configuration file /META-INF/webservices.xml for an EJB Web Service:


<webservices>
    <webservice-description>
        <webservice-description-name>HelloServiceEJB</webservice-description-name>
        <wsdl-file>META-INF/wsdl/HelloServiceEJB.wsdl</wsdl-file>
        <jaxrpc-mapping-file>META-INF/mapping.xml</jaxrpc-mapping-file>
        <port-component>
            <port-component-name>HelloServiceInfPort</port-component-name>
            <wsdl-port xmlns:my="http://hello" >my:HelloServiceInfPort</wsdl-port>
            <service-endpoint-interface>HelloServiceSEI</service-endpoint-interface>
            <service-impl-bean>
                <ejb-link>HelloServiceEJB</ejb-link>
            </service-impl-bean>
        </port-component>
    </webservice-description>
</webservices>
					
					
This webservices.xml is more or less similar to the one for a JAX-RPC Web Service, except for service-impl-bean having an ejb-link element in it, pointing to the fact the implementation is an EJB.

EJB Container deployment descriptor (/META-INF/ejb-jar.xml):


<ejb-jar>
    <enterprise-beans>
        <session>
            <display-name>HelloServiceEJB</display-name>
            <ejb-name>HelloServiceEJB</ejb-name>
            <service-endpoint>HelloServiceSEI</service-endpoint>
            <ejb-class>HelloServiceBean</ejb-class>
            <session-type>Stateless</session-type>
        </session>
    </enterprise-beans>
</ejb-jar>
					
					

Observe that the ejb-link of webservices.xml is used to relate to the ejb-name inside ejb-jar.xml. Moreover the ejb-jar.xml has a new entry service-endpoint as part of EJB 2.1 in J2EE 1.4 which has the fully qualified Service Endpoint Interface name.The ejb ejb-class should have implementation of the methods defined in Service Endpoint Interface class.

NOTE: The service implementation class need not explicitly implement the service endpoint interface (through a Java implements keyword).This allows for flexibility in service endpoint interface implementation because one can use an existing class and expose the business methods one wishes to expose by creating a service endpoint interface class. The service implementation class may implement other methods in addition to those defined by service endpoint interface, but only the service endpoint interface methods are exposed to the client.

Deployment Descriptors

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 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 Enterprise JavaBeans and Servlet 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 information in the webservices.xml deployment descriptor:

  • Port's name.

    A logical name for the port must be specified by the developer using the port-component-name element. This name bears no relationship to the WSDL port name. This name must be unique amongst all port component names in a module.

  • Port's bean class.

    The developer declares the implementation of the Web service using the service-impl-bean element of the deployment descriptor. The bean declared in this element must refer to a class that implements the methods of the Port's Service Endpoint Interface. This element allows a choice of implementations. For a JAX-RPC Service Endpoint, the servlet-link element associates the port-component with a JAX-RPC Service Endpoint class defined in the web.xml by the servlet-class element. For a stateless session bean implementation, the ejb-link element associates the port-component with a session element in the ejb-jar.xml. The ejb-link element may not refer to a session element defined in another module. A servlet must only be linked to by a single port-component. A session EJB must only be linked to by a single port-component.

  • Port's Service Endpoint Interface.

    The developer must specify the fully qualified class name of the Service Endpoint Interface in the service-endpoint-interface element. If the Service Implementation is a stateless session EJB, the developer must also specify the Service Endpoint Interface in the EJB deployment descriptor using the service-endpoint element.

  • Port's WSDL definition.

    The wsdl-file element specifies a location of the WSDL description of a set of Web services. The location is relative to the root of the module and must be specified by the developer. The WSDL file may reference (e.g. import) other files contained within the module using relative references. It may also reference other files external to the module using an explicit URL. Relative imports are declared relative to the file defining the import. Imported files may import other files as well using relative locations or explicit URLs. It is recommended that the WSDL file and relative referenced files be packaged in the wsdl directory. Relative references must not start with a "/".

  • Port's QName.

    In addition to specifying the WSDL document, the developer must also specify the WSDL port QName in the wsdl-port element for each Port defined in the deployment descriptor.

  • JAX-RPC Mapping.

    The developer must specify the correlation of the WSDL definition to the interfaces using the jaxrpc-mapping-file element. The same mapping file must be used for all interfaces associated with a wsdl-file.

  • Handlers.

    A developer may optionally specify handlers associated with the port-component using the handler element.

  • Servlet Mapping.

    A developer may optionally specify a servlet-mapping, in the web.xml deployment descriptor, for a JAX-RPC Service Endpoint. No more than one servlet-mapping may be specified for a servlet that is linked to by a port-component. The url-pattern of the servlet-mapping must be an exact match pattern (i.e. it must not contain an asterisk (“*”)).

Note that if the WSDL specifies an address statement within the port, its URI address is ignored. This address is generated and replaced during the deployment process in the deployed WSDL.

Service Reference Deployment Descriptor Information

The developer is responsible for defining a service-ref for each Web service a component within the module wants to reference. This includes the following information:

  • Service Reference Name.

    This defines a logical name for the reference that is used in the client source code. It is recommended, but not required that the name begin with service/.

  • Service type.

    The service-interface element defines the fully qualified name of the JAX-RPC Service Interface class returned by the JNDI lookup.

  • Ports.

    The developer declares requirements for container managed port resolution using the port-component-ref element. The port-component-ref elements are resolved to a WSDL port by the container.

  • WSDL definition.

    The wsdl-file element specifies a location of the WSDL description of the service. The location is relative to the root of the module. The WSDL description may be a partial WSDL, but must at least include the portType and binding elements. The WSDL description provided by the developer is considered a template that must be preserved by the assembly/deployment process. In other words, the WSDL description contains a declaration of the application’s dependency on portTypes, bindings, and QNames. The WSDL document must be fully specified, including the service and port elements, if the application is dependent on port QNames (e.g. uses the Service.getPort(QName,Class) method). The developer must specify the wsdl-file if any of the following Service methods are used.

    Call createCall() throws ServiceException;
    java.rmi.Remote getPort(java.lang.Class serviceEndpointInterface) throws ServiceException;
    javax.xml.namespace.QName getServiceName();
    java.util.Iterator getPorts() throws ServiceException;
    java.net.URL getWSDLDocumentLocation();								
    								
    The WSDL file may reference (e.g. import) other files contained within the module using relative references. It may also reference other files external to the module using an explicit URL. Relative imports are declared relative to the file defining the import. Imported files may import other files as well using relative locations or explicit URLs. Relative references must not start with a "/".

  • Service Port.

    If the specified wsdl-file has more than one service element, the developer must specify the service-qname.

  • JAX-RPC Mapping.

    The developer specifies the correlation of the WSDL definition to the interfaces using the jaxrpc-mapping-file element. The location is relative to the root of the module. The same mapping file must be used for all interfaces associated with a wsdl-file. The developer must specify the jaxrpc-mapping-file if the wsdl-file is specified.

  • Handlers.

    A developer may optionally specify handlers associated with the service-ref using the handler element.

Below is provided an extract of the web.xml with the service-ref and items of interest noted:

					
<web-app>
    ...
    <service-ref>
        <service-ref-name>service/MyHelloServiceRef</service-ref-name>          <!-- [1] -->
        <service-interface>javax.xml.rpc.Service</service-interface>            <!-- [2] -->
        <wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
        <jaxrpc-mapping-file>WEB-INF/mapping.xml</jaxrpc-mapping-file>
        <service-qname xmlns:my="http://hello">my:HelloService</service-qname>  <!-- [3] -->
        <port-component-ref>
            <service-endpoint-interface>hello.HelloInterface</service-endpoint-interface>
        </port-component-ref>
    </service-ref>
    ...
<web-app>

					
  • [1] Logical name that components in your module will use to look up the Web service

  • [2] The classname of the interface whose implementation will be returned by the process of JNDI lookup

  • [3] The service-qname is the qualified name of the service, as present inside the packaged WSDL

The Servlet (or JSP) executing the look up of the Web service has code as is shown below:

public String consumeService (String name) {
    ...
    Context ic = new InitialContext();
    Service service = (Service)ic.lookup("java:comp/env/service/MyHelloServiceRef");

    // declare the qualified name of the port, as specified in the wsdl
    QName portQName= new QName("http://hello","HelloInterfacePort");
    
    // get a handle on that port : 
    // Service.getPort(portQName,SEI class)
    HelloInterface helloPort = (HelloInterface)service.getPort(portQName, hello.HelloInterface.class); 

    // invoke the operation : sayHello()
    resultFromService = helloPort.sayHello(name);
    ...
}   					
					
The client, which is a Servlet in this case, makes use of JNDI lookup to get an instance of the javax.xml.rpc.Service. It makes use of the 'Service' object to get a handle on a 'Port' of the Web service, these are the ports defined in the WSDL representing the service. The port obtained can be cast into a locally packaged service endpoint interface (hello.HelloInterface), and the available methods invoked on it. The locally packaged service endpoint interface can be either generated from the WSDL using a tool or can be already available and mapped to the WSDL using a JAX-RPC mapping file. The client can use this 'Service' object to get a handle on the 'Call' object as well, and make a DII Web Service call.

The important observation to be made here is that a client always accesses the Service implementation indirectly by way of a JNDI lookup - that is, through the container - and is never passed a direct reference to the Web service implementation. That way, the container can intervene and provide services (logging, security, management ) for the client. Moreover a J2EE Web service client remains oblivious of how a port operates and concerns itself only with the methods a port defines.

Note: similar service-ref tags inside an ejb-jar.xml will allow an EJB or application client to look up and invoke a remote Web service.

JAX-RPC Mapping Deployment Descriptor

The JAX-RPC mapping deployment descriptor has no standard file name, though it is recommended that the file use a .xml suffix. There is a 1-1 correspondence between WSDL files and mapping files within a module. The JAX-RPC mapping deployment descriptor contains information that correlates the mapping between the Java interfaces and WSDL definition. A deployment tool uses this information along with the WSDL file to generate stubs and TIEs for the deployed services and service-refs.

Deployment

Deployment starts with a service enabled application or module. The deployer uses a deployment tool to start the deployment process. In general, the deployment tool validates the content as a correctly assembled deployment artifact, collects binding information from the deployer, deploys the components and Web services defined within the modules, publishes the WSDL documents representing the deployed Web services, deploys any clients using Web services, configures the server and starts the application. The deployment tool starts the deployment process by examining the deployable artifact and determining which modules are Web service enabled by looking for a webservices.xml deployment descriptor file contained within the module. Deployment of services occurs before resolution of service references. This is done to allow deployment to update the WSDL port addresses before the service references to them are processed. Validation of the artifact packaging is performed to ensure that:

  • Every port in every WSDL defined in the Web services deployment descriptor has a corresponding port-component element.

  • If the Service Implementation Bean is an EJB, the transaction attributes for the methods defined by the SEI DO NOT include Mandatory.

  • JAX-RPC service components are only packaged within a WAR file.

  • Stateless session bean Web services are only packaged within an EJB-JAR file.

  • The WSDL bindings used by the WSDL ports are supported by the Web Services for J2EE runtime. Bindings that are not supported may be declared within the WSDL if no port uses them.

Deployment of each port-component is dependent upon the service implementation and container used. Deployment of a JAX-RPC Service Endpoint requires different handling than deployment of a session bean service.

If the implementation is a JAX-RPC Service Endpoint, a servlet is generated to handle parsing the incoming SOAP request and dispatch it to an instance of the JAX-RPC service component. The generated servlet class is dependent on threading model of the JAX-RPC Service Endpoint. The web.xml deployment descriptor is updated to replace the JAX-RPC Service Endpoint class with the generated servlet class. If the JAX-RPC Service Endpoint was specified without a corresponding servlet-mapping, the deployment tool generates one. The WSDL port address for the Port component is the combination of the web app context-root and url-pattern of the servlet-mapping. If the implementation is a stateless session bean, the deployment tool has a variety of options available to it. In general, the deployment tool generates a servlet to handle parsing the incoming SOAP request, the servlet obtains a reference to an instance of an appropriate EJBObject and dispatches the request to the stateless session EJB. How the request is dispatched to the Service Implementation Bean is dependent on the deployment tool and deploy time binding information supplied by the deployer.

The deployment tool must deploy and publish all the ports of all WSDL documents described in the Web services deployment descriptor. The deployment tool updates or generates the WSDL port address for each deployed port-component. The updated WSDL documents are then published to a location determined by the deployer. It could be as simple as publishing to a file in the modules containing the deployed services, a URL location representing the deployed services of the server, a UDDI or ebXML registry, or a combination of these. This is required for the next step, which is resolving references to Web services.

For each service reference described in the Web services client deployment descriptors, the deployment tool ensures that the client code can access the Web service. The deployment tool examines the information provided in the client deployment descriptor (the Service interface class, the Service Endpoint Interface class, and WSDL ports the client wants to access) as well as the JAX-RPC mapping information. In general the procedure includes providing an implementation of the JAX-RPC Service interface class declared in the deployment descriptor service reference, generating stubs for all the service-endpoint-interface declarations (if generated Stubs are supported and the deployer decides to use them), and binding the Service class implementation into a JNDI namespace. The specifics depend on whether or not the service is declared as a client managed or container managed access.

When client managed port access is used, the deployment tool must provide generated stubs or dynamic proxy access to every port declared within the Web services client deployment descriptor. The choice of generated stub or dynamic proxy is deploy time binding information. The container must provide an implementation for a Generated Service Interface if declared within the deployment descriptor.

When container managed port access to a service is used, the container must provide generated stubs or dynamic proxy access to every port declared within the deployment descriptor. The choice of generated stub or dynamic proxy is deploy time binding information. The deployment descriptor may contain a port-component-link to associate the reference not only with the Service Endpoint Implementation, but with the WSDL that defines it.

Once the Web services enabled deployable artifact has been converted into a J2EE deployable artifact, the deployment process continues using normal deployment processes.

Generation of any run-time classes the container requires to support a JAX-RPC Service Endpoint or Stateless Session Bean Service Implementation is provider specific. The behavior of the run-time classes must match the deployment descriptor settings of the component. A JAX-RPC Service Endpoint must match the behavior defined by the servlet element in the web.xml deployment descriptor. A Stateless Session Bean Service Implementation must match the behavior defined by the session element and the assembly-descriptor in the ejb-jar.xml deployment descriptor.

The container must update and/or generate a deployed WSDL document for each declared wsdl-file element in the Web services deployment descriptor (webservices.xml). If multiple wsdl-file elements refer to the same location, a separate WSDL document must be generated for each. The container must not update a WSDL file located in the document root of a WAR file.

The WSDL document described by the wsdl-file element must contain service and port elements and every port-component in the deployment descriptor must have a corresponding WSDL port and vice versa. The deployment tool must update the WSDL port address element to produce a deployed WSDL document. The generated port address information is deployment time binding information. In the case of a port-component within a web module, the address is partially constrained by the context-root of the web application and partially constructed from the servlet-mapping (if specified).

The deployment tool and/or container must make the WSDL document that a service-ref is bound to available via a URL returned by the Service Interface getWSDLDocumentLocation() method. This may or may not be the same WSDL document packaged in the module. The process of publishing the bound service-ref WSDL is analogous to publishing deployed WSDL, but only the service-ref that is bound to it is required to have access to it. A Web Services for J2EE provider is required to provide a URL that maintains the referential integrity of the WSDL document the service-ref is bound to if the wsdl-file element refers to a document located in the wsdl directory or one of its subdirectories.

The deployment tool must publish every deployed WSDL document. The deployed WSDL document may be published to a file, URL, or registry. File and URL publication must be supported by the provider. File publication includes within the generated artifacts of the application. Publication to a registry, such as UDDI or ebXML, is encouraged but is not required. If publication to a location other than file or URL is supported, then location of a WSDL document containing a service from that location must also be supported. As an example, a Web services deployment descriptor declares a wsdl-file StockQuoteDescription.wsdl and a port-component which declares a port QName within the WSDL document. When deployed, the port address in StockQuoteDescription.wsdl is updated to the deployed location. This is published to a UDDI registry location. In the same application, a service-ref uses a port-component-link to refer to the deployed port-component. The provider must support locating the deployed WSDL for that port component from the registry it was published to. This support must be available to a deployed client that is not bundled with the application containing the service. Publishing to at least one location is required. Publishing to multiple locations is allowed, but not required. The choice of where (both location and how many places) to publish is deployment time binding information. A Web Services for J2EE provider is required to support publishing a deployed WSDL document if the Web services deployment descriptor (webservices.xml) wsdl-file element refers to a WSDL file contained in the wsdl directory or subdirectory. A vendor may support publication of WSDL files packaged in other locations, but these are considered non-portable. A provider may publish the static content (e.g. no JSPs or Servlets) of the entire wsdl directory and all its subdirectories if the deploy tool cannot compute the minimal set of documents to publish in order to maintain referential integrity. The recommended practice is to place WSDL files referenced by a wsdl-file element and their relative imported documents under the wsdl directory. Web Services for J2EE providers are free to organize the published WSDL documents however they see fit so long as referential integrity is maintained. For example, the wsdl directory tree may be collapsed to a flat published directory structure (updating import statements appropriately). Clients should not depend on the wsdl directory structure being maintained during publication. Access to relatively imported documents should only be attempted by traversing the published WSDL document at the location chosen by the deployer.

The container must provide an implementation of the JAX-RPC Service Interface. There is no requirement for a Service Implementation to be created during deployment. The container may substitute a Generated Service Interface Implementation for a generic Service Interface Implementation. The container must provide an implementation of the JAX-RPC Generated Service Interface if the Web services client deployment descriptor defines one. A Generated Service Interface Implementation will typically be provided during deployment. The Service Interface Implementation must provide a static stub and/or dynamic proxy for all ports declared by the service element in the WSDL description. A container provider must support at least one of static stubs or dynamic proxies, but may provide support for both. The container must make the required Service Interface Implementation available at the JNDI namespace location java:comp/env/service-ref-name where service-ref-name is the name declared within the Web services client deployment descriptor using the service-ref-name element.

If a service-ref contains a port-component-ref that contains a port-component-link, the deployer should bind the container managed Port for the SEI to the deployed port address of the port-component referred to by the port-component-link. For example, given a webservices.xml file containing:


<webservices>
	<webservice-description>
		<webservice-description-name>JoesServices</webservice-description-name>
		<wsdl-file>META-INF/joe.wsdl</wsdl-file>
		<jaxrpc-mapping-file>META-INF/mapping.xml</jaxrpc-mapping-file>
		<port-component>
			<port-component-name>JoePort</port-component-name>
			...
			<service-impl-bean>
				<ejb-link>JoeEJB</ejb-link>
			</service-impl-bean>
		</port-component>
	</webservice-description>
</webservices>
					
					
and a module's deployment descriptor containing:

<service-ref>
	<service-ref-name>service/Joe</service-ref-name>
	<service-interface>javax.xml.rpc.Service</service-interface>
	<wsdl-file>WEB-INF/joe.wsdl</wsdl-file>
	...
	<port-component-ref>
		<service-endpoint-interface>sample.Joe</service-endpoint-interface>
		<port-component-link>JoePort</port-component-link>
	</port-component-ref>
</service-ref>

					
During deployment, the deployer must provide a binding for the port address of the JoePort port-component. This port address must be defined in the published WSDL for JoesServices. The deployer must also provide a binding for container managed port access to the sample.Joe Service Endpoint Interface. This should be the same binding used for the port address of the JoePort port-component. When providing a binding for a port-component-ref, the deployer must ensure that the port-component-ref is compatible with the Port being bound to.

EJB 2.1 Web Service deployment descriptor

The Bean Provider must use web service references to locate web service interfaces as follows.

  • Assign an entry in the enterprise bean’s environment to the reference.

  • The EJB specification recommends, but does not require, that all references to web services be organized in the service subcontext of the bean’s environment (i.e., in the java:comp/env/service JNDI context).

  • Look up the JAX-RPC web service interrface of the referenced service in the enterprise bean's environment using JNDI.

The following example illustrates how an enterprise bean uses an web service reference to locate a web service interface and invoke a method on the service endpoint:
public class InvestmentBean implements SessionBean {
	public void checkPortfolio(...) {
		...
		// Obtain the default initial JNDI context.
		Context initCtx = new InitialContext();
	
		// Look up the stock quote service in the environment.
		com.example.StockQuoteService sqs = (com.example.StockQuoteService)initCtx.lookup(
			"java:comp/env/service/StockQuoteService");
		
		// Get the stub for the service endpoint
		com.example.StockQuoteProvider sqp = sqs.getStockQuoteProviderPort();

		// Get a quote
		float quotePrice = sqp.getLastTradePrice(...);
		...
	}
}
					
In the example, the Bean Provider of the InvestmentBean enterprise bean assigned the environment entry service/StockQuoteService as the web service reference name to refer to the StockQuoteService JAX-RPC web service interface.

Although the web service reference is an entry in the enterprise bean's environment, the Bean Provider must not use a env-entry element to declare it. Instead, the Bean Provider must declare all the web service references using the service-ref elements of the deployment descriptor. This allows the ejb-jar consumer (i.e. Application Assembler or Deployer) to discover all the web service references used by the enterprise bean.

Each service-ref element describes the interface requirements that the referencing enterprise bean has for the referenced web service. The service-ref element contains an optional description element and the mandatory service-ref-name and service-interface elements. The use of service references and the service-ref deployment descriptor element are described in further detail in [Web Services for J2EE, Version 1.1. http://jcp.org/en/jsr/detail?id=109, http://jcp.org/en/jsr/detail?id=921].

The service-ref-name element specifies the web service reference name: its value is the environment entry name used in the enterprise bean code. The service-interface element specifies the fully qualified name of the JAX-RPC service interface returned by the JNDI lookup.

A web service reference is scoped to the enterprise bean whose declaration contains the service-ref element. This means that the web service reference is not accessible to other enterprise beans at runtime, and that other enterprise beans may define service-ref elements with the same service-ref-name without causing a name conflict.

The following example illustrates the declaration of a web service reference in the deployment descriptor (ejb-jar.xml):


<session>
	...
	<ejb-name>InvestmentBean</ejb-name>
	<ejb-class>com.wombat.empl.InvestmentBean</ejb-class>
	...
	
	<service-ref>
		<description>
			This is a reference to the stock quote
			service used to estimate portfolio value.
		</description>
		<service-ref-name>service/StockQuoteService</service-ref-name>
		<service-interface>com.example.StockQuoteService</service-interface>
	</service-ref>
	
	...
</session>
					
					

JAX-RPC Web Services deployment descriptor

JSR-109 [http://jcp.org/jsr/detail/109.jsp] defines the model for packaging a Web service interface with its associated WSDL description and associated classes. It defines a mechanism for JAX-RPC-enabled Web containers to link to a component that implements this Web service. A JAX-RPC Web service implementation component uses the APIs defined by the JAX-RPC specification, which defines its contract with the JAX-RPC enabled Web container. It is packaged into the WAR file. The Web service developer makes a declaration of this component using the usual servlet declaration. The JAX-RPC-enabled Web container must support the developer in using the Web deployment descriptor to define the following information for the endpont implementation component, using the same syntax as for HTTP Servlet components:

  • a logical name which may be used to locate this endpoint description among the other Web components in the WAR

  • the fully qualified Java class name of this endpoint implementation

  • descriptions of the component which may be displayed in a tool

  • the order in which the component is initialized relative to other Web components in the Web container

  • security-role-reference that it may use to test whether the authenticated user is in a logical security role

  • whether or not to override the identity propagated to EJBs called by this component

Any servlet initialization parameters defined by the developer for this Web component may be ignored by the container. Additionally, the JAX-RPC enabled Web component inherits the traditional Web component mechanisms for defining information:

  • mapping of the component to the Web container's URL namespace using the servlet mapping technique

  • authorization constraints on Web components using security constraints

  • the ability to use servlet filters to provide low-level byte stream support for manipulating JAX-RPC messages using the filter mapping technique

  • the timeout characteristics of any HTTP sessions that are associated with the component

  • links to J2EE objects stored in the JNDI namespace

The service-ref declares the reference to a Web service. The service-ref-name declares the logical name that the components in the module use to look up the Web service. It is recommended that all service reference names start with /service/. The service-interface defines the fully qualified class name of the JAX-RPC Service interface that the client depends on. In most cases, the value will be javax.xml.rpc.Service. A JAX-RPC generated Service Interface class may also be specified. The wsdl-file element contains the URI location of a WSDL file. The location is relative to the root of the module. The jaxrpc-mapping-file contains the name of a file that describes the JAX-RPC mapping between the Java interaces used by the application and the WSDL description in the wsdl-file. The file name is a relative path within the module file. The service-qname element declares the specific WSDL service element that is being refered to. It is not specified if no wsdl-file is declared. The port-component-ref element declares a client dependency on the container for resolving a Service Endpoint Interface to a WSDL port. It optionally associates the Service Endpoint Interface with a particular port-component. This is only used by the container for a Service.getPort(Class) method call. The handler element declares the handler for a port-component. Handlers can access the init-param name-value pairs using the HandlerInfo interface. If port-name is not specified, the handler is assumed to be associated with all ports of the service. See JSR-109 Specification [http://www.jcp.org/en/jsr/detail?id=921] for detail. The container that is not a part of a J2EE implementation is not required to support this element. Example of web.xml:


<service-ref>
   <service-ref-name>service/MyHelloServiceRef</service-ref-name>
   <service-interface>javax.xml.rpc.Service</service-interface>
      ....
      <port-component-ref> 
         ....
      </port-component-ref>
      <handler>
         <handler-name>First Handler</handler-name>
         <handler-class >example.AccountTransactionHandler</handler-class>
         <port-name>portA</port-name>
      </handler>
      <handler>
         <handler-name>Second Handler </handler-name>
         <handler-class>example.NewAccountHandler< /handler-class>
         <port-name>portB</port-name>
      </handler>
</service-ref>

 					
 					

Professional hosting     Belorussian informational portal         Free SCWCD 1.4 Study Guide     Free SCBCD 1.3 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     Free SCJP 5.0 (Tiger) Study Guide     Free Mock Exam Engine     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide     IBM Test 000-255. Developing with IBM Rational Application Developer for WebSphere Software V6 Study Guide