[[Predefined_client_and_endpoint_configurations]]
= Predefined client and endpoint configurations

[abstract]

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]]
== 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

[[endpoint-configuration-assignment]]
=== Endpoint 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.

[[endpoint-configuration-deployment-descriptor]]
=== Endpoint Configuration Deployment Descriptor

Jakarta 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
http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1.0.Final/src/main/resources/schema/jbossws-jaxws-config_4_0.xsd[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:

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>
<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>org.jboss.test.ws.jaxws.jbws3282.Endpoint4Impl</config-name>
<pre-handler-chains>
<javaee:handler-chain>
<javaee:handler>
<javaee:handler-name>Log Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.LogHandler</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</pre-handler-chains>
<post-handler-chains>
<javaee:handler-chain>
<javaee:handler>
<javaee:handler-name>Routing Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.RoutingHandler</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</post-handler-chains>
</endpoint-config>
<endpoint-config>
<config-name>EP6-config</config-name>
<post-handler-chains>
<javaee:handler-chain>
<javaee:handler>
<javaee:handler-name>Authorization Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.test.ws.jaxws.jbws3282.AuthorizationHandler</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</post-handler-chains>
</endpoint-config>
</jaxws-config>
----

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

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8"?>
<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">
<client-config>
<config-name>Custom Client Config</config-name>
<pre-handler-chains>
<javaee:handler-chain>
<javaee:handler>
<javaee:handler-name>Routing Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class>
</javaee:handler>
<javaee:handler>
<javaee:handler-name>Custom Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.CustomHandler</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</pre-handler-chains>
</client-config>
<client-config>
<config-name>Another Client Config</config-name>
<post-handler-chains>
<javaee:handler-chain>
<javaee:handler>
<javaee:handler-name>Routing Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.test.ws.jaxws.clientConfig.RoutingHandler</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</post-handler-chains>
</client-config>
</jaxws-config>
----

[[application-server-configurations]]
==== 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
https://docs.jboss.org/author/display/WFLY9/Web+services+configuration[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
https://github.com/jbossas/jboss-as/blob/7.2.0.Final/build/src/main/resources/docs/schema/jboss-as-webservices_1_2.xsd[schema]
included in the application server.

[[standard-configurations]]
===== 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]]
===== 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-predefined-endpoint]]
===== Examples

.JBoss AS 7.2 default configurations

[source,xml,options="nowrap"]
----
<subsystem xmlns="urn:jboss:domain:webservices:2.0">
<!-- ... -->
<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

[source,xml,options="nowrap"]
----
<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

[source,xml,options="nowrap"]
----
<subsystem xmlns="urn:jboss:domain:webservices:2.0">
<!-- ... -->
<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>
----

[[endpointconfig-annotation]]
==== 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.

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

[[jaxws-feature]]
==== 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:

[source,java,options="nowrap"]
----
import org.jboss.ws.api.configuration.ClientConfigFeature;
 
...
 
Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"));
port.echo("Kermit");
 
... or ....
 
port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"), true); //setup properties too from the configuration
port.echo("Kermit");
... or ...
 
port = service.getPort(Endpoint.class, new ClientConfigFeature(null, testConfigName)); //reads from current container configurations if available
port.echo("Kermit");
----

JBossWS parses the specified configuration file. The configuration file
must be found as a resource by the classloader of the current thread.
The
http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1.0.Beta1/src/main/resources/schema/jbossws-jaxws-config_4_0.xsd[jbossws-jaxws-config
schema] defines the descriptor contents and is included in the
_jbossws-spi_ artifact.

[[explicit-setup-through-api]]
==== 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:

[source,java,options="nowrap"]
----
import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;
 
...
 
Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);
BindingProvider bp = (BindingProvider)port;
ClientConfigUtil.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config 1");
port.echo("Kermit");
 
...
 
ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config 2");
port.echo("Kermit");
 
...
 
configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config 3");
port.echo("Kermit");
 
 
...
 
configurer.setConfigHandlers(bp, null, "Container Custom Client Config"); //reads from current container configurations if available
port.echo("Kermit");
----

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

[source,java,options="nowrap"]
----
import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;
 
...
 
Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);
 
ClientConfigUtil.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config 1");
port.echo("Kermit");
 
...
 
ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config 2");
port.echo("Kermit");
 
...
 
configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config 3");
port.echo("Kermit");
 
 
...
 
configurer.setConfigProperties(port, null, "Container Custom Client Config"); //reads from current container configurations if available
port.echo("Kermit");

...

configurer.setConfigProperties(port, null, null); //reads from current Elytron client configuration if available
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
http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1.0.Beta1/src/main/resources/schema/jbossws-jaxws-config_4_0.xsd[jbossws-jaxws-config
schema] defines the descriptor contents and is included in the
_jbossws-spi_ artifact.

If WildFly Elytron client configuration is present, the client will automatically use SSL context and credentials (for HTTP Basic authentication or Username Token Profile) from this configuration if these were not already configured.

[[automatic-configuration-from-default-descriptors]]
=== 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]]
=== 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
