tomdz 2005/03/18 13:40:09
Modified: src/doc/forrest/src/documentation/content/xdocs/docu/guides
Tag: OJB_1_0_RELEASE xdoclet-module.xml
. Tag: OJB_1_0_RELEASE release-notes.txt
Log:
Updated XDoclet module documentation and release notes
Revision Changes Path
No revision
No revision
1.4.2.3 +118 -25
db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/xdoclet-module.xml
Index: xdoclet-module.xml
===================================================================
RCS file:
/home/cvs/db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/guides/xdoclet-module.xml,v
retrieving revision 1.4.2.2
retrieving revision 1.4.2.3
diff -u -r1.4.2.2 -r1.4.2.3
--- xdoclet-module.xml 5 Jan 2005 19:59:42 -0000 1.4.2.2
+++ xdoclet-module.xml 18 Mar 2005 21:40:08 -0000 1.4.2.3
@@ -422,22 +422,34 @@
<strong>documentation</strong>
</dt>
<dd>
- Optionally contains documentation on the class.
+ Optionally contains documentation on the class. If
no <code>table-documentation</code>
+ attribute is specified, then the value is also used
for the table documentation
+ in the database schema.
+ <br/>
+ </dd>
+ <dt>
+ <strong>generate-repository-info : true (default) |
false</strong>
+ </dt>
+ <dd>
+ Setting this to <code>false</code> prevents the
generation of field/reference/collection
+ descriptors in the repository XML file, and also
automatically enforces
+ <code>generate-table-info = false</code>.<br/>
+ Note that there is one case where the XDoclet module
will still generate field
+ descriptors. If the type is referenced by a
reference or collection, then
+ the corresponding foreign key fields (if 1:n
collection) or primary keys (if
+ reference or m:n collection) will be automatically
included in the class descriptor,
+ even if they are only defined in subtypes.
<br/>
</dd>
-
<dt>
<strong>generate-table-info : true (default) |
false</strong>
</dt>
<dd>
- This attribute controls whether the type has data.
If set to <code>true</code>, the field,
- reference and collection descriptors will be present
in the repository file and a torque
- table descriptor will be created in the database
schema. When set to <code>false</code>,
- only the inheritance information but no field,
reference or collection descriptors are
- generated in the repository file and no table will
be in the database schema.
+ This attribute controls whether the type has an
associated table. If set to
+ <code>true</code>, a torque table descriptor will be
created in the database
+ schema. Otherwise, no table will be in the database
schema for this type.
<br/>
</dd>
-
<dt>
<strong>include-inherited : true (default) |
false</strong>
</dt>
@@ -453,7 +465,6 @@
not.
<br/>
</dd>
-
<dt>
<strong>table</strong>
</dt>
@@ -461,6 +472,13 @@
The name of the table used for this type. Is only
used when table info is generated. If not
specified, then the short name of the type is used.
</dd>
+ <dt>
+ <strong>table-documentation</strong>
+ </dt>
+ <dd>
+ Optionally contains documentation for the table in
the database schema.
+ <br/>
+ </dd>
</dl>
<p>
@@ -511,10 +529,11 @@
...
/**
- * @ojb.class table="Artikel"
+ * @ojb.class table="ARTICLE"
* proxy="dynamic"
* include-inherited="true"
* documentation="This is important documentation on the Article
class."
+ * table-documentation="And this is important documentation on
the ARTICLE table."
* attributes="color=blue,size=big"
*/
public class Article extends AbstractArticle implements InterfaceArticle,
java.io.Serializable
@@ -538,7 +557,7 @@
<class-descriptor
class="org.apache.ojb.broker.Article"
proxy="dynamic"
- table="Artikel"
+ table="ARTICLE"
>
<documentation>This is important documentation on the Article
class.</documentation>
...
@@ -607,9 +626,11 @@
<link href="#ojb.field">ojb.field</link>,
<link href="#ojb.reference">ojb.reference</link>, and
<link href="#ojb.collection">ojb.collection</link> (with
- the exception of
- <strong>indirection-table</strong> and
- <strong>remote-foreignkey</strong>), and also:
+ the exception of the attributes related to indirection
tables (
+ <strong>indirection-table</strong>,
<strong>remote-foreignkey</strong>,
+ <strong>indirection-table-primarykeys</strong>,
<strong>indirection-table-documentation</strong>,
+ <strong>foreignkey-documentation</strong>,
<strong>remote-foreignkey-documentation</strong>),
+ and also:
</p>
<dl>
<dt>
@@ -1324,8 +1345,8 @@
have the same attributes.
</p>
<p>
- Due to a bug in XDoclet, you currently cannot process
<code>final</code> or <code>transient</code>
- fields.
+ Due to a bug in XDoclet, it is currently not possible to
process <code>final</code> or
+ <code>transient</code> fields.
</p>
<p>
Marked fields are used for descriptor generation in the
same type (if it has an
@@ -1419,7 +1440,13 @@
used.
<br/>
</dd>
-
+ <dt>
+ <strong>column-documentation</strong>
+ </dt>
+ <dd>
+ Optionally contains documentation on the column in
the database schema.
+ <br/>
+ </dd>
<dt>
<strong>conversion</strong>
</dt>
@@ -1461,7 +1488,9 @@
<strong>documentation</strong>
</dt>
<dd>
- Optionally contains documentation on the field.
+ Optionally contains documentation on the field. If
no <code>column-documentation</code>
+ attribute value is specified, then this value is
also used for the documentation
+ of the column in the database schema.
<br/>
</dd>
@@ -1846,6 +1875,7 @@
* @ojb.field column="Auslaufartikel"
* jdbc-type="INTEGER"
*
conversion="org.apache.ojb.broker.accesslayer.conversions.Boolean2IntFieldConversion"
+ * column-documentation="Some documentation on the column"
* id="10"
* attributes="color=green,size=small"
*/
@@ -1872,6 +1902,7 @@
<column name="Auslaufartikel"
javaName="isSelloutArticle"
type="INTEGER"
+ description="Some documentation on the column"
/>
...
</table>]]></source>
@@ -1988,7 +2019,19 @@
<link href="#ojb.class">ojb.class</link> tag.
<br/>
</dd>
-
+ <dt>
+ <strong>database-foreignkey : true (default) |
false</strong>
+ </dt>
+ <dd>
+ Specifies whether a database foreignkey shall be
generated for the reference. Note
+ that this attribute is only evaluated if the XDoclet
module has determined that
+ a database foreignkey could be generated. You cannot
force the generation with this
+ attribute, and the value of the attribute is not
considered when checking if
+ database foreignkeys can be generated in case the
referencing class has subtypes
+ (in which case database foreignkeys can only be
generated if all subtypes map to the
+ same table or don't map to a table or the
inheritance is mapped via a super-reference).
+ <br/>
+ </dd>
<dt>
<strong>documentation</strong>
</dt>
@@ -2150,7 +2193,21 @@
<strong>collection-class</strong> attribute
automatically. Otherwise, you have to specify it.
<br/>
</dd>
-
+ <dt>
+ <strong>database-foreignkey : true (default) |
false</strong>
+ </dt>
+ <dd>
+ Specifies whether a database foreignkey shall be
generated for the collection. Note
+ that this attribute is only evaluated if the XDoclet
module has determined that
+ a database foreignkey could be generated. You cannot
force the generation with this
+ attribute, and the value of the attribute is not
considered when checking if
+ database foreignkeys can be generated in the case of
subtypes of the element type or
+ the type having the collection (if m:n collection).
For 1:n collections, database
+ foreignkeys can only be generated if all subtypes of
the element type map to the
+ same table or don't map to a table or the
inheritance is mapped via a super-reference.
+ For m:n collections, the same applies to the class
owning the collection.
+ <br/>
+ </dd>
<dt>
<strong>documentation</strong>
</dt>
@@ -2188,6 +2245,14 @@
type.
<br/>
</dd>
+ <dt>
+ <strong>foreignkey-documentation</strong>
+ </dt>
+ <dd>
+ Optionally contains documentation for the columns in
the indirection table in the database schema
+ that point to this class.
+ <br/>
+ </dd>
<dt>
<strong>indirection-table</strong>
@@ -2206,6 +2271,22 @@
type (and length setting if necessary) of these
primarey keys for the columns.
<br/>
</dd>
+ <dt>
+ <strong>indirection-table-documentation</strong>
+ </dt>
+ <dd>
+ Optionally contains documentation for the
indirection table in the database schema.
+ <br/>
+ </dd>
+ <dt>
+ <strong>indirection-table-primarykeys : true | false
(default)</strong>
+ </dt>
+ <dd>
+ Specifies that the columns in the indirection table
that point to this type, are
+ primary keys of the table. If the element type has
no corresponding collection,
+ then this setting is also applied to the columns
pointing to the element type.
+ <br/>
+ </dd>
<dt>
<strong>orderby</strong>
@@ -2248,6 +2329,16 @@
attribute is ignored if used with 1:n collections
(no indirection table specified).
<br/>
</dd>
+ <dt>
+ <strong>remote-foreignkey-documentation</strong>
+ </dt>
+ <dd>
+ Optionally contains documentation for the columns in
the indirection table in the database schema
+ that point to the element type. This value can be
used when the element type has no
+ corresponding collection (i.e. remote-foreignkey is
specified) or if the corresponding
+ collection does not specify the
<code>foreignkey-documentation</code> attribute.
+ <br/>
+ </dd>
</dl>
<p>
The same attributes as for references are written
directly to the repository descriptor file (see
@@ -2449,10 +2540,12 @@
<em>Attributes:</em> All of
<link href="#ojb.field">ojb.field</link>,
<link href="#ojb.reference">ojb.reference</link>, and
- <link href="#ojb.collection">ojb.collection</link> (with
- the exception of
- <strong>indirection-table</strong> and
- <strong>remote-foreignkey</strong>), and also:
+ <link href="#ojb.collection">ojb.collection</link> with
+ the exception of the attributes related to indirection
tables (
+ <strong>indirection-table</strong>,
<strong>remote-foreignkey</strong>,
+ <strong>indirection-table-primarykeys</strong>,
<strong>indirection-table-documentation</strong>,
+ <strong>foreignkey-documentation</strong>,
<strong>remote-foreignkey-documentation</strong>),
+ and also:
</p>
<dl>
<dt>
No revision
No revision
1.54.2.38 +25 -1 db-ojb/release-notes.txt
Index: release-notes.txt
===================================================================
RCS file: /home/cvs/db-ojb/release-notes.txt,v
retrieving revision 1.54.2.37
retrieving revision 1.54.2.38
diff -u -r1.54.2.37 -r1.54.2.38
--- release-notes.txt 18 Mar 2005 19:50:00 -0000 1.54.2.37
+++ release-notes.txt 18 Mar 2005 21:40:09 -0000 1.54.2.38
@@ -22,6 +22,30 @@
- Oracle9i plaform now handles CLOB>4k and BLOB>2k when DBCP and/or P6Spy
are used.
- Oracle9i plaform can now be used with Oracle10g JDBC-driver. Escape
processing statements are
removed and OracleConnection unwrapping have been adjusted to be
compatible with 10g JDBC.
+- XDoclet module:
+ * Important: generate-table-info now only prevents the generation of a
table in the database schema,
+ the class-descriptor is unaffacted
+ * The new ojb.class#generate-repository-info attribute prevents the
generation of field/reference/collection
+ descriptors in the repository as well as the table in the database
schema
+ This attribute should be used when using inheritance with
interfaces/abstract classes
+ * Database foreignkeys are now generated for collections, as well
+ * It is possible to prevent the generation of database foreignkeys for
individual references
+ or collections using the database-foreignkey attribute
(ojb.collection/ojb.reference).
+ However this attribute cannot be used to force generation of
database-foreignkeys
+ * Inheritance with interfaces/abstract classes (i.e. classes without
table) is now handled properly
+ for types that are referenced by references/collections even if the
relevant foreignkey
+ (reference/1:n collection) or primarykey (m:n collection) is not
defined in the basetype itself
+ but only in the subtypes. The XDoclet module will determine these
fields and generate virtual
+ field descriptors in the class-descriptor of the basetype (even if
generate-repository-info=false).
+ Additionally, database foreignkeys are generated if the subtypes map
to the same table
+ * Additional attributes for generating documentation in the database
schema:
+ - ojb.class#table-documentation
+ - ojb.field#column-documentation
+ - ojb.collection#indirection-table-documentation
+ - #foreignkey-documentation
+ - #remote-foreignkey-documentation
+ * Foreignkey columns of an m:n collection can be made primarykeys of the
indirection table by
+ using the ojb.collection#indirection-table-primarykeys attribute
NOTES:
- ODMG-api refactoring!! All known issues in test suite are fixed. But the
refactored odmg-api
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
