# How to configure and use xdoclet for JOnAS

This guide contains the following sections:

- Downloading and installing xdoclet
- Ejbdoclet Ant target
- Xdoclet tags for JOnAS

## Downloading and installing xdoclet

You can find Xdoclet for JOnAS on ObjectWeb SourceForge / Tools / xdoclet / xdocletForJOnAS42.zip

This ZIP file contains:

- `test`: A folder that contains tests for JOnAS tags. You can use this as an example for your applications.
- `objectweb-tags.html`: Tags for the creation of JOnAS-specific resources (for use with xdoclet-objectweb-module-1.2.2.jar).
- `xdoclet-objectweb-module-1.2.2.jar`: Updated ObjectWeb libraries for xdoclet.
- `Readme.txt`: This readme file.

### How to use this archive:

- Download xdoclet from: http://xdoclet.sourceforge.net/install.html
- Install xdoclet and replace your local xdoclet-objectweb-module-1.2.2.jar file with this new version of that file.

Note: JOnAS examples (xdoclet and olstore) use the `$JONAS_ROOT/lib/example/xdoclet/xdoclet-objectweb-module-1.2.2.jar`.

## Ejbdoclet Ant target

The following ejbdoclet Ant target illustrates how to launch an xdoclet task to generate a deployment descriptor for JOnAS. The `defaultentityjndiname` is not mandatory, but you can use it if you do not want to specify the `@bean.jndi-name` for your Entity beans.

    <target name="ejbdoclet" >
        <taskdef
           name="ejbdoclet"
           classname="xdoclet.modules.ejb.EjbDocletTask"
           classpathref="project.class.path"
        />

        <ejbdoclet
           destdir="${build.generate.dir}"
           excludedtags="@version,@author"
           addedtags="@xdoclet-generated at ${TODAY}"
           ejbspec="2.0"
           verbose="true"
        >
          ...
           <jonas version="4.2"
               validateXML="true"
               destdir="${build.generate.dir}"
               defaultentityjndiname="jdbc_1"
           />
        </ejbdoclet>
    </target>

## Xdoclet tags

Field-Level Tags

- @jonas.bean
- @jonas.resource
- @jonas.resource-env
- @jonas.ejb-ref
- @jonas.session-timeout
- @jonas.is-modified-method-name
- @jonas.shared
- @jonas.passivation
- @jonas.max-cache-size
- @jonas.min-pool-size
- @jonas.jdbc-mapping
- @jonas.jonas-message-driven-destination

Method-Level Tags

- @jonas.ejb-relation
- @jonas.field-mapping
- @jonas.target-field-mapping
- @jonas.cmp-field-jdbc-mapping

### Field-Level Tags

#### jonas.bean

The jonas.bean element declares the JOnAS-specific information for an enterprise bean.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
ejb-name | text |  | The enterprise bean's name specified in the standard EJB deployment descriptor. | true
jndi-name | text |  | The JNDI name of the enterprise bean's home. Concerns only the Entity and Session beans. Mandatory if version < 2.5, but optional for Session beans for 2.5 onwards. | false
cleanup | text |  | Determines the jonas-specific behavior for table management at deploy time. | false
lock-policy | text |  | Determine the jonas-specific lock policy for database access. | false
automatic-pk-field-name | text |  | The jdbc column name for automatic primary key; auto-generated. | false
inactivity-timeout | text |  | Optional inactivity-timeout value (integer value) | false
prefetch | text |  | Optional prefetch (boolean value) | false

#### jonas.resource

The jonas.resource element declares the JOnAS-specific information for an external resource referenced by a bean.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
res-ref-name | text |  | The name of the resource reference specified in the standard EJB deployment descriptor. | true
jndi-name | text |  | The JNDI name of the resource. | true

#### jonas.resource-env

The jonas.resource-env element declares the JOnAS-specific information for an external resource environment referenced by a bean.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
resource-env-ref-name | text |  | The name of the resource environment reference specified in the standard EJB deployment descriptor. | true
jndi-name | text |  | The JNDI name of the resource environment. | true

#### jonas.ejb-ref

The jonas.ejb-ref element declares the JOnAS-specific information for a reference to another enterprise bean's home.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
ejb-ref-name | text |  | The name of the EJB reference specified in the standard EJB deployment descriptor. | true
jndi-name | text |  | The JNDI name of the ejb. | true

#### jonas.ejb-ref

The jonas.ejb-ref element specifies the value of timeout in seconds for expiration of session instances.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
session-timeout | int |  | The value of timeout in seconds for expiration of session instances. | true

#### jonas.is-modified-method-name

The jonas.is-modified-method-name element specifies the name of the is-modified method of an entity.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
is-modified-method-name | text |  | The name of the is-modified method of an entity. | true

#### jonas.shared

The jonas.shared element specifies whether the bean state can be accessed outside JOnAS. This tag was introduced in version 2.4.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
shared | bool |  | True if the bean state can be accessed outside JOnAS. The default is False. | true

#### jonas.passivation-timeout

The jonas.passivation-timeout element specifies the value of timeout in seconds for passivation of entity instances when no transaction are used.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
passivation-timeout | int |  | The value of timeout in seconds for passivation of entity instances when no transaction are used. | true

#### jonas.max-cache-size

The jonas.max-cache-size element defines the max number of instances (int value) that can be held in memory. The default value is infinite. This tag was introduced in version 2.4.

#### jonas.min-pool-size

The jonas.min-pool-size element specifies the number of instances that will be created to populate the pool when the bean is loaded for the first time. The default value is 0. This tag was introduced in version 2.4.

#### jonas.jdbc-mapping

The jonas.jdbc-mapping element declares the mapping of an entity with container-managed persistence to the underlying database.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
jndi-name | text |  | The JNDI name of the datasource. | true
automatic-pk | bool |  | True or False for use automatic generation of primary key. | false
jdbc-table-name | text |  | The name of the relational table. | true

#### jonas.finder-method-jdbc-mapping

The jonas.finder-method-jdbc-mapping element declares the SQL `WHERE` clause associated to a finder method of a container-managed persistence entity.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
method-name | text |  | The method's name. | true
method-params | text |  | Identifies a single method among multiple methods with an overloaded method name. | false
jdbc-where-clause | text |  | The SQL WHERE clause. | true

#### jonas.jonas-message-driven-destination

The jonas.jonas-message-driven-destination element declares the JOnAS-specific information for a the message-driven bean destination.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
jndi-name | text |  | The JNDI name of the message driven destination. | true

### Method Level tags

#### jonas.ejb-relation

The jonas.ejb-relation element declares the CMR fields Mapping to primary-key-fields to the underlying database.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
jdbc-table-name | text |  | The optional name of the relation joint table. | false

#### jonas.field-mapping

The jonas.field-mapping element represents a mapping from a foreign key column in the database table

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
foreign-key-jdbc-name | text |  | The column name of the foreign key of this field | true
key-jdbc-name | text |  | The column name of the primary key composite of this field. Use only if the pk is rename or composite | false

#### jonas.target-field-mapping

The jonas.target-field-mapping element was used for unidirectional relations. It specifies the column map for the target end of the relation. Since there is not a method in the other side of the relationship where the column mapping can be specified, it must be done on this side of the relationship, but with a reference to the other side.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
foreign-key-jdbc-name | text |  | The column name of the foreign key of this field | true
key-jdbc-name | text |  | The column name of the primary key composite of this field. Use only if your pk is rename or composite | false

#### jonas.cmp-field-jdbc-mapping

The jonas.cmp-field-jdbc-mapping element declares the mapping of a container-managed field of an entity to a column of a relational table.

Parameter | Type | Applicability | Description | Mandatory
--- | --- | --- | --- | ---
field-name | text |  | The field's name. | true
jdbc-field-name | text |  | The column name of the relational table. | true
sql-type | text |  | The sql-type element specifies the SQL type (CMP2 only) | false