JBoss Global Defaults

An example of the defaults section follows:

<jbosscmp-jdbc>
    <defaults>
        <datasource>java:/DefaultDS</datasource>
        <datasource-mapping>Hypersonic SQL</datasource-mapping>
        <create-table>true</create-table>
        <remove-table>false</remove-table>
        <read-only>false</read-only>
        <read-time-out>300000</read-time-out>
        <pk-constraint>true</pk-constraint>
        <fk-constraint>false</fk-constraint>
        <row-locking>false</row-locking>
        <preferred-relation-mapping>foreign-key</preferred-relation-mapping>
        <read-ahead>
            <strategy>on-load</strategy>
            <page-size>1000</page-size>
            <eager-load-group>*</eager-load-group>
        </read-ahead>
        <list-cache-max>1000</list-cache-max>
    </defaults>
</jbosscmp-jdbc>

A Sample jbosscmp-jdbc.xml Defaults Declaration

Each of the following jbosscmp-jdbc.xml options can apply to entities, relationships, or both, and can be overridden in the specific entity or relationship:

• datasource This optional element is the jndi-name that is used to look up the datasource. All database connections used by an entity or relation-table are obtained from the datasource. Having different datasources for entities is not recommended because it vastly constrains the domain over which finders and ejbSelects can query.

• datasource-mapping This optional element specifies the name of the type-mapping, which determines how Java types are mapped to SQL types and how EJB-QL functions are mapped to database-specific functions. Type mappings are discussed in the section "Mapping," later in this chapter.

• create-table When this optional element is TRue, JBoss attempts to create a table for the entity. When the application is deployed, JBoss checks whether a table already exists before creating the table. If a table is found, it is logged, and the table is not created. This option is very useful during the early stages of development, when the table structure changes often. The default is false.

• alter-table If create-table is used to automatically create the schema, you can use alter-table to keep the schema current with changes to the entity bean. This element performs the following specific tasks:

  It creates new fields.

  It removes fields that are no longer used.

  It increases the length of string fields that are shorter than the declared length to the declared length. (This is not supported by all databases.)

• remove-table When this optional element is TRue, JBoss attempts to drop the table for each entity and each relation table mapped relationship. When the application is undeployed, JBoss attempts to drop the table. This option is very useful during the early stages of development, when the table structure changes often. The default is false.

• read-only When this optional element is TRue, the bean provider is not allowed to change the values of any fields. A field that is read-only is not stored in or inserted into the database. If a primary key field is read-only, the create method throws a CreateException. If a set accessor is called on a read-only field, it throws an EJBException. Read-only fields are useful for fields that are filled in by database triggers, such as last updates. You can override the read-only option on a per-field basis. The default is false.

• read-time-out This optional element is the amount of time, in milliseconds, that a read on a read-only field is valid. A value of 0 means that the value is always reloaded at the start of a transaction, and a value of -1 means that the value never times out. You can override this option on a per-CMP-field basis. If read-only is false, this value is ignored. The default is -1.

• row-locking If this optional element is true, JBoss locks all rows that are loaded in a transaction. Most databases implement this by using the SELECT FOR UPDATE syntax when loading the entity, but the actual syntax is determined by the row-locking-template in the datasource-mapping used by this entity. The default is false.

• pk-constraint If this optional element is true, JBoss adds a primary key constraint when creating tables. The default is true.

• preferred-relation-mapping This optional element specifies the preferred mapping style for relationships. The preferred-relation-mapping element must be either foreign-key or relation-table.

• read-ahead This optional element controls caching of query results and CMR fields for the entity. This option is discussed earlier in this chapter, in the section "Read-ahead."

• list-cache-max This optional element specifies the number of read-lists that this entity can track. This option is discussed earlier in this chapter, in the section "The on-load Strategy." The default is 1000.

• clean-read-ahead-on-load When an entity is loaded from the read-ahead cache, JBoss can remove the data used from the read-ahead cache. The default is false.

• fetch-size This optional element specifies the number of entities to read in one round-trip to the underlying datastore. The default is 0.

• unknown-pk This optional element allows you to define the default mapping of an unknown primary key type of java.lang.Object to the persistent store.

• entity-command This optional element allows you to define the default command for entity creation. This is described in detail earlier in this chapter, in the section "Entity Commands and Primary Key Generation."

• ql-compiler This optional elements allows a replacement query compiler to be specified. Alternate query compilers are discussed earlier in this chapter, in the section "EJB-QL 2.1 and SQL92 Queries."