From jbossws-commits at lists.jboss.org Fri Nov 8 06:13:20 2013 Content-Type: multipart/mixed; boundary="===============8706339485571983684==" MIME-Version: 1.0 From: jbossws-commits at lists.jboss.org To: jbossws-commits at lists.jboss.org Subject: [jbossws-commits] JBossWS SVN: r18075 - stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc. Date: Fri, 08 Nov 2013 06:13:20 -0500 Message-ID: <201311081113.rA8BDK8O028775@svn01.web.mwc.hst.phx2.redhat.com> --===============8706339485571983684== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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/Aut= hor_Group.xml stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Rev= ision_History.xml stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/cha= pter-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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Au= thor_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/Au= thor_Group.xml 2013-11-08 11:13:20 UTC (rev 18075) @@ -15,4 +15,8 @@ Jim Ma + + Rebecca + Searls + Modified: stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/= doc/Revision_History.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/Re= vision_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/Re= vision_History.xml 2013-11-08 11:13:20 UTC (rev 18075) @@ -102,6 +102,20 @@ + + 4.2.3 + Fri Nov 8 2013 + + Alessio + Soldano + alessio.soldano(a)jboss.com + + + + JBossWS-CXF 4.2.3 documentation + + + Modified: stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/= doc/chapter-5-Advanced_User_Guide.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- stack/cxf/branches/jbossws-cxf-4.2.3.Final/modules/dist/src/main/doc/ch= apter-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/ch= apter-5-Advanced_User_Guide.xml 2013-11-08 11:13:20 UTC (rev 18075) @@ -365,15 +365,16 @@
= Overview + JBossWS enables extra setup configuration data to be predefi= ned and associated with an endpoint. Endpoint configurations can include J= AX-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. - JBossWS comes with a concept of - predefined configurations - , which are kind of basic templates that can be used for both JA= X-WS client and JAX-WS endpoint setup. Configurations can include JAX-WS ha= ndlers as well as basic key/value properties declarations. + Endpoint configurations can be defined in the webservice subsyst= em 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 u= nique within the server. Configurations defined in an application are loc= al to the application. Endpoint implementations declare the use of a speci= fic configuration through the use of the + org.jboss.ws.api.annotation.EndpointConfig + annotation. An endpoint configuration defined in the webservice= s subsystem is available to all deployed applications on the server contai= ner and can be referenced by name in the annotation. An endpoint configura= tion defined in an application must be referenced by deployment descriptor= file name and the configuration name in the annotation.
= Handlers - For each endpoint configuration, both PRE and POST handler= chains can be specified. Each handler chain may include JAXWS handlers. Fo= r outbound messages, PRE handler chain handlers are meant to be executed be= fore 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. + Each endpoint configuration may be associated with zero or= more PRE and POST handler chains. Each handler chain may include JAXWS h= andlers. For outbound messages the PRE handler chains are executed before= any handler that is attached to the endpoint using the standard means, s= uch as with annotation @HandlerChain, and POST handler chains are execute= d after those objects have executed. For inbound messages the POST hand= ler chains are executed before any handler that is attached to the endpoi= nt 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 @@ -396,9 +397,9 @@ = Endpoint configuration assignment - JAX-WS endpoints can be assigned to a given configuration by a= nnotating them with the + Annotation org.jboss.ws.api.annotation.EndpointConfig - annotation: + is used to assign an endpoint configuration to a JAX-WS endpo= int implementation. When assigning a configuration that is defined in the = webservices subsystem only the configuration name is specified. When assi= gning a configuration that is defined in the application, the relative pat= h to the deployment descriptor and the configuration name must be specifie= d. @EndpointConfig(configFile =3D "WEB-INF/jaxws-= endpoint-config.xml", configName =3D "Custom WS-Security Endpoint") @@ -410,30 +411,16 @@ } } +
+
+ = + Endpoint Configuration Deployment Descriptor - The - configFile - attribute is used to specify which config file, if any, is to = be used to load the configuration; if - configFile - is not set, the application server configurations are used. + Java EE archives that can contain JAX-WS endpoint implementati= ons can also contain predefined endpoint configurations. All endpoint confi= guration definitions for a given archive must be provided in a single deplo= yment 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 fi= le 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-confi= g.xml but this is not required. - - The - configName - attributed is used to specify the name of the configuration to= be used. - - - Alternatively, configurations can be assigned to endpoints thr= ough the - jboss-webservices.xml deployment= descriptor - . - - - The configuration file, if any, needs to be included in the en= dpoint deployment; the - jbossws-jaxws-config schema - defines its contents and is included in the - jbossws-spi - artifact. - + Many endpoint configurations can be defined within the de= ployment descriptor file. Each configuration must have a name that is uniq= ue within the server on which the application is deployed. The configurati= on name is not referencable by endpoint implementations outside the applic= ation.
= @@ -469,7 +456,7 @@ - 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 config= uration 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 @@ -479,7 +466,7 @@
= Explicit setup - 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: + Alternatively, JBossWS API comes with facility classes t= hat can be used for assigning configurations when building a client. JAXWS= handlers read from client configurations as follows: import org.jboss.ws.api.configuration.Client= ConfigUtil; import org.jboss.ws.api.configuration.ClientConfigurer; @@ -1041,7 +1028,7 @@ BusFactory to be used leverages the Service API, basically looking for o= ptional configurations in META-INF/services/... - location using the current thread context classloader. JBossW= S-CXF integration comes with his own implementation of + location using the current thread context classloader. JBossW= S-CXF integration comes with its own implementation of BusFactory , org.jboss.wsf.stack.cxf.client.configuration.JBossWSBusF= actory @@ -1109,9 +1096,9 @@ getThreadDefaultBus() and getThreadDefaultBus(true) - first fallback to retrieving the configured global default bus= before actually trying creating a new instance (and the created new insta= nce 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 insta= nce is set as global default bus if that was not set there yet). - The drawback of this mechanism (which is basically fine i= n JSE environment) is that when running in a JBoss AS container you need t= o be careful in order not to (mis)use a bus over multiple applications (as= suming the Apache CXF classes are loaded by the same classloader, which is= currently the case with AS6 and 7). + The drawback of this mechanism (which is basically fine i= n JSE environment) is that when running in a JBoss AS container you need t= o be careful in order not to (mis)use a bus over multiple applications (as= suming the Apache CXF classes are loaded by the same classloader, which is= currently the case with JBoss AS6, JBoss AS7 and WildFly). Here is a list of general suggestions to avoid problems wh= en running in-container: @@ -1138,8 +1125,9 @@ 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 a= ssociation. + Finally, remember that each time you explictly create a n= ew Bus instance (factory.createBus()) that is set as thread default bus an= d global default bus if those are not set yet. - Finally, remember that each time you explictly create a new B= us instance (factory.createBus()) that is set as thread default bus and gl= obal default bus if those are not set yet. The JAXWS + The JAXWS Provider implementation also creates Bus @@ -1147,9 +1135,156 @@ Provider makes sure the default bus is never internally used and inste= ad a new Bus - is created if required. + is created if required (more details on this in the next para= graph).
+
+ = + Bus selection strategies for JAXWS clients + + JAXWS clients require an Apache CXF Bus to be available; the c= lient 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 fo= r in-container clients; for this reason, JBossWS users can choose the prefe= rred Bus selection strategy. The strategy is enforced in the + javax.xml.ws.spi.Provider + implementation from the JBossWS integration, being that called= whenever a JAXWS + Service + (client) is requested. + +
+ = + Thread bus strategy (THREAD_BUS) + Each time the vanilla JAXWS api is used to create a Bus,= the JBossWS-CXF integration will automatically make sure a Bus is currentl= y associated to the current thread in the BusFactory. If that's not the cas= e, a new Bus is created and linked to the current thread (to prevent the us= er from relying on the default Bus). The Apache CXF engine will then create= the client using the current thread Bus. + This is the default strategy, and the most straightforwa= rd one in Java SE environments; it lets users automatically reuse a previou= sly 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> + The drawback of the strategy is that the link between th= e Bus instance and the thread needs to be eventually cleaned up (when not n= eeded anymore). This is really evident in a Java EE environment (hence when= running in-container), as threads from pools (e.g. serving web requests) a= re re-used. + + When relying on this strategy, the safest approach to be sur= e of cleaning up the link is to surround the JAXWS client with a + try/finally + block as below: + + + try { + Service service =3D Service.create(wsdlURL, serviceQName); + MyEndpoint port =3D service.getPort(MyEndpoint.class); + //... +} finally { + BusFactory.setThreadDefaultBus(null); + // OR (if you don't need the bus and the client anymore) + =C2=A0Bus bus =3D BusFactory.getThreadDefaultBus(false); + bus.shutdown(true); +} + +
+
+ = + New bus strategy (NEW_BUS) + 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 former= ly cached information (e.g. cached WSDL / schemas) which might have changed= after the previous client creation. The main drawback is of course worse p= erformance as the Bus creation takes time. + If there's a bus already associated to the current threa= d before the JAXWS client creation, that is automatically restored when ret= urning control to the user; in other words, the newly created bus will be u= sed only for the created JAXWS client but won't stay associated to the curr= ent thread at the end of the process. Similarly, if the thread was not asso= ciated to any bus before the client creation, no bus will be associated to = the thread at the end of the client creation. +
+
+ = + Thread context classloader bus strategy (TCCL_BUS)</tit= le> + <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 runn= ing when the same TCCL is set. This is particularly interesting as each web= application deployment usually has its own context classloader, so this st= rategy 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 threa= d before the JAXWS client creation, that is automatically restored when re= turning 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 p= rocess. If the thread was not associated to any bus before the client crea= tion, 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 t= o the thread at the end of the client creation.</para> + </section> + <section id=3D"sid-3866786_ApacheCXFintegration-Strategyconfigur= ation"> + = + <title>Strategy configuration + + Users can request a given Bus selection strategy to be used = for the client being built by specifying one of the following JBossWS featu= res (which extend + javax + . + xml + . + ws + . + WebServiceFeature + ): + + + + + + + Feature + + + Strategy + + + + + + + + org.jboss.wsf.stack.cxf.client.UseThreadBusF= eature + + + + THREAD_BUS + + + + + + org + . + jboss + . + wsf + . + stack + . + cxf + . + client. + UseNewBusFeature + + + + NEW_BUS + + + + + + org + . + jboss + . + wsf + . + stack + . + cxf + . + client. + UseTCCLBusFeature + + + + TCCL_BUS + + + + + + The feature is specified as follows: + + Service service =3D Service.create(wsdlURL, = serviceQName, new UseThreadBusFeature()); + + + If no feature is explicitly specified, the system default st= rategy is used, which can be modified through the + org.jboss.ws.cxf.jaxws-client.bus.strategy + system property when starting the JVM. The valid values for = the property are + THREAD_BUS + , + NEW_BUS + and + TCCL_BUS + . The default is + THREAD_BUS + . + +
+
= --===============8706339485571983684==--