+

Search Tips   |   Advanced Search

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

The web.xml file contains information about the structure and 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 web.xml.

Complete the JavaBeans implementation.

When you package a JavaBeans-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:

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 web.xml. 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. 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 EJB JAR file within an EAR file, we can customize the URL patterns using the endptEnabler command.

  1. 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, we can optionally define custom URL patterns.

  2. 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. We 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.


Single WSDL port definition within a service implementation class

Example 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 web.xml 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>

Example 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 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

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