Customizing URL patterns in the web.xml file for JAX-WS applications

Customize URL patterns in the web.xml file for JAX-WS applications

The web.xml file contains information about the structure and external dependencies of web components in the module and describes how the components are used at run time. For JAX-WS applications, we can customize the URL pattern in the web.xml file.

Complete the JavaBeans implementation.

When we package a JavaBeans-based JAX-WS application as a web service, the web service is contained within a web application archive (WAR) file or a WAR module within an EAR file. A JAX-WS enabled WAR file contains the following items:

A WEB-INF/web.xml file that describes configuration and deployment information for the web components that comprise a web application.
Annotated classes that implement the web services contained in the application module including the service endpoint implementation class.
JAXB classes
(Optional) WSDL documents that describe the web services contained in the application module.
(Optional) XML schema file
(Optional) utility classes
(Optional) web service clients

The default URL pattern is defined by the @WebService.serviceName attribute contained in the web service implementation class. When the WSDL file associated with your service implementation class contains a single port definition, we can choose to use the default URL pattern or we can customize the URL pattern within the web.xml file. When the WSDL file associated with your service implementation class contains multiple port definitions within the same service definition, customized URL patterns are required. If we use the default URL pattern when the service implementation class contains multiple port definitions, then multiple service implementation classes are mapped to the same URL pattern which results in an error condition. We must edit the web.xml file and customize the URL patterns for each service definition. Each port maps to a web service implementation class and to its own custom URL pattern. By customizing the URL pattern in the web.xml file, you correct conflicting URL pattern definitions.

If our JAX-WS application is packaged in an EJB Java archive (JAR) file within an EAR file, we can customize the URL patterns using the endptEnabler command.

Tasks

Determine if custom URL patterns are required or desired. Custom URL patterns are only required when the WSDL file for the JAX-WS web service contains multiple port definitions within a single service. Otherwise, we can optionally define custom URL patterns.
To customize the URL pattern for a service implementation class, edit the web.xml file and provide a <servlet> and corresponding <servlet-mapping> entry for each JAX-WS web service implementation class for which a custom URL pattern is desired. We must define the <url-pattern> value within the <servlet-mapping> entry.

You now have a web services-enabled web application archive (WAR) file with customized URL patterns.

Single WSDL port definition within a service implementation class

The following example illustrates the default URL pattern and how to customize the URL pattern when the WSDL file associated with the service implementation class has a single port definition.

This is an excerpt from a sample web service implementation class.
package com.ibm.test;
@WebService(serviceName="EchoService", portName="SOAP11EchoServicePort")
public class EchoServiceSOAP11{
This is an excerpt from the WSDL file associated with the EchoServiceSOAP11 web service implementation class:
<wsdl:service name="EchoService">
	<wsdl:port name="SOAP11EchoServicePort" tns:binding="..." >
		...
	</wsdl:port>
</wsdl:service>
As prescribed by JSR-109, the default URL pattern in this example is constructed using the @WebService.serviceName attribute and the default URL pattern is /EchoService.
To optionally customize the URL pattern for this example, edit the web.xml file and provide a url-pattern entry. In this example, the customized URL pattern is now /EchoServiceSOAP11.

The following excerpt is from a sample web.xml file that demonstrates setting up a servlet:
<servlet id="...">
	<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
	<servlet-class>com.ibm.test.EchoServiceSOAP11</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
	<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
	<url-pattern>/EchoServiceSOAP11</url-pattern> ---->  Defining the URL pattern and 
pointing it to the service implementation class.
</servlet-mapping>
The following example illustrates the required URL pattern customizations when the WSDL file associated with the service implementation class has multiple port definitions.

The following excerpt is from a sample web service implementation class:
package com.ibm.test;
@WebService(serviceName="EchoService", portName="SOAP11EchoServicePort")
public class EchoServiceSOAP11{
	...
}
package com.ibm.test;
@WebService(serviceName="EchoService", portName="SOAP12EchoServicePort")
public class EchoServiceSOAP12{
	...
}
The following excerpt is from the WSDL file associated with the EchoServiceSOAP11 web service implementation class. Each port in the WSDL file maps to a portName in the web service implementation class.
<wsdl:service name="EchoService">
	<wsdl:port name="SOAP11EchoServicePort" tns:binding="..." >
		...
	</wsdl:port>
	<wsdl:port name="SOAP12EchoServicePort" tns:binding="..." >
		...
	</wsdl:port>
</wsdl:service>
In this scenario, because there are multiple port definitions within the WSDL file, we must customize the URL pattern by editing the web.xml file. Specify custom URL patterns for each service.

The following excerpt is from a sample web.xml file that demonstrates setting up a servlet:
<servlet id="...">
	<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
	<servlet-class>com.ibm.test.EchoServiceSOAP11</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
	<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
	<url-pattern>/EchoServiceSOAP11</url-pattern>
</servlet-mapping>

<servlet id="...">
	<servlet-name>com.ibm.test.EchoServiceSOAP12</servlet-name>
	<servlet-class>com.ibm.test.EchoServiceSOAP12</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
	<servlet-name>com.ibm.test.EchoServiceSOAP12</servlet-name>
	<url-pattern>/EchoServiceSOAP12</url-pattern>
</servlet-mapping>
What to do next
Assemble a WAR file enabled for web services from Java code.

Implement web services applications with JAX-WS
Implement web services applications from existing WSDL files with JAX-WS
Assembling a WAR file enabled for web services from Java code