From seam-commits at lists.jboss.org Mon Nov 23 19:33:32 2009 Content-Type: multipart/mixed; boundary="===============4995900109941102503==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r11654 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US. Date: Mon, 23 Nov 2009 19:33:32 -0500 Message-ID: <200911240033.nAO0XWbs009295@svn01.web.mwc.hst.phx2.redhat.com> --===============4995900109941102503== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: laubai Date: 2009-11-23 19:33:31 -0500 (Mon, 23 Nov 2009) New Revision: 11654 Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Cache.xml tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml Log: Removed callout syntax, as it breaks in publican. Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Cache= .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 --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Cache.xml 2= 009-11-24 00:07:11 UTC (rev 11653) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Cache.xml 2= 009-11-24 00:33:31 UTC (rev 11654) @@ -14,7 +14,7 @@ nodes of the cluster. What these silly people are really thinking = of = is a "share nothing except for the database" architecture. Of cour= se, = sharing the database is the primary problem with scaling a multi-u= ser = - application—so the claim that this architecture is highly sc= alable = + application — so the claim that this architecture is highly = scalable = is absurd, and tells you a lot about the kind of applications that= these folks spend most of their time working on. = @@ -66,7 +66,7 @@ persistence context associated with a conversation-scoped = stateful session bean) acts as a cache of data that has been read i= n the current conversation. This cache tends to have a pretty hi= gh - hitrate! Seam optimizes the replication of Seam-managed pe= rsistence = + hit rate! Seam optimizes the replication of Seam-managed p= ersistence = contexts in a clustered environment, and there is no requi= rement for = transactional consistency with the database (optimistic lo= cking is = sufficient) so you don't need to worry too much about the = performance = Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutor= ial.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 --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xm= l 2009-11-24 00:07:11 UTC (rev 11653) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xm= l 2009-11-24 00:33:31 UTC (rev 11654) @@ -99,105 +99,107 @@ validation declaratively, via= annotations. It also needs some extra annotations that define the class as a Seam component.= - - - -(a)Entity <co id=3D"registration-entity-annotation"/> + User.java Example + = + - = - The EJB3 standard @Entity<= /literal> annotation indicates that the - User class is a= n entity bean. +}]]> + + + = = - A Seam component needs a = component name specified by the - @Name - annotation. This name must be unique = within the Seam application. When JSF - asks Seam to resolve a context variabl= e with a name that is the same as a Seam - component name, and the context variab= le is currently undefined (null), Seam will - instantiate that component, and bind t= he new instance to the context variable. In - this case, Seam will instantiate a User the first time JSF - encounters a variable named u= ser. +User.java Explanatory Notes + = - Whenever Seam instantiates a compon= ent, it binds the new instance to a context - variable in the component's = default context. The default - context is specified using the - @Scope - annotation. The User bean is a session scoped component. - + + + + The EJB3 standard @Entity annotation indicates that the User class is an entity= bean. + + + + + A Seam component must have a com= ponent name specified by the @Name annotation. This name must be unique within the= Seam application. When JSF asks Seam to resolve a currently undefined (nul= l) context variable whose name matches that of a Seam component, Seam will = instantiate that component, and bind the new instance to the context variab= le. In this case, Seam will instantiate a User the first= time JSF encounters a variable named user. + + + = + + Whenever Seam instantiates a component, it= binds the new instance to a context variable in the component's default context. The default context is specified using the = @Scope annotation= . The User bean is a session scoped component. + + + + + The EJB standard @Table= annotation indicates that the User class is mapped to t= he users table. + + + + + name, password= , and username are the persistent attributes o= f the entity bean. All of our persistent attributes define accessor methods= . These are needed when this component is used by JSF in the render respons= e and update model values phases. + + + + + An empty constructor is required by both t= he EJB specification and by Seam. + + + + + The @NotNull and @Length annotations are part of the Hibernate Validator framew= ork. Seam integrates Hibernate Validator and lets you use it for data valid= ation (even if you are not using Hibernate for persistence). + + + + + The EJB standard @Id an= notation indicates the primary key attribute of the entity bean. + + + + + = - The EJB standard @Table annotation indicates that the - User class is m= apped to the users table. - - - - name, pass= word and username - are the persistent attributes of the e= ntity bean. All of our persistent attributes - define accessor methods. These are nee= ded when this component is used by JSF in the - render response and update model value= s phases. - - An empty constructor is both requir= ed by both the EJB specification and by Seam. - - - The @NotNull and= @Length annotations are - part of the Hibernate Validator framew= ork. Seam integrates Hibernate Validator and - lets you use it for data validation (e= ven if you are not using Hibernate for - persistence). - - The EJB standard @Id annotation indicates the primary key - attribute of the entity bean. - The most important things to notice in this exa= mple are the @Name and @Scope annotations. These a= nnotations establish that this class is a Seam component. We'll see below that the properties of our User class are bound @@ -221,92 +223,136 @@ = This is the only really interesting code in the exa= mple! - - - - -(a)Stateless + = + = +RegisterAction.java Example + = + = + = + - - = - The EJB standard @Stateles= s annotation marks this class as - a stateless session bean. - - The - @In - annotation marks an attribute of the = bean as injected by Seam. In this case, - the attribute is injected from a conte= xt variable named user (the - instance variable name). - = - The EJB standard @Persiste= nceContext annotation is used to - inject the EJB3 entity manager. - - The Seam @Logger= annotation is used to inject the component's - Log instance. <= /para> - - The action listener method uses the= standard EJB3 - EntityManager API t= o interact with the database, and returns the - JSF outcome. Note that, since this is = a session bean, a transaction is automatically - begun when the register() method is called, and committed when it - completes. - - Notice that Seam lets you use a JSF= EL expression inside EJB-QL. Under the - covers, this results in an ordinary JP= A setParameter() call on - the standard JPA Query object. Nice, huh? - - The Log API lets= us easily display templated log messages. +}]]> + + + + + RegisterAction.java Explanatory Notes</= title> + <para> + <orderedlist> + <listitem> + <para> + The EJB <literal>@Stateless</literal> anno= tation marks this class as a stateless session bean. + </para> + </listitem> + <listitem> + <para> + The <xref linkend=3D"in-annotation" /> <li= teral>@In</literal> annotation marks an attribute of the bean as injected = by Seam. In this case, the attribute is injected from a context variable na= med <literal>user</literal> (the instance variable name). + </para> + </listitem> + <listitem> + <para> + The EJB standard <literal>@PersistenceCont= ext</literal> annotation is used to inject the EJB3 entity manager. + </para> + </listitem> + <listitem> + <para> + The Seam <literal>@Logger</literal> annota= tion is used to inject the component's <literal>Log</literal> instance. + </para> + </listitem> + <listitem> + <para> + The action listener method uses the standa= rd EJB3 <literal>EntityManager</literal> API to interact with the database,= and returns the JSF outcome. Note that, since this is a session bean, a tr= ansaction begins automatically when the <literal>register()</literal> metho= d is called, and is committed when it completes. + </para> + </listitem> + <listitem> + <para> + Notice that Seam lets you use a JSF EL exp= ression inside EJB-QL. This results in an ordinary JPA <literal>setParamete= r()</literal> call on the standard JPA <literal>Query</literal> object. + </para> + </listitem> + <listitem> + <para> + The <literal>Log</literal> API allows easi= ly display templated log messages that can include JSF EL expressions. + </para> + </listitem> + <listitem> + <para> + JSF action listener methods return a strin= g-valued outcome that determines the next page displayed. A null outcome (o= r a void action listener method) redisplays the previous page. In plain JSF= , it is normal to always use a JSF <emphasis>navigation rule</emphasis> to = determine the JSF view ID from the outcome. For complex applications, this = redirection is good practice. However, for very simple examples like this o= ne, Seam lets you use the JSF view ID as the outcome, eliminating the need = for a navigation rule. + </para> + <note> + <para> + When a view ID is used as an outcome, = Seam always performs a browser redirect. </para> + </note> + </listitem> + <listitem> + <para> + Seam provides a number of <emphasis>built-= in components</emphasis> to help solve common problems. The <literal>FacesM= essages</literal> component makes it easy to display templated error or suc= cess messages. (As of Seam 2.1, you can use <literal>StatusMessages</litera= l> instead, to remove the semantic dependency on JSF.) Built-in Seam compon= ents may be obtained by injection, or by calling the <literal>instance()</l= iteral> method on the class of the built-in component. + </para> + </listitem> + </orderedlist> + </para> + </formalpara> + <!-- </example> --> + <para> + Note that we did not explicitly specify a <literal>@Sc= ope</literal> this time. Each Seam component type has a default scope, whic= h will be used if scope is not explicitly specified. For stateless session = beans, the default scope is the stateless context. + </para> + <para> + The session bean action listener performs the business= and persistence logic for our mini-application. In a more complex applicat= ion, a separate service layer might be necessary, but Seam allows you to im= plement your own strategies for application layering. You can make any appl= ication as simple, or as complex, as you want. + </para> + <note> + <para> + This application is more complex than necessary fo= r the sake of clear example code. All of the application code could have be= en eliminated by using Seam's application framework controllers. + </para> + </note> + </section> + = + <section> + <title>The session bean local interface: <literal>Register= .java</literal> + + The session bean requires a local interface. + + Register.java Example + = + + = + + + + + = + = + = + = = - JSF action listener methods return = a string-valued outcome that determines what - page will be displayed next. A null ou= tcome (or a void action listener method) - redisplays the previous page. In plain= JSF, it is normal to always use a JSF - navigation rule to determine the JSF view id from the - outcome. For complex application this = indirection is useful and a good practice. - However, for very simple examples like= this one, Seam lets you use the JSF view id - as the outcome, eliminating the requir= ement for a navigation rule. Note - that when you use a view id as an = outcome, Seam always performs a browser - redirect. - - - Seam provides a number of built-in components to help solve - common problems. The FacesMes= sages component makes it easy to - display templated error or success mes= sages. Built-in Seam components may be - obtained by injection, or by calling a= n instance() method. - - - Note that we did not explicitly specify a @Scope this time. Each Seam component type has a default scope if not explicit= ly specified. For stateless session beans, the default scope is the stateless context. Actually, = all stateless session @@ -775,89 +821,99 @@ We want to cache the list of messages in memory bet= ween server requests, so we will make this a stateful session bean. - - - -(a)Stateful + = +MessageManagerBean.java Example + + = + messageList; + = + @DataModelSelection + @Out(required=3Dfalse) + private Message message; + = + @PersistenceContext(type=3DEXTENDED) + private EntityManager em; + = + @Factory("messageList") + public void findMessages() { + messageList =3D em.createQuery("select msg from Message msg " + = + "order by msg.datetime desc") + .getResultList(); + } + = + public void select() { + message.setRead(true); + } + = + public void delete() { + messageList.remove(message); + em.remove(message); + message=3Dnull; + } + = + @Remove + public void destroy() {} = - @DataModel - private List<Message> messageList; - = - @DataModelSelection - @Out(required=3Dfalse) - private Message message; - = - @PersistenceContext(type=3DEXTENDED) - private EntityManager em; - = - @Factory("messageList") - public void findMessages() - { - messageList =3D em.createQuery("from Message msg order by msg.dateti= me desc") - .getResultList(); - } - = - public void select() - { - message.setRead(true); - } - = - public void delete() - { - messageList.remove(message); - em.remove(message); - message=3Dnull; - } - = - @Remove - public void destroy() {} +}]]> + + + = + + MessageManagerBean.java Explanator= y Notes + + + + + The @DataModel annotati= on exposes an attibute of type java.util.List to the JSF= page as an instance of javax.faces.model.DataModel. Thi= s allows us to use the list in a JSF ]]> with clickable links for each row. In this case, the DataMo= del is made available in a session context variable named messageList. + + + + + The @DataModelSelection= annotation tells Seam to inject the List element corres= ponding to the clicked link. + + + + + The @Out annotation the= n exposes the selected value directly to the page. Every time a row of the = clickable list is selected, the Message is injected to t= he attribute of the stateful bean, and subsequently "outjected" to the even= t context variable named message. + + + + + This stateful bean has an EJB3 e= xtended persistence context. This means that messages retrieved = in the query remain in the managed state for as long as the bean exists. An= y subsequent method calls to the stateful bean can therefore update the mes= sages without needing to make an explicit call to the EntityManage= r. + + + + + The first time we navigate to the JSP page= , the messageList context variable does not hold a value= . The @Factory annotation tells Seam to create an instan= ce of MessageManagerBean and invoke findMessage= s() =E2=80=94 a factory method for messages =E2=80=94 to initiali= ze the value. + + + + + The select() action lis= tener method marks the selected Message as read, and upd= ates it in the database. + + + + + The delete() action lis= tener method removes the selected Message from the datab= ase. + + + + + All stateful session bean Seam components = must have a method @Remove defined,= with no parameters marked. Seam uses this to remove the stateful bean and = clean up any server-side state when the Seam context ends. + + + + + = -} - = - The @DataModel a= nnotation exposes an attibute of type - java.util.List = to the JSF page as an instance of - javax.faces.model.DataMod= el. This allows us to use the list - in a JSF <h:dataTable><= /literal> with clickable links for - each row. In this case, the D= ataModel is made available in a - session context variable named messageList. - = - The @DataModelSelection annotation tells Seam to inject the - List element th= at corresponded to the clicked link. - = - The @Out annotat= ion then exposes the selected value directly - to the page. So every time a row of th= e clickable list is selected, the - Message is inje= cted to the attribute of the stateful bean, - and the subsequently outject= ed to the event context variable - named message. - = - This stateful bean has an EJB3 extended persistence context. - The messages retrieved in the query re= main in the managed state as long as the bean - exists, so any subsequent method calls= to the stateful bean can update them without - needing to make any explicit call to t= he EntityManager. - = - The first time we navigate to the J= SP page, there will be no value in the - messageList con= text variable. The @Factory - annotation tells Seam to create an ins= tance of MessageManagerBean - and invoke the findMessages()= method to initialize the value. We - call findMessages()= a factory method for - messages. - = - The select() act= ion listener method marks the selected - Message as read= , and updates it in the database. + = + = = - The delete() act= ion listener method removes the selected - Message from th= e database. - - All stateful session bean Seam comp= onents must have a method - with no parameters marked @Re= move that Seam uses to remove = - the stateful bean when the Seam contex= t ends, and clean up any server-side state. - - - Note that this is a session-scoped Seam component. = It is associated with the user login session, and all requests from a login session share the same i= nstance of the component. (In Seam applications, we usually use session-scoped components= sparingly.) --===============4995900109941102503==--