In the previous section, we saw that the datastore-identity
element can take either a column
attribute
or nested column
elements. This option is repeated
on many elements throughout mapping metadata. The motivation for this
dualistic approach is to make the common case easy, but retain
the flexibility to handle more complex scenarios. When a mapping has
a single column with default properties, you can use the
column
attribute to just name the column. When, on the
other hand, a mapping has multiple columns or columns with non-default
properties, you can fall back to nested column
elements. We saw this in
Example 15.3, “Datastore Identity Mapping” above: most classes
used the column
attribute to simply name the
primary key column, but Author
and
Magazine
used a nested element in order to
specify additional column information. Column elements have the
following attributes:
name
: The column name. Later in this
chapter, we will come across situations where a column is not
in the expected table. In these cases, you can specify the
column name as
<table-name>.<column-name>
, or even
<schema-name>.<table-name>.<column-name>
.
The column name is required for runtime use. The reason the
name
attribute isn't marked
#REQUIRED
in the DTD is that some vendors
may allow you to partially-specify column information during
the mapping process, and have the rest filled in by a
vendor-supplied tool.
jdbc-type
: Determines what JDBC APIs the
implementation uses to load and store data to the column.
This attribute is only required when the column uses a
non-default type for the associated data - for example,
when a String
is mapped to a
CLOB
column rather than a
CHAR
or VARCHAR
.
Standard values for this attribute include all of the constant
names from the java.sql.Types
class, in
either uppercase or lowercase: BIGINT, bigint, BLOB, blob,
DECIMAL, decimal, VARCHAR, varchar, etc.
sql-type
: The database-specific column type
name. This attribute is only used by vendors that support
creating tables from your mapping metadata. During table
creation, the vendor will use the text of the
sql-type
attribute as the declared column
type. If no sql-type
is given, the vendor
will choose an appropriate default based on the
column's JDBC type, length, and scale.
length
: The column length. This attribute
is typically only used during table creation, though some
vendors might use it to validate data before flushing.
CHAR
and VARCHAR
columns typically default to a length of 255; other
column types use the database default.
scale
: The number of decimal digits a numeric
column can hold. This attribute is often used in
conjunction with length
to form the proper
column type name during table creation.
allows-null
: Whether the column can store
null values. Vendors may use this attribute both for table
creation and at runtime; however, it is never required.
Defaults to false
for primary key columns
and columns holding primitive field values, and
true
for all other columns.
default-value
: A database-assigned default
value for the column if no value is given in the
INSERT
SQL. Vendors will pass this default on to the
database during table creation. When a new object is being
persisted with Java default field values, vendors may use this
attribute to decide whether to include the columns for those
fields in the generated INSERT
SQL.
Note | |
---|---|
Kodo uses a combination of a column's default value and JDO
metadata's |
target
: In joins, the column that this
column joins to. We examine joins in detail in the next
section.
target-field
: In joins, the primary key
field of the related type that this column joins to. We
examine joins in detail in the next section.
Note | |
---|---|
Kodo also defines extensions to mark that the current mapping should not attempt to insert or update a column's value. See Section 7.9.3, “Column Extensions” in the Reference Guide. |