Author: pete.muir(a)jboss.org Date: 2008-10-06 14:57:08 -0400 (Mon, 06 Oct 2008) New Revision: 9211 Modified: trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml Log: Edits Modified: trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml =================================================================== --- trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml 2008-10-06 18:08:39 UTC (rev 9210) +++ trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml 2008-10-06 18:57:08 UTC (rev 9211) @@ -1,92 +1,85 @@ <?xml version="1.0" encoding="UTF-8"?> <chapter id="glassfish"> - <title>Seam on Glassfish application server</title> + <title>Seam on GlassFish application server</title> <para> - Glassfish is an open source application server which fully implements Java + GlassFish is an open source application server which fully implements Java EE 5. The latest stable release is v2 UR2. </para> <para> - First we will go over some basic information about the Glassfish - environment that we used for these examples. We will go over the details - of those steps with the jee5 example. We will also deploy the JPA example - application. Finally we show customizing of seam-gen's generated - application. + First, we'll discuss the GlassFish environment. Then we will go over the + how you deploy the jee5 example. Next, we will deploy the JPA example + application. Finally we show how to get a seam-gen's generated + application running on GlassFish. </para> <section> - <title>Glassfish environment and deployment information</title> + <title>GlassFish environment and deployment information</title> - <para> - Glassfish is a open source project and its installation is very easy. - This section will detail the exact server versions used and - installation tips. - </para> - <section> - <title>Installation version and tips</title> + <title>Installation</title> <para> All of the examples and information in this chapter are based on the - the latest version of Glassfish at the time of this writing. + the latest version of GlassFish at the time of this writing. <itemizedlist> <listitem> <para> <ulink url="https://glassfish.dev.java.net/downloads/v2ur2-b04.html"> - Glassfish v2 UR2 - download page</ulink> + GlassFish v2 UR2 - download page</ulink> </para> </listitem> </itemizedlist> </para> <para> - After downloading suitable jar file with Glassfish, install it by - writing on command line in case of linux version: + After downloading GlassFish, install it: </para> <programlisting>$ java -Xmx256m -jar glassfish-installer-v2ur2-b04-linux.jar</programlisting> <para> - After installing, setup glassfish, the following command creates - Glassfish server domain: + After installing, setup GlassFish: </para> <programlisting>$ cd glassfish; ant -f setup.xml</programlisting> <para> - The created domain name is domain1. + The created domain's name is <literal>domain1</literal>. </para> <para> - Start the embedded JavaDB server: + Next, we start the embedded JavaDB server: </para> <programlisting>$ bin/asadmin start-database</programlisting> - <para> - This is default embedded database server in Glassfish. - </para> + <note> + <para> + JavaDB is an embedded database that is included with GlassFish, + just as HSQLDB is included in JBoss AS. + </para> + </note> <para> - Start the Glassfish server domain1: + Now, start the GlassFish server: </para> <programlisting>$ bin/asadmin start-domain domain1</programlisting> <para> - The deployment and configuration is available at the Web - Administration console at http://localhost:4848/. Access the web - admin console with default username/password: admin/adminadmin. You - can also copy EAR/WAR file to - <literal>glassfish/domains/domain1/autodeploy</literal> - for quick automatic deployment. + The web adminstration console is available at <literal>http://localhost:4848/</literal>. + You can access the web admin console with the default username + (<literal>admin</literal>) and password (<literal>adminadmin</literal>). + Alternatively, you could copy EAR/WAR file to + <literal>glassfish/domains/domain1/autodeploy</literal> to deploy + it. </para> <para> - Stopping the server and database can be done by the following - command: + You can stop the server and database using: </para> <programlisting>$ bin/asadmin stop-domain domain1; bin/asadmin stop-database</programlisting> @@ -99,24 +92,23 @@ <para> The <literal>jee5/booking</literal> example is based on the Hotel Booking example (which runs on JBoss AS). Out of the box it is also - designed to run on Glassfish. It is located in the - <literal>$SEAM_DIST/examples/jee5/booking</literal> directory. + designed to run on GlassFish. It is located in + <literal>$SEAM_DIST/examples/jee5/booking</literal>. </para> <section id="jee5-glassfish-deploy"> - <title>Deploying the application to Glassfish</title> + <title>Deploying the application to GlassFish</title> <para> - We will deploy the application on Glassfish with using of - Glassfish's administration console. + We will deploy the application on GlassFish using the GlassFish + admin console. </para> <orderedlist> <listitem> <para> - Log in to the administration console: + Log in to the admin console at <literal>http://localhost:4848</literal> </para> - <programlisting>http://localhost:4848</programlisting> </listitem> <listitem> <para> @@ -128,8 +120,8 @@ <listitem> <para> At the top of the <literal>Enterprise Application</literal> - table select <literal>Deploy</literal>. Below are installation - wizard pages and what needs to done on each: + table select <literal>Deploy</literal>. Follow through the + wizard, using these hints: </para> <itemizedlist> <listitem> @@ -139,8 +131,7 @@ <itemizedlist> <listitem> <para> - Browse to the <literal>examples/jee5/booking/dist/jboss-seam-jee5.ear</literal> - file using the file upload widget. + Browse to <literal>examples/jee5/booking/dist/jboss-seam-jee5.ear</literal>. </para> </listitem> <listitem> @@ -173,25 +164,21 @@ <para> The example already has a break-out of configurations and build scripts - for many of the common containers including Glassfish. + for many of the common containers including GlassFish. </para> - <para> - First thing we are going to do is build and deploy that example. - </para> - <section> <title>Building the <literal>jpa</literal> example</title> <para> - Building it only requires running the correct ant command: + To build the example, use the <literal>glassfish</literal> target: </para> <programlisting>$ ant glassfish</programlisting> <para> - This will create container specific distribution and exploded - archive directories with the <literal>glassfish</literal> suffix. + This will create the container specific <literal>dist-glassfish</literal> + and <literal>exploded-archives-glasfish</literal> directories. </para> </section> @@ -226,8 +213,7 @@ <itemizedlist> <listitem> <para> - Browse to the <literal>examples/jpa/dist-glassfish/jboss-seam-jpa.war</literal> - file using the file upload widget. + Browse to <literal>examples/jpa/dist-glassfish/jboss-seam-jpa.war</literal>. </para> </listitem> <listitem> @@ -250,26 +236,18 @@ <note> <title>Using Derby instead of Hypersonic SQL DB</title> - In order for the app to work out of the box with Glassfish, we have - used the Derby (i.e., Java DB) database in Glassfish. However, we - strongly recommend you to use a non-Derby data source (e.g., HSQL is - a much better embeded DB) if possible. The - <literal>examples/jpa/resources-glassfish/WEB-INF/classes/GlassfishDerbyDialect.class</literal> - is a special hack to get around a Derby bug in Glassfish server. You - must use it as your Hibernate dialect if you use Derby with - Glassfish. + In order for the app to work out of the box with GlassFish, we have + used the Derby (aka JavaDB) database in GlassFish. However, we + strongly recommend that you use another database (e.g. HSQL). + <literal>examples/jpa/resources-glassfish/WEB-INF/classes/GlassFishDerbyDialect.class</literal> + is a hack to get around a Derby bug in GlassFish server. You must + use it as your Hibernate dialect if you use Derby with GlassFish. </note> </section> <section> - <title>What's different for Glassfish v2 UR2</title> + <title>What's different for GlassFish v2 UR2</title> - <para> - The differences between the JPA examples that deploys to JBoss 4.2 - and Glassfish v2 UR2. Expected differences are in persistence - related configurations. - </para> - <itemizedlist> <listitem> <para> @@ -279,17 +257,17 @@ <listitem> <para> <literal>META-INF/persistence.xml</literal> — the main - changes here are for the datasource JNDI path, switching - to the Glassfish transaction manager look up class, and + changes needed are the datasource JNDI, switching to the + GlassFish transaction manager lookup class, and changing the hibernate dialect to be - <literal>GlassfishDerbyDialect</literal>. + <literal>GlassFishDerbyDialect</literal>. </para> </listitem> <listitem> <para> - <literal>WEB-INF/classes/GlassfishDerbyDialect.class</literal> + <literal>WEB-INF/classes/GlassFishDerbyDialect.class</literal> — this class is needed for the Hibernate dialect change - to <literal>GlassfishDerbyDialect</literal> + to <literal>GlassFishDerbyDialect</literal> </para> </listitem> <listitem> @@ -306,16 +284,16 @@ </section> <section> - <title>Deploying an application generated by <literal>seam-gen</literal> on Glassfish v2 UR2</title> + <title>Deploying an application generated by <literal>seam-gen</literal> on GlassFish v2 UR2</title> <para> <literal>seam-gen</literal> is a very useful tool for developers to quickly get an application up and running, and provides a foundation to add your own functionality. Out of box <literal>seam-gen</literal> will produce applications configured to run on JBoss AS. These instructions - will show the steps needed to get it to run on Glassfish. As stated - above in <xref linkend="jee5-glassfish-section" /> there is easy to - deploy on glassfish either EJB3 or Seam POJOs based application. + will show the steps needed to get it to run on GlassFish. As stated + above in <xref linkend="jee5-glassfish-section" /> it's easy to deploy + either an EJB3 or a Seam POJOs application on Glassfish. </para> <section> @@ -328,91 +306,94 @@ once the project is created. </para> - <programlisting>$ ./seam setup Buildfile: build.xml + <programlisting><![CDATA[$ ./seam setup +Buildfile: build.xml - init: +init: - setup: [echo] Welcome to seam-gen :-) [input] Enter your Java - project workspace (the directory that contains your Seam projects) - [C:/Projects] [C:/Projects] /home/mnovotny/projects [input] Enter - your JBoss home directory [C:/Program Files/jboss-4.2.3.GA] - [C:/Program Files/jboss-4.2.3.GA] +setup: +[echo] Welcome to seam-gen :-) +[input] Enter your Java project workspace (the directory that contains your +Seam projects) [C:/Projects] [C:/Projects] +/projects +[input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.3.GA] +[C:/Program Files/jboss-4.2.3.GA] - [input] Enter the project name [myproject] [myproject] - seamgen_example [echo] Accepted project name as: seamgen_example - [input] Do you want to use ICEfaces instead of RichFaces [n] (y, - [n]) +[input] Enter the project name [myproject] [myproject] +seamgen_example +[echo] Accepted project name as: seamgen_example +[input] Do you want to use ICEfaces instead of RichFaces [n] (y, [n]) - [input] skipping input as property icefaces.home.new has already - been set. [input] Select a RichFaces skin [blueSky] ([blueSky], - classic, ruby, wine, deepMarine, emeraldTown, japanCherry, DEFAULT) +[input] skipping input as property icefaces.home.new has already +been set. +[input] Select a RichFaces skin [blueSky] ([blueSky], classic, ruby, wine, +deepMarine, emeraldTown, japanCherry, DEFAULT) - [input] Is this project deployed as an EAR (with EJB components) or - a WAR (with no EJB support) [ear] ([ear], war) +[input] Is this project deployed as an EAR (with EJB components) or a WAR +(with no EJB support) [ear] ([ear], war) - [input] Enter the Java package name for your session beans - [com.mydomain.seamgen_example] [com.mydomain.seamgen_example] - org.jboss.seam.tutorial.glassfish.action [input] Enter the Java - package name for your entity beans - [org.jboss.seam.tutorial.glassfish.action] - [org.jboss.seam.tutorial.glassfish.action] - org.jboss.seam.tutorial.glassfish.model [input] Enter the Java - package name for your test cases - [org.jboss.seam.tutorial.glassfish.action.test] - [org.jboss.seam.tutorial.glassfish.action.test] - org.jboss.seam.tutorial.glassfish.test [input] What kind of database - are you using? [hsql] ([hsql], mysql, oracle, postgres, mssql, db2, - sybase, enterprisedb, h2) +[input] Enter the Java package name for your session beans +[com.mydomain.seamgen_example] [com.mydomain.seamgen_example] +org.jboss.seam.tutorial.glassfish.action +[input] Enter the Java package name for your entity beans +[org.jboss.seam.tutorial.glassfish.action] +[org.jboss.seam.tutorial.glassfish.action] +org.jboss.seam.tutorial.glassfish.model +[input] Enter the Java package name for your test cases +[org.jboss.seam.tutorial.glassfish.action.test] +[org.jboss.seam.tutorial.glassfish.action.test] +org.jboss.seam.tutorial.glassfish.test +[input] What kind of database are you using? [hsql] ([hsql], mysql, oracle, +postgres, mssql, db2, sybase, enterprisedb, h2) - [input] Enter the Hibernate dialect for your database - [org.hibernate.dialect.HSQLDialect] - [org.hibernate.dialect.HSQLDialect] +[input] Enter the Hibernate dialect for your database +[org.hibernate.dialect.HSQLDialect] +[org.hibernate.dialect.HSQLDialect] - [input] Enter the filesystem path to the JDBC driver jar - [../lib/hsqldb.jar] [../lib/hsqldb.jar] +[input] Enter the filesystem path to the JDBC driver jar +[../lib/hsqldb.jar] [../lib/hsqldb.jar] - [input] Enter JDBC driver class for your database - [org.hsqldb.jdbcDriver] [org.hsqldb.jdbcDriver] +[input] Enter JDBC driver class for your database [org.hsqldb.jdbcDriver] +[org.hsqldb.jdbcDriver] - [input] Enter the JDBC URL for your database [jdbc:hsqldb:.] - [jdbc:hsqldb:.] +[input] Enter the JDBC URL for your database [jdbc:hsqldb:.] +[jdbc:hsqldb:.] - [input] Enter database username [sa] [sa] +[input] Enter database username [sa] [sa] - [input] Enter database password [] [] +[input] Enter database password [] [] - [input] Enter the database schema name (it is OK to leave this - blank) [] [] +[input] Enter the database schema name (it is OK to leave this blank) [] [] - [input] Enter the database catalog name (it is OK to leave this - blank) [] [] +[input] Enter the database catalog name (it is OK to leave this +blank) [] [] - [input] Are you working with tables that already exist in the - database? [n] (y, [n]) +[input] Are you working with tables that already exist in the database? [n] +(y, [n]) - [input] Do you want to drop and recreate the database tables and - data in import.sql each time you deploy? [n] (y, [n]) +[input] Do you want to drop and recreate the database tables and data in +import.sql each time you deploy? [n] (y, [n]) - [propertyfile] Creating new property file: - /home/mnovotny/workspaces/jboss/jboss-seam/seam-gen/build.properties - [echo] Installing JDBC driver jar to JBoss server [copy] Copying 1 - file to - /home/mnovotny/workspaces/jboss/jboss-seam/seam-gen/C:/Program - Files/jboss-4.2.3.GA/server/default/lib [echo] Type 'seam - create-project' to create the new project +[propertyfile] Creating new property file: +/home/mnovotny/workspaces/jboss/jboss-seam/seam-gen/build.properties +[echo] Installing JDBC driver jar to JBoss server +[copy] Copying 1 file to +/home/mnovotny/workspaces/jboss/jboss-seam/seam-gen/C:/Program +Files/jboss-4.2.3.GA/server/default/lib +[echo] Type 'seam create-project' to create the new project - BUILD SUCCESSFUL Total time: 4 minutes 5 seconds - </programlisting> +BUILD SUCCESSFUL +Total time: 4 minutes 5 seconds]]></programlisting> <para> Type <literal>$ ./seam new-project</literal> to create your project - and <literal>cd /home/mnovotny/projects/seamgen_example</literal> to + and then <literal>cd /projects/seamgen_example</literal> to the newly created structure. </para> </section> <section> - <title>Changes needed for deployment to Glassfish</title> + <title>Changes needed for deployment to GlassFish</title> <para> We now need to make some changes to the generated project. @@ -433,7 +414,7 @@ <para> Alter the <literal>jta-data-source</literal> to be <literal>jdbc/__default</literal>. We are going to - be using the integrated Glassfish Derby DB. + be using the integrated GlassFish Derby DB. </para> </listitem> <listitem> @@ -442,7 +423,7 @@ described in detail at <xref linkend="jee5-glassfish-section" />: </para> - <programlisting role="XML"><![CDATA[<property name="hibernate.dialect" value="GlassfishDerbyDialect"/> + <programlisting role="XML"><![CDATA[<property name="hibernate.dialect" value="GlassFishDerbyDialect"/> <property name="hibernate.hbm2ddl.auto" value="update"/> <property name="hibernate.show_sql" value="true"/> <property name="hibernate.format_sql" value="true"/> @@ -453,7 +434,7 @@ <para> You'll need to alter <literal>persistence-prod.xml</literal> as well if - you want to deploy to Glassfish using the prod + you want to deploy to GlassFish using the prod profile. </para> </listitem> @@ -462,7 +443,7 @@ </varlistentry> <varlistentry> <term> - <literal>resources/GlassfishDerbyDialect.class</literal> + <literal>resources/GlassFishDerbyDialect.class</literal> </term> <listitem> <para> @@ -472,7 +453,7 @@ <literal>seamgen_example/resources</literal> directory. </para> <programlisting>$ cp \ -$SEAM_DIST/examples/jpa/resources-glassfish/WEB-INF/classes/GlassfishDerbyDialect.class \ +$SEAM_DIST/examples/jpa/resources-glassfish/WEB-INF/classes/GlassFishDerbyDialect.class \ ./resources </programlisting> </listitem> @@ -497,7 +478,7 @@ <para> You can delete these file as we aren't deploying to JBoss AS (these files define data sources in JBoss AS, - we are using Glassfish's default data source) + we are using GlassFish's default data source) </para> </listitem> </varlistentry> @@ -533,7 +514,7 @@ As with the <literal>jee5/booking</literal> example we need to add EJB references to the web.xml. These references require the empty - <literal>local-home</literal> to flag them for Glassfish + <literal>local-home</literal> to flag them for GlassFish to perform the proper binding. </para> <programlisting role="XML"><![CDATA[<ejb-local-ref> @@ -607,7 +588,7 @@ <listitem> <para> We've already added its reference to the <literal>web.xml</literal> - file so are good to go. + file so we are good to go. </para> </listitem> </orderedlist> @@ -628,7 +609,7 @@ <listitem> <para> Change the default target to <literal>archive</literal> (we - aren't going to cover automatic deployment to Glassfish). + aren't going to cover automatic deployment to GlassFish). </para> <programlisting role="XML"><![CDATA[<project name="seamgen_example" default="archive" basedir=".">]]></programlisting> @@ -654,7 +635,7 @@ <listitem> <para> - We need to get the <literal>GlassfishDerbyDialect.class</literal> + We need to get the <literal>GlassFishDerbyDialect.class</literal> into our application jar. To do that find the <literal>jar</literal> task and modify the top of it so that it looks like this: </para> @@ -664,7 +645,7 @@ <fileset dir="${basedir}/resources"> <include name="seam.properties" /> <include name="*.drl" /> - <include name="GlassfishDerbyDialect.class" /> + <include name="GlassFishDerbyDialect.class" /> </fileset> </copy> ...]]></programlisting> @@ -674,7 +655,7 @@ <para> Next we need to get the <literal>jboss-seam.jar</literal> into the base of the <literal>EAR</literal> file. For - deployment Glassfish requires this jar to be in both the + deployment GlassFish requires this jar to be in both the <literal>/lib</literal> directory and at the base of the <literal>EAR</literal>. You must add the following to the <literal>archive</literal> task: @@ -825,7 +806,7 @@ </section> <section> - <title>Building and deploying the seam-gen'd application to Glassfish</title> + <title>Building and deploying the seam-gen'd application to GlassFish</title> <itemizedlist> <listitem>