org.datanucleus.store.mapped.mapping
Class ReferenceMapping

java.lang.Object
  org.datanucleus.store.mapped.mapping.JavaTypeMapping
      org.datanucleus.store.mapped.mapping.MultiMapping
          org.datanucleus.store.mapped.mapping.ReferenceMapping

All Implemented Interfaces:

MappingCallbacks

Direct Known Subclasses:

InterfaceMapping, ObjectMapping, ReferenceIdMapping

public abstract class ReferenceMapping
extends MultiMapping
implements MappingCallbacks

Mapping for a "reference" type. This can be used for things like interfaces, or Object which are simply a reference to some specific (PersistenceCapable) class. This can be persisted in several ways (see "mappingStrategy") :-

• List of possible "implementations" of the reference type where column(s) are created for each possible implementation of the reference as a FK to the implementation table. This has the advantage that it retains referential integrity since direct FKs are used.
• What Kodo/Xcalia used was a single column storing the identity toString() form.

Field Summary

static int	ID_MAPPING Single column containing the "identity" of an object.
protected static Localiser	LOCALISER_MAPPED Localiser for messages
protected int	mappingStrategy Strategy for how the reference(s) are mapped.
static int	PER_IMPLEMENTATION_MAPPING Each implementation has its own column(s) as a FK to the related table.
static int	XCALIA_MAPPING Single column containing the Xcalia form of the "identity" of an object.

Fields inherited from class org.datanucleus.store.mapped.mapping.MultiMapping

javaTypeMappings, numberOfDatastoreMappings

Fields inherited from class org.datanucleus.store.mapped.mapping.JavaTypeMapping

datastoreContainer, datastoreMappings, LOCALISER, mmd, referenceMapping, roleForMember, storeMgr, type

Constructor Summary

ReferenceMapping()

Method Summary

java.lang.Class	getJavaType() Accessor for the java type being mapped.
java.lang.String	getJavaTypeForDatastoreMapping(int index) Accessor for the java type represented by a particular datastore mapping.
int	getMappingNumberForValue(ObjectManager om, java.lang.Object value) Convenience accessor for the number of the java type mapping where the passed value would be stored.
int	getMappingStrategy() Accessor for the mapping strategy.
java.lang.Object	getObject(ObjectManager om, java.lang.Object rs, int[] pos) Method to retrieve an object of this type from the ResultSet.
protected java.lang.Object	getObjectForReferenceString(ObjectManager om, java.lang.String refString) Method to convert a "reference string" into the associated object.
protected java.lang.String	getReferenceStringForObject(ObjectManager om, java.lang.Object value) Method to convert an object to be stored into a "reference string" to store.
java.lang.Object	getSampleValue(ClassLoaderResolver clr) Return a sample value of the mapping type to be used for internal evaluation of type/conversion.
void	initialize(AbstractMemberMetaData mmd, DatastoreContainerObject container, ClassLoaderResolver clr) Initialize this JavaTypeMapping for the specified field/property.
void	insertPostProcessing(StateManager sm) Hook so that we can handle any post-processing on the insert of a particular field.
ScalarExpression	newLiteral(QueryExpression qs, java.lang.Object value) Creates a literal from an value for use in TJDO-style JDOQL.
ScalarExpression	newScalarExpression(QueryExpression qs, LogicSetExpression te) Creates a expression from a field name/table.
void	postFetch(StateManager sm) Method executed just after a fetch of the owning object, allowing any necessary action to this field and the object stored in it.
void	postInsert(StateManager sm) Method executed just after the insert of the owning object, allowing any necessary action to this field and the object stored in it.
void	postUpdate(StateManager sm) Method executed just afer any update of the owning object, allowing any necessary action to this field and the object stored in it.
void	preDelete(StateManager sm) Method executed just before the owning object is deleted, allowing tidying up of any relation information.
protected void	prepareDatastoreMapping(ClassLoaderResolver clr) Convenience method to create the necessary columns to represent this reference in the datastore.
void	setObject(ObjectManager om, java.lang.Object ps, int[] pos, java.lang.Object value, StateManager ownerSM, int ownerFieldNumber) Sets the specified positions in the PreparedStatement associated with this field, and value.

Methods inherited from class org.datanucleus.store.mapped.mapping.MultiMapping

addJavaTypeMapping, getDatastoreMapping, getDatastoreMappings, getJavaTypeMapping, getNumberOfDatastoreMappings, setObject

Methods inherited from class org.datanucleus.store.mapped.mapping.JavaTypeMapping

addDatastoreMapping, equals, failureMessage, getBoolean, getByte, getChar, getColumnMetaDataForMember, getDatastoreContainer, getDouble, getFloat, getInt, getLong, getMemberMetaData, getObject, getReferenceMapping, getRoleForMember, getShort, getString, getType, getValueForDatastoreMapping, hashCode, hasSimpleDatastoreRepresentation, includeInFetchStatement, includeInInsertStatement, includeInUpdateStatement, initialize, isNullable, isSerialised, setBoolean, setByte, setChar, setDatastoreContainer, setDefault, setDouble, setFloat, setInt, setLong, setMemberMetaData, setReferenceMapping, setRoleForMember, setShort, setString

Methods inherited from class java.lang.Object

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

Field Detail

LOCALISER_MAPPED

protected static final Localiser LOCALISER_MAPPED

Localiser for messages

PER_IMPLEMENTATION_MAPPING

public static final int PER_IMPLEMENTATION_MAPPING

Each implementation has its own column(s) as a FK to the related table.

See Also:

Constant Field Values

ID_MAPPING

public static final int ID_MAPPING

Single column containing the "identity" of an object.

See Also:

Constant Field Values

XCALIA_MAPPING

public static final int XCALIA_MAPPING

Single column containing the Xcalia form of the "identity" of an object.

See Also:

Constant Field Values

mappingStrategy

protected int mappingStrategy

Strategy for how the reference(s) are mapped.

Constructor Detail

ReferenceMapping

public ReferenceMapping()

Method Detail

initialize

public void initialize(AbstractMemberMetaData mmd,
                       DatastoreContainerObject container,
                       ClassLoaderResolver clr)

Initialize this JavaTypeMapping for the specified field/property.

Overrides:

initialize in class JavaTypeMapping

Parameters:

mmd - AbstractMemberMetaData for the field to be mapped (if any)

container - The datastore container storing this mapping (if any)

clr - the ClassLoaderResolver

getMappingStrategy

public int getMappingStrategy()

Accessor for the mapping strategy. There are various supported strategies for reference fields with the default being one mapping per implementation, but also allowing a single (String) mapping for all implementations.

Returns:

The mapping strategy

prepareDatastoreMapping

protected void prepareDatastoreMapping(ClassLoaderResolver clr)

Convenience method to create the necessary columns to represent this reference in the datastore. With "per-implementation" mapping strategy will create columns for each of the possible implementations. With "identity"/"xcalia" will create a single column to store a reference to the implementation value.

Parameters:

clr - The ClassLoaderResolver

getJavaTypeForDatastoreMapping

public java.lang.String getJavaTypeForDatastoreMapping(int index)

Accessor for the java type represented by a particular datastore mapping. This implementation relays to the superclass implementation except in the case of "identity" mapping strategy, in which case it returns "java.lang.String".

Overrides:

getJavaTypeForDatastoreMapping in class JavaTypeMapping

Parameters:

index - requested datastore field index.

Returns:

the name of java-type for the requested datastore field.

getMappingNumberForValue

public int getMappingNumberForValue(ObjectManager om,
                                    java.lang.Object value)

Convenience accessor for the number of the java type mapping where the passed value would be stored. If no suitable mapping is found will return -1. If is a persistent interface then will return -2 meaning persist against *any* mapping

Overrides:

getMappingNumberForValue in class MultiMapping

Parameters:

om - ObjectManager

value - The value

Returns:

The index of javaTypeMappings to use (if any), or -1 (none), or -2 (any)

setObject

public void setObject(ObjectManager om,
                      java.lang.Object ps,
                      int[] pos,
                      java.lang.Object value,
                      StateManager ownerSM,
                      int ownerFieldNumber)

Sets the specified positions in the PreparedStatement associated with this field, and value.

Overrides:

setObject in class MultiMapping

Parameters:

om - the ObjectManager

ps - a datastore object that executes statements in the database

pos - The position(s) of the PreparedStatement to populate

value - the value stored in this field

ownerSM - the owner StateManager

ownerFieldNumber - the owner absolute field number

getObject

public java.lang.Object getObject(ObjectManager om,
                                  java.lang.Object rs,
                                  int[] pos)

Method to retrieve an object of this type from the ResultSet.

Overrides:

getObject in class MultiMapping

Parameters:

om - Object Manager

rs - The ResultSet

pos - The parameter positions

Returns:

The object

getJavaType

public java.lang.Class getJavaType()

Description copied from class: JavaTypeMapping

Accessor for the java type being mapped. This is the java type that the mapping represents. Some examples :

• if the field is of type "MyClass" then the mapping will be OIDMapping (or subclass) the javaType will be OID, and the type will be MyClass.
• if the field is of type "int" then the mapping will be IntegerMapping, the javaType will be Integer, and the type will be int.

The "java type" is the java-type name used in the plugin.xml mapping file

Specified by:

getJavaType in class JavaTypeMapping

Returns:

The java type

getSampleValue

public java.lang.Object getSampleValue(ClassLoaderResolver clr)

Description copied from class: JavaTypeMapping

Return a sample value of the mapping type to be used for internal evaluation of type/conversion. TODO Delete when we drop legacy support

Overrides:

getSampleValue in class JavaTypeMapping

Parameters:

clr - ClassLoader resolver

Returns:

The sample value.

getReferenceStringForObject

protected java.lang.String getReferenceStringForObject(ObjectManager om,
                                                       java.lang.Object value)

Method to convert an object to be stored into a "reference string" to store. Reference string is of the form :

• ID_MAPPING : "{classname}:{id}"
• XCALIA_MAPPING (datastore-id) : "{definer}:{id-key}" where definer is discriminator/classname
• XCALIA_MAPPING (app-id) : "{definer}:{id}" where definer is discriminator/classname

Parameters:

om - ObjectManager

value - The object

Returns:

The reference string

getObjectForReferenceString

protected java.lang.Object getObjectForReferenceString(ObjectManager om,
                                                       java.lang.String refString)

Method to convert a "reference string" into the associated object. Reference string is of the form :

• ID_MAPPING : "{classname}:{id}"
• XCALIA_MAPPING (datastore-id) : "{definer}:{id-key}" where definer is discriminator/classname
• XCALIA_MAPPING (app-id) : "{definer}:{id}" where definer is discriminator/classname

Parameters:

om - ObjectManager

refString - The reference string

Returns:

The referenced object

insertPostProcessing

public void insertPostProcessing(StateManager sm)

Description copied from interface: MappingCallbacks

Hook so that we can handle any post-processing on the insert of a particular field. For example with Oracle we need to insert "EMPTY_CLOB" and then immediately after do a SELECT of it and update the contents of the CLOB/BLOB.

Specified by:

insertPostProcessing in interface MappingCallbacks

Parameters:

sm - StateManager

postFetch

public void postFetch(StateManager sm)

Method executed just after a fetch of the owning object, allowing any necessary action to this field and the object stored in it.

Specified by:

postFetch in interface MappingCallbacks

Parameters:

sm - StateManager for the owner.

postInsert

public void postInsert(StateManager sm)

Method executed just after the insert of the owning object, allowing any necessary action to this field and the object stored in it.

Specified by:

postInsert in interface MappingCallbacks

Parameters:

sm - StateManager for the owner

postUpdate

public void postUpdate(StateManager sm)

Method executed just afer any update of the owning object, allowing any necessary action to this field and the object stored in it.

Specified by:

postUpdate in interface MappingCallbacks

Parameters:

sm - StateManager for the owner

preDelete

public void preDelete(StateManager sm)

Method executed just before the owning object is deleted, allowing tidying up of any relation information.

Specified by:

preDelete in interface MappingCallbacks

Parameters:

sm - StateManager for the owner

newLiteral

public ScalarExpression newLiteral(QueryExpression qs,
                                   java.lang.Object value)

Description copied from class: JavaTypeMapping

Creates a literal from an value for use in TJDO-style JDOQL. This implementation just throws a NucleusException.

Overrides:

newLiteral in class JavaTypeMapping

Parameters:

qs - The Query statement

value - The object

Returns:

A Scalar Expression TODO Remove this when we drop legacy query mechanism

newScalarExpression

public ScalarExpression newScalarExpression(QueryExpression qs,
                                            LogicSetExpression te)

Description copied from class: JavaTypeMapping

Creates a expression from a field name/table. e.g. tablename.fieldname; tablealias.fieldalias For use in TJDO-style JDOQL. This implementation just throws a NucleusException.

Overrides:

newScalarExpression in class JavaTypeMapping

Parameters:

qs - The Query statement

te - the alias for the table

Returns:

A Scalar Expression TODO Remove this when we drop legacy query mechanism