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

## @MVCSoft Tag Reference

MVCSoft Persistence Manager tags

Applies to: Entity Beans - on class and method levels

### @MVCSoft Class Level Tags

@mvcsoft.entity
@mvcsoft.fault-group
@mvcsoft.high-low-key
@mvcsoft.query
@mvcsoft.unknown-key
@mvcsoft.uuid-key

### @MVCSoft Method Level Tags

@mvcsoft.col-name
@mvcsoft.exclude-from-optimistic-lock
@mvcsoft.jdbc-type
@mvcsoft.lightweight
@mvcsoft.relation
@mvcsoft.sql-type
@mvcsoft.wrap

### @MVCSoft Field Level Tags

## @MVCSoft Class Level Tag Usage

### @mvcsoft.entity (0..1)

Sets various configuration options that apply to the entity as a whole

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
table | text |  | The name of the table to which the entity is persisted | true
cache | text |  | Sets how entity data is synchronized with the database. Valid choices are CommitOptionA and CommitOptionBC Default value(s): CommitOptionBC | true
insert | text |  | Determines when a new entity is inserted into the database. Valid choices are AfterCreate, AfterPostCreate, and AtTransactionCompletion Default value(s): AtTransactionCompletion | true
delete | text |  | Determines when an entity is deleted from the database. Valid choices are AtRemove and AtTransactionCompletion Default value(s): AtTransactionCompletion | true
locking-strategy | text |  | Sets the locking strategy for concurrent entity access. Valid choices are None, Pessimistic, Counter, Timestamp, or FieldComparison Default value(s): FieldComparison | true
lock-col-name | text |  | Sets the database column name for the implementation of the locking strategies Counter and Timestamp | true
lock-col-sql-type | text |  | Sets the database column type for the implementation of the locking strategies Counter and Timestamp | true
data-expires | text |  | Specifies a time-out value for CommitOptionA and ReadOnly caches. The default is no expiration. | true

### @mvcsoft.fault-group (0..1)

Configures fault groups, which are named groups of fields that are loaded as a unit for an EJB-QL query or "on-demand." For example: @mvcsoft:fault-group name="sample_fault_group" fields="id,date,product,value" It is possible to have fault groups that extend to related information. You can specify an unlimited number of semi-colon-separated "nested" fault groups by navigating through the cmr fields. An example of this for a fault group that includes information from related customer, order, and line item beans is: @mvcsoft:fault-group name="custgroup" fields="custName" nested="orders:shipAddress,billAddress;orders.lineItems:prodId,quantity,price" You can load nested fault groups without any related fields. Just the ids will be retrieved by the MVCSoft runtime. This is valuable in several situations, for example where the related data already exists in the cache. You are still required to use the syntax with the colon, but you are not required to list fields. For example: @mvcsoft:fault-group name="custgroup" fields="custName" nested="orders:;orders.lineItems:"

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
name | text |  | The name of the fault group | true
fields | text |  | A comma-separated list of fields in the entity that are members of the named fault group | true
nested | text |  | A semi-colon-separated list of related fields in the form cmr1.cmr2.cmr3:field1,field2,field3 | true

### @mvcsoft.high-low-key (0..1)

Configures the MVCSoft Persistence Manager to automatically and efficiently provide a sequence value for a specified primary key field. (This strategy is also known as "sequence blocks.") This strategy requires a database table to hold the value for the next block of sequence numbers. See the MVCSoft documentation for more information

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
key-field | text |  | The name of the primary key field that should be configured with a sequence value when the entity is created, or the special string "Unknown Key" for the case of an unknown primary key | true
sequence-name | text |  | The name that identifies a particular sequence. (Sequences may be reused across entity bean types if desired.) | true
non-transactional-pool-name | text |  | The JNDI name of a DataSource that will provide a Connection that does not participate in the current transaction | true
chunk-size | text |  | The number of sequences that are retrieved in a single database access. Setting this to a high value reduces database i/o (at the negligible cost of potentially "wasted" sequence numbers). | true
retry-count | int |  | Sequence numbers are retrieved using optimistic concurrency. This value determines the number of retries in case of an optimistic rollback | true
table-name | int |  | The name of the database table in which sequence values are stored | true
sequence-name-column | text |  | The column name for the column that holds the "sequence name" information | true
sequence-name-sql-type | text |  | The sql type for the column that holds the "sequence name" information | true
value-column | text |  | The column name for the column that holds the last used sequence number | true
value-sql-type | text |  | The sql type for the column that holds the last used sequence number | true

### @mvcsoft.query (0..1)

Configures finder and ejbSelect methods for: (1) the fields that should be "eagerly loaded" within the transaction; (2) whether or not the transaction data should be flushed before executing; and (3) the sort order of the returned results.

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
name | text |  | The name of the finder or ejbSelect method | true
fault-group | text |  | The name of the fault group that indicates which fields should be loaded when the query is executed | true
should-flush | text |  | The EJB 2.0 specification mandates that changes within a transaction be visible to queries issued within that transaction. The MVCSoft Persistence Manager meets this requirement by flushing all pending changes to the database before issuing the query. It may be that the results of a particular query will never depend on these changes, in which case you can set should-flush to false Default value(s): true | true
sort-order | text |  | A comma-separated list of fields in the entity by which to sort the query. Optionally, asc or desc may be specified after the field name to indicate the direction of the sort. There cannot be any spaces between fields on which to sort. In other words, sort-order="id, value desc" will not work, but sort-order="id,value desc" will | true
lightweight | bool |  | Whether or not the returned interfaces from an ejbSelect query are "lightweight interfaces" that bypass the J2EE stack. Note that finder methods cannot be configured to return lightweight values. Default value(s): false | false

### @mvcsoft.unknown-key (0..1)

Configures the MVCSoft Persistence Manager for the case of the unknown primary key. You must also specify a uuid-key configuration or a high-low-key configuration to provide a value for the unknown primary key at runtime

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
java-type | text |  | The Java class that will be used to represent the unknown primary key at runtime. This should be compatible with the UUID or high-low strategy you choose for generating the value of this key | true
col-name | text |  | The column name of the key in the entity database table | true
jdbc-type | text |  | The JDBC type of the unknown key. This should be a constant from the java.sql.Types class | true
sql-type | text |  | The sql type for the columnof the key in the entity database table | true

### @mvcsoft.uuid-key (0..1)

Configures the MVCSoft Persistence Manager to provide a "universally unique identifier" value (of type String or BigInteger) for a specified primary key field. The components of this UUID are specified by indicating the source of a value (e.g. counter, ip address, class hash code) and the number of bytes for that value. See the MVCSoft documentation for more information

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
key-field | text |  | The name of the primary key field that should be configured with a UUID value when the entity is created, or the special string "Unknown Key" for the case of an unknown primary key | true
field-type | text |  | The type of UUID created. Valid values are String and BigInteger | true
timestamp | int |  | The number of bytes from a timestamp that should be included in the UUID | true
ipaddress | int |  | The number of bytes from the IP address that should be included in the UUID | true
classhash | int |  | The number of bytes from a hash of the container class that should be included in the UUID | true
classstarttime | int |  | The number of bytes from the container start time that should be included in the UUID | true
counter | int |  | The number of bytes from a counter that should be included in the UUID | true

## @MVCSoft Method Level Tag Usage

### @mvcsoft.col-name (0..1)

The column name for the field in the table where this bean will be persisted

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
type | text |  | Define the name of the column for the field | true

### @mvcsoft.exclude-from-optimistic-lock (0..1)

Indicates that the field should not be used in field-based comparisons for optimistic locking

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
value | bool |  | Default value(s): false | true

### @mvcsoft.jdbc-type (0..1)

The JDBC type for the column where this field will be persisted. See the javadoc for "java.sql.Types" for a list of valid types

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
type | text |  | The jdbc type of the field. Example VARCHAR | true

### @mvcsoft.lightweight (0..1)

Indicates that a cmr field should return lightweight local interfaces.

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
value | bool |  | Default value(s): false | true

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

Configures the persistent storage of an EJB 2.0 relationship specified by the @ejb:relation tag. There are two basic mechanisms for persistent storage of relationships: a relationship table, which can be used for any relationship cardinality (and must be used with many-many relationships); and foreign keys in the entity table, which can be used for one-one, one-many, and many-one relationships. An example of configuring a relationship using foreign keys is: @mvcsoft.relation map-style="foreign-key" role-with-key="ChildrenForParent" key-aliases="id=parentid, id2=parentid2,id3=parentid3" relationship-in-pk="true". An example of configuring a relationship using a relationship table is: @mvcsoft.relation map-style="table" table-name="TestRelationship" key-aliases="ParentHasChildren:id=parentid,id2=parentid2,id3=parentid3;ChildrenInParent:id=childid,id2=childid2,id3=childid3"

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
map-style | text |  | Valid values are foreign-key or table | true
role-with-key | text |  | For foreign-key mapped relationships only. Indicates the "side" of the relationship where the foreign keys are located. The source entity of that role will have those keys in its table. (In a one-one relationship, either role can be chosen. In a one-many relationship, the entity in the "many" role, e.g. OrderInLineItem, must have the keys.) | true
key-aliases | text |  | Specifies the names of the database columns that persistently store a relationship. These names are mapped to entity primary key fields by a simple comma-separated list in the format key=alias,key=alias. For a table-mapped relationship, both participants can have aliases, so the format is role1:key=alias,key=alias;role2:key=alias,key=alias. | true
relationship-in-pk | text |  | For foreign-key mapped relationships only. Indicates that the foreign keys for the relationship are also components of the primary key for the entity | true

### @mvcsoft.sql-type (0..1)

The SQL type for the column where this field will be persisted

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
type | text |  | Define the name of the sql type for the field. Example varchar(10) | true

### @mvcsoft.wrap (0..1)

Indicates that the method is a wrapper for a query. (Wrapper methods allow the bean developer to efficiently retrieve subsets of query results.) Example: @mvcsoft.wrap query-name="findAll"

Applies to: EntityBeans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
query-name | text |  | Define the name of the associated finder or ejbSelect query | true

## @MVCSoft Field Level Tag Usage