Purpose: Allows customization of an object's inheritance.
The primary supported inheritance model uses a class type indicator
column in the table that stores the object's class type.
The class-to-type mapping is specified on this policy.
The full class name can also be used for the indicator instead of the mapping.

Each subclass can either share their parents table, or in addition add their
own table(s).

For legacy models a customized inheritance class-extractor can be provided.
This allows Java code to be used to compute the class type to use for a row.
When this customized inheritance model is used an only-instances and with-all-subclasses
filter expression may be required for concrete and branch querying.

classFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord rowFromDatabase,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
This method is invoked only for the abstract descriptors.

java.lang.Class

classFromValue(java.lang.Object classFieldValue,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
This method is used to turn the a raw database field value classFieldValue into a Class object.

getDescribesNonPersistentSubclasses()
ADVANCED:
Determines whether the descriptors using this inheritance policy
should be used as descriptors for subclasses of the classes they
describe if those subclasses do not have their own descriptor
e.g.

initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
Initialized the inheritance properties of the descriptor once the mappings are initialized.

protected void

initializeClassExtractor(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:
Setup the default classExtractionMethod, or if one was specified by the user make sure it is valid.

setDescribesNonPersistentSubclasses(boolean describesNonPersistentSubclasses)
ADVANCED:
Determines whether the descriptors using this inheritance policy
should be used as descriptors for subclasses of the classes they
describe if those subclasses do not have their own descriptor
e.g.

setReadAllSubclassesView(org.eclipse.persistence.internal.helper.DatabaseTable readAllSubclassesView)
INTERNAL:
The view can be used to optimize/customize the query for all subclasses where they have multiple tables.

void

setReadAllSubclassesViewName(java.lang.String readAllSubclassesViewName)
ADVANCED:
The view can be used to optimize/customize the query for all subclasses where they have multiple tables.

setUseDescriptorsToValidateInheritedObjects(boolean useDescriptorsToValidateInheritedObjects)
INTERNAL:
Sets if we should use the descriptor inheritance to determine
if an object can be returned from the identity map or not.

addClassIndicator

PUBLIC:
Add a class indicator for the root classes subclass.
The indicator is used to determine the class to use for a row read from the database,
and to query only instances of a class from the database.
Every concrete persistent subclass must have a single unique indicator defined for it.
If the root class is concrete then it must also define an indicator.
Only the root class's descriptor of the entire inheritance hierarchy can define the class indicator mapping.

addClassIndicatorFieldToInsertRow

INTERNAL:
Add abstract class indicator information to the database row. This is
required when building a row for an insert or an update of a concrete child
descriptor.
This is only used to build a template row.

classFromValue

INTERNAL:
This method is used to turn the a raw database field value classFieldValue into a Class object. Used to determine
which class objects to build from database results, and for class type expression

clone

convertClassNamesToClasses

INTERNAL:
Convert all the class-name-based settings in this InheritancePolicy to actual class-based settings.
This method is used when converting a project that has been built with class names to a project with classes.
It will also convert referenced classes to the versions of the classes from the classLoader.

dontReadSubclassesOnQueries

public void dontReadSubclassesOnQueries()

PUBLIC:
Set the descriptor to only read instance of itself when queried.
This is used with inheritance to configure the result of queries.
By default this is true for root inheritance descriptors, and false for all others.

dontUseClassNameAsIndicator

public void dontUseClassNameAsIndicator()

PUBLIC:
Set the descriptor not to use the class' full name as the indicator.
The class indicator is used with inheritance to determine the class from a row.
By default a class indicator mapping is required, this can be set to true if usage of the class name is desired.
The field must be of a large enough size to store the fully qualified class name.

getAllChildClassIndicators

protected java.util.Vector getAllChildClassIndicators()

INTERNAL:
Stores class indicators for all child and children's children.
Used for queries on branch classes only.

getAllChildDescriptors

public java.util.Vector getAllChildDescriptors()

INTERNAL:
Returns all the child descriptors, even descriptors for subclasses of
subclasses.
Required for bug 3019934.

getChildrenTablesJoinExpressions

getChildrenJoinExpression

INTERNAL:
all expressions from childrenTablesJoinExpressions ANDed together

getAllTables

public java.util.Vector getAllTables()

INTERNAL:
all tables for reference class plus childrenTables

getChildDescriptors

public java.util.Vector getChildDescriptors()

INTERNAL:
Return all the immediate child descriptors. Only descriptors from
direct subclasses are returned.

getClassExtractionMethod

protected java.lang.reflect.Method getClassExtractionMethod()

INTERNAL:
Return all the classExtractionMethod

getClassExtractionMethodName

public java.lang.String getClassExtractionMethodName()

ADVANCED:
A class extraction method can be registered with the descriptor to override the default inheritance mechanism.
This allows for a user defined class indicator in place of providing an explicit class indicator field.
The method registered must be a static method on the class which has that descriptor. The method must take a
Record as an argument (for example, a DatabaseRecord), and must return the class to use for that record.
This method will be used to decide which class to instantiate when reading from the database.
It is the application's responsibility to populate any typing information in the database required
to determine the class from the record.
If this method is used, then the class indicator field and mapping cannot be used, and in addition,
the descriptor's withAllSubclasses and onlyInstances expressions must also be setup correctly.

getClassExtractor

ADVANCED:
A class extractor can be registered with the descriptor to override the default inheritance mechanism.
This allows for a user defined class indicator in place of providing an explicit class indicator field.
The instance registered must extend the ClassExtractor class and implement the extractClass(Map) method.
The method must take database row (a Record/Map) as an argument and must return the class to use for that row.
This method will be used to decide which class to instantiate when reading from the database.
It is the application's responsibility to populate any typing information in the database required
to determine the class from the row, such as usage of a direct or transformation mapping for the type fields.
If this method is used then the class indicator field and mapping cannot be used, and in addition,
the descriptor's withAllSubclasses and onlyInstances expressions must also be setup correctly.

setClassExtractor

ADVANCED:
A class extractor can be registered with the descriptor to override the default inheritance mechanism.
This allows for a user defined class indicator in place of providing an explicit class indicator field.
The instance registered must extend the ClassExtractor class and implement the extractClass(Map) method.
The method must take database row (a Record/Map) as an argument and must return the class to use for that row.
This method will be used to decide which class to instantiate when reading from the database.
It is the application's responsibility to populate any typing information in the database required
to determine the class from the row, such as usage of a direct or transformation mapping for the type fields.
If this method is used then the class indicator field and mapping cannot be used, and in addition,
the descriptor's withAllSubclasses and onlyInstances expressions must also be setup correctly.

getDescriptor

getDescribesNonPersistentSubclasses

public boolean getDescribesNonPersistentSubclasses()

ADVANCED:
Determines whether the descriptors using this inheritance policy
should be used as descriptors for subclasses of the classes they
describe if those subclasses do not have their own descriptor
e.g. If Employee.class has a descriptor and EmployeeSubClass does
not have a descriptor, if describesNonPersistenceSubclasses is true
Employee's descriptor will be used as the descriptor for Employee

getParentClassName

getParentDescriptor

getReadAllSubclassesView

public org.eclipse.persistence.internal.helper.DatabaseTable getReadAllSubclassesView()

INTERNAL:
The view can be used to optimize/customize the query for all subclasses where they have multiple tables.
This view can do the outer join, we require the view because we cannot generate dynamic platform independent SQL
for outer joins (i.e. not possible to do so either).

getReadAllSubclassesViewName

public java.lang.String getReadAllSubclassesViewName()

ADVANCED:
The view can be used to optimize/customize the query for all subclasses where they have multiple tables.
This view can use outer joins or unions to combine the results of selecting from all of the subclass tables.
If a view is not given then TopLink must make an individual call for each subclass.

readSubclassesOnQueries

public void readSubclassesOnQueries()

PUBLIC:
Set the descriptor to read instance of itself and its subclasses when queried.
This is used with inheritance to configure the result of queries.
By default this is true for root inheritance descriptors, and false for all others.

remoteInitialization

requiresMultipleTableSubclassRead

public boolean requiresMultipleTableSubclassRead()

INTERNAL:
Return if this descriptor has children that define additional tables and needs to read them.
This case requires a special read, because the query cannot be done through a single SQL call with normal joins.

selectAllRowUsingCustomMultipleTableSubclassRead

INTERNAL:
Select all rows from a abstract table descriptor.
This is accomplished by selecting for all of the concrete classes and then merging the rows.
This does not optimize using type select, as the type information is not known.

selectOneRowUsingCustomMultipleTableSubclassRead

INTERNAL:
Select one rows from a abstract table descriptor.
This is accomplished by selecting for all of the concrete classes until a row is found.
This does not optimize using type select, as the type information is not known.

setChildDescriptors

setClassExtractionMethodName

ADVANCED:
A class extraction method can be registered with the descriptor to override the default inheritance mechanism.
This allows for a user defined class indicator in place of providing an explicit class indicator field.
The method registered must be a static method on the class which has that descriptor. The method must take Record
as an argument (for example, a DatabaseRecord), and must return the class to use for that record.
This method will be used to decide which class to instantiate when reading from the database.
It is the application's responsibility to populate any typing information in the database required
to determine the class from the record.
If this method is used then the class indicator field and mapping cannot be used, and in addition,
the descriptor's withAllSubclasses and onlyInstances expressions must also be set up correctly.

setDescribesNonPersistentSubclasses

ADVANCED:
Determines whether the descriptors using this inheritance policy
should be used as descriptors for subclasses of the classes they
describe if those subclasses do not have their own descriptor
e.g. If Employee.class has a descriptor and EmployeeSubClass does
not have a descriptor, if describesNonPersistenceSubclasses is true
Employee's descriptor will be used as the descriptor for Employee

setJoinedStrategy

setOnlyInstancesExpression

ADVANCED:
Sets the expression used to select instance of the class only. Can be used to customize the
inheritance class indicator expression.

setParentClass

public void setParentClass(java.lang.Class parentClass)

PUBLIC:
Set the parent class.
A descriptor can inherit from another descriptor through defining it as its parent.
The root descriptor must define a class indicator field and mapping.
All children must share the same table as their parent but can add additional tables.
All children must share the root descriptor primary key.

setParentClassName

public void setParentClassName(java.lang.String parentClassName)

INTERNAL:
Set the parent class name, used by MW to avoid referencing the real class for
deployment XML generation.

setReadAllSubclassesView

INTERNAL:
The view can be used to optimize/customize the query for all subclasses where they have multiple tables.
This view can do the outer join, we require the view because we cannot generate dynamic platform independent SQL
for outer joins (i.e. not possible to do so either).

setReadAllSubclassesViewName

ADVANCED:
The view can be used to optimize/customize the query for all subclasses where they have multiple tables.
This view can use outer joins or unions to combine the results of selecting from all of the subclass tables.
If a view is not given then TopLink must make an individual call for each subclass.

setShouldReadSubclasses

INTERNAL:
Set the descriptor to read instance of itself and its subclasses when queried.
This is used with inheritance to configure the result of queries.
By default this is true for root inheritance descriptors, and false for all others.

setShouldReadSubclasses

public void setShouldReadSubclasses(boolean shouldReadSubclasses)

PUBLIC:
Set the descriptor to read instance of itself and its subclasses when queried.
This is used with inheritance to configure the result of queries.
By default this is true for root inheritance descriptors, and false for all others.

setShouldUseClassNameAsIndicator

PUBLIC:
Set if the descriptor uses the classes fully qualified name as the indicator.
The class indicator is used with inheritance to determine the class from a row.
By default a class indicator mapping is required, this can be set to true if usage of the class
name is desired.
The field must be of a large enough size to store the fully qualified class name.

setAlwaysUseOuterJoinForClassType

public void setAlwaysUseOuterJoinForClassType(boolean choice)

PUBLIC:
Sets the inheritance policy to always use an outer join when querying across a relationship of class.
used when using getAllowingNull(), or anyOfAllowingNone()

setSingleTableStrategy

public void setSingleTableStrategy()

INTERNAL:
Used to indicate a SINGLE_TABLE inheritance strategy. Since only JOINED and SINGLE_TABLE
strategies are supported at this time (no support for TABLE_PER_CLASS) using a
!isJoinedStrategy an an indicator for SINGLE_TABLE is sufficient.

setWithAllSubclassesExpression

ADVANCED:
Sets the expression to be used for querying for a class and all its subclasses. Can be used
to customize the inheritance class indicator expression.

shouldReadSubclasses

public boolean shouldReadSubclasses()

PUBLIC:
Return true if this descriptor should read instances of itself and subclasses on queries.

shouldReadSubclassesValue

public java.lang.Boolean shouldReadSubclassesValue()

INTERNAL:
Return true if this descriptor should read instances of itself and subclasses on queries.

shouldAlwaysUseOuterJoin

public boolean shouldAlwaysUseOuterJoin()

PUBLIC:
returns if the inheritance policy will always use an outerjoin when selecting class type

shouldOuterJoinSubclasses

public boolean shouldOuterJoinSubclasses()

PUBLIC:
Return if an outer join should be used to read subclasses.
By default a separate query is done for each subclass when querying for
a root or branch inheritance class that has subclasses that span multiple tables.

setShouldOuterJoinSubclasses

PUBLIC:
Set if an outer join should be used to read subclasses.
By default a separate query is done for each subclass when querying for
a root or branch inheritance class that has subclasses that span multiple tables.

shouldUseClassNameAsIndicator

public boolean shouldUseClassNameAsIndicator()

PUBLIC:
Return true if the descriptor use the classes full name as the indicator.
The class indicator is used with inheritance to determine the class from a row.
By default a class indicator mapping is required, this can be set to true if usage of the class
name is desired.
The field must be of a large enough size to store the fully qualified class name.

toString

public java.lang.String toString()

INTERNAL:

Overrides:

toString in class java.lang.Object

updateTables

protected void updateTables()

INTERNAL:
set the tables on the child descriptor
overridden in org.eclipse.persistence.internal.oxm.QNameInheritancePolicy

useClassNameAsIndicator

public void useClassNameAsIndicator()

PUBLIC:
Set the descriptor to use the classes full name as the indicator.
The class indicator is used with inheritance to determine the class from a row.
By default a class indicator mapping is required, this can be set to true if usage of the class
name is desired.
The field must be of a large enough size to store the fully qualified class name.