How to configure and use xdoclet for JOnAS

This guide contains the following sections:

Downloading and installing xdoclet

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

This ZIP file contains:

How to use this archive:

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

Method-Level Tags

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