Web services deployment descriptor: jboss-webservices.xml

For those willing to configure a given Web Services endpoint deployment without adding a compile time dependency to WildFly (or Apache CXF) specific classes, the jboss-webservices.xml descriptor can be also used. It needs to be placed either in WEB-INF or META-INF folder of the deployment (depending on it being a war or jar archive) and is structured as follows:

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
   <context-root />
   <config-name />
   <config-file />
   <property>
      <name />
      <value />
   </property>
   <port-component>
      <ejb-name />
      <port-component-name />
      <port-component-uri />
      <auth-method />
      <transport-guarantee />
      <secure-wsdl-access />
   </port-component>
</webservices>

Let’s see in detail each element that makeup the jboss-webservices.xml descriptor:

  • context-root element: The context-root element can be used to customize the context root of the web application that is being deployed.
<webservices>
   <context-root>my-context-root</context-root>
</webservices>
  • config-name and config-file elements

The example below is from a jar archive containing EJB3 endpoint(s); the custom.xml config file is referenced and will have to be included in META-INF folder of the deployment archive.

<webservices>
   <config-name>My Custom Endpoint</config-name>
   <config-file>META-INF/custom.xml</config-file>
</webservices>
  • property element
<property>
   <name>prop.name</name>
   <value>prop.value</value>
</property>

Among the supported properties, there are some JBossWS defined ones that control Apache CXF integration without requiring Apache CXF API direct usage in the deployment. Check the wiki for additional information about it.

  • port-component element
<webservices>
   <port-component>
      <ejb-name>TestService</ejb-name>
      <port-component-name>TestServicePort</port-component-name>
      <port-component-uri>/*</port-component-uri>
      <auth-method>BASIC</auth-method>
      <transport-guarantee>NONE</transport-guarantee>
      <secure-wsdl-access>true</secure-wsdl-access>
   </port-component>
</webservices>

Example usage:

As an example of jboss-webservices.xml usage, we’ll be controlling the way Apache CXF deals with WS-Policy alternatives for incoming messages. A WS-Policy represents a set of specifications that describe the capabilities and constraints of the security policies on intermediaries and endpoints. It also deals with how to associate policies with services and endpoints. Have a look at the following WS-Policy example, featuring a policy having two alternatives:

<wsp:Policy>
   <wsp:ExactlyOne>
      <wsp:Policy>
         <wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2006/05/addressing/wsdl"/>
      </wsp:Policy>
      <wsp:Policy>
	<wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2006/05/addressing/wsdl"/>
		<wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"/>
	</wsp:Policy>
   </wsp:ExactlyOne>
</wsp:Policy>

When the Apache CXF policy engine processes incoming messages on the server side, it needs a strategy to select a policy alternative if multiple ones are valid for the received message. In the example above, a message using both WS-Addressing and WS-ReliableMessaging would actually match both policy alternative requirements.

The selection task is performed by a CXF component named AlternativeSelector. The JBossWS integration defaults to org.apache.cxf.ws.policy.selector.MaximalAlternativeSelector implementation, which chooses the alternative with most assertions (in the example, that’s the second alternative, of course, as it has two assertions, while the first just has one). For complex policies, the default behavior might not always be the proper solution, so users might want a different strategy to be applied for a given deployment. That is achieved by including a jboss-webservices.xml descriptor as follows in the deployment:

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">
	<property>
		<name>cxf.policy.alternativeSelector</name>
		<value>org.apache.cxf.ws.policy.selector.MinimalAlternativeSelector</value>
	</property>
</webservices>

This excerpt is an extract from the Advanced Web Services guide from Alessio Soldano

Found the article helpful? if so please follow us on Socials