/**********************************************************************
Copyright (c) 2004 Erik Bengtson and others. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Contributors:
...
**********************************************************************/
package org.jpox.store.mapped.mapping;
import org.jpox.ClassLoaderResolver;
import org.jpox.ObjectManager;
import org.jpox.ObjectManagerFactoryImpl;
import org.jpox.StateManager;
import org.jpox.exceptions.JPOXException;
import org.jpox.metadata.AbstractMemberMetaData;
import org.jpox.store.mapped.DatastoreAdapter;
import org.jpox.store.mapped.DatastoreContainerObject;
import org.jpox.store.mapped.expression.LogicSetExpression;
import org.jpox.store.mapped.expression.QueryExpression;
import org.jpox.store.mapped.expression.ScalarExpression;
import org.jpox.util.Localiser;
/**
* Representation of the mapping of a Java type.
* The java type maps to one or more datastore mappings. This means that a field
* in a java class can be mapped to many columns in a table (in an RDBMS).
* A JavaTypeMapping can exist in 2 forms
* <ul>
* <li>Constructed for the java type on its own to represent a literal in a JDOQL query, and consequently has
* no metadata/container information</li>
* <li>Constructed for a field managed by a datastore container, and so has metadata/container information</li>
* </ul>
*
* @version $Revision: 1.33 $
**/
public abstract class JavaTypeMapping
{
/** Localiser for messages */
protected static final Localiser LOCALISER = Localiser.getInstance("org.jpox.store.Localisation",
ObjectManagerFactoryImpl.class.getClassLoader());
/** Role signifying that the mapping is for a field in the primary class table */
public static final int MAPPING_FIELD = 0;
/** Role signifying that the mapping is for a collection element in a join table */
public static final int MAPPING_COLLECTION_ELEMENT = 1;
/** Role signifying that the mapping is for an array element in a join table */
public static final int MAPPING_ARRAY_ELEMENT = 2;
/** Role signifying that the mapping is for a map key in a join table */
public static final int MAPPING_MAP_KEY = 3;
/** Role signifying that the mapping is for a value in a join table */
public static final int MAPPING_MAP_VALUE = 4;
/**
* The field definition, when the type relates specifically to a field.
* When this mapping is for a query literal then the metadata will be null.
*/
protected AbstractMemberMetaData fmd;
/**
* Role of the mapping for the field. Whether it is for the field as a whole, or element of
* a collection field (in a join table), or key/value of a map field (in a join table).
*/
protected int roleForField = MAPPING_FIELD;
/** The Datastore mappings for this Java type. */
protected DatastoreMapping[] datastoreMappings = new DatastoreMapping[0];
/** The Datastore Container storing this mapping. */
protected DatastoreContainerObject datastoreContainer;
/** Adapter for the datastore being used. */
protected DatastoreAdapter dba;
/** Actual type being mapped */
protected String type;
/**
* Mapping of the reference on the end of the association - Only used when this mapping does not
* have datastore fields, but the other side of the association has
*/
protected JavaTypeMapping referenceMapping;
/**
* Create a new empty JavaTypeMapping.
* The caller must call one of the initialize methods to initialize the instance with the DatastoreAdapter
* and its type.
* <p>
* The combination of this empty constructor and one of the initialize method is used instead of parameterized
* constructors for efficientcy purpose, both in execution time and code maintainability.
* See MappingFactory for how they are used.
* </p>
* <p>
* Concrete subclasses must have a public accesstable empty constructor.
* </p>
*/
protected JavaTypeMapping()
{
}
/**
* Create a new Mapping with the given DatastoreAdapter for the given type.
* @param dba The Datastore Adapter that this Mapping should use.
* @param type The Class that this mapping maps to the database.
* @param fmd FieldMetaData for the field to be mapped (if any)
* @param container The datastore container storing this mapping (if any)
*/
protected JavaTypeMapping(DatastoreAdapter dba, String type, AbstractMemberMetaData fmd,
DatastoreContainerObject container)
{
this.dba = dba;
this.type = type;
this.fmd = fmd;
this.datastoreContainer = container;
}
/**
* Initialize this JavaTypeMapping with the given DatastoreAdapter for the given type.
* This will not set the "fmd" and "datastoreContainer" parameters. If these are required for
* usage of the mapping then you should call
* "setFieldInformation(AbstractMemberMetaData, DatastoreContainerObject)" below
* @param dba The Datastore Adapter that this Mapping should use.
* @param type The Class that this mapping maps to the database.
* @see MappingFactory#createMapping(Class, DatastoreAdapter, String)
*/
public void initialize(DatastoreAdapter dba, String type)
{
this.dba = dba;
this.type = type;
}
/**
* Initialize this JavaTypeMapping with the given DatastoreAdapter for the given FieldMetaData.
* Subclasses should override this method to perform any datastore initialization operations.
* @param dba The Datastore Adapter that this Mapping should use.
* @param fmd FieldMetaData for the field to be mapped (if any)
* @param container The datastore container storing this mapping (if any)
* @param clr the ClassLoaderResolver
*/
public void initialize(DatastoreAdapter dba, AbstractMemberMetaData fmd, DatastoreContainerObject container,
ClassLoaderResolver clr)
{
this.dba = dba;
this.fmd = fmd;
this.type = fmd.getType().getName();
this.datastoreContainer = container;
}
/**
* Convenience method for use where the mapping was created for a particular type
* (using the initialize(DatastoreAdapter, String) and we now have the field that it applies for.
* @param fmd Field MetaData
* @param container Container (table) that the mapping is for
*/
public void setFieldInformation(AbstractMemberMetaData fmd, DatastoreContainerObject container)
{
this.fmd = fmd;
this.datastoreContainer = container;
}
/**
* Method to set the role for the field.
* Should be called before initialize().
* @param role Role for field.
*/
public void setRoleForField(int role)
{
roleForField = role;
}
/**
* Convenience method to return if the (part of the) field being represented by this mapping is serialised.
* @return Whether to use Java serialisation
*/
public boolean isSerialised()
{
if (roleForField == MAPPING_FIELD)
{
return (fmd != null ? fmd.isSerialized() : false);
}
else if (roleForField == MAPPING_COLLECTION_ELEMENT)
{
if (fmd == null)
{
return false;
}
return (fmd.getCollection() != null ? fmd.getCollection().isSerializedElement() : false);
}
else if (roleForField == MAPPING_ARRAY_ELEMENT)
{
if (fmd == null)
{
return false;
}
return (fmd.getArray() != null ? fmd.getArray().isSerializedElement() : false);
}
else if (roleForField == MAPPING_MAP_KEY)
{
if (fmd == null)
{
return false;
}
return (fmd.getMap() != null ? fmd.getMap().isSerializedKey() : false);
}
else if (roleForField == MAPPING_MAP_VALUE)
{
if (fmd == null)
{
return false;
}
return (fmd.getMap() != null ? fmd.getMap().isSerializedValue() : false);
}
return false;
}
/**
* Accessor for whether this mapping is nullable
* @return Whether it is nullable
*/
public boolean isNullable()
{
for (int i=0; i<datastoreMappings.length; i++)
{
if (!datastoreMappings[i].isNullable())
{
return false;
}
}
return true;
}
/**
* Accessor for the datastore mappings for this java type
* @return The datastore mapping(s)
*/
public DatastoreMapping[] getDataStoreMappings()
{
return datastoreMappings;
}
/**
* Accessor for the datastore class (e.g in an RDBMS context, the Table).
* Will be null if this mapping is for a literal in a query.
* @return The datastore class containing this mapped field.
*/
public DatastoreContainerObject getDatastoreContainer()
{
return datastoreContainer;
}
/**
* Accessor for a datastore mapping
* @param index The id of the mapping
* @return The datastore mapping
*/
public DatastoreMapping getDataStoreMapping(int index)
{
return datastoreMappings[index];
}
/**
* Accessor for the mapping at the other end of a relation when this field is
* part of a 1-1, 1-N, M-N relation. Will be null otherwise.
* @return The mapping at the other end.
*/
public JavaTypeMapping getReferenceMapping()
{
return referenceMapping;
}
/**
* Method to set the mapping at the other end of the relation.
* Not to be used when this field is not part of a relation.
* @param referenceMapping The mapping at the other end
*/
public void setReferenceMapping(JavaTypeMapping referenceMapping)
{
this.referenceMapping = referenceMapping;
}
/**
* Method to add a datastore mapping
* @param datastoreMapping The datastore mapping
*/
public void addDataStoreMapping(DatastoreMapping datastoreMapping)
{
DatastoreMapping[] dm = datastoreMappings;
datastoreMappings = new DatastoreMapping[datastoreMappings.length+1];
System.arraycopy(dm, 0, datastoreMappings, 0, dm.length);
datastoreMappings[dm.length] = datastoreMapping;
}
/**
* Acessor for the number of datastore fields (e.g. RDBMS number of columns)
* @return the number of datastore fields
*/
public int getNumberOfDatastoreFields()
{
return datastoreMappings.length;
}
/**
* Accessor for the FieldMetaData of the field to be mapped.
* Will be null if this mapping is for a literal in a query.
* @return Returns the FieldMetaData.
*/
public AbstractMemberMetaData getFieldMetaData()
{
return fmd;
}
/**
* Accessor for the role of the is mapping for the field.
* @return Role of this mapping for the field
*/
public int getRoleForField()
{
return roleForField;
}
/**
* Accessor for the java type being mapped.
* This is the java type that the mapping represents. Some examples :
* <ul>
* <li>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.</li>
* <li>if the field is of type "int" then the mapping will be IntegerMapping, the javaType will
* be Integer, and the type will be int.</li>
* </ul>
* The "java type" is the java-type name used in the plugin.xml mapping file
* @return The java type
*/
public abstract Class getJavaType();
/**
* Accessor for the name of the java-type actually used when mapping the particular datastore
* field. This java-type must have an entry in the datastore mappings.
* The default implementation throws an UnsupportedOperationException.
* TODO Merge this with getJavaType().
*
* @param index requested datastore field index.
* @return the name of java-type for the requested datastore field.
*/
public String getJavaTypeForDatastoreMapping(int index)
{
throw new UnsupportedOperationException("Datastore type mapping is not supported by: "+getClass());
}
/**
* Accessor for the class name of the object that is being mapped here.
* There are mainly two situations:
* <ul>
* <li>For a JavaTypeMapping that maps a PersistentCapable class field, this will return
* the type of the field. For example with a field of type "MyClass" this will return "MyClass"</li>
* <li>For a JavaTypeMapping that maps a variable or parameter in a query, this will return
* the type declared in the query.</li>
* </ul>
* @return The actual type that this Mapping maps.
*/
public String getType()
{
return type;
}
/**
* Return a sample value of the mapping type to be used for internal
* evaluation of type and conversion.
* @param clr TODO
* @return The sample value.
*/
public abstract Object getSampleValue(ClassLoaderResolver clr);
/**
* Accessor for whether this mapping is to be included in any fetch statement.
* @return Whether to include this mapping in a fetch statement
*/
public boolean includeInFetchStatement()
{
return true;
}
/**
* Accessor for whether this mapping is to be included in the update statement.
* @return Whether to include in update statement
*/
public boolean includeInUpdateStatement()
{
return true;
}
/**
* Accessor for whether this mapping is to be included in the insert statement.
* @return Whether to include in insert statement
*/
public boolean includeInInsertStatement()
{
return true;
}
/**
* Creates a literal from an value.
* A string literal is enclosed in single quotes. for example: "literal".
* A string literal that includes a single quote is represented by two
* single quotes. for example: "literal''s".
* An exact numeric literal is a numeric value without a decimal point,
* such as 57, -957, +62.
* An approximate numeric literal is a numeric value in scientific notation,
* such as 7E3, -57.9E2, or a numeric value with a decimal, such as 7.,
* -95.7, +6.2.
* @param qs The Query statement
* @param value The object
* @return A Scalar Expression
*/
public abstract ScalarExpression newLiteral(QueryExpression qs, Object value);
/**
* Creates a expression from a field name/table.
* e.g. tablename.fieldname; tablealias.fieldalias
* @param qs The Query statement
* @param te the alias for the table
* @return A Scalar Expression
*/
public abstract ScalarExpression newScalarExpression(QueryExpression qs, LogicSetExpression te);
/**
* Utility to output any error message.
* @param method The method that failed.
* @return the localised failure message
**/
protected String failureMessage(String method)
{
return LOCALISER.msg("041004",getClass().getName(),method);
}
// ------------------- Accessors & Mutators for datastore access -----------------------
/**
* Convenience setter to provide a default value for this field.
* If the field is nullable, a null is provided, otherwise the sample value.
* @param om The ObjectManager
* @param datastoreStatement Prepared Statement
* @param exprIndex The indices in the statement
*/
public void setDefault(ObjectManager om, Object datastoreStatement, int[] exprIndex)
{
// TODO Dont just use the first datastore mapping and parameter number
getDataStoreMapping(0).setObject(datastoreStatement, exprIndex[0], isNullable() ? null : getSampleValue(om.getClassLoaderResolver()));
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setBoolean(ObjectManager om, Object datastoreStatement, int[] exprIndex, boolean value)
{
throw new JPOXException(failureMessage("setBoolean")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public boolean getBoolean(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("setBoolean")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setChar(ObjectManager om, Object datastoreStatement, int[] exprIndex, char value)
{
throw new JPOXException(failureMessage("setChar")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public char getChar(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getChar")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setByte(ObjectManager om, Object datastoreStatement, int[] exprIndex, byte value)
{
throw new JPOXException(failureMessage("setByte")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public byte getByte(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getByte")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setShort(ObjectManager om, Object datastoreStatement, int[] exprIndex, short value)
{
throw new JPOXException(failureMessage("setShort")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public short getShort(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getShort")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setInt(ObjectManager om, Object datastoreStatement, int[] exprIndex, int value)
{
throw new JPOXException(failureMessage("setInt")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public int getInt(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getInt")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setLong(ObjectManager om, Object datastoreStatement, int[] exprIndex, long value)
{
throw new JPOXException(failureMessage("setLong")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public long getLong(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getLong")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setFloat(ObjectManager om, Object datastoreStatement, int[] exprIndex, float value)
{
throw new JPOXException(failureMessage("setFloat")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public float getFloat(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getFloat")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setDouble(ObjectManager om, Object datastoreStatement, int[] exprIndex, double value)
{
throw new JPOXException(failureMessage("setDouble")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public double getDouble(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getDouble")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setString(ObjectManager om, Object datastoreStatement, int[] exprIndex, String value)
{
throw new JPOXException(failureMessage("setString")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public String getString(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getString")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
* @param ownerSM the owner StateManager
* @param ownerFieldNumber the owner absolute field number
*/
public void setObject(ObjectManager om, Object datastoreStatement, int[] exprIndex, Object value, StateManager ownerSM, int ownerFieldNumber)
{
throw new JPOXException(failureMessage("setObject")).setFatal();
}
/**
* Sets a <code>value</code> into <code>datastoreStatement</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreStatement a datastore object that executes statements in the database
* @param exprIndex the position of the value in the statement
* @param value the value
*/
public void setObject(ObjectManager om, Object datastoreStatement, int[] exprIndex, Object value)
{
throw new JPOXException(failureMessage("setObject")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @param ownerSM the owner StateManager
* @param ownerFieldNumber the owner absolute field number
* @return the value
*/
public Object getObject(ObjectManager om, Object datastoreResults, int[] exprIndex, StateManager ownerSM, int ownerFieldNumber)
{
throw new JPOXException(failureMessage("getObject")).setFatal();
}
/**
* Obtains a value from <code>datastoreResults</code>
* at position specified by <code>exprIndex</code>.
* @param om the ObjectManager
* @param datastoreResults an object returned from the datastore with values
* @param exprIndex the position of the value in the result
* @return the value
*/
public Object getObject(ObjectManager om, Object datastoreResults, int[] exprIndex)
{
throw new JPOXException(failureMessage("getObject")).setFatal();
}
}