Customizing 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 Java™ API for XML-Based Web Services (JAX-WS) applications, you can customize the URL pattern in the web.xml file.
Before you begin
About this task
- 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) Web Services Description Language (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 that is contained in your web service implementation class. When the WSDL file that is associated with your service implementation class contains a single port definition, you can choose to use the default URL pattern or you can customize the URL pattern within the web.xml file. When the WSDL file that is associated with your service implementation class contains multiple port definitions within the same service definition, customized URL patterns are required. If you 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. You 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 your JAX-WS application is packaged in an Enterprise JavaBeans (EJB) Java archive (JAR) file within an enterprise archive (EAR) file, you can customize the URL patterns using the endptEnabler command.
Procedure
- Determine if custom URL patterns are required or desired.
Custom URL patterns are only required when the WSDL file for your JAX-WS web service contains multiple port definitions within a single service. Otherwise, you 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. You must define the <url-pattern> value within the <servlet-mapping> entry.
Results
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>
Multiple WSDL port definitions within a service implementation class
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, you 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>