[jboss-cvs] JBossAS SVN: r83769 - in projects/ejb3/trunk/docs/reference/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Feb 2 05:29:42 EST 2009
Author: jaikiran
Date: 2009-02-02 05:29:42 -0500 (Mon, 02 Feb 2009)
New Revision: 83769
Added:
projects/ejb3/trunk/docs/reference/en/Author_Group.xml
projects/ejb3/trunk/docs/reference/en/modules/ejbref.xml
projects/ejb3/trunk/docs/reference/en/modules/entity_configuration.xml
Modified:
projects/ejb3/trunk/docs/reference/en/master.xml
Log:
EJBTHREE-1509 More additions to the reference guide
Added: projects/ejb3/trunk/docs/reference/en/Author_Group.xml
===================================================================
--- projects/ejb3/trunk/docs/reference/en/Author_Group.xml (rev 0)
+++ projects/ejb3/trunk/docs/reference/en/Author_Group.xml 2009-02-02 10:29:42 UTC (rev 83769)
@@ -0,0 +1,7 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<authorgroup>
+ <corpauthor>Bill Burke</corpauthor>
+ <corpauthor>Jaikiran Pai</corpauthor>
+</authorgroup>
Modified: projects/ejb3/trunk/docs/reference/en/master.xml
===================================================================
--- projects/ejb3/trunk/docs/reference/en/master.xml 2009-02-02 10:10:56 UTC (rev 83768)
+++ projects/ejb3/trunk/docs/reference/en/master.xml 2009-02-02 10:29:42 UTC (rev 83769)
@@ -3,14 +3,17 @@
"../../../../../docbook-support/support/docbook-dtd/docbookx.dtd"
[
<!ENTITY session SYSTEM "modules/session.xml">
+<!ENTITY ejbref SYSTEM "modules/ejbref.xml">
+<!ENTITY entity_configuration SYSTEM "modules/entity_configuration.xml">
]>
<book lang="en">
<bookinfo>
- <title>JBoss EJB 3.0 Reference Documentation</title>
- <subtitle>JBoss EJB 3.0 Reference Documentation</subtitle>
- <releaseinfo>1.0.0</releaseinfo>
+ <title>JBoss EJB 3.0 Reference Documentation</title>
+ <subtitle>JBoss EJB 3.0 Reference Documentation</subtitle>
+ <releaseinfo>1.0.0</releaseinfo>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/>
</bookinfo>
<toc/>
@@ -28,20 +31,13 @@
&session;
-<!-- &ejbref; Sequence of steps for injection-->
+&ejbref;
+&entity_configuration;
+
-<!-- &entity_configuration; JACC-->
-
-<!--
- &jboss_deployment_descriptor;
-
- &partial_deployment_descriptors; -->
-
-
-
</book>
Added: projects/ejb3/trunk/docs/reference/en/modules/ejbref.xml
===================================================================
--- projects/ejb3/trunk/docs/reference/en/modules/ejbref.xml (rev 0)
+++ projects/ejb3/trunk/docs/reference/en/modules/ejbref.xml 2009-02-02 10:29:42 UTC (rev 83769)
@@ -0,0 +1,59 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<chapter id="EJB_Ref_Resolution">
+
+ <title>EJB reference resolution</title>
+
+ <sect5>
+ Introduction :
+ <para>
+ This section covers how JBoss implements @EJB and @Resource. Please note that XML always overrides annotations.
+ </para>
+ </sect5>
+ <sect5>
+ EJB references :
+ <para>
+ Rules for the @EJB annotation
+ <itemizedlist>
+ <listitem>
+ The @EJB annotation also has a mappedName() attribute. The specification leaves this a vendor specific metadata,
+ but JBoss recognizes mappedName() as the global JNDI name of the EJB you are referencing. If you have specified
+ a mappedName(), then all other attributes are ignored and this global JNDI name is used for binding.
+ </listitem>
+ <listitem>
+ If you specify @EJB with no attributes defined:
+ <programlisting>
+ <![CDATA[
+ at EJB
+ProcessPayment myEjbref;
+ ]]>
+ </programlisting>
+ Then the following rules apply:
+ <itemizedlist>
+ <listitem>
+ The EJB jar of the referencing bean is searched for an EJB with the interface, used in for @EJB injection.
+ If there are more than one EJB that publishes same business interface, then an exception is thrown. If there is only one
+ bean with that interface then that one is used.
+ </listitem>
+ <listitem>
+ Search the EAR for EJBs that publish that interface. If there are duplicates, then an exception is thrown. Otherwise the matching
+ bean is returned.
+ </listitem>
+ <listitem>
+ Search globally in JBoss for an EJB of that interface. Again, if duplicates, an exception is thrown.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ @EJB.beanName() corresponds to <literal><ejb-link></literal>. If the beanName() is defined, then use the same algorithm
+ as @EJB with no attributes defined except use the beanName() as a key in the search. An exception to this rule is if you use
+ the ejb-link '#' syntax. The '#' syntax allows you to put a relative path to a jar in the EAR where the EJB you are
+ referencing lives. See spec for more details
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ For XML the same rules apply as annotations
+ </para>
+ </sect5>
+</chapter>
+
Property changes on: projects/ejb3/trunk/docs/reference/en/modules/ejbref.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: projects/ejb3/trunk/docs/reference/en/modules/entity_configuration.xml
===================================================================
--- projects/ejb3/trunk/docs/reference/en/modules/entity_configuration.xml (rev 0)
+++ projects/ejb3/trunk/docs/reference/en/modules/entity_configuration.xml 2009-02-02 10:29:42 UTC (rev 83769)
@@ -0,0 +1,246 @@
+<chapter id="entityconfig">
+
+ <title>Entity Configuration Files</title>
+
+ <sect5>
+ Introduction :
+ <para>
+ This section talks about various configuration parameters for getting entities to work within JBoss.
+ JBoss EJB 3.0 is built on top of the Hibernate ORM solution, and more specifically, the Hibernate Entity Manager.
+ This chapter explains the configurations related to the datasource, the persistence-unit and how they relate to each other.
+ </para>
+ </sect5>
+ <sect5>
+ Configuration Files :
+ <para>
+ To use EJB3 Entities within JBoss you'll need to do a few things.
+ <itemizedlist>
+ <listitem>
+ Configure a JBoss datasource using *-ds.xml file. Check out the documentation at <ulink url="http://jboss.org/community/docs/DOC-9328">our wiki</ulink>
+ or you can view example configurations for many different datasources within:
+ %JBOSS_HOME%/docs/examples/jca
+ </listitem>
+ <listitem>
+ Create a persistence.xml file and place it in the META-INF folder of your jar
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <sect5>
+ Configure JBoss datasource :
+ <para>
+ For datasources,
+ JBoss comes with the Hypersonic SQL database
+ embedded within it and a default datasource available in JNDI under <literal>java:/DefaultDS</literal>. Otherwise, you'll need to specify your own datasource. Please refer to the JBoss AS guide or the wiki mentioned earlier, on how to create a JBoss connection pool.
+ Also, there are examples in the jboss distrubtion under %JBOSS_HOME%/docs/examples/jca.
+ </para>
+ </sect5>
+
+ <sect5>
+ persistence.xml and .jar files :
+ <para>
+ Entities are placed in a EJB-JAR .jar file or a .jar file all their own. You must
+ also define a persistence.xml file that resides in the META-INF folder of the .jar file. Here's an example of
+ a persistence.xml file.
+ </para>
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
+ version="1.0">
+
+ <persistence-unit name="manager1">
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <jar-file>../MyApp.jar</jar-file>
+ <class>org.acme.Employee</class>
+ <class>org.acme.Person</class>
+ <class>org.acme.Address</class>
+ <properties>
+ <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
+ <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
+ </properties>
+ </persistence-unit>
+</persistence>]]>
+ </programlisting>
+
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term><code>name</code></term>
+ <listitem>
+ <para>
+ You are required to name your persistence unit.
+ If your persistence classes are within a EJB JAR archive, and it is the only persistence
+ unit defined, then you do not have to reference this name explicitly in your @PersistenceContext and @PersistenceUnit
+ annotations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>jta-data-source</code>, <code>non-jta-data-source</code>
+ </term>
+ <listitem>
+ <para>
+ This is the JNDI name of where the javax.sql.DataSource is located. This is ignored when *not* used within
+ an application server. When running outside of an application server, you must specify JDBC connections
+ with Hibernate specific properties (see below). If you're running inside JBoss, put the jndi name of the
+ datasource you defined in the earlier section.
+ <note>
+ <para>
+ JBoss by default binds the datasource to the java: namespace. Remember to use the java: while using the datasource name in the persistence.xml
+ </para>
+ </note>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>jar-file and class</code></term>
+ <listitem>
+ <para>
+ The class element specifies a fully qualified classname that you will belong to the persistence unit.
+ The jar-file element specifies another jar you want automatically scanned for @Entity classes.
+ When using jar-file, you must specify a path relative to the jar file the persistence.xml
+ file is in.
+ By default also, the jar the persistence.xml file is placed in is scanned for @Entity classes
+ as well.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><code>properties</code></term>
+ <listitem>
+ <para>
+ The properties element is used to specify vendor specific properties. This is where you will define
+ your JBoss and Hibernate specific configurations.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ JBoss EJB 3.0 is built on top of Hibernate 3.0 ORM solution. You may need to provide information to Hibernate so that it knows
+ the database vendor dialect (MySQL, Oracle, etc...), caching, as well as other settings. JBoss EJB 3.0 also has some specific
+ configurable properties as well. Here's a table of properties. We don't list all the Hibernate ones. You can browse through the Hibernate documentation for those.
+ </para>
+ <table frame="topbot" id="3rdpartylibs">
+ <title>
+ Example Config Properties
+ </title>
+ <tgroup cols="2" rowsep="1" colsep="1">
+ <colspec colname="c1" colwidth="1*"/>
+ <colspec colname="c2" colwidth="2*"/>
+ <thead>
+ <row>
+ <entry align="center">
+ Property
+ </entry>
+ <entry align="center">
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ hibernate.dialect
+ </entry>
+ <entry>
+ Usually Hibernate can figure out the database dialect itself, but maybe not.
+ Check the hibernate documentation for information on this
+ </entry>
+ </row>
+ <row>
+ <entry>
+ hibernate.hbm2ddl.auto=update
+ </entry>
+ <entry>
+ Creates the database schema on deploy if it doesn't exist. Alters it if it has changed. Useful
+ for when you want to generate database schema from entity beans
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ jboss.entity.manager.jndi.name
+ </entry>
+ <entry>
+ JBoss does not publish container managed EntityManagers in JNDI by default. Use this to bind it.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ jboss.entity.manager.factory.jndi.name
+ </entry>
+ <entry>
+ JBoss does not publish container managed EntityManagerFactorys in JNDI by default. Use this to bind it.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ jboss.no.implicit.datasource.dependency
+ </entry>
+ <entry>
+ JBoss tries to register deployment dependencies for datasource by guessing the dependency name
+ based on the jndi name of the datasource. Use this switch if the guess is wrong.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ jboss.depends.{some arbitrary name}
+ </entry>
+ <entry>
+ Specify an MBean dependency for the persistence unit deployment.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect5>
+ </sect5>
+ <sect5>
+ EAR and WAR files :
+ <para>
+ You can deploy your EJB3 entities and the persistence-unit through WAR files too. You will have to place the jar containing the entities and META-INF/persistence.xml, in the .war/WEB-INF/lib folder.
+ </para>
+ <para>
+ For deploying through an EAR, you need not mention the jar containing the entities and the persistence-unit in the application.xml. If you place the jar at the root of the EAR, the persistence-unit and the entities will be deployed.
+ </para>
+
+ </sect5>
+ <sect5>
+ Referencing persistence units :
+ <sect5>
+ Scoped deployments :
+ <para>
+ If a persistence unit is defined in an EJB-JAR file it is not visible to other deployed jars
+ using the @PersistenceContext or @PersistenceUnit annotation. This scoping is required by the specification.
+ </para>
+ </sect5>
+ <sect5>
+ <title>Referencing from Global JNDI</title>
+ <para>
+ Persistence units are not available within global JNDI unless you explicitly configure them
+ to do so. There are two properties you can specify in your persistence.xml file to enable this.
+ <literal>jboss.entity.manager.jndi.name</literal> gives you a transaction scoped entity manager
+ you can interact with. <literal>jboss.entity.manager.factory.jndi.name</literal> binds the
+ entity manager factory into global JNDI.
+ </para>
+ <programlisting><![CDATA[
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
+ http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
+ version="1.0">
+ <persistence-unit name="manager1">
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <properties>
+ <property name="jboss.entity.manager.jndi.name" value="java:/Manager1"/>
+ <property name="jboss.entity.manager.factory.jndi.name" value="java:/Manager1Factory"/>
+ </properties>
+ </persistence-unit>
+</persistence>]]>
+ </programlisting>
+ </sect5>
+ </sect5>
+
+</chapter>
+
Property changes on: projects/ejb3/trunk/docs/reference/en/modules/entity_configuration.xml
___________________________________________________________________
Name: svn:executable
+ *
More information about the jboss-cvs-commits
mailing list