User: tobias
Date: 01/01/03 09:21:54
Modified: documentation jawsxml_howto.html
Added: documentation HowTo-JAWS-JoinQueries.html
HowTo-JAWS-UseCustomFinders.html
Log:
added howtos for JAWS custom finders and join queries.
Thanks to Michel de Groot
Revision Changes Path
1.3 +12 -2 newsite/documentation/jawsxml_howto.html
Index: jawsxml_howto.html
===================================================================
RCS file: /products/cvs/ejboss/newsite/documentation/jawsxml_howto.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- jawsxml_howto.html 2000/11/28 19:25:54 1.2
+++ jawsxml_howto.html 2001/01/03 17:21:54 1.3
@@ -15,7 +15,9 @@
<li><a href="#options">Set a bunch of options concerning jaws behavior</a>
<li><a href="#names">Specify how JAWS should build/use your tables</a>
<li><a href="#finders">Define finders to access you entity beans</a>
-<li><a href="#typemappings">Define a type mapping</a></ul></p>
+<li><a href="#typemappings">Define a type mapping</a>
+<li><a href="#advanced">Advanced: Define custom finders and join queries</a>
+</ul></p>
<p>If you want to know everything about <em>jaws.xml</em>, see the <a
href="jaws.dtd">Jaws.xml DTD</a>. The general structure of the <em>jaws.xml</em> can
be found <a href="jaws_structure.txt">here</a>. All parts of this file are optional:
you only provide what you need!</p>
@@ -241,7 +243,15 @@
<p>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 <a href="mailing.htm">JAWS mailing list</a>.
+<h3><a name="advanced">Advanced: Defining custom finders and join queries</a></h3>
+<ul>
+<li><a href="HowTo-JAWS-UseCustomFinders.html">custom finders with JAWS CMP for EJB
1.1</a></li>
+<li><a href="HowTo-JAWS-JoinQueries.html">join queries with JAWS CMP for EJB
1.1</a></li>
+</ul>
<br>
-<hr>Author: <a href="mailto:[EMAIL PROTECTED]">S�bastien Alborini</a>
+<hr>Author: <a href="mailto:[EMAIL PROTECTED]">S�bastien Alborini</a> and
others.
</body>
</html>
+
+
+
1.1 newsite/documentation/HowTo-JAWS-JoinQueries.html
Index: HowTo-JAWS-JoinQueries.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
<TITLE>How-To: Use join queries with JAWS CMP in EJB 1.1</TITLE>
<META NAME="AUTHOR" CONTENT="Michel">
<META NAME="CREATED" CONTENT="20001231;8300000">
</HEAD>
<BODY LINK="#0000ff">
<H1>How-To: Use join queries with JAWS CMP for EJB 1.1</H1>
<P>You can 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.</P>
<H2>About this documentation</H2>
<P>Author:</P>
<P>Michel de Groot</P>
<P><U><A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A></U>
or <U><A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A></U></P>
<P><BR>
</P>
<P>Version:</P>
<P>1.0</P>
<H2>Applies to</H2>
<P>JBoss 2.1</P>
<P>JBoss 2.0 BETA-PROD3 with following CVS
updates:</P>
<P>org.jboss.ejb.plugins.jaws.jdbc.JDBCDefindedFinderCommand.java
v1.6</P>
<H2>Standards compliance</H2>
<P>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.</P>
<H2>Tested configurations</H2>
<P>JBoss 2.0 BETA-PROD3 (with
modifications available in JBoss 2.1) run by Sun JRE 1.3.0_01 Client
HotSpot on Windows NT 4.0sp3 with MS Access 97 connected by Sun
JdbcOdbc driver in JDK 1.2.2</P>
<H2>Special configuration notes</H2>
<P>You must use a database which has
support for SQL92 (most databases do) or T-SQL join queries.
</P>
<H2>Using the feature step by step</H2>
<P>1. Define a finder method in the EJB's
Home class. Example:<BR>
<pre>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;
}</pre>
<P><BR>
</P>
<P>As you can see, this is an ordinary
finder method definition.
</P>
<P><BR>
</P>
<P>2. Define the finder in jaws.xml.
</P>
<P>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).</P>
<P><BR>
</P>
<P>Generic SQL92 example:</P>
<pre><finder>
<name>findByProvinceAndType</name>
<query>,CreatureEJBTable
WHERE CreatureEJBTable.id = PopulationEJBTable.creatureId AND
provinceId={0} AND type={1}</query>
<order></order>
</finder></pre>
<P><BR>
</P>
<P>T-SQL example:</P>
<pre><finder>
<name>findByProvinceAndType</name>
<query>inner join CreatureEJBTable ON CreatureEJBTable.id =
PopulationEJBTable.creatureId WHERE provinceId={0} AND
type={1}</query>
<order></order>
</finder></pre>
<P><BR>
</P>
<P>You must be aware of the following
issues:</P>
<OL>
<LI><P>The query must start with
'<b>,<table name to join with></b>' (for SQL92 query) or with
'<b>inner
join <table name to join with></b>' (for T-SQL). JAWS will append
the proper select statement.</P>
<LI><P>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.</P>
<LI><P>The query must contain the WHERE
statement followed by the conditions of the query.</P>
<LI><P>The query always delivers
instances of the Entity Bean on which the finder is defined.</P>
<LI><P>Field names must be fully
qualified with table name if ambiguity can arise.</P>
</OL>
<P><BR>
</P>
<P>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.</P>
</BODY>
</HTML>
1.1 newsite/documentation/HowTo-JAWS-UseCustomFinders.html
Index: HowTo-JAWS-UseCustomFinders.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
<TITLE>How-To: Use join queries with JAWS CMP in EJB 1.1</TITLE>
<META NAME="AUTHOR" CONTENT="Michel">
<META NAME="CREATED" CONTENT="20001231;9000000">
</HEAD>
<BODY LINK="#0000ff">
<H1>How-To: Use custom finders with JAWS CMP for EJB 1.1</H1>
<P STYLE="margin-bottom: 0in">At times, 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.</P>
<P><BR>
</P>
<P>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.</P>
<H2>About this documentation</H2>
<P>Author:</P>
<P>Michel de Groot</P>
<P><U><A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A></U>
or <U><A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A></U></P>
<P><BR>
</P>
<P>Version:</P>
<P>1.0</P>
<H2>Applies to</H2>
<P>JBoss 2.1</P>
<P>JBoss 2.0 BETA-PROD3 with following CVS
updates:</P>
<P>org.jboss.ejb.plugins.jaws.bmp.CustomFindByEntitiesCommand.java
v1.0</P>
<P>org.jboss.ejb.plugins.jaws.jdbc.JDBCFindEntitiesCommand.java
v1.6</P>
<H2>Standards compliance</H2>
<P>This feature is required in EJB 1.1. It
is missing in JBoss 2.0.</P>
<H2>Tested configurations</H2>
<P>JBoss 2.0 BETA-PROD3 (with
modifications available in JBoss 2.1) run by Sun JRE 1.3.0_01 Client
HotSpot on Windows NT 4.0sp3 with MS Access 97 connected by Sun
JdbcOdbc driver in JDK 1.2.2</P>
<H2>Special configuration notes</H2>
<P>Using this patch might break existing
applications. See the 'Applying Patch for custom finders with JAWS
CMP for EJB1.1' document.</P>
<H2>Using the feature step by step</H2>
<P>1. Define a finder method in the EJB's
Home class. Example:<BR><BR>
<pre>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;
}</pre>
<P><BR>
</P>
<P>As you can see, this is an ordinary
finder method definition.
</P>
<P><BR>
</P>
<P>2. Implement the finder method in the
EJB's implementation class. Example:</P>
<pre>public class PopulationEJB implements EJBObject {
public Collection ejbFindByProvinceAndType(String provinceId, int type) {
// .. fill Collection with primary keys of result objects
return aResultCollection;
}
}</pre>
<P><BR>
</P>
<P>You must be aware of the following
issues:</P>
<OL>
<LI><P>The finder's name must begin with
'findBy' in the EJB's Home interface.</P>
<LI><P>Custom finders will ALWAYS be used
if present. They override automatic or defined finders. This is
according to the EJB 1.1 specification.</P>
</OL>
<P><BR>
</P>
<P><BR>
</P>
</BODY>
</HTML>
