Seam Tutorial

--===============2976945207518061672== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: norman.richards(a)jboss.com Date: 2008-10-03 15:57:11 -0400 (Fri, 03 Oct 2008) New Revision: 9185 Modified: trunk/doc/Seam_Reference_Guide/en-US/Tutorial.xml Log: JBSEAM-3026 Modified: trunk/doc/Seam_Reference_Guide/en-US/Tutorial.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/Tutorial.xml 2008-10-03 16:24:02 U= TC (rev 9184) +++ trunk/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2008-10-03 19:57:11 U= TC (rev 9185) @@ -4,82 +4,83 @@ Seam Tutorial =

- Try the examples + Using the Seam examples = - In this tutorial, we'll assume that you have downloaded JBo= ss AS 4.2. You should also have a copy of - Seam downloaded and extracted to a work directory. + Seam provides a number of example applications demonstrating= how to use the various features + of Seam. This tutorial will guide you through a few of those exam= ples to help you get started + learning Seam. The Seam examples are located in the exam= ples subdirectory + of the Seam distribution. The registration example, which will be= the first example we look at, + is in the examples/registration directory. = - The directory structure of each example in Seam follows thi= s pattern: + Each example has the same directory structure: = - Web pages, images and stylesheets may be found in - examples/registration/view + The view directory contains vi= ew-related files such as = + web page templates, images and stylesheets. + = - Resources such as deployment descriptors and data i= mport scripts may be found in - examples/registration/resources + The resources directory contai= ns deployment descriptors and + other configuration files. = - Java source code may be found in - examples/registration/src - + The src directory contains th= e application source code. - - The Ant build script is - examples/registration/build.xml - - + = + + The example applications run both on JBoss AS and Tomcat with = no additional configuration. + The following sections will explain the procedure in both case= s. Note that all the examples + are built and run from the Ant build.xml,= so you'll need a recent version + of Ant installed before you get started. + + = + + =

Running the examples on JBoss AS = - First, make sure you have Ant correctly installed, with= $ANT_HOME and - $JAVA_HOME set correctly. Next, mak= e sure you set the location of your JBoss AS - 4.2 installation in the build.properties file in the root folder of your Seam - installation. If you haven't already done so, start JBoss = AS now by typing bin/run.sh - or bin/run.bat in the root directory of= your JBoss installation. + The examples are configured for use on JBoss 4.2. You'll= need to set jboss.home, + in the shared build.properties file in = the root folder of your Seam = + installation, to the location of your JBoss AS installatio= n . = - Now, build and deploy the example by typing an= t deploy in the - examples/registration directory. + Once you've done that and started the application serve= r, you can build = + and deploy any example by typing ant deploy in the + the directory for that example. The examples all deploy= to a URL = + like /seam-example<= /literal>. + For the registration example, the URL would be + http://localhost:8080/seam-registration/. = - Try it out by accessing - http://localhost:8080/seam-registration/ - with your web browser. -

Running the examples on Tomcat = - = - First, make sure you have Ant correctly installed, with $ANT_HOME and - $JAVA_HOME set correctly. Next, make su= re you set the location of your Tomcat = - 6.0 installation in the build.properties file in the root folder of your Seam - installation. You will need to follow the instructions in= - for installing JBoss Embedded on Tomcat 6.0. JBoss Embedd= ed is required to run the Seam demo - applications on Tomcat. (However, it is possible to use Se= am on Tomcat without JBoss Embedded.) + The examples are also configured for use on Tomcat 6.0. = You will need to follow the + instructions in + for installing JBoss Embedded on Tomcat 6.0. JBoss Embedd= ed is only required to run the Seam = + demos that use EJB3 components on Tomcat. There are also e= xamples of non-EJB3 applications that = + can be run on Tomcat without the use of JBoss Embedded. - - = - Now, build and deploy the example by typing ant t= omcat.deploy in the - examples/registration= directory. + You'll need to + set tomcat.home, in the shared build.properties file in = + the root folder of your Seam installation, to the location= of your Tomcat installation. + make sure you set the location of your Tomcat. = = - Finally, start Tomcat. - - - Try it out by accessing - http://localhost:8080/jboss-seam-registration/ - with your web browser. + You'll need to use a different Ant target when using Tom= cat. Use = + ant tomcat.deploy in example subdirecto= ry to build and deploy + any example for Tomcat. = - - When you deploy the example to Tomcat, any EJB3 components= will run inside the JBoss Embeddable EJB3 - container, a complete standalone EJB3 container environmen= t. + On Tomcat, the examples deploy to URLs like = + /jboss-seam-example, so for the registration + example the URL would be + http://localhost:8080/jboss-seam-registration/. =

@@ -87,9 +88,9 @@

Running the example tests = - Most of the examples come with a suite of TestNG integrati= on tests. The easiest way to run the tests - is to run ant testexample inside the - examples/registration= directory. It is also possible + Most of the examples come with a suite of TestNG integrati= on tests. The easiest way to = + run the tests + is to run ant test. It is also possible to run the tests inside your IDE using the TestNG plugin.

@@ -99,7 +100,7 @@

Your first Seam application: the registration example</titl= e> = - <para> The registration example is a fairly trivial application th= at lets a new user store his username, real + <para> The registration example is a simple application that lets = a new user store his username, real name and password in the database. The example isn't intended = to show off all of the cool functionality of Seam. However, it demonstrates the use of an EJB3 session bean= as a JSF action listener, and basic configuration of Seam. </para> @@ -121,7 +122,8 @@ <section> <title>Understanding the code = - The example is implemented with two JSP pages, one enti= ty bean and one stateless session bean. + The example is implemented with two Facelets templates,= one entity bean and one = + stateless session bean. = @@ -142,7 +144,7 @@ annotations that define the class as a Seam component.= - + User.java @@ -286,7 +288,7 @@ This is the only really interesting code in the exa= mple! - + RegisterAction.java @@ -336,7 +338,7 @@ = - The EJB standard @Stateles= s annotation marks this class as + The EJB @Stateless annotation marks this class as a stateless session bean. @@ -395,20 +397,19 @@ = 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 - beans belong in the stateless context. + default scope is the stateless context, which is t= he only sensible value. = Our session bean action listener performs the b= usiness and persistence logic for our - mini-application. In more complex applications, we= might need to layer the code and refactor - persistence logic into a dedicated data access com= ponent. That's perfectly trivial to do. But - notice that Seam does not force you into any parti= cular strategy for application layering. - - Furthermore, notice that our session bean has s= imultaneous access to context associated with - the web request (the form values in the U= ser object, for example), and state - held in transactional resources (the Enti= tyManager object). This is a break - from traditional J2EE architectures. Again, if you= are more comfortable with the traditional - J2EE layering, you can certainly implement that in= a Seam application. But for many - applications, it's simply not very useful. + mini-application. In more complex applications, we= might need require a separate service + layer. This is easy to achieve with Seam, but it'= s overkill for most web applications. = + Seam does not force you into any particular strate= gy for application layering, allowing = + your application to be as simple, or as complex, a= s you want. = + + Note that in this simple + application, we've actually made it far more compl= ex than it needs to be. If we had + used the Seam application framework controllers, w= e would have eliminated all of our = + application code. However, then we wouldn't have = had much of an application to explain. + =

= @@ -417,7 +418,7 @@ = Naturally, our session bean needs a local interface.= = - + Register.java = = - That's the end of the Java code. Now onto the deplo= yment descriptors. + That's the end of the Java code. Now we'll look at = the view. =

+ 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. + + + register.xhtml + + + + + + Register New User + + + + + + + Username: + Real Name: + Password: + + + + + + + + +]]> + = + + The only thing here that is specific to Seam is the + <s:validateAll> tag. This JSF= component tells JSF to validate all + the contained input fields against the Hibernate Valid= ator annotations specified on the entity bean. + + + registered.xhtml + + + + + + Successfully Registered New User + + + + Welcome, #{user.name}, you are successfully registered as #{user.= username}. + + + + +]]> + + + + This is a simple Facelets page using some embedded = EL. There is nothing specific to Seam + here. + +

+ = +

The Seam component deployment descriptor: <literal>= components.xml</literal> = + Since this is the first Seam app we've seen, we'll t= ake a look at the deployment + descriptors. Before we get into them, it is worth noti= ng that Seam strongly values = + minimal configuration. These configuration files will = be created for you when you create a Seam = + application. You'll never need to touch most of these= files. We're presenting them + now only to help you understand what all the pieces in= the example are doing. = + + = 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 @@ -445,7 +522,7 @@ WEB-INF directory. We'll use the components.xml file to tell Seam how to find our EJB components in JNDI: - + components.xml The presentation layer for our mini-application wil= l be deployed in a WAR. So we'll need a web deployment descriptor. - + + web.xml

= - + faces-config.xml

- 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. - - - - - - - - - Register New User - - - - - - - Username: - Real Name: - Password: - - - - - - - - -]]> - = - - The only thing here that is specific to Seam is the - <s:validateAll> tag. This JSF= component tells JSF to validate all - the contained input fields against the Hibernate Valid= ator annotations specified on the entity bean. - - - - - - - - - Successfully Registered New User - - - - Welcome, #{user.name}, you are successfully registered as #{user.= username}. - - - - -]]> - - - - This is a boring old Facelets page using some embed= ded EL. There is nothing specific to Seam - here. - -

- -

The EAR deployment descriptor: <literal>application= .xml</literal> = Finally, since our application is deployed as an EA= R, we need a deployment descriptor there, too. @@ -779,7 +788,7 @@ flag indicating whether the message has been read: = - + Message.java - + MessageManagerBean.java @@ -886,7 +895,7 @@ @Factory("messageList") public void findMessages() { - messageList =3D em.createQuery("from Message msg order by msg.dateti= me desc") + messageList =3D em.createQuery("select msg from Message msg order by= msg.datetime desc") .getResultList(); } = @@ -968,7 +977,9 @@ The session bean local interface: <literal>MessageM= anager.java</literal> = All session beans have a business interface, of cou= rse. - + + MessageManager.java + = +}]]> = From now on, we won't show local interfaces in our = code examples. = @@ -993,7 +1004,7 @@ The JSP page is a straightforward use of the JSF <h:dataTable> component. Again, nothing specific to Seam. - + messages.jsp <%@ taglib uri=3D"http://java.sun.com/jsf/core" prefix=3D"f" %> @@ -1048,8 +1059,7 @@

How it works = - The first time we navigate to the messages.jsp= page, whether by a JSF postback - (faces request) or a direct browser GET request (non-faces= request), the page will try to resolve the + The first time we navigate to the messages.jsp= page, the page will try to resolve the messageList context variable. Since= this context variable is not initialized, Seam will call the factory method findMessages()<= /literal>, which performs a query against the database and results in a DataModel bei= ng outjected. This @@ -1102,7 +1112,7 @@ other transactional behavior). Let's start with the proces= s definition: - + todo.jpdl.xml @@ -1180,7 +1190,7 @@ initialize the jBPM actor id using the actor component. (In a real application, it would also need to authenticate the user.) - + Login.java The JSP itself is trivial: = - + + login.jsp + <%@ taglib uri=3D"http://java.sun.com/jsf/core" prefix=3D"f"%> @@ -1228,7 +1240,7 @@ -]]> +]]> = = = @@ -1236,7 +1248,7 @@ = - + TodoList.java @@ -1289,7 +1301,7 @@ = Finally, the meat of the application is in tod= o.jsp: - + todo.jsp <%@ taglib uri=3D"http://java.sun.com/jsf/core" prefix=3D"f" %> <%@ taglib uri=3D"http://jboss.com/products/seam/taglib" prefix=3D"s" %> @@ -1363,7 +1375,7 @@ The page renders a list of tasks, which it gets from a = built-in Seam component named taskInstanceList. The list is defin= ed inside a JSF form. - + todo.jsp

@@ -1416,12 +1428,11 @@ ]]> = - (Note that this is using a Seam <s:button&g= t; JSF control from the - seam-ui.jar package.) + Note that this is using a Seam <s:button>= ; JSF control from the + seam-ui.jar package. This button is use= d to update the properties of the + tasks. When the form is submitted, Seam and jBPM will make= any changes to the tasks persistent. + There is no need for any action listener method: = - This button is used to update the properties of the tas= ks. When the form is submitted, Seam and jBPM - will make any changes to the tasks persistent. There is no= need for any action listener method: - ]]> = A second form on the page is used to create new items, = by calling the action method annotated @@ -1438,6 +1449,7 @@ configuration and not very interesting.

= + =

How it works TODO @@ -1472,7 +1484,7 @@ begin with the pageflow: - + pageflow.jpdl.xml @@ -1493,6 +1505,7 @@ + = @@ -1511,6 +1524,11 @@ = + + + + + =

@@ -1566,7 +1584,7 @@ Here is the main page of the application, numb= erGuess.jspx: = - + numberGuess.jspx The win.jspx page is predictable: - + win.jspx = = - As is lose.jspx (which I can't be bo= thered copy/pasting). Finally, the JavaBean - Seam component: + The lose.jspx looks roughly the same,= so we'll skip over it. + = + Finally, we'll look at the actual application code: - + NumberGuess.java @@ -1805,7 +1824,10 @@ pageflow definition to use for the conversation's page flo= w. = = + + pages.xml = + =

= - - - - = -]]> = +]]> = + = = As you can see, this Seam component is pure business= logic! It doesn't need to know anything at all --===============2976945207518061672==--