31.4.2. CMP Field Column Mapping

The relational mapping configuration of a CMP field is done in the jbosscmp-jdbc.xml file. The structure is similar to the ejb-jar.xml with an entity element that has cmp-field elements under it with the additional configuration details.
The following is shows the basic column name and data type mappings for the gangster bean. 
<jbosscmp-jdbc>
  <enterprise-beans>
    <entity>
      <ejb-name>GangsterEJB</ejb-name>
      <table-name>gangster</table-name>
                 
      <cmp-field>
        <field-name>gangsterId</field-name>
        <column-name>id</column-name>
      </cmp-field>
      <cmp-field>
        <field-name>name</field-name>
        <column-name>name</column-name>
        <not-null/>
      </cmp-field>
      <cmp-field>
        <field-name>nickName</field-name>
        <column-name>nick_name</column-name>
        <jdbc-type>VARCHAR</jdbc-type>
        <sql-type>VARCHAR(64)</sql-type>
      </cmp-field>
      <cmp-field>
        <field-name>badness</field-name>
        <column-name>badness</column-name>
      </cmp-field>
    </entity>
  </enterprise-beans>
            </jbosscmp-jdbc>
The full content model of the cmp-field element of the jbosscmp-jdbc.xml is shown below.
The JBoss entity element content model

Figure 31.4. The JBoss entity element content model

A detailed description of each element follows:
  • field-name: This required element is the name of the cmp-field that is being configured. It must match the field-name element of a cmp-field declared for this entity in the ejb-jar.xml file.
  • read-only: This declares that field in question is read-only. This field will not be written to the database by JBoss. Read-only fields are discussed in Section 31.4.3, “Read-only Fields”.
  • read-only-timeout: This is the time in milliseconds that a read-only field value will be considered valid.
  • column-name: This optional element is the name of the column to which the cmp-field is mapped. The default is to use the field-name value.
  • not-null: This optional element indicates that JBoss should add a NOT NULL to the end of the column declaration when automatically creating the table for this entity. The default for primary key fields and primitives is not null.
  • jdbc-type: This is the JDBC type that is used when setting parameters in a JDBC prepared statement or loading data from a JDBC result set. The valid types are defined in java.sql.Types. This is only required if sql-type is specified. The default JDBC type will be based on the database type in the datasourcemapping.
  • sql-type: This is the SQL type that is used in create table statements for this field. Valid SQL types are only limited by your database vendor. This is only required if jdbc-type is specified. The default SQL type will be base on the database type in the datasourcemapping
  • property: This optional element allows one to define how the properties of a dependent value class CMP field should be mapped to the persistent store. This is discussed further in Section 31.4.5, “Dependent Value Classes (DVCs)”.
  • auto-increment: The presence of this optional field indicates that it is automatically incremented by the database layer. This is used to map a field to a generated column as well as to an externally manipulated column.
  • dbindex: The presence of this optional field indicates that the server should create an index on the corresponding column in the database. The index name will be fieldname_index.
  • check-dirty-after-get: This value defaults to false for primitive types and the basic java.lang immutable wrappers (Integer, String, etc...). For potentially mutable objects, JBoss will mark they field as potentially dirty after a get operation. If the dirty check on an object is too expensive, you can optimize it away by setting check-dirty-after-get to false.
  • state-factory: This specifies class name of a state factory object which can perform dirty checking for this field. State factory classes must implement the CMPFieldStateFactory interface.