com.triactive.jdo.store.mapping
Class Mapping

java.lang.Object
  extended bycom.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.


Copyright 2001-2007 The TJDO Project All Rights Reserved.