Torque Schema Reference

The Torque Database Schema Reference attempts to explain what the different elements and attributes are when defining your own database schema. In addition I will attempt to explain which attributes mean what in the different databases that are currently supported.

Elements and their attributes

Some of the following examples are taken from the project-schema.xml document in the src/conf/torque/schema.

Element: database

The database element and its relevant attributes.

       

The database element has 8 attributes associated with it, they are:

nameThe name of the database being referenced
defaultIdMethodHow will the primary keys be created, defaults to "none"
defaultJavaTypeDefault type of columns in the database (object or primitive, defaults to primitive)
packageUsed for OM Peer generation
baseClassUsed for OM generation
basePeerUsed for OM Peer generation
defaultJavaNamingMethodIndicates how a schema table or column name is mapped to a Java class or method name respectively
heavyIndexingAdds extra indices for multi-part primary key columns. true or false, defaults to false. For databases like MySQL, values in a where clause must match key part order from the left to right. So, in the key definition PRIMARY KEY (FOO_ID, BAR_ID), FOO_ID must be the first element used in the where clause of the SQL query used against this table for the primary key index to be used. This feature could cause problems under MySQL with heavily indexed tables, by causing too many indices to be created, overrunning MySQL's table limit.

The database element can contain the following elements:

table1 or more

Attribute: defaultIdMethod

By defining this attribute at the database level it applies the defaultIdMethod to those tables which do not have an idMethod attribute defined. The attribute defaultIdMethod has 5 possible values, they are:

idbrokerThis allows Torque to generate the IDs through its IDBroker Service
nativeTorque will determine how the database will auto-generate IDs
autoincrementdeprecated, please use native
sequencedeprecated, please use native
noneTypically used if you do not want IDs generated

Attribute: defaultJavaNamingMethod

This attribute determines how table or column names, from the name attribute of the table or column element, are converted to a Java class or method name respectively when creating the OM Java objects. defaultJavaNamingMethod can contain 3 different values:

nochangeIndicates no change is performed.
underscoreUnderscores are removed, First letter is capitalized, first letter after an underscore is capitalized, the rest of the letters are converted to lowercase.
javanameSame as underscore, but no letters are converted to lowercase.

Attribute: package

The base package in which this database will generate the Object Models associated with it. This overrides the targetPackage property in the Torque build.properties file.

Attribute: baseClass

The base class to use when generating the Object Model. This class does not have to extend org.apache.torque.om.BaseObject.

Attribute: basePeer

The base peer to use when generating the Object Model Peers. Unlike baseClass, basePeer should extend BasePeer at some point in the chain, i.e. it needs to be the superclass.

Element: table

The table element and its relevant attributes

       

The table element has 13 attributes associated with it, they are:

nameThe name of the table being referenced
javaNameHow this table will be referenced in Java
idMethodHow will the primary keys be created, defaults to "null"
skipSqlWhether or not to skip SQL generation for this reference
abstractWhether or not to generate the class as Abstract or not
baseClassUsed for OM Peer generation
basePeerUsed for OM Peer generation
aliasThe table alias
interface?
javaNamingMethodSpecifies how the name attribute is converted to the Java class name of the corresponding OM object. This attribute overrides the defaultJavaNamingMethod attribute of the database element
heavyIndexing? (true or false)
descriptionUsed for doc generation

The table element can contain the following elements:

column1 or more
foreign-key0 or more
index0 or more
unique0 or more
id-method-parameter0 or more

Attribute: javaName

This is the Java class name to use when generating the Table or column. If this is missing the Java name is generated in the following manner:

Underscores are removed, first letter and first letter after each underscore is uppercased, all other letters are lowercased. So YOUR_TABLE_NAME would become YourTableName.

Element: column

The column element and its relevant attributes

       

The column element has 13 attributes associated with it, they are:

nameThe name of the column being referenced
javaNameHow this column will be referred to in Java
primaryKeyIs this a primary key or not (true or false, defaults to false)
requiredWhether a value is required in this field (true or false, defaults to false)
typeWhat type of column is it? Covered below, defaults to VARCHAR
javaTypeThe type of the column in Java (object or primitive)
sizeHow many characters or digits can be stored?
defaultDefault value to insert into field if it is missing.
autoIncrementWhether or not to auto-increment this field (true or false, defaults to false)
inheritance? (single or false, defaults to false)
inputValidator?
javaNamingMethodSpecifies how the name attribute is converted to the Java class name of the corresponding OM object. This attribute overrides the defaultJavaNamingMethod attribute of the database element
descriptionUsed for doc generation

The column element can contain the following elements:

inheritance0 or more

Element: inheritance

The inheritance element and its relevant attributes

        

The inheritance element has 3 attributes associated with it, they are:

key?
class?
extends?

The inheritance element can not contain other elements.

Element: foreign-key

The foreign-key element and its relevant attributes

      

The foreign-key element has 4 attributes associated with it, they are:

foreignTableThe name of the table being referenced
nameThe name of the foreign key
onUpdateThe action to take when the referenced value in foreignTable is updated
onDeleteThe action to take when the referenced value in foreignTable is deleted

The foreign-key element can contain the following elements:

reference1 or more

Element: reference

The reference element and its relevant attributes

      

The reference element has 2 attributes associated with it, they are:

localThe local reference
foreignThe foreign key reference

The reference element can not contain other elements.

Element: index

The index element and its relevant attributes

      

The index element has 1 attribute associated with it, it is:

nameThe name of the index

The index element can contain the following elements:

index-column1 or more

Element: index-column

The index-column element and its relevant attributes

      

The index-column element has 2 attributes associated with it, they are:

nameThe name of the indexed column
size?

The index-column element can not contain other elements.

Element: unique

The unique element and its relevant attributes

      

The unique element has 1 attribute associated with it, it is:

nameThe name of the unique constraint

The unique element can contain the following elements:

unique-column1 or more

Element: unique-column

The unique-column element and its relevant attributes

      

The unique-column element has 1 attribute associated with it, it is:

nameThe name of the unique column

The unique-column element can not contain other elements.