JBoss Community Archive (Read Only)

JBoss AS 7.2

Predefined client and endpoint configurations

Overview

JBossWS comes with a concept of predefined configurations, which are kind of basic templates that can be used for both JAX-WS client and JAX-WS endpoint setup. Configurations can include JAX-WS handlers as well as basic key/value properties declarations.

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.

Assigning configurations

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.

Application server configurations

JBoss Application Server 7.x allows declaring JBossWS client and server predefined configurations in the webservices subsystem section of the server model. As a consequence it is possible to declare server-wide handlers to be added to the chain of each endpoint or client assigned to a given configuration.

Please refer to the JBoss Application Server 7 documentation for any detail on managing the webservices subsystem to add, remove or modify handlers and properties.

The allowed contents in the webservices subsystem are defined by the schema included in the application server.

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.

Examples

JBoss AS 7.2 default configurations
<subsystem xmlns="urn:jboss:domain:webservices:1.2">
    <!-- ... -->
    <endpoint-config name="Standard-Endpoint-Config"/>
    <endpoint-config name="Recording-Endpoint-Config">
        <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
            <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/>
        </pre-handler-chain>
    </endpoint-config>
    <client-config name="Standard-Client-Config"/>
</subsystem>
A configuration file for a deployment specific ws-security endpoint setup
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>Custom WS-Security Endpoint</config-name>
    <property>
      <property-name>ws-security.signature.properties</property-name>
      <property-value>bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.properties</property-name>
      <property-value>bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.signature.username</property-name>
      <property-value>bob</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.username</property-name>
      <property-value>alice</property-value>
    </property>
    <property>
      <property-name>ws-security.callback-handler</property-name>
      <property-value>org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback</property-value>
    </property>
  </endpoint-config>
</jaxws-config>
JBoss AS 7.2 default configurations modified to default to SOAP messages schema-validation on
<subsystem xmlns="urn:jboss:domain:webservices:1.2">
    <!-- ... -->
    <endpoint-config name="Standard-Endpoint-Config">
        <property name="schema-validation-enabled" value="true"/>
    </endpoint-config>
    <!-- ... -->
    <client-config name="Standard-Client-Config">
        <property name="schema-validation-enabled" value="true"/>
    </client-config>
</subsystem>
JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 13:28:21 UTC, last content change 2012-11-22 15:12:00 UTC.