[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Emmanuel Bernard
emmanuel.bernard at jboss.com
Mon Jun 4 17:50:32 EDT 2007
User: ebernard
Date: 07/06/04 17:50:32
Modified: doc/reference/en/modules gettingstarted.xml
Added: doc/reference/en/modules groovy.xml
Log:
JBSEAM-1356 Groovy documentation
Revision Changes Path
1.16 +282 -368 jboss-seam/doc/reference/en/modules/gettingstarted.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: gettingstarted.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/gettingstarted.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -b -r1.15 -r1.16
--- gettingstarted.xml 28 May 2007 19:57:00 -0000 1.15
+++ gettingstarted.xml 4 Jun 2007 21:50:32 -0000 1.16
@@ -1,104 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?>
<chapter id="gettingstarted">
<title>Getting started with Seam, using seam-gen</title>
- <para>
- The Seam distribution includes a command line utility that makes
- it really easy to set up an Eclipse project, generate some simple
- Seam skeleton code, and reverse engineer an application from a
- pre-existing database.
- </para>
-
- <para>
- This is the easy way to get your feet wet with Seam, and gives
- you some ammunition for next time you find yourself trapped in
- an elevator with one of those tedious Ruby guys ranting about
- how great and wonderful his new toy is for building totally
- trivial applications that put things in databases.
- </para>
-
- <para>
- In this release, seam-gen works best for people with JBoss AS.
- You can use the generated project with other J2EE or Java EE 5
- application servers by making a few manual changes to the
- project configuration.
- </para>
-
- <para>
- You <emphasis>can</emphasis> use seam-gen without Eclipse, but in
- this tutorial, we want to show you how to use it in conjunction
- with Eclipse for debugging and integration testing. If you don't
- want to install Eclipse, you can still follow along with this
- tutorial—all steps can be peformed from the command line.
- </para>
-
- <para>
- Seam-gen is basically just a big ugly Ant script wrapped around
- Hibernate Tools, together with some templates. That makes it
- easy to customize if you need to.
- </para>
+
+ <para>The Seam distribution includes a command line utility that makes it
+ really easy to set up an Eclipse project, generate some simple Seam skeleton
+ code, and reverse engineer an application from a pre-existing
+ database.</para>
+
+ <para>This is the easy way to get your feet wet with Seam, and gives you
+ some ammunition for next time you find yourself trapped in an elevator with
+ one of those tedious Ruby guys ranting about how great and wonderful his new
+ toy is for building totally trivial applications that put things in
+ databases.</para>
+
+ <para>In this release, seam-gen works best for people with JBoss AS. You can
+ use the generated project with other J2EE or Java EE 5 application servers
+ by making a few manual changes to the project configuration.</para>
+
+ <para>You <emphasis>can</emphasis> use seam-gen without Eclipse, but in this
+ tutorial, we want to show you how to use it in conjunction with Eclipse for
+ debugging and integration testing. If you don't want to install Eclipse, you
+ can still follow along with this tutorial—all steps can be peformed from the
+ command line.</para>
+
+ <para>Seam-gen is basically just a big ugly Ant script wrapped around
+ Hibernate Tools, together with some templates. That makes it easy to
+ customize if you need to.</para>
<section>
<title>Before you start</title>
- <para>
- Make sure you have JDK 5 or JDK 6, JBoss AS 4.2 and Ant 1.6, along
- with recent versions of Eclipse, the JBoss IDE plugin for Eclipse and
- the TestNG 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
- unzipped the Seam distribution.
- </para>
-
- <para>
- JBoss has sophisticated support for hot re-deployment of WARs
- and EARs. Unfortunately, due to bugs in the JVM, repeated
- redeployment of an EAR—which is common during
- development—eventually causes the JVM to run out of perm
- gen space. For this reason, we recommend running JBoss in a JVM
- with a large perm gen space at development time. If you're running
- JBoss from JBoss IDE, you can configure this in the server
- launch configuration, under "VM arguments". We suggest the
- following values:
- </para>
+ <para>Make sure you have JDK 5 or JDK 6, JBoss AS 4.2 and Ant 1.6, along
+ with recent versions of Eclipse, the JBoss IDE plugin for Eclipse and the
+ TestNG 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
+ unzipped the Seam distribution.</para>
+
+ <para>JBoss has sophisticated support for hot re-deployment of WARs and
+ EARs. Unfortunately, due to bugs in the JVM, repeated redeployment of an
+ EAR—which is common during development—eventually causes the JVM to run
+ out of perm gen space. For this reason, we recommend running JBoss in a
+ JVM with a large perm gen space at development time. If you're running
+ JBoss from JBoss IDE, you can configure this in the server launch
+ configuration, under "VM arguments". We suggest the following
+ values:</para>
<programlisting>-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512</programlisting>
- <para>
- If you don't have so much memory available, the following is
- our minimum recommendation:
- </para>
+ <para>If you don't have so much memory available, the following is our
+ minimum recommendation:</para>
<programlisting>-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256</programlisting>
- <para>
- If you're running JBoss from the commandline, you can configure
- the JVM options in <literal>bin/run.conf</literal>.
- </para>
-
- <para>
- If you don't want to bother with this stuff now, you don't have
- to—come back to it later, when you get your first
- <literal>OutOfMemoryException</literal>.
- </para>
+ <para>If you're running JBoss from the commandline, you can configure the
+ JVM options in <literal>bin/run.conf</literal>.</para>
+ <para>If you don't want to bother with this stuff now, you don't have
+ to—come back to it later, when you get your first
+ <literal>OutOfMemoryException</literal>.</para>
</section>
<section>
<title>Setting up a new Eclipse project</title>
- <para>
- The first thing we need to do is configure seam-gen for your
- environment: JBoss AS installation directory, Eclipse workspace,
- and database connection. It's easy, just type:
- </para>
+ <para>The first thing we need to do is configure seam-gen for your
+ environment: JBoss AS installation directory, Eclipse workspace, and
+ database connection. It's easy, just type:</para>
<programlisting>cd jboss-seam-1.3.x
seam setup</programlisting>
- <para>
- And you will be prompted for the needed information:
- </para>
+ <para>And you will be prompted for the needed information:</para>
- <programlisting><![CDATA[C:\Projects\jboss-seam>seam setup
+ <programlisting>C:\Projects\jboss-seam>seam setup
Buildfile: build.xml
setup:
@@ -144,42 +119,34 @@
BUILD SUCCESSFUL
Total time: 1 minute 17 seconds
-C:\Projects\jboss-seam>]]></programlisting>
+C:\Projects\jboss-seam></programlisting>
+
+ <para>The tool provides sensible defaults, which you can accept by just
+ pressing enter at the prompt.</para>
+
+ <para>The most important choice you need to make is between EAR deployment
+ 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 simpler to
+ understand. If you installed an EJB3-ready application server like JBoss,
+ choose <literal>ear</literal>. Otherwise, choose <literal>war</literal>.
+ We'll assume that you've chosen an EAR deployment for the rest of the
+ tutorial, but you can follow exactly the same steps for a WAR
+ deployment.</para>
+
+ <para>If you are working with an existing data model, make sure you tell
+ seam-gen that the tables already exist in the database.</para>
+
+ <para>The settings are stored in
+ <literal>seam-gen/build.properties</literal>, but you can also modify them
+ simply by running <literal>seam setup</literal> a second time.</para>
- <para>
- The tool provides sensible defaults, which you can accept by just pressing enter
- at the prompt.
- </para>
-
- <para>
- The most important choice you need to make is between EAR deployment 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 simpler to understand. If you installed an EJB3-ready
- application server like JBoss, choose <literal>ear</literal>. Otherwise, choose
- <literal>war</literal>. We'll assume that you've chosen an EAR deployment for
- the rest of the tutorial, but you can follow exactly the same steps for a
- WAR deployment.
- </para>
-
- <para>
- If you are working with an existing data model, make sure you tell seam-gen that
- the tables already exist in the database.
- </para>
-
- <para>
- The settings are stored in <literal>seam-gen/build.properties</literal>, but you
- can also modify them simply by running <literal>seam setup</literal> a second
- time.
- </para>
-
- <para>
- Now we can create a new project in our Eclipse workspace directory, by typing:
- </para>
+ <para>Now we can create a new project in our Eclipse workspace directory,
+ by typing:</para>
<programlisting>seam new-project</programlisting>
- <programlisting><![CDATA[C:\Projects\jboss-seam>seam new-project
+ <programlisting>C:\Projects\jboss-seam>seam new-project
Buildfile: build.xml
validate-workspace:
@@ -199,86 +166,76 @@
new-project:
[echo] A new Seam project named 'helloworld' was created in the C:\Projects directory
[echo] Type 'seam explode' and go to http://localhost:8080/helloworld
- [echo] Eclipse Users: Add the project into Eclipse using File > New > Project and select General > Project (not Java Project)
+ [echo] Eclipse Users: Add the project into Eclipse using File > New > Project and select General > Project (not Java Project)
[echo] NetBeans Users: Open the project in NetBeans
BUILD SUCCESSFUL
Total time: 7 seconds
-C:\Projects\jboss-seam>]]></programlisting>
+C:\Projects\jboss-seam></programlisting>
- <para>
- This copies the Seam jars, dependent jars and the JDBC driver jar to a new Eclipse
- project, and generates all needed resources and configuration files, a facelets
- template file and stylesheet, along with Eclipse metadata and an Ant build script.
- The Eclipse project will be automatically deployed to an exploded directory structure
- in JBoss AS as soon as you add the project using
- <literal>New -> Project... -> General -> Project -> Next</literal>, typing the
- <literal>Project name</literal> (<literal>helloworld</literal> in this case),
- and then clicking <literal>Finish</literal>. Do not select <literal>Java Project</literal>
- from the New Project wizard.
- </para>
-
- <para>
- 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 compliant JDK using <literal>Project -> Properties -> Java Compiler</literal>.
- </para>
-
- <para>
- Alternatively, you can deploy the project from outside Eclipse by typing
- <literal>seam explode</literal>.
- </para>
-
- <para>
- Go to <literal>http://localhost:8080/helloworld</literal>
- to see a welcome page. This is a facelets page, <literal>view/home.xhtml</literal>,
- using the template <literal>view/layout/template.xhtml</literal>.
- You can edit this page, or the template, in eclipse, and see the results
- <emphasis>immediately</emphasis>, by clicking refresh in your browser.
- </para>
-
- <para>
- Don't get scared by the XML configuration documents that were generated into the
- project directory. They are mostly standard Java EE stuff, the stuff you need to
- create once and then never look at again, and they are 90% the same between all
- Seam projects. (They are so easy to write that even seam-gen can do it.)
- </para>
-
- <para>
- The generated project includes three database and persistence configurations.
- The <literal>jboss-beans.xml</literal>, <literal>persistence-test.xml</literal>
- and <literal>import-test.sql</literal> files are used when running the TestNG
+ <para>This copies the Seam jars, dependent jars and the JDBC driver jar to
+ a new Eclipse project, and generates all needed resources and
+ configuration files, a facelets template file and stylesheet, along with
+ Eclipse metadata and an Ant build script. The Eclipse project will be
+ automatically deployed to an exploded directory structure in JBoss AS as
+ soon as you add the project using <literal>New -> Project... ->
+ General -> Project -> Next</literal>, typing the <literal>Project
+ name</literal> (<literal>helloworld</literal> in this case), and then
+ clicking <literal>Finish</literal>. Do not select <literal>Java
+ Project</literal> from the New Project wizard.</para>
+
+ <para>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 compliant JDK using <literal>Project
+ -> Properties -> Java Compiler</literal>.</para>
+
+ <para>Alternatively, you can deploy the project from outside Eclipse by
+ typing <literal>seam explode</literal>.</para>
+
+ <para>Go to <literal>http://localhost:8080/helloworld</literal> to see a
+ welcome page. This is a facelets page, <literal>view/home.xhtml</literal>,
+ using the template <literal>view/layout/template.xhtml</literal>. You can
+ edit this page, or the template, in eclipse, and see the results
+ <emphasis>immediately</emphasis>, by clicking refresh in your
+ browser.</para>
+
+ <para>Don't get scared by the XML configuration documents that were
+ generated into the project directory. They are mostly standard Java EE
+ stuff, the stuff you need to create once and then never look at again, and
+ they are 90% the same between all Seam projects. (They are so easy to
+ write that even seam-gen can do it.)</para>
+
+ <para>The generated project includes three database and persistence
+ configurations. The <literal>jboss-beans.xml</literal>,
+ <literal>persistence-test.xml</literal> and
+ <literal>import-test.sql</literal> files are used when running the TestNG
unit tests against HSQLDB. The database schema and the test data in
- <literal>import-test.sql</literal> is always exported to the database before
- running tests. The <literal>myproject-dev-ds.xml</literal>,
- <literal>persistence-dev.xml</literal>and <literal>import-dev.sql</literal>
- files are for use when deploying the application to your development database.
- The schema might be exported automatically at deployment, depending upon
- whether you told seam-gen that you are working with an existing database.
- The <literal>myproject-prod-ds.xml</literal>,
- <literal>persistence-prod.xml</literal>and <literal>import-prod.sql</literal>
- files are for use when deploying the application to your production database.
- The schema is not exported automatically at deployment.
- </para>
-
+ <literal>import-test.sql</literal> is always exported to the database
+ before running tests. The <literal>myproject-dev-ds.xml</literal>,
+ <literal>persistence-dev.xml</literal>and
+ <literal>import-dev.sql</literal> files are for use when deploying the
+ application to your development database. The schema might be exported
+ automatically at deployment, depending upon whether you told seam-gen that
+ you are working with an existing database. The
+ <literal>myproject-prod-ds.xml</literal>,
+ <literal>persistence-prod.xml</literal>and
+ <literal>import-prod.sql</literal> files are for use when deploying the
+ application to your production database. The schema is not exported
+ automatically at deployment.</para>
</section>
<section>
<title>Creating a new action</title>
- <para>
- If you're used to traditional action-style web frameworks, you're probably wondering
- how you can create a simple webpage with a stateless action method in Java. If you
- type:
- </para>
+ <para>If you're used to traditional action-style web frameworks, you're
+ probably wondering how you can create a simple webpage with a stateless
+ action method in Java. If you type:</para>
<programlisting>seam new-action</programlisting>
- <para>
- Seam will prompt for some information, and generate a new facelets page and Seam
- component for your project.
- </para>
+ <para>Seam will prompt for some information, and generate a new facelets
+ page and Seam component for your project.</para>
- <programlisting><![CDATA[C:\Projects\jboss-seam>seam new-action
+ <programlisting>C:\Projects\jboss-seam>seam new-action
Buildfile: build.xml
validate-workspace:
@@ -310,44 +267,37 @@
BUILD SUCCESSFUL
Total time: 13 seconds
-C:\Projects\jboss-seam>]]></programlisting>
-
- <para>
- Because we've added a new Seam component, we need to restart the exploded
- directory deployment. You can do this by typing <literal>seam restart</literal>,
- or by running the <literal>restart</literal> target in the generated project
- <literal>build.xml</literal> file from inside Eclipse. Another way to force
- a restart is to edit the file <literal>resources/META-INF/application.xml</literal>
- in Eclipse. <emphasis>Note that you do not need to restart JBoss each time you
- change the application.</emphasis>
- </para>
-
- <para>
- Now go to <literal>http://localhost:8080/helloworld/ping.seam</literal> and click
- the button. You can see the code behind this action by looking in the project
- <literal>src</literal> directory. Put a breakpoint in the <literal>ping()</literal>
- method, and click the button again.
- </para>
-
- <para>
- Finally, locate the <literal>PingTest.xml</literal>
- file in the test package and run the integration tests using the TestNG plugin for
- Eclipse. Alternatively, run the tests using <literal>seam test</literal> or the
- <literal>test</literal> target of the generated build.
- </para>
+C:\Projects\jboss-seam></programlisting>
+ <para>Because we've added a new Seam component, we need to restart the
+ exploded directory deployment. You can do this by typing <literal>seam
+ restart</literal>, or by running the <literal>restart</literal> target in
+ the generated project <literal>build.xml</literal> file from inside
+ Eclipse. Another way to force a restart is to edit the file
+ <literal>resources/META-INF/application.xml</literal> in Eclipse.
+ <emphasis>Note that you do not need to restart JBoss each time you change
+ the application.</emphasis></para>
+
+ <para>Now go to
+ <literal>http://localhost:8080/helloworld/ping.seam</literal> and click
+ the button. You can see the code behind this action by looking in the
+ project <literal>src</literal> directory. Put a breakpoint in the
+ <literal>ping()</literal> method, and click the button again.</para>
+
+ <para>Finally, locate the <literal>PingTest.xml</literal> file in the test
+ package and run the integration tests using the TestNG plugin for Eclipse.
+ Alternatively, run the tests using <literal>seam test</literal> or the
+ <literal>test</literal> target of the generated build.</para>
</section>
<section>
<title>Creating a form with an action</title>
- <para>
- The next step is to create a form. Type:
- </para>
+ <para>The next step is to create a form. Type:</para>
<programlisting>seam new-form</programlisting>
- <programlisting><![CDATA[C:\Projects\jboss-seam>seam new-form
+ <programlisting>C:\Projects\jboss-seam>seam new-form
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml
validate-workspace:
@@ -379,162 +329,126 @@
BUILD SUCCESSFUL
Total time: 5 seconds
-C:\Projects\jboss-seam>]]></programlisting>
-
- <para>
- Restart the application again, and go to
- <literal>http://localhost:8080/helloworld/hello.seam</literal>. Then
- take a look at the generated code. Run the test. Try adding some new
- fields to the form and Seam component (remember to restart the deploment
- each time you change the Java code).
- </para>
+C:\Projects\jboss-seam></programlisting>
+ <para>Restart the application again, and go to
+ <literal>http://localhost:8080/helloworld/hello.seam</literal>. Then take
+ a look at the generated code. Run the test. Try adding some new fields to
+ the form and Seam component (remember to restart the deploment each time
+ you change the Java code).</para>
</section>
<section>
<title>Generating an application from an existing database</title>
- <para>
- Manually create some tables in your database. (If you need to switch
+ <para>Manually create some tables in your database. (If you need to switch
to a different database, just run <literal>seam setup</literal> again.)
- Now type:
- </para>
+ Now type:</para>
<programlisting>seam generate-entities</programlisting>
- <para>
- Restart the deployment, and go to
- <literal>http://localhost:8080/helloworld</literal>.
- You can browse the database, edit existing objects, and create new
- objects. If you look at the generated code, you'll probably be amazed
- how simple it is! Seam was designed so that data access code is easy to
- write by hand, even for people who don't want to cheat by using seam-gen.
- </para>
-
+ <para>Restart the deployment, and go to
+ <literal>http://localhost:8080/helloworld</literal>. You can browse the
+ database, edit existing objects, and create new objects. If you look at
+ the generated code, you'll probably be amazed how simple it is! Seam was
+ designed so that data access code is easy to write by hand, even for
+ people who don't want to cheat by using seam-gen.</para>
</section>
<section>
<title>Deploying the application as an EAR</title>
- <para>
- Finally, we want to be able to deploy the application using standard
- Java EE 5 packaging. First, we need to remove the exploded directory
- by running <literal>seam unexplode</literal>. To deploy the EAR, we
- can type <literal>seam deploy</literal> at the command prompt, or
- run the <literal>deploy</literal> target of the generated project
- build script. You can undeploy using <literal>seam undeploy</literal>
- or the <literal>undeploy</literal> target.
- </para>
-
- <para>
- By default, the application will be deployed with the
- <emphasis>dev profile</emphasis>. The EAR will include the
- <literal>persistence-dev.xml</literal> and <literal>import-dev.sql</literal>
- files, and the <literal>myproject-dev-ds.xml</literal> file
- will be deployed. You can change the profile, and use the
- <emphasis>prod profile</emphasis>, by typing
- </para>
+ <para>Finally, we want to be able to deploy the application using standard
+ Java EE 5 packaging. First, we need to remove the exploded directory by
+ running <literal>seam unexplode</literal>. To deploy the EAR, we can type
+ <literal>seam deploy</literal> at the command prompt, or run the
+ <literal>deploy</literal> target of the generated project build script.
+ You can undeploy using <literal>seam undeploy</literal> or the
+ <literal>undeploy</literal> target.</para>
+
+ <para>By default, the application will be deployed with the <emphasis>dev
+ profile</emphasis>. The EAR will include the
+ <literal>persistence-dev.xml</literal> and
+ <literal>import-dev.sql</literal> files, and the
+ <literal>myproject-dev-ds.xml</literal> file will be deployed. You can
+ change the profile, and use the <emphasis>prod profile</emphasis>, by
+ typing</para>
<programlisting>seam -Dprofile=prod deploy</programlisting>
- <para>
- You can even define new deployment profiles for your application.
- Just add appropriately named files to your project—for example,
+ <para>You can even define new deployment profiles for your application.
+ Just add appropriately named files to your project—for example,
<literal>persistence-staging.xml</literal>,
<literal>import-staging.sql</literal> and
- <literal>myproject-staging-ds.xml</literal>—and select the
- name of the profile using <literal>-Dprofile=staging</literal>.
- </para>
-
+ <literal>myproject-staging-ds.xml</literal>—and select the name of the
+ profile using <literal>-Dprofile=staging</literal>.</para>
</section>
- <section>
+ <section id="gettingstarted-hotdeployment">
<title>Seam and incremental hot deployment</title>
- <para>
- When you deploy your Seam application as an exploded directory, you'll get
- some support for incremental hot deployment at development time. You need
- to enable debug mode in both Seam and Facelets, by adding this line
- to <literal>components.xml</literal>:
- </para>
-
- <programlisting><![CDATA[<core:init debug="true"/>]]></programlisting>
-
- <para>
- Now, the following files may be redeployed without requiring a full restart
- of the web application:
- </para>
+ <para>When you deploy your Seam application as an exploded directory,
+ you'll get some support for incremental hot deployment at development
+ time. You need to enable debug mode in both Seam and Facelets, by adding
+ this line to <literal>components.xml</literal>:</para>
+
+ <programlisting><core:init debug="true"/></programlisting>
+
+ <para>Now, the following files may be redeployed without requiring a full
+ restart of the web application:</para>
<itemizedlist>
<listitem>
- <para>
- any facelets page
- </para>
+ <para>any facelets page</para>
</listitem>
+
<listitem>
- <para>
- any <literal>pages.xml</literal> file
- </para>
+ <para>any <literal>pages.xml</literal> file</para>
</listitem>
</itemizedlist>
- <para>
- But if we want to change any Java code, we still need to do a full restart
- of the application. (In JBoss this may be accomplished by touching the
- toplevel deployment descriptor: <literal>application.xml</literal> for an
- EAR deployment, or <literal>web.xml</literal> for a WAR deployment.)
- </para>
-
- <para>
- But if you really want a fast edit/compile/test cycle, Seam supports incremental
- redeployment of JavaBean components. To make use of this functionality, you
- must deploy the JavaBean components into the <literal>WEB-INF/dev</literal>
- directory, so that they will be loaded by a special Seam classloader,
- instead of by the WAR or EAR classloader.
- </para>
-
- <para>
- You need to be aware of the following limitations:
- </para>
+ <para>But if we want to change any Java code, we still need to do a full
+ restart of the application. (In JBoss this may be accomplished by touching
+ the toplevel deployment descriptor: <literal>application.xml</literal> for
+ an EAR deployment, or <literal>web.xml</literal> for a WAR
+ deployment.)</para>
+
+ <para>But if you really want a fast edit/compile/test cycle, Seam supports
+ incremental redeployment of JavaBean components. To make use of this
+ functionality, you must deploy the JavaBean components into the
+ <literal>WEB-INF/dev</literal> directory, so that they will be loaded by a
+ special Seam classloader, instead of by the WAR or EAR classloader.</para>
+
+ <para>You need to be aware of the following limitations:</para>
<itemizedlist>
<listitem>
- <para>
- the components must be JavaBean components, they cannot be EJB3
- beans (we are working on fixing this limitation)
- </para>
+ <para>the components must be JavaBean components, they cannot be EJB3
+ beans (we are working on fixing this limitation)</para>
</listitem>
+
<listitem>
- <para>
- entities can never be hot-deloyed
- </para>
+ <para>entities can never be hot-deloyed</para>
</listitem>
+
<listitem>
- <para>
- components deployed via <literal>components.xml</literal> may not
- be hot-deployed
- </para>
+ <para>components deployed via <literal>components.xml</literal> may
+ not be hot-deployed</para>
</listitem>
+
<listitem>
- <para>
- the hot-deployable components will not be visible to any classes deployed
- outside of <literal>WEB-INF/dev</literal>
- </para>
+ <para>the hot-deployable components will not be visible to any classes
+ deployed outside of <literal>WEB-INF/dev</literal></para>
</listitem>
+
<listitem>
- <para>
- Seam debug mode must be enabled
- </para>
+ <para>Seam debug mode must be enabled</para>
</listitem>
</itemizedlist>
- <para>
- If you create a WAR project using seam-gen, incremental hot deployment is
- available out of the box for classes in the <literal>src/action</literal>
- source directory. However, seam-gen does not support incremental hot
- deployment for EAR projects.
- </para>
-
+ <para>If you create a WAR project using seam-gen, incremental hot
+ deployment is available out of the box for classes in the
+ <literal>src/action</literal> source directory. However, seam-gen does not
+ support incremental hot deployment for EAR projects.</para>
</section>
-
</chapter>
\ No newline at end of file
1.1 date: 2007/06/04 21:50:32; author: ebernard; state: Exp;jboss-seam/doc/reference/en/modules/groovy.xml
Index: groovy.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<chapter>
<title>Groovy integration</title>
<para>One aspect of JBoss Seam is its RAD (Rapid Application Development)
capability. While not synonym with RAD, one interesting tool in this space
is dynamic languages. Until recently, choosing a dynamic language was
synonym of choosing a completly different development platform (a
development platform with a set of APIs and a runtime so great that you
would no longer want to use you old legacy Java [sic] APIs anymore, which
would be lucky because you would be forced to use those proprietary APIs
anyway). Dynamic languages built on top of the Java Virtual Machine, and
<ulink url="http://groovy.codehaus.org">Groovy</ulink> in particular broke
this approach in silos.</para>
<para>Bringing the dynamic language world to the JBoss Seam and the Java EE
world is now possible. By seamlessly integrating both static and dynamic
languages, JBoss Seam let the application developer use the best tool for
the task, without context switching: writing dynamic Seam components are
exactly like writing regular Seam components, same annotations, same APIs,
same everything.</para>
<section>
<title id="groovy">Groovy introduction</title>
<para>Groovy is an agile dynamic language based on the Java language but
with additional features inspired by Python, Ruby and Smalltalk. The
strengths of Groovy are twofold:</para>
<itemizedlist>
<listitem>
<para>the Java syntax is supported in Groovy: a Java code is a Groovy
code, making the learning curve very smooth</para>
</listitem>
<listitem>
<para>a Groovy object is a Java object, a Groovy class is a Java
class: Groovy integrates smoothly with all the Java libraries and
frameworks out there.</para>
</listitem>
</itemizedlist>
<para>TODO: write a quick overview of the Groovy syntax add-on</para>
</section>
<section>
<title>Writing Seam applications in Groovy</title>
<para>There is not much to say about it. A Groovy object is a Java object,
you can virtually write any Seam component, or any class for what it
worth, in Groovy and deploy them. You can also mix Groovy classes and Java
classes in the same application.</para>
<section>
<title>Writing Groovy components</title>
<para>As you should have noticed by now, Seam uses annotations heavily.
Be sure to use Groovy 1.1 Beta1 or above, with annotations support. The
Groovy annotations support has been very stable. Here are some example
of groovy code used in a Seam application.</para>
<section>
<title>Entity</title>
<programlisting> @Entity
@Name("hotel")
class Hotel implements Serializable
{
@Id @GeneratedValue
Long id
@Length(max=50) @NotNull
String name
@Length(max=100) @NotNull
String address
@Length(max=40) @NotNull
String city
@Length(min=2, max=10) @NotNull
String state
@Length(min=4, max=6) @NotNull
String zip
@Length(min=2, max=40) @NotNull
String country
@Column(precision=6, scale=2)
BigDecimal price
@Override
String toString()
{
return "Hotel(${name},${address},${city},${zip})"
}
}
</programlisting>
<para>Groovy natively support the notion of properties
(getter/setter), no need to explicitly write verbose getters and
setters: in the previous example, the hotel class can be accessed from
Java as <code>hotel.getCity()</code>, the getters and setters being
generated by the Groovy compiler. This syntactic sugar (amongst
others) makes the entity code very concise.</para>
<para>Some temporary gotchas: Groovy 1.1 Beta1 does not (yet) support
generics definition. Practically, you will need to use the
targetEntity attribute of <literal>@*ToMany</literal> instead of
<code>Collection<Entity></code>. For the same reason, you won't
be able to benefit from the very useful <xref linkend="framework" />.
Such a support is targeted for Groovy 1.1 though (Groovy 1.1 Beta2 at
the time of writing).</para>
</section>
<section>
<title>Seam component</title>
<para>Writing Seam components in Groovy is in no way different than in
Java: annotations are use to mark the class as Seam component.</para>
<programlisting>@Scope(ScopeType.SESSION)
@Name("bookingList")
class BookingListAction implements Serializable
{
@In EntityManager em
@In User user
@DataModel List<Booking> bookings
@DataModelSelection Booking booking
@Logger Log log
@Factory public void getBookings()
{
bookings = em.createQuery('''
select b from Booking b
where b.user.username = :username
order by b.checkinDate''')
.setParameter("username", user.username)
.getResultList()
}
public void cancel()
{
log.info("Cancel booking: #{bookingList.booking.id} for #{user.username}")
Booking cancelled = em.find(Booking.class, booking.id)
if (cancelled != null) em.remove( cancelled )
getBookings()
FacesMessages.instance().add("Booking cancelled for confirmation number #{bookingList.booking.id}", new Object[0])
}
}</programlisting>
<para></para>
</section>
</section>
<section>
<title>seam-gen</title>
<para>Seam gen has a transparent integration with Groovy. You can write
Groovy code in seam-gen backed projects without any additional
infrastructure requirement. When writing a Groovy entity, simply place
your <filename>.groovy</filename> files in
<filename>src/model</filename>. Unsurprisingly, when writing an action,
simply place your <filename>.groovy</filename> files in
<filename>src/action</filename>.</para>
</section>
</section>
<section>
<title>Deployment</title>
<para>Deploying Groovy classes is very much alike deploying Java classes
(surprisingly, no need to write nor comply with a 3-letter composite
specification to support a multi languages component framework).</para>
<para>Beyond standard deployments, JBoss Seam has the ability, at
development time, to redeploy JavaBeans Seam component classes without
having to restart the application, saving a lot of time in development /
test cycles. The same support is provided for GroovyBeans Seam components,
with one additional particularity: the <filename>.groovy</filename> file
themselves are deployed.</para>
<section>
<title>Deploying Groovy code</title>
<para>A Groovy class <emphasis>is</emphasis> a Java class, with a
bytecode representation just like a Java class. To deploy, a Groovy
entity, a Groovy Session bean, a Groovy Seam component, a compilation
step is necessary. A common approach is to use the
<literal>groovyc</literal> ant task. Once compile, a Groovy class is in
no way different than a Java class and the application server will treat
them equally. Note that this allow a seamless mix of Groovy and Java
code.</para>
</section>
<section>
<title>Native .groovy file deployment at development time</title>
<para>JBoss Seam supports natively the deployment of
<literal>.groovy</literal> files (ie without compilation) in incremental
hotdeployment mode (development only). This enables a very fast
edit/test cycle. To set up .groovy deployments, follow the configuration
at <xref linkend="gettingstarted-hotdeployment" /> and deploy your
Groovy code (<filename>.groovy</filename> files) into the
<filename>WEB-INF/dev</filename> directory. The GroovyBean components
will be picked up incrementally with no need to restart the application
(and obviously not the application server either).</para>
<para>Be aware that the native .groovy file deployment suffers the same
limitations as the regular Seam hotdeployment:</para>
<itemizedlist>
<listitem>
<para>the components must be JavaBeans or GroovyBeans, there cannot
be EJB3 bean</para>
</listitem>
<listitem>
<para>entities cannot be hotdeployed</para>
</listitem>
<listitem>
<para>the hot-deployable components will not be visible to any
classes deployed outside of <literal>WEB-INF/dev</literal></para>
</listitem>
<listitem>
<para>Seam debug mode must be enabled</para>
</listitem>
</itemizedlist>
<para></para>
</section>
<section>
<title>seam-gen</title>
<para>Seam-gen transparently supports Groovy files deployment and
compilation. This includes the native <filename>.groovy</filename> file
deployment in development mode (compilation-less). If you create a
seam-gen project of type WAR, Java and Groovy classes in
<filename>src/action</filename> will automatically be candidate for the
incremental hot deployment. If you are in production mode, the Groovy
files will simply be compiled before deployment.</para>
<para>You will find a live example of the Booking demo written completly
in Groovy and supporting incremental hot deployment in
<filename>examples/groovybooking</filename>.</para>
</section>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list