Oracle Fusion Middleware Java API Reference for Oracle TopLink
11g Release 1 (11.1.1)

B32476-03

oracle.toplink.descriptors
Class InheritancePolicy

java.lang.Object
  extended by oracle.toplink.descriptors.InheritancePolicy
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public class InheritancePolicy
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

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.

See Also:
Serialized Form

Method Summary
 void addClassIndicator(java.lang.Class childClass, java.lang.Object typeValue)
          Add a class indicator for the root classes subclass.
 void dontReadSubclassesOnQueries()
          Set the descriptor to only read instance of itself when queried.
 void dontUseClassNameAsIndicator()
          Set the descriptor not to use the class' full name as the indicator.
 java.lang.String getClassExtractionMethodName()
          ADVANCED: A class extraction method can be registered with the descriptor to override the default inheritance mechanism.
 ClassExtractor getClassExtractor()
          ADVANCED: A class extractor can be registered with the descriptor to override the default inheritance mechanism.
 java.lang.String getClassIndicatorFieldName()
          Return the class indicator field name.
 Expression getOnlyInstancesExpression()
          ADVANCED: Return the 'only instances expression'.
 java.lang.Class getParentClass()
          Return the parent class.
 java.lang.String getReadAllSubclassesViewName()
          ADVANCED: The view can be used to optimize/customize the query for all subclasses where they have multiple tables.
 Expression getWithAllSubclassesExpression()
          ADVANCED: Return the Expression which gets all subclasses.
 void readSubclassesOnQueries()
          Set the descriptor to read instance of itself and its subclasses when queried.
 void setAlwaysUseOuterJoinForClassType(boolean choice)
          Sets the inheritance policy to always use an outer join when quering across a relationship of class.
 void setClassExtractionMethodName(java.lang.String staticClassClassExtractionMethod)
          ADVANCED: A class extraction method can be registered with the descriptor to override the default inheritance mechanism.
 void setClassExtractor(ClassExtractor classExtractor)
          ADVANCED: A class extractor can be registered with the descriptor to override the default inheritance mechanism.
 void setClassIndicatorField(DatabaseField classIndicatorField)
          ADVANCED: To set the class indicator field.
 void setClassIndicatorFieldName(java.lang.String fieldName)
          To set the class indicator field name.
 void setClassIndicatorMapping(java.util.Map classIndicatorMapping)
          Set the association of indicators and classes.
 void setOnlyInstancesExpression(Expression onlyInstancesExpression)
          ADVANCED: Sets the expression used to select instance of the class only.
 void setParentClass(java.lang.Class parentClass)
          Set the parent class.
 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.
 void setShouldOuterJoinSubclasses(boolean shouldOuterJoinSubclasses)
          Set if an outer join should be used to read subclasses.
 void setShouldReadSubclasses(boolean shouldReadSubclasses)
          Set the descriptor to read instance of itself and its subclasses when queried.
 void setShouldUseClassNameAsIndicator(boolean shouldUseClassNameAsIndicator)
          Set if the descriptor uses the classes fully qualified name as the indicator.
 void setWithAllSubclassesExpression(Expression withAllSubclassesExpression)
          ADVANCED: Sets the expression to be used for querying for a class and all its subclasses.
 boolean shouldAlwaysUseOuterJoin()
          returns if the inheritance policy will always use an outerjoin when selecting class type
 boolean shouldOuterJoinSubclasses()
          Return if an outer join should be used to read subclasses.
 boolean shouldReadSubclasses()
          Return true if this descriptor should read instances of itself and subclasses on queries.
 boolean shouldUseClassNameAsIndicator()
          Return true if the descriptor use the classes full name as the indicator.
 void useClassNameAsIndicator()
          Set the descriptor to use the classes full name as the indicator.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

addClassIndicator

public void addClassIndicator(java.lang.Class childClass,
                              java.lang.Object typeValue)
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.


dontReadSubclassesOnQueries

public void dontReadSubclassesOnQueries()
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()
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.


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 responsiblity 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.

See Also:
setWithAllSubclassesExpression(Expression), setOnlyInstancesExpression(Expression)

getClassExtractor

public ClassExtractor 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 responsiblity 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.

See Also:
setWithAllSubclassesExpression(Expression), setOnlyInstancesExpression(Expression)

setClassExtractor

public void setClassExtractor(ClassExtractor classExtractor)
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 responsiblity 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.

See Also:
setWithAllSubclassesExpression(Expression), setOnlyInstancesExpression(Expression)

getClassIndicatorFieldName

public java.lang.String getClassIndicatorFieldName()
Return the class indicator field name. This is the name of the field in the table that stores what type of object this is.


getOnlyInstancesExpression

public Expression getOnlyInstancesExpression()
ADVANCED: Return the 'only instances expression'.


getParentClass

public java.lang.Class getParentClass()
Return the parent class.


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.


getWithAllSubclassesExpression

public Expression getWithAllSubclassesExpression()
ADVANCED: Return the Expression which gets all subclasses.


readSubclassesOnQueries

public void readSubclassesOnQueries()
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.


setClassExtractionMethodName

public void setClassExtractionMethodName(java.lang.String staticClassClassExtractionMethod)
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 responsiblity 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.

See Also:
setWithAllSubclassesExpression(Expression), setOnlyInstancesExpression(Expression)

setClassIndicatorField

public void setClassIndicatorField(DatabaseField classIndicatorField)
ADVANCED: To set the class indicator field. This can be used for advanced field types, such as XML nodes, or to set the field type.


setClassIndicatorFieldName

public void setClassIndicatorFieldName(java.lang.String fieldName)
To set the class indicator field name. This is the name of the field in the table that stores what type of object this is.


setClassIndicatorMapping

public void setClassIndicatorMapping(java.util.Map classIndicatorMapping)
Set the association of indicators and classes. This may be desired to be used by clients in strange inheritence models.


setOnlyInstancesExpression

public void setOnlyInstancesExpression(Expression onlyInstancesExpression)
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)
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.


setReadAllSubclassesViewName

public 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. 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

public void setShouldReadSubclasses(boolean shouldReadSubclasses)
Set the descriptor to read instance of itself and its subclasses when queried. This is used with inheritence to configure the result of queries. By default this is true for root inheritence descriptors, and false for all others.


setShouldUseClassNameAsIndicator

public void setShouldUseClassNameAsIndicator(boolean shouldUseClassNameAsIndicator)
Set if the descriptor uses the classes fully qualified name as the indicator. The class indicator is used with inheritence 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)
Sets the inheritance policy to always use an outer join when quering across a relationship of class. used when using getAllowingNull(), or anyOfAllowingNone()


setWithAllSubclassesExpression

public void setWithAllSubclassesExpression(Expression withAllSubclassesExpression)
ADVANCED: Sets the expression to be used for querying for a class and all its subclasses. Can be used to customize the inheritence class indicator expression.


shouldReadSubclasses

public boolean shouldReadSubclasses()
Return true if this descriptor should read instances of itself and subclasses on queries.


shouldAlwaysUseOuterJoin

public boolean shouldAlwaysUseOuterJoin()
returns if the inheritance policy will always use an outerjoin when selecting class type


shouldOuterJoinSubclasses

public boolean shouldOuterJoinSubclasses()
Return if an outer join should be used to read subclasses. By default a seperate query is done for each subclass when querying for a root or branch inheritance class that has subclasses that span multiple tables.


setShouldOuterJoinSubclasses

public void setShouldOuterJoinSubclasses(boolean shouldOuterJoinSubclasses)
Set if an outer join should be used to read subclasses. By default a seperate 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()
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.


useClassNameAsIndicator

public void useClassNameAsIndicator()
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.


Copyright © 1998, 2010, Oracle. All Rights Reserved.