Web services deployment descriptor: jboss-webservices.xml

For developers who want to configure a Web Services endpoint deployment without adding compile-time dependencies to WildFly or Apache CXF-specific Java classes, the jboss-webservices.xml descriptor is the ideal solution. In the modern Jakarta EE 11 ecosystem (supported by WildFly 41.0.1.Final), this descriptor seamlessly manages endpoints powered by the JBossWS-CXF stack.

The descriptor must be placed in either the WEB-INF folder (for WAR deployments) or the META-INF folder (for JAR/EJB deployments) of your archive. It is structured according to the following schema definition:

<webservices xmlns="http://www.jboss.com/xml/ns/javaee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/schema/jbossas/jboss-webservices_1_2.xsd"
             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 examine each element that makes up the modern jboss-webservices.xml descriptor in detail:

1. The <context-root> Element

The context-root element customizes the base context path of the web application containing your SOAP endpoints. This is incredibly useful for aligning the service URL with your organization's API naming conventions.

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
   <context-root>api/v1/soap</context-root>
</webservices>

2. The <config-name> and <config-file> Elements

These elements link the deployment to a predefined or custom client/endpoint configuration. If you are deploying an EJB3-based SOAP endpoint packaged inside a JAR, you can reference a custom configuration file packaged within the archive itself.

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
   <config-name>My Custom Endpoint</config-name>
   <config-file>META-INF/custom.xml</config-file>
</webservices>

3. The <property> Element

Properties let you configure low-level engine parameters. In WildFly 41, these properties primarily fine-tune JBossWS-CXF integration features (such as schema validation, message logging, and WS-Security configurations) without polluting your Java codebase with proprietary annotations.

<property>
   <name>schema-validation-enabled</name>
   <value>true</value>
</property>

4. The <port-component> Element

The port-component element is used to map configuration specifics to EJB-based endpoints. Here, you define URL patterns, authentication rules, and transport requirements.

Security Warning: In modern environments, never deploy endpoints with weak security profiles. Instead of using plain HTTP, always configure your server for HTTPS/TLS. In your configuration, utilize CONFIDENTIAL transport guarantees to enforce SSL/TLS encryption.

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" version="1.2">
   <port-component>
      <ejb-name>SecureBillingService</ejb-name>
      <port-component-name>BillingServicePort</port-component-name>
      <port-component-uri>/billing/*</port-component-uri>
      <auth-method>CLIENT-CERT</auth-method>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      <secure-wsdl-access>true</secure-wsdl-access>
   </port-component>
</webservices>

Real-World Example: Controlling Apache CXF WS-Policy Selection

To see the power of the jboss-webservices.xml descriptor, let's look at how it can modify the internal behavior of Apache CXF. This is highly useful when dealing with WS-Policy alternatives for incoming SOAP messages. WS-Policy allows a service provider to define constraints and capabilities (such as WS-Addressing or WS-ReliableMessaging) that a caller must satisfy.

Consider the following WS-Policy example defined in a WSDL, which features two distinct alternatives:

<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-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, it uses an AlternativeSelector strategy to choose between valid alternatives. By default, JBossWS integration configures CXF to use the MaximalAlternativeSelector, which automatically selects the policy option containing the highest number of assertions (in this case, the second alternative because it includes both Addressing and RM).

For complex deployments, the default behavior might not be what you want. You can force CXF to use a different strategy—such as the MinimalAlternativeSelector—by configuring a property inside your deployment's jboss-webservices.xml without altering a single line of Java code:

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

This approach keeps your code strictly standard-compliant with Jakarta XML Web Services 4.0 (part of Jakarta EE 11) while utilizing the full runtime capabilities of the JBossWS-CXF stack on WildFly 41.

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

Frequently Asked Questions (FAQs)