ibatis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jgbut...@apache.org
Subject svn commit: r648102 [3/34] - in /ibatis/trunk/java/tools/ibator/core: ./ build/ devlib/ doc/ htmldoc/ htmldoc/configreference/ htmldoc/generatedobjects/ htmldoc/reference/ htmldoc/usage/ src/ src/org/ src/org/apache/ src/org/apache/ibatis/ src/org/apac...
Date Tue, 15 Apr 2008 02:33:09 GMT
Added: ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/extendingExampleClass.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/extendingExampleClass.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/extendingExampleClass.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/extendingExampleClass.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,226 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Extending the Example Classes</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="extendingExampleClass.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>Extending the Example Classes</h1>
+<p>In some cases it may be desirable to extended the generated example classes.
+You may want to add criterion that are specific to your database (such as Oracle
+ROWNUM support), or add criterion that are not automatically generated (such as
+a case insensitive search).  In situations like these, you may extend the generated
+example class to add these additional criteria.</p>
+
+<h2>General Principles</h2>
+<p>iBATOR generates an "example" class for each table, unless instructed otherwise
+in the configuration.  The "example" class is used to generate a dynamic where
+clause for use in the
+<code>selectByExample</code>, <code>deleteByExample</code>,
+<code>updateByExample</code>, and <code>countByExample</code> statements.
+The standard "example" class includes functionality for all standard SQL predicates.
+In some cases, it may be desirable to add additional predicates for the
+specific needs of your application.  This may include adding support for non-standard
+predicates, or for using database specific functions in your where clauses.</p>
+
+<p>The generated "example" class includes a nested inner class where the actual
+functionality of the predicates exists.  This inner class is always named <code>Criteria</code>.
+If you wish to add predicates to dynamic where clauses, you must extend
+both the "example" class and the <code>Criteria</code> class.  For example, suppose there is a
+table called CUSTOMER.  Typically, iBATOR would generate a class named
+<code>CustomerExample</code>.  To add functionality to the <code>CustomerExample</code> class, you must
+follow these steps:</p>
+<ul>
+  <li>Extend the <code>CustomerExample</code> class</li>
+  <li>Extend the nested <code>CustomerExample$Criteria</code> class</li>
+  <li>Override the <code>createCriteriaInternal()</code> method of the
+      <code>CustomerExample</code> class so that the extended Criteria
+      class is created</li>
+  <li>Add functionality to the extended Criteria class</li>
+</ul>
+
+<p>The following code fragment shows the basic requirements of an extended
+example class:</p>
+<pre>
+import ibatortest.generated.CustomerExample;
+
+public class ExtendedCustomerExample extends CustomerExample {
+
+  @Override
+  protected Criteria createCriteriaInternal() {
+    return new ExtendedCriteria();
+  }
+
+  public static class ExtendedCriteria extends CustomerExample.Criteria {
+
+    // add additional predicate support here...
+
+  }
+}
+</pre>
+
+<p>Once the basic class is created, adding additional predicates is a matter
+of adding additional methods the the extended <code>Criteria</code> class.</p>
+
+<h2>Adding Predicates</h2>
+<p>iBATOR generates a dynamic SQL fragment that allows virtually unlimited
+where clauses to be created at run-time.  To accomplish this, the generated SQL
+fragment supports four broad types of SQL predicates.  For each type of
+SQL predicate, there is a corresponding method in the generated <code>Criteria</code> class
+that can be used to add a predicate to the dynamic where clause.</p>
+
+<h3>1. Simple String Substitution</h3>
+<p>This type of predicate is used when there is no need for a property
+from the parameter object to be substituted into the where clause.  Examples
+include:</p>
+<p><code>FIRST_NAME is null</code><br/>
+   <code>LAST_NAME is not null</code></p>
+
+<p>The generated <code>Criteria</code> class method for this predicate is:</p>
+&nbsp;&nbsp;&nbsp;<code>addCriterion(String anyString)</code>
+
+<p>Where "anyString" is the string to be substituted into the where clauses.
+This method can be used to add any kind of test to the generated where clause.</p>
+
+<p>For example, suppose you wanted to use the SOUNDEX function to do a "sounds like"
+name search.  In MySQL, the predicate should look like this:</p>
+<code>SOUNDEX(FIRST_NAME) = SOUNDEX('frod')</code>
+<p>This predicate is too complex to use one of the other methods, so it must
+be inserted into the where clause by simple string substitition.  Add the following
+method to the <code>ExtendedCriteria</code> for this functionality:</p>
+<pre>
+public ExtendedCriteria andFirstNameSoundsLike(String value) {
+  StringBuffer sb = new StringBuffer("SOUNDEX(FIRST_NAME) = SOUNDEX('");
+  sb.append(value);
+  sb.append("')");
+
+  addCriterion(sb.toString());
+
+  return this;
+}
+</pre>
+
+<p>The following code shows the use of this new functionality with the <code>selectByExample</code> method:</p>
+<pre>
+ExtendedExample example = new ExtendedExample();
+ExtendedCriteria criteria = (ExtendedCriteria) example.createCriteria();
+criteria.andFirstNameSoundsLike("frod");
+List results = selectByExample(example);
+</pre>
+
+<p>This method can be used to add virtually any predicate to a where clause.
+However, it is generally better to use parameter substitution if possible because
+the problems of formatting different datatypes properly (most notably
+dates, times, and timestamps).  Also, there is a chance of SQL
+injection issues with this method if you expose a too generic method.
+If at all possible, we suggest using one of the other methods listed below.</p>
+
+<h3>2. Single Parameter Predicates</h3>
+<p>This type of predicate is used when there is a single property
+   from the parameter object to be substituted into the where clause.  Examples
+   include</p>
+<p><code>FIRST_NAME = ?</code><br/>
+   <code>LAST_NAME &lt;&gt; ?</code></p>
+
+<p>The generated <code>Criteria</code> class method for this predicate is:</p>
+<p>&nbsp;&nbsp;&nbsp;<code>addCriterion(String anyString, Object anyObject, String propertyName)</code></p>
+
+<p>Where:</p>
+<dl>
+  <dt><b>anyString</b></dt>
+  <dd>is the string to be substituted into the where clause before a parameter substitution</dd>
+  <dt><b>anyObject</b></dt>
+  <dd>is the Object to be substituted into the where clause after the string substitution</dd>
+  <dt><b>propertyName</b></dt>
+  <dd>is a string denoting the property name related to this clause.  This String is only used
+      in potential error messages.</dd>
+</dl>
+
+This method can be used to add simple tests related to a single parameter to the generated where clause.</p>
+
+<p>For example, suppose you wanted to perform a case insensitve search on certain columns.
+In MySQL, the predicate could look like this:</p>
+<code>upper(FIRST_NAME) like ?</code>
+<p>This predicate fits the capabilities of a single parameter predicate - where the predicate
+is a string value followed by a single parameter.  Add the following
+method to the <code>ExtendedCriteria</code> for this functionality:</p>
+<pre>
+public ExtendedCriteria andFirstNameLikeInsensitive(String value) {
+  addCriterion("upper(FIRST_NAME) like",
+    value.toUpperCase(), "firstName");
+
+  return this;
+}
+</pre>
+
+<p>The following code shows the use of this new functionality with the <code>selectByExample</code> method:</p>
+<pre>
+ExtendedExample example = new ExtendedExample();
+ExtendedCriteria criteria = (ExtendedCriteria) example.createCriteria();
+criteria.andFirstNameLikeInsensitive("fred%");
+List results = selectByExample(example);
+</pre>
+
+<h3>3. List Predicates</h3>
+<p>List predicates are used to add a variable sized list of values as parameters to a where
+clause.  Examples include:</p>
+<p><code>FIRST_NAME IN (?, ?, ?)</code><br/>
+<code>LAST_NAME NOT IN (?, ?, ?, ?)</code></p>
+
+<p>This predicate is less flexible then the others because it is included specifically
+for the "in" and "not in" standard predicates.  Nevertheless, if you find some use for it
+the corresponding method in the <code>Criteria</code> class is as follows:</p>
+
+<p>&nbsp;&nbsp;&nbsp;<code>addCriterion(String anyString, List listOfObjects, String propertyName)</code></p>
+
+<p>Where:</p>
+<dl>
+  <dt><b>anyString</b></dt>
+  <dd>is the string to be substituted into the where clause before a parameter substitution</dd>
+  <dt><b>listOfObjects</b></dt>
+  <dd>is the List of Objects to be substituted into the where clause after the string substitution
+      (an open parenthesis will be appended before the list, list items will be comma delimited,
+      and a close parenthesis will be appended after the list).</dd>
+  <dt><b>propertyName</b></dt>
+  <dd>is a string denoting the property name related to this clause.  This String is only used
+      in potential error messages.</dd>
+</dl>
+
+<h3>4. Between Predicates</h3>
+<p>Between predicates are used to add a two parameters to a where
+clause in a specific format.  Examples include:</p>
+<p><code>FIRST_NAME BETWEEN ? AND ?</code><br/>
+<code>LAST_NAME NOT BETWEEN ? AND ?</code></p>
+
+<p>This predicate is less flexible then the others because it is included specifically
+for the "between" and "not between" standard predicates.  Nevertheless, if you find some use for it
+the corresponding method in the <code>Criteria</code> class is as follows:</p>
+
+<p>&nbsp;&nbsp;&nbsp;<code>addCriterion(String anyString, Object object1, Object object2, String propertyName)</code></p>
+
+<p>Where:</p>
+<dl>
+  <dt><b>anyString</b></dt>
+  <dd>is the string to be substituted into the where clause before a parameter substitution</dd>
+  <dt><b>object1</b></dt>
+  <dd>is the objects to be substituted into the where clause after the string substitution
+      (the word "and" will be appended after this object).</dd>
+  <dt><b>object2</b></dt>
+  <dd>is the objects to be substituted into the where clause after the word "and".</dd>
+  <dt><b>propertyName</b></dt>
+  <dd>is a string denoting the property name related to this clause.  This String is only used
+      in potential error messages.</dd>
+</dl>
+
+
+
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javadao.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javadao.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javadao.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javadao.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,87 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>iBATOR Generated Java DAO Classes</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="javadao.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>iBATOR Generated Java DAO Classes</h1>
+<p>iBATOR generates DAO classes of several types.  For each table in the configuration, iBATOR
+generates a Java Interface that describes DAO methods, and a Java Class that implements the
+generated interface.  Generating DAO objects is optional, and is controlled by the
+<code>&lt;daoGenerator&gt;</code> configuration element.  iBATOR can generate DAOs of the following
+types:
+</p>
+<ul>
+  <li>IBATIS - for use with the iBATIS DAO Framework</li>
+  <li>SPRING - for use with the Spring Framework</li>
+  <li>GENERIC-CI - with no dependencies beyond the iBATIS Data Mapper</li>
+  <li>GENERIC-SI - also with no dependencies beyond the iBATIS Data Mapper</li>
+</ul>
+
+<p>Every field and method generated by iBATOR includes the non-standard JavaDoc tag
+<code>@ibatorgenerated</code>.  On subsequent runs of iBATOR, every field and method that
+includes this JavaDoc tag will be deleted and replaced.  Any other field or method in the
+class will be untouched by iBATOR.
+With this in mind, you can add other fields and methods to the classes without fear of losing them in
+subsequent runs of iBATOR - simply DO NOT include the <code>@ibatorgenerated</code>
+JavaDoc tag on anything that you add to the class.</p>
+
+<p>Note: in the following descriptions, the term "BLOB" is used to refer to any column
+with a data type of BLOB, CLOB, LONGVARCHAR, or LONGVARBINARY.</p>
+
+<h2>Methods Common to All DAO Types</h2>
+<p>Depending on the specifics of the table, and the configuration options, the DAO generator
+will generate these methods:</p>
+<ul>
+  <li>countByExample</li>
+  <li>deleteByPrimaryKey</li>
+  <li>deleteByExample</li>
+  <li>insert</li>
+  <li>selectByPrimaryKey</li>
+  <li>selectByExample</li>
+  <li>selectByExampleWithBLOBs</li>
+  <li>updateByPrimaryKey (with an override to specify whether or not to update BLOB columns)</li>
+  <li>updateByPrimaryKeySelective (will only update non-null fields in the parameter class)</li>
+  <li>updateByExample (with an override to specify whether or not to update BLOB columns)</li>
+  <li>updateByExampleSelective (will only update non-null fields in the parameter class)</li>
+</ul>
+<p>iBATOR attempts to make it easier to deal with tables that contain BLOBs by generating
+different objects and methods so that you can use the BLOB fields, or ignore them, depending
+on the situation.</p>
+<p>See the
+<a href="exampleClassUsage.html">Example Class Usage</a>
+page for an example of using the <code>selectByExample</code> method.</p>
+
+<h2>IBATIS DAOs</h2>
+<p>iBATIS DAOs depend on the iBATIS DAO framework (an optional part of iBATIS).
+They extend the SqlMapDaoTemplate class and are
+constructed with an instance of the DAOManager object, and call methods in their super class
+to execute the different statements.</p>
+<p>iBATOR does not update the "dao.xml" file for you - you must add the appropriate entries
+manually.</p>
+<p>The iBATIS DAO framework is a very elementary IoC container and is useful if you
+are not already using something like Spring or PicoContainer to manage dependencies.</p>
+
+<h2>SPRING DAOs</h2>
+<p>SPRING DAOs depend on the Spring framework.  They extend Spring's SqlMapClientDaoSupport class,
+and are constructed by the Spring container.</p>
+
+<h2>GENERIC-CI DAOs</h2>
+<p>GENERIC-CI DAOs call methods in iBATIS' SqlMapClient interface directly.  An instance of the
+interface is supplied through constructor injection.</p>
+
+<h2>GENERIC-SI DAOs</h2>
+<p>GENERIC-SI DAOs call methods in iBATIS' SqlMapClient interface directly.  An instance of the
+interface is supplied through setter injection.</p>
+
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javamodel.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javamodel.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javamodel.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/javamodel.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,135 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>iBATOR Generated Java Model Classes</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="javamodel.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>iBATOR Generated Java Model Classes</h1>
+<p>iBATOR generates Java classes that correspond to the fields in a database table.
+The generated classes are a type of domain object, but should in no way be confused
+with a rich domain model (see the <a href="../philosophy.html">Philosophy</a> page
+for more on this subject).  iBATOR generates different types of "domain" objects based on
+the characteristics of the table and configuration options.</p>
+
+<p>Every field and method generated by iBATOR includes the non-standard JavaDoc tag
+<code>@ibatorgenerated</code>.  When run as an Eclipse plugin,
+on subsequent runs of iBATOR every field and method that
+includes this JavaDoc tag will be deleted and replaced.  Any other field or method in the
+class will be untouched by iBATOR.
+With this in mind, you can add other fields and methods to the classes without fear of losing them in
+subsequent runs of iBATOR - simply DO NOT include the <code>@ibatorgenerated</code>
+JavaDoc tag on anything that you add to the class.</p>
+<p>Outside of the Eclipse plugin, Java files need to be merged by hand, but you can use the
+<code>@ibatorgenerated</code> JavaDoc tag to know what is safe to delete from a prior
+version of a file.</p>
+<p>The following sections describe the different types of "domain" classes that will be
+generated by iBATOR.  iBATOR will generate different types of domain classes depending
+on the value of the <code>defaultModelType</code> attribute of the
+<a href="../configreference/ibatorContext.html">&lt;ibatorContext&gt;</a>
+configuration element and the <code>modelType</code> attribute of the
+<a href="../configreference/table.html">&lt;table&gt;</a>
+configuration element.</p>
+
+<p>Any column ignored by an
+<a href="../configreference/ignoreColumn.html">&lt;ignoreColumn&gt;</a>
+configuration element will
+by ignored and not added to any generated Java class.</p>
+
+<p>Note: in the following descriptions, the term "BLOB" is used to refer to any column
+with a data type of BLOB, CLOB, LONGVARCHAR, or LONGVARBINARY.</p>
+
+<h2>Primary Key Class</h2>
+<p>This class will contain properties for each field in the primary key of a table.
+The property names will be generated automatically by iBATOR, and based on the column name
+in the table.  The iBATOR generated property names can be overridden with a
+<code>&lt;columnOverride&gt;</code> configuration element.
+</p>
+<p>The name of the class will be <code>&laquo;TableName&raquo;Key</code> by default, or
+<code>&laquo;domainObjectName&raquo;Key</code> if the <code>domainObjectName</code>
+attribute is specified on the <code>&lt;table&gt;</code> configuration element.</p>
+
+<p>This class will be generated in the hierarchical model if the table has a primary key.
+This class will be generated in the conditional model if the table has more
+then one column in the primary key.  This class will not be generated in the flat
+model.</p>
+
+<h2>Record Class</h2>
+<p>This class will contain properties for each non-BLOB and non-primary key column in the table.
+The class will extend the primary key class, if there is a primary key.
+The property names will be generated automatically by iBATOR, and based on the column name
+in the table.  The iBATOR generated property names can be overridden with a
+<code>&lt;columnOverride&gt;</code> configuration element.</p>
+
+<p>The name of the class will be <code>&laquo;TableName&raquo;</code> by default, or
+<code>&laquo;domainObjectName&raquo;</code> if the <code>domainObjectName</code>
+attribute is specified on the <code>&lt;table&gt;</code> configuration element.</p>
+
+<p>This class will be generated in the hierarchical model if the table has non-BLOB
+and non-primary key columns.  This class will be generated in the conditional model
+if the table has non-BLOB and non-primary key columns, or if there is only
+one primary key column or one BLOB column.  This class is always generated in the
+flat model.</p>
+
+<h2>Record With BLOBs Class</h2>
+<p>This class will contain properties for each BLOB column in the table.
+The class will extend the record class, if there are other non-BLOB and non-Primary Key
+columns in the table, else it will extend the primary key (note that iBATOR does not support
+tables that only contain BLOB columns).
+The property names will be generated automatically by iBATOR, and based on the column name
+in the table.  The iBATOR generated property names can be overridden with a
+<code>&lt;columnOverride&gt;</code> configuration element.</p>
+
+<p>This class will be the return value from the <code>selectByPrimaryKey</code> method,
+or the <code>selectByExampleWithBLOBs</code> method.</p>
+
+<p>The name of the class will be <code>&laquo;TableName&raquo;WithBLOBs</code> by default, or
+<code>&laquo;domainObjectName&raquo;WithBLOBs</code> if the <code>domainObjectName</code>
+attribute is specified on the <code>&lt;table&gt;</code> configuration element.</p>
+
+<p>This class will be generated in the hierarchical model if the table has any BLOB columns.
+This class will be generated in the conditional model if the table has more than one
+BLOB column.  This class will not be generated in the flat model.</p>
+
+<h2>Example Class</h2>
+<p>This class is used to work with iBATOR's dynamic select capability.
+The class holds a set of criteria that are used to generate a dynamic WHERE clause at runtime
+for the following methods:</p>
+<ul>
+  <li><code>selectByExample</code></li>
+  <li><code>selectByExampleWithBLOBs</code></li>
+  <li><code>deleteByExample</code></li>
+  <li><code>countByExample</code></li>
+  <li><code>updateByExample</code></li>
+</ul>
+
+<p>This class may or may not extend one of the other generated domain classes based on the
+table configuration, and the value of the <code>generatorSet</code>
+attribute of the <a href="../configreference/ibatorContext.html">&lt;ibatorContext&gt;</a>
+configuration element.</p>
+
+<p>The name of the class will be <code>&laquo;TableName&raquo;Example</code> by default, or
+<code>&laquo;domainObjectName&raquo;Example</code> if the <code>domainObjectName</code>
+attribute is specified on the <code>&lt;table&gt;</code> configuration element.</p>
+
+<p>This class will be generated if any of the <code>*ByExample</code>
+methods are enabled.  Note that the configuration elements produced by these options can grow quite large.
+With the "Java2" or "Java5" generator sets
+the example class itself can grow quite large, but the DAO methods are small as is the generated XML
+fragment.
+If you do not plan to use the dynamic WHERE clause features of iBATOR, you may prefer to
+disable the generation of these methods.</p>
+
+<p>See the <a href="exampleClassUsage.html">Example Class Usage</a>
+page for details on using the example class.</p>
+
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/results.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/results.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/results.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/results.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,28 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Using the iBATOR Generated Objects</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="results.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>Using the iBATOR Generated Objects</h1>
+<p>iBATOR generates three types of objects:</p>
+<ol>
+  <li><a href="javamodel.html">Java Model Classes</a></li>
+  <li><a href="sqlmap.html">SQL Map Files</a></li>
+  <li><a href="javadao.html">Java DAO Classes (optional)</a></li>
+</ol>
+
+<p>The individual pages describe these objects, and their usage.  Also see the
+<a href="exampleClassUsage.html">Example Class Usage</a> page
+for information on using the example classes.</p>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/sqlmap.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/sqlmap.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/sqlmap.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/generatedobjects/sqlmap.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,191 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>iBATOR Generated SQL Map Files</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="sqlmap.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>iBATOR Generated SQL Map Files</h1>
+<p>iBATOR generates SQL Map files that conform to iBATIS' SQL Map DTD.  The files contain many different
+elements based on the characteristics of the table, and on the configuration options you specify.
+iBATOR generates a different SQL Map file for every table you specify.  The name space of the
+SQL Map is the name of the table (qualified by schema and catalog if present).  iBATOR does not
+add the SQL Map entries to the iBATIS SQLMapConfig file - you must do that manually.</p>
+
+<p>Every element generated by iBATOR has an id that is prefixed with the string <code>"ibatorgenerated_"
+</code>.  On subsequent runs of iBATOR, every element with an id whose prefix is
+<code>"ibatorgenerated_"</code>
+will be deleted and replaced.  Any other element in the SQL Map will be untouched by iBATOR.
+With this in mind, you can add other elements to the file without fear of losing them in
+subsequent runs of iBATOR - simply give your custom elements an id that DOES NOT start with
+<code>"ibatorgenerated_"</code>.</p>
+<p>The following sections describe the elements that will be generated by iBATOR.</p>
+
+<p>Note: in the following descriptions, the term "BLOB" is used to refer to any column
+with a data type of BLOB, CLOB, LONGVARCHAR, or LONGVARBINARY.</p>
+
+<h2>Result Map</h2>
+<p>This element is used to map table columns to properties of the generated Java model object.
+The result map (and corresponding select statements) will not contain:</p>
+<ul>
+  <li>Any field that has been ignored by the <code>&lt;ignoreColumn&gt;</code> configuration element</li>
+  <li>Any BLOB field from the table (see the result map with BLOBs element)</li>
+</ul>
+<p>The columns will be mapped according the configuration element <code>&lt;columnOverride&gt;</code> if it exists
+for the specific column.  If the override does not exist, then a default property name and JDBC type
+will be used.</p>
+<p>It is acceptable to extend this result map if you code any
+custom join queries in the SQL map.  This is a common use case and is expected.</p>
+<p>This element will be generated if either the select by example, or select by primary key statements
+are enabled.</p>
+
+<h2>Result Map With BLOBs</h2>
+<p>The element extends the base result map, and adds any BLOB fields that exist in the table.
+We do this because we offer different versions of the select by example statement depending on
+whether or not you want to return the BLOB fields in those queries.</p>
+
+<p>The result map (and corresponding select statements) will not contain:</p>
+<ul>
+  <li>Any field that has been ignored by the <code>&lt;ignoreColumn&gt;</code> configuration element</li>
+</ul>
+<p>The columns will be mapped according the configuration element <code>&lt;columnOverride&gt;</code> if it exists
+for the specific column.  If the override does not exist, then a default property name and JDBC type
+will be used.</p>
+<p>It is acceptable to extend this result map if you code any
+custom join queries in the SQL map.  This is a common use case and is expected.</p>
+<p>This element will be generated if that table contains BLOB fields, and either the select by example,
+or select by primary key statements are enabled.</p>
+
+<h2>SQL Where Clause</h2>
+<p>This element contains a reusable where clause that conforms to the "by example" methods. The
+where clause will not include any BLOB fields if they exist in the table.  Most databases do not
+support BLOB fields in the WHERE clause.</p>
+<p>This element will be generated if either the select by example, or delete by example statements
+are enabled.</p>
+
+<h2>Select By Primary Key</h2>
+<p>This element contains a select statement that will return one row - designated by the primary key.
+The returned row will include BLOB fields if they exist in the table.</p>
+<p>This element will be generated if the table has a primary key and the select by primary key statement
+is enabled.</p>
+
+<h2>Select by Example</h2>
+<p>This element contains a select statement with rows that match the example object.
+This implements a simple "query by example" functionality that can be used to generate many
+different database queries.  The returned rows will not include any BLOB fields that exist in the table
+(see the select by example with BLOBs statement below).</p>
+<p><b>Important:</b> If the example class is null, or no criteria have been set,
+then <b>all</b> rows in the table will be selected.</p>
+<p>This element will be generated if the select by example statement is enabled.</p>
+
+<h2>Select by Example With BLOBs</h2>
+<p>This element contains a select statement with rows that match the example object.
+This implements a simple "query by example" functionality that can be used to generate many
+different database queries.  The returned rows will include any BLOB fields that exist in the table.</p>
+<p><b>Important:</b> If the example class is null, or no criteria have been set,
+then <b>all</b> rows in the table will be selected.</p>
+<p>This element will be generated if the table contains BLOB fields, and the select by example
+ statement is enabled.</p>
+
+<h2>Insert</h2>
+<p>This element is an insert statement that includes all fields in the table (including BLOBs),
+unless the field is specifically ignored with the <code>&lt;ignoreColumn&gt;</code> configuration
+element.</p>
+<p>If the table has an auto generated key (an identity column or from a sequence), and the
+<code>&lt;generatedKey&gt;</code> configuration element is specified, then iBATOR will generate
+an appropriate <code>&lt;selectKey&gt;</code> element and will return the value of the
+generated key.</p>
+<p>This element will be generated if the insert statement is enabled.</p>
+
+<h2>Update By Primary Key</h2>
+<p>This element is an update statement that will update one row - designated by the primary
+key.  The update statement will update all fields in the table unless:</p>
+<ul>
+  <li>The field has been ignored by the <code>&lt;ignoreColumn&gt;</code> configuration element</li>
+  <li>The field is a BLOB field (see the update by primary key with BLOBs element)</li>
+</ul>
+<p>This element will be generated if the table has a primary key, and the update by primary
+key statement is enabled.</p>
+
+<h2>Update By Primary Key With BLOBs</h2>
+<p>This element is an update statement that will update one row - designated by the primary
+key.  The update statement will update all fields in the table (including BLOB fields) unless:</p>
+<ul>
+  <li>The field has been ignored by the <code>&lt;ignoreColumn&gt;</code> configuration element</li>
+</ul>
+<p>This element will be generated if the table has a primary key, the table has BLOB columns,
+ and the update by primary key statement is enabled.</p>
+
+<h2>Update By Primary Key Selective</h2>
+<p>This element is an update statement that will update one row - designated by the primary
+key.  The update statement will update only the fields in the table whose corresponding
+property in the parameter object is non-null.  This statement can be used to update
+certain columns in a record without affecting all columns in the record.  <b>Important:</b>
+if the column has been mapped to a primitive type, then the column will always be
+updated.</p>
+<p>This element will be generated if the table has a primary key, and the update by primary
+key statement is enabled.</p>
+
+<h2>Delete By Primary Key</h2>
+<p>This element is a delete statement that will delete one row in the table - designated by the
+primary key.</p>
+<p>This element will be generated if the table has a primary key, and the delete by primary key
+ statement is enabled.</p>
+
+<h2>Delete By Example</h2>
+<p>This element is a delete statement that will delete one or more rows in the table - designated by
+the example object.</p>
+<p><b>Important:</b> If the example class is null, or no criteria have been set,
+then <b>all</b> rows in the table will be deleted.</p>
+<p>This element will be generated if the delete by example statement is enabled.</p>
+
+<h2>Count By Example</h2>
+<p>This element is a select count(*) statement that will return the number of rows in the table
+that match the specified example object.</p>
+<p><b>Important:</b> If the example class is null, or no criteria have been set,
+then the select will return the number of rows in the entire table.</p>
+<p>This element will be generated if the count by example statement is enabled.</p>
+
+<h2>Update By Example</h2>
+<p>This element is an update statement that will update all rows in a table that match
+the specified example.  The update statement will update all fields in the table unless:</p>
+<ul>
+  <li>The field has been ignored by the <code>&lt;ignoreColumn&gt;</code> configuration element</li>
+  <li>The field is a BLOB field (see the update by example with BLOBs element)</li>
+</ul>
+<p><b>Important:</b> If the example class is null, or no criteria have been set,
+then <b>all</b> rows in the table will be updated.</p>
+<p>This element will be generated if the update by example statement is enabled.</p>
+
+<h2>Update By Example With BLOBs</h2>
+<p>This element is an update statement that will update all rows in a table that match
+the specified example.  The update statement will update all fields in the table (including BLOB fields)
+unless:</p>
+<ul>
+  <li>The field has been ignored by the <code>&lt;ignoreColumn&gt;</code> configuration element</li>
+</ul>
+<p><b>Important:</b> If the example class is null, or no criteria have been set,
+then <b>all</b> rows in the table will be updated.</p>
+<p>This element will be generated if the table contains BLOB columns, and the update by
+example statement is enabled.</p>
+
+<h2>Update By Example Selective</h2>
+<p>This element is an update statement that will update all rows in a table that match the
+specified example.  The update statement will update only the fields in the table whose corresponding
+property in the parameter object is non-null.  This statement can be used to update
+certain columns in certain records without affecting all columns in the records.  <b>Important:</b>
+if the column has been mapped to a primitive type, then the column will always be
+updated.</p>
+<p><b>Important:</b> If the example class is null, or no criteria have been set,
+then <b>all</b> rows in the table will be updated.</p>
+<p>This element will be generated if the update by example statement is enabled.</p>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/ibator.css
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/ibator.css?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/ibator.css (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/ibator.css Mon Apr 14 19:32:53 2008
@@ -0,0 +1,121 @@
+p, table, td, th {  font-family: arial, helvetica, geneva, sans-serif; font-size: 10pt}
+pre {  font-family: "Courier New", Courier, mono, serif; font-size: 10pt}
+h2 { font-family: arial, helvetica, geneva, sans-serif; font-size: 18pt; font-weight: bold; margin-top: 30px}
+code {  font-family: "Courier New", Courier, mono, serif; font-size: 10pt}
+sup {  font-family: arial,helvetica,geneva, sans-serif; font-size: 10px}
+h3 {  font-family: arial, helvetica, geneva, sans-serif; font-size: 14pt; font-weight: bold}
+li {  font-family: arial, helvetica, geneva, sans-serif; font-size: 10pt}
+h1 {  font-family: arial, helvetica, geneva, sans-serif; font-size: 28px; font-weight: bold}
+body {  font-family: arial, helvetica, geneva, sans-serif; font-size: 10pt; margin-top: 5mm; margin-left: 3mm}
+.indextop { font-size: x-large;; font-family: Verdana, Arial, Helvetica, sans-serif; font-weight: bold}
+.indexsub { font-size: xx-small;; font-family: Arial, Helvetica, sans-serif; color: #8080FF}
+
+pre {
+    padding: 0px;
+    margin-top: 0px;
+    margin-left: 0px;
+    margin-bottom: 0px;
+    margin-right: 0px;
+    text-align: left;
+}
+
+.code {
+ 	border: 1px dashed #3c78b5;
+    font-size: 11px;
+	font-family: Courier;
+    margin: 10px;
+	line-height: 13px;
+    text-align: left;
+    color: #000000;
+    background-color: #f0f0f0;
+    padding: 10px;
+}
+
+.code-xml {
+  color: #000000;
+}
+
+.schema-type
+{
+  color: #009100;
+  background-color: inherit;
+}
+
+.schema-type-link a:link
+{
+  color: #009100;
+  text-decoration: none
+}
+
+.schema-type-link a:visited
+{
+  color: #009100;
+  text-decoration: none
+}
+
+.schema-control {
+  color: #009100;
+  font-style: italic;
+  background-color: inherit;
+}
+
+.code-text {
+  color: #009100;
+  background-color: inherit;
+}
+
+.context-code {
+  color: #767676;
+  background-color: inherit;
+}
+
+.xml-text
+{
+  color: #009100;
+}
+
+.java-code 
+{
+  color: #000000;
+}
+
+.java-comment 
+{
+  color: #009100;
+}
+
+.java-javadoc-keyword
+{
+  font-weight: bold;
+}
+
+.java-keyword
+{
+  color: #7f0055;
+  font-weight: bold;
+}
+
+.java-literal
+{
+  color: #009100;
+}
+
+.java-context
+{
+  color: #767676;
+}	
+
+.java-context-keyword
+{
+  font-weight: bold;
+}	
+
+.screen-shot 
+{
+    margin: 10px;
+}
+
+.block-indent 
+{
+    margin: 10px;
+}

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/index.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/index.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/index.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/index.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,17 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>iBATOR for iBATIS User Manual</title>
+  <link type="text/css" rel="stylesheet" href="ibator.css"/>
+</head>
+
+<frameset cols="30%,*">
+
+  <frame src="menu.html" name="menuFrame"/>
+  <frame src="intro.html" name="mainFrame"/>
+
+</frameset>
+
+</html>
\ No newline at end of file

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/intro.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/intro.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/intro.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/intro.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,143 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Introduction to iBATOR</title>
+  <link type="text/css" rel="stylesheet" href="ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="index.html" target="_top">Frames</a>
+    <a href="intro.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>Introduction to iBATOR</h1>
+<p>iBATOR is a code generator for <a target="_blank" href="http://ibatis.apache.org">iBATIS</a>.
+ iBATOR will introspect a database
+ table (or many tables) and will generate iBATIS artifacts that can be used to
+ access the table(s).  This lessens the initial nuisance of setting up objects and configuration
+ files to interact with database tables.  iBATOR seeks to make a major impact on the large
+percentage of database operations that are simple CRUD (Create, Retrieve, Update, Delete).  You will
+ still need to hand code SQL and objects for join queries, or stored procedures.
+</p>
+<p>iBATOR will generate:</p>
+<ul>
+  <li>Java POJOs that match the table structure.  This may include:
+    <ul>
+      <li>a class to match the primary key of the table (if there is a primary key)</li>
+      <li>a class to match the non-primary key fields of the table (except BLOB fields)</li>
+      <li>a class to include the BLOB fields of a table (if the table has BLOB fields)</li>
+      <li>a class to enable dynamic selects, updates, and deletes</li>
+    </ul>
+    <p>There is an inheritance relationship between these classes as appropriate.
+       Note that iBATOR may be configured to generate different types of POJO hierarchies -
+       for example, you may choose to tell
+       iBATOR to generate a single domain object for each table if you so
+       desire.</p>
+  </li>
+  <li>iBATIS Compatible SQL Map XML Files.  iBATOR generates SQL for simple
+   CRUD functions on each table in a configuration.  The generated SQL
+   statements include:
+    <ul>
+      <li>insert</li>
+      <li>update by primary key</li>
+      <li>update by example (using a dynamic where clause)</li>
+      <li>delete by primary key</li>
+      <li>delete by example (using a dynamic where clause)</li>
+      <li>select by primary key</li>
+      <li>select by example (using a dynamic where clause)</li>
+    </ul>
+   <p>There are different variations of these statements depending on the
+   structure of the table (for example, if the table doesn't have a primary key,
+   then iBATOR will not generate an update by primary key function).</p>
+  </li>
+  <li>DAO interface and implementation classes that make appropriate use of the
+    above objects.  The generation of DAO classes is optional.  iBATOR will
+    generate DAOs of the following types:
+    <ul>
+      <li>DAOs that conform to the
+          <a target="_blank" href="http://www.springframework.org">Spring</a> framework</li>
+      <li>DAOs that only use the iBATIS SQL mapping API.  These DAOs can be
+          generated in two varieties: supplying the <code>SqlMapClient</code> through
+          either constructor or setter injection.</li>
+      <li>DAOs that conform to the iBATIS DAO Framework (an optional part of iBATIS, this
+          framework is now deprecated and we suggest that you use the Spring framework
+          instead)</li>
+    </ul>
+  </li>
+</ul>
+
+<p>iBATOR is designed to run well in an iterative development environment, and
+  iBATOR can even be included as an Ant task in a continuous build environment.
+  Important things to note when running iBATOR iteratively include:</p>
+
+<ol>
+  <li>iBATOR will automatically merge XML files if there is an existing file
+      with the same name as the newly generated XML file.  iBATOR will not overwrite
+      any custom changes you make to the XML files it generates.
+      You can run it over and over again without fear of losing custom changes to you XML.
+      iBATOR will replace any XML elements that were generated in a previous run.
+      </li>
+  <li>iBATOR will <b>not</b> merge Java files, it can either overwrite existing files
+      or save newly generated files with a different unique name.  If you make changes
+      to the generated Java files and run iBATOR iteratively you will have to
+      merge the changes by hand.  When run as an
+      <a target="_blank" href="http://www.eclipse.org">Eclipse</a>
+      plugin, then iBATOR can automatically merge Java files.</li>
+</ol>
+
+<h2>Dependencies</h2>
+<p>iBATOR has no dependencies beyond the JRE.  iBATOR does require JRE 5.0 or
+above.  iBATOR also requires that the JDBC driver implements the
+DatabaseMetaData interface, especially the <code>getColumns</code> and
+<code>getPrimaryKeys</code> methods.</p>
+
+<h2>About the Name</h2>
+<p>"iBATOR" is an iBATIS styled version of the noun Abator.  "Abator" means "one who
+abates a nuisance".  This describes the purpose of iBATOR - it abates some of the nuisance
+of creating object and configuration files for iBATIS.</p>
+<p>iBATOR was originally named "Abator", but the name was changed as the result of
+a federal trade registration dispute.</p>
+
+<h2>Support</h2>
+<p>Support for iBATOR is provided through the iBATIS user mailing list.
+You may subscribe to the mailing list by sending a note to:</p>
+
+<blockquote>
+  <p>
+  <a href="mailto:user-java-subscribe@ibatis.apache.org">user-java-subscribe@ibatis.apache.org</a>
+  </p>
+</blockquote>
+
+<p>Once you have subscribed, you can mail questions or bug reports to:</p>
+<blockquote>
+  <p>
+  <a href="mailto:user-java@ibatis.apache.org">user-java@ibatis.apache.org</a>
+  </p>
+</blockquote>
+
+<p>If you want to unsubscribe from the mailing list, send a note to:</p>
+<blockquote>
+  <p>
+  <a href="mailto:user-java-unsubscribe@ibatis.apache.org">user-java-unsubscribe@ibatis.apache.org</a>
+  </p>
+</blockquote>
+
+<p>If you think you have found a bug, please ask a question about it on the user list first,
+before creating a JIRA issue.  If you find a bug, or have a new feature request,
+you may open a JIRA issue for iBATOR at</p>
+
+<blockquote>
+  <p>
+  <a target="_blank" href="http://issues.apache.org/jira/browse/IBATIS">
+    http://issues.apache.org/jira/browse/IBATIS
+  </a>
+  </p>
+</blockquote>
+
+<p>Please select the "Tools" component when creating any JIRA issues for iBATOR.</p>
+
+</body>
+</html>
\ No newline at end of file

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/license.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/license.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/license.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/license.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,38 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>iBATOR Licensing Information</title>
+  <link type="text/css" rel="stylesheet" href="ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="index.html" target="_top">Frames</a>
+    <a href="license.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>iBATOR Licensing Information</h1>
+<p>Copyright 2006 The Apache Software Foundation</p>
+<p>Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this product except in compliance with the License.
+   You may obtain a copy of the License at
+</p>
+<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="http://www.apache.org/licenses/LICENSE-2.0">
+http://www.apache.org/licenses/LICENSE-2.0</a></p>
+<p>
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+</p>
+
+<p>This product includes software developed by the Apache Software
+Foundation <a href="http://www.apache.org">(http://www.apache.org/)</a>.</p>
+
+<p>This product includes the <code>EqualsUtil</code> and <code>HashCodeUtil</code> classes
+from <a target="_blank" href="http://www.javapractices.com">http://www.javapractices.com</a>.</p>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/menu.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/menu.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/menu.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/menu.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,55 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Table of Contents</title>
+  <link type="text/css" rel="stylesheet" href="ibator.css"/>
+</head>
+<body>
+<h1>Table of Contents</h1>
+<p>
+  <a href="intro.html" target="mainFrame">Introduction</a><br/>
+  <a href="whatsNew.html" target="mainFrame">What's New?</a><br/>
+  <a href="quickstart.html" target="mainFrame">Quick Start Guide</a><br/>
+  <a href="running.html" target="mainFrame">Running iBATOR</a><br/>
+  <a href="afterRunning.html" target="mainFrame">Tasks After Running iBATOR</a><br/>
+
+  <a href="configreference/xmlconfig.html" target="mainFrame">XML Configuration File Reference</a><br/>
+  &nbsp;&nbsp;<a href="configreference/classPathEntry.html" target="mainFrame">&lt;classPathEntry&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/columnOverride.html" target="mainFrame">&lt;columnOverride&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/columnRenamingRule.html" target="mainFrame">&lt;columnRenamingRule&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/commentGenerator.html" target="mainFrame">&lt;commentGenerator&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/daoGenerator.html" target="mainFrame">&lt;daoGenerator&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/generatedKey.html" target="mainFrame">&lt;generatedKey&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/ibatorConfiguration.html" target="mainFrame">&lt;ibatorConfiguration&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/ibatorContext.html" target="mainFrame">&lt;ibatorContext&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/ignoreColumn.html" target="mainFrame">&lt;ignoreColumn&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/javaTypeResolver.html" target="mainFrame">&lt;javaTypeResolver&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/javaModelGenerator.html" target="mainFrame">&lt;javaModelGenerator&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/jdbcConnection.html" target="mainFrame">&lt;jdbcConnection&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/properties.html" target="mainFrame">&lt;properties&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/property.html" target="mainFrame">&lt;property&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/sqlMapGenerator.html" target="mainFrame">&lt;sqlMapGenerator&gt;</a><br/>
+  &nbsp;&nbsp;<a href="configreference/table.html" target="mainFrame">&lt;table&gt;</a><br/>
+
+  <a href="generatedobjects/results.html" target="mainFrame">Using the Generated Objects</a><br/>
+  &nbsp;&nbsp;<a href="generatedobjects/javamodel.html" target="mainFrame">Java Model Objects</a><br/>
+  &nbsp;&nbsp;<a href="generatedobjects/sqlmap.html" target="mainFrame">SQL Map Files</a><br/>
+  &nbsp;&nbsp;<a href="generatedobjects/javadao.html" target="mainFrame">DAO Interfaces and Classes</a><br/>
+  &nbsp;&nbsp;<a href="generatedobjects/exampleClassUsage.html" target="mainFrame">Example Class Usage Notes</a><br/>
+  &nbsp;&nbsp;<a href="generatedobjects/extendingExampleClass.html" target="mainFrame">Extending the Example Classes</a><br/>
+
+  <a href="usage/intro.html" target="mainFrame">Database Specific Information</a><br/>
+  &nbsp;&nbsp;<a href="usage/db2.html" target="mainFrame">DB2</a><br/>
+  &nbsp;&nbsp;<a href="usage/mysql.html" target="mainFrame">MySql</a><br/>
+  &nbsp;&nbsp;<a href="usage/oracle.html" target="mainFrame">Oracle</a><br/>
+
+  <a href="reference/intro.html" target="mainFrame">Other Reference Information</a><br/>
+  &nbsp;&nbsp;<a href="reference/building.html" target="mainFrame">Building iBATOR from Source</a><br/>
+  &nbsp;&nbsp;<a href="reference/extending.html" target="mainFrame">Extending iBATOR</a><br/>
+  <a href="philosophy.html" target="mainFrame">Design Philosophy</a><br/>
+  <a href="license.html" target="mainFrame">Licensing Information</a><br/>
+</p>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/philosophy.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/philosophy.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/philosophy.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/philosophy.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,94 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>iBATOR Philosophy and Apology</title>
+  <link type="text/css" rel="stylesheet" href="ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="index.html" target="_top">Frames</a>
+    <a href="philosophy.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>iBATOR Philosophy and Apology</h1>
+<p>Some philosophical questions might be raised by this tool because the
+ tool is more focused on database tables than on the domain model.
+ We will take a few paragraphs to talk about this approach.</p>
+
+<p>First of all, this tool does what it does.  We are not making any kind of statement
+about how projects should, or should not, be structured.  In general we are strong proponents
+of rich domain models - but creating a rich domain model is quite a different thing from
+answering the question of how that model should be persisted.</p>
+
+<p>If your particular design philosophy  is that the domain model drives all decisions, and
+ that the database design is subservient to the domain model, then this tool - and iBATIS
+ itself - may not be the proper fit for your application.  In that case, we would suggest
+ taking a serious look at <a target="_blank" href="http://www.hibernate.org">Hibernate</a>
+ - it may fit
+ more closely with your application design and philosophy.</p>
+
+<p>But not all projects fit that paradigm.  Very few truly enterprise
+ class applications do.  iBATIS and iBATOR can be of great help in projects where
+ database design is seen as a co-equal to domain object design.
+iBATIS is not an object relational mapper, and does not attempt to transparently
+persist objects.  So it falls on application developers to write SQL to interact with
+database tables.</p>
+
+<p>In large or enterprise class projects, many of these factors are quite common:</p>
+<ul>
+  <li>Database design is often a separate function (with separate management) from OO domain
+      design
+  </li>
+  <li>Database designers do not have OO tools (like inheritance), so they don't think
+      in OO terms</li>
+  <li>Application designers do not have complete control over the final form of database tables.
+    For example, the data that seems to fit in one object for the application, may be split
+    into several tables in the database.</li>
+  <li>The database design often ends up quite different from the OO design, leading to
+   a significant mismatch between tables and objects.</li>
+</ul>
+<p>
+These factors are primary indicators that iBATIS is a good candidate tool for your
+application, and this is the type of project where iBATOR can make a significant impact.
+So how should iBATIS and iBATOR be used in this case?</p>
+
+<p>The Data Access Object(DAO) pattern is still the primary pattern.  iBATOR can generate a basic
+set of DAOs that match each individual table.  iBATOR's DAOs are transaction neutral.  This means
+that it is easy to extend the DAOs to add transaction attributes if more than one table is involved in
+a transaction.  Or, you could create another DAO (or service method) that more closely matches the
+persistence needs of a domain object
+and make use of one or more iBATOR DAOs in a single transaction.</p>
+
+<p>As an example, consider a typical <code>Order</code> object - the typical header/detail problem.
+In some environments such an object would be persisted into at least 4 tables -
+two key tables, a "header" table, and a "detail" table (again, we are not making any kind of
+statement about whether this is "correct" design, just stating a fact).
+Your application should still interact with interact with the <code>Order</code> object, and
+there might
+be a <code>saveOrder(Order order)</code> method
+somewhere (in an OrderDAO, or a service object).  That method
+would interact with the iBATOR created DAOs for each of the 4 tables involved.</p>
+
+<p>What has iBATOR bought us in this case?  Several things:</p>
+<ul>
+  <li>Reuse - it is likely that some tables will need to be accessed from multiple different DAOs
+  or service methods.  Creating a DAO for each table promotes reuse and consistency within the
+  application.</li>
+  <li>Database abstraction - a service layer typically defines persistence in your application.  Those
+    methods can be stabilized fairly quickly.  As database design evolves:
+    <ol>
+      <li>iBATOR can quickly regenerate the DAOs as the tables change</li>
+      <li>The service methods can be modified as necessary</li>
+      <li>Higher layers in the application remain unchanged</li>
+    </ol>
+  </li>
+  <li>Developer productivity - generating table based DAOs is quick and repeatable and error free.
+    Developers can concentrate on Object persistence, and on complex join queries if needed.</li>
+  <li>Fewer defects - because the most tedious and error prone part of any application (getting the
+   SQL to match the objects) is automated.</li>
+</ul>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/quickstart.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/quickstart.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/quickstart.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/quickstart.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,56 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>iBATOR Quick Start Guide</title>
+  <link type="text/css" rel="stylesheet" href="ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="index.html" target="_top">Frames</a>
+    <a href="quickstart.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>iBATOR Quick Start Guide</h1>
+<p>To get up and running quickly with iBATOR, follow these steps:</p>
+<ol>
+  <li>Create and fill out a configuration file appropriately.
+      At a minimum, you must specify:
+    <ol type="a">
+      <li>A <code>&lt;jdbcConnection&gt;</code> element to specify how to connect to
+          the target database</li>
+      <li>A <code>&lt;javaModelGenerator&gt;</code> element to specify target package
+          and target project for generated Java model objects</li>
+      <li>A <code>&lt;sqlMapGenerator&gt;</code> element to specify target package
+          and target project for generated SQL map files</li>
+      <li>(Optionally) A <code>&lt;daoGenerator&gt;</code> element to specify target package
+           and target project for generated DAO interfaces and classes (you may
+          omit the <code>&lt;daoGenerator&gt;</code> element if you don't wish to generate DAOs)</li>
+      <li>At least one database <code>&lt;table&gt;</code> element</li>
+    </ol>
+    <p>See the <a href="configreference/xmlconfig.html">XML Configuration File Reference</a>
+       page for an example of an iBATOR configuration file.</p>
+  </li>
+  <li>Save the file in some convenient location (like \temp\ibatorConfig.xml)</li>
+  <li>Run iBATOR from the command line with a command like this:
+    <pre>
+
+      java -jar ibator.jar -configfile \temp\ibatorConfig.xml -overwrite
+    </pre>
+    <p>This will tell iBATOR to run using your configuration file.  It will also tell iBATOR
+    to overwrite any existing Java files with the same name.  If you want to save any existing
+    Java files, then omit the <code>-overwrite</code> parameter.  If there is a conflict, iBATOR
+    will save the newly generated file with a unique name (e.g. MyClass.java.1).</p>
+  </li>
+  <li>After running iBATOR, you will need to create or modify the standard iBATIS
+      configuration files to make use of your newly generated code.  See the
+      <a href="afterRunning.html">Tasks After Running iBATOR</a> page for more
+      information.</li>
+</ol>
+<p><b>Important:</b> iBATOR generated code requires that statement namespaces are enabled
+  in your iBATIS configuration.  See the <a href="afterRunning.html">Tasks After Running iBATOR</a>
+  page for more information.</p>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/reference/building.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/reference/building.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/reference/building.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/reference/building.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,41 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Building iBATOR from Source</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="building.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>Building iBATOR from Source</h1>
+<p>All iBATOR distributions include source code.  The only compile time dependency iBATOR
+has is on <code>ant.jar</code> - for successful compilation of the included Ant task.
+It is straight forward to compile iBATOR from source - simply unzip the source in
+an iBATOR distribution and compile it with your favorite tool.</p>
+
+<p>If you would like to build iBATOR from the very latest version of the source code
+at Apache then follow these steps:</p>
+<ol>
+  <li>Do a SubVersion checkout of the iBATOR source tree from the location
+    <a target="_blank" href="http://svn.apache.org/repos/asf/ibatis/trunk/java/mapper/mapper2/tools/abator/core/">
+    http://svn.apache.org/repos/asf/ibatis/trunk/java/mapper/mapper2/tools/abator/core/</a>
+    (You may use any SubVersion client you prefer.  We recommend
+    <a target="_blank" href="http://tortoisesvn.tigris.org/">TortoiseSVN</a>.)
+  </li>
+  <li>The build file requires that ANT_HOME and JAVA_HOME environment variables be defined.
+      If they are not already defined on your system, then
+      modify the file <code>../build/setupCmdLine.bat</code> to specify
+      the proper values on your machine.</li>
+  <li>Run the Ant build script by running the batch file <code>../build/build.bat</code>
+    from the checked out directory.</li>
+</ol>
+
+
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/reference/extending.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/reference/extending.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/reference/extending.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/reference/extending.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,215 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Extending iBATOR</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="extending.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>Extending iBATOR</h1>
+<p>iBATOR is designed for extensibility.  All code generation is performed using a
+simple DOM representation of Java and XML elements that is included with iBATOR.</p>
+<p>The Java DOM is included in the package <code>org.apache.ibatis.ibator.api.dom.java</code></p>
+<p>The XML DOM is included in the package <code>org.apache.ibatis.ibator.api.dom.xml</code></p>
+<p>These classes are not sufficient for every conceivable code generation possibility, but they are quite
+useful for generating simple to moderately complex Java and XML code.</p>
+
+<p>Using options in the iBATOR configuration file, you can provide your own implementations
+of any of iBATOR's key interfaces.  You can also subclass any of the provided implementations
+to provide customized behaviors.  This page will describe the public APIs available in
+iBATOR and provide pointers to the source code for further investigation.  If you have
+any difficulty understanding how to extend iBATOR, feel free to send a note to the
+support mailing list at
+<a href="mailto:user-java@ibatis.apache.org">user-java@ibatis.apache.org</a>.</p>
+
+<h2>org.apache.ibatis.ibator.api.JavaModelGenerator</h2>
+<p>iBATOR calls methods in this interface to generate the Java model POJOs.
+   You can provide your own implementation, and the default implementations have
+   been designed for extensibility.  The default implementation of the interface
+   is dependant on the value of the <code>generatorSet</code>
+   property of the <a href="../configreference/ibatorContext.html">&lt;ibatorContext&gt;</a>
+   configuration element.  The following table shows the different possibilities:</p>
+
+<table border="1" cellspacing="0" cellpadding="5">
+  <tr>
+    <th>generatorSet</th>
+    <th>Implementation Class</th>
+  </tr>
+  <tr>
+    <td>Java2 (the default value)</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.model.JavaModelGeneratorJava2Impl</code></td>
+  </tr>
+  <tr>
+    <td>Java5</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.model.JavaModelGeneratorJava5Impl</code></td>
+  </tr>
+</table>
+
+<p>To provide your own implementation, specify the fully qualified class name
+   in the XML configuration like this:</p>
+<pre>
+    &lt;javaModelGenerator type="mypackage.MyImplementation"&gt;
+      ...
+    &lt;/javaModelGenerator&gt;
+</pre>
+
+<h2>org.apache.ibatis.ibator.api.SqlMapGenerator</h2>
+<p>iBATOR calls methods in this interface to generate the SQL Maps.
+   You can provide your own implementation, and the default implementations have
+   been designed for extensibility.  The default implementation of the interface
+   is dependant on the value of the <code>generatorSet</code>
+   property of the <a href="../configreference/ibatorContext.html">&lt;ibatorContext&gt;</a>
+   configuration element.  The following table shows the different possibilities:</p>
+
+<table border="1" cellspacing="0" cellpadding="5">
+  <tr>
+    <th>generatorSet</th>
+    <th>Implementation Class</th>
+  </tr>
+  <tr>
+    <td>Java2 (the default set) or Java5</td>
+    <td><code>org.apache.ibatis.ibator.internal.sqlmap.SqlMapGeneratorIterateImpl</code></td>
+  </tr>
+</table>
+
+<p>To provide your own implementation, specify the fully qualified class name
+   in the XML configuration like this:</p>
+<pre>
+    &lt;sqlMapGenerator type="mypackage.MyImplementation"&gt;
+      ...
+    &lt;/sqlMapGenerator&gt;
+</pre>
+
+<h2>org.apache.ibatis.ibator.api.DAOGenerator</h2>
+<p>iBATOR calls methods in this interface to generate the DAOs for each introspected
+table.  iBATOR supplies twelve implementations of this
+interface to match the four different types of DAOs, and the three different sets
+of code generators.  The implementation is selected based on the value of the
+<a href="../configreference/ibatorContext.html">&lt;ibatorContext&gt;</a>
+configuration element and the value of the <code>type</code> attribute
+of the <a href="../configreference/daoGenerator.html">&lt;daoGenerator&gt;</a> element.
+The implementations are:</p>
+
+<table border="1" cellspacing="0" cellpadding="5">
+  <tr>
+    <th>generatorSet/type</th>
+    <th>Implementation Class</th>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java2/IBATIS</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.IbatisJava2DAOGenerator</code></td>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java2/GENERIC-CI</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.GenericCIJava2DAOGenerator</code></td>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java2/GENERIC-SI</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.GenericSIJava2DAOGenerator</code></td>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java2/SPRING</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.SpringJava2DAOGenerator</code></td>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java5/IBATIS</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.IbatisJava5DAOGenerator</code></td>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java5/GENERIC-CI</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.GenericCIJava5DAOGenerator</code></td>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java5/GENERIC-SI</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.GenericSIJava5DAOGenerator</code></td>
+  </tr>
+  <tr>
+    <td nowrap="nowrap">Java5/SPRING</td>
+    <td><code>org.apache.ibatis.ibator.internal.java.dao.SpringJava5DAOGenerator</code></td>
+  </tr>
+</table>
+
+<p>The different DAO implementations are "configured" through the use of
+   a template described in
+   <code>org.apache.ibatis.ibator.internal.java.dao.AbstractDAOTemplate</code>.
+   It should be fairly simple to provide a new template for a different type
+   of DAO if needed.</p>
+<p>The DAO generators are also designed for extensibility.  To provide your own
+   implementation, specify the fully qualified class name in the XML
+   configuration like this:</p>
+<pre>
+    &lt;daoGenerator type="mypackage.MyImplementation"&gt;
+      ...
+    &lt;/daoGenerator&gt;
+</pre>
+
+<h2>org.apache.ibatis.ibator.api.JavaTypeResolver</h2>
+<p>iBATOR calls methods in this interface to map JDBC types to Java types
+   during database introspection.  The default implementation of this
+   interface is <code>org.apache.ibatis.ibator.internal.types.JavaTypeResolverDefaultImpl</code>.
+   You can provide your own implementation, and the default implementation has
+   been designed for extensibility.</p>
+
+<p>To provide your own implementation, specify the fully qualified class name
+   in the XML configuration like this:</p>
+<pre>
+    &lt;javaTypeResolver type="mypackage.MyImplementation"&gt;
+      ...
+    &lt;/javaTypeResolver&gt;
+</pre>
+
+<h2>org.apache.ibatis.ibator.api.ShellCallback</h2>
+<p> iBATOR calls methods in this interface to perform functions that it cannot
+   do on its own.  The most important of these functions are:</p>
+<ul>
+  <li>Translating project/package into a directory structure</li>
+   <li>Merging Java source files in the event that an existing Java file of
+     the same name/package exists.</li>
+</ul>
+
+<p>The default implementation of this interface is
+   <code>org.apache.ibatis.ibator.internal.DefaultShellCallback</code>.  The default
+   implementation simply concatenates project and package together and creates
+   the necessary package directories if needed.  The default implementation does not
+   support merging of Java files, and will either overwrite or ignore files.</p>
+
+<p>You can provide your own implementation.  This would be the most important
+   class to write if you want to integrate iBATOR into some other environment.
+   The Eclipse plugin provides an implementation of this interface that
+   supports Java file merging when running in the Eclipse environment.</p>
+
+<p>To provide your own implementation, supply an instance of the interface
+   on the constructor to the <code>org.apache.ibatis.ibator.api.Ibator</code>
+   object.  This cannot be configured through XML.  If you are providing
+   your own implementation of this interface then we assume that you are
+   also providing some collateral code (like a new Ant task) to run
+   your implementation.</p>
+
+<h2>org.apache.ibatis.ibator.api.ProgressCallback</h2>
+<p>iBATOR calls methods in this interface to report progress during the
+   generation of files (a long running process).  The default implementation
+   of this interface is
+   <code>org.apache.ibatis.ibator.internal.NullProgressCallback</code>
+   which simply ignores all progress messages.  You can provide an
+   implementation of this interface to support progress notifications and
+   cancellation of file generation.</p>
+
+<p>Implementing this interface would be important when integrating iBATOR
+   into other IDE environments.  The Eclipse plugin provides an implementation
+   of this interface that hooks into Eclipse's progress notification system.</p>
+
+<p>To provide your own implementation, supply an instance of the interface
+   in the <code>org.apache.ibatis.ibator.api.Ibator.generate()</code> method call.
+   This cannot be configured through XML.  Again, we assume that if you are providing
+   your own implementation of this interface then you are
+   also providing some collateral code (like a new Ant task or an IDE integration) to run
+   your implementation.</p>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/reference/intro.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/reference/intro.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/reference/intro.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/reference/intro.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,25 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>iBATOR Reference Information</title>
+  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="../index.html" target="_top">Frames</a>
+    <a href="intro.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>iBATOR Reference Information</h1>
+<p>This section collects useful information related to technical topics
+with iBATOR.</p>
+
+<ul>
+  <li><a href="building.html">Building iBATOR from Source</a></li>
+  <li><a href="extending.html">Extending iBATOR</a></li>
+</ul>
+</body>
+</html>

Added: ibatis/trunk/java/tools/ibator/core/htmldoc/running.html
URL: http://svn.apache.org/viewvc/ibatis/trunk/java/tools/ibator/core/htmldoc/running.html?rev=648102&view=auto
==============================================================================
--- ibatis/trunk/java/tools/ibator/core/htmldoc/running.html (added)
+++ ibatis/trunk/java/tools/ibator/core/htmldoc/running.html Mon Apr 14 19:32:53 2008
@@ -0,0 +1,238 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Running iBATOR</title>
+  <link type="text/css" rel="stylesheet" href="ibator.css"/>
+</head>
+<body>
+<p align="right">
+  <font size="-2">
+    <a href="index.html" target="_top">Frames</a>
+    <a href="running.html" target="_top">No Frames</a>
+  </font>
+</p>
+<h1>Running iBATOR</h1>
+<p>iBATOR can be run in the following ways:</p>
+<ul>
+  <li>From the command line with an XML configuration</li>
+  <li>As an Ant task with an XML configuration</li>
+  <li>From another Java program with an XML configuration</li>
+  <li>From another Java program with a Java based configuration</li>
+</ul>
+<p>Each method is described in detail below.</p>
+<p><b>Note:</b> there is also an Eclipse
+plugin for iBATOR that adds extra function - namely good integration into Eclipse,
+an Eclipse enabled Ant task, and support for automatic merging of
+Java files.  See the
+<a target="_blank" href="http://ibatis.apache.org/ibator.html">iBATOR</a>
+home page for information on installing the Eclipse plugin.</p>
+
+<p><b>Important:</b> When running outside of an IDE environment like Eclipse,
+  iBATOR interprets the <code>targetProject</code> and
+  <code>targetPackage</code> attributes in all XML configurations as follows:</p>
+<ul>
+  <li><code>targetProject</code> is assumed to be an existing directory structure.
+    iBATOR will fail if this directory structure does not exist.</li>
+   <li><code>targetPackage</code> will be translated to a suitable subdirectory
+     structure of the <code>targetProject</code>
+     directory structure.  iBATOR will create these subdirectories if necessary.</li>
+</ul>
+
+<h2>Running iBATOR from the Command Line</h2>
+<p>iBATOR may be run directly from the command line.  The JAR manifest includes the
+   name of the default class (<code>org.apache.ibatis.ibator.api.IbatorRunner</code>)
+   or you may specify it yourself.  The <code>IbatorRunner</code>
+   class accepts several arguments as detailed below:</p>
+<table border="1" cellspacing="0" cellpadding="5">
+<tr>
+  <th>Argument</th>
+  <th>Value</th>
+</tr>
+<tr>
+  <td>-configfile (required)</td>
+  <td>Specifies the name of the configuration file.</td>
+</tr>
+<tr>
+  <td>-overwrite (optional)</td>
+  <td>If specified, then existing Java files will be overwritten if an existing Java
+      file if found with the same nae as a generated file.  If not specified, and a
+      Java file already exists with the same name as a generated file, then iBATOR
+      will write the newly generated Java file to the proper directory with a
+      unique name (e.g. MyClass.java.1, MyClass.java.2, etc.).
+      <b>Important: iBATOR will always merge and overwrite XML files.</b></td>
+</tr>
+<tr>
+  <td>-contextids (optional)</td>
+  <td>If specified, then this is a comma delimited list of contexts to use in
+      the current run of iBATOR.  Any id specified in the list must exactly
+      match the value of the <code>id</code> attribute of an
+      &lt;ibatorContext&gt; configuration element.  Only ids specified
+      in this list will be active for this run of iBATOR.  If this argument
+      is not specified, then all contexts will be active.</td>
+</tr>
+<tr>
+  <td>-tables (optional)</td>
+  <td>If specified, then this is a comma delimited list of tables to use in
+      the current run of iBATOR.  Any table specified in the list must exactly
+      match the fully qualified table name specified in a
+      &lt;table&gt; configuration element.  Only tables specified
+      in this list will be active for this run of iBATOR.  If this argument
+      is not specified, then all tables will be active.
+      Specify table names as: <br/><br/>
+      <code>table</code><br/>
+      <code>schema.table</code><br/>
+      <code>catalog..table</code><br/>
+      etc.</td>
+</tr>
+</table>
+
+<p>You must create an iBATOR XML configuration file to run iBATOR from the
+   command line.  If the file is
+   named "ibatorConfig.xml", then any of the following command lines will run
+   iBATOR:</p>
+<pre>
+   java -jar ibator.jar -configfile ibatorConfig.xml
+   java -jar ibator.jar -configfile ibatorConfig.xml -overwrite
+   java -cp ibator.jar org.apache.ibatis.ibator.api.IbatorRunner -configfile ibatorConfig.xml
+   java -cp ibator.jar org.apache.ibatis.ibator.api.IbatorRunner -configfile ibatorConfig.xml -overwrite
+</pre>
+
+<h2>Running iBATOR from Ant</h2>
+<p>iBATOR includes a simple Ant task.  The task must be defined in your
+  build.xml file, and the task has three parameters.  Here is an example
+  build.xml file:</p>
+<pre>
+   &lt;project default="genfiles" basedir="."&gt;
+     &lt;property name="generated.source.dir" value="${basedir}" /&gt;
+
+     &lt;target name="genfiles" description="Generate the files"&gt;
+       &lt;taskdef name="ibator"
+                classname="org.apache.ibatis.ibator.ant.IbatorAntTask"
+                classpath="ibator.jar" /&gt;
+       &lt;ibator overwrite="true" configfile="ibatorConfig.xml" verbose="false" &gt;
+         &lt;propertyset&gt;
+           &lt;propertyref name="generated.source.dir"/&gt;
+         &lt;/propertyset&gt;
+       &lt;/ibator&gt;
+     &lt;/target&gt;
+   &lt;/project&gt;
+</pre>
+
+<p>iBATOR task attributes are as follows:</p>
+<table border="1" cellspacing="0" cellpadding="5">
+<tr>
+  <th>Attribute</th>
+  <th>Value</th>
+</tr>
+<tr>
+  <td>configfile (required)</td>
+  <td>Specifies the name of the configuration file.</td>
+</tr>
+<tr>
+  <td>overwrite (optional)</td>
+  <td>If "true", "yes", etc., then existing Java files will be overwritten if an existing Java
+      file if found with the same nae as a generated file.  If "false", "no", etc., and a
+      Java file already exists with the same name as a generated file, then iBATOR
+      will write the newly generated Java file to the proper directory with a
+      unique name (e.g. MyClass.java.1, MyClass.java.2, etc.).
+      <b>Important: iBATOR will always merge and overwrite XML files.</b></td>
+</tr>
+<tr>
+  <td>contextids (optional)</td>
+  <td>If specified, then this is a comma delimited list of contexts to use in
+      the current run of iBATOR.  Any id specified in the list must exactly
+      match the value of the <code>id</code> attribute of an
+      &lt;ibatorContext&gt; configuration element.  Only ids specified
+      in this list will be active for this run of iBATOR.  If this argument
+      is not specified, then all contexts will be active.</td>
+</tr>
+<tr>
+  <td>tables (optional)</td>
+  <td>If specified, then this is a comma delimited list of tables to use in
+      the current run of iBATOR.  Any table specified in the list must exactly
+      match the fully qualified table name specified in a
+      &lt;table&gt; configuration element.  Only tables specified
+      in this list will be active for this run of iBATOR.  If this argument
+      is not specified, then all tables will be active.
+      Specify table names as: <br/><br/>
+      <code>table</code><br/>
+      <code>schema.table</code><br/>
+      <code>catalog..table</code><br/>
+      etc.</td>
+</tr>
+<tr>
+  <td>verbose (optional)</td>
+  <td>If "true", "yes", etc., then iBATOR will log progress messages to the
+      ant console.  The default is "false".</td>
+</tr>
+</table>
+
+<p>Notes:</p>
+<ul>
+  <li>The classpath on the &lt;taskdef&gt; is used to tell Ant where the iBATOR JAR file
+     is.  This is optional if you add iBATOR to the Ant classpath in one
+     of the other ways described in the Ant manual</li>
+   <li>The name of the task can be anything you desire, "ibator" is
+     simply an example</li>
+   <li>The task supports an optional nested <code>&lt;propertyset&gt;</code> element which
+       is the standard Ant property set type.  This can be used to pass parameters into
+       a configuration file.  For example, the above property
+       <code>generated.source.dir</code> can be
+       accessed in the iBATOR configuration file with the escape sequence
+       <code>${generated.source.dir}</code>
+   </li>
+   <li>If a property is specified in the configuration file and is not resolved,
+       then the escaped property string will be passed "as is" into the generated code.
+   </li>
+</ul>
+
+<h2>Running iBATOR from Java with an XML Configuration File</h2>
+<p>The following code sample shows how to call iBATOR from Java.  It does not
+   show exception handling, but that should be obvious from the compiler
+   errors :)</p>
+<pre>
+   List warnings = new ArrayList();  // iBATOR will add Strings to this list
+   boolean overwrite = true;
+   File configFile = new File("ibatorConfig.xml");
+   IbatorConfigurationParser cp = new IbatorConfigurationParser(warnings);
+   IbatorConfiguration config = cp.parseIbatorConfiguration(configFile);
+   DefaultShellCallback callback = new DefaultShellCallback(overwrite);
+   Ibator ibator = new Ibator(config, callback, warnings);
+   ibator.generate(null);
+</pre>
+
+<p>Notes:</p>
+<ul>
+   <li>Configuration file properties may be passed to the parser as a parameter on
+       the IbatorConfigurationParser constructor.  If not passed explicitly, the JVM
+       system properties will be searched for the value of configuration file
+       properties.  For example, the property
+       <code>generated.source.dir</code> can be
+       accessed in the iBATOR configuration file with the escape sequence
+       <code>${generated.source.dir}</code>
+   </li>
+   <li>If a property is specified in the configuration file and is not resolved,
+       then the escaped property string will be passed "as is" into the generated code.
+   </li>
+</ul>
+
+<h2>Running iBATOR from Java with a Java Based Configuration</h2>
+<p>The following code sample shows how to call iBATOR from Java only.  It does
+   not show exception handling, but that should be obvious from the compiler
+   errors :)</p>
+<pre>
+   List warnings = new ArrayList();  // iBATOR will add Strings to this list
+   boolean overwrite = true;
+   IbatorConfiguration config = new IbatorConfiguration();
+
+   //   ... fill out the config object as appropriate...
+
+   DefaultShellCallback callback = new DefaultShellCallback(overwrite);
+   Ibator ibator = new Ibator(config, callback, warnings);
+   ibator.generate(null);
+</pre>
+
+</body>
+</html>
\ No newline at end of file



Mime
View raw message