XDoclet: Attribute-Oriented Programming - Tag Reference

##### XDoclet

- Overview
- News and Status
- Download/Installation
- Using XDoclet
- Best Practices
- FAQ
- License

##### Ant Task Reference

- <doclet .. />
- <ejbdoclet .. />
- <hibernatedoclet .. />
- <jdodoclet .. />
- <jmxdoclet .. />
- <mockdoclet .. />
- <portletdoclet .. />
- <springdoclet .. />
- <tapestrydoclet .. />
- <webdoclet .. />
- <wseedoclet .. />

##### Tag Reference

- apache (@soap @struts @axis @tapestry)
- bea (@weblogic)
- borland (@bes)
- caucho (@resin)
- ejb (@ejb @dao)
- exolab (@castor)
- hp (@hpas)
- hibernate (@hibernate)
- ibm (@websphere)
- java (@javabean)
- jboss (@jboss)
- jdo (@jdo)
- jmx (@jmx)
- jsf (@jsf)
- macromedia (@jrun)
- mockobjects (@mock)
- mvcsoft (@mvcsoft)
- mx4j (@mx4j)
- objectweb (@jonas)
- oracle (@oc4j)
- orion (@orion)
- portlet (@portlet)
- pramati (@pramati)
- spring (@spring)
- sun (@sunone)
- sybase (@easerver)
- tjdo (@tjdo)
- web (@web @jsp)
- webwork (@webwork)
- wsee (@wsee)
- xdoclet (@xdoclet @doc @msg)

##### Feature Documentation

- Using Value Objects
- EJB Environment Handling

##### Advanced

- Maven Plug-in
- Merge Points
- IDE Integration
- Migration from EJBDoclet
- Ant 1.5 Troubleshooting

##### Community

- Feedback
- Resources
- Tools

##### Development

- Developer Guide
- Javadoc (API)
- Template Language (*.xdt)
- XJavaDoc Site

##### Search XDoclet

##### Project Documentation

- About XDoclet
- Project Info
- Project Reports
- Development Process

## @jdo Tag Reference

JDO tags used to generate jdo xml metadata. The tag names are identical to the element names in jdo.dtd.

Applies to: classes to be persistence-capable on class and field level

### @jdo Class Level Tags

@jdo.fetchgroup
@jdo.persistence-capable
@jdo.query
@sql.table

### @jdo Method Level Tags

### @jdo Field Level Tags

@jdo.field
@jdo.join
@jdo.join-column
@jdo.join-vendor-extension
@sql.field
@sql.relation

## @jdo Class Level Tag Usage

### @jdo.fetchgroup (0..*)

Defines a fetch-group to be used by JDO detach. Example: @jdo.fetch-group name="fetch-some-fields" field-names="field0, field1, field2"

Applies to: Applicable to the whole class.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
name | text |  | Defines the name of the fetch-group. | true
post-load | bool |  |  | false
field-names | text |  | A comma-separated list of the fields that should be contained by this fetch-group. This list may contain spaces for better readability - they are ignored. | false
fetch-group-names | text |  | A comma-separated list of previously defined fetch-groups to be included in this fetch-group. This avoids rewriting all the fields by just refering other fetch-groups. This list may contain spaces for better readability - they are ignored. | false

### @jdo.persistence-capable (0..1)

The jdo.persistence-capable tag provides information about the JDO persistent bean. Its presence determines if your class will be included in the generated jdo metadata.

Applies to: The presence of the jdo.persistence-capable tag determines if a class will be included in the generated jdo metadata and thus if it will be enhanced to PersistenceCapable

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
identity-type | text |  | Specifies whether objects are uniquely identified by a jdo-implementation provided abstract identifier (datastore identity), accessible fields in the object (application identity), or not at all (nondurable identity). Valid options are: application datastore nondurable Default value(s): datastore | true
objectid-class | text |  | The fully-qualified class name for the application identity object id. Use only with application identity. | false
requires-extent | bool |  | Specifies whether the jdo implementation must provide an extent for this class. Default value(s): true | false
persistence-capable-superclass | text |  | Fully-qualified class name of the PersistenceCapable super class, if any. | false

### @jdo.query (0..*)

Defines a a named query in the one-string-notation.

Applies to: Applicable to the whole class.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
name | text |  | Defines the name of the query. | true
language | text |  | Defines the query language. Possible values are 'javax.jdo.query.JDOQL', 'javax.jdo.query.SQL' or 'javax.jdo.query.JPOXSQL' (a vendor extension of the JPOX project). Other languages may be supported by your JDO implementation, but only the first two are guaranteed to be supported by all JDO libraries. Default value(s): javax.jdo.query.JDOQL | false
query | text |  | The query expression itself, e.g. "SELECT FROM org.jpox.example.Product WHERE status == 'Sold Out'" | true

### @sql.table (0..1)

Defines the mapping to a relational database. To use if the JDO bean is to be persisted on a relational database. WARNING: All sql.* tags are not supported by most of the JDO implementations and are replaced by new tags in JDO2!

Applies to: Applicable to the whole class.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
table-name | text |  | Name of the table to map to. | false

## @jdo Method Level Tag Usage

## @jdo Field Level Tag Usage

### @jdo.field (0..1)

Defines a JDO persistent field. The jdo.field tag can be used on any persistent field or to specify non-default properties. Many jdo implementation require explicit listing of collection-valued fields.

Applies to: The jdo.field tag can be used on any persistent field or to specify non-default properties. Many jdo implementation require explicit listing of collection-valued fields.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
persistence-modifier | text |  | Specifies if the field is persistent, transactional or none of these. Valid options are: persistent transactional none Default value(s): persistent | false
primary-key | bool |  | Specifies whether or not this field is part of the primary key for application identity. Default value(s): false | false
null-value | text |  | Specifies the treatment (exception, default, or none) of null values for persistent fields during storage in the data store. Valid options are: exception default none Default value(s): none | false
default-fetch-group | bool |  | Specifies whether this field is managed as a group with other fields. It defaults to "true" for non-key fields of primitive types, java.util.Date, and fields of java.lang, java.math types specified above. | false
embedded | bool |  | Specifies whether the field should be stored if possible as part of the instance instead of as its own instance in the datastore. It defaults to "true" for fields of primitive types, java.util.Date, and fields of java.lang, java.math, and array types specified above. This attribute is only a hint to the implementation. A compliant implementation is permitted to support these types as first class instances in the datastore. A portable application should not depend on the embedded treatment of persistent fields. | false
collection-type | text |  | The collection-type property specifies the type (collection, map, or array) of a collection valued field and provides details about the elements and their storage. Valid options are: collection map array | false
element-type | text | Must be used with collection or array valued persistent field | The element-type property specifies the fully qualified java class name of the element of a collection or array-valued persistent field. | false
embedded-element | bool | Must be used only with a collection or array valued persistent field. | The embedded-element property specifies whether the elements of a collection or array-valued persistent field should be stored embedded or as first class objects. Default value(s): true | false
key-type | text | Must be used only with a map valued persistent field. | The key-type property specifies the fully qualified java class name of the keys of map-valued persistent field. | false
embedded-key | bool | Must be used only with a map valued persistent field. | The embedded-key property specifies whether the keys of a map-valued persistent field should be stored embedded or as first class objects. Default value(s): true | false
value-type | text | Must be used only with a map valued persistent field. | The value-type property specifies the fully qualified java class name of the values of map-valued persistent field. | false
embedded-value | bool | Must be used only with a map valued persistent field. | The embedded-value property specifies whether the values of a map-valued persistent field should be stored embedded or as first class objects. Default value(s): true | false
mapped-by | text | Must be used with collection, map or array valued persistent field, in case it is a double ended (or inverse) relationship. | The mapped-by property can only be used in JDO 2.0! It is necessary for inverse (double-ended) maps/collections. It specifies the member of the element class (element within the collection), which points back to the owner class. Example: Person.addresses is a collection having instances of type Address. Address.person is the member that makes Address know to which person it belongs. Thus, in the declaration of Person.addresses, mapped-by="person" must be specified. | false
table | text |  | This parameter can only be used in JDO 2.0! | false
column | text |  | This parameter can only be used in JDO 2.0! It defines the name of the column into which this field should be persisted. You can use '@jdo.column name="xxx"' alternatively. | false
serialized | bool |  | This parameter can only be used in JDO 2.0! | false
dependent | bool |  | This parameter can only be used in JDO 2.0! It controls whether to delete the object in this field if the container object is deleted out of the store. Some people call this behaviour 'cascaded delete'. | false
value-strategy | text |  | This parameter can only be used in JDO 2.0! It defines how to automatically assign values to this field. This works in application identity and can be used to generate values for one of the primary key fields. Possible values that a JDO implementation might support are: 'native', 'sequence', 'autoassign', 'increment', 'identity' 'uuid-string', 'max', 'custom' | false
delete-action | text |  | This parameter can only be used in JDO 2.0! Possible values are: 'restrict', 'cascade', 'null', 'default', 'none' | false
indexed | text |  | This parameter can only be used in JDO 2.0! Possible values are: 'true', 'false', 'unique' | false
unique | bool |  | This parameter can only be used in JDO 2.0! | false
sequence | text |  | This parameter can only be used in JDO 2.0! | false
foreign-key | text |  | This parameter can only be used in JDO 2.0! | false
load-fetch-group | text |  | This parameter can only be used in JDO 2.0! It defines which fetch-group should be used for loading the object in this field member. | false
fetch-depth | int |  | This parameter can only be used in JDO 2.0! It defines, how many levels the JDO implementation should dive into the object graph for detaching. This is especially useful when an object contains a member of the same class as itself (or if there is an indirect circle). | false

### @jdo.join (0..1)

The jdo.join tag is only available in JDO 2.0! When defining a collection (or a map), there are two possibilities: Either the linked object knows its owner (this is called "inverse relationship") or not (which is called "normal relationship"). If using an inverse relationship, you don't use jdo.join but set the property mapped-by of the tag jdo.field. For a normal relationship, jdo.join defines parameters of how the owner shall be linked to its collection/map elements.

Applies to: Applicable to a persistent field of type Collection or Map and only with a normal relationship (not with inverse relationships).

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
table | text |  | Name of the relation table. | false
column | text |  |  | false
outer | text |  |  | false
foreign-key | text |  |  | false

### @jdo.join-column (0..*)

The jdo.join-column tag is only available in JDO 2.0! It is used to specify information for each column used in a normal relationship in a Collection/Map.

Applies to: Applicable only if jdo.join has been defined.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
name | text |  |  | false
target | text |  |  | false
target-field | text |  |  | false
jdbc-type | text |  |  | false
sql-type | text |  |  | false
length | text |  |  | false
scale | text |  |  | false
precision | text |  |  | false
allows-null | text |  |  | false

### @jdo.join-vendor-extension (0..1)

The jdo.join-vendor-extension tag is only available in JDO 2.0! It allows to define additional metadata that is not defined in the JDO 2.0 standard.

Applies to: Applicable only if jdo.join has been defined.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
vendor-name | text |  |  | true
key | text |  |  | true
value | text |  |  | true

### @sql.field (0..*)

Defines the mapping of a field to a relational database. To use if the JDO bean is to be persisted on a relational database. Usually only one @jdo.mapping tag is required for a basic persistent field, except for fields that link to a persistence-capable class, where there are as many @jdo.mapping tags as there are foreign keys to this class, and for fields that represent a 1:n relationship where no @jdo.mapping tag is required, and finally for fields that represent a n:m relationship where there are as many @jdo.mapping tags as there are foreign keys from the relation table to the table for this class.

Applies to: Applicable to a persistent field (basic field or object relationship)

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
table-name | text | The field must be in a sub-class mapped partially onto another table. | (Experimental) For basic fields part of an inheritance mapping onto multiple tables, the name of the table that the field is mapped to. | false
column-name | text | Applicable only on a persistent field | Name of the column to map the field to. For fields representing a n:m relationship, name of one of the foreign key column in the relation table pointing to the table for this class. | true
related-field | text | The field must be a collection representing a n:m relationship | Name of the field in this class matching the foreign key in the relation table. | false

### @sql.relation (0..1)

Further defines the mapping of a field of type Collection.

Applies to: Applicable to a persistent field of type Collection

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
style | text | Applicable only on a persistent field of type Collection | The style of the mapping between this class and the objects contained in the collection. For 1:n relationships, the style is 'foreign-key'. For n:m relationships, the style is 'relation-table' Valid options are: foreign-key relation-table | true
table-name | text | Applicable only on a persistent field of type Collection used in a n:m relationship | Name of the relation table when style is 'relation-table' | false
related-field | text | Applicable only on a persistent field of type Collection | Name of the field in the class contained in the collection refering to this class. For a 1:n relationship, this is a field of the same type as this class, for a n:m relationship, it is a field of type Collection containing elements of the same type as this class. | false