Skip to end of metadata
Go to start of metadata

Overview

JBossWS permits extra setup configuration data to be predefined and associated with an endpoint or a client. Configurations can include JAX-WS handlers and key/value property declarations that control JBossWS and Apache CXF internals. Predefined configurations can be used for JAX-WS client and JAX-WS endpoint setup.

Configurations can be defined in the webservice subsystem and in an application's deployment descriptor file. There can be many configuration definitions in the webservice subsystem and in an application. Each configuration must have a name that is unique within the server.  Configurations defined in an application are local to the application. Endpoint implementations declare the use of a specific configuration through the use of the org.jboss.ws.api.annotation.EndpointConfig annotation. An endpoint configuration defined in the webservices subsystem is available to all deployed applications on the server container and can be referenced by name in the annotation. An endpoint configuration defined in an application must be referenced by both deployment descriptor file name and configuration name by the annotation.

Handlers

Each endpoint configuration may be associated with zero or more PRE and POST handler chains. Each handler chain may include JAXWS handlers. For outbound messages the PRE handler chains are executed before any handler that is attached to the endpoint using the standard means, such as with annotation @HandlerChain, and POST handler chains are executed after those objects have executed. For inbound messages the POST handler chains are executed before any handler that is attached to the endpoint using the standard means and the PRE handler chains are executed after those objects have executed.

* 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

Endpoints and clients are assigned configuration through different means. Users can explicitly require a given configuration or rely on container defaults. The assignment process can be split up as follows:

  • Explicit assignment through annotations (for endpoints) or API programmatic usage (for clients)
  • Automatic assignment of configurations from default descriptors
  • Automatic assignment of configurations from container

Explicit configuration assignment

The explicit configuration assignment is meant for developer that know in advance their endpoint or client has to be setup according to a specified configuration. The configuration is either coming from a descriptor that is included in the application deployment, or is included in the application server webservices subsystem management model.

Configuration Deployment Descriptor

Java EE archives that can contain JAX-WS client and endpoint implementations can also contain predefined client and endpoint configuration declarations. All endpoint/client configuration definitions for a given archive must be provided in a single deployment descriptor file, which must be an implementation of schema jbossws-jaxws-config. Many endpoint/client configurations can be defined in the deployment descriptor file. Each configuration must have a name that is unique within the server on which the application is deployed. The configuration name can't be referred to by endpoint/client implementations outside the application. Here is an example of a descriptor, containing two endpoint configurations:

Similarly, client configurations can be specified in descriptors (still implementing the schema mentioned above):

Application server configurations

WildFly 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 WildFly documentation for details on managing the webservices subsystem such as adding, removing and modifying 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. The defaults are used unless different configurations are set as described on this page. This enables administrators to tune the default handler chains for client and endpoint configurations. The names of the default client and endpoint configurations, used in the webservices subsystem are Standard-Client-Config and Standard-Endpoint-Config respectively.

Handlers classloading

When setting a server-wide handler, please note the handler class needs to be available through each ws deployment classloader. As a consequence proper module dependencies might need to be specified in the deployments that are going to leverage a given predefined configuration. A shortcut is to add a dependency to the module containing the handler class in one of the modules which are already automatically set as dependencies to any deployment, for instance org.jboss.ws.spi.

Examples

JBoss AS 7.2 default configurations
A configuration file for a deployment specific ws-security endpoint setup
JBoss AS 7.2 default configurations modified to default to SOAP messages schema-validation on

EndpointConfig annotation

Once a configuration is available to a given application, the org.jboss.ws.api.annotation.EndpointConfig annotation is used to assign an endpoint configuration to a JAX-WS endpoint implementation. When assigning a configuration that is defined in the webservices subsystem only the configuration name is specified.  When assigning a configuration that is defined in the application, the relative path to the deployment descriptor and the configuration name must be specified.

JAXWS Feature

The most practical way of setting a configuration is using org.jboss.ws.api.configuration.ClientConfigFeature, a JAXWS Feature extension provided by JBossWS:

JBossWS parses the specified configuration file.  The configuration file must be found as a resource by the classloader of the current thread. The jbossws-jaxws-config schema defines the descriptor contents and is included in the jbossws-spi artifact.

Explicit setup through API

Alternatively, JBossWS API comes with facility classes that can be used for assigning configurations when building a client. JAXWS handlers read from client configurations as follows:

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

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.

Automatic configuration from default descriptors

In some cases, the application developer might not be aware of the configuration that will need to be used for its client and endpoint implementation, perhaps because that's a concern of the application deployer. In other cases, explicit usage (compile time dependency) of JBossWS API might not be accepted. To cope with such scenarios, JBossWS allows including default client (jaxws-client-config.xml) and endpoint (jaxws-endpoint-config.xml) descriptor within the application (in its root), which are parsed for getting configurations any time a configuration file name is not specified.

If the configuration name is also not specified, JBossWS automatically looks for a configuration named the same as

  • the endpoint implementation class (full qualified name), in case of JAX-WS endpoints;
  • the service endpoint interface (full qualified name), in case of JAX-WS clients.

No automatic configuration name is selected for Dispatch clients.

So, for instance, an endpoint implementation class org.foo.bar.EndpointImpl for which no pre-defined configuration is explicitly set will cause JBossWS to look for a org.foo.bar.EndpointImpl named configuration within a jaxws-endpoint-config.xml descriptor in the root of the application deployment. Similarly, on client side, a client proxy implementing org.foo.bar.Endpoint interface (SEI) will have the setup read from a org.foo.bar.Endpoint named configuration in jaxws-client-config.xml descriptor.

Automatic configuration assignment from container setup

JBossWS fall-backs to getting predefined configurations from the container setup whenever no explicit configuration has been provided and the default descriptors are either not available or do not contain relevant configurations. This gives additional control on the JAX-WS client and endpoint setup to administrators, as the container setup can be managed independently from the deployed applications.

JBossWS hence accesses the webservices subsystem the same as explained above for explicitly named configuration; the default configuration names used for look are

  • the endpoint implementation class (full qualified name), in case of JAX-WS endpoints;
  • the service endpoint interface (full qualified name), in case of JAX-WS clients.

Dispatch clients are not automatically configured. If no configuration is found using names computed as above, the Standard-Client-Config and Standard-Endpoint-Config configurations are used for clients and endpoints respectively

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.