From seam-commits at lists.jboss.org Tue Nov 24 03:51:59 2009 Content-Type: multipart/mixed; boundary="===============2829224884053384419==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r11674 - tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US. Date: Tue, 24 Nov 2009 03:51:59 -0500 Message-ID: <200911240851.nAO8px9w008070@svn01.web.mwc.hst.phx2.redhat.com> --===============2829224884053384419== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: laubai Date: 2009-11-24 03:51:59 -0500 (Tue, 24 Nov 2009) New Revision: 11674 Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xml Log: Edited the Tutorial chapter. 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 08:09:15 UTC (rev 11673) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Tutorial.xm= l 2009-11-24 08:51:59 UTC (rev 11674) @@ -97,7 +97,7 @@ validation declaratively, via= annotations. It also needs some extra annotations that define the class as a Seam component.= - + User.java Example = - + 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 @@ -214,7 +214,7 @@
The stateless session bean class: <literal>Register= Action.java</literal> = - Most Seam application use session beans as JSF acti= on listeners (you can use JavaBeans instead if + Most Seam applications use session beans as JSF act= ion listeners (you can use JavaBeans instead if you like). We have exactly one JSF action in our application, = and one session bean method attached to it. In this case, we'll use a stateless session bean, since a= ll the state associated with our action is @@ -392,18 +392,9 @@
The Seam component deployment descriptor: <literal>= components.xml</literal> = - If you've used many Java frameworks before, you'll = be used to having to declare all your - component classes in some kind of XML file that gradua= lly grows more and more unmanageable as your - project matures. You'll be relieved to know that Seam = does not require that application components - be accompanied by XML. Most Seam applications require = a very small amount of XML that does not grow - very much as the project gets bigger. + If you have used Java frameworks previously, you wi= ll be used to declaring your component classes in an XML file. You have pro= bably also noticed that as a project matures, these XML files tend to becom= e unmanageable. Fortunately, Seam does not require application components t= o be accompanied by XML. Most Seam applications require only a small amount= of XML, which does not tend to increase in size as projects expand. = - Nevertheless, it is often useful to be able to prov= ide for some external - configuration of some components = (particularly the components built in to - Seam). You have a couple of options here, but the most= flexible option is to provide this - configuration in a file called components.xml= , located in the - WEB-INF directory. We'll use the components.xml file to tell - Seam how to find our EJB components in JNDI: + However, it is often useful to be able to provide f= or some external configuration of some components, particularly the compone= nts that are built into Seam. The most flexible option, here, is to provide= this configuration in a file called components.xml, l= ocated in the WEB-INF directory. The compone= nts.xml file can be used to tell Seam how to find our EJB compon= ents in JNDI: @@ -504,17 +495,12 @@ = = - Note that we don't need - any JSF managed bean declarations! Our managed beans a= re annotated Seam components. In Seam applications, - the faces-config.xml is used much l= ess often than in plain JSF. + Note that JSF managed bean declarations are unnece= ssary because the managed beans are annotated Seam components. In Seam appl= ications, faces-config.xml is used much less often tha= n in plain JSF. Here, we use it simply to enable Facelets (and not JSP) as = the view handler. + = - In fact, once you have all the basic descriptors se= t up, the only XML you - need to write as you add new functionality to a Seam a= pplication is orchestration: navigation rules = - or jBPM process definitions. Seam takes the view that = process flow and - configuration data are the on= ly things that truly belong in XML. + Once you have set up all the basic descriptors, the= only XML you need write to add functionality to a Seam application will be= for orchestration: navigation rules or jBPM process definitions. Seam oper= ates on the principle that process flow and configuration data are all that= truly belongs in XML. = - In this simple example, we don't even need a naviga= tion rule, since we decided to embed the view - id in our action code. + The previous example does not require a navigation = rule, since the view ID was embedded in our action code. =
= @@ -579,7 +565,7 @@ The view: <literal>register.xhtml</literal> and <li= teral>registered.xhtml</literal> = The view pages for a Seam application could be impl= emented using any technology that supports - JSF. In this example we use Facelets, because we think= it's better than JSP. + JSF. This example uses Facelets. = @@ -638,9 +624,6 @@ = = - This is a boring old Facelets page using some embed= ded EL. There is nothing specific to Seam - here. -
=
@@ -681,8 +664,6 @@ This deployment descriptor links modules in the ent= erprise archive and binds the web application to the context root /seam-registration. = - We've now seen all the files in th= e entire application! -
= @@ -813,7 +794,7 @@ = But MessageManagerBean is also r= esponsible for fetching the list of messages the first time we navigate to the message list page. T= here are various ways the user could navigate - to the page, and not all of them are preceded by a JSF= action—the user might have + to the page, and not all of them are preceded by a JSF= action — the user might have bookmarked the page, for example. So the job of fetchi= ng the message list takes place in a Seam factory method, instead of in= an action listener method. = @@ -934,12 +915,11 @@ public void destroy(); } = - From now on, we won't show local interfaces in our = code examples. = - Let's skip over components.xml, = persistence.xml, + From this point, local interfaces are no longer sho= wn in these code examples. + components.xml, persistence.xm= l, web.xml, ejb-jar.xml, faces-config.xml - and application.xml since they are = much the same as the previous example, and go - straight to the JSP. + and application.xml operate in a si= milar fashion to the previous example and to directly to the JSP. = = @@ -1055,8 +1035,8 @@
Understanding the code The center of this example is the jBPM process definiti= on. There are also two JSPs and two trivial - JavaBeans (There was no reason to use session beans, since= they do not access the database, or have any - other transactional behavior). Let's start with the proces= s definition: + JavaBeans. (There was no reason to use session beans, sinc= e they do not access the database, or have any + other transactional behavior.) Let's start with the proces= s definition: todo.jpdl.xml Example @@ -1531,7 +1511,7 @@ = - Now that we have seen the pageflow, it is very, very ea= sy to understand the rest of the application! + Now that we have seen the pageflow, it is easy to under= stand the rest of the application. = Here is the main page of the application, numb= erGuess.jspx: = @@ -1647,7 +1627,7 @@ = = - As is lose.jspx (which I can't be bo= thered copy/pasting). Finally, the JavaBean + lose.jspx is also as expected. Fina= lly, the JavaBean Seam component: NumberGuess.java Example @@ -1786,7 +1766,7 @@ = = = - As you can see, this Seam component is pure business= logic! It doesn't need to know anything at all + As you can see, this Seam component is pure business= logic. It doesn't need to know anything at all about the user interaction flow. This makes the component = potentially more reuseable. =
@@ -1849,50 +1829,60 @@ = - The booking application uses JSF, EJB 3.0 and Seam, tog= ether with Facelets for the view. There is - also a port of this application to JSF, Facelets, Seam, Ja= vaBeans and Hibernate3. + The booking application uses JSF, EJB 3.0 and Seam, tog= ether with Facelets for the view. There is also a port of this application = to JSF, Facelets, Seam, JavaBeans and Hibernate3. = - One of the things you'll notice if you play with this a= pplication for long enough is that it is - extremely robust. You can play with b= ack buttons and browser refresh and opening - multiple windows and entering nonsensical data as much as = you like and you will find it very difficult - to make the application crash. You might think that we spe= nt weeks testing and fixing bugs to achive - this. Actually, this is not the case. Seam was designed to= make it very straightforward to build robust - web applications and a lot of robustness that you are prob= ably used to having to code yourself comes - naturally and automatically with Seam. - As you browse the sourcecode of the example application= , and learn how the application works, observe - how the declarative state management and integrated valida= tion has been used to achieve this robustness. + One of the things you will notice about this applicatio= n is that it is extremely robust. You can open multiple windows, use the ba= ck and browser refresh buttons, and enter nonsensical data, but the applica= tion is difficult to crash. Seam was designed to make building robust web a= pplications straightforward, so robustness that would previously be hand-co= ded comes naturally and automatically with Seam. + = + As you browse the source code of the example applicatio= n and learn how the application works, pay particular attention to the way = the declarative state management and integrated validation has been used to= achieve this robustness. = =
Overview of the booking example = - The project structure is identical to the previous one,= to install and deploy this application, + The project structure is identical to the previous one.= To install and deploy this application, please refer to . Once you= 've successfully started the application, you can access it by pointing your browser to http://localhost:8080/seam-booking/ = - Just nine classes (plus six session beans local interfa= ces) where used to implement this application. - Six session bean action listeners contain all the business= logic for the listed features. + The application uses six session beans to implement the= business logic for the following features: = - + - BookingListAction retrieves e= xisting bookings for the currently logged in user. + + AuthenticatorAction provides th= e login authentication logic. + - - ChangePasswordAction updates = the password of the currently logged in user. + + + BookingListAction retrieves exi= sting bookings for the currently logged in user. + - - HotelBookingAction implements= the core functionality of the application: hotel - room searching, selection, booking and booking confirm= ation. This functionality is implemented as a - conversation, so this is the = most interesting class in the application. - - RegisterAction registers a ne= w system user. + + + ChangePasswordAction updates th= e password of the currently logged in user. + + + + HotelBookingAction implements b= ooking and confirmation functionality. This is implemented as a c= onversation, so this is one of the more important classes in the= application. + + + + + HotelSearchingAction implements= the hotel search functionality. + + + + + RegisterAction registers a new = system user. + + = + Three entity beans implement the application's persiste= nt domain model. = @@ -1909,66 +1899,36 @@ =
Understanding Seam conversations - We encourage you browse the sourcecode at your pleasure= . In this tutorial we'll concentrate upon one - particular piece of functionality: hotel search, selection= , booking and confirmation. From the point of - view of the user, everything from selecting a hotel to con= firming a booking is one continuous unit of - work, a conversation. Searching, howe= ver, is not part of the - conversation. The user can select multiple hotels from the= same search results page, in different - browser tabs. - Most web application architectures have no first class = construct to represent a conversation. This - causes enormous problems managing state associated with th= e conversation. Usually, Java web applications - use a combination of two techniques: first, some state is = thrown into the - HttpSession; second, persistable state = is flushed to the database after every - request, and reconstructed from the database at the beginn= ing of each new request. - Since the database is the least scalable tier, this oft= en results in an utterly unacceptable lack of - scalability. Added latency is also a problem, due to the e= xtra traffic to and from the database on every - request. To reduce this redundant traffic, Java applicatio= ns often introduce a data (second-level) cache - that keeps commonly accessed data between requests. This c= ache is necessarily inefficient, because - invalidation is based upon an LRU policy instead of being = based upon when the user has finished working - with the data. Furthermore, because the cache is shared be= tween many concurrent transactions, we've - introduced a whole raft of problem's associated with keepi= ng the cached state consistent with the - database. - Now consider the state held in the HttpSession= . By very careful programming, we - might be able to control the size of the session data. Thi= s is a lot more difficult than it sounds, - since web browsers permit ad hoc non-linear navigation. Bu= t suppose we suddenly discover a system - requirement that says that a user is allowed to have mutiple concurrent - conversations, halfway through the development = of the system (this has happened to me). - Developing mechanisms to isolate session state associated = with different concurrent conversations, and - incorporating failsafes to ensure that conversation state = is destroyed when the user aborts one of the - conversations by closing a browser window or tab is not fo= r the faint hearted (I've implemented this - stuff twice so far, once for a client application, once fo= r Seam, but I'm famously psychotic). - Now there is a better way. - Seam introduces the conversation context as a first class construct. You can - safely keep conversational state in this context, and be a= ssured that it will have a well-defined - lifecycle. Even better, you won't need to be continually p= ushing data back and forth between the - application server and the database, since the conversatio= n context is a natural cache of data that the - user is currently working with. - Usually, the components we keep in the conversation con= text are stateful session beans. (We can also - keep entity beans and JavaBeans in the conversation contex= t.) There is an ancient canard in the Java - community that stateful session beans are a scalability ki= ller. This may have been true in 1998 when - WebFoobar 1.0 was released. It is no longer true today. Ap= plication servers like JBoss AS have extremely - sophisticated mechanisms for stateful session bean state r= eplication. (For example, the JBoss EJB3 - container performs fine-grained replication, replicating o= nly those bean attribute values which actually - changed.) Note that all the traditional technical argument= s for why stateful beans are inefficient apply - equally to the HttpSession, so the prac= tice of shifting state from business tier - stateful session bean components to the web session to try= and improve performance is unbelievably - misguided. It is certainly possible to write unscalable ap= plications using stateful session beans, by - using stateful beans incorrectly, or by using them for the= wrong thing. But that doesn't mean you should - never use them. Anyway, Seam guid= es you toward a safe usage model. Welcome to - 2005. - OK, I'll stop ranting now, and get back to the tutorial= . + + This tutorial concentrates upon one particular piece of fu= nctionality: placing a hotel reservation. From the user's perspective, = hotel search, selection, booking, and confirmation are one continuous unit = of work =E2=80=94 a conversation. However, from our pe= rspective, it is important that searching remains separate so that users ca= n select multiple hotels from the same search results page, and open distin= ct conversations in separate browswer tabs. + + + Most web application architectures do not have first class= constructs to represent conversations, which makes managing conversational= state problematic. Java web applications generally use a combination of se= veral techniques. Some state is transferred in the URL, but what cannot be = transferred here is either added to the HttpSession or r= ecorded to the database at the beginning and end of each request. + + + Since the database is the least-scalable tier, this drasti= cally reduces scalability. The extra traffic to and from the database also = increases latency. In order to reduce redundant traffic, Java applications = often introduce a data cache to store commonly-accessed data between reques= ts. However, since invalidation is based upon an LRU policy, rather than wh= ether the user has finished using the data, this cache is inefficient. It i= s also shared between concurrent transactions, which introduces further iss= ues associated with keeping the cached state consistent with that of the da= tabase. + + + State held in the HttpSession suffers s= imilar issues. The HttpSession is fine for storing true = session data =E2=80=94 data common to all requests between user and applica= tion =E2=80=94 but for data related to individual request series, it does n= ot work so well. Conversations stored here quickly break down when dealing = with multiple windows or the back button. Without careful programming, data= in the HttpSession can also grow quite large, which mak= es the session difficult to cluster. Developing mechanisms to deal with the= problems these methods present (by isolating session state associated with= distinct concurrent conversations, and incorporating failsafes to ensure c= onversation state is destroyed when a conversation is aborted) can be compl= icated. + + + Seam greatly improves conditions by introducing = conversation context as a first class construct. Conversation st= ate is stored safely in this context, with a well-defined lifecycle. Even b= etter, there is no need to push data continually between the application se= rver and the database; the conversation context is a natural cache for curr= ently-used data. + = - The booking example application shows how stateful comp= onents with different scopes can collaborate - together to achieve complex behaviors. The main page of th= e booking application allows the user to - search for hotels. The search results are kept in the Seam= session scope. When the user navigates to one - of these hotels, a conversation begins, and a conversation= scoped component calls back to the session - scoped component to retrieve the selected hotel. = - The booking example also demonstrates the use of RichFa= ces Ajax to implement rich client behavior without - the use of handwritten JavaScript. + + In the following application, the conversation context is = used to store stateful session beans. These are sometimes regarded as detri= mental to scalability, and in the past, they may have been. However, modern= application servers have sophisticated mechanisms for stateful session bea= n replication. JBoss AS performs fine-grained replication, replicating only= altered bean attribute values. Used correctly, stateful session beans pose= no scalability problems, but for those uncomfortable or unfamiliar with th= e use of stateful session beans, Seam also allows the use of POJOs. + + + The booking example shows one way that stateful components= with different scopes can collaborate to achieve complex behaviors. The ma= in page of the booking application allows the user to search for hotels. Se= arch results are stored in the Seam session scope. When the user navigate t= o a hotel, a conversation begins, and a conversation scoped component retri= eves the selected hotel from the session scoped component. + + + The booking example also demonstrates the use of RichFaces= Ajax to implement rich client behavior without handwritten JavaScript. + + + The search function is implemented with a session-scoped s= tateful session bean, similar to the one used in the message list example. + = - The search functionality is implemented using a session= -scope stateful session bean, similar to the - one we saw in the message list example above. = HotelSearchingAction.java Example @@ -2724,7 +2684,7 @@ = = - Notice that the example is using page actions for some = other functionality—the login + Notice that the example is using page actions for some = other functionality — the login challenge, and the pageview counter. Also notice the use o= f a parameter in the page action method binding. This is not a standard feature of JSF EL, but Sea= m lets you use it, not just for page actions, but also in JSF method bindings. --===============2829224884053384419==--