Skip to end of metadata
Go to start of metadata

Overview

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

Endpoint configurations can be defined in the webservice subsystem and in a deployment descriptor file within the application.   There can be many endpoint configuration definitions in the webservice subsystem and in an application.  Each endpoint 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 used 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 system and can be referenced by name in the annotation. An endpoint configuration defined in an application must be referenced by deployment descriptor file name and the configuration name in 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

Endpoint configuration assignment

Annotation, org.jboss.ws.api.annotation.EndpointConfig 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.

Endpoint Configuration Deployment Descriptor

Java EE archives that can contain JAX-WS endpoint implementations can also contain predefined endpoint configurations.  All endpoint configuration definitions for a given archive must be provided in a single deployment descriptor file. The file must reside in directory WEB-INF for a web application and directory META-INF for a client and EJB application.  The file name must end with extension .xml and be an implementation of schema jbossws-jaxws-config   Common practice is to use the file name jaxws-endpoint-config.xml but this is not required.

Many endpoint configurations can be defined within 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 is not referencable by endpoint implementations outside the application.

Client configuration assignment

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

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.

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 webservices subsystem 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 WildFly 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
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
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.