Handlers

For each endpoint configuration, both PRE and POST handler chains can be specified. Each handler chain may include JAXWS handlers. For outbound messages, PRE handler chain handlers are meant to be executed before any handler attached to the endpoints using standard JAXWS means (e.g. using @HandlerChain), while POST handler chain handlers are executed after usual endpoint handlers. For inbound messages, the opposite applies.

* Server inbound messages
Client --> ... --> POST HANDLER --> ENDPOINT HANDLERS --> PRE HANDLERS --> Endpoint

* Server outbound messages
Endpoint --> PRE HANDLER --> ENDPOINT HANDLERS --> POST HANDLERS --> ... --> Client

The same applies for client configurations.

Properties

Key/value properties are used for controlling both some Apache CXF internals and some JBossWS options. Specific supported values are mentioned where relevant in the rest of the documentation.

Endpoint configuration assignment

JAX-WS endpoints can be assigned to a given configuration by annotating them with the org.jboss.ws.api.annotation.EndpointConfig annotation:

@EndpointConfig(configFile = "WEB-INF/jaxws-endpoint-config.xml", configName = "Custom WS-Security Endpoint")
public class ServiceImpl implements ServiceIface
{
   public String sayHello()
   {
      return "Secure Hello World!";
   }
}

The configFile attribute is used to specify with config file, if any, is to be used to load the configuration; if configFile is not set, the application server configurations are used.

The configName attributed is used to specify the name of the configuration to be used.

Alternatively, configurations can be assigned to endpoints through the jboss-webservices.xml deployment descriptor. 

The configuration file, if any, needs to be included in the endpoint deployment; the jbossws-jaxws-config schema defines its contents and is included in the jbossws-spi artifact.

Client configuration assignment

JBossWS API comes with facility classes for assigning configurations when building up a client; JAXWS handlers can be read from client configurations as follows:

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

...

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = (Endpoint)service.getPort(Endpoint.class);
BindingProvider bp = (BindingProvider)port;
ClientConfigUtil.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 1");
port.echo("Kermit");

...

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 2");
port.echo("Kermit");

...

configurer.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 3");
port.echo("Kermit");


...

configurer.setConfigHandlers(bp, null, "Container Custom Client Config"); //reads from container configurations
port.echo("Kermit");

... similarly, properties are read from client configurations as follows:

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

...

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = (Endpoint)service.getPort(Endpoint.class);

ClientConfigUtil.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 1");
port.echo("Kermit");

...

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 2");
port.echo("Kermit");

...

configurer.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 3");
port.echo("Kermit");


...

configurer.setConfigProperties(port, null, "Container Custom Client Config"); //reads from container configurations
port.echo("Kermit");

The default ClientConfigurer implementation parses the specified configuration file, if any, after having resolved it as a resources using the current thread context classloader. The jbossws-jaxws-config schema defines the descriptor contents and is included in the jbossws-spi artifact.

Standard configurations

Clients running in-container as well as endpoints are assigned standard configurations by default. Those are used unless different configurations are set as previously described. This way administrators can tune default handler chains for client and endpoints developers did not assign a specific configuration to. The name for such default configuration, to be used in the JBoss AS 7 webservices subsystem are Standard-Client-Config and Standard-Endpoint-Config.

Handlers classloading

When setting a server-wide handler, please note the handler class needs to be available either through each ws deployment classloader or the org.jboss.as.webservices.server.integration:main module classloader. As a consequence proper module dependencies might need to be specified either in the deployments that are going to leverage a given predefined configuration or directly in the previously mentioned AS7 module.