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

## @oc4j Tag Reference

Oracle Application Server (OC4J) specific tags for EJB.

Applies to: all EJB types

### @oc4j Class Level Tags

@oc4j.bean

### @oc4j Method Level Tags

@oc4j.field-persistence-manager
@oc4j.field-persistence-manager-property
@oc4j.persistence

### @oc4j Field Level Tags

## @oc4j Class Level Tag Usage

### @oc4j.bean (0..1)

All attributes of session-deployment, entity-deployment and message-driven-deployment are placed under this class level tag.

Applies to: All EJB types, class level

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
jndi-name | text | Applicable to session and entity beans | This parameter specifies the JNDI name to be used for lookup. It uses the 'ejb-name' by default. | false
pool-cache-timeout | int | Applicable to session (stateless) and entity beans | This parameter specifies how long (in seconds) to keep beans cached in the pool. For stateless session beans, if you specify a pool-cache-timeout, then at every pool-cache-timeout interval, all beans in the pool, of the corresponding bean type, are removed. If the value specified is zero or negative, then the pool-cache-timeout is disabled and beans are not removed from the pool. Default value(s): 60 | false
call-timeout | int | Applicable to session and entity beans. | This parameter specifies the maximum time (in milli seconds) to wait for any resource to make a business/life-cycle method invocation. This is not a timeout for how long a business method invocation can take. If the timeout is reached, a TimedOutException is thrown. This excludes database connections. Set to 0 if you want the timeout to be forever. Default value(s): 90000 | false
copy-by-value | bool | Applicable to session and entity beans | Whether or not to copy (clone) all the incoming/outgoing parameters in EJB calls. Set this to 'false' if you're certain your application doesn't assume copy-by-value semantics for a speed-up. The default is 'true'. Default value(s): true | false
max-instances | int | Applicable to session (stateless) and entity beans | The number of maximum bean implementation instances to be kept instantiated or pooled. The default is 100. This setting is valid for session beans (stateless) and entity beans only. Default value(s): 100 | false
min-instances | int | Applicable to session (stateless) and entity beans | The number of minimum bean implementation instances to be kept instantiated or pooled. The default is 0. This setting is valid for session (stateless) and entity beans only. Default value(s): 0 | false
max-instances-per-pk | int | Applicable to entity beans | Sets the maximum entity bean wrapper instances allowed in its pool for a given primary key. Default value(s): 50 | false
min-instances-per-pk | int | Applicable to entity beans | Sets the minimum entity bean wrapper instances allowed in its pool for a given primary key. Default value(s): 0 | false
max-tx-retries | int | Applicable to session and entity beans | The number of times to retry a transaction that was rolled back due to system-level failures. The default is 3. Default value(s): 3 | false
persistence-filename | text | Applicable to session beans | Path to file where sessions are stored across restarts. | false
timeout | int | applicable to session beans | Inactivity timeout in seconds. If the value is zero or negative timeouts will be disabled. Default value(s): 0 | false
clustering-schema | text | Applicable to entity beans. | This parameter should be set to "asynchronous-cache" in order to cluster-enable an Entity bean. Valid options are: default asynchronous-cache Default value(s): default | true
data-source | text | Applicable to entity beans. | The name of the data-source used if using container-managed persistence. Use the 'ejb-location' attribute of the data-source entry. Default value(s): jdbc/OracleDS | true
exclusive-write-access | bool | Applicable to entity beans. | Whether or not the EJB-server has exclusive write (update) access to the database backend. This can be used only for entity beans that use a "read_only" locking mode. In this case, it increases the performance for common bean operations and enables better caching. Default is false for beans with locking-mode=optimistic or pessimistic and true for locking-mode=read-only. Default value(s): Default is false for beans with locking-mode=optimistic or pessimistic and true for locking-mode=read-only. | false
instance-cache-timeout | int | Applicable to entity beans. | The amount of time in seconds that entity wrapper instances are assigned to an identity. If you specify 'never', you retain the wrapper instances until they are garbage collected. The default is 60 seconds. Default value(s): 60 | false
isolation | text | Applicable to entity beans. | Specifies the isolation-level for database actions. The valid values for Oracle databases are 'serializable' and 'committed'. The default is 'committed'. Non-Oracle databases can be the following: 'none', 'committed', 'serializable', 'uncommitted', and 'repeatable_reads'. Default value(s): committed Valid options are: none committed serializable uncommitted repeatable_reads Default value(s): committed | false
table | text | Applicable to entity beans. | The name of the table in the database if using container-managed persistence. Applicable to entity beans. | false
validity-timeout | int | Applicable to entity beans. | The maximum amount of time (in millis) that an entity is valid in the cache (before being reloaded). Useful for loosely coupled environments where rare updates from legacy systems occur. This attribute is only valid when exclusive-write-access="true" (the default). Applicable to entity beans. | false
instance-cache-timeout | int | Applicable to entity beans. | The amount of time in seconds that entity wrapper instances are assigned to an identity. If you specify 'never', you retain the wrapper instances until they are garbage collected. The default is 60 seconds. Default value(s): 60 | false
do-select-before-insert | bool | Applicable to entity beans. | Recommend setting to false to avoid the extra select before insert which checks if the entity already exists before doing the insert. This will then detect a duplicate, if there is one, during the insert. Default Value: true Default value(s): true | false
locking-mode | text | Applicable to entity beans. | Configures the handling of resource contention and parallel execution within CMP entity beans. PESSIMISTIC uses "select for update" to manage resource contention and only allows one user at a time to execute the entity bean. OPTIMISTIC allows multiple users to execute the entity bean in parallel. It does not monitor resource contention; thus, the burden of the data consistency is placed on the database isolation modes. READ-ONLY allows multiple users to execute the entity bean in parallel. The container does not allow any updates to the bean's state. OLD_PESSIMISTIC is maintained for backward compatibility with OC4J 1.0.2.2 and for use with non-Oracle databases. Valid options are: pessimistic optimistic read-only old_pessimistic Default value(s): optimistic | false
update-changed-fields-only | bool | Applicable to entity beans. | Specifies whether the container updates only modified fields or all fields to persistence storage for CMP entity beans when ejbStore is invoked. The default is true, which specifies to only update modified fields. Default value(s): true | false
disable-wrapper-cache | bool | Applicable to entity beans. | If true, a pool of wrapper instances is not maintained. The default is true. Default value(s): true | false
delay-updates-until-commit | bool | Applicable to entity (CMP) beans. | This attribute is valid only for CMP entity beans. Defers the flushing of transactional data until commit time or not. The default is true. Set this value to false to update persistence data after completion of every EJB method invocation - except ejbRemove() and the finder methods. Default value(s): false | false
connection-factory-location | text | Applicable to message driven beans. | The JMS Destination Connection Factory is specified in the connection-factory-location attribute. The syntax for database queue/topic is "java:comp/resource" + resource provider name + "TopicConnectionFactories" or "QueueConnectionFactories" + user defined name. The xxxConnectionFactories details what type of factory is being defined. | true
destination-location | text | Applicable to message driven beans. | The JNDI location of the destination (queue/topic) to use. The JMS Destination is specified in the destination-location attribute. The syntax for database queue/topic is "java:comp/resource" + resource provider name + "Topics" or "Queues" + Destination name. The Topic or Queue details what type of Destination is being defined. The Destination name is the actual queue or topic name defined in the database. | true
subscription-name | text | Applicable to message driven beans. | If this is a topic, the subscription name is defined in the subscription-name attribute. | false
listener-threads | int | Applicable to message driven beans. | The listener threads are used to concurrently consume JMS messages. The default is one thread. Default value(s): 1 | false
transaction-timeout | int | Applicable to message driven beans. | This attribute controls the transaction timeout interval for any container-managed transactional MDB. The default is one day. If the transaction has not completed in this timeframe, the transaction is rolled back. Default value(s): 1 | false

## @oc4j Method Level Tag Usage

### @oc4j.field-persistence-manager (0..*)

If @oc4j.persistence field-persistence-manager specified and there's some properties for the persistence manager, specify it as one or more @oc4j.field-persistence-manager-property tags for the persistent field.

Applies to: Method level, entity beans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
class | text |  | The class that implements a custom persistence handler for this CMP-field. | false

### @oc4j.field-persistence-manager-property (0..*)

Specify properties for field-persistence-manager. Must have a @oc4j.field-persistence-manager "class" param set.

Applies to: Method level, entity beans

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
name | text |  | The name of the property. | false
value | text |  | The value of the property. | false

### @oc4j.persistence (0..*)

Use these tags to specify persistence details for Container Managed Entity Beans.

Applies to: Applicable to entity (CMP) beans.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
persistence-name | text |  | The name of the field in the database table. | false
persistence-type | text |  | The database type (valid values varies from database to database) of the field. | false
table-name | text |  | The database table name for this field | false
immutable | bool |  | Whether or not the value can be trusted to be immutable once added to the Collection/Map. Setting this to true will optimize database operations extensively. The default value is "true" for set-mapping and map-mappings and "false" for collection-mapping and list-mapping. | false

## @oc4j Field Level Tag Usage