User: alborini
Date: 01/04/25 05:38:23
Modified: src/docs customizingjaws.xml
Log:
- some corrections
- now includes the 2 missing howtos by Michel de Groot about custom finders and join
queries
Revision Changes Path
1.6 +190 -68 manual/src/docs/customizingjaws.xml
Index: customizingjaws.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/customizingjaws.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- customizingjaws.xml 2001/03/30 02:30:43 1.5
+++ customizingjaws.xml 2001/04/25 12:38:23 1.6
@@ -9,10 +9,11 @@
</para>
<section>
<title>Introduction</title>
- <para>JAWS is the O/R mapper used by JBoss to manage CMP entity beans.
JAWS
-can be configured by putting a jaws.xml file in the
-META-INF directory of your application. JAWS will read this file while
-deploying your beans. Here is what you can do with jaws.xml:</para>
+ <para>JAWS is the O/R mapper used by JBoss to manage CMP entity beans.
JAWS is configured in a file named standardjaws.xml, located in the conf/config-name
directory in the JBoss distribution. The default <quote>config-name</quote> is
<quote>default</quote>.</para>
+
+ <para>This file configures JAWS for all JBoss. You can then extend
this configuration on a per-application basis by putting a jaws.xml file in the
META-INF directory of your application. Upon deploying your beans, JAWS will first
process the standardjaws.xml file, and then the jaws.xml file for your application if
provided.</para>
+
+ <para>Here is what you can do with standardjaws.xml / jaws.xml:</para>
<itemizedlist>
<listitem>
<para> Specify a datasource and the
type-mappings to use with it
@@ -107,9 +108,9 @@
<para>If none of the predefined type mappings satisfies your needs,
you can define
your own type-mapping.</para>
</section>
- <section>
+ <section id="jaws-options">
<title>JAWS Options</title>
- <para>Here are the options you can set in JAWS:</para>
+ <para>Here are the options you can set in JAWS. Default values are
provided in the standardjaws.xml file:</para>
<itemizedlist>
<listitem>
<para> create-table: this tells JAWS whether it
has to try and create the
@@ -127,7 +128,7 @@
</para>
</listitem>
<listitem>
- <para> tuned-updates: when this option is turned
on (default) JAWS will only
+ <para> tuned-updates: when this option is turned
on (off by default) JAWS will only
update in the database the fields of your bean that have
actually changed.
</para>
@@ -141,7 +142,7 @@
<listitem>
<para> time-out: this option is only used when
read-only is true. In this
case, JAWS will not refresh the state of your beans from the
- database more than once every time-out milliseconds.
+ database more than once every <quote>time-out</quote> milliseconds.
</para>
</listitem>
<listitem>
@@ -153,29 +154,25 @@
</para>
</listitem>
<listitem>
- <para> debug: when this option is turned on,
JAWS will log all SQL
+ <para> debug: when this option is turned on (off
by default), JAWS will log all SQL
queries at the debug level. This is useful when debugging CMP configuration and
database performance problems.
</para>
</listitem>
</itemizedlist>
- <para>Each of these options can be set either generally (it will
affect JAWS for
-your whole application) or on a per bean basis, or both of these.
-JAWS will always read the defaults first, then override them with the
-bean-specific configuration.</para>
- <para>General settings: to set an option generally, you have to
declare it in a <![CDATA[ <default-entity> tag in jaws.xml. Here is the section as
jaws
-uses
-it internally: you may want to override all or part of it:
+ <para>Each of these options can be set either generally (it will
affect JAWS for your whole application) or on a per bean basis, or both of these. JAWS
will always read the defaults in standardjaws.xml first, then override them with the
defaults in jaws.xml if provided, and finally override them with bean-specific
configuration if provided.</para>
+ <para>General settings: to set an option generally, you have to
declare it in a <![CDATA[ <default-entity> tag in jaws.xml. Here is the section as
in standardjaws.xml, you may want to override all or part of it:
]]></para>
<programlisting><![CDATA[
<jaws>
- <default-entity>
- <create-table>true</create-table>
- <remove-table>false</remove-table>
- <tuned-updates>true</tuned-updates>
- <read-only>false</read-only>
- <time-out>300</time-out>
- </default-entity>
+ <default-entity>
+ <create-table>true</create-table>
+ <remove-table>false</remove-table>
+ <tuned-updates>false</tuned-updates>
+ <read-only>false</read-only>
+ <time-out>300</time-out>
+ <select-for-update>false</select-for-update>
+ </default-entity>
...
<jaws>
@@ -208,20 +205,21 @@
CMP fields of this entity.</para>
<para>By default, JAWS will create the tables for you. The name of the
table will be
the ejb-name of the bean, and the name of the columns will be
-the name of the CMP fields. The jdbc type and the sql type will be the ones
+the names of the CMP fields. The jdbc type and the sql type will be the ones
given by the type-mapping. (see how the jdbc and sql type work
-in the type mappings section)</para>
+in <xref linkend="jaws-type-mappings"/>)</para>
<para>However, you may want to override this behavior and tell JAWS
which
names/types to use. For example, you may want JAWS to use an
already existing table. To do this, you must set these parameters in the <![CDATA[
<enterprise-beans> section of you jaws.xml file.
]]></para>
- <para>Example 1: you create an entity bean that will represent a
customer. You
+ <section>
+ <title>Example 1</title>
+ <para>You create an entity bean that will represent a
customer. You
already have the table in your database, it was created using the
following SQL statement:</para>
- <para>CREATE TABLE CUSTOMER (NAME VARCHAR(20),
- ADDRESS VARCHAR(100), PHONE VARCHAR(20));</para>
- <para>This is how the your xml file will look like:</para>
- <programlisting><![CDATA[
+ <para>CREATE TABLE CUSTOMER (NAME VARCHAR(20), ADDRESS
VARCHAR(100), PHONE VARCHAR(20));</para>
+ <para>This is how the your xml file will look like:</para>
+ <programlisting><![CDATA[
<jaws>
<enterprise-beans>
<entity>
@@ -246,11 +244,15 @@
</jaws>
]]></programlisting>
- <para>Example 2: your bank account bean has a String field to hold the
VISA card
+ </section>
+
+ <section>
+ <title>Example 2</title>
+ <para>Your bank account bean has a String field to hold the
VISA card
number. You don't want to use the default mapping for a String
(VARCHAR(256)) since a VISA Card number is not that long. Your xml file will
look like this:</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jaws>
<enterprise-beans>
<entity>
@@ -268,37 +270,34 @@
</jaws>
]]></programlisting>
- <para>Note that the contents of the <![CDATA[ <ejb-name> tag and of
all the
+ <para>Note that the contents of the <![CDATA[ <ejb-name> tag
and of all the
]]><![CDATA[ <field-name> tags must match the ones declared in
ejb-jar.xml.]]></para>
+ </section>
</section>
<section>
<title>Declaring finders</title>
- <para>.
-The finders to access your beans are all declared in the home interface. JAWS
-automatically generates the following finders for you:</para>
- <itemizedlist>
- <listitem>
- <para> findAll() will return a Collection of all
the beans available
- </para>
- </listitem>
- <listitem>
- <para> findByPrimaryKey(YourPK pk) will return a
single bean with the
-corresponding primary key (the primary key class is defined in
- ejb-jar.xml)
- </para>
- </listitem>
- <listitem>
- <para> for each of the cmp-fields of your bean,
findByXX(YY fieldValue), where
-XX is the name of the cmp-field (NOT case-sensitive)
- and YY its class, will return a Collection of all the beans with the
-right value in this field.
- </para>
- </listitem>
- </itemizedlist>
- <para>Note that these finders are only generated if you declare them
in your home
-interface.</para>
- <para>JAWS then allows you to define customized finders. These finders
must also be
+ <para>The finders to access your beans must all be declared in the
home interface, according to the EJB specification.</para>
+ <section>
+ <title>Standard finders, automatically generated</title>
+ <para>JAWS automatically generates the following finders for
you:</para>
+ <itemizedlist>
+ <listitem>
+ <para>findAll() will return a Collection of
all the beans available</para>
+ </listitem>
+ <listitem>
+ <para>findByPrimaryKey(YourPK pk) will return
a single bean with the corresponding primary key (the primary key class is defined in
ejb-jar.xml)</para>
+ </listitem>
+ <listitem>
+ <para>for each of the cmp-fields of your bean,
findByXX(YY fieldValue), where XX is the name of the cmp-field (NOT case-sensitive)
and YY its class, will return a Collection of all the beans with the right value in
this field.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Note that these finders are only generated if you
declare them in your home
+interface. <quote>Automatically generated</quote> only means that JAWS will guess
the meaning of your finder from its name, you don't have to add anything.</para>
+ </section>
+ <section>
+ <title>Custom finders</title>
+ <para>JAWS then allows you to define customized finders. These
finders must also be
declared in the home interface of your bean. You must then
provide additional information in jaws.xml about the query to be used for this
finder. This is done in a <![CDATA[ <finder> section in the section for
@@ -306,9 +305,9 @@
the home interface), the WHERE part of the query, and the
ORDER part.
]]></para>
- <para>Example: you want to select classes with a mininum number of
students. Your
+ <para>Example: you want to select classes with a mininum
number of students. Your
Class bean has the following structure:</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<ejb-jar>
<enterprise-beans>
<entity>
@@ -333,12 +332,12 @@
</ejb-jar>
]]></programlisting>
- <para>You want to define a method in ClassHome:</para>
- <programlisting> public Collection findBigClasses(int
minStudentCount, String teacher)
+ <para>You want to define a method in ClassHome:</para>
+ <programlisting> public Collection findBigClasses(int
minStudentCount, String teacher)
throws FinderException;
</programlisting>
- <para>Your jaws.xml file will contain the following:</para>
- <programlisting><![CDATA[
+ <para>Your jaws.xml file will contain the following:</para>
+ <programlisting><![CDATA[
<jaws>
<enterprise-beans>
<entity>
@@ -354,12 +353,135 @@
</jaws>
]]></programlisting>
- <para>Then a call to findBigClasses(100, "Jones") will generate</para>
- <programlisting>SELECT classId FROM ClassBean
+ <para>Then a call to findBigClasses(100, "Jones") will
generate</para>
+ <programlisting>SELECT classId FROM ClassBean
WHERE studentCount > 100 AND teacherName = Jones
ORDER BY studentCount DESC;</programlisting>
+ </section>
+
+ <section>
+ <title>Custom finders with join queries</title>
+ <para>Author:
+ <author>
+ <firstname>Michel</firstname>
+ <surname>de Groot</surname>
+ </author>
+ <email>[EMAIL PROTECTED]</email> or
<email>[EMAIL PROTECTED]</email>
+ </para>
+ <para>By default, JAWS will use only the table for your bean
to perform select queries. You can also use inner join queries on multiple tables with
JAWS CMP for finder methods with EJB 1.1. This allows you to deliver powerful queries
with minimal effort.</para>
+ <para>Standards compliance note: this feature is not standard
or required in EJB 1.1. Therefore, EJBs that use this feature, might not be
compile-free portable to other EJB containers.</para>
+ <para>You must use a database which has support for SQL92
(most databases do) or T-SQL join queries.</para>
+ <para>Example: </para>
+ <itemizedlist>
+ <listitem>
+ <para>List your finder method in the EJB's
home interface as usual.</para>
+ <programlisting>
+public interface PopulationHome extends EJBHome {
+ /**
+ * Finds all populations of a specific type as defined in
+ * CreatureTypes of a Province.
+ * @param provinceId the primary key of the province
+ * @param type the type of creatures to find
+ */
+ public Collection findByProvinceAndType(String provinceId, int type)
+ throws RemoteException, FinderException;
+}
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>Declare your finder in jaws.xml, using
the <![CDATA[<query>]]> tag. There are two options. The first presented here conforms
to SQL92 and is the more generic and portable one. The second presented here is
defined by T-SQL and is useful for MS Access 97 (and maybe more databases I'm not
aware of).</para>
+ <para>Generic SQL92 example:</para>
+ <programlisting><![CDATA[
+<finder>
+ <name>findByProvinceAndType</name>
+ <query>,CreatureEJBTable
+ WHERE CreatureEJBTable.id = PopulationEJBTable.creatureId AND
+ provinceId={0} AND type={1}</query>
+ <order></order>
+</finder>
+]]></programlisting>
+ <para>T-SQL example:</para>
+ <programlisting><![CDATA[
+<finder>
+ <name>findByProvinceAndType</name>
+ <query>inner join CreatureEJBTable ON CreatureEJBTable.id =
+ PopulationEJBTable.creatureId WHERE provinceId={0} AND
+ type={1}</query>
+ <order></order>
+</finder>
+]]></programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>You must be aware of the following issues:
+ <itemizedlist>
+ <listitem>
+ <para>The query must start with
<![CDATA[',<table name to join with>' (for SQL92 query) or with 'inner join <table
name to join with>' (for T-SQL)]]>. JAWS will append the proper select
statement.</para>
+ </listitem>
+ <listitem>
+ <para>If SQL92 is used, the WHERE
statement must contain the identity statement which joins the tables. If T-SQL is
used, the ON statement must contain the identity statement which joins the
tables.</para>
+ </listitem>
+ <listitem>
+ <para>The query must contain the WHERE
statement followed by the conditions of the query.</para>
+ </listitem>
+ <listitem>
+ <para>The query always delivers
instances of the Entity Bean on which the finder is defined.</para>
+ </listitem>
+ <listitem>
+ <para>Field names must be fully
qualified with table name if ambiguity can arise.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>We strongly suggest you use SQL92 as default query
language. T-SQL is provided for ease-of-use if you have existing T-SQL queries.</para>
+ </section>
+
+ <section>
+ <title>Custom finders coded in your beans</title>
+ <para>Author:
+ <author>
+ <firstname>Michel</firstname>
+ <surname>de Groot</surname>
+ </author>
+ <email>[EMAIL PROTECTED]</email> or
<email>[EMAIL PROTECTED]</email>
+ </para>
+ <para>Sometimes, the finders automatically generated by JAWS
or the finders defined in jaws.xml using SQL92 are not sufficient for your
application. You want to implement a custom finder by coding the query in your
bean.</para>
+ <para>You can also have Entity Beans with finders which have
been developed against a less advanced persistence manager. This forced you to develop
custom finders at that time. You want to be able to leverage this work to JBoss.</para>
+ <para>To do this, all you have to do is</para>
+ <itemizedlist>
+ <listitem>
+ <para>Declare the finder in the EJB's home
interface as usual. This name must begin with <quote>findBy</quote>. Example: </para>
+ <programlisting>
+public interface PopulationHome extends EJBHome {
+ /**
+ * Finds all populations of a specific type as defined in
+ * CreatureTypes of a Province.
+ * @param provinceId the primary key of the province
+ * @param type the type of creatures to find
+ */
+
+ public Collection findByProvinceAndType(String provinceId, int type)
+ throws RemoteException, FinderException;
+}
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>Implement the finder method in the EJB's
implementation class. The name of the method must begin with <quote>ejbFindBy</quote>
and match the name declared in the home interface. Example: </para>
+ <programlisting>
+public class PopulationEJB implements EJBObject {
+ public Collection ejbFindByProvinceAndType(String provinceId, int type) {
+ // .. fill Collection with primary keys of result objects
+ return aResultCollection;
+ }
+}
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>This feature is standard and required in EJB 1.1.</para>
+ <para>Custom finders defined this way will ALWAYS be used if
present. They override automatic or defined finders. This is according to the EJB 1.1
specification.</para>
+ </section>
+
+
</section>
- <section>
+ <section id="jaws-type-mappings">
<title>Defining a type mapping</title>
<para>A type mapping tells JAWS how to map java objects to a specific
database. For
example, some databases have a boolean type, and other
@@ -394,6 +516,6 @@
</itemizedlist>
<para>If the type mapping we provide for a particular database is
faulty and you
find you have to modify it, please consider sharing your changes:
-post the modified mapping on the JAWS mailing list.</para>
+post the modified mapping on the jbosscmp mailing list.</para>
</section>
</chapter>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
