From seam-commits at lists.jboss.org Wed Nov 26 02:56:46 2008 Content-Type: multipart/mixed; boundary="===============1833392249672191989==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r9658 - trunk/doc/Seam_Reference_Guide/en-US. Date: Wed, 26 Nov 2008 02:56:46 -0500 Message-ID: --===============1833392249672191989== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: dan.j.allen Date: 2008-11-26 02:56:46 -0500 (Wed, 26 Nov 2008) New Revision: 9658 Modified: trunk/doc/Seam_Reference_Guide/en-US/Configuration.xml trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml Log: JBSEAM-3034 correctly document the need for ejb-local-ref and why it is needed to injec= t one Seam EJB component into another Modified: trunk/doc/Seam_Reference_Guide/en-US/Configuration.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 --- trunk/doc/Seam_Reference_Guide/en-US/Configuration.xml 2008-11-26 07:55= :35 UTC (rev 9657) +++ trunk/doc/Seam_Reference_Guide/en-US/Configuration.xml 2008-11-26 07:56= :46 UTC (rev 9658) @@ -5,8 +5,8 @@ Configuring Seam and packaging Seam applications Configuration is a very boring topic and an extremely tedious p= astime. Unfortunately, several lines of XML are required to integrate Seam into your JSF implementation and se= rvlet container. There's no need to be too put - off by the following sections; you'll never need to type any of th= is stuff yourself, since you can just copy and - paste from the example applications! + off by the following sections; you'll never need to type any of th= is stuff yourself, since you can just use = + seam-gen to start your application or you can copy and paste from = the example applications! = Basic Seam configuration @@ -70,9 +70,9 @@ = - Using facelets + Using Facelets = - If you want follow our advice and use facelets instead = of JSP, add the following lines to + If you want follow our advice and use Facelets instead = of JSP, add the following lines to faces-config.xml: = @@ -87,12 +87,14 @@ ]]> = - If you are using facelets in JBoss AS, you'll find that fac= elets - logging is broken. Seam provides a bridge to fix this, to u= se it - copy lib/interop/jboss-seam-jul.jar to - $JBOSS_HOME/server/default/deploy/jboss-web.deploy= er/jsf-libs/ - and include the jboss-seam-ui.jar in the = - WEB-INF/lib of your application. + If you are using facelets in JBoss AS, you'll find that Fac= elets logging is broken (the log messages + don't make it to the server log). Seam provides a bridge to= fix this, to use it copy + lib/interop/jboss-seam-jul.jar to + $JBOSS_HOME/server/default/deploy/jboss-web.deploy= er/jsf-libs/ and include the + jboss-seam-ui.jar in the WEB-IN= F/lib of your application. The + Facelets logging catagories are itemized in the Facelets Developer + Documentation. = @@ -398,10 +400,16 @@ Integrating Seam with your EJB container = - We need to apply the SeamInterceptor= to our Seam components. The simplest way to - do this across an entire application is to add the followi= ng interceptor configuration in - ejb-jar.xml: + In a Seam application, EJB components have a certain du= ality, as they are managed by both the EJB + container and Seam. Actually, it's more that Seam resolves= EJB component references, manages the + lifetime of stateful session bean components, and also par= ticipates in each method call via + interceptors. Let's start with the configuration of the Se= am interceptor chain. = + We need to apply the SeamInterceptor= to our Seam EJB components. This interceptor + delegates to a set of built-in server-side interceptors th= at handle such concerns as bijection, + conversation demarcation, and business process signals. Th= e simplest way to do this across an entire + application is to add the following interceptor configurat= ion in ejb-jar.xml: + org.jboss.seam.ejb.SeamInterceptor @@ -420,29 +428,157 @@ @JndiName annotation on every sessi= on bean Seam component. However, this is quite tedious. A better approach is to specify a pattern that Se= am can use to calculate the JNDI name from the EJB name. Unfortunately, there is no standard mapping to g= lobal JNDI defined in the EJB3 specification, - so this mapping is vendor-specific. We usually specify thi= s option in components.xml. + so this mapping is vendor-specific (and may depend on your= own naming conventions as well). We usually + specify this option in components.xml. = = For JBoss AS, the following pattern is correct: = - ]]> + ]]> = - Where myEarName is the name of the E= AR in which the bean is deployed. + In this case, earName is the name of= the EAR in which the bean is deployed, Seam + replaces #{ejbName} with the name of th= e EJB, and the final segment represents the + type of interface (local or remote). = - Outside the context of an EAR (when using the JBoss Emb= eddable EJB3 container), the following pattern - is the one to use: + Outside the context of an EAR (when using the JBoss Emb= eddable EJB3 container), the first segment is + dropped since there is no EAR, leaving us with the followi= ng pattern: = ]]> = - You'll have to experiment to find the right setting for= other application servers. Note that some - servers (such as GlassFish) require you to specify JNDI na= mes for all EJB components explicitly (and - tediously). In this case, you can pick your own pattern ;-= ) - = + How these JNDI names are resolved and somehow locate an= EJB component might appear a bit like black + magic at this point, so let's dig into the details. First,= let's talk about how the EJB components get + into JNDI. + + The folks at JBoss don't care much for XML, if you can'= t tell. So when they designed JBoss AS, they + decided that EJB components would get assigned a global JN= DI name automatically, using the pattern + just described (i.e., EAR name/EJB name/interface type). T= he EJB name is the first non-empty value + from the following list: + + + The value of the <ejb-name> element in ejb-jar.xml + + + The value of the name attribu= te in the @Stateless or @Stateful annotation + + + The simple name of the bean class + + + + Let's look at an example. Assume that you have the foll= owing EJB bean and interface defined. + + + + Assuming your EJB bean class is deployed in an EAR name= d myapp, the global JNDI name = + myapp/AuthenticatorBean/local will be assigned to it. As y= ou learned, you can reference this EJB + component as a Seam component with the name authe= nticator and Seam will take care of + finding it in JNDI according to the JNDI pattern (or @JndiName annotation). + + So what about the rest of the application servers? Well= , according to the Java EE spec, which most + vendors try to adhere to religiously, you have to declare = an EJB reference for your EJB in order for it + to be assigned a JNDI name. That requires some XML. It als= o means that it is up to you to establish a + JNDI naming convention so that you can leverage the Seam J= NDI pattern. You might find the JBoss + convention a good one to follow. + + There are two places you have to define the EJB referen= ce. If you are going to be looking up the + Seam EJB component through JSF (in a JSF view or as a JSF = action listener) or a Seam JavaBean component, + then you must declare the EJB reference in web.xml. Here i= s the EJB reference for the example component + just shown: + + + myapp/AuthenticatorBean/local + Session + org.example.vehicles.action.Authenticator + +]]> + + This reference will cover most uses of the component in= a Seam application. However, if you want to + be able to inject a Seam EJB component into another Seam E= JB component using @In, you + need to define this EJB reference in another location. Thi= s time, it must be defined in ejb-jar.xml, and + it's a bit tricker. + + Within the context of an EJB method call, you have to d= eal with a somewhat sheltered JNDI context. + When Seam attempts to find another Seam EJB component to s= atisfy an injection point defined using + @In, it isn't going to be successful lo= oking up the component in JNDI. You cannot + simply resolve JNDI names as you please. You have to defin= e those references explicitly. Unlike with the + web context, however, you cannot declare EJB references gl= obally for all EJB components. Instead, you + have to specify the JNDI resources for a given EJB compone= nt one-by-one. + + Let's assume that we have an EJB named RegisterAction (= the name is resolved using the three steps + mentioned previously). That EJB has the following Seam inj= ection: + + + + In order for this injection to work, the link must be e= stablished in the ejb-jar.xml file as follows: + + + + + RegisterAction + + myapp/AuthenticatorAction/local + Session + com.example.myapp.Authenticator + + + + + ... + = + +]]> + + Notice that the contents of the <ejb-local-= ref> are identical to what we + defined in web.xml. What we are doing is bringing the refe= rence into the EJB context where it can be + used by the RegisterAction bean. You will need to add one = of these references for any injection of a + Seam EJB compoenent into another Seam EJB component using = @In. (You can see an + example of this setup in the jee5/booking example). + + But what about @EJB? It's true that = you can inject one EJB into another using + @EJB. However, by doing so, you are inj= ecting the actual EJB reference rather than the + Seam EJB component instance. In this case, some Seam featu= res will work, while others won't. That's + because Seam's interceptor is invoked on any method call t= o an EJB component. But that only invokes + Seam's server-side interceptor chain. What you lose is Sea= m's state management and Seam's client-side + interceptor chain. Client-side interceptors handle concern= s such as security and concurrency. Also, when + injecting a SFSB, there is no guarantee that you will get = the SFSB bound to the active session or + conversation, whatever the case may be. Thus, you definite= ly want to inject the Seam EJB component using + @In. + + That covers how JNDI names are defined and used. The le= sson is that with some application servers, + such as GlassFish, you are going to have to specify JNDI n= ames for all EJB components explicitly, and + sometimes twice! And even if you are following the same na= ming convention as JBoss AS, the JNDI pattern + in Seam may need to be altered. For instance, the global J= NDI names are automatically prefixed with + java:comp/env on GlassFish, so you need to define the JNDI= pattern as follows: + + ]]> + - In an EJB3 environment, we recommend the use of a special = built-in component for transaction management, - that is fully aware of container transactions, and can cor= rectly process transaction success events - registered with the Events component. I= f you don't add this line to your = - components.xml file, Seam won't know wh= en container-managed transactions end: - + Finally, let's talk about transactions. In an EJB3 environ= ment, we recommend the use of a special + built-in component for transaction management, that is ful= ly aware of container transactions, and can + correctly process transaction success events registered wi= th the Events component. If + you don't add this line to your components.xml file, Seam won't know when + container-managed transactions end: = ]]> = Modified: trunk/doc/Seam_Reference_Guide/en-US/Glassfish.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 --- trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml 2008-11-26 07:55:35 = UTC (rev 9657) +++ trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml 2008-11-26 07:56:46 = UTC (rev 9658) @@ -527,25 +527,45 @@ - As with the jee5/booking exampl= e we = - need to add EJB references to the web.xml. These = - references require the empty = - local-home to flag them for Gla= ssFish - to perform the proper binding. + As with the jee5/booking exampl= e, we + need to add EJB references to web.xml. Technically= , the + reference type is not required, but we add it here= for + good measure. Note that these references require t= he + presence of an empty local-home + element to retain compatibility with a JBoss AS 4.x + deployment. = = seamgen_example/AuthenticatorAction = = Session = - + org.jboss.seam.tutorial.glassfish.action.Authenticator = = seamgen_example/EjbSynchronizations = Session - + org.jboss.seam.transaction.LocalEjbSynchronizations ]]> + + Keep in mind that if you are deploying to JBoss AS= 4.x, + and have defined the EJB references shown above in= your + web.xml, you will need to also define local JNDI n= ames + for each of them in jboss-web.xml, as shown below. + This step is not required when deploying to GlassF= ish, + but it's mentioned here in case you are also deplo= ying the + application to JBoss AS 4.x (not required for JBos= s AS 5). + + = = + seamgen_example/AuthenticatorAction = = + AuthenticatorAction = + + = + + seamgen_example/EjbSynchronizations = + EjbSynchronizations + ]]> --===============1833392249672191989==--