Customizing URL patterns in web.xml 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, we can customize the URL pattern in web.xml. Complete the Java Beans™ implementation.
When you package a Java Beans-based JAX-WS application as a Web service, the Web service is contained within a 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 app.
- 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 that is associated with the 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 that is associated with the 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. You must edit web.xml 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 web.xml, you correct conflicting URL pattern definitions.
If wer JAX-WS application is packaged in an EJBs JAR file within an EAR file, we can customize the URL patterns using the endptEnabler command.
- 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, optionally define custom URL patterns.
- To customize the URL pattern for a service implementation class, edit web.xml 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 WAR file with customized URL patterns.
Example
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, customize the URL pattern by editing web.xml. 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 that is enabled for Web services from Java code.
Related tasks
Implementing Web services applications with JAX-WS
Implementing Web services applications from existing WSDL files with JAX-WS
Assembling a WAR file that is enabled for Web services from Java code