5:13 a.m.
Author: asoldano
Date: 2013-11-08 06:13:20 -0500 (Fri, 08 Nov 2013)
New Revision: 18075
Modified:
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Author_Group.xml
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Revision_History.xml
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml
Log:
Updating doc
Modified:
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Author_Group.xml
===================================================================
---
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Author_Group.xml 2013-11-08
10:06:08 UTC (rev 18074)
+++
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Author_Group.xml 2013-11-08
11:13:20 UTC (rev 18075)
@@ -15,4 +15,8 @@
<firstname>Jim</firstname>
<surname>Ma</surname>
</author>
+ <author>
+ <firstname>Rebecca</firstname>
+ <surname>Searls</surname>
+ </author>
</authorgroup>
Modified:
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Revision_History.xml
===================================================================
---
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Revision_History.xml 2013-11-08
10:06:08 UTC (rev 18074)
+++
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Revision_History.xml 2013-11-08
11:13:20 UTC (rev 18075)
@@ -102,6 +102,20 @@
</simplelist>
</revdescription>
</revision>
+ <revision>
+ <revnumber>4.2.3</revnumber>
+ <date>Fri Nov 8 2013</date>
+ <author>
+ <firstname>Alessio</firstname>
+ <surname>Soldano</surname>
+ <email>alessio.soldano(a)jboss.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>JBossWS-CXF 4.2.3 documentation</member>
+ </simplelist>
+ </revdescription>
+ </revision>
</revhistory>
</simpara>
</appendix>
Modified:
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml
===================================================================
---
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml 2013-11-08
10:06:08 UTC (rev 18074)
+++
stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml 2013-11-08
11:13:20 UTC (rev 18075)
@@ -365,15 +365,16 @@
<section
id="sid-41713670_Predefinedclientandendpointconfigurations-Overview">
<title>Overview</title>
+ <para>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.</para>
<para>
- JBossWS comes with a concept of
- <emphasis role="italics">predefined
configurations</emphasis>
- , 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.
+ 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 use of the
+ <code>org.jboss.ws.api.annotation.EndpointConfig</code>
+ 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 deployment descriptor file name and the configuration name in the
annotation.
</para>
<section
id="sid-41713670_Predefinedclientandendpointconfigurations-Handlers">
<title>Handlers</title>
- <para>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.</para>
+ <para>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.</para>
<informalexample>
<programlisting>* Server inbound messages
Client --> ... --> POST HANDLER --> ENDPOINT HANDLERS --> PRE
HANDLERS --> Endpoint
@@ -396,9 +397,9 @@
<title>Endpoint configuration assignment</title>
<para>
- JAX-WS endpoints can be assigned to a given configuration by annotating them
with the
+ Annotation
<code>org.jboss.ws.api.annotation.EndpointConfig</code>
- 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.
</para>
<informalexample>
<programlisting>@EndpointConfig(configFile =
"WEB-INF/jaxws-endpoint-config.xml", configName = "Custom WS-Security
Endpoint")
@@ -410,30 +411,16 @@
}
}</programlisting>
</informalexample>
+ </section>
+ <section
id="sid-41713670_Predefinedclientandendpointconfigurations-EndpointConfigurationDeploymentDescriptor">
+
+ <title>Endpoint Configuration Deployment Descriptor</title>
<para>
- The
- <code>configFile</code>
- attribute is used to specify which config file, if any, is to be used to load
the configuration; if
- <code>configFile</code>
- is not set, the application server configurations are used.
+ 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
+ <ulink
url="http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1...
+ . Common practice is to use the file name jaxws-endpoint-config.xml but this
is not required.
</para>
- <para>
- The
- <code>configName</code>
- attributed is used to specify the name of the configuration to be used.
- </para>
- <para>
- Alternatively, configurations can be assigned to endpoints through the
- <link linkend="sid-3866738">jboss-webservices.xml deployment
descriptor</link>
- .
- </para>
- <para>
- The configuration file, if any, needs to be included in the endpoint
deployment; the
- <ulink
url="http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1...
schema</ulink>
- defines its contents and is included in the
- <emphasis role="italics">jbossws-spi</emphasis>
- artifact.
- </para>
+ <para>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.</para>
</section>
<section
id="sid-41713670_Predefinedclientandendpointconfigurations-Clientconfigurationassignment">
@@ -469,7 +456,7 @@
</programlisting>
</informalexample>
<para>
- JBossWS internally parses the specified configuration file, if any, after
having resolved it as a resources using the current thread context classloader. The
+ JBossWS parses the specified configuration file. The configuration file
must be found as a resource by the classloader of the current thread. The
<ulink
url="http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1...
schema</ulink>
defines the descriptor contents and is included in the
<emphasis role="italics">jbossws-spi</emphasis>
@@ -479,7 +466,7 @@
<section
id="sid-41713670_Predefinedclientandendpointconfigurations-Explicitsetup">
<title>Explicit setup</title>
- <para>Alternatively, JBossWS API facility classes can be used for
assigning configurations when building up a client; JAXWS handlers can be read from client
configurations as follows:</para>
+ <para>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:</para>
<informalexample>
<programlisting>import
org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;
@@ -1041,7 +1028,7 @@
<code>BusFactory</code>
to be used leverages the Service API, basically looking for optional
configurations in
<emphasis
role="italics">META-INF/services/...</emphasis>
- location using the current thread context classloader. JBossWS-CXF
integration comes with his own implementation of
+ location using the current thread context classloader. JBossWS-CXF
integration comes with its own implementation of
<code>BusFactory</code>
,
<code>org.jboss.wsf.stack.cxf.client.configuration.JBossWSBusFactory</code>
@@ -1109,9 +1096,9 @@
<emphasis
role="italics">getThreadDefaultBus()</emphasis>
and
<emphasis
role="italics">getThreadDefaultBus(true)</emphasis>
- first fallback to retrieving the configured global default bus before
actually trying creating a new instance (and the created new instance is set as global
default bus if that was not there set yet).
+ first fallback to retrieving the configured global default bus before
actually trying creating a new instance (and the created new instance is set as global
default bus if that was not set there yet).
</para>
- <para>The drawback of this mechanism (which is basically fine in JSE
environment) is that when running in a JBoss AS container you need to be careful in
order not to (mis)use a bus over multiple applications (assuming the Apache CXF classes
are loaded by the same classloader, which is currently the case with AS6 and
7).</para>
+ <para>The drawback of this mechanism (which is basically fine in JSE
environment) is that when running in a JBoss AS container you need to be careful in
order not to (mis)use a bus over multiple applications (assuming the Apache CXF classes
are loaded by the same classloader, which is currently the case with JBoss AS6, JBoss AS7
and WildFly).</para>
<para>Here is a list of general suggestions to avoid problems when
running in-container:</para>
<itemizedlist>
<listitem>
@@ -1138,8 +1125,9 @@
<para>keep in mind thread pooling whenever you customize a thread
default bus instance (for instance adding bus scope interceptors, ...), as that thread
and bus might be later reused; so either shutdown the bus when you're done or
explicitly remove it from the BusFactory thread association.</para>
</listitem>
</itemizedlist>
+ <para>Finally, remember that each time you explictly create a new Bus
instance (factory.createBus()) that is set as thread default bus and global default bus
if those are not set yet.</para>
<para>
- Finally, remember that each time you explictly create a new Bus instance
(factory.createBus()) that is set as thread default bus and global default bus if those
are not set yet. The JAXWS
+ The JAXWS
<code>Provider</code>
implementation also creates
<code>Bus</code>
@@ -1147,9 +1135,156 @@
<code>Provider</code>
makes sure the default bus is never internally used and instead a new
<code>Bus</code>
- is created if required.
+ is created if required (more details on this in the next paragraph).
</para>
</section>
+ <section
id="sid-3866786_ApacheCXFintegration-BusselectionstrategiesforJAXWSclients">
+
+ <title>Bus selection strategies for JAXWS clients</title>
+ <para>
+ JAXWS clients require an Apache CXF Bus to be available; the client is
registered within the Bus and the Bus affects the client behavior (e.g. through the
configured CXF interceptors). The way a bus is internally selected for serving a given
JAXWS client is very important, especially for in-container clients; for this reason,
JBossWS users can choose the preferred Bus selection strategy. The strategy is enforced in
the
+ <code>javax.xml.ws.spi.Provider</code>
+ implementation from the JBossWS integration, being that called whenever a
JAXWS
+ <code>Service</code>
+ (client) is requested.
+ </para>
+ <section
id="sid-3866786_ApacheCXFintegration-Threadbusstrategy%28THREADBUS%29">
+
+ <title>Thread bus strategy (THREAD_BUS)</title>
+ <para>Each time the vanilla JAXWS api is used to create a Bus, the
JBossWS-CXF integration will automatically make sure a Bus is currently associated to the
current thread in the BusFactory. If that's not the case, a new Bus is created and
linked to the current thread (to prevent the user from relying on the default Bus). The
Apache CXF engine will then create the client using the current thread Bus.</para>
+ <para>This is the default strategy, and the most straightforward one in
Java SE environments; it lets users automatically reuse a previously created Bus instance
and allows using customized Bus that can possibly be created and associated to the thread
before building up a JAXWS client.</para>
+ <para>The drawback of the strategy is that the link between the Bus
instance and the thread needs to be eventually cleaned up (when not needed anymore). This
is really evident in a Java EE environment (hence when running in-container), as threads
from pools (e.g. serving web requests) are re-used.</para>
+ <para>
+ When relying on this strategy, the safest approach to be sure of cleaning
up the link is to surround the JAXWS client with a
+ <code>try/finally</code>
+ block as below:
+ </para>
+ <informalexample>
+ <programlisting>try {
+ Service service = Service.create(wsdlURL, serviceQName);
+ MyEndpoint port = service.getPort(MyEndpoint.class);
+ //...
+} finally {
+ BusFactory.setThreadDefaultBus(null);
+ // OR (if you don't need the bus and the client anymore)
+ Bus bus = BusFactory.getThreadDefaultBus(false);
+ bus.shutdown(true);
+}</programlisting>
+ </informalexample>
+ </section>
+ <section
id="sid-3866786_ApacheCXFintegration-Newbusstrategy%28NEWBUS%29">
+
+ <title>New bus strategy (NEW_BUS)</title>
+ <para>Another strategy is to have the JAXWS Provider from the JBossWS
integration create a new Bus each time a JAXWS client is built. The main benefit of this
approach is that a fresh bus won't rely on any formerly cached information (e.g.
cached WSDL / schemas) which might have changed after the previous client creation. The
main drawback is of course worse performance as the Bus creation takes time.</para>
+ <para>If there's a bus already associated to the current thread
before the JAXWS client creation, that is automatically restored when returning control to
the user; in other words, the newly created bus will be used only for the created JAXWS
client but won't stay associated to the current thread at the end of the process.
Similarly, if the thread was not associated to any bus before the client creation, no bus
will be associated to the thread at the end of the client creation.</para>
+ </section>
+ <section
id="sid-3866786_ApacheCXFintegration-Threadcontextclassloaderbusstrategy%28TCCLBUS%29">
+
+ <title>Thread context classloader bus strategy
(TCCL_BUS)</title>
+ <para>The last strategy is to have the bus created for serving the
client be associated to the current thread context classloader (TCCL). That basically
means the same Bus instance is shared by JAXWS clients running when the same TCCL is set.
This is particularly interesting as each web application deployment usually has its own
context classloader, so this strategy is possibly a way to keep the number of created Bus
instances bound to the application number in a JBoss AS container.</para>
+ <para>If there's a bus already associated to the current thread
before the JAXWS client creation, that is automatically restored when returning control
to the user; in other words, the bus corresponding to the current thread context
classloader will be used only for the created JAXWS client but won't stay associated
to the current thread at the end of the process. If the thread was not associated to any
bus before the client creation, a new bus will be created (and later user for any other
client built with this strategy and the same TCCL in place); no bus will be associated to
the thread at the end of the client creation.</para>
+ </section>
+ <section
id="sid-3866786_ApacheCXFintegration-Strategyconfiguration">
+
+ <title>Strategy configuration</title>
+ <para>
+ Users can request a given Bus selection strategy to be used for the client
being built by specifying one of the following JBossWS features (which extend
+ <code>javax</code>
+ <code>.</code>
+ <code>xml</code>
+ <code>.</code>
+ <code>ws</code>
+ <code>.</code>
+ <code>WebServiceFeature</code>
+ ):
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>Feature</para>
+ </entry>
+ <entry>
+ <para>Strategy</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+
<code>org.jboss.wsf.stack.cxf.client.UseThreadBusFeature</code>
+ </para>
+ </entry>
+ <entry>
+ <para>THREAD_BUS</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <code>org</code>
+ <code>.</code>
+ <code>jboss</code>
+ <code>.</code>
+ <code>wsf</code>
+ <code>.</code>
+ <code>stack</code>
+ <code>.</code>
+ <code>cxf</code>
+ <code>.</code>
+ <code>client.</code>
+ <code>UseNewBusFeature</code>
+ </para>
+ </entry>
+ <entry>
+ <para>NEW_BUS</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <code>org</code>
+ <code>.</code>
+ <code>jboss</code>
+ <code>.</code>
+ <code>wsf</code>
+ <code>.</code>
+ <code>stack</code>
+ <code>.</code>
+ <code>cxf</code>
+ <code>.</code>
+ <code>client.</code>
+ <code>UseTCCLBusFeature</code>
+ </para>
+ </entry>
+ <entry>
+ <para>TCCL_BUS</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>The feature is specified as follows:</para>
+ <informalexample>
+ <programlisting>Service service = Service.create(wsdlURL,
serviceQName, new UseThreadBusFeature());</programlisting>
+ </informalexample>
+ <para>
+ If no feature is explicitly specified, the system default strategy is used,
which can be modified through the
+ <code>org.jboss.ws.cxf.jaxws-client.bus.strategy</code>
+ system property when starting the JVM. The valid values for the property
are
+ <code>THREAD_BUS</code>
+ ,
+ <code>NEW_BUS</code>
+ and
+ <code>TCCL_BUS</code>
+ . The default is
+ <code>THREAD_BUS</code>
+ .
+ </para>
+ </section>
+ </section>
</section>
<section
id="sid-3866786_ApacheCXFintegration-ServerSideIntegrationCustomization">