3.8 Deploying and Packaging a Service Endpoint

Up to now, we have examined Web services on the J2EE platform in terms of design, development, and implementation. Once you complete the Web services implementation, you must write its deployment descriptors, package the service with all its components, and deploy the service.

• Developers should, if at all possible, use tools or IDEs to develop a Web service. These Web service development tools and IDEs automatically create the proper deployment descriptors for the service and correctly handle the packaging of the service--steps necessary for a service to operate properly. Furthermore, tools and IDEs hide these details from the developer.

Although you can expect your development tool to perform these tasks for you, it is good to have a conceptual understanding of the J2EE 1.4 platform deployment descriptor and packaging structure, since they determine how a service is deployed on a J2EE server and the service's availability to clients. This section, which provides a conceptual overview of the deployment and packaging details, is not essential reading. Nonetheless, you may find it worthwhile to see how these details contribute to portable, interoperable Web services.

3.8.1 Service Information in the Deployment Descriptors

To successfully deploy a service, the developer provides the following information.

• Deployment-related details of the service implementation, including the Web service interface, the classes that implement the Web service interface, and so forth.
• Details about the Web services to be deployed, such as the ports and mappings
• Details on the WSDL port-to-port component relationship

More specifically, the deployment descriptor contains information about a service's port and associated WSDL. Recall from "Web Service Technologies Integrated in J2EE Platform" on page 49:

• A port component (also called a port) gives a view of the service to clients such that the client need not worry about how the service has been implemented.
• Each port has an associated WSDL.
• Each port has an associated service endpoint (and its implementation). The endpoint services all requests that pass through the location defined in the WSDL port address.

To begin, the service implementation declares its deployment details in the appropriate module-specific deployment descriptors. For example, a service implementation that uses a JAX-RPC service endpoint declares its details in the WEB-INF/web.xml file using the servlet-class element. (See Code Example 3.21.)

<web-app ...>
	...
	<servlet>
		<description>Endpoint for Some Web Service</description>
		<display-name>SomeWebService</display-name>
		<servlet-name>SomeService</servlet-name>
		<servlet-class>com.a.b.c.SomeServiceImpl</servlet-class>
		<load-on-startup>0</load-on-startup>
	</servlet>
	<servlet-mapping>
		<servlet-name>SomeService</servlet-name>
		<url-pattern>/webservice/SomeService</url-pattern>
	</servlet-mapping>
	...
</web-app>

Note that when you have a service that functions purely as a Web service using JAX-RPC service endpoints, some specifications in the web.xml file, such as <error-page> and <welcome-file-list>, have no effect.

A service implementation that uses an EJB service endpoint declares its deployment details in the file META-INF/ejb-jar.xml using the session element. (See Code Example 3.22.)

<ejb-jar ...>
	<display-name>Some Enterprise Bean</display-name>
	<enterprise-beans>
		<session>
			<ejb-name>SomeBean</ejb-name>
			<service-endpoint>com.a.b.c.SomeIntf</service-endpoint>
			<ejb-class>com.a.b.c.SomeServiceEJB</ejb-class>
			<session-type>Stateless</session-type>
			<transaction-type>Container</transaction-type>
		</session>
	</enterprise-beans>
	...
</ejb-jar>

Next, the details of the port are specified. The Web service deployment descriptor, called webservices.xml, defines and declares the structural details for the port of a Web service. This file contains the following information:

• A logical name for the port that is also unique among all port components (port-component-name element)
• The service endpoint interface for the port (service-endpoint-interface -element)
• The name of the class that implements the service interface (service-impl-bean element)
• The WSDL file for the service (wsdl-file element)
• A QName for the port (wsdl-port element)
• A correlation between WSDL definitions and actual Java interfaces and definitions using the mapping file (jaxrpc-mapping-file element)
• Optional details on any handlers

The reference to the service implementation bean, specified using the service-impl-bean element in webservices.xml, is either a servlet-link or an ejb-link depending on whether the endpoint is a JAX-RPC or EJB service endpoint. This link element associates the Web service port to the actual endpoint implementation defined in either the web.xml or ejb-jar.xml file.

The JAX-RPC mapping file, which is specified using the jaxrpc-mapping-file element in webservices.xml, keeps details on the relationships and mappings between WSDL definitions and corresponding Java interfaces and definitions. The information contained in this file, along with information in the WSDL, is used to create stubs and ties for deployed services.

Thus, the Web services deployment descriptor, webservices.xml, links the WSDL port information to a unique port component and from there to the actual implementation classes and Java-to-WSDL mappings. Code Example 3.23 is an example of the Web services deployment descriptor for our sample weather Web service, which uses a JAX-RPC service endpoint.

<webservices ...>
	<description>Web Service Descriptor for weather service
	</description>
	<webservice-description>
		<webservice-description-name>
			WeatherWebService
		</webservice-description-name>
		<wsdl-file>
			WEB-INF/wsdl/WeatherWebService.wsdl
		</wsdl-file>
		<jaxrpc-mapping-file>
			WEB-INF/WeatherWebServiceMapping.xml
		</jaxrpc-mapping-file>
		<port-component>
			<description>port component description</description>
			<port-component-name>
				WeatherServicePort
			</port-component-name>
			<wsdl-port xmlns:weatherns="urn:WeatherWebService">
				weatherns:WeatherServicePort
			</wsdl-port>
			<service-endpoint-interface>
				endpoint.WeatherService
			</service-endpoint-interface>
			<service-impl-bean>
				<servlet-link>WeatherService</servlet-link>
			</service-impl-bean>
		</port-component>
	</webservice-description>
</webservices>

3.8.2 Package Structure

Once the service implementation and deployment descriptors are completed, the following files should be packaged into the appropriate J2EE module:

• The WSDL file
• The service endpoint interface, including its implementation and dependent classes
• The JAX-RPC mapping file, which specifies the package name containing the generated runtime classes and defines the namespace URI for the service. See Code Example 5.21 on page 242.
• The Web service deployment descriptor

The type of endpoint used for the service implementation determines the type of the J2EE module to use.

• The appropriate J2EE module for a service with a JAX-RPC service endpoint is a WAR file. A service using an EJB service endpoint must be packaged in an EJB-JAR file.

The package structure is as follows:

• WSDL files are located relative to the root of the module.
• The service interface, the service implementation classes, and the dependent classes are packaged just like any other J2EE component.
• The JAX-RPC mapping file is located relative to the root of the module (typically in the same place as the module's deployment descriptor).
• The Web service deployment descriptor location depends on the type of service endpoint, as follows:

See Figure 3.10, which shows a typical package structure for a Web service using an EJB endpoint. Figure 3.11 shows the typical structure for a Web service using a JAX-RPC endpoint.

Figure 3.10 Package Structure for EJB Endpoint

Figure 3.11 Package Structure for JAX-RPC Service Endpoint