[[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 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 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] ---- org.jboss.test.ws.jaxws.jbws3282.Endpoint4Impl Log Handler org.jboss.test.ws.jaxws.jbws3282.LogHandler Routing Handler org.jboss.test.ws.jaxws.jbws3282.RoutingHandler EP6-config Authorization Handler org.jboss.test.ws.jaxws.jbws3282.AuthorizationHandler ---- Similarly, client configurations can be specified in descriptors (still implementing the schema mentioned above): [source,xml] ---- Custom Client Config Routing Handler org.jboss.test.ws.jaxws.clientConfig.RoutingHandler Custom Handler org.jboss.test.ws.jaxws.clientConfig.CustomHandler Another Client Config Routing Handler org.jboss.test.ws.jaxws.clientConfig.RoutingHandler ---- [[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]] ===== Examples .JBoss AS 7.2 default configurations [source,xml] ---- ---- .A configuration file for a deployment specific ws-security endpoint setup [source,xml] ---- Custom WS-Security Endpoint ws-security.signature.properties bob.properties ws-security.encryption.properties bob.properties ws-security.signature.username bob ws-security.encryption.username alice ws-security.callback-handler org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback ---- .JBoss AS 7.2 default configurations modified to default to SOAP messages schema-validation on [source,xml] ---- ---- [[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] ---- @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] ---- 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] ---- 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] ---- 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"); ---- 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. [[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