com.goldencode.p2j.persist

Class AbstractJoin

java.lang.Object

com.goldencode.p2j.persist.AbstractJoin

Direct Known Subclasses:

DynamicJoin, DynamicLegacyKeyJoin, ServerJoin, ServerLegacyKeyJoin

abstract class AbstractJoin
extends java.lang.Object

The abstract base class for dynamic and server-side join helpers. Join helpers are used by query implementations to:

• generate FQL where clause snippets which join records using foreign relations;
• provide query substitution parameters if the FQL snippet requires them at query execution time.

Instances of this class are enclosed within query objects and are used at query prepare time and at query execution time to augment the query with the necessary join semantics.

See Also:

DynamicJoin, ServerJoin

Field Summary

Fields

Modifier and Type	Field and Description
private FQLExpression[][]	fql FQL where clause snippet used to perform the join
protected BufferReference	inverse Buffer to which this component should join via a foreign relation.
private java.lang.Class<? extends DataModelObject>	inverseIface DMO interface for the inverse (non-local) end of the join
static int	NOT_NULL_FIELD The index of fql expression for not null fields.
static int	NULL_FIELD The index of fql expression for null fields.
private java.util.List<FqlType>	parameterTypes Hibernate types of query substitution parameters (null if none)

Constructor Summary

Constructors

Constructor and Description
AbstractJoin(RecordBuffer local, RecordBuffer inverse) Constructor which invokes abstract initialization methods in subclass implementations.

Method Summary

Modifier and Type	Method and Description
protected abstract FQLExpression[][]	generateFQL(RecordBuffer local, RecordBuffer inverse, RelationInfo info, boolean dereference) Generate the set of FQL where clause snippets which will be inserted into the overall FQL statement executed by the enclosing query.
(package private) FQLExpression[][]	getFQL() Get the FQLs for the where clause snippet used to perform the join.
BufferReference	getInverse() Return the inverse buffer used with this join, if any.
(package private) java.lang.Class<? extends DataModelObject>	getInverseInterface() Get the DMO interface for the inverse (non-local) end of the join.
(package private) java.util.List<java.io.Serializable>	getParameters() Get the values of DMO instance fields or the DMO instance itself which will be used as the query substitution parameter(s).
(package private) java.util.List<FqlType>	getParameterTypes() Get the type of the query substitution parameters, if any, which was determined at construction.
protected abstract java.util.List<FqlType>	getParameterTypes(RelationInfo info, boolean dereference) Determine the Hibernate type of the query substitution parameters, if any.
java.util.List<FieldReference>	getUnresolvedParameters() Get a list of unresolved field reference parameters for this join.
protected abstract boolean	isServerJoin() Report whether the join represented by this object takes place at the database server, or within runtime code.
protected void	raiseJoinError(RecordBuffer left, RecordBuffer right, boolean parentIsPersistent) Throw ErrorConditionException that signals that the specified tables cannot be joined.
protected void	setup(RecordBuffer local, RecordBuffer inverse, RelationInfo info, boolean dereference) Perform any additional setup necessary for a particular join helper implementation.

Methods inherited from class java.lang.Object

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

Field Detail

NULL_FIELD

public static final int NULL_FIELD

The index of fql expression for null fields.

See Also:

Constant Field Values

NOT_NULL_FIELD

public static final int NOT_NULL_FIELD

The index of fql expression for not null fields.

See Also:

Constant Field Values

fql

private final FQLExpression[][] fql

FQL where clause snippet used to perform the join

inverseIface

private final java.lang.Class<? extends DataModelObject> inverseIface

DMO interface for the inverse (non-local) end of the join

parameterTypes

private final java.util.List<FqlType> parameterTypes

Hibernate types of query substitution parameters (null if none)

inverse

protected final BufferReference inverse

Buffer to which this component should join via a foreign relation.

Constructor Detail

AbstractJoin

AbstractJoin(RecordBuffer local,
             RecordBuffer inverse)

Constructor which invokes abstract initialization methods in subclass implementations.

Parameters:

local - Local record buffer (the referring end of the join).

inverse - Inverse record buffer (the referent end of the join).

Method Detail

getInverse

public BufferReference getInverse()

Return the inverse buffer used with this join, if any.

Returns:

The inverse buffer used with this join.

getUnresolvedParameters

public java.util.List<FieldReference> getUnresolvedParameters()

Get a list of unresolved field reference parameters for this join.

Returns:

An empty list. Subclasses should override this implementation if a non-empty parameter list is required.

isServerJoin

protected abstract boolean isServerJoin()

Report whether the join represented by this object takes place at the database server, or within runtime code.

Returns:

true if the join happens at the server; false if it happens in the runtime.

generateFQL

protected abstract FQLExpression[][] generateFQL(RecordBuffer local,
                                                 RecordBuffer inverse,
                                                 RelationInfo info,
                                                 boolean dereference)

Generate the set of FQL where clause snippets which will be inserted into the overall FQL statement executed by the enclosing query.

Parameters:

local - Local record buffer (the referring end of the join).

inverse - Inverse record buffer (the referent end of the join).

info - Relation descriptor object.

dereference - true if the local DMO contains a reference to the foreign record, which must be dereferenced in the FQL query; false if the local DMO is the foreign record, referenced by the inverse DMO.

Returns:

FQL where clause snippets used to perform the join. A bi-dimensional array of clauses are used. The first dimension is the size of the join (aka the number of fields paired) and the second is always two: the first (NULL_FIELD) is used when the joined field is null and the second (NOT_NULL_FIELD) is used when the join field is not unknown.

getParameterTypes

protected abstract java.util.List<FqlType> getParameterTypes(RelationInfo info,
                                                             boolean dereference)

Determine the Hibernate type of the query substitution parameters, if any. The parameter(s) generally will be a FQL type of the implementation class of the inverse DMO or the types of DMO fields.

Parameters:

info - Relation descriptor object.

dereference - true if the local DMO contains a reference to the foreign record, which must be dereferenced in the FQL query; false if the local DMO is the foreign record, referenced by the inverse DMO.

Returns:

The list of appropriate FQL types, or null if no query substitution parameters are used for this join.

setup

protected void setup(RecordBuffer local,
                     RecordBuffer inverse,
                     RelationInfo info,
                     boolean dereference)

Perform any additional setup necessary for a particular join helper implementation. This base implementation does nothing.

Parameters:

local - Local record buffer (the referring end of the join).

inverse - Inverse record buffer (the referent end of the join).

info - Relation descriptor object.

dereference - true if the local DMO contains a reference to the foreign record, which must be dereferenced in the FQL query; false if the local DMO is the foreign record, referenced by the inverse DMO.

raiseJoinError

protected void raiseJoinError(RecordBuffer left,
                              RecordBuffer right,
                              boolean parentIsPersistent)

Throw ErrorConditionException that signals that the specified tables cannot be joined.

Parameters:

left - Record buffer which represents the left table in the join.

right - Record buffer which represents the right table in the join.

parentIsPersistent - Depending on this parameter, a specific error is raised: if true then error 230, otherwise the pair 855 and 1832 are raised.

Throws:

ErrorConditionException - If parentIsPersistent then error 230, containing the text '<Table1> of <Table2>'. Index fields of table 1 must be fields in table 2.. Otherwise, Unknown database name . and ** Workfile names cannot have database qualifiers. are raised.

getParameters

java.util.List<java.io.Serializable> getParameters()

Get the values of DMO instance fields or the DMO instance itself which will be used as the query substitution parameter(s). This base implementation returns null. Subclasses which need a parameter must override this method.

Returns:

null.

getInverseInterface

java.lang.Class<? extends DataModelObject> getInverseInterface()

Get the DMO interface for the inverse (non-local) end of the join.

Returns:

Inverse DMO interface.

getFQL

FQLExpression[][] getFQL()

Get the FQLs for the where clause snippet used to perform the join. Since this part of the predicate will nnt be preprocessed using FQLPreprocessor and the join fields of the inverse may contain unknown values, a bi-dimensional array of clauses are used. The first dimension is the size of the join (aka the number of fields paired) and the second is always two: the first (0) is used when the joined field is null and the second (1) is used when the join field is not unknown.

The enclosing query embeds these phrases into the overall FQL statement before executing the query based on the actual values of the inverse buffer.

Returns:

FQL where clause snippets used to perform the join. A bi-dimensional array of clauses are used. The first dimension is the size of the join (aka the number of fields paired) and the second is always two: the first (NULL_FIELD) is used when the joined field is null and the second (NOT_NULL_FIELD) is used when the join field is not unknown.

getParameterTypes

java.util.List<FqlType> getParameterTypes()

Get the type of the query substitution parameters, if any, which was determined at construction.

Returns:

The list of appropriate Hibernate types, or null if no query substitution parameters are used for this join.