5.5 Mapping a Single-Valued Field to a Column

A primitive or single-valued Java field usually is mapped to a single column of a table. Some implementations allow a field to be mapped to multiple columns, but such a feature is not supported by most implementations or needed in most applications. When mapping a Java field to a relational column, you need to consider the name and the type to be used for the associated column. The types are always different, since Java and SQL have their own distinct type systems. The name of the field and column can be either the same or different.

5.5.1 Name-Mapping

When you're mapping a field in Java to a relational column, you can use different names. In some cases, you may have to use a different name, because some names in Java may not be allowable as a column name in the relational database. In Java, class and field names are case-sensitive Unicode characters. Some relational databases and JDBC drivers may have restrictions on the names that are used (e.g., the table and column names must be US ASCII, names are case-insensitive, or names must be uppercase). Using a field or class name that is a keyword in SQL or the relational database also necessitates a mapping to a different name in the datastore.

You may wish to map the firstName field of the Customer class to a column named fname:

<class name="Customer" >
   <field name="firstName" >
      <extension 
vendor-name="vendorX" key="column" value="fname"/>
      <extension vendor-name="vendorY" key="sqlname" value="fname"/>
   </field>
</class>

If the firstName field does not already have a field element, you need to add one to specify the column name in a nested extension element. In this case, to specify the column to map the field to, vendorX uses a value of "column" and vendorY uses a value of "sqlname" for the key attribute. Again, the value for the key attribute is implementation-specific and you can provide extension elements for multiple implementations without any interference.

5.5.2 Type-Mapping

Besides specifying the name of the column, you may also want to indicate the column's datatype. The datatypes that can be used for a specific Java type vary across relational datastores and JDO implementations. The supported column types for each Java datatype in each underlying datastore should be specified in your JDO implementation's documentation. Table 5-2 provides a list of the relational column datatypes commonly supported for the Java types supported by JDO.

Table 5-2. Java types and corresponding column types found in relational databases

Java type	Column datatypes
Boolean, boolean	BIT, TINYINT, SMALLINT, BYTE, INT2
Byte, byte	TINYINT, SMALLINT, BYTE, INT2
Character, char	INTEGER, CHAR, VARCHAR
Short, short	SMALLINT, INTEGER, NUMBER, INT2
Integer, int	INTEGER, NUMBER, INT4
Long, long	BIGINT, DECIMAL, INT8
Float, float	FLOAT, DECIMAL, REAL
Double, double	DOUBLE, NUMBER, DECIMAL
BigInteger	DECIMAL, NUMBER, NUMERIC, BIGINT
BigDecimal	DECIMAL, NUMBER, DOUBLE
String	CHAR, VARCHAR, VARCHAR2, LONGVARCHAR, CLOB
Date	TIMESTAMP, DATE, DATETIME
Locale	VARCHAR

ANSI SQL defines some of these column types. Others are supported by specific relational databases and found in applications' schemas. Some implementations allow you to specify the maximum size of a String stored in the datastore.

BLOBs You may be using JDO with an existing relational schema that has a column defined as a binary large object (BLOB) and wonder how JDO deals with them. The short answer is that the JDO 1.0.1 Specification does not directly specify the mapping for any datastore-specific datatype. Your JDO implementation defines the mappings it supports from Java types to the datatypes of the underlying datastore. You should ask yourself what kind of data the BLOB contains and why it is being stored as a BLOB. In some circumstances, a BLOB contains structured data that may be more appropriately and easily represented as persistent objects in JDO. Sometimes BLOBs are used as a denormalizing technique to simplify the modeling and access of a complex graph of data. In other cases, BLOBs and denormalization are used as an optimization technique because a normalized representation of the data cannot be efficiently accessed. The best approach for dealing with data commonly found in a BLOB depends on the kind of data involved and how effective your JDO implementation and datastore are in dealing with the data.

5.5.3 Indexes

JDO does not define the concept of an index. Indexes can be added to columns independent of the JDO environment. However, some implementations may allow you to specify indexes in the metadata, allowing you to provide the index information relative to the fields in your Java classes. An index on a single field is usually specified as a nested extension of a field element. If the index includes more than one column, it will likely be specified with an extension of the class element, so that you can specify the order of the fields in the index.