From seam-commits at lists.jboss.org Tue Sep 23 11:19:02 2008 Content-Type: multipart/mixed; boundary="===============4691734823416615461==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r9119 - trunk/doc/Seam_Reference_Guide/en-US. Date: Tue, 23 Sep 2008 11:19:02 -0400 Message-ID: --===============4691734823416615461== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: manaRH Date: 2008-09-23 11:19:02 -0400 (Tue, 23 Sep 2008) New Revision: 9119 Added: trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml Modified: trunk/doc/Seam_Reference_Guide/en-US/Author_Group.xml Log: Added Glassfish chapter Modified: trunk/doc/Seam_Reference_Guide/en-US/Author_Group.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/doc/Seam_Reference_Guide/en-US/Author_Group.xml 2008-09-23 14:51:= 16 UTC (rev 9118) +++ trunk/doc/Seam_Reference_Guide/en-US/Author_Group.xml 2008-09-23 15:19:= 02 UTC (rev 9119) @@ -64,6 +64,10 @@ Jacob Orshalick + + Marek + Novotny + James Cobb Added: trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml = (rev 0) +++ trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml 2008-09-23 15:19:02 = UTC (rev 9119) @@ -0,0 +1,917 @@ + + + Seam on Glassfish application server + + Glassfish is an open source application server which + fully implements + Java EE 5. The latest stable release is v2 UR2. + + 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. + +
+ Glassfish environment and deployment information + + + Glassfish is a open source project and its installation + is very + easy. This section will detail the exact server versions used and + installation tips. + +
+ Installation version and tips + + + All of the examples and information in this chapter are based on + the the latest version of Glassfish at the time of this writing. + + + + + Glassfish v2 UR2 - download page + + + + + + + After downloading suitable jar file with Glassfish, install it by + writing on command line in case of linux version: + java -Xmx256m -jar + glassfish-installer-v2ur2-b04-linux.jar + + + + After installing, setup glassfish, the following command creates + Glassfish server domain: + cd glassfish; ant -f setup.xml + The created domain name is domain1. + + + + Start the embedded JavaDB server: + bin/asadmin start-database + + This is default embedded database server in Glassfish. + + + + Start the Glassfish server domain1: + bin/asadmin start-domain domain1 + + + + + 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 + glassfish/domains/domain1/autodeploy + + for quick + automatic deployment. + + + + Stopping the server and database can be done by the following + command: + bin/asadmin stop-domain domain1; + bin/asadmin stop-database + +
+
+ +
+ + The + <literal>jee5/booking</literal> + example + + + + The + jee5/booking + 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 + $SEAM_DIST/examples/jee5/booking + + directory. + + +
+ Deploying the application to Glassfish + + We will deploy the application on Glassfish with using of + Glassfish's administration console. + + + The steps below are for the Glassfish version stated above. + + + + Log in to the administration console + http://localhost:4848 + + + + + + + Access the + Enterprise Applications + in the + menu option under the + Applications + left side + menu. + + + + + + At the top of the + Enterprise Application + table select + Deploy + . Below are installation + wizard pages and what needs to done on each: + + + + Preparing for the application + installation + + + + Browse to the + examples/jee5/booking/dist/jboss-seam-jee5.ear + + file using the file upload widget. + + + + + + Select the + OK + button. + + + + + + + + + + + + You can now access the application at + http://localhost:8081/seam-jee5/ + + . + + + + +
+
+ +
+ + The + <literal>jpa</literal> + booking example + + + This is the Hotel Booking example implemented in Seam POJOs + and + using Hibernate JPA with JPA transactions. It does not require EJB3 + support to run on application server. + + The example already has a break-out of configurations and + build + scripts for many of the common containers including Glassfish. + + First thing we are going to do is build and deploy that + example. + +
+ + Building the + <literal>jpa</literal> + example + + + + Building it only requires running the correct ant command: + ant glassfish + This will create + container specific distribution and exploded archive directories with + the + glassfish + suffix. + +
+ +
+ + Deploying the + <literal>jpa</literal> + example + + + + This is very similar to the + jee5 + example at + + . + + + + + + Log in to the administration console + http://localhost:4848 + + + + + + + Access the + Web Applications + in the menu + option under the + Applications + left side menu. + + + + Preparing for the application + installation + + + + Browse to the + examples/jpa/dist-glassfish/jboss-seam-jpa.war + + file using the file upload widget. + + + + + + Select the + OK + button. + + + + + + + + + You can now access the application at + http://localhost:8081/jboss-seam-jpa/ + + . + + + + + + + + + Using Derby instead of Hypersonic SQL DB + + 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 + examples/jpa/resources-glassfish/WEB-INF/classes/GlassfishDerbyDialect= .class + 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. + +
+ +
+ What's different for Glassfish v2 UR2 + + The differences between the JPA examples that deploys to + JBoss 4.2 + and Glassfish v2 UR2. Expected differences are in persistence related + configurations. + + + + + Configuration file changes + + + + META-INF/persistence.xml + + =E2=80=94 the main + changes here are for the datasource JNDI path, switching to + the Glassfish transaction manager look up class, and changing + the hibernate dialect to be + GlassfishDerbyDialect + . + + + + + + WEB-INF/classes/GlassfishDerbyDialect.class + + =E2=80=94 this class is needed for the hibernate dialect + change to + GlassfishDerbyDialect + + + + + + import.sql + =E2=80=94 either for the dialect + or Derby DB the + ID + column can not be + populated by this file and was removed. + + + + + + +
+
+ +
+ + Deploying an application generated by + <literal>seam-gen</literal> + on Glassfish v2 UR2 + + + + seam-gen + 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 + seam-gen + 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 abo= ve + in + + there is easy to deploy on + glassfish either EJB3 or Seam POJOs based application + + +
+ + Running + <literal>seam-gen</literal> + Setup + + + + The first step is setting up + seam-gen + to + construct the base project. There are several choices made below, + specifically the datasource and hibernate values that we will adjust + once the project is created. + + + + ./seam setup + Buildfile: build.xml + + 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] + + [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, w= ine, + 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] 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, or= acle, + 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 filesystem path to the JDBC driver jar + [../lib/hsqldb.jar] [../lib/hsqldb.jar] + + [input] Enter JDBC driver class for your database [org.hsqldb.jdbcDriv= er] + [org.hsqldb.jdbcDriver] + + [input] Enter the JDBC URL for your database [jdbc:hsqldb:.] + [jdbc:hsqldb:.] + + [input] Enter database username [sa] [sa] + + [input] Enter database password [] [] + + [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] 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]) + + [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 + + + + Type + ./seam new-project + to create your project + and + cd /home/mnovotny/projects/seamgen_example + to + the newly created structure. + +
+ +
+ Changes needed for deployment to Glassfish + + We now need to make some changes to the generated project. + + +
+ Configuration file changes + + + + + resources/META-INF/persistence-dev.xml + + + + + + + + Alter the + jta-data-source + to be + jdbc/__default + . We are going to be + using the integrated Glassfish Derby DB. + + + + + + Add or change the properties below. These are + described in detail at + + : + + + +<property name=3D"hibernate.dialect" value=3D"GlassfishDerbyDialect"/&g= t; +<property name=3D"hibernate.hbm2ddl.auto" value=3D"update"/> +<property name=3D"hibernate.show_sql" value=3D"true"/> +<property name=3D"hibernate.format_sql" value=3D"true"/> +<property name=3D"hibernate.cache.provider_class" = + value=3D"org.hibernate.cache.HashtableCacheProvider"/> +<property name=3D"hibernate.transaction.manager_lookup_class" = + value=3D"org.hibernate.transaction.SunONETransactionManagerLooku= p"/> + + + + You'll need to alter + persistence-prod.xml as well if you w= ant + to deploy to Glassfish using the prod profile. + + + + + + + resources/GlassfishDerbyDialect.class= + + + As with other examples we need to include this class f= or + DB support. It can be copied from the jpa + example into the seamgen_example/resources + directory. +cp $SEAM_DIST/examples/jpa/resources-glassfish/WEB-INF/classes/GlassfishDe= rbyDialect.class + ./resources + + + + + resources/META-INF/jboss-app.xml + + + You can delete this file as we aren't deploying to JBo= ss + AS ( jboss-app.xml is used to enable + classloading isolation in JBoss AS) + + + + + resources/*-ds.xml + + + You can delete these file as we aren't deploying to JB= oss + AS (these files define data sources in JBoss AS, we are using + Glassfish's default data source) + + + + + resources/WEB-INF/components.xml + + + + + Enable container managed transaction integration -= add + the <transaction:ejb-transaction /> + component, and it's namespace declaration + + xmlns:transaction=3D"http://jboss.com/products/seam/tran= saction" + + + + + Alter the jndi-pattern to + java:comp/env/seamgen_example/#{ejbName}/local + + + + + + + resources/WEB-INF/web.xml + + + As with the jee5/booking + example we need to add EJB references to the web.xml. = These + references require the empty + local-home to flag them for + Glassfish to perform the proper binding. + = + = + = + seamgen_example/AuthenticatorAction = = + Session = + + org.jboss.seam.tutorial.glassfish.action.Authenticator = + + = + + seamgen_example/EjbSynchronizations = + Session + + org.jboss.seam.transaction.LocalEjbSynchronizations + ]]> + + + +
+ +
+ Creating the <literal>AuthenticatorAction</literal> EJB</ti= tle> + + <para>We want to take the existing <literal>Authenticator</literal> + Seam POJO component and create an EJB3 out of it.</para> + + <orderedlist> + <listitem> + <itemizedlist> + <listitem> + <para>Rename the class to + <literal>AuthenticatorAction</literal></para> + </listitem> + + <listitem> + <para>Add the <literal>@Stateless</literal> annotation to = the + new <literal>AuthenticatorAction</literal> class.</para> + </listitem> + + <listitem> + <para>Create an interface called + <literal>Authenticator</literal> which + <literal>AuthenticatorAction</literal> implements (EJB3 + requires session beans to have a local interface). Annotate + the interface with <literal>@Local</literal> , and add a + single method with same signature as the + <literal>authenticate</literal> in + <literal>AuthenticatorAction</literal> .</para> + </listitem> + </itemizedlist> + + <programlisting role=3D"JAVA"> +(a)Name("authenticator") @Stateless = +public class AuthenticatorAction implements Authenticator {</programlistin= g> + + <programlisting role=3D"JAVA"> +(a)Local = +public interface Authenticator { = + public boolean authenticate(); = +}</programlisting> + </listitem> + + <listitem> + <para>We've already added its reference to the + <literal>web.xml</literal> file so are good to go.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>Extra jar dependencies and other changes to the + <literal>build.xml</literal> + + This application has similar requirements as the + jee5/booking example. + + + + Change the default target to archive = (we + aren't going to cover automatic deployment to Websphere). + + +<project name=3D"seamgen_example" default=3D"archive" basedir=3D".">= + + + + Websphere looks for the drools + /security.drl file in the root of the + war file instead of the root of the + seamgen_example.jar so we need to have the + build.xml move it to the correct location at + build time. The following must be added at the top of the + <target name=3D"war" depends=3D"compile" + description=3D"Build the distribution .war file"> + target. + + +<copy todir=3D"${war.dir}"> + <fileset dir=3D"${basedir}/resources" > + <include name=3D"*.drl" /> + </fileset> +</copy> + = + + + We need to get the + GlassfishDerbyDialect.class into our + application jar. To do that find the jar ta= sk + and modify the top of it so that it looks like this: + + +<target name=3D"jar" depends=3D"compile,copyclasses" = + description=3D"Build the distribution .jar file"> + <copy todir=3D"${jar.dir}"> + <fileset dir=3D"${basedir}/resources"> + <include name=3D"seam.properties" /> + <include name=3D"*.drl" /> + <include name=3D"GlassfishDerbyDialect.class" /> + </fileset> + </copy> +... + + + + Next we need to get the jboss-seam.jar + into the base of the EAR file. For deployme= nt + Glassfish requires this jar to be in both the + /lib directory and at the base of the + EAR. You must add the following to the + archive task: + + +<fileset dir=3D"${lib.dir}"> + <include name=3D"jboss-seam.jar" /> +</fileset> + + So that the whole archive task looks + like: + + +<target name=3D"archive" depends=3D"jar,war,ear" = + description=3D"Package the archives"> + <jar jarfile=3D"${dist.dir}/${project.name}.jar" basedir=3D"${jar.di= r}"/> + <jar jarfile=3D"${dist.dir}/${project.name}.war" basedir=3D"${war.di= r}"/> + <jar jarfile=3D"${dist.dir}/${project.name}.ear"> + <fileset dir=3D"${ear.dir}"/> + <fileset dir=3D"${dist.dir}"> + <include name=3D"${project.name}.jar"/> + <include name=3D"${project.name}.war"/> + </fileset> + <fileset dir=3D"${lib.dir}"> + <include name=3D"jboss-seam.jar" /> + </fileset> + </jar> +</target> + + + Now we need to get extra jars into the + build.xml. Look for the <fileset + dir=3D"${basedir}"> section of the task below. Ad= d the + new includes at the bottom of the fileset. + + +<target name=3D"ear" description=3D"Build the EAR"> + <copy todir=3D"${ear.dir}"> + <fileset dir=3D"${basedir}/resources"> + <include name=3D"*jpdl.xml" /> + <include name=3D"*hibernate.cfg.xml" /> + <include name=3D"jbpm.cfg.xml" /> + </fileset> + <fileset dir=3D"${lib.dir}"> + <include name=3D"jboss-seam.jar" /> + </fileset> + <fileset dir=3D"${basedir}"> + <include name=3D"lib/jbpm*.jar" /> + <include name=3D"lib/jboss-el.jar" /> + <include name=3D"lib/drools-*.jar"/> + <include name=3D"lib/core.jar"/> + <include name=3D"lib/janino*.jar"/> + <include name=3D"lib/antlr-*.jar"/> + <include name=3D"lib/mvel*.jar"/> + <include name=3D"lib/richfaces-api*.jar" /> + </fileset> + </copy> + <copy todir=3D"${ear.dir}/META-INF"> + <fileset dir=3D"${basedir}/resources/META-INF"> + <include name=3D"application.xml" /> + <include name=3D"jboss-app.xml" /> + </fileset> + </copy> +</target> + + + + Add Hibernate dependencies + + + <!-- Hibernate and deps --> + <include name=3D"lib/hibernate.jar"/> + <include name=3D"lib/hibernate-commons-annotations.jar"/> + <include name=3D"lib/hibernate-annotations.jar"/> + <include name=3D"lib/hibernate-entitymanager.jar"/> + <include name=3D"lib/hibernate-validator.jar"/> + <include name=3D"lib/jboss-common-core.jar" /> + + + + Add JSF dependencies. You will need to copy the + el-ri.jar from the + $SEAM_DIST/lib directory. + + + <!-- jsf libs --> + <include name=3D"lib/jsf-api.jar" /> + <include name=3D"lib/jsf-impl.jar" /> + <include name=3D"lib/el-api.jar" /> + <include name=3D"lib/el-ri.jar"/> + + + + Add third party dependencies. + + + <!-- 3rd party and supporting jars --> + <include name=3D"lib/javassist.jar"/> + <include name=3D"lib/dom4j.jar" /> + <include name=3D"lib/concurrent.jar" /> + <include name=3D"lib/cglib.jar"/> + <include name=3D"lib/asm.jar"/> + <include name=3D"lib/antlr.jar" /> + <include name=3D"lib/commons-logging.jar" /> + <include name=3D"lib/commons-collections.jar" /> + = + + + You should end up with something like: + + +<fileset dir=3D"${basedir}"> + + <include name=3D"lib/jbpm*.jar" /> + <include name=3D"lib/jboss-el.jar" /> + <include name=3D"lib/drools-*.jar"/> + <include name=3D"lib/core.jar"/> + <include name=3D"lib/janino*.jar"/> + <include name=3D"lib/antlr-*.jar"/> + <include name=3D"lib/mvel*.jar"/> + <include name=3D"lib/richfaces-api*.jar" /> + = + <!-- Hibernate and deps --> + <include name=3D"lib/hibernate.jar"/> + <include name=3D"lib/hibernate-commons-annotations.jar"/> + <include name=3D"lib/hibernate-annotations.jar"/> + <include name=3D"lib/hibernate-entitymanager.jar"/> + <include name=3D"lib/hibernate-validator.jar"/> + <include name=3D"lib/jboss-common-core.jar" /> + = + <!-- jsf libs --> + <include name=3D"lib/jsf-api.jar" /> + <include name=3D"lib/jsf-impl.jar" /> + <include name=3D"lib/el-api.jar" /> + <include name=3D"lib/el-ri.jar"/> + = + <!-- 3rd party and supporting jars --> + <include name=3D"lib/javassist.jar"/> + <include name=3D"lib/dom4j.jar" /> + <include name=3D"lib/concurrent.jar" /> + <include name=3D"lib/cglib.jar"/> + <include name=3D"lib/asm.jar"/> + <include name=3D"lib/antlr.jar" /> + <include name=3D"lib/commons-logging.jar" /> + <include name=3D"lib/commons-collections.jar" /> + = +</fileset> + + +
+ +
+ Building and deploying the seam-gen'd application to + Glassfish + + + + Build your application by calling ant= in + the base directory of your project (ex. + /projects/seamgen-example ). The target of = the + build will be dist/seamgen-example.ear . + + + + To deploy the application follow the instructions here : + but use references = to + this project seamgen-example instead of + jboss-seam-jee5. + + + + Checkout the app at: + http://localhost:8081/seamgen_example/ + + +
+
+
+ \ No newline at end of file Property changes on: trunk/doc/Seam_Reference_Guide/en-US/Glassfish.xml ___________________________________________________________________ Name: svn:executable + * Name: svn:mime-type + text/plain --===============4691734823416615461==--