@ejbgen:cmp-field Annotation

In a CMP entity bean, marks a virtual container-managed persistence (CMP) field.

Scope

Method tag for a CMP entity bean.

Syntax

@ejbgen:cmp-field

column="tableColumnName"

[column-type="OracleClob/OracleBlob"]

[exclude-from-value-object="True/False"]

[group-names="GroupName"]

[ordering-number="0...N"]

[primkey-field="True/False"]

[read-only-in-value-object="True/False"]

[table-name="TableName"]

Attributes

column

Required. Specifies the column in a database table to which this CMP field will be mapped.

column-type

Optional. Specify OracleClob or OracleBlob to map the CMP field to these database column types. When you use this field, you must declare the CMP field to either be a byte array or a class that implements the Serializable interface. If you want to serialize a byte array that is mapped to an OracleBlob, you must set the serialize-byte-array-to-oracle-blob attribute of the ejbgen:compatibility tag to true (default is false).

exclude-from-value-object

Optional. Specify true if you don't want this field to be included in the auto-generated value object (data transfer object) class. When left unspecified, this attribute defaults to false. For more information, see @ejbgen:file-generation Annotation.

group-names

Optional. This attribute defines how CMP fields of an entity bean are stored in memory. CMP fields and CMR fields that have the same group-name attribute specified are stored together. When this property is not used, all CMP fields and CMR fields are stored together in memory. Breaking up the memory signature into two or more groups can improve performance. For more details, see Accelerating Entity Bean Data Access.

ordering-number

Optional. Specify a number to enforce where this field will appear relative to other fields in signatures and constructors of generated compound primary key and value object (data transfer object) classes. In order for this ordering to work, all CMR and CMP fields must have this attribute set with a distinct numeric value. See the remark below.

primkey-field

Optional. Sets whether this field is the primary key field, or part of the compound primary key. The default is false.

read-only-in-value-object

Optional. Specify True if you want this field to be read-only in a generated value object class.

table-name

Optional. Specify the table(s) where this field should be mapped to. If the table-name is not specified, the CMP field is mapped to the table specified in the ejbgen:entity tag. You can also use this attribute to map primary key fields to multiple tables within the same database. For more information, see the example below.

Remarks

The following comments apply to this tag's use:

Various attributes (exclude-from-value-object, ordering-number, and read-only-in-value-object) affect value and primary key classes generated during the build process. These attributes do not affect explicit definitions of dependent value classes and/or method definitions in EJBs in the EJB Project folder.
For more information on the (disabling of) automatic creation of value objects, see @ejbgen:file-generation Annotation.
If you specify ordering-number to all CMP and CMP fields, it will only affect compound primary key and value object classes that are generated during the build process. For instance, if you define three primary key fields FieldA, FieldB, and FieldC, and need to enforce that the compound primary key class constructor uses these arguments in the given order, you can set the ordering-number of these attributes (to 1, 2, and 3). This will ensure this order, even if the ejbCreate method that returns the compound primary key object calls these arguments in a different order, for instance:
```
public my.customer.UntitledPK ejbCreate(int FieldC, java.lang.String FieldA, java.lang.String FieldB)
```
Also notice that the ordering-number attribute does not enforce the order of arguments in the methods in the ejb file itself or in any dependent value classes you have explicitly defined in your EJB project.

Multiple Table Mapping Example

The following example demonstrates the use of the table-name property. The MultipleTablesBean entity bean by default maps to the table OneTable as defined in the ejbgen:entity tag. The DefaultTable_field CMP field has no table-name property on its ejbgen:cmp-field tag and therefore maps to this table. The OtherTable_field CMP field has the table-name property set to OtherTable and therefore maps to the table OtherTable. The setMultipleTables_ID primary key field is set to both tables. Only primary keys can map to multiple tables:

/**
 * @ejbgen:entity prim-key-class="java.lang.Integer" 
 *   ejb-name="MT"
 *   data-source-name="cgSampleDataSource"
 *   table-name="OneTable"
 *   abstract-schema-name = "Divided"
 * ...
 */
public abstract class MultipleTablesBean extends GenericEntityBean implements EntityBean
{

    /**
     * @ejbgen:cmp-field column="DefaultTable_field"
     * @ejbgen:local-method
     */
    public abstract String getDefaultTable_field();

    /**
     * @ejbgen:local-method
     */
    public abstract void setDefaultTable_field(String arg);

    /**
     * @ejbgen:cmp-field table-name="OtherTable" column="OtherTable_field"
     * @ejbgen:local-method
     */
    public abstract String getOtherTable_field();

    /**
     * @ejbgen:local-method
     */
    public abstract void setOtherTable_field(String arg);

    /**
     * @ejbgen:cmp-field table-name="OneTable, OtherTable" primkey-field="true" column="Divided_ID, Divided_ID"
     * @ejbgen:local-method
     */
    public abstract Integer getMultipleTables_ID();

    /**
     * @ejbgen:local-method
     */
    public abstract void setMultipleTables_ID(Integer arg);



    public java.lang.Integer ejbCreate(java.lang.Integer MultipleTables_ID, java.lang.String OtherTable_field, java.lang.String DefaultTable_field)
    {
      setMultipleTables_ID(MultipleTables_ID);
      setOtherTable_field(OtherTable_field);
      setDefaultTable_field(DefaultTable_field);

      return null; // FIXME return PK value 
    }

    public void ejbPostCreate(java.lang.Integer MultipleTables_ID, java.lang.String OtherTable_field, java.lang.String DefaultTable_field)
    {
    }
}