31.12. Defaults

JBoss global defaults are defined in the standardjbosscmp-jdbc.xml file of the server/<server-name>/conf/ directory. Each application can override the global defaults in the jbosscmp-jdbc.xml file. The default options are contained in a defaults element of the configuration file, and the content model is shown below.
The jbosscmp-jdbc.xml defaults content model

Figure 31.16. The jbosscmp-jdbc.xml defaults content model

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>

31.12.1. A sample jbosscmp-jdbc.xml defaults declaration

Each option can apply to entities, relationships, or both, and can be overridden in the specific entity or relationship. A detailed description of each option follows:
  • datasource: This optional element is the jndi-name 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, as 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 Section 31.13.3, “Mapping”.
  • create-table: This optional element when true, specifies that JBoss should attempt to create a table for the entity. When the application is deployed, JBoss checks if 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, alter-table can be used to keep the schema current with changes to the entity bean. Alter table will perform the following specific tasks:
    • new fields will be created
    • fields which are no longer used will be removed
    • string fields which are shorter than the declared length will have their length increased to the declared length. (not supported by all databases)
  • remove-table: This optional element when true, JBoss will attempt to drop the table for each entity and each relation table mapped relationship. When the application is undeployed, JBoss will attempt 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: This optional element when true specifies that the bean provider will not be allowed to change the value of any fields. A field that is read-only will not be stored in, or inserted into, the database. If a primary key field is read-only, the create method will throw 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 update. The read-only option can be overridden 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. This option can also be overridden on a per CMP field basis. If read-only is false, this value is ignored. The default is -1.
  • row-locking: This optional element if true specifies that JBoss will lock all rows 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: This optional element if true specifies that JBoss will add 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 in Section 31.7.3, “Read-ahead”.
  • list-cache-max: This optional element specifies the number of read-lists that can be tracked by this entity. This option is discussed in Section 31.7.3.2, “on-load”. 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 one to define the default mapping of an unknown primary key type of java.lang.Object maps to the persistent store.
  • entity-command: This optional element allows one to define the default command for entity creation. This is described in detail in Section 31.11, “Entity Commands and Primary Key Generation”.
  • ql-compiler: This optional elements allows a replacement query compiler to be specified. Alternate query compilers were discussed in Section 31.6.7, “EJBQL 2.1 and SQL92 queries”.
  • throw-runtime-exceptions: This attribute, if set to true, indicates that an error in connecting to the database should be seen in the application as runtime EJBException rather than as a checked exception.