Modified: branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-U= S/Getting_Started_With_JBoss_Tools.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 --- branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Gett= ing_Started_With_JBoss_Tools.xml 2012-07-17 15:36:16 UTC (rev 14981) +++ branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Gett= ing_Started_With_JBoss_Tools.xml 2012-07-17 15:36:31 UTC (rev 14982) @@ -7,7 +7,7 @@ JBoss Tools is a collection of Eclipse plugins. JBoss Tools a project creation wizard for Seam, Content Assist for the Unified Expression - Language (EL) in both facelets and Java code, a graphical editor for= jPDL, + Language (EL) in both facelets and Java code, = a graphical editor for Seam configuration files, support for running= Seam integration tests from within Eclipse, and much more. @@ -15,6 +15,10 @@ In short, if you are an Eclipse user, then you'll want JBoss Tools! + = + Please read the latest JBoss Tools documentation at = + = http://docs.jboss.org/tools/latest/en/seam/html_single/ + = JBoss Tools, as with seam-gen, works best with JBoss AS, but it's po= ssible @@ -27,658 +31,18 @@ Before you start = - Make sure you have JDK 5, JBoss AS 4.2 or 5.0, Eclipse 3.3, the J= Boss - Tools plugins (at least Seam Tools, the Visual Page Editor, jBPM = Tools - and JBoss AS Tools) and the TestNG plugin for Eclipse correctly + Make sure you have JDK 6, JBoss AS 7.1.1.Final, Eclipse 3.7, the = JBoss + Tools plugins (at least Seam Tools, the Visual Page Editor + and JBoss AS Tools) and the JUnit plugin for Eclipse correctly installed before starting. = Please see the official JBoss To= ols - installation page for the quickest way to get JBoss Tools= setup - in Eclipse. You can also check out the = Installing - JBoss Tools page on the JBoss community wiki for the gory - details and a set of alternative installation approaches. + url=3D"http://docs.jboss.org/tools/latest/en/GettingStartedGuide/= html_single/index.html">JBoss Tools + Getting started page for the quickest way to get JBoss To= ols setup + in Eclipse. = - -

- Setting up a new Seam project - - - Start up Eclipse and select the Seam perspec= tive. - - - - Go to File -> New -> - Seam Web Project. - - - - - - - - - - - - - First, enter a name for your new project. For this tutorial, we're - going to use - helloworld - . - - - - - Now, we need to tell JBoss Tools about JBoss AS. In this example = we - are using JBoss AS 4.2, though you can certainly use JBoss AS 5.0= as - well. Selecting JBoss AS is a two step process. First we need to - define a runtime. Again, we'll choose JBoss AS 4.2 in this case: - - - - - - - - - - - - - Enter a name for the runtime, and locate it on your hard drive: - - - - - - - - - - - - - Next, we need to define a server JBoss Tools can deploy the proje= ct to. - Make sure to again select JBoss AS 4.2, and also the runtime you = just - defined: - - - - - - - - - - - - - On the next screen give the server a name, and hit = - Finish: - - - - - - - - - - - - - Make sure the runtime and server you just created are selected, s= elect - Dynamic Web Project with Seam 2.0 (technology preview)<= /emphasis> - and hit Next: - - - - - - - - - - - - - The next 3 screens allow you to further customize your new projec= t, but - for us the defaults are fine. So just hit Next = - until you reach the final screen. - - = - - The first step here is to tell JBoss Tools about the Seam downloa= d you - want to use. Add a new = - Seam Runtime - make sure to give it a name, = and - select 2.0 as the version: - - - - - - - - - - - = - - The most important choice you need to make is between EAR deploym= ent - and WAR deployment of your project. EAR projects support EJB 3.0 = and - require Java EE 5. WAR projects do not support EJB 3.0, but may be - deployed to a J2EE environment. The packaging of a WAR is also si= mpler - to understand. If you installed an EJB3-ready application server = like - JBoss, choose EAR. Otherwise, choose - WAR. We'll assume that you've chosen a WAR = - deployment for the rest of the tutorial, but you can follow exact= ly the - same steps for a EAR deployment. - - = - - Next, select your database type. We'll assume you have MySQL inst= alled, - with an existing schema. You'll need to tell JBoss Tools about - the database, select MySQL as the database, = and - create a new connection profile. Select Generic JDBC = - Connection: - - = - - - - - - - - - = - - Give it a name: - - = - - - - - - - - - = - - JBoss Tools doesn't come with drivers for any databases, so you n= eed to - tell JBoss Tools where the MySQL JDBC driver is. Tell it about the - driver by clicking .... - - = - - Locate MySQL 5, and hit Add...: - - = - - - - - - - - - = - - Choose the MySQL JDBC Driver template: - - = - - - - - - - - - = - - Locate the jar on your computer by choosing Edit = - Jar/Zip: - - = - - - - - - - - - = - - Review the username and password used to connect, and if correct,= hit - Ok. - - = - - Finally, choose the newly created driver: - - = - - - - - - - - - = - - If you are working with an existing data model, make sure you tell - JBoss Tools that the tables already exist in the database. - - = - - Review the username and password used to connect, test the connec= tion - using the Test Connection button, and if it = works, - hit Finish: - - = - - Finally, review the package names for your generated beans, and i= f you - are happy, click Finish: - - = - - - - - - - - - - - JBoss has sophisticated support for hot re-deployment of WARs and= EARs. - Unfortunately, due to bugs in the JVM, repeated redeployment of an - EAR=E2=80=94which is common during development=E2=80=94eventually= causes the JVM to run - out of perm gen space. For this reason, we recommend running JBos= s in a - JVM with a large perm gen space at development time. We suggest t= he = - following values: - - - - -Xms512m -Xmx1024m -XX:PermSize=3D256m -XX:MaxPermSize=3D512 - - - - If you don't have so much memory available, the following is our - minimum recommendation: - - - - -Xms256m -Xmx512m -XX:PermSize=3D128m -XX:MaxPermSize=3D256 - - - - Locate the server in the JBoss Server View, = right - click on the server and select Edit Launch = - Configuration: = - - = - - - - - - - - - = - - Then, alter the VM arguments: - - = - - - - - - - - - - - If you don't want to bother with this stuff now, you don't have t= o=E2=80=94come - back to it later, when you get your first - OutOfMemoryException. - - - - To start JBoss, and deploy the project, just right click on the s= erver - you created, and click Start, (or = - Debug to start in debug mode): - - - - - - - - - - - - - Don't get scared by the XML configuration documents that were gen= erated - into the project directory. They are mostly standard Java EE stuf= f, the - stuff you need to create once and then never look at again, and t= hey - are 90% the same between all Seam projects. - - -

- -

- Creating a new action - - - If you're used to traditional action-style web frameworks, you're - probably wondering how you can create a simple web page with a - stateless action method in Java. - - = - - First, select New -> Seam Action: - - = - - - - - - - - - = - - Now, enter the name of the Seam component. JBoss Tools selects se= nsible - defaults for other fields: - - = - - - - - - - - - = - - Finally, hit Finish. - - - - Now go to http://localhost:8080/helloworld/ping.seam - and click the button. You can see the code behind this action by - looking in the project src directory. Put a = - breakpoint in the ping() method, and click the = - button again. - - - - Finally, open the helloworld-test project, loc= ate - PingTest class, right click on it, and choose - Run As -> TestNG Test: - - = - - - - - - - - - = -

- -

- Creating a form with an action - - - The first step is to create a form. Select New -> = - Seam Form: - - - - - - - - - - - = - - Now, enter the name of the Seam component. JBoss Tools selects se= nsible - defaults for other fields: - - = - - - - - - - - - = - - Go to http://localhost:8080/helloworld/hello.seam. = - Then take a look at the generated code. Run the test. Try adding = some - new fields to the form and Seam component (note, you don't need t= o = - restart the app server each time you change the code in = - src/action as Seam hot reloads the component f= or = - you ). - -

- -

- Generating an application from an existing database - - - Manually create some tables in your database. (If you need to swi= tch to - a different database, create a new project, and select the correct - database). Then, select New -> = - Seam Generate Entities: - - - - - - - - - - - = - - JBoss Tools gives you the option to either reverse engineer - entities, components and views from a database schema or to rever= se - engineer components and views from existing JPA entities. We're g= oing - to do reverse engineering from database. - - = - - Restart the deployment: - - = - - - - - - - - - = - - Then go to http://localhost:8080/helloworld. Y= ou can - browse the database, edit existing objects, and create new object= s. If = - you look at the generated code, you'll probably be amazed how sim= ple it - is! Seam was designed so that data access code is easy to write b= y = - hand, even for people who don't want to cheat by using reverse - engineering. - -

- -

- Seam and incremental hot deployment with JBoss Tools - - - JBoss Tools supports incremental hot deployment of: - - - - - any facelets page - - - - - any pages.xml file - - - - = - - out of the box. - - - - But if we want to change any Java code, we still need to do a full - restart of the application by doing a = - Full Publish. - - - - But if you really want a fast edit/compile/test cycle, Seam suppo= rts - incremental redeployment of JavaBean components. To make use of t= his - functionality, you must deploy the JavaBean components into the - WEB-INF/dev directory, so that they will be lo= aded = - by a special Seam classloader, instead of by the WAR or EAR = - classloader. - - - You need to be aware of the following limitations: - - - - - the components must be JavaBean components, they cannot be = EJB3 - beans (we are working on fixing this limitation) - - - - - - entities can never be hot-deployed - - - - - - components deployed via components.xml m= ay not - be hot-deployed - - - - - - the hot-deployable components will not be visible to any cl= asses - deployed outside of WEB-INF/dev - - - - - - Seam debug mode must be enabled and = - jboss-seam-debug.jar must be in - WEB-INF/lib - - - - - - You must have the Seam filter installed in web.xml - - - - - - You may see errors if the system is placed under any load a= nd - debug is enabled. - - - - - - - If you create a WAR project using JBoss Tools, incremental hot de= ployment - is available out of the box for classes in the = - src/action source directory. However, JBoss To= ols = - does not support incremental hot deployment for EAR projects. - -

= - Modified: branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-U= S/Gettingstarted.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 --- branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Gett= ingstarted.xml 2012-07-17 15:36:16 UTC (rev 14981) +++ branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Gett= ingstarted.xml 2012-07-17 15:36:31 UTC (rev 14982) @@ -24,9 +24,9 @@

Before you start = - Make sure you have JDK 5 or JDK 6 (see for details), JBoss AS 4.2 or 5= .0 and Ant 1.7.0, along with recent versions of - Eclipse, the JBoss IDE plugin for Eclipse and the TestNG plugi= n for Eclipse correctly installed before + Make sure you have JDK 6 (see for details), JBoss AS 7.1.1 an= d Maven 3.x, along with recent versions of + Eclipse, the JBoss IDE plugin for Eclipse correctly installed = before starting. Add your JBoss installation to the JBoss Server View= in Eclipse. Start JBoss in debug mode. Finally, start a command prompt in the directory where you unz= ipped the Seam distribution. = @@ -43,7 +43,7 @@ -Xms256m -Xmx512m -XX:PermSize=3D128m -XX:MaxPermS= ize=3D256m = If you're running JBoss from the command line, you can confi= gure the JVM options in - bin/run.conf. + bin/standalone.conf. = If you don't want to bother with this stuff now, you don't h= ave to=E2=80=94come back to it later, when you get your first OutOfMemoryException. @@ -55,7 +55,7 @@ The first thing we need to do is configure seam-gen for your= environment: JBoss AS installation directory, project workspace, and database connection. It's easy, just ty= pe: = - cd jboss-seam-2.2.x + cd jboss-seam-2.3.0 seam setup = And you will be prompted for the needed information: @@ -69,12 +69,12 @@ [echo] Welcome to seam-gen :-) [input] Enter your project workspace (the directory that contains your= Seam projects) [C:/Projects] [C:/Projects] /Users/pmuir/workspace - [input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.3.= GA] [C:/Program Files/jboss-4.2.3.GA] -/Applications/jboss-4.2.3.GA + [input] Enter your JBoss AS home directory [C:/Program Files/jboss-as-= 7.1.1.Final] [C:/Program Files/jboss-as-7.1.1.Final] +/Applications/jboss-as-7.1.1.Final [input] Enter the project name [myproject] [myproject] helloworld [echo] Accepted project name as: helloworld - [input] Select a RichFaces skin (not applicable if using ICEFaces) [bl= ueSky] ([blueSky], classic, ruby, wine, deepMarine, emeraldTown, sakura, DE= FAULT) + [input] Select a RichFaces skin [blueSky] ([blueSky], emeraldTown, rub= y, classic, japanCherry, wine, deepMarine, DEFAULT, plain) = [input] Is this project deployed as an EAR (with EJB components) or a = WAR (with no EJB support) [ear] ([ear], war, ) = @@ -84,7 +84,7 @@ = [input] Enter the Java package name for your test cases [org.jboss.hel= loworld.test] [org.jboss.helloworld.test] = - [input] What kind of database are you using? [hsql] ([hsql], mysql, o= racle, postgres, mssql, db2, sybase, enterprisedb, h2) + [input] What kind of database are you using? [h2] ([h2], hsql, mysql,= oracle, postgres, mssql, db2, sybase, enterprisedb) mysql [input] Enter the Hibernate dialect for your database [org.hibernate.d= ialect.MySQLDialect] [org.hibernate.dialect.MySQLDialect] = @@ -104,8 +104,7 @@ [input] Are you working with tables that already exist in the database= ? [n] (y, [n], ) y [input] Do you want to drop and recreate the database tables and data = in import.sql each time you deploy? [n] (y, [n], ) -n - [input] Enter your ICEfaces home directory (leave blank to omit ICEfac= es) [] [] +n = = [propertyfile] Creating new property file: /Users/pmuir/workspace/jboss-se= am/seam-gen/build.properties [echo] Installing JDBC driver jar to JBoss server @@ -157,7 +156,7 @@ (helloworld in this case), and then cli= cking Finish. Do not select Java Project from the New Project wizar= d. = - If your default JDK in Eclipse is not a Java SE 5 or Java SE= 6 JDK, you will need to select a Java SE 5 + If your default JDK in Eclipse is not a Java SE 6 JDK, you w= ill need to select a Java SE 6 compliant JDK using Project -> Properties -> Ja= va Compiler. = Alternatively, you can deploy the project from outside Eclip= se by typing seam explode. @@ -407,41 +406,4 @@ incremental hot deployment for EAR projects.

= -

- Using Seam with JBoss 4.0 - - Seam 2 was developed for JavaServer Faces 1.2. When using J= Boss AS, we recommend using JBoss 4.2 or - JBoss 5.0, both of which bundle the JSF 1.2 reference implemen= tation. However, it is still possible to use - Seam 2 on the JBoss 4.0 platform. There are two basic steps re= quired to do this: install an EJB3-enabled - version of JBoss 4.0 and replace MyFaces with the JSF 1.2 refe= rence implementation. Once you complete these - steps, Seam 2 applications can be deployed to JBoss 4.0. - -

- Install JBoss 4.0 - JBoss 4.0 does not ship a default configuration compatib= le with Seam. To run Seam, you must install - JBoss 4.0.5 using the JEMS 1.2 installer with the ejb3 pro= file selected. Seam will not run with an - installation that doesn't include EJB3 support. The JEMS i= nstaller can be downloaded from http://www.jboss.org/jbossas/downloads. -

- -

- Install the JSF 1.2 RI - - The web configuration for JBoss 4.0 can be found in the - server/default/deploy/jbossweb-tomcat55.sar. You'll need to delete - myfaces-api.jar any myface= s-impl.jar from the - jsf-libs directory. Then, you'll ne= ed to copy jsf-api.jar, - jsf-impl.jar, el-api.jar, and el-ri.jar - to that directory. The JSF JARs can be found in the Seam <= literal>lib directory. The el JARs - can be obtained from the Seam 1.2 release. - - You'll also need to edit the conf/web.xml, replacing - myfaces-impl.jar with jsf-impl= .jar. -

- - - -

- Modified: branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-U= S/Gwt.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 --- branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Gwt.= xml 2012-07-17 15:36:16 UTC (rev 14981) +++ branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Gwt.= xml 2012-07-17 15:36:31 UTC (rev 14982) @@ -172,13 +172,12 @@ =

GWT Ant Targets - = For deployment of GWT apps, there is a compile-to-Javascript step (w= hich compacts and obfuscates the code). There is an ant utility which can be used instead of the command line or GUI uti= lity that GWT provides. To use this, you will need to have the ant task jar in your ant classpath, as well as GWT downl= oaded (which you will need for hosted mode anyway). - - = + + = Then, in your ant file, place (near the top of your ant file): @@ -229,6 +228,54 @@ you can't or won't use the hosted mode browser, I would go far as to= say you should NOT be using GWT at all - it's that valuable!). + = +

+ = + = +

+ GWT Maven plugin + = + + For a deployment of GWT apps, there is a set of maven GWT goals whic= h does everything what GWT supports. The + maven-gwt-plugin usage is in more + details at GWT . + = + + Basic set up is for instance here: + + + + + [...] + + org.codehaus.mojo + gwt-maven-plugin + 1.2 + + ${project.build.outoutDirectory}/${= project.build.finalName} + false + TRACE + -Xmx512m -DDEBUG + false + + + + + resources + compile + + + + + [...] + + [...] + ]]> + + + More can be seen here = + http://mojo.codehaus.org/gwt-maven-plugin/user-guide/compile= .html +

Modified: branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-U= S/I18n.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 --- branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/I18n= .xml 2012-07-17 15:36:16 UTC (rev 14981) +++ branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/I18n= .xml 2012-07-17 15:36:31 UTC (rev 14982) @@ -1,430 +1,337 @@ - - + + - Internationalization, localization and themes - - - Seam makes it easy to build internationalized applications. First, l= et's = - walk through all the stages needed to internationalize and localize = your = - app. Then we'll take a look at the components Seam bundles. - - -

- Internationalizing your app - - - A JEE application consists of many components and all of them mus= t be = - configured properly for your application to be localized. - - = - - Note that all i18n features in Seam work only in JSF context= . = - - - - Starting at the bottom, the first step is to ensure that your dat= abase = - server and client is using the correct character encoding for you= r = - locale. Normally you'll want to use UTF-8. How to do this is outs= ide - the scope of this tutorial. - - -

- Application server configuration - - - To ensure that the application server receives the request = - parameters in the correct encoding from client requests you ha= ve to = - configure the tomcat connector. If you use Tomcat or JBoss AS,= add - the URIEncoding=3D"UTF-8" attribute to the = - connector configuration. For JBoss AS 4.2 change = - ${JBOSS_HOME}/server/(default)/deploy/jboss-web.deplo= yer/server.xml: - - - <Connector port=3D"8080" URIEncod= ing=3D"UTF-8"/> - - - There is alternative which is probably better. You can tell JB= oss AS - that the encoding for the request parameters will be taken fro= m the - request: - - - <Connector port=3D"8080" useBodyE= ncodingForURI=3D"true"/> -

- -

- Translated application strings - - - You'll also need localized strings for all the messa= ges - in your application (for example field labels on your views). = First = - you need to ensure that your resource bundle is encoded using = the = - desired character encoding. By default ASCII is used. Although= ASCII = - is enough for many languages, it doesn't provide characters fo= r all = - languages. - - - - Resource bundles must be created in ASCII, or use Unicode esca= pe = - codes to represent Unicode characters. Since you don't compile= a = - property file to byte code, there is no way to tell the JVM wh= ich = - character set to use. So you must use either ASCII characters= or = - escape characters not in the ASCII character set. - You can represent a Unicode character in any Java file using \= uXXXX, - where XXXX is the hexadecimal representation of the character. - - = - - You can write your translation of labels = - () to your messages resource = - bundle in the native encoding and then convert the content of = the = - file into the escaped format through the tool native2= ascii - provided in the JDK. This tool will convert a file written in = your = - native encoding to one that represents non-ASCII characters as - Unicode escape sequences. - - - - Usage of this tool is described = - here for Java 5 - or = - here for Java 6. - For example, to convert a file from UTF-8: - - = - $ native2ascii -encoding UTF-8 messages_c= s.properties > messages_cs_escaped.properties - = -

- -

- Other encoding settings - - - We need to make sure that the view displays your localized dat= a and = - messages using the correct character set and also any data sub= mitted - uses the correct encoding. - - - - To set the display character encoding, you need to use the = - <f:view locale=3D"cs_CZ"/> tag (here = we tell = - JSF to use the Czech locale). You may want to change the encod= ing of = - the xml document itself if you want to embed localized strings= in the - xml. To do this alter the encoding attribute in xml declaratio= n = - <?xml version=3D"1.0" encoding=3D"UTF-8"?> as = - required. - - - - Also JSF/Facelets should submit any requests using the specifi= ed - character encoding, but to make sure any requests that don't s= pecify - an encoding you can force the request encoding using a servlet = - filter. Configure this in components.xml: - - - ]]> -

- -

- Locales - - Each user login session has an associated instance of - java.util.Locale (available to the application as a - component named locale). Under normal circumstances, - you won't need to do any special configuration to set the locale. Seam - just delegates to JSF to determine the active locale: - - - - If there is a locale associated with the HTTP request (the - browser locale), and that locale is in the list of supported local= es - from faces-config.xml, use that locale for the = rest - of the session. - - - - Otherwise, if a default locale was specified in the - faces-config.xml, use that locale for the rest = of - the session. - - - - Otherwise, use the default locale of the server. - - - - It is possible to set the locale manually v= ia - the Seam configuration properties - org.jboss.seam.international.localeSelector.language, - org.jboss.seam.international.localeSelector.country and - org.jboss.seam.international.localeSelector.variant, - but we can't think of any good reason to ever do this. - - It is, however, useful to allow the user to set the locale manua= lly - via the application user interface. Seam provides built-in functionali= ty - for overriding the locale determined by the algorithm above. All you h= ave - to do is add the following fragment to a form in your JSP or Facelets - page: - - <h:selectOneMenu value=3D"#{localeSe= lector.language}"> - <f:selectItem itemLabel=3D"English" itemValue=3D"en"/> - <f:selectItem itemLabel=3D"Deutsch" itemValue=3D"de"/> - <f:selectItem itemLabel=3D"Francais" itemValue=3D"fr"/> + Internationalization, localization and themes + Seam makes it easy to build internationalized applications. = + First, let's walk through all the stages needed to = + internationalize and localize your app. Then we'll take a look at = + the components Seam bundles. +

+ Internationalizing your app + A JEE application consists of many components and all of them = + must be configured properly for your application to be = + localized. + + Note that all i18n features in Seam work only in JSF = + context. + + Starting at the bottom, the first step is to ensure that your = + database server and client is using the correct character encoding = + for your locale. Normally you'll want to use UTF-8. How to do = + this is outside the scope of this tutorial. +

+ Application server configuration + To ensure that the application server receives the request = + parameters in the correct encoding from client requests you have to = + configure the tomcat connector. If you use JBoss AS, add the system = + properties + org.apache.catalina.connector.URI_ENCODING and + org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING = + to the server configuration. For JBoss AS 7.1.1 change + ${JBOSS_HOME}/standalone/configuration/standalone.xml: + = +<system-properties> + <property name=3D"org.apache.catalina.connector.URI_ENCODING&= quot; value=3D"UTF-8"/> + <property name=3D"org.apache.catalina.connector.USE_BODY_ENCO= DING_FOR_QUERY_STRING" value=3D"true"/> +</system-properties> + +

+ Translated application strings + You'll also need localized strings for all the + messages in your application (for example field labels on = + your views). First you need to ensure that your resource bundle is = + encoded using the desired character encoding. By default ASCII is = + used. Although ASCII is enough for many languages, it doesn't = + provide characters for all languages. + Resource bundles must be created in ASCII, or use Unicode = + escape codes to represent Unicode characters. Since you don't = + compile a property file to byte code, there is no way to tell the = + JVM which character set to use. So you must use either ASCII = + characters or escape characters not in the ASCII character set. You = + can represent a Unicode character in any Java file using \uXXXX, = + where XXXX is the hexadecimal representation of the character. + You can write your translation of labels ( + ) to your messages resource bundle in the = + native encoding and then convert the content of the file into the = + escaped format through the tool native2ascii = + provided in the JDK. This tool will convert a file written in your = + native encoding to one that represents non-ASCII characters as = + Unicode escape sequences. + Usage of this tool is described = + + here for Java 5 or = + + here for Java 6. For example, to convert a file from = + UTF-8: + $ native2ascii -encoding UTF-8 messages_cs.prop= erties > messages_cs_escaped.properties +

+ Other encoding settings + We need to make sure that the view displays your localized = + data and messages using the correct character set and also any data = + submitted uses the correct encoding. + To set the display character encoding, you need to use the = + <f:view locale=3D"cs_CZ"/> tag = + (here we tell JSF to use the Czech locale). You may want to change = + the encoding of the xml document itself if you want to embed = + localized strings in the xml. To do this alter the encoding = + attribute in xml declaration <?xml = + version=3D"1.0" encoding=3D"UTF-8"?> a= s = + required. + Also JSF/Facelets should submit any requests using the = + specified character encoding, but to make sure any requests that = + don't specify an encoding you can force the request encoding = + using a servlet filter. Configure this in + components.xml: + <web:character-encoding-filter encoding= =3D"UTF-8" = + override-client=3D"true" = + url-pattern=3D"*.seam" /> +

+ Locales + Each user login session has an associated instance of + java.util.Locale (available to the application as a = + component named locale). Under normal = + circumstances, you won't need to do any special configuration to = + set the locale. Seam just delegates to JSF to determine the active = + locale: + + + If there is a locale associated with the HTTP request (the = + browser locale), and that locale is in the list of supported = + locales from faces-config.xml, use that locale = + for the rest of the session. + + + Otherwise, if a default locale was specified in the + faces-config.xml, use that locale for the rest of the = + session. + + + Otherwise, use the default locale of the server. + + + It is possible to set the locale manually = + via the Seam configuration properties + org.jboss.seam.international.localeSelector.language, = + + org.jboss.seam.international.localeSelector.country and = + + org.jboss.seam.international.localeSelector.variant, but we = + can't think of any good reason to ever do this. + It is, however, useful to allow the user to set the locale = + manually via the application user interface. Seam provides built-in = + functionality for overriding the locale determined by the algorithm = + above. All you have to do is add the following fragment to a form in = + your JSP or Facelets page: + <h:selectOneMenu value=3D"#{local= eSelector.language}"> + <f:selectItem itemLabel=3D"English" itemValue=3D"en&= quot;/> + <f:selectItem itemLabel=3D"Deutsch" itemValue=3D"de&= quot;/> + <f:selectItem itemLabel=3D"Francais" itemValue=3D"fr= "/> </h:selectOneMenu> -<h:commandButton action=3D"#{localeSelector.select}" - value=3D"#{messages['ChangeLanguage']}"/> - - Or, if you want a list of all supported locales from - faces-config.xml, just use: - - <h:selectOneMenu value=3D"#{localeSe= lector.localeString}"> - <f:selectItems value=3D"#{localeSelector.supportedLocales}"/> +<h:commandButton action=3D"#{localeSelector.select}" + value=3D"#{messages['ChangeLanguage']}"/> + Or, if you want a list of all supported locales from + faces-config.xml, just use: + <h:selectOneMenu value=3D"#{local= eSelector.localeString}"> + <f:selectItems value=3D"#{localeSelector.supportedLocales}&quo= t;/> </h:selectOneMenu> -<h:commandButton action=3D"#{localeSelector.select}" - value=3D"#{messages['ChangeLanguage']}"/> - - When the user selects an item from the drop-down, then clicks the - command button, the Seam and JSF locales will be overridden for the re= st of the - session. - - The brings us to the question of where the supported locales are - defined. Typically, you provide a list of locales for which you have - matching resource bundles in the <locale-config> - element of the JSF configuration file (/META-INF/faces-config.xml). H= owever, - you have learned to appreciate that Seam's component configuration - mechanism is more powerful than what is provided in Java EE. For that - reason, you can configure the supported locales, and the default local= e of - the server, using the built-in component named - org.jboss.seam.international.localeConfig. To use i= t, - you first declare an XML namespace for Seam's international package in= the - Seam component descriptor. You then define the default locale and supp= orted - locales as follows: - - <international:locale-config default-l= ocale=3D"fr_CA" supported-locales=3D"en fr_CA fr_FR"/> - - Naturally, if you pronounce that you support a locale, you better - provide a resource bundle to match it! Up next, you'll learn how to de= fine - the language-specific labels. -

- -

- Labels - - JSF supports internationalization of user interface labels and - descriptive text via the use of <f:loadBundle />. - You can use this approach in Seam applications. Alternatively, you can - take advantage of the Seam messages component to - display templated labels with embedded EL expressions. - -

- Defining labels - - Seam provides a java.util.ResourceBundle - (available to the application as a - org.jboss.seam.core.resourceBundle). You'll need to make y= our - internationalized labels available via this special resource bundle.= By - default, the resource bundle used by Seam is named - messages and so you'll need to define your labels= in - files named messages.properties, - messages_en.properties, - messages_en_AU.properties, etc. These files usually belong= in - the WEB-INF/classes directory. - - So, in messages_en.properties: - - Hello=3DHello - - And in messages_en_AU.properties: - - Hello=3DG'day - - You can select a different name for the resource bundle by set= ting - the Seam configuration property named - org.jboss.seam.core.resourceLoader.bundleNames. You can ev= en - specify a list of resource bundle names to be searched (depth first)= for - messages. - - <core:resource-loader> +<h:commandButton action=3D"#{localeSelector.select}" + value=3D"#{messages['ChangeLanguage']}"/> + When the user selects an item from the drop-down, then clicks = + the command button, the Seam and JSF locales will be overridden for = + the rest of the session. + The brings us to the question of where the supported locales = + are defined. Typically, you provide a list of locales for which you = + have matching resource bundles in the + <locale-config> element of the JSF configuration file = + (/META-INF/faces-config.xml). However, you have learned to appreciate = + that Seam's component configuration mechanism is more powerful = + than what is provided in Java EE. For that reason, you can configure = + the supported locales, and the default locale of the server, using = + the built-in component named + org.jboss.seam.international.localeConfig. To use it, you = + first declare an XML namespace for Seam's international package = + in the Seam component descriptor. You then define the default locale = + and supported locales as follows: + <international:locale-config default-loc= ale=3D"fr_CA" supported-locales=3D"en fr_CA fr_FR"/>= + Naturally, if you pronounce that you support a locale, you = + better provide a resource bundle to match it! Up next, you'll = + learn how to define the language-specific labels. +

+ Labels + JSF supports internationalization of user interface labels and = + descriptive text via the use of <f:loadBundle = + />. You can use this approach in Seam applications. = + Alternatively, you can take advantage of the Seam + messages component to display templated labels with = + embedded EL expressions. +

+ Defining labels + Seam provides a java.util.ResourceBundle = + (available to the application as a + org.jboss.seam.core.resourceBundle). You'll need to = + make your internationalized labels available via this special = + resource bundle. By default, the resource bundle used by Seam is = + named messages and so you'll need to define = + your labels in files named messages.properties, = + messages_en.properties, + messages_en_AU.properties, etc. These files usually belong = + in the WEB-INF/classes directory. + So, in messages_en.properties: + Hello=3DHello + And in messages_en_AU.properties: + Hello=3DG'day + You can select a different name for the resource bundle by = + setting the Seam configuration property named + org.jboss.seam.core.resourceLoader.bundleNames. You can = + even specify a list of resource bundle names to be searched (depth = + first) for messages. + <core:resource-loader> <core:bundle-names> <value>mycompany_messages</value> <value>standard_messages</value> = </core:bundle-names> </core:resource-loader> - - If you want to define a message just for a particular page, you - can specify it in a resource bundle with the same name as the JSF vi= ew - id, with the leading / and trailing file extension - removed. So we could put our message in - welcome/hello_en.properties if we only needed to display t= he - message on /welcome/hello.jsp. - - You can even specify an explicit bundle name in - pages.xml: - - <page view-id=3D"/welcome/hello.jsp"= bundle=3D"HelloMessages"/> - - Then we could use messages defined in - HelloMessages.properties on - /welcome/hello.jsp. -

- -

- Displaying labels - - If you define your labels using the Seam resource bundle, you'= ll - be able to use them without having to type <f:loadBundle - ... /> on every page. Instead, you can simply type: - - <h:outputText value=3D"#{messages[= 'Hello']}"/> - - or: - - <h:outputText value=3D"#{messages.= Hello}"/> - - Even better, the messages themselves may contain EL - expressions: - - Hello=3DHello, #{user.firstName} #{user.lastName} - - Hello=3DG'day, #{user.firstName} - - You can even use the messages in your code: - - @In private Map<String, String> = messages; - - @In("#{messages['Hello']}") private St= ring helloMessage; -

- -

- Faces messages - - The facesMessages component is a - super-convenient way to display success or failure messages to the u= ser. - The functionality we just described also works for faces - messages: - - @Name("hello") + If you want to define a message just for a particular page, = + you can specify it in a resource bundle with the same name as the = + JSF view id, with the leading / and trailing file = + extension removed. So we could put our message in + welcome/hello_en.properties if we only needed to display = + the message on /welcome/hello.jsp. + You can even specify an explicit bundle name in + pages.xml: + <page view-id=3D"/welcome/hello.js= p" bundle=3D"HelloMessages"/> + Then we could use messages defined in + HelloMessages.properties on + /welcome/hello.jsp. +

+ Displaying labels + If you define your labels using the Seam resource bundle, = + you'll be able to use them without having to type + <f:loadBundle ... /> on every page. Instead, you can = + simply type: + <h:outputText value=3D"#{message= s['Hello']}"/> + or: + <h:outputText value=3D"#{message= s.Hello}"/> + Even better, the messages themselves may contain EL = + expressions: + Hello=3DHello, #{user.firstName} #{user.lastName} + Hello=3DG'day, #{user.firstName} + You can even use the messages in your code: + @In private Map<String, String> mes= sages; + @In("#{messages['Hello']}&= quot;) private String helloMessage; +

+ Faces messages + The facesMessages component is a = + super-convenient way to display success or failure messages to the = + user. The functionality we just described also works for faces = + messages: + @Name("hello") @Stateless public class HelloBean implements Hello { @In FacesMessages facesMessages; = public String sayIt() { - facesMessages.addFromResourceBundle("Hello"); + facesMessages.addFromResourceBundle("Hello"); } } - - This will display Hello, Gavin King or - G'day, Gavin, depending upon the user's - locale. -

- -

- Timezones - - There is also a session-scoped instance of - java.util.Timezone, named - org.jboss.seam.international.timezone, and a Seam component = for - changing the timezone named - org.jboss.seam.international.timezoneSelector. By default, t= he - timezone is the default timezone of the server. Unfortunately, the JSF - specification says that all dates and times should be assumed to be UT= C, - and displayed as UTC, unless a timezone is explicitly specified using - <f:convertDateTime>. This is an extremely - inconvenient default behavior. - = - - You can use application parameter to set up different defaul= t time zone for JSF 2 in web.xml. - <context-param> + This will display Hello, Gavin King or = + G'day, Gavin, depending upon the user's = + locale. +

+ Timezones + There is also a session-scoped instance of + java.util.Timezone, named + org.jboss.seam.international.timezone, and a Seam component = + for changing the timezone named + org.jboss.seam.international.timezoneSelector. By default, = + the timezone is the default timezone of the server. Unfortunately, = + the JSF specification says that all dates and times should be assumed = + to be UTC, and displayed as UTC, unless a timezone is explicitly = + specified using <f:convertDateTime>. This is = + an extremely inconvenient default behavior. + + + You can use application parameter to set up different default time = + zone for JSF 2 in = + web.xml. + = + <context-param> <param-name>javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SY= STEM_TIMEZONE</param-name> - <param-value>true</param-value> - </context-param> - - - - Seam overrides this behavior, and defaults all dates and times to - the Seam timezone. In addition, Seam provides the - <s:convertDateTime> tag which always performs conversi= ons - in the Seam timezone. - - Seam also provides a default date converter to convert a string = value - to a date. This saves you from having to specify a converter on input = fields - that are simply capturing a date. The pattern is selected according the - the user's locale and the time zone is selected as described above. -

- -

- Themes - - Seam applications are also very easily skinnable. The theme API = is - very similar to the localization API, but of course these two concerns= are - orthogonal, and some applications support both localization and - themes. - - First, configure the set of supported themes: - - <theme:theme-selector cookie-enabled= =3D"true"> + <param-value>true</param-value> +</context-param> + + Seam overrides this behavior, and defaults all dates and times = + to the Seam timezone. In addition, Seam provides the + <s:convertDateTime> tag which always performs = + conversions in the Seam timezone. + Seam also provides a default date converter to convert a string = + value to a date. This saves you from having to specify a converter on = + input fields that are simply capturing a date. The pattern is = + selected according the the user's locale and the time zone is = + selected as described above. +

+ Themes + Seam applications are also very easily skinnable. The theme API = + is very similar to the localization API, but of course these two = + concerns are orthogonal, and some applications support both = + localization and themes. + First, configure the set of supported themes: + <theme:theme-selector cookie-enabled=3D&= quot;true"> <theme:available-themes> <value>default</value> <value>accessible</value> <value>printable</value> </theme:available-themes> </theme:theme-selector> - - Note that the first theme listed is the default theme. - - Themes are defined in a properties file with the same name as the - theme. For example, the default theme is defined as= a - set of entries in default.properties. For example, - default.properties might define: - - css ../screen.css + Note that the first theme listed is the default theme. + Themes are defined in a properties file with the same name as = + the theme. For example, the default theme is = + defined as a set of entries in default.properties. = + For example, default.properties might = + define: + css ../screen.css template /template.xhtml = - Usually the entries in a theme resource bundle will be paths to = CSS - styles or images and names of facelets templates (unlike localization - resource bundles which are usually text). - - Now we can use these entries in our JSP or facelets pages. For - example, to theme the stylesheet in a facelets page: - - <link href=3D"#{theme.css}" rel=3D"s= tylesheet" type=3D"text/css" /> - - Or, when the page definition resides in a subdirectory: - - <link href=3D"#{facesContext.externa= lContext.requestContextPath}#{theme.css}" = - rel=3D"stylesheet" type=3D"text/css" /> - - Most powerfully, facelets lets us theme the template used by a - <ui:composition>: - - <ui:composition xmlns=3D"http://www.= w3.org/1999/xhtml" - xmlns:ui=3D"http://java.sun.com/jsf/facelets" - xmlns:h=3D"http://java.sun.com/jsf/html" - xmlns:f=3D"http://java.sun.com/jsf/core" - template=3D"#{theme.template}"> - - Just like the locale selector, there is a built-in theme selecto= r to - allow the user to freely switch themes: - - <h:selectOneMenu value=3D"#{themeSel= ector.theme}"> - <f:selectItems value=3D"#{themeSelector.themes}"/> + Usually the entries in a theme resource bundle will be paths to = + CSS styles or images and names of facelets templates (unlike = + localization resource bundles which are usually text). + Now we can use these entries in our JSP or facelets pages. For = + example, to theme the stylesheet in a facelets page: + <link href=3D"#{theme.css}" = rel=3D"stylesheet" type=3D"text/css" /> + Or, when the page definition resides in a subdirectory: + <link href=3D"#{facesContext.exte= rnalContext.requestContextPath}#{theme.css}" = + rel=3D"stylesheet" type=3D"text/css" /> + Most powerfully, facelets lets us theme the template used by a = + <ui:composition>: + <ui:composition xmlns=3D"http://w= ww.w3.org/1999/xhtml" + xmlns:ui=3D"http://java.sun.com/jsf/facelets" + xmlns:h=3D"http://java.sun.com/jsf/html" + xmlns:f=3D"http://java.sun.com/jsf/core" + template=3D"#{theme.template}"> + Just like the locale selector, there is a built-in theme = + selector to allow the user to freely switch themes: + <h:selectOneMenu value=3D"#{theme= Selector.theme}"> + <f:selectItems value=3D"#{themeSelector.themes}"/> </h:selectOneMenu> -<h:commandButton action=3D"#{themeSelector.select}" value=3D"Select The= me"/> -

- -

- Persisting locale and theme preferences via cookies - - The locale selector, theme selector and timezone selector all - support persistence of locale and theme preference to a cookie. Simply= set - the cookie-enabled property in - components.xml: - - <theme:theme-selector cookie-enabled= =3D"true"> +<h:commandButton action=3D"#{themeSelector.select}" value=3D&= quot;Select Theme"/> +

+ Persisting locale and theme preferences via cookies + The locale selector, theme selector and timezone selector all = + support persistence of locale and theme preference to a cookie. = + Simply set the cookie-enabled property in + components.xml: + <theme:theme-selector cookie-enabled=3D&= quot;true"> <theme:available-themes> <value>default</value> <value>accessible</value> @@ -432,6 +339,6 @@ </theme:available-themes> </theme:theme-selector> = -<international:locale-selector cookie-enabled=3D"true"/> -

+<international:locale-selector cookie-enabled=3D"true"/> +

Modified: branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-U= S/Mail.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 --- branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Mail= .xml 2012-07-17 15:36:16 UTC (rev 14981) +++ branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Mail= .xml 2012-07-17 15:36:31 UTC (rev 14982) @@ -399,8 +399,8 @@ The Seam Mail module requires the use of Facelets as the view = - technology. Future versions of the library may also support the u= se of = - JSP. Additionally, it requires the use of the seam-ui package. + technology. This is the default View technology in JSF 2. = + Additionally, it requires the use of the jboss-seam-ui module. = @@ -426,10 +426,10 @@ JNDI lookup in JBoss AS = - The JBossAS deploy/mail-service.xml configure= s a = + The JBoss AS 7 Mail service is defined in standalone/c= onfiguration/standalone.xml file. It configures a = JavaMail session binding into JNDI. The default service = configuration will need altering for your network. = - http= ://www.jboss.org/community/wiki/JavaMail + Full article how to configur= e Mail system in JBoss AS 7 describes the service in more detail. = @@ -437,13 +437,13 @@ xmlns:core=3D"http://jboss.org/schema/seam/core" xmlns:mail=3D"http://jboss.org/schema/seam/mail"> = - + = ]]> = Here we tell Seam to get the mail session bound to = - java:/Mail from JNDI. + java:jboss/mail/Default from JNDI. = @@ -469,30 +469,6 @@ = -

- Meldware - = - - Seam's mail examples use Meldware (from buni.org) = - as a mail server. Meldware is a groupware package that provides = - SMTP, POP3, IMAP, - webmail, a shared calendar and an graphical admin tool; it's written= as a - JEE application so can be deployed onto JBoss AS alongside your Seam - application. = - - = - - - The version of Meldware distributed with Seam (downloaded on dema= nd) - is specially tailored for development - mailboxes, users and = - aliases (email addresses) are created every time the application = - deploys. If you want to use Meldware in production you should in= stall - the latest release from buni.org. = - - - = -

Tags = Modified: branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-U= S/Testing.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 --- branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Test= ing.xml 2012-07-17 15:36:16 UTC (rev 14981) +++ branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Test= ing.xml 2012-07-17 15:36:31 UTC (rev 14982) @@ -92,8 +92,7 @@ Integration testing Seam components = - Using JBoss Embedded for integration testing is now deprecated= . The preferred - way is to use Arquillian. See + Using JBoss Embedded for integration testing was removed. See = = @@ -108,8 +107,7 @@ The approach taken by Seam is to let you write tests that exer= cise your components while running inside a pruned down container enviro= nment (Seam, - together with the JBoss Embedded container; see = - for configuration= details) + together with the JBoss AS container) = = - Let's consider a JSP view for the component we unit tested abo= ve: + Let's consider a JSF view for the component we unit tested abo= ve: = @@ -301,9 +299,10 @@ You'll find plenty of integration tests for the Seam example a= pplications which demonstrate more complex cases. There are instructions f= or running - these tests using Ant, or using the TestNG plugin for eclipse: + these tests using Maven, or using the JUnit plugin for eclipse: = + @@ -324,171 +323,32 @@ = - First, lets look at the dependencies you need at a minimum: - + For ant or own build tool which uses jars on local - you can u= se to get all jars + by running ant -f get-arquillian-libs.xml -Dtest.lib.= dir=3Dlib/test. This just copy all Arquillian + jars for managed JBoss AS 7.1.1 container and copy all jars in= to defined directory lib/test + by using that test.lib.dir property. = = + = = - - - - - - - Group Id - - - Artifact Id - - - Location in Seam - - - - - - - org.jboss.seam.embedded - - - hibernate-all - - - lib/test/hibernate-all.jar - - - - - org.jboss.seam.embedded - - - jboss-embedded-all - - - lib/test/jboss-embedded-all.jar - - - - - org.jboss.seam.embedded - - - thirdparty-all - - - lib/test/thirdparty-all.jar - - - - - org.jboss.seam.embedded - - - jboss-embedded-api - - - lib/jboss-embedded-api.jar - - - - - org.jboss.seam - - - jboss-seam - - - lib/jboss-seam.jar - - - - - org.jboss.el - - - jboss-el - - - lib/jboss-el.jar - - - - - javax.faces - - - jsf-api - - - lib/jsf-api.jar - - - - - javax.el - - - el-api - - - lib/el-api.jar - - - - - javax.activation - - - javax.activation - - - lib/activation.jar - - - - -

- = - It's very important you don't put the compile time JBoss AS = - dependencies from lib/ (e.g. = - jboss-system.jar) on the classpath, these - will cause Embedded JBoss to not boot. So, just add the = - dependencies (e.g. Drools, jBPM)you need as you go. - - = - - You also need to include the bootstrap/ = - directory on the classpath; bootstrap/ co= ntains - the configuration for Embedded JBoss. - - = - And, of course you need to put your built project and tests = onto the classpath as well as jar for your test framework. Don't = forget to put all the correct configuration files for JPA and Seam = onto = - the classpath as well.Seam asks Embedded JBoss to deploy any = + the classpath as well.Seam asks Arquillian to deploy any = resource (jar or directory) which has = seam.properties in it's root. Therefore, = if you don't assemble a directory structure that resembles a deploy= able = archive containing your built project, you must put a = seam.properties in each resource. - = - - By default, a generated project will use the = - java:/DefaultDS (a built in HSQL datasour= ce in - Embedded JBoss) for testing. If you want to use another data= source - place the foo-ds.xml into = - bootstrap/deploy directory. - - = +

Using SeamTest with another test framework = - Seam provides TestNG support out of the box, but you can als= o use - another test framework, such as JUnit, if you want. + Seam provides JUnit and TestNG support out of the box, but y= ou can also use + another test framework, if you want. = @@ -552,7 +412,7 @@ = DBUnit supports two formats for dataset files, flat and XML. = Seam's - DBUnitSeamTest assumes the flat format is u= sed, so make sure that = + DBUnitSeamTest or DBJUnitSeamTest<= /literal> assumes the flat format is used, so make sure that = your dataset is in this format. = @@ -603,7 +463,7 @@ ]]> = - DBUnitSeamTest has support for MySQL and HSQL - you need to te= ll it + DBUnitSeamTest and DBJUnitSeamTest have support for MySQL and = HSQL - you need to tell it which database is being used, otherwise it defaults to HSQL: = Modified: branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-U= S/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 --- branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Tuto= rial.xml 2012-07-17 15:36:16 UTC (rev 14981) +++ branches/community/Seam_2_3/seam-reference-guide/src/docbook/en-US/Tuto= rial.xml 2012-07-17 15:36:31 UTC (rev 14982) @@ -12,10 +12,32 @@ of the Seam distribution. The registration example, which will be= the first example we look at, is in the examples/registration directory. = - Each example has the same directory structure: + Each example has the very similar directory structure which = is based on Maven project structure defaults: = + The *-ear directory contains = enterprise application submodule files such as = + aggregator for web application files, EJB project. = = + + + + The *-web directory contains = web application submodule view-related files such as = + web page templates, images and stylesheets. = = + + + + The *-ejb directory contains = Enterprise Java Beans components. = + + + + The *-tests directory contains= Maven integration and functional tests submodule. = = + + + + = + + + The view directory contains vi= ew-related files such as = web page templates, images and stylesheets. = @@ -31,26 +53,26 @@ = + = - 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. + The example applications run both on JBoss AS 7.1.1 with no ad= ditional configuration. + The following sections will explain the procedure. Note that = all the examples + are built and run from the Maven pom.xml,= so you'll need at least version 3.x + of Maven installed before you get started. At the time of writ= ing this text recent version was 3.0.4. - = = =

Running the examples on JBoss AS = - The examples are configured for use on JBoss AS 4.2 or 5= .0. 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. + The examples are configured for use on JBoss AS 7.1. You= 'll need to set JBOSS_HOME, + in your environment, to the location of your JBoss AS inst= allation. = Once you've set the location of JBoss AS and started the= application server, you can build and deploy - any example by typing ant explode in th= e directory for that example. Any example - that is packaged as an EAR deploys to a URL like + any example by typing mvn install in th= e example root directory. And deploys it by changing = + to *-ear or *-web directory in case of existence only *-we= b submodule. Type in that submodule mvn jboss-as:deploy. = + Any example that is packaged as an EAR deploys to a URL l= ike /seam-example, where example is the name of the example folder, with one exception. If the= example folder begins with seam, the prefix "seam" is ommitted. For instance, if JBoss AS is running o= n port 8080, the URL for the registration @@ -60,48 +82,18 @@ http://localhost:8080/seam-space/. = If, on the other hand, the example gets packaged as a WA= R, then it deploys to a URL like - /jboss-seam-example. Most of the examples can be deployed as a WAR - to Tomcat with Embedded JBoss by typing ant tomca= t.deploy. Several of the examples + /jboss-seam-example. Several of the examples can only be deployed as a WAR. Those examples are groovybo= oking, hibernate, jpa, and spring. =

- Running the examples on Tomcat - - 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. - - 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. = - - - 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. - - - 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/. The same is true - for examples that deploy as a WAR, as mentioned in the pre= vious section. - - -

- -

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 test. It is also possible t= o run the tests inside your IDE using the - TestNG plugin. Consult the readme.txt in the examples dire= ctory of the Seam distribution for more + Most of the examples come with a suite of Arquillian JUnit= integration tests. The easiest way to run the tests is + to run mvn verify -Darquillian=3Djbossas-managed-= 7. It is also possible to run the tests inside your IDE using the + JUnit plugin. Consult the readme.txt in the examples direc= tory of the Seam distribution for more information.

@@ -178,7 +170,7 @@ = public User() {} = - @NotNull @Length(min=3D5, max=3D15) + @NotNull @Size(min=3D5, max=3D15) public String getPassword() { return password; @@ -200,7 +192,7 @@ this.name =3D name; } = - @Id @NotNull @Length(min=3D5, max=3D15) + @Id @NotNull @Size(min=3D5, max=3D15) public String getUsername() { return username; @@ -253,7 +245,7 @@ - The @NotNull and= @Length annotations are + The @NotNull and= @Size 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). @@ -269,7 +261,7 @@ @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 directly to JSF components and are populated by JS= F during the update model values phase. We - don't need any tedious glue code to copy data back= and forth between the JSP pages and the + don't need any tedious glue code to copy data back= and forth between the JSF pages and the entity bean domain model. However, entity beans shouldn't do transaction = management or database access. So we can't use this component as a JSF action listener. For that = we need a session bean. @@ -436,7 +428,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. In this example we use Facelets, because we think= it's better than JSF. = register.xhtml @@ -540,9 +532,14 @@ = This code configures a property named jndi= Pattern of a built-in Seam component named org.jboss.seam.core.init. The= funny @ symbols are - there because our Ant build script puts the correct JN= DI pattern in when we deploy the application, + there because our Maven build puts the correct JNDI pa= ttern in when we deploy the application, which it reads from the components.properties file. Yo= u learn more about how this process works in . + = + + Eclipse M2e Web tools plugin can't use the <= literal>@ for token property filtering. Fortunately + there works the other way which is in Maven filter= ing defined - ${property}. + =

= @@ -558,8 +555,8 @@ xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=3D" http://java.sun.com/xml/ns/javaee - http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" - version=3D"2.5"> + http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" + version=3D"3.0"> =

org.jboss.seam.servlet.SeamListener @@ -607,21 +604,16 @@ xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=3D" http://java.sun.com/xml/ns/javaee - http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd" - version=3D"1.2"> - - - com.sun.facelets.FaceletViewHandler - + http://java.sun.com/xml/ns/javaee/web-facesconfig_2_1.xsd" + version=3D"2.1"> = ]]> = = 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. Here, we are simply - using it to enable Facelets as the view handler instea= d of JSP. + any JSF managed bean declarations and neither FaceletV= iewHandler definition as Facelets are default view technology = + in JSF 2! Our managed beans are annotated Seam compone= nts.

= 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 = @@ -681,7 +673,7 @@ = org.hibernate.ejb.HibernatePersistence - java:/DefaultDS + java:jboss/datasources/ExampleDS @@ -695,34 +687,34 @@ 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. + = + + This file can be generated by Maven EAR plugin a= nd registration application has got this set up registration-ear/pom.xml. + = + Just for imagination, the following is the result of= that generation: + = regist= ration application - = - Seam Registration - + http://java.sun.com/xml/ns/javaee/application_6.xsd" + version=3D"6"> + registration-ear - jboss-seam-registration.war + registration-web.war

/seam-registration

- jboss-seam-registration.jar + registration-ejb.jar jboss-seam.jar - - jboss-el.jar - - ]]> = @@ -784,7 +776,7 @@

Understanding the code The message list example has one entity bean, = Message, one session bean, - MessageListBean and one JSP. + MessageListBean and one JSF. =

The entity bean: <literal>Message.java</literal></t= itle> @@ -815,7 +807,7 @@ this.id =3D id; } = - @NotNull @Length(max=3D100) + @NotNull @Size(max=3D100) public String getTitle() { return title; @@ -956,7 +948,7 @@ needing to make any explicit call to t= he <literal>EntityManager</literal>. </para> </callout> <callout arearefs=3D"messages-factory"> - <para> The first time we navigate to the J= SP page, there will be no value in the + <para> The first time we navigate to the J= SF page, there will be no value in the <literal>messageList</literal> con= text variable. The <literal>@Factory</literal> annotation tells Seam to create an ins= tance of <literal>MessageManagerBean</literal> and invoke the <literal>findMessages()= </literal> method to initialize the value. We @@ -1008,58 +1000,58 @@ <para> Let's skip over <literal>components.xml</literal>, = <literal>persistence.xml</literal>, <literal>web.xml</literal>, <literal>ejb-jar.xml</= literal>, <literal>faces-config.xml</literal> and <literal>application.xml</literal> since they are = much the same as the previous example, and go - straight to the JSP. </para> + straight to the JSF. </para> = </section> = <section> - <title>The view: <literal>messages.jsp</literal> + The view: <literal>messages.xhtml</literal> = - The JSP page is a straightforward use of the JSF <h:dataTable> + The JSF 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" %> - + messages.xhtml + + + Messages -

Message List

- - 0}"> + + 0}"> - + - + - + - + -

- +

]]> @@ -1073,7 +1065,7 @@

How it works = - The first time we navigate to the messages.jsp= page, the page will try to resolve the + The first time we navigate to the messages.xht= ml 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 @@ -1200,7 +1192,7 @@ trivial possible business process: there is one = task to be performed, and when that task is complete, the business process ends. = - The first JavaBean handles the login screen lo= gin.jsp. Its job is just to + The first JavaBean handles the login screen lo= gin.xhtml. Its job is just to initialize the jBPM actor id using the actor component. In a real application, it would also need to authenticate the user. @@ -1226,7 +1218,7 @@ public String login() { actor.setId(user); - return "/todo.jsp"; + return "/todo.xhtml"; } }]]> @@ -1235,27 +1227,31 @@ Here we see the use of @In to inject= the built-in Actor component. = - The JSP itself is trivial: + The JSF itself is trivial: = - login.jsp - -<%@ taglib uri=3D"http://java.sun.com/jsf/core" prefix=3D"f"%> - - -Login - - -

Login

- - -

- - - + login.xhtml + + + + + Login + + +

Login

+ + + + ]]> = = @@ -1295,7 +1291,7 @@ }]]> - The description property accepts user i= nput from the JSP page, and exposes it to the + The description property accepts user i= nput from the JSF page, and exposes it to the process definition, allowing the task desc= ription to be set. @@ -1316,9 +1312,9 @@ appear on the same method, because there is usually work t= o be done using the application in order to complete the task. = - Finally, the core of the application is in tod= o.jsp: + Finally, the core of the application is in tod= o.xhtml: - todo.jsp + todo.xhtml <%@ taglib uri=3D"http://java.sun.com/jsf/core" prefix=3D"f" %> <%@ taglib uri=3D"http://jboss.org/schema/seam/taglib" prefix=3D"s" %> @@ -1392,7 +1388,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 + todo.xhtml

@@ -1470,7 +1466,7 @@ =

How it works - After logging in, todo.jsp uses the taskInstanc= eList component to display a table + After logging in, todo.xhtml uses the taskInsta= nceList component to display a table of outstanding todo items for a the current user. Initially t= here are none. It also presents a form to enter a new entry. When the user type= s the todo item and hits the "Create New Item" button, #{todoList.createT= odo} is called. This starts @@ -1488,7 +1484,7 @@ = - When todo.jsp is redisplayed, = taskInstanceList now finds = + When todo.xhtml is redisplayed, taskInstanceList now finds = the task that was just created. The task is shown in an h:dataTable. T= he internal state of the task is = displayed in = @@ -1508,7 +1504,7 @@ The state of the task and process are both updated in the data= base. = - When todo.jsp is displayed again, the= now-completed task is no longer = + When todo.xhtml is displayed again, t= he now-completed task is no longer = displayed in the taskInstanceList, since that component only= display active tasks for the user.

@@ -1538,7 +1534,7 @@ =

Understanding the code - The example is implemented using one JavaBean, three JS= P pages and a jPDL pageflow definition. Let's + The example is implemented using one JavaBean, three JS= F pages and a jPDL pageflow definition. Let's begin with the pageflow: @@ -1557,7 +1553,7 @@ http://jboss.org/schema/seam/pageflow-2.3.xsd" name=3D"numberGuess"> = - + @@ -1576,7 +1572,7 @@ = - + @@ -1587,12 +1583,12 @@ = - +

= - +

@@ -1639,120 +1635,98 @@ = Now that we have seen the pageflow, it is very, very ea= sy to understand the rest of the application! = - Here is the main page of the application, numb= erGuess.jspx: + Here is the main page of the application, numb= erGuess.xhtml: = - numberGuess.jspx - - - - - + numberGuess.xhtml + + Guess a number... -

Guess a number...

- - - = + +

- - - + + +

- = +

- I'm thinking of a number between = - and = - . You have = - guesses. + I'm thinking of a number between and + . Y= ou have + guesses.

- = +

- Your guess: = - + Your guess: + - - + + - - + + - - - + + +

- = +

- +

- = + - - -]]> +]]> = = Notice how the command button names the guess<= /literal> transition instead of calling an action directly. = - The win.jspx page is predictable: + The win.xhtml page is predictable: <= /para> - win.jspx - - - - + win.xhtml + + You won!

You won!

- - Yes, the answer was . - It took you gue= sses. - + Yes, the answer was . + It took you guesses. + Would you like to play again? - - - + ]]> = = - The lose.jspx looks roughly the same,= so we'll skip over it. + The lose.xhtml looks roughly the same= , so we'll skip over it. = Finally, we'll look at the actual application code: @@ -1867,7 +1841,7 @@ ]]> - The first time a JSP page asks for a numberGuess component, Seam + The first time a JSF page asks for a numberGuess component, Seam will create a new one for it, and the @Create method will be invoked, allowing the component to initialize itsel= f. @@ -1891,7 +1865,7 @@ xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=3D"http://jboss.org/schema/seam/pages http://jbo= ss.org/schema/seam/pages-2.3.xsd"> = - +

= @@ -1908,7 +1882,7 @@

How it works We'll step through basic flow of the application. The g= ame starts with the = - numberGuess.jspx view. When the page i= s first displayed, the = + numberGuess.xhtml view. When the page = is first displayed, the = pages.xml configuration causes conversa= tion to begin and associates the numberGuess pageflow = with that conversation. The pageflow starts with a start-page tag, = @@ -1934,7 +1908,7 @@ tests the #{numberGuess.lastGuess} stat= e to determine whether or not the user has = more guesses. If there are more guesses (lastGue= ss is false), we transition back to the original displayGuess state. Finally we've - reached a page state, so the associated page /num= berGuess.jspx is displayed. = + reached a page state, so the associated page /num= berGuess.xhtml is displayed. = Since the page has a redirect element, Seam sends a redire= ct to the user's browser, = starting the process over. @@ -1942,7 +1916,7 @@ We won't follow the state any more except to note that if = on a future request either the = win or the lose tran= sition were taken, the user would = - be taken to either the /win.jspx or /lose.jspx. = + be taken to either the /win.xhtml or /lose.xhtml. = Both states specify that Seam should end the conversation,= tossing away all the game state and = pageflow state, before redirecting the user to the final page. = @@ -2011,8 +1985,8 @@ = - 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 2, EJB 3.0 and Seam, t= ogether with Facelets for the view. There is + also a port of this application to JSF 2, Seam, JavaBeans = and Hibernate4. = 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 @@ -2272,36 +2246,34 @@ - + = - + =

Search Hotels

= -

= - - - +

+ + + = - + - - - + + +
- Maximum results:= 60; - - - - + Maximum = results: + + + +

@@ -2310,39 +2282,36 @@ =

- - 0}"> - - Name + + 0}"> + + Name #{hot.name} - - Address + + Address #{hot.address} - - City, State + + City, State #{hot.city}, #{hot.state}, #{hot.country} = - - Zip + + Zip #{hot.zip} - - Action - + + Action + - +

- ]]> + +]]> - The RichFaces Ajax <a:suppo= rt> tag allows a JSF action + The RichFaces Ajax <a:ajax&= gt; tag allows a JSF action event listener to be called by asynchronou= s XMLHttpRequest when a JavaScript event like onkeyup occurs. Even better, the reRender attribute = lets us render a fragment of the JSF page and @@ -2742,20 +2711,14 @@

- - 0}"/> - = + + 0}"/> - =

= - 0}"> + 0}"> Name #{room.name} @@ -2772,8 +2735,7 @@ Action - Sele= ct + Select

@@ -2782,7 +2744,7 @@

= +

= ]]> --===============0728330560258315943==--