Author: shane.bryzak(a)jboss.com Date: 2008-12-01 01:09:22 -0500 (Mon, 01 Dec 2008) New Revision: 9678 Removed: trunk/doc/Seam_Reference_Guide/en-US/Oc4j.xml Modified: trunk/doc/Seam_Reference_Guide/en-US/master.xml Log: JBSEAM-3713 Deleted: trunk/doc/Seam_Reference_Guide/en-US/Oc4j.xml =================================================================== --- trunk/doc/Seam_Reference_Guide/en-US/Oc4j.xml 2008-12-01 02:43:21 UTC (rev 9677) +++ trunk/doc/Seam_Reference_Guide/en-US/Oc4j.xml 2008-12-01 06:09:22 UTC (rev 9678) @@ -1,1168 +0,0 @@ -<chapter id="oc4j"> - <title>Seam on OC4J</title> - - <para> OC4J (Oracle Containers for Java) 11g (currently a "Technology - Preview" release) is Oracle's JEE5 application server. Seam application - can be deployed to OC4J, but require some additional configuration - changes, and dependencies. This chapter will show you exactly what must be - done. We will start by looking at the building and deploying the JEE5 Hotel - Booking example application which comes with Seam. Then we will deploy a - project generated by <literal>seam-gen</literal> . First a basic - <literal>seam-gen</literal> application with RichFaces ajax - components, and facelets. Then expand that application to include Seam - security with Drools, JPA provided with hibernate, and automatic CRUD - reverse engineering of a MySQL database. </para> - - <section id="oc4j-install-operation"> - <title>Installation and operation of OC4J</title> - <para> First we need to install the target container - OC4j. This chapter - requires you to use OC4J 11g Technology Preview (not OC4J 10g). You can - download OC4J 11g from <ulink - url="http://www.oracle.com/technology/tech/java/oc4j/11/"> - http://www.oracle.com/technology/tech/java/oc4j/11/ </ulink> - Below are instructions to install. launch, access, and shutdown the 11g - release. For further information on installing OC4J, consult the - <literal>readme.txt</literal> distributed with OC4J, or the OC4J - installation guide and release notes. - <orderedlist> - <listitem> - <para>Download and unzip OC4J</para> - </listitem> - <listitem> - <para> Make sure you have <literal>$JAVA_HOME</literal> and - <literal>$ORACLE_HOME</literal> set as environment - variables ( <literal>$ORACLE_HOME</literal> is the - directory to which you unzip OC4J). For further information - on installing OC4J, consult the - <literal>readme.txt</literal> distributed with OC4J - </para> - </listitem> - <listitem> - <para> Applications (ear/war) are deployed to the - <literal>$ORACLE_HOME/j2ee/home/applications</literal> - directory. </para> - <para> Note that OC4J does not support hot deployment by default. - This means every time you deploy the application you must - restart the server. </para> - </listitem> - <listitem> - <para> Start OC4J: <literal> $ORACLE_HOME/j2ee/home/java - -jar -XX:MaxPermSize=256M oc4j.jar </literal> </para> - <para> You must override the default PermGen memory settings - using above command. See <ulink - url="http://www.oracle.com/technology/tech/java/oc4j/11/oc4j-relnote... - OC4J release notes </ulink> for details. </para> - <para> You will be asked to set the admin password if this is the - first time you have started OC4J </para> - </listitem> - <listitem> - <para> Once deployed you can check out your applications at - <literal>http://localhost:8888/&lt;your-app-path&gt;</literal> - </para> - </listitem> - <listitem> - <para> You can stop the server by pressing - <literal>CTRL-C</literal> in the console on which the - server is running. </para> - </listitem> - </orderedlist> </para> - </section> - - <section> - <title> The <literal>jee5/booking</literal> example </title> - - <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 designed to - run on Glassfish, but it's easy to build it for OC4J. It is located in the - <literal>$SEAM_DIST/examples/jee5/booking</literal> directory. - </para> - - <section> - <title>Booking Example Dependencies</title> - - <para> First, lets look at the basic dependencies of the booking - example. Armed with this knowledge we can look at the extra - dependencies requirements that OC4J adds. </para> - - <para> We will show you how to get these dependencies into the - application in <xref linkend="oc4j-build-jee5"/> below. </para> - <section> - <title>Core Seam dependencies</title> - <itemizedlist> - <listitem> - <simpara><literal>jboss-seam.jar</literal> &#8212; We - declare this as an EJB3 module (why? well Seam needs to be - able to interact with container managed transactions; - this is implemented as an EJB3 Stateful Session Bean) - </simpara> - </listitem> - <listitem> - <simpara> <literal>jboss-el.jar</literal> </simpara> - </listitem> - <listitem> - <simpara><literal>jboss-seam-ui.jar</literal> &#8212; - Seam's JSF controls depend on Apache's - commons-beanutils</simpara> - </listitem> - <listitem> - <simpara> <literal>jboss-seam-debug.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> <literal>jsf-facelets.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> <literal>richfaces-api.jar</literal> , - <literal>richfaces-impl.jar</literal> and - <literal>richfaces-ui.jar</literal> &#8212; which - requires Apache commons-digester and - commons-beanutils </simpara> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Extra dependencies</title> - <itemizedlist> - <listitem> - <para> Hibernate &#8212; of course, we decided to use - Hibernate as the JPA provider (rather than TopLink - Essentials which ships with OC4J). </para> - <para> To use Hibernate as your JPA provider you need the - following jars: - <itemizedlist> - <listitem> - <simpara> <literal>hibernate.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>hibernate-annotations.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>hibernate-entitymanager.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>hibernate-validator.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>jboss-common-core.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>commons-logging.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>commons-collections.jar</literal> - </simpara> - </listitem> - </itemizedlist> </para> - </listitem> - <listitem> - <para> Third party jars &#8212; various jars needed for seam - and this example to run. - <itemizedlist> - <listitem> - <simpara> <literal>javaasist.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> <literal>dom4j.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> <literal>cglib.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> <literal>asm.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>commons-beanutils.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>commons-digester.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>concurrent.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara><literal>log4j.jar</literal> - &#8212; This can be left out if you are not going - to configure log4j. If it is packaged but not - configured logging will be hidden in oc4j. - </simpara> - </listitem> - </itemizedlist> </para> - </listitem> - <listitem> - <para> Extra OC4J jars &#8212; Running Seam on most - application servers (such as JBoss AS or Glassfish) you - only need to include the dependencies for those bits of - Seam you actually use (e.g. if you use Seam Text you need to - include ANTLR); but, on OC4J, due to its "interesting" - classloading you must always include them: - <itemizedlist> - <listitem> - <simpara> - <literal>hibernate-search.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>hibernate-common-annotations.jar</literal> - &#8212; needed for hibernate search - </simpara> - </listitem> - <listitem> - <simpara> <literal>lucene-core.jar</literal> - &#8212; needed for hibernate search - </simpara> - </listitem> - <listitem> - <simpara> <literal>antlr.jar</literal> - &#8212; needed for Seam Text </simpara> - </listitem> - <listitem> - <simpara> <literal>jbpm-jpdl.jar</literal> - &#8212; needed for Seam's JBPM </simpara> - </listitem> - <listitem> - <simpara> <literal>quartz.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> <literal>dbunit.jar</literal> - &#8212; needed for some testing classes - </simpara> - </listitem> - <listitem> - <simpara> - <literal>jboss-embedded-api.jar</literal> - &#8212; needed for some testing classes - </simpara> - </listitem> - <listitem> - <para> Drools &#8212; needed for Seam Security. We - aren't using Seam security with Drools, but - have to include it. Drools consists of 6 jars: - <itemizedlist> - <listitem> - <simpara> - <literal>drools-core.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>drools-compiler.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>janino.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>mvel141.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>core.jar</literal> - </simpara> - </listitem> - <listitem> - <simpara> - <literal>antlr-runtime.jar</literal> - </simpara> - </listitem> - </itemizedlist> Drools integration is not - used in the example. </para> - </listitem> - </itemizedlist> </para> - </listitem> - </itemizedlist> - </section> - </section> - - <section> - <title>Configuration file changes</title> - - <para>There are just a few changes to be made:</para> - <variablelist> - <varlistentry> - <term> <literal>web.xml</literal> - </term> - <listitem> - <para> You need to declare all your ejb's in the - <literal>web.xml</literal> . This is a silly - requirement of a number of JEE5 application servers - for - example OC4J and Glassfish. </para> - <para> This is already done in the example's web.xml file, - below is an example. </para> - - - <programlisting role="XML"><![CDATA[<ejb-local-ref> - <ejb-ref-name> - jboss-seam-jee5/AuthenticatorAction/local - </ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <local> - org.jboss.seam.example.booking.Authenticator - </local> - <ejb-link>AuthenticatorAction</ejb-link> -</ejb-local-ref>]]></programlisting> - </listitem> - </varlistentry> - <varlistentry> - <term> <literal>persistence.xml</literal> - </term> - <listitem> - <para> You need to provide the correct configuration for your - JPA implementation. We are using Hibernate and due to OC4J - bundling an old ANTLR, we need to use an alternative query - factory, we also want to use the OC4J transaction manager: - </para> - <para> For our example modify the - <literal>resources/META-INF/persistence.xml</literal> - file. Comment out the Glassfish properties and - un-comment the OC4J properties. </para> - - - <programlisting role="XML"><![CDATA[<property name="hibernate.dialect" - value="org.hibernate.dialect.HSQLDialect"/> -<property name="hibernate.query.factory_class" - value="org.hibernate.hql.classic.ClassicQueryTranslatorFactory"/> -<property name="hibernate.transaction.manager_lookup_class" - value="org.hibernate.transaction.OrionTransactionManagerLookup"/>]]></programlisting> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="oc4j-build-jee5"> - <title> Building the <literal>jee5/booking</literal> example - </title> - - <orderedlist> - <listitem> - <para> Modify the <literal>build.xml</literal> file in the - example: </para> - <itemizedlist> - <listitem> - <para> Un-comment the labeled OC4J-related library - properties. This will include all the extra - dependencies discussed above. </para> - <para>It should look like the following:</para> - - - <programlisting role="XML"><![CDATA[<!-- add libs for oc4j (eager classloading) --> -<property name="jbpm.lib" value="true"/> -<property name="drools.lib" value="true"/> -<property name="quartz.lib" value="true" /> -<property name="search.lib" value="true" /> -<property name="dbunit.lib" value="true" /> -<property name="jboss-embedded-api.lib" value="true" /> - ]]></programlisting> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para> Build the demo app by running <literal>ant</literal> in - the <literal>examples/jee5/booking</literal> - directory. The build target is - <literal>dist/jboss-seam-jee5.ear</literal> </para> - </listitem> - <listitem> - <para> Copy <literal>dist/jboss-seam-jee5.ear</literal> - following the instructions below. </para> - </listitem> - </orderedlist> - </section> - </section> - - <section id="oc4j-app-deploy"> - <title>Deploying the Seam application to OC4J</title> - <para> This mini-tutorial describes the (fairly tedious) steps required - to deploy a JEE 5 application to OC4J. It assumes you have already - downloaded and installed it following the instructions in <xref - linkend="oc4j-install-operation"/>. It also assumes you are - deploying the <literal>jee5/booking</literal> example, using the - embedded hsqldb database. To deploy another application you would need - to alter the datasource and application name. </para> - <orderedlist> - <listitem> - <para> Copy <literal>hsqldb.jar</literal> to OC4J shared library - directory: <literal> cp $SEAM_HOME/lib/hsqldb.jar - $ORACLE_HOME/j2ee/home/applib/ </literal> (OC4J doesn't - come with an embedded database so we decided to use HSQLDB) - </para> - </listitem> - <listitem> - <para> Edit the OC4J datasource file - <literal>$ORACLE_HOME/j2ee/home/config/data-sources.xml</literal> - and, inside <literal>&lt;data-sources&gt;</literal> , add - </para> - - - <programlisting role="XML"><![CDATA[<managed-data-source - connection-pool-name="jee5-connection-pool" - jndi-name="jdbc/__default" - name="jee5-managed-data-source" /> -<connection-pool name="jee5-connection-pool"> - <connection-factory - factory-class="org.hsqldb.jdbcDriver" - user="sa" - password="" - url="jdbc:hsqldb:." /> -</connection-pool>]]></programlisting> - - <para> The <literal>jndi-name</literal> is used as the - <literal>jta-data-source</literal> in - <literal>persistence.xml</literal> . </para> - </listitem> - <listitem> - <para> Edit - <literal>$ORACLE_HOME/j2ee/home/config/server.xml</literal> - and, inside <literal>&lt;application-server&gt;</literal> - , add </para> - - - <programlisting role="XML"><![CDATA[<application name="jboss-seam-jee5" - path="../../home/applications/jboss-seam-jee5.ear" - parent="default" - start="true" />]]></programlisting> - <para> To keep things simple use the same names as you used for - project. </para> - </listitem> - <listitem> - <para> Edit <literal> - $ORACLE_HOME/j2ee/home/config/default-web-site.xml - </literal> , and, inside - <literal>&lt;web-site&gt;</literal> , add </para> - - - <programlisting role="XML"><![CDATA[<web-app application="jboss-seam-jee5" - name="jboss-seam-jee5" - load-on-startup="true" - root="/seam-jee5" />]]></programlisting> - <para> The <literal>root</literal> is the context path you will put - into your web browser to access the application. </para> - </listitem> - <listitem> - <para> Copy the application to OC4J: <literal> cp - dist/jboss-seam-jee5.ear - $ORACLE_HOME/j2ee/home/applications/ </literal> </para> - </listitem> - <listitem> - <para> Start/stop OC4J following instructions in <xref - linkend="oc4j-install-operation"/> above. </para> - </listitem> - <listitem> - <para> Checkout the app at: - <literal>http://localhost:8888/seam-jee5</literal> - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title> Deploying an application created using - <literal>seam-gen</literal> to OC4J </title> - - <para> <literal>seam-gen</literal> is a great tool for developers that - can quickly get you up and running with a full Seam application. However - the project that it created is configured to run on JBoss AS. This means - there are some extra steps needed to have it execute on OC4j. The - following explanation assumes you are using the command line and a - simple text editor, but of course you can use your favorite IDE. - <literal>seam-gen</literal> projects come with support for Eclipse - and Netbeans. </para> - - <para> We will start by creating and deploying a pretty simple application - using <literal>seam-gen</literal> . Then we'll show you how easy it is - to use <literal>seam-gen</literal> and Hibernate Tools to reverse - engineer a database schema into a functional CRUD application. - <literal>seam-gen</literal> will create JPA entity beans, Seam - Application Framework components and JSF views for you. We will also add - Seam security using Drools. </para> - - <para> This tutorial uses MySQL (but of course you could use any database, - altering the SQL and datasources as appropriate); install, configure - and run MySQL, then create a database with some sample data. Don't forget - to also download the - <literal>mysql-connector-java-X.jar</literal> for jdbc support. - When setting up Seam security this tutorial will assume there is a table - named <literal>User</literal> with columns - <literal>username</literal> and <literal>password</literal> with - at least one entry. Beyond that you can set up any type of sample data and - tables you would like. </para> - - <section> - <title> Generating a basic <literal>seam-gen</literal> application - </title> - <para> First we need to tell the <literal>seam-gen</literal> what we - want, run <literal>./seam setup</literal> in the seam - distribution directory. Follow the settings example below based on - your system and setup (ex. use your database name instead of - <literal>oc4jexample</literal> ). </para> - - - <programlisting><![CDATA[> ./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/jbalunas/workspace - [input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.3.GA] -[C:/Program Files/jboss-4.2.3.GA] -/home/jbalunas/jboss/jboss-4.2.3.GA - [input] Enter the project name [myproject] [myproject] -oc4j_example - [echo] Accepted project name as: oc4j_example - [input] Select a RichFaces skin (not applicable if using ICEFaces) [blueSky] - ([blueSky], classic, ruby, wine, deepMarine, emeraldTown, sakura, 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. -oc4j_example] [com.mydomain.oc4j_example] -org.jboss.seam.tutorial.oc4j.action - [input] Enter the Java package name for your entity beans [org.jboss.seam. -tutorial.oc4j.action] [org.jboss.seam.tutorial.oc4j.action] -org.jboss.seam.tutorial.oc4j.model - [input] Enter the Java package name for your test cases [org.jboss.seam. -tutorial.oc4j.action.test] [org.jboss.seam.tutorial.oc4j.action.test] -org.jboss.seam.tutorial.oc4j.test - [input] What kind of database are you using? [hsql] ([hsql], mysql, oracle, - postgres, mssql, db2, sybase, enterprisedb, h2) -mysql - [input] Enter the Hibernate dialect for your database [org.hibernate. -dialect.MySQLDialect] [org.hibernate.dialect.MySQLDialect] - - [input] Enter the filesystem path to the JDBC driver jar [/tmp/seam/lib/hsqldb.jar] -[/tmp/seam/lib/hsqldb.jar] -lib/mysql-connector.jar - [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver] -[com.mysql.jdbc.Driver] - - [input] Enter the JDBC URL for your database [jdbc:mysql:///test] -[jdbc:mysql:///test] -jdbc:mysql:///oc4jexample - [input] Enter database username [sa] [sa] -username - [input] Enter database password [] [] -password - [input] skipping input as property hibernate.default_schema.new has already -been set. - [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], ) -y - [input] Do you want to drop and recreate the database tables and data in -import.sql each time you deploy? [n] (y, [n], ) -n - [input] Enter your ICEfaces home directory (leave blank to omit ICEfaces) [] [] - -[propertyfile] Creating new property file: -/home/jbalunas/workspace/jboss-seam/seam-gen/build.properties - [echo] Installing JDBC driver jar to JBoss server - [copy] Copying 1 file to /home/jbalunas/jboss/jboss-4.2.3.GA/server/default/lib - [echo] Type 'seam create-project' to create the new project - -BUILD SUCCESSFUL]]></programlisting> - - <para> Type <literal>./seam new-project</literal> to create your - project and <literal>cd - /home/jbalunas/workspace/oc4j_example</literal> to the newly - created project. </para> - - </section> - <section> - <title>Changes needed for deployment to OC4J</title> - <para>We now need to make some changes to the generated project.</para> - <section> - <title>Configuration file changes</title> - <para>Let's start with the configuration files:</para> - <variablelist> - <varlistentry> - <term> <literal>build.xml</literal> - </term> - <listitem> - <itemizedlist> - <listitem> - <para>Change the default target to archive (we - aren't going to cover automatic deployment to - OC4J). - </para> - <programlisting role="XML"><![CDATA[<project name="oc4j_example" default="archive" basedir=".">]]></programlisting> - </listitem> - <listitem> - <para>OC4J looks for the drools file - <literal>/security.drl</literal> file in - the root of the <literal>war</literal> file - instead of the root of the - <literal>ear</literal> file so we need to have - the <literal>build.xml</literal> move it to - the correct location at build time. The - following must be added at the top of the - <literal> &lt;target name="war" - depends="compile" description="Build the - distribution .war file"&gt; </literal> - target. - </para> - - <programlisting role="XML"><![CDATA[<copy todir="${war.dir}"> - <fileset dir="${basedir}/resources" > - <include name="*.drl" /> - </fileset> - </copy>]]></programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>resources/META-INF/persistence-dev.xml</literal> - </term> - <listitem> - <itemizedlist> - <listitem> - <para> Alter the - <literal>jta-data-source</literal> to be - <literal>jdbc/__oc4jexample</literal> - (and use this as the - <literal>jndi-name</literal> when creating - the data source in - <literal>data-sources.xml</literal> later - during deployment). </para> - </listitem> - <listitem> - <para> Add the properties (described in - <literal>jee5/booking</literal> example): - </para> - - - <programlisting role="XML"><![CDATA[<property name="hibernate.query.factory_class" - value="org.hibernate.hql.classic.ClassicQueryTranslatorFactory" /> -<property name="hibernate.transaction.manager_lookup_class" - value="org.hibernate.transaction.OrionTransactionManagerLookup" /> -<property name="hibernate.transaction.flush_before_completion" - value="true"/> -<property name="hibernate.cache.provider_class" - value="org.hibernate.cache.HashtableCacheProvider"/>]]></programlisting> - </listitem> - <listitem> - <para> Remove the JBoss AS specific method of - exposing the EntityManagerFactory: </para> - - - <programlisting role="XML"><![CDATA[<property - name="jboss.entity.manager.factory.jndi.name" - value="java:/oc4j_exampleEntityManagerFactory">]]></programlisting> - </listitem> - <listitem> - <para> You'll need to alter - <literal>persistence-prod.xml</literal> - as well if you want to deploy to OC4J using the - prod profile. </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>resources/META-INF/jboss-app.xml</literal> - </term> - <listitem> - <para> You can delete this file as we aren't deploying to - JBoss AS ( <literal>jboss-app.xml</literal> is used - to enable classloading isolation in JBoss AS) </para> - </listitem> - </varlistentry> - <varlistentry> - <term> <literal>resources/*-ds.xml</literal> - </term> - <listitem> - <para> You can delete these file as we aren't deploying to - JBoss AS (these files define datasources in JBoss AS, - in OC4J you have to edit the master - <literal>data-sources.xml</literal> file) - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>resources/WEB-INF/components.xml</literal> - </term> - <listitem> - <itemizedlist> - <listitem> - <para> Enable container managed transaction - integration - add the <literal> - &lt;transaction:ejb-transaction /&gt; - </literal> component, and it's namespace - declaration <literal> - xmlns:transaction="http://jboss.com/products/seam/transaction" - </literal> </para> - </listitem> - <listitem> - <para> Alter the - <literal>jndi-pattern</literal> to - <literal> - java:comp/env/oc4j_example/#{ejbName}/local - </literal> </para> - </listitem> - <listitem> - <para> We want to use a Seam Managed Persistence - Context in our application. Unfortunately - OC4J doesn't expose the EntityManagerFactory - in JNDI, but Seam provides a built-in manager - component. To activate add the following - entry: </para> - - - <programlisting role="XML"><![CDATA[<persistence:entity-manager-factory - auto-create="true" - name="oc4jEntityManagerFactory" - persistence-unit-name="oc4j_example" />]]></programlisting> - <para> We then need to tell Seam to use it, so we alter - the - <literal>managed-persistence-context</literal> - injecting the Entity Manager Factory into the - existing element: </para> - - - <programlisting role="XML"><![CDATA[<persistence:managed-persistence-context - name="entityManager" - auto-create="true" - entity-manager-factory="#{oc4jEntityManagerFactory}" />]]> - </programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term> <literal>resources/WEB-INF/web.xml</literal> - </term> - <listitem> - <para> You must add the Seam container managed - transaction integration EJB entry below. Remember - for OC4j you need to declare all your EJBs here if you - modify the application further. </para> - - - <programlisting role="XML"><![CDATA[<ejb-local-ref> - <ejb-ref-name> - oc4j_example/EjbSynchronizations/local - </ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <local> - org.jboss.seam.transaction.LocalEjbSynchronizations - </local> - <ejb-link>EjbSynchronizations</ejb-link> -</ejb-local-ref>]]></programlisting> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>resources/META-INF/orion-application.xml</literal> - </term> - <listitem> - <itemizedlist> - <listitem> - <para> This is a file that you must create so that - RichFaces and Ajax4Jsf stylesheets will work - with OC4J. This file basically tells OC4J not - force its own inherited URL settings. </para> - - - <programlisting role="XML"><![CDATA[<?xml version = '1.0' encoding = 'utf-8'?> -<orion-application - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/ - orion-application-10_0.xsd" - schema-major-version="10" - schema-minor-version="0" - component-classification="internal"> - - <imported-shared-libraries> - <remove-inherited name="oracle.xml"/> - </imported-shared-libraries> -</orion-application>]]></programlisting> - </listitem> - <listitem> - <para> Now you need to tell the - <literal>build.xml</literal> file that it - needs to copy this file to the - <literal>ear</literal> archive. Find the - <literal> &lt;target name="ear" - description="Build the EAR"&gt; </literal> - target and modify the <literal> - &lt;copy todir="${ear.dir}/META-INF"&gt; - </literal> section to look like the following: - </para> - - - <programlisting role="XML"><![CDATA[<copy todir="${ear.dir}/META-INF"> - <fileset dir="${basedir}/resources/META-INF"> - <include name="application.xml" /> - <include name="orion-application.xml"/> - <include name="jboss-app.xml" /> - </fileset> - </copy>]]></programlisting> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </section> - <section> - <title>Extra jar dependencies</title> - <para> This application has similar requirements as the - <literal>jee5/booking</literal> example above. </para> - <para> The <literal>build.xml</literal> must be modified to add - the jars listed below to the generated archive files. Look for the - <literal>&lt;fileset dir="${basedir}"&gt;</literal> - section below and add the imports underneath the other libraries - being imported. </para> - - - <programlisting role="XML"><![CDATA[<target name="ear" description="Build the EAR"> - <copy todir="${ear.dir}"> - <fileset dir="${basedir}/resources"> - <include name="*jpdl.xml" /> - <include name="*hibernate.cfg.xml" /> - <include name="jbpm.cfg.xml" /> - <include name="*.drl" /> - </fileset> - <fileset dir="${lib.dir}"> - <include name="jboss-seam.jar" /> - </fileset> - <fileset dir="${basedir}"> - <include name="lib/jbpm*.jar" /> - <include name="lib/jboss-el.jar" /> - <include name="lib/drools-*.jar"/> - <include name="lib/janino*.jar"/> - <include name="lib/antlr-*.jar"/> - <include name="lib/mvel*.jar"/> - <include name="lib/richfaces-api*.jar" /> - </fileset> - </copy> - <copy todir="${ear.dir}/META-INF"> - <fileset dir="${basedir}/resources/META-INF"> - <include name="application.xml" /> - <include name="jboss-app.xml" /> - </fileset> - </copy> -</target>]]></programlisting> - <itemizedlist> - <listitem> - <para>Hibernate:</para> - - - <programlisting role="XML"><![CDATA[<include name="lib/hibernate.jar"/> -<include name="lib/hibernate-annotations.jar"/> -<include name="lib/hibernate-commons-annotations.jar"/> -<include name="lib/hibernate-entitymanager.jar"/> -<include name="lib/hibernate-search.jar"/> -<include name="lib/hibernate-validator.jar"/> -<include name="lib/commons-logging.jar"/> -<include name="lib/commons-collections.jar"/> -<include name="lib/jboss-common-core.jar"/>]]></programlisting> - </listitem> - <listitem> - <para> Drools &#8212; because we are using Drools to provide - Seam Security rules, we need to add in Eclipse JDT compiler - (you don't need this on JBoss AS; again this is due to OC4J's - classloading): </para> - - - <programlisting role="XML"><![CDATA[<include name="lib/core.jar"/>]]></programlisting> - </listitem> - <listitem> - <para> Third party jars &#8212; most of these are only needed - because of OC4J's classloading: </para> - - - <programlisting role="XML"><![CDATA[<include name="lib/javassist.jar"/> -<include name="lib/quartz.jar"/> -<include name="lib/dbunit.jar"/> -<include name="lib/jboss-embedded-api.jar"/> -<include name="lib/dom4j.jar"/> -<include name="lib/lucene-core.jar"/> -<include name="lib/cglib.jar"/> -<include name="lib/asm.jar"/> -<include name="lib/commons-beanutils.jar"/> -<include name="lib/commons-digester.jar"/> -<include name="lib/concurrent.jar"/> -<include name="lib/antlr.jar"/>]]></programlisting> - </listitem> - </itemizedlist> - - <para>You should end up with something like:</para> - - - <programlisting role="XML"><![CDATA[<fileset dir="${basedir}"> - <include name="lib/jbpm*.jar" /> - <include name="lib/jboss-el.jar" /> - <include name="lib/drools-*.jar"/> - <include name="lib/janino*.jar"/> - <include name="lib/antlr-*.jar"/> - <include name="lib/mvel*.jar"/> - <include name="lib/richfaces-api*.jar" /> - <include name="lib/hibernate.jar"/> - <include name="lib/hibernate-annotations.jar"/> - <include name="lib/hibernate-commons-annotations.jar"/> - <include name="lib/hibernate-entitymanager.jar"/> - <include name="lib/hibernate-search.jar"/> - <include name="lib/hibernate-validator.jar"/> - <include name="lib/commons-logging.jar"/> - <include name="lib/commons-collections.jar"/> - <include name="lib/jboss-common-core.jar"/> - <include name="lib/core.jar"/> - <include name="lib/javassist.jar"/> - <include name="lib/quartz.jar"/> - <include name="lib/dbunit.jar"/> - <include name="lib/jboss-embedded-api.jar"/> - <include name="lib/dom4j.jar"/> - <include name="lib/lucene-core.jar"/> - <include name="lib/cglib.jar"/> - <include name="lib/asm.jar"/> - <include name="lib/commons-beanutils.jar"/> - <include name="lib/commons-digester.jar"/> - <include name="lib/concurrent.jar"/> - <include name="lib/antlr.jar"/> -</fileset>]]></programlisting> - </section> - - </section> - <section> - <title> Building and deploying the seam-gen'd application to OC4J - </title> - <para> These instructions are very similar to the ones in <xref - linkend="oc4j-app-deploy"/> but with the correct references - for the <literal>oc4j_example</literal> application. </para> - - <itemizedlist> - <listitem> - <para> Build your application by calling - <literal>ant</literal> in the base directory of your - project (ex. - <literal>/home/jbalunas/workspace/oc4j_example</literal> - ). The target of the build will be - <literal>dist/oc4j_example.ear</literal> . </para> - </listitem> - <listitem> - <para> Copy the <literal>mysql-connector.jar</literal> file - to the - <literal>$ORACLE_HOME/j2ee/home/applib</literal> - directory so that jdbc drivers are available. </para> - </listitem> - - <listitem> - <para> <literal> - $ORACLE_HOME/j2ee/home/config/data-sources.xml - </literal> </para> - - - <programlisting role="XML"><![CDATA[<managed-data-source - connection-pool-name="oc4j-example-connection-pool" - jndi-name="jdbc/__oc4jexample" - name="oc4j-example-managed-data-source" /> -<connection-pool - name="oc4j-example-connection-pool"> - <connection-factory - factory-class="com.mysql.jdbc.Driver" - user="username" - password="password" - url="jdbc:mysql:///oc4j" /> -</connection-pool>]]></programlisting> - </listitem> - <listitem> - <para> - <literal>$ORACLE_HOME/j2ee/home/config/server.xml</literal> - </para> - - - <programlisting role="XML"><![CDATA[<application name="oc4j_example" - path="../../home/applications/oc4j_example.ear" - parent="default" - start="true" />]]></programlisting> - </listitem> - <listitem> - <para> <literal> - $ORACLE_HOME/j2ee/home/config/default-web-site.xml - </literal> </para> - - - <programlisting role="XML"><![CDATA[<web-app application="oc4j_example" - name="oc4j_example" - load-on-startup="true" - root="/oc4j_example" />]]></programlisting> - </listitem> - - <listitem> - <para> Start/stop OC4J following instructions in the - <literal>Installation and operation of OC4J</literal> - section above. </para> - </listitem> - <listitem> - <para> Checkout the app at: - <literal>http://localhost:8888/oc4j_example</literal> - </para> - </listitem> - </itemizedlist> - - </section> - - <section> - <title> Extending example with reverse engineered CRUD and Drools - </title> - <para> In this section we extend the basic - <literal>seam-gen</literal> application into a full blown CRUD - application based on an existing database. Plus we will add - <literal>Drools</literal> based security as well. </para> - <section> - <title> Have <literal>seam-gen</literal> generate your CRUD - applications </title> - <para> Type <literal>./seam generate-entities</literal> in the - base directory of your seam distribution. This will create the - entities, the Seam Application Framework classes and the - relevant views for the CRUD application. </para> - - <para> That's it...no really...that's it. Build and deploy as - before and see for yourself. </para> - - </section> - <section> - <title> Hook up drools authentication using your new CRUD - application </title> - <para> As stated above this section assumes your database had a - <literal>User</literal> table with - <literal>username</literal> and - <literal>password</literal> columns with at least one entry. - If you don't have this you may need to modify the - <literal>authenticate</literal> method below. </para> - <para> Lets link our <literal>User</literal> entity into Seam - Security by making our authenticator class a Stateless Session - Bean (OC4J is a EJB3 container after all!): </para> - - <orderedlist> - <listitem> - <itemizedlist> - <listitem> - <para> Add the <literal>@Stateless</literal> - annotation to the - <literal>Authenticator</literal> class. - </para> - </listitem> - <listitem> - <para> Rename the class to - <literal>AuthenticatorAction</literal> - </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="JAVA"><![CDATA[@Name("authenticator") @Stateless public class - AuthenticatorAction implements Authenticator {]]></programlisting> - - - <programlisting role="JAVA"><![CDATA[@Local public interface Authenticator { - public boolean authenticate(); -}]]></programlisting> - </listitem> - <listitem> - <para> Use <literal>@PersistenceContext</literal> to - inject an EntityManager by adding this line the - <literal>AuthenticatorAction</literal> class: - </para> - - - <programlisting role="JAVA"><![CDATA[@PersistenceContext private EntityManager entityManager;]]></programlisting> - </listitem> - <listitem> - <para>Implement authenticate:</para> - - - <programlisting role="JAVA"><![CDATA[public boolean authenticate() { - List <User> users = entityManager .createQuery("select u from User u where - u.username = #{identity.username} and - u.password = #{identity.password}") .getResultList(); - if (users.size() == 1) { - identity.addRole("admin"); - return true; - } else { - return false; - } -}]]></programlisting> - </listitem> - <listitem> - <para> And then add the EJB3 reference to - <literal>web.xml</literal> : </para> - - - <programlisting role="XML"><![CDATA[<ejb-local-ref> - <ejb-ref-name> - oc4j_example/AuthenticatorAction/local - </ejb-ref-name> - <ejb-ref-type>Session</ejb-ref-type> - <local> - org.jboss.seam.tutorial.oc4j.action.Authenticator - </local> - <ejb-link>AuthenticatorAction</ejb-link> -</ejb-local-ref>]]></programlisting> - </listitem> - </orderedlist> - - <para> Build and deploy as before and notice that now only actual - username and passwords are accepted. </para> - </section> - - </section> - - </section> - <section> - <title>Finishing up</title> - <para> That's it, we're through. You now have a great starting point for any - Seam based application deployed to OC4J. </para> - </section> -</chapter> Modified: trunk/doc/Seam_Reference_Guide/en-US/master.xml =================================================================== --- trunk/doc/Seam_Reference_Guide/en-US/master.xml 2008-12-01 02:43:21 UTC (rev 9677) +++ trunk/doc/Seam_Reference_Guide/en-US/master.xml 2008-12-01 06:09:22 UTC (rev 9678) @@ -40,7 +40,6 @@ <xi:include href="Performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Oc4j.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Weblogic.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Websphere.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Glassfish.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />