com.triactive.jdo.store.mapping
Class Mapping

java.lang.Object
  com.triactive.jdo.store.mapping.Mapping

Direct Known Subclasses:

ColumnMapping, ComplexMapping

public abstract class Mapping

extends java.lang.Object

An object that maps between a Java type and its relational representation in the data store.

Subclasses of Mapping define and perform the storage and retrieval functions for a particular Java type. They also assist in arbitrary SQL generation such as done during Query compilation.

Individual Mapping objects are sometimes bound to specific database tables or columns, and are re-used for all data transfers. Other times a Mapping is merely prototypical, and is used for transferring to or from any suitable table/column.

Author:

Mike Martin

See Also:

DatabaseAdapter.newMapping(Class), DatabaseAdapter.newMapping(FieldMetaData)

Field Summary

protected DatabaseAdapter	dba The database adapter for this mapping.
protected FieldMetaData	fmd The metadata for the persistent field mapped by this mapping, or null if not mapping a persistent field.
protected java.lang.Class	type The Java type mapped by this mapping.

Constructor Summary

protected	Mapping(DatabaseAdapter dba, java.lang.Class type) Constructs a new mapping for a given Java type.
protected	Mapping(DatabaseAdapter dba, FieldMetaData fmd) Constructs a new mapping for a given persistent field.

Method Summary

abstract SqlExpression	accessAsFieldIn(FcoExpression objExpr) Returns an SQL expression representing the persistent field mapped by this mapping within a particular first-class object expression.
abstract void	defineConstraints(BaseTable table, StoreManager.MgmtTransaction mtx) Causes the mapping object to define whatever constraints it needs on its backing storage, relative to the specified table.
abstract void	defineStorage(Table table, StoreManager.MgmtTransaction mtx) Causes the mapping object to define whatever backing storage it needs, relative to the specified table.
boolean	equals(java.lang.Object obj) Tests this object for equality with another object.
static java.util.Map	getDefaultMappingsByType() Returns the default map of Java types to Mapping classes.
FieldMetaData	getFieldMetaData() Returns the field metadata for the field that this mapping maps to the database.
java.lang.Class	getType() Return the Class that this Mapping maps to the database.
int	hashCode() Returns a hash code value for this object.
abstract SqlExpression	newSqlLiteral(QueryStatement qs, java.lang.Object value) Returns an SQL expression representing the literal value of a Java object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

dba

protected final DatabaseAdapter dba

The database adapter for this mapping.

type

protected final java.lang.Class type

The Java type mapped by this mapping.

fmd

protected final FieldMetaData fmd

The metadata for the persistent field mapped by this mapping, or null if not mapping a persistent field.

Constructor Detail

Mapping

protected Mapping(DatabaseAdapter dba,
                  java.lang.Class type)

Constructs a new mapping for a given Java type.

Parameters:

dba - the database adapter

type - the Java class that this mapping maps to the database

Mapping

protected Mapping(DatabaseAdapter dba,
                  FieldMetaData fmd)

Constructs a new mapping for a given persistent field.

Parameters:

dba - the database adapter

fmd - the field metadata for the field that this mapping maps to the database

Method Detail

getType

public java.lang.Class getType()

Return the Class that this Mapping maps to the database.

Returns:

The Class that this Mapping maps to the database.

getFieldMetaData

public FieldMetaData getFieldMetaData()

Returns the field metadata for the field that this mapping maps to the database.

Returns:

The field metadata, or null if this mapping object does not map a persistent field.

defineStorage

public abstract void defineStorage(Table table,
                                   StoreManager.MgmtTransaction mtx)

Causes the mapping object to define whatever backing storage it needs, relative to the specified table. Depending on the type of mapping, this may mean adding columns to the table, constructing other related table objects, or both.

Storage in this case means only tables, columns, and primary keys. Other candidate keys, foreign keys, and indexes are added by defineConstraints(com.triactive.jdo.store.sql.BaseTable, com.triactive.jdo.store.StoreManager.MgmtTransaction).

The StoreManager will never call this method more than once.

Parameters:

table - the table relative to which storage should be defined.

mtx - the context in which the mapping is being initialized

defineConstraints

public abstract void defineConstraints(BaseTable table,
                                       StoreManager.MgmtTransaction mtx)

Causes the mapping object to define whatever constraints it needs on its backing storage, relative to the specified table. Depending on the type of mapping, this may mean adding any or all of candidate keys, foreign keys, or indexes to the specified table and/or other tables.

This method only applies to base tables. It will always be called after calling defineStorage(com.triactive.jdo.store.sql.Table, com.triactive.jdo.store.StoreManager.MgmtTransaction) and is passed the same table argument.

The StoreManager will never call this method more than once.

Parameters:

table - the table relative to which constraints should be defined.

mtx - the context in which the mapping is being initialized

newSqlLiteral

public abstract SqlExpression newSqlLiteral(QueryStatement qs,
                                            java.lang.Object value)

Returns an SQL expression representing the literal value of a Java object. The object must be of a type used with this mapping.

Parameters:

qs - the surrounding query statement for the expression

value - the literal value

Throws:

java.lang.ClassCastException - if the type of value is not compatible with this mapping

accessAsFieldIn

public abstract SqlExpression accessAsFieldIn(FcoExpression objExpr)

Returns an SQL expression representing the persistent field mapped by this mapping within a particular first-class object expression. Throws an exception if this mapping does not map a specified persistent field.

Parameters:

objExpr - an expression representing a first-class object

Throws:

java.lang.IllegalStateException - if this mapping does not map a specified persistent field.

hashCode

public int hashCode()

Returns a hash code value for this object.

equals

public boolean equals(java.lang.Object obj)

Tests this object for equality with another object. Two Mapping objects are equal if they are of the same type and their database adapters, types, and field metadata (if present) are all equal.

Parameters:

obj - the object to compare with

Returns:

true if the objects are equal, false otherwise.

getDefaultMappingsByType

public static java.util.Map getDefaultMappingsByType()

Returns the default map of Java types to Mapping classes. Each new DatabaseAdapter object calls this method to get its default set of mappings. Adapter subclasses may modify the map as needed.

Known field types that are not (yet) supported have an entry with a mapping class of UnsupportedMapping.

Returns:

an unmodifiable Map whose keys and values are both of type Class.