[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Fri Nov 10 00:50:30 EST 2006
User: gavin
Date: 06/11/10 00:50:30
Modified: doc/reference/en/modules components.xml concepts.xml
events.xml
Added: doc/reference/en/modules gettingstarted.xml
Log:
update docs for 1.1
Revision Changes Path
1.46 +6 -0 jboss-seam/doc/reference/en/modules/components.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: components.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/components.xml,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -b -r1.45 -r1.46
--- components.xml 30 Oct 2006 17:57:02 -0000 1.45
+++ components.xml 10 Nov 2006 05:50:30 -0000 1.46
@@ -976,6 +976,12 @@
variables in the client instead of in the <literal>HttpSession</literal>.
</para>
</listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.init.userTransactionName</literal> — the JNDI
+ name to use when looking up the JTA <literal>UserTransaction</literal> object.
+ </para>
+ </listitem>
</itemizedlist>
</listitem>
</varlistentry>
1.37 +41 -0 jboss-seam/doc/reference/en/modules/concepts.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: concepts.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/concepts.xml,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -b -r1.36 -r1.37
--- concepts.xml 23 Oct 2006 18:14:47 -0000 1.36
+++ concepts.xml 10 Nov 2006 05:50:30 -0000 1.37
@@ -809,6 +809,47 @@
</sect2>
<sect2>
+ <title>Fine-grained configuration files</title>
+ <para>
+ If you have a large number of components that need to be configured in XML, it
+ makes much more sense to split up the information in
+ <literal>components.properties</literal> into many small files. Seam lets you
+ put configuration for a class named, for example,
+ <literal>com.helloworld.Hello</literal> in a resource named
+ <literal>com/helloworld/Hello.component.xml</literal>. (You might be familiar
+ with this pattern, since it is the same one we use in Hibernate.) The root
+ element of the file may be either a <literal><components></literal> or
+ <literal><component></literal> element.
+ </para>
+
+ <para>
+ The first option lets you define multiple components in the file:
+ </para>
+
+ <programlisting><![CDATA[<components>
+ <component class="com.helloworld.Hello" name="hello">
+ <property name="name">#{user.name}</property>
+ </component>
+ <factory name="message" value="#{hello.message}"/>
+</components>]]></programlisting>
+
+ <para>
+ The second option only lets you define or configure one component,
+ but is less noisy:
+ </para>
+
+ <programlisting><![CDATA[<component name="hello">
+ <property name="name">#{user.name}</property>
+</component>]]></programlisting>
+
+ <para>
+ In the second option, the class name is implied by the file in which the
+ component definition appears.
+ </para>
+
+ </sect2>
+
+ <sect2>
<title>Configurable property types</title>
<para>
Properties of string, primitive or primitive wrapper type may be configured just
1.3 +20 -0 jboss-seam/doc/reference/en/modules/events.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: events.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/events.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- events.xml 23 Oct 2006 18:14:47 -0000 1.2
+++ events.xml 10 Nov 2006 05:50:30 -0000 1.3
@@ -226,6 +226,26 @@
</sect3>
+ <sect3>
+ <title>Fine-grained files for definition of page actions and parameters</title>
+ <para>
+ If you have a lot of different page actions and page parameters,
+ you will almost certainly want to split the declarations up over
+ multiple files. You can define actions and parameters for a page
+ with the view id <literal>/calc/calculator.jsp</literal> in a
+ resource named <literal>calc/calculator.page.xml</literal>. The
+ root element in this case is the <literal><page></literal>
+ element, and the view id is implied:
+ </para>
+
+ <programlisting><![CDATA[<page action="#{calculator.calculate}">
+ <param name="x" value="#{calculator.lhs}"/>
+ <param name="y" value="#{calculator.rhs}"/>
+ <param name="op" converter="#{operatorConverter}"/>
+</page>]]></programlisting>
+
+ </sect3>
+
</sect2>
<sect2>
1.1 date: 2006/11/10 05:50:30; author: gavin; state: Exp;jboss-seam/doc/reference/en/modules/gettingstarted.xml
Index: gettingstarted.xml
===================================================================
<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 a nice comeback next time one of those tedious Ruby guys
starts giving you a hard time 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 only works for people who want to use
Seam with EJB 3.0 in JBoss AS. Future versions will support other
deployment environments.
</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. Which means it is
easy to customize if you need to.
</para>
<section>
<title>Before you start</title>
<para>
Make sure you have recent versions of Eclipse, the JBoss IDE plugin
for Eclipse and the TestNG plugin for Eclipse along with JBoss AS 4.0.5
and Ant 1.6 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>
</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>
<programlisting>cd jboss-seam-1.1.x
seam setup</programlisting>
<para>
And you will be prompted for the needed information:
</para>
<programlisting><![CDATA[C:\Projects\jboss-seam>seam setup
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml
setup:
[echo] Welcome to seam-gen :-)
[input] Enter your Java project workspace [C:/Projects]
[input] Enter your JBoss home directory [C:/Program Files/jboss-4.0.5.GA]
[input] Enter the project name [myproject]
helloworld
[input] Enter the Java package name for your session beans [com.mydomain.helloworld]
org.jboss.helloworld
[input] Enter the Java package name for your entity beans [org.jboss.helloworld]
[input] Enter the Java package name for your test cases [org.jboss.helloworld.test]
[input] What kind of database are you using? [hsql] (hsql,mysql,oracle,postgres,mssql,db2,sybase,)
mysql
[input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect]
[input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar]
../../mysql-connector.jar
[input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver]
[input] Enter the JDBC URL for your database [jdbc:mysql:///test]
[input] Enter database username [sa]
gavin
[input] Enter database password []
[input] Are you working with tables that already exist in the database? [n] (y,n,)
y
[propertyfile] Creating new property file: C:\Projects\jboss-seam\seam-gen\build.properties
[echo] Installing JDBC driver jar to JBoss server
[echo] Type 'seam new-project' to create the new project
BUILD SUCCESSFUL
Total time: 1 minute 17 seconds
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 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>
<programlisting>seam new-project</programlisting>
<programlisting><![CDATA[C:\Projects\jboss-seam>seam new-project
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml
validate-workspace:
validate-project:
copy-lib:
[echo] Copying project jars ...
[copy] Copying 32 files to C:\Projects\helloworld\lib
[copy] Copying 9 files to C:\Projects\helloworld\embedded-ejb
file-copy-wtp:
file-copy:
[echo] Copying project resources ...
[copy] Copying 12 files to C:\Projects\helloworld\resources
[copy] Copying 1 file to C:\Projects\helloworld\resources
[copy] Copying 5 files to C:\Projects\helloworld\view
[copy] Copying 5 files to C:\Projects\helloworld
[mkdir] Created dir: C:\Projects\helloworld\src
new-project:
[echo] A new Seam project was created in the C:/Projects directory
[echo] Add the project from inside Eclipse (or type 'seam explode') and go to http://localhost:
8080/helloworld
BUILD SUCCESSFUL
Total time: 7 seconds
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... -> Java Project</literal>. 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>
</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>
<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>
<programlisting><![CDATA[C:\Projects\jboss-seam>seam new-action ping
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml
validate-workspace:
validate-project:
action-input:
[input] Enter the Seam component name
ping
[input] Enter the local interface name [Ping]
[input] Enter the bean class name [PingBean]
[input] Enter the action method name [ping]
[input] Enter the page name [ping]
setup-filters:
new-action:
[echo] Creating a new stateless session bean component with an action method
[copy] Copying 1 file to C:\Projects\hello\src\com\hello
[copy] Copying 1 file to C:\Projects\hello\src\com\hello
[copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
[copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
[copy] Copying 1 file to C:\Projects\hello\view
[echo] Type 'seam restart' and go to http://localhost:8080/helloworld/ping.seam
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. <emphasis>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. Finally, locate the <literal>PingTest.xml</literal>
file in the test package and run the integration tests using the TestNG plugin.
</para>
</section>
<section>
<title>Creating a form with an action</title>
<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
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml
validate-workspace:
validate-project:
action-input:
[input] Enter the Seam component name
hello
[input] Enter the local interface name [Hello]
[input] Enter the bean class name [HelloBean]
[input] Enter the action method name [hello]
[input] Enter the page name [hello]
setup-filters:
new-form:
[echo] Creating a new stateful session bean component with an action method
[copy] Copying 1 file to C:\Projects\hello\src\com\hello
[copy] Copying 1 file to C:\Projects\hello\src\com\hello
[copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
[copy] Copying 1 file to C:\Projects\hello\view
[copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
[echo] Type 'seam restart' and go to http://localhost:8080/hello/hello.seam
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>
</section>
<section>
<title>Generating an application from an existing database</title>
<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>
<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 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>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list