<jboss/> subtask

jboss

Creates JBoss-specific deployment descriptors (jboss.xml, jaws.xml and jbosscmp-jdbc.xml files) for EJB beans.

Parameters

Attribute Description Required
version The version of JBoss. Supported versions are 2.4 and 3.0. No, default is "2.4".
debug Debug flag for jaws.xml. No, default is "false"
xmlencoding The encoding of the ejb-jar.xml file. No, default is "UTF-8"
typemapping The type-mapping for JAWS. No, default is "Hypersonic SQL"
datasource The datasource for JAWS. No, default is "java:/DefaultDS"
destdir Destination directory for output JBoss-specific deployment descriptor files. No, default is destdir parameter of ejbdoclet task
mergedir Merge directory where ejbdoclet looks for files to be merged with generated files. No, required, if the merge feature used
validateXml Validates the generated xml files according to the DTD file contained inside xdoclet.jar. No, default is false

Merge Points

Merge File Name Description Required
jboss-resource-managers.xml The file where JBoss resource managers are defined. See resource-managers in jboss.xml. No
jboss-{0}.xml The file where per-bean settings are defined. {0}designates the EJB name. See elements under <enterprise-beans> in jboss.xml. No
jboss-beans.xml To add beans that you have deployment descriptor info for, add
a file to your XDoclet merge directory called session-beans.xml that contains
the <session></session>, <entity></entity> and <message-driven></message-driven>
markup for those beans.
No
jaws-db-settings-{0}.xml The file where per-bean JAWS database settings are defined. {0}designates the EJB name. See elements under <enterprise-beans> in jaws.xml. No
jaws-{0}.xml The file where per-bean JAWS CMP settings are defined. {0}designates the EJB name. See <cmp-field> in jaws.xml. No
jboss-security.xml The file where security domain setting is defined No
jboss-container.xml The file where container configurations are defined No
jbosscmp-jdbc-defaults.xml The file where JBossCMP defaults are defined No
jbosscmp-jdbc-db-setting-{0}.xml The file where per-bean JBossCMP database settings are defined No
jbosscmp-jdbc-{0}.xml The file where per-ben JBossCMP CMP settings are defined No
jbosscmp-jdbc-load-{0}.xml The file where per-bean JBossCMP load groups are defined No
jbosscmp-jdbc-dvc.xml The file where DVC classes are defined No
jbosscmp-jdbc-typemappings.xml The file where JBossCMP custom typemappings are defined No

Remember you should preserve the package directory structure in mergedir. If the bean is test.bank.AccountBean then jboss-Account.xml should be located at test/bank directory in mergedir.

Class level Tags

@jboss:container-configuration

The name of the container configuration to use for the bean. Applicable to all types of EJBs.

Parameter Usage
[name]: String Defines the container configuration for the bean.

[DEPRECATED in favour of @jboss:persistence] @jboss:read-only

Parameter Usage
[read-only]: "true" | "false" Declare the bean as read only.

@jboss:ejb-ref-jndi

Sets the JNDI name of a referenced bean. For example:

@jboss:ejb-ref-jndi Bar foo/Bar

There must be an @ejb:ejb-ref tag too which points to the referenced bean.

Parameter Usage
[ref-name]: String
Define the name of the bean reference.
[jndi-name]: String Define the jndi-name of the referenced bean.

@jboss:resource-ref

Sets multiple resource managers in jboss.xml. For example:

@jboss:resource-manager org.jboss.ejb.deployment.MailResource mail/EasyNetMail Mail
Parameter Usage
[res-ref-name]: String Define the resource reference name.
[resource-name]: String Define the name of the resource.

@jboss:resource-manager

Parameter Usage
[res-man-class]: String Define the class of the resource manager
[res-man-name]: String Define the name of the resource manager.
[res-man-jndi-name]: String Define the jndi name of the resource manager.

@jboss:persistence

The Jaws/Jboss CMP deployment descriptor specific entries.

Parameter Usage Mandatory
[datasource]: String JNDI name of the datasource to be used for this bean. No. If specified, datasource-mapping should also be specified.
[datasource-mapping]: String Typemapping for the datasource to be used for this bean. No. If specified, datasource should also be specified.
[create-table]: "true" | "false" Set to true if you want JBoss to create the entity table when the bean is deployed. No. Default is taken from container configuration (usually true).
[remove-table]: "true" | "false" Set to true if you want JBoss to remove the entity table when the bean is undeployed. No. Default is taken from container configuration (usually false).
[read-only]: "true" | "false" If true then the bean is read-only and no properties can be set. Avoid database calls. No. Default is taken from container configuration (usually false).
[time-out]: milisseconds Specify the amount of time that a read-only field is considered valid. No. Default is taken from container configuration (usually 300).
[row-locking]: "true" | "false" Set to true if you want JBossCMP to use SELECT ... FOR UPDATE queries. No. Default is taken from container configuration (usually false).
[tuned-updates]: "true" | "false" Set to true if you want JAWS to use tuned updates. No. Default is taken from container configuration (usually false).
[pk-constraint]: "true" | "false" Set to true if you want JBoss to create primary key constraints when creating the entity table. No. Default is taken from container configuration (usually true).
[list-cache-max]: integer Specifies the number of simultaneous queries that can be tracked by the cache for the entity. No. Default is taken from container configuration (usually 1000).

@jboss:read-ahead

JBossCMP read-ahead configuration

Parameter Usage Mandatory
strategy: on-load/on-find The strategy used to read-ahead data in queries. Yes
[page-size]: integer The number of entities that will be read in a single read-ahead load query. No. Default is taken from container configuration (usually 1000).
[eager-load-group]: string The name of the load-group that should be loaded on the read-ahead load queries. No. Default is taken from container configuration (usually *).

[DEPRECATED in favour of @ejb:persistence] @jboss:table-name

The table to be used by this bean is called table-name. Applicable to entity beans using JAWS for CMP.

Parameter Usage
[table-name]: String Define the name of the table for the bean.

[DEPRECATED in favour of @jboss:persistence] @jboss:create-table

Create the table if it doesn't exist. Applicable to entity beans using JAWS for CMP.
Parameter Usage
[create]: "true" | "false" Create the table if it does not already exist.

[DEPRECATED in favour of @jboss:persistence] @jboss:remove-table

Remove the table when the bean is undeployed. Applicable to entity beans using JAWS for CMP.
Parameter Usage
[remove]: "true" | "false" Create the table if it does not already exist.

[DEPRECATED in favour of @jboss:persistence] @jboss:pk-constraint

Create a primary constraint when creating the table
Parameter Usage
[pk-constraint]: "true" | "false" Creates a pk constraint when creating the table.

[DEPRECATED in favour of @jboss:persistence] @jboss:tuned-updates

Use tuned updates (i.e. minimize data stored on ejbStore). Applicable to entity beans using JAWS for CMP.

Parameter Usage
[tune]: "true" | "false" Apply tuned updates.

[DEPRECATED in favour of @jboss:persistence] @jboss:time-out

Time out for read-only beans. The state of the bean will be reloaded from the database after the time out. Applicable to entity beans using JAWS for CMP.

Parameter Usage
[time-out]: integer (in seconds) Define the time out interval for transactions.

@jboss:finder-query

Assign custom query to finder named "findFoo". An @ejb:finder tag for the named finder must also be present. Example:

@jboss:finder-query name="findFoo" query="foo = {1}" order="foo,bar"

Applicable to Entity beans using JAWS CMP.

Parameter Usage
[name]:String The name of the finder.
[query]:String The query for the finder. See JAWS documentation for finder query syntax.
[order]:String The order for the finder results.
[read-ahead]:(true|false) Optional, if provided, should be true or false to indicate if the query should have read-ahead.

@jboss:query

Assign a JBoss-QL or Dynamic-QL element to a finder.

Parameter Usage
signature: String The method signature for this finder. Must match the signature in ejb-jar.xml (genereted using @ejb:finder).
[query]: String Specify the JBoss-QL for this finder. JBoss-QL is an extension to EJB-QL.
[dynamic-ql]: String Mark this finder as a method that takes a Dynamic-QL argument. More info on the JBossCMP documentation.
[result-type-mapping]: "Local" | "Remote" The result type for a collection-valued finder.

@jboss:declared-sql

Declares the SQL for a finder.

Parameter Usage
signature: String The method signature for this finder. Must match the signature in ejb-jar.xml (genereted using @ejb:finder).
[where]: String The WHERE clause for the declared SQL.
[order]: String The ORDER BY clause for the declared SQL.
[other]: String Any aditional words for the declared SQL.
[result-type-mapping]: "Local" | "Remote" The result type for a collection-valued finder.

@jboss:cmp-field

Will define a <cmp-field> element for a field of a cmp-field of ejb-jar.xml. This is used for dependant objects fields mapping, see @jboss:not-persisted-field. Example:

@jboss:cmp-field field-name="sitePk.pk" column-name="site"

Applicable to EJBs using JAWS CMP.

Parameter Usage
[field-name]: String The name of the field
[column-name]: String The name of the column.

@jboss:destination-jndi-name

Defines JNDI name of the Queue/Topic used my the MDB. Applicable to MDB. Example:

@jboss:destination-jndi-name name="queue/testQueue"
Parameter Usage
[name]: String The name of the destination.

@jboss:dvc

JBossCMP Dependent Value Class configuration. Just put this tag on a class if you want to generate o section for this class. Also, you need to tag each property you want persisted with @jboss:dvc-property.

Method level Tags

[DEPRECATED in favour of @ejb:persistence] @jboss:column-name

The column name for the CMP field in the table where this bean will be persisted. Applicable to Entity EJBs using JAWS CMP.

Parameter Usage
[name]: String Define the name of the column for the field.

[DEPRECATED in favour of @ejb:persistence] @jboss:sql-type

The SQL type for the column where this CMP field will be persisted. See your database's documentation for a list of valid types. Example:

@jboss:sql-type VARCHAR(10)
Parameter Usage
[type]: String Define the name of the sql type for the field.

[DEPRECATED in favour of @ejb:persistence] @jboss:jdbc-type

The JDBC type for the column where this CMP field will be persisted. See the javadoc for "java.sql.Types" for a list of valid types. Applicable to Entity beans using CMP through JAWS.
Parameter Usage
type: String The jdbc type of the field.

@jboss:not-persisted-field

Means the field does not have to be stored in the database. It will appear in ejb-jar.xml but not in jaws.xml. Used for a dependant object that is not mapped as Object to the database, but instead exploded by its attributes. See @jboss:cmp-field. Applicable to Entity beans using JAWS CMP. This tag has no parameters.

@jboss:relation-mapping

Used to choose the relation mapping style for a relationship. It can be safely omitted and must be used only when you want a mapping style that is different from the default (foreign-key for 1-1 and 1-n relations, relation-table for n-m relations).

Parameter Usage
style: (foreign-key | relation-table) The mapping style for this relationship.

@jboss:relation

Used to customize the relationships via jbosscmp-jdbc.xml for JBoss 3.0. NOTE: If you replace jboss:relation with jboss:target-relation, you can modify the blind side of a unidirectional relationship (someone fix this wording)

Also please note that the @jboss:relation semantics and the generated <key-fields> generated element are somewhat reversed. You use @jboss:relation tag on the relation side that has the foreign key, but the <key-fields> element is genereted on the relation side that holds the primary key. This behavior is correct. Take a look at the samples so you can understand better what this means.

Parameter Usage
fk-constraint: (true|false*) Flag to indicate if a foreign key constraint should be placed on the relation column.
related-pk-field: (String) Name of the pk field of the 1- end of the relationship that this foreign key constraint applies to. Required for support of complex primary keys in the 1- end of the relation. (Corresponds to field-name in jbosscmp-jdbc.xml)
fk-column: (String) Name of the column that should be used for foreign key mapping. (Corresponds to column-name in jbosscmp-jdbc.xml)

@jboss:relation-table

Used to configure the table used in relation table mapped relationships.

Parameter Usage
table-name: String The name of the table used for this relationship.
[create-table]: (true | false) Set to true if you want JBossCMP to create the relation table at deployment time.
[remove-table]: (true | false) Set to true if you want JBossCMP to remove the relation table at undeployment time.
[pk-constraint]: (true | false) Set to true if you want JBossCMP to create a primary key constraint on the relation table.

@jboss:dvc-property

This tag has two possible uses. The first is on the DVC class to declare which properties should be used as DVC fields and the second is on a CMR field to specify how to map DVC properties to database columns. On a DVC property, this tag doesn't need any parameters. On a CMR field you need to indicate at least property-name and can also define the column-name, jdbc-type and sql-type. Please not that jdbc-type and sql-type should both on none be specified.

Parameter Usage
property-name: String The name of the DVC property being configured.
[column-name]: String The database column where te persist this property.
[jdbc-type]: String The JDBC type for this property.
[sql-type]: String The SQL type for this property.