****************************************
		README
****************************************

The custom.zip contains two files, custom.jar and customEx.jar.  
The file custom.jar contains the java source code that supports custom
queries.  The customEx.jar conatains two examples of its use.  Import 
custom.jar before customEx.jar.  

How to create a custom query?

1.  Add a method on the HomeImpl that will be called to execute your query
(e.g., 'retrieveStudentsBornBefore(Date)'.  This method will return the result of 
calling 'customQuery'.  The 'customQuery' method can take one argument, String, or two
arguments, String and Object[].'  You can use either method depending on whether or not
your custom query requires arguments.  The string argument will be the name of the 
method that will be added to the query pool class (see step 3).  The arguments will
be the arguments used in the "WHERE" clause of the query, in the same order that 
they appear in the where clause.

2.  Add a method to the query pool class to return the desired SQL string 
(e.g., 'CeducCLIDB2VapStudentQueryPool.studentsBornBeforeSqlString').  This sql string will
be similar to the 'allInstancesSqlString' except with a "WHERE" clause.

3.  Add the query method to the query pool class 
(e.g., 'CeducCLIDB2VapStudentQueryPool.studentsBornBeforeQuery').  This query method
will be very similar to the 'allInstancesQuery'.  You will build the query using the 
SQL string from step 2.

If you have pessimistic locking enabled for the class with the custom query, then you
must also supply the locking query and query string.  Follow steps 4 and 5.

WITH PESSIMISTIC LOCKING
4.  Add a method to the query pool class to return the desired SQL string that will be
used to lock the rows obtained in your custom query (see step 2 and 3) 
(e.g., 'CeducCLIDB2VapStudentQueryPool.studentsBornBeforeForLockSqlString').  This
query will have the exact same "WHERE" clause as the method from step 2.  In our
example, to lock the rows, we simply perform an update setting the primary key to itself.

5.  Add the locking query method to the query pool class
(e.g., 'CeducCLIDB2VapStudentQueryPool.studentsBornBeforeQueryForLocking').  This method
name MUST follow a naming scheme.  The name of the method will be the same name as the
query method (see step 3) with 'ForLocking' added to the end.  This method will call
the SQL method from step 4 when creating the DatabaseQuerySpec (note that this is a 
DatabaseQuerySpec and not a DatabaseSelectQuerySpec).
