[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Peter Muir
peter at bleepbleep.org.uk
Mon Aug 27 17:31:25 EDT 2007
User: pmuir
Date: 07/08/27 17:31:25
Added: doc/reference/en/modules oc4j.xml
Log:
JBSEAM-1871
Revision Changes Path
1.1 date: 2007/08/27 21:31:25; author: pmuir; state: Exp;jboss-seam/doc/reference/en/modules/oc4j.xml
Index: oc4j.xml
===================================================================
<chapter id="oc4j">
<title>Seam on OC4J</title>
<para>
OC4J (Oracle Containers for Java) 11g (currently a "Technology Preview"
release) is Oracle's JEE 5 application server. We will will start by
looking at the building and deploying the Hotel Booking example
application which comes with Seam, and then at deploying a project
generated by seam-gen. This project will integrate Seam, RichFaces Ajax
and components, Seam Security (with Drools), Facelets and JPA provided
by Hibernate.
</para>
<para>
This section 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>.
</para>
<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.
</para>
<section>
<title>Booking Example Dependencies</title>
<para>
First, lets look at the dependencies of the booking example. Armed
with this knowledge we can look at the extra dependencies requirements
that OC4J adds.
</para>
<itemizedlist>
<listitem>
<para>
<literal>jboss-seam.jar</literal> — 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)
</para>
</listitem>
<listitem>
<para>
<literal>jboss-el.jar</literal>
</para>
</listitem>
<listitem>
<para>
<literal>jboss-seam-ui.jar</literal> — Seam's JSF controls
depend on Apache's commons-beanutils
</para>
</listitem>
<listitem>
<para>
<literal>jboss-seam-debug.jar</literal>
</para>
</listitem>
<listitem>
<para>
<literal>jsf-facelets.jar</literal>
</para>
</listitem>
<listitem>
<para>
<literal>ajax4jsf-1.1.1.jar</literal> — which requires Apache
commons-digester and commons-beanutils
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Extra dependencies required by OC4J</title>
<itemizedlist>
<listitem>
<para>
Hibernate — 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 three jars
(<literal>hibernate3.jar</literal>, <literal>hibernate-annotations.jar</literal>,
<literal>hibernate-entitymanager.jar</literal>) and their
dependencies (<literal>jboss-common.jar</literal>,
<literal>jboss-archive-browsing.jar</literal> and
<literal>ejb3-persistence.jar</literal>). You can find these
in the <literal>hibernate/lib</literal> directory in the Seam
distribution.
</para>
</listitem>
<listitem>
<para>
<literal>thirdparty-all.jar</literal> — a selection of
third party libraries on which Seam depends (like javassist).
</para>
</listitem>
</itemizedlist>
<para>
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:
</para>
<itemizedlist>
<listitem>
<para>
<literal>antlr-2.7.6.jar</literal> — needed for Seam Text
(not used in the example).
</para>
</listitem>
<listitem>
<para>
<literal>jbpm-jpdl.jar</literal> — needed for Seam's JBPM
integration (not used in the example).
</para>
</listitem>
<listitem>
<para>
Drools — needed for Seam Security. We aren't using Seam
security with Drools, but have to include it. Drools consists
of 5 jars - <literal>drools-core-4.0.0.jar</literal>,
<literal>drools-compiler-4.0.0.jar</literal>,
<literal>janino-2.5.7.jar</literal>,
<literal>mvel14-1.2rc1.jar</literal> and
<literal>antlr-runtime-3.0.jar</literal>. Drools integration
is not used in the example.
</para>
</listitem>
</itemizedlist>
</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 JEE 5 application servers - for example OC4J and
Glassfish.
</para>
<programlisting><![CDATA[<ejb-local-ref>
<ejb-ref-name>
jboss-seam-jee5/AuthenticatorAction/local
</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home/>
<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>
<programlisting><![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" />]]></programlisting>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Building the <literal>jee5/booking</literal> example</title>
<orderedlist>
<listitem>
<para>Modify the following files in the project:</para>
<itemizedlist>
<listitem>
<para>
<literal>build.xml</literal> — Un-comment the
OC4J-related libraries
</para>
</listitem>
<listitem>
<para>
<literal>resources/META-INF/persistence.xml</literal> —
Comment out the Glassfish properties and un-comment the OC4J
properties.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Build the demo app by running <literal>ant</literal>. The build
target is <literal>dist/jboss-seam-jee5.ear</literal>
</para>
</listitem>
<listitem>
<para>
Copy <literal>hsqldb.jar</literal> to OC4J:
<literal>cp ../../seam-gen/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>
</orderedlist>
</section>
</section>
<section>
<title>Deploying a 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 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>
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>
Edit the OC4J datasource
<literal>$ORACLE_HOME/j2ee/home/config/data-sources.xml</literal>
and, inside <literal><data-sources></literal>, add
</para>
<programlisting><![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><application-server></literal>, add
</para>
<programlisting><![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><web-site></literal>, add
</para>
<programlisting><![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 OC4J:
<literal>$ORACLE_HOME/bin/oc4j -start</literal>
</para>
<para>
You will be asked to set the admin password if this is
the first time you've started OC4J
</para>
</listitem>
<listitem>
<para>
Checkout the app at:
<literal>http://localhost:8888/seam-jee5</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>
</section>
<section>
<title>
Deploying an application created using <literal>seam-gen</literal>
to OC4J
</title>
<para>
The following explanation assumes you are using the command line and
a simple text editor, but of course you can use your favourite IDE -
<literal>seam-gen</literal> projects come with support for Eclipse
and Netbeans.
</para>
<para>
We start by creating a pretty simple application using
<literal>seam-gen</literal>. <literal>seam-gen</literal> uses
Hibernate Tools to reverse engineer a database schema to JPA entity
beans; it also genereates Seam Application Framework components and
JSF views for CRUD. This tutorial uses MySQL (but of course you
could use any database, altering the SQL as appropriate); install,
configure and run MySQL, then create a database with some sample
data.
</para>
<para>
Next, run <literal>./seam setup</literal> in the seam directory.
</para>
<programlisting><![CDATA[> ./seam setup
Buildfile: build.xml
setup:
[echo] Welcome to seam-gen :-)
[input] Enter your Java project workspace (the directory that contains your Seam projects) [/home/pmuir/workspace] [/home/pmuir/workspace]
[input] Enter your JBoss home directory [/home/pmuir/java/jboss-4.2.1.GA] [/home/pmuir/java/jboss-4.2.1.GA]
[input] Enter the project name [oc4j-example] [oc4j-example]
[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 [org.jboss.seam.tutorial.oc4j.action] [org.jboss.seam.tutorial.oc4j.action]
[input] Enter the Java package name for your entity beans [org.jboss.seam.tutorial.oc4j.model] [org.jboss.seam.tutorial.oc4j.model]
[input] Enter the Java package name for your test cases [org.jboss.seam.tutorial.oc4j.test] [org.jboss.seam.tutorial.oc4j.test]
[input] What kind of database are you using? [mysql] (hsql, [mysql], oracle, postgres, mssql, db2, sybase, enterprisedb, )
[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 [lib/mysql.jar] [lib/mysql.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:///oc4j] [jdbc:mysql:///oc4j]
[input] Enter database username [user] [user]
[input] Enter database password [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? [y] ([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] Updating property file: /home/pmuir/workspace/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]]></programlisting>
<para>
Type <literal>./seam new-project</literal> to create your project and
<literal>cd</literal> to the newly created project.
</para>
<para>
Type <literal>./seam generate-entities</literal> to run create the
entities, the Seam Application Framework classes and the relevant
views.
</para>
<para>
We now need to make some changes to the generated project. Let's
start with the configuration files:
</para>
<variablelist>
<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>).
</para>
</listitem>
<listitem>
<para>Add the properties (described above):</para>
<programlisting><![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><![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><transaction:ejb-transaction /></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:
</para>
<programlisting><![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:
</para>
<programlisting><![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 need to declare all your EJBs here. Remember to include
the Seam container managed transaction integration:
</para>
<programlisting><![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>build.xml</literal>
</term>
<listitem>
Change the default target to archive (we aren't going to cover
automatic deployment to OC4J).
</listitem>
</varlistentry>
</variablelist>
<para>Now, lets add in the extra dependencies:</para>
<itemizedlist>
<listitem>
<para>
Hibernate —
</para>
<itemizedlist>
<listitem>
<para>
Copy the jars from <literal>hibernate/lib</literal> directory
in the Seam distribution <literal>oc4j-example/lib</literal>:
<literal>cp ../jboss-seam/hibernate/lib/*.jar lib/</literal>
</para>
</listitem>
<listitem>
<para>
Alter the build.xml to include them in the ear - add these
includes underneath the other libraries being copies:
</para>
<programlisting><![CDATA[<include name="lib/hibernate-annotations.jar" />
<include name="lib/hibernate-entitymanager.jar" />
<include name="lib/hibernate3.jar" />
<include name="ejb3-peristence.jar" />
<include name="lib/jboss-archive-browsing.jar" />
<include name="lib/jboss-common.jar" />]]></programlisting>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<literal>thirdparty-all.jar</literal> — alter the
<literal>build.xml</literal> to include it - add this include:
</para>
<programlisting><![CDATA[<include name="lib/thirdparty-all.jar" />]]></programlisting>
</listitem>
<listitem>
<para>
<literal>antlr-2.7.6.jar</literal> — alter the build.xml to
include it - add this include:
</para>
<programlisting><![CDATA[<include name="lib/antlr-*.jar" />]]></programlisting>
</listitem>
<listitem>
<para>
As 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>
<itemizedlist>
<listitem>
<programlisting><![CDATA[cp ../jboss-seam/seam-gen/lib/org.eclipse.jdt.core*.jar lib/]]></programlisting>
</listitem>
<listitem>
<para>
Alter the build.xml to include them in the ear:
</para>
<programlisting><![CDATA[<include name="lib/org.eclipse.jdt.core*.jar" />]]></programlisting>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>You should end up with something like:</para>
<programlisting><![CDATA[<fileset dir="${basedir}">
<!-- other libraries added by seam-gen -->
<include name="lib/hibernate-annotations.jar" />
<include name="lib/hibernate-entitymanager.jar" />
<include name="lib/hibernate3.jar" />
<include name="lib/jboss-archive-browsing.jar" />
<include name="lib/jboss-common.jar" />
<include name="lib/thirdparty-all.jar" />
<include name="lib/antlr-*.jar" />
<include name="lib/org.eclipse.jdt.core*.jar" />
</fileset>]]></programlisting>
<para>
Finally, lets link our <literal>User</literal> entity into Seam
Security (we have a <literal>User</literal> table with a
<literal>username</literal> column and a <literal>password</literal>
column). We're going to make our authentictor a Stateless Session
Bean (OC4J is a EJB3 container after all!):
</para>
<orderedlist>
<listitem>
<itemizedlist>
<listitem>
<para>
Add the <literal>@Stateless</literal> annotation.
</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><![CDATA[@Name("authenticator") @Stateless public class
AuthenticatorAction implements Authenticator {]]></programlisting>
<programlisting><![CDATA[@Local public interface Authenticator {
public boolean authenticate();
}]]></programlisting>
</listitem>
<listitem>
<para>
Use <literal>@PersistenceContext</literal> to inject an
EntityManager:
</para>
<programlisting><![CDATA[@PersistenceContext private EntityManager entityManager;]]></programlisting>
</listitem>
<listitem>
<para>
Implement authenticate:
</para>
<programlisting><![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><![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>
Now you can go on and customize your application.
</para>
<section>
<title>OC4J Deployment Descriptors for the seam-gen'd application</title>
<para>
To deploy your application use the deployment instructions above in
conjunction with these deployment descriptors:
</para>
<variablelist>
<varlistentry>
<term>
<literal>$ORACLE_HOME/j2ee/home/config/data-sources.xml</literal>
</term>
<listitem>
<programlisting><![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>
</varlistentry>
<varlistentry>
<term>
<literal>$ORACLE_HOME/j2ee/home/config/server.xml</literal>
</term>
<listitem>
<programlisting><![CDATA[<application name="oc4j-example"
path="../../home/applications/oc4j-example.ear"
parent="default"
start="true" />]]></programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>$ORACLE_HOME/j2ee/home/config/default-web-site.xml</literal>
</term>
<listitem>
<programlisting><![CDATA[<web-app application="oc4j-example"
name="oc4j-example"
load-on-startup="true"
root="/oc4j-example" />]]></programlisting>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list