db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From to...@apache.org
Subject cvs commit: db-ojb/xdocs xdoclet-module.xml
Date Fri, 26 Dec 2003 20:19:46 GMT
tomdz       2003/12/26 12:19:46

  Modified:    xdocs    xdoclet-module.xml
  Log:
  Updated to reflect changes to the module
  
  Revision  Changes    Path
  1.5       +103 -71   db-ojb/xdocs/xdoclet-module.xml
  
  Index: xdoclet-module.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/xdoclet-module.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- xdoclet-module.xml	23 Dec 2003 22:19:26 -0000	1.4
  +++ xdoclet-module.xml	26 Dec 2003 20:19:46 -0000	1.5
  @@ -13,23 +13,51 @@
           </p>
           <p>
           In order to build the XDoclet OJB module from source, you'll need a source distribution
of XDoclet
  -        &gt;= version 1.2b3, preferably a CVS checkout or CVS drop (see the XDoclet
website at
  -        <a href="http://xdoclet.sourceforge.net/install.html">http://xdoclet.sourceforge.net/install.html</a>
on
  -        how to obtain a source version of XDoclet).<br/>
  +        version 1.2, either a source distribution from the sourceforge download site or
a CVS checkout/drop. See
  +        the XDoclet website at
  +        <a href="http://xdoclet.sourceforge.net/install.html">http://xdoclet.sourceforge.net/install.html</a>
for
  +        details.</p>
  +
  +		<subsection name="Building with a XDoclet source distribution">
  +		<p>
  +		Unpack the source distribution of XDoclet which is contained in a file
  +		<code>xdoclet-src-&lt;version&gt;.&lt;archive-format&gt;</code>
somewhere. If you unpacked it side-by-side of
  +		OJB, you'll get a directory layout similar to:
  +		</p>
  +        <source><![CDATA[
  +    \xdoclet-1.2
  +        \config
  +        \core
  +        \lib
  +        ...
  +    \db-ojb
  +        \bin
  +        \contrib
  +        ...
  +        ]]></source>
  +        <p>
           The XDoclet OJB module is then build using the <code>build-xdoclet-module.xml</code>
ant script:
           </p>
           <source><![CDATA[
  -ant -Dxdoclet.src.dir=<xdoclet src dir> -f build-xdoclet-module.xml
  +ant -Dxdoclet.src.dir=../xdoclet-1.2 -f build-xdoclet-module.xml
           ]]></source>
           <p>
  -        where <code>&lt;xdoclet src dir&gt;</code> stands for the directory
that contains the XDoclet source.
  -        The <code>xdoclet.src.dir</code> build property is per default set
to <code>../xdoclet-all/xdoclet</code>
  -        which assumes the following directory structure (as the result of a CVS checkout
of xdoclet with the
  -        <code>xdoclet-all</code> CVS module):
  +        The build process will take some time, and after successful compilation the three
jars
  +        <code>xjavadoc-&lt;version&gt;.jar</code>, <code>xdoclet-&lt;version&gt;.jar</code>,
and
  +        <code>xdoclet-ojb-module-&lt;version&gt;.jar</code> are copied
to the library directory of OJB.
           </p>
  +        </subsection>
  +
  +		<subsection name="Building with a XDoclet CVS checkout">
  +		<p>
  +		When checking out from CVS (the <code>xdoclet-all</code> target), you'll
get a directory like:
  +		</p>
           <source><![CDATA[
       \xdoclet-all
           \xdoclet
  +        	\config
  +        	\core
  +        	...
           \xdocletgui
           \xjavadoc
       \db-ojb
  @@ -38,24 +66,28 @@
           ...
           ]]></source>
           <p>
  -        In this case, you can omit the <code>-Dxdoclet.src.dir</code> option.<br/>
  -        Building with a source distribution of xdoclet (from the SourceForge download site)
also works. The
  -        <code>-Dxdoclet.src.dir</code> option then refers to the directory
where the source archive was extracted
  -        into.<br/>
  -        The build script for the XDoclet OJB module also uses the OJB build properties
so you could also
  -        add a line 
  -        </p>
  +		Building is XDoclet OJB module is performed by calling:
  +		</p>
           <source><![CDATA[
  -xdoclet.src.dir=<xdoclet src dir>
  +ant -Dxdoclet.src.dir=../xdoclet-all/xdoclet -f build-xdoclet-module.xml
           ]]></source>
           <p>
  -        to your <code>build.properties</code> file instead of using the <code>-D</code>
option.<br/>
  -        The build process will take some time, and after successful compilation the three
jars
  -        <code>xjavadoc-&lt;version&gt;.jar</code>, <code>xdoclet-&lt;version&gt;.jar</code>,
and
  -        <code>xdoclet-ojb-module-&lt;version&gt;.jar</code> are copied
from the directories
  -        <code>&lt;xdoclet src dir&gt;\lib</code> and <code>&lt;xdoclet
src dir&gt;\target\lib</code>
  -        respectively, to the library directory of OJB.
  +        Since this is the default structure assumed by the build script, this can be shortend
to:
  +        </p>
  +        <source><![CDATA[
  +ant -f build-xdoclet-module.xml
  +        ]]></source>
  +		</subsection>
  +		<subsection name="Other build options">
  +		<p>
  +        The build script for the XDoclet OJB module uses the OJB build properties so the
following line
  +        added to the <code>build.properties</code> file in the OJB root directory
allows to omit
  +        the <code>-Dxdoclet.src.dir=&lt;xdoclet src dir&gt;</code>
commandline option:
           </p>
  +        <source><![CDATA[
  +xdoclet.src.dir=<xdoclet src dir>
  +        ]]></source>
  +        </subsection>
           </section>
   
           <section name="Usage">
  @@ -179,8 +211,7 @@
           <dt>References</dt>
           <dd><a href="#ojb.reference">ojb.reference</a></dd>
           <dt>Collections</dt>
  -        <dd><a href="#ojb.collection">ojb.collection</a><br/>
  -        <a href="#ojb.query-customizer">ojb.query-customizer</a></dd>
  +        <dd><a href="#ojb.collection">ojb.collection</a><br/></dd>
           </dl>
           </p>
           </section>
  @@ -191,7 +222,7 @@
           <p>
           The <b>ojb.class</b> tag marks interfaces and classes that shall be
present in the repository
           descriptor. This includes types that are used as reference targets or as collection
elements, but
  -        for instance not abstract base classes not used elsewhere.
  +        for instance not abstract base classes not used elsewhere. 
           </p>
           <p>
           <i>Attributes:</i>
  @@ -441,8 +472,10 @@
           <subsection name="ojb.index">
           <p>
           The <b>ojb.index</b> tag is used to define possibly unique indices
for the class. An index consists of
  -        at least one field of the class (either locally defined or inherited, anonymous
or explicit). Note
  -        that indices are not inherited.
  +        at least one field of the class (either locally defined or inherited, anonymous
or explicit). There is
  +        an default index (without a name) that is made up by all fields that have the <b>indexed</b>
attribute
  +        set to <code>true</code>. All other indices have to be defined via
the <b>ojb.index</b> tag. In contrast
  +        to the <b>indexed</b> attribute, indices defined via the <b>ojb.index</b>
tag are not inherited.
           </p>
           <p>
           <i>Attributes:</i>
  @@ -454,7 +487,8 @@
           <dt><b>fields</b></dt>
           <dd>The fields that make up the index separated by commas.</dd><br/>
           <dt><b>name</b></dt>
  -        <dd>The name of the index.</dd><br/>
  +        <dd>The name of the index (required). If there are multiple indices with
the same name, then only the first
  +        one is used (all others are ignored).</dd><br/>
           <dt><b>unique</b></dt>
           <dd>Whether the index is unique or not.</dd>
           </dl>
  @@ -471,6 +505,10 @@
   public class Site implements Serializable
   {
       /**
  +     * @ojb.field indexed="true"
  +     */
  +    private Integer nr;
  +    /**
        * @ojb.field column="NAME"
        *            length="100"
        */
  @@ -487,11 +525,19 @@
       table="SITE"
   >
       <field-descriptor
  +        name="nr"
  +        column="nr"
  +        jdbc-type="INTEGER"
  +        indexed="true"
  +    >
  +    </field-descriptor>
  +    <field-descriptor
           name="name"
           column="NAME"
           jdbc-type="VARCHAR"
           length="100"
       >
  +    </field-descriptor>
       ...
       <index-descriptor
           name="NAME_UNIQUE"
  @@ -506,12 +552,19 @@
           </p>
           <source><![CDATA[
   <table name="SITE">
  +    <column name="nr"
  +            javaName="nr"
  +            type="INTEGER"
  +    />
       <column name="NAME"
               javaName="name"
               type="VARCHAR"
               size="100"
       />
       ...
  +	<index>
  +		<index-column name="nr"/>
  +	</index>
       <unique name="NAME_UNIQUE">
           <unique-column name="NAME"/>
       </unique>
  @@ -839,8 +892,7 @@
    * @ojb.field name="eID"
    *            column="E_ID"
    *            jdbc-type="INTEGER"
  - * @ojb.reference name="super"
  - *                class-ref="org.apache.ojb.broker.E"
  + * @ojb.reference class-ref="org.apache.ojb.broker.E"
    *                auto-retrieve="true"
    *                auto-update="true"
    *                auto-delete="true"
  @@ -878,8 +930,9 @@
   </class-descriptor>
           ]]></source>
           <p>
  -        Here the anonymous field and reference are used to establish the super-subtype
relationship between
  -        <code>E</code> and <code>F</code> on the database level.
For details on this see the
  +        Here the anonymous field and reference (which implicitly refers to <code>super</code>)
are used to
  +        establish the super-subtype relationship between <code>E</code> and
<code>F</code> on the database
  +        level. For details on this see the
           <a href="tutorial3.html#Mapping%20Each%20Class%20to%20a%20Distinct%20Table">tutorial</a>.
           </p>
           </subsection>
  @@ -899,12 +952,10 @@
           Foreign keys of references are also declared in the torque table schema (see example
below).<br/>
           OJB currently requires that the referenced type has at least one field used to
implement the
           reference, usually some id of an integer type.<br/>
  -        Anonymous references where there is no field in the class for the reference are
also supported.
  -        Similar to anonymous fields, the <b>ojb.reference</b> tag for an anonymous
reference is specified in
  -        the JavaDoc comment of the class, and the <b>name</b> and <b>class-ref</b>
attributes are required.
  -        The foreignkeys of the reference can be anonymous fields. One special case of anoymous
references are
  -        the <code>super</code> references used to establish an inheritance
relationship (for an example see
  -        <a href="#ojb.field.example">ojb.field</a>).
  +        A reference can be stated in the JavaDoc comment of the class (anonymous reference),
but in this case
  +        it silently refer to <code>super</code> (see the example of <a href="#ojb.field.example">ojb.field</a>)
  +        which can be used to establish an inheritance relationship. Note that anonymous
references are not
  +        inherited (in contrast to anonymous fields and normal references).
           </p>
           <p>
           <i>Attributes:</i>
  @@ -926,11 +977,7 @@
           <dt><b>foreignkey</b></dt>
           <dd>Contains one or more foreign key fields (separated by commas). The foreign
key fields are fields
               with the <a href="#ojb.class">ojb.field</a> tag in the same class
as the reference, which
  -            implement the association, i.e. contains the values of the primarykeys of the
referenced object.
  -        <dt><b>name</b></dt>
  -        <dd>The name of the reference. This attribute is required for anonymous references,
otherwise it is
  -            ignored.</dd>
  -        </dd>
  +            implement the association, i.e. contains the values of the primarykeys of the
referenced object.</dd>
           </dl>
           </p>
           <p>
  @@ -1032,8 +1079,11 @@
           <dd>Optionally contains attributes of the collection as a comma-separated
list of name-value
               pairs.</dd><br/>
           <dt><b>collection-class</b></dt>
  -        <dd>Specifies the class that implements the collection. This attribute usually
is not necessary, as
  -            the xdoclet ojb module checks whether the type of the collection field implements
the
  +        <dd>Specifies the class that implements the collection. This attribute is
usually only required if
  +            the actual type of the collection object shall be different from the variable
type.<br/>
  +            Collection classes that implement <code>java.util.Collection</code>
can be handled by OJB as-is
  +            so specifying them is not necessary. For the types that do not, the xdoclet
ojb module checks 
  +            whether the collection field type implements the
               <code>org.apache.ojb.broker.ManageableCollection</code> interface,
and if so, generates the
               collection-class attribute automatically.</dd><br/>
           <dt><b>documentation</b></dt>
  @@ -1067,6 +1117,12 @@
               comma-separated list of name-value pairs. For instance, <code>field1=DESC,field2,field3=ASC</code>
               specifies three fields after which to sort, the first one in descending order
and the other two in
               ascending order (which is the default and can be omitted).</dd><br/>
  +        <dt><b>query-customizer</b></dt>
  +        <dd>Specifies a query customizer for the collection. The type is required
to implement
  +            <code>org.apache.ojb.broker.accesslayer.QueryCustomizer</code>.</dd>
  +        <dt><b>query-customizer-attributes</b></dt>
  +        <dd>Specifies attributes for the query customizer. This attribute is ignored
if no query customizer
  +            is specified for this collection.</dd>
           <dt><b>remote-foreignkey</b></dt>
           <dd>Contains one or more foreign key columns (separated by commas) in the
indirection table pointing
               to the elements. Note that this field should only be used if the other type
does not have a
  @@ -1097,8 +1153,8 @@
        *                 auto-update="false"
        *                 auto-delete="true"
        *                 orderby="productGroupId=DESC"
  -     * @ojb.query-customizer class="org.apache.ojb.broker.accesslayer.QueryCustomizerDefaultImpl"
  -     *                       attributes="attr1=value1"
  +     *                 query-customizer="org.apache.ojb.broker.accesslayer.QueryCustomizerDefaultImpl"
  +     *                 query-customizer-attributes="attr1=value1"
        */
       private ArticleCollection allArticlesInGroup;
           ]]></source>
  @@ -1208,30 +1264,6 @@
           </subsection>
           <p/>
   
  -        <subsection name="ojb.query-customizer">
  -        <p>
  -        Specifies a query customizer for the collection. The type is required to implement
  -        <code>org.apache.ojb.broker.accesslayer.QueryCustomizer</code>
  -        </p>
  -        <p>
  -        <i>Attributes:</i>
  -        </p>
  -        <p>
  -        <dl>
  -        <dt><b>attributes</b></dt>
  -        <dd>Optionally contains attributes of the query customizer as a comma-separated
list of name-value
  -            pairs.</dd><br/>
  -        <dt><b>class</b></dt>
  -        <dd>The fully qualified name of the query customizer class.</dd><br/>
  -        <dt><b>documentation</b></dt>
  -        <dd>Optionally contains documentation on the query customizer.</dd>
  -        </dl>
  -        </p>
  -        <p>
  -        <a name="ojb.query-customizer.example"><i>Example:</i></a>
see
  -        <a href="#ojb.collection.example">ojb.collection</a>
  -        </p>
  -        </subsection>
           </section>
       </body>
   </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org


Mime
View raw message