Customizing web services endpoints

We can use the ibm-ws-bnd.xml file to customize web services endpoints for server provider and client within the applications.

The ibm-ws-bnd.xml file must be in the /WEB-INF directory of a web-based web services application (WAR file), or in the /META-INF directory of a EJB-based web service application (JAR file). If the client is running in clientContainer, the ibm-ws-bnd.xml file must be in the /META-INF directory of the JAR file in the client EAR.

By configuring the ibm-ws-bnd.xml file, we can override the web services address configurations on both the service provider and consumer, export your web services using a specific URL in the applications deployed on Liberty, and import the web services from JAX-WS client applications.

For all available elements we can configure within the ibm-ws-bnd.xml file.

1. Override web services bindings for service providers.
   1. Override the web services endpoint address. In the webservice-endpoint element, we can override the endpoint address of a web service endpoint identified by the port-component-name attribute. The address attribute specifies the relative path to the context root of the application.

      <?xml version="1.0" encoding="UTF-8"?>
      <webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
      		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      		xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd" 
      		version="1.0">
      	<!-- 0 to many endpoint descriptions -->
      	<webservice-endpoint port-component-name="Hello" address="/hiService" />
      </webservices-bnd>

   2. Override the context root for EJB based web services. If the web service is an EJB-based web service and defined in an EJB application (JAR archive), the default context root is the EJB jar name. However, we can override the default value using the context-root attribute of the http-publishing element.

      <?xml version="1.0" encoding="UTF-8"?>
      <webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
      		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      		xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd" 
      		version="1.0">
      	<!-- optional http publishing module overrides -->
      	<http-publishing context-root="/HiServer" />
      </webservices-bnd>

      Note that the context-root attribute takes effective only when the web service is an EJB based web service and defined in an EJB jar archive. If the web service is defined in a web application (WAR archive), no matter if it is an EJB based web service, the context-root attribute of the http-publishing element is ignored, and the context root will always be the context root of the web application.

2. Override web services bindings for client applications.
   1. Override the location of the WSDL document. In the service-ref element, we can override the WSDL location of a web service reference within a web service client application.

      <?xml version="1.0" encoding="UTF-8"?>
      <webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
      		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      		xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd" 
      		version="1.0">
      	<service-ref name="services/hello" wsdl-location="http://localhost:9080/HiServer/hiService?wsdl" />
      </webservices-bnd>

      The wsdl-location attribute specifies an absolute URI (either HTTP or file protocol), and it can also be an relative URI to the root of the client application. For example:

      <?xml version="1.0" encoding="UTF-8"?>
      <webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
      		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      		xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd" 
      		version="1.0">
      	<service-ref name="services/hello" wsdl-location="WEB-INF/wsdl/hiService.wsdl" />
      </webservices-bnd>

   2. Override the Port Address. In the port element, we can override the address of a port within web service reference in a web service client.

      <?xml version="1.0" encoding="UTF-8"?>
      <webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
      		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      		xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd" 
      		version="1.0">
      	<service-ref name="services/hello" wsdl-location="WEB-INF/wsdl/hiService.wsdl">
      		<port name="HelloPort" namespace="http://server.ejb.hello.sample.jaxws.ws.ibm.com/" 
      				address="http://localhost:9080/HiServer/hiService" />
      	</service-ref>
      </webservices-bnd>

      The address attribute of the port element specifies the absolute URI of a web service port. If the referenced web service only has one port, we can use the port-address attribute of the service-ref element. For example:

      <webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
      		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      		xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd" 
      		version="1.0">
      	<service-ref name="services/hello" 
      			port-address="http://localhost:9080/HiServer/hiService" />
      </webservices-bnd>

      Note: If the port-address attribute of the service-ref element and the address attribute of the port element are both specified, the address attribute of the port element takes effect.