User: danch
Date: 01/06/21 20:47:40
Modified: src/docs customizingjaws.xml
Log:
added brief/terse explanation of the interaction between read-ahead option and
transactions
Revision Changes Path
1.9 +267 -259 manual/src/docs/customizingjaws.xml
Index: customizingjaws.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/customizingjaws.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- customizingjaws.xml 2001/06/16 00:49:32 1.8
+++ customizingjaws.xml 2001/06/22 03:47:40 1.9
@@ -1,15 +1,15 @@
<?xml version = "1.0" encoding = "UTF-8"?>
<chapter id="jaws">
- <title>Customizing JAWS</title>
- <para>Author:<author>
- <firstname>Sebastien</firstname>
- <surname>Alborini</surname>
- </author>
- <email>[EMAIL PROTECTED]</email>
- </para>
- <section>
- <title>Introduction</title>
- <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>
+ <title>Customizing JAWS</title>
+ <para>Author:<author>
+ <firstname>Sebastien</firstname>
+ <surname>Alborini</surname>
+ </author>
+ <email>[EMAIL PROTECTED]</email>
+ </para>
+ <section>
+ <title>Introduction</title>
+ <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
@@ -21,91 +21,91 @@
directory of the <emphasis>jar</emphasis> archive.
</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
- </para>
- </listitem>
- <listitem>
- <para> Set a bunch of options concerning jaws
behavior
- </para>
- </listitem>
- <listitem>
- <para> Specify how JAWS should build/use your
tables
- </para>
- </listitem>
- <listitem>
- <para> Define finders to access you entity beans
- </para>
- </listitem>
- <listitem>
- <para> Define a type mapping
- </para>
- </listitem>
- </itemizedlist>
- <para>If you want to know everything about jaws.xml, see the Jaws.xml
DTD. The
+ <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
+ </para>
+ </listitem>
+ <listitem>
+ <para> Set a bunch of options concerning jaws behavior
+ </para>
+ </listitem>
+ <listitem>
+ <para> Specify how JAWS should build/use your tables
+ </para>
+ </listitem>
+ <listitem>
+ <para> Define finders to access you entity beans
+ </para>
+ </listitem>
+ <listitem>
+ <para> Define a type mapping
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>If you want to know everything about jaws.xml, see the Jaws.xml DTD.
The
general structure of the jaws.xml can be found here. All parts of
this file are optional: you only provide what you need!</para>
- </section>
- <section>
- <title>Specifying a datasource</title>
- <para>A datasource is, mainly, a database plus a driver plus a
connection pool. By
+ </section>
+ <section>
+ <title>Specifying a datasource</title>
+ <para>A datasource is, mainly, a database plus a driver plus a connection
pool. By
default, jboss uses the Hypersonic datasource. To add another
datasource, you have to declare it as a JMX MLet: see the manual.</para>
- <para>The second ARG of this MLet is the JNDI name of the datasource,
i.e. the name
+ <para>The second ARG of this MLet is the JNDI name of the datasource, i.e.
the name
you have to use to access it. To tell JAWS to use this
datasource, simply add in your jaws.xml file a <![CDATA[ <datasource> tag
with the JNDI name in it.]]></para>
- <para>According to the type of the database, you probably also want to
specify a
+ <para>According to the type of the database, you probably also want to
specify a
type mapping for this datasource. A type mapping tells JAWS
which jdbc types, which sql types to use for the storage of your cmp fields.
You just have to add a <![CDATA[ <type-mapping> tag with the name of the
type mapping in it. Type mappings for the most common databases are already
defined in jboss in a file called standardjaws.xml. Their
names are listed here:]]></para>
- <itemizedlist>
- <listitem>
- <para> Hypersonic SQL
- </para>
- </listitem>
- <listitem>
- <para> InstantDB
- </para>
- </listitem>
- <listitem>
- <para> Oracle
- </para>
- </listitem>
- <listitem>
- <para> PointBase
- </para>
- </listitem>
- <listitem>
- <para> PostgreSQL
- </para>
- </listitem>
- <listitem>
- <para> SOLID
- </para>
- </listitem>
- <listitem>
- <para> mySQL
- </para>
- </listitem>
- <listitem>
- <para> DB2/400
- </para>
- </listitem>
- <listitem>
- <para> MS SQLSERVER
- </para>
- </listitem>
- </itemizedlist>
- <para>For instance, if you want to use the Postgres Database that you
have deployed
+ <itemizedlist>
+ <listitem>
+ <para> Hypersonic SQL
+ </para>
+ </listitem>
+ <listitem>
+ <para> InstantDB
+ </para>
+ </listitem>
+ <listitem>
+ <para> Oracle
+ </para>
+ </listitem>
+ <listitem>
+ <para> PointBase
+ </para>
+ </listitem>
+ <listitem>
+ <para> PostgreSQL
+ </para>
+ </listitem>
+ <listitem>
+ <para> SOLID
+ </para>
+ </listitem>
+ <listitem>
+ <para> mySQL
+ </para>
+ </listitem>
+ <listitem>
+ <para> DB2/400
+ </para>
+ </listitem>
+ <listitem>
+ <para> MS SQLSERVER
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>For instance, if you want to use the Postgres Database that you have
deployed
in jboss.conf under the name MyPostgresPool, this is how
your jaws.xml file should look like:</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jaws>
<datasource>MyPostgresPool</datasource>
<type-mapping>PostgreSQL</type-mapping>
@@ -113,65 +113,65 @@
</jaws>
]]></programlisting>
- <para>If none of the predefined type mappings satisfies your needs,
you can define
+ <para>If none of the predefined type mappings satisfies your needs, you can
define
your own type-mapping.</para>
- </section>
- <section id="jaws-options">
- <title>JAWS Options</title>
- <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
+ </section>
+ <section id="jaws-options">
+ <title>JAWS Options</title>
+ <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
table for your beans at deployment time. It is turned on by
default. If the table already exists, JAWS will tell it to you, and
proceed.
</para>
- </listitem>
- <listitem>
- <para> remove-table: this tells JAWS whether it
has to remove (drop) the table
+ </listitem>
+ <listitem>
+ <para> remove-table: this tells JAWS whether it has to remove
(drop) the table
of your bean at undeployment time. It is turned off by
default. You may want to turn it on to clean the database. Note that if
you change a cmp-field in a bean, you will probably have to
drop the table and create it again, since the schema will have changed.
</para>
- </listitem>
- <listitem>
- <para> tuned-updates: when this option is turned
on (off by default) JAWS will only
+ </listitem>
+ <listitem>
+ <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>
- </listitem>
- <listitem>
- <para> read-only: tells whether JAWS will allow
client application to modify
+ </listitem>
+ <listitem>
+ <para> read-only: tells whether JAWS will allow client
application to modify
the state of your beans. Default is false. If true, JAWS will
perform no INSERT/UPDATE.
</para>
- </listitem>
- <listitem>
- <para> time-out: this option is only used when
read-only is true. In this
+ </listitem>
+ <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 <quote>time-out</quote> milliseconds.
</para>
- </listitem>
- <listitem>
- <para> select-for-update: when this option is
turned on, JAWS will do a
+ </listitem>
+ <listitem>
+ <para> select-for-update: when this option is turned on, JAWS
will do a
SQL "SELECT ... FOR UPDATE" when an entity bean is loaded creating a row lock in
the
datastore. This is very useful for synchronizing multiple instances of JBoss
running
against the same datastore. The default value for select-for-update is false and
also false when the bean is read-only.
</para>
- </listitem>
- <listitem>
- <para> debug: when this option is turned on (off
by default), JAWS will log all SQL
+ </listitem>
+ <listitem>
+ <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 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:
+ </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 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[
+ <programlisting><![CDATA[
<jaws>
<default-entity>
<create-table>true</create-table>
@@ -185,11 +185,11 @@
<jaws>
]]></programlisting>
- <para>Settings for a bean: to set an option for a particular bean, do
it in the
+ <para>Settings for a bean: to set an option for a particular bean, do it in
the
corresponding <![CDATA[ <entity> section. For example, if you want JAWS to
drop the table for your CustomerBean only, your xml file will contain:
]]></para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jaws>
...
<enterprise-beans>
@@ -202,32 +202,32 @@
<jaws>
]]></programlisting>
- <para>Note that the <![CDATA[ <ejb-name> tag must match the one
declared in
+ <para>Note that the <![CDATA[ <ejb-name> tag must match the one declared in
ejb-jar.xml.
]]></para>
- </section>
- <section>
- <title>Telling JAWS about your tables</title>
- <para>JAWS will use one different table for each of your CMP entity
beans. The table
+ </section>
+ <section>
+ <title>Telling JAWS about your tables</title>
+ <para>JAWS will use one different table for each of your CMP entity beans.
The table
for one entity bean will contain one column for each of the
CMP fields of this entity.</para>
- <para>By default, JAWS will create the tables for you. The name of the
table will be
+ <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 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 <xref linkend="jaws-type-mappings"/>)</para>
- <para>However, you may want to override this behavior and tell JAWS
which
+ <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>
- <section>
- <title>Example 1</title>
- <para>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>
@@ -252,15 +252,15 @@
</jaws>
]]></programlisting>
- </section>
+ </section>
- <section>
- <title>Example 2</title>
- <para>Your bank account bean has a String field to hold the
VISA card
+ <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>
@@ -278,34 +278,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 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
+ </section>
+ </section>
+ <section>
+ <title>Declaring finders</title>
+ <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
+ </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
@@ -313,9 +313,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>
@@ -340,12 +340,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>
@@ -361,29 +361,29 @@
</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>
- <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>
+ <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
@@ -395,11 +395,11 @@
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[
+ </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
@@ -408,8 +408,8 @@
<order></order>
</finder>
]]></programlisting>
- <para>T-SQL example:</para>
- <programlisting><![CDATA[
+ <para>T-SQL example:</para>
+ <programlisting><![CDATA[
<finder>
<name>findByProvinceAndType</name>
<query>inner join CreatureEJBTable ON CreatureEJBTable.id =
@@ -418,29 +418,29 @@
<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>
+ </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>Advanced options for declared finders</title>
@@ -458,9 +458,17 @@
optimization, simply add <read-ahead>true</read-ahead> to
your finder declaration. Note that as of the same version, you can override
this option for the autogenerated findAll method as well.</para>
+ <para>Note that the data preloaded by this feature is tied to the
+ transaction it is loaded in. In other words, data preloaded by one
+ transaction is not seen by another transaction. One practical implication
+ of this is that calling a finder from client code will not take
+ advantage of this feature. It may be feasable in some circumstances to
+ declare the finder and an entity's getter methods as 'Supports' in which
+ case the data preloaded by the finder will not be tied to any transaction
+ and may be available when the getter methods are called.</para>
- <para>This is an example jaws.xml showing use of this
option</para>
- <programlisting><![CDATA[
+ <para>This is an example jaws.xml showing use of this option</para>
+ <programlisting><![CDATA[
<jaws>
<enterprise-beans>
<entity>
@@ -484,22 +492,22 @@
]]></programlisting>
</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>
+ <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
@@ -512,10 +520,10 @@
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>
+ </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
@@ -523,49 +531,49 @@
}
}
</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>
+ </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 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
+ </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
don't, so you have to map a java.lang.Boolean to a CHAR(5).</para>
- <para>Many type mappings are already defined in standardjaws.xml. If
you want to
+ <para>Many type mappings are already defined in standardjaws.xml. If you want
to
define a new one, I advise you to modify one of these: copy it
and paste it to the <![CDATA[<type-mappings> section of your jaws.xml
file.]]></para>
- <para>A type mapping is constituted of several mappings, one for each
java Class
+ <para>A type mapping is constituted of several mappings, one for each java
Class
that you need to map. If your class is not found in the mappings,
JAWS will use the mapping for java.lang.Object.</para>
- <para>A mapping comes in 3 parts:</para>
- <itemizedlist>
- <listitem>
- <para> the <![CDATA[<java-type> is the name of
the java class you want to
+ <para>A mapping comes in 3 parts:</para>
+ <itemizedlist>
+ <listitem>
+ <para> the <![CDATA[<java-type> is the name of the java class you
want to
map.
]]></para>
- </listitem>
- <listitem>
- <para> the <![CDATA[<jdbc-type> is the jdbc type
to use. Its value must be
+ </listitem>
+ <listitem>
+ <para> the <![CDATA[<jdbc-type> is the jdbc type to use. Its
value must be
one of the fields of java.sql.Types (e.g. BIT, CHAR...). This jdbc type will
be used by JAWS to determine which method to call on PreparedStatement
and ResultSet for INSERT / UPDATE / SELECT
queries.
]]></para>
- </listitem>
- <listitem>
- <para> the <![CDATA[<sql-type> is the actual
type in the database. This
+ </listitem>
+ <listitem>
+ <para> the <![CDATA[<sql-type> is the actual type in the
database. This
value will only be used when JAWS creates your table.
]]></para>
- </listitem>
- </itemizedlist>
- <para>If the type mapping we provide for a particular database is
faulty and you
+ </listitem>
+ </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 jbosscmp mailing list.</para>
- </section>
+ </section>
</chapter>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
