Class HistoryPolicy

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

    public class HistoryPolicy
    extends java.lang.Object
    implements java.lang.Cloneable, java.io.Serializable
    Purpose:Expresses how historical data is saved on the data store.

    This information is used to both maintain a history of all objects modified through TopLink and to enable point in time querying.

    If Oracle 9R2 or later Flashback is used this policy is not required, as the preservation of history is automatic.

    Descriptors, ManyToManyMappings, DirectCollectionMappings, and DirectMapMappings only can have a history policy, as only they have associated database tables.

    Since:
    10
    Author:
    Stephen McRitchie
    See Also:
    Serialized Form
    • Constructor Summary

      Constructors 
      Constructor Description
      HistoryPolicy()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addEndFieldName​(java.lang.String endFieldName)
      PUBLIC:
      void addHistoryTableName​(java.lang.String name)
      PUBLIC: Use to specify the names of the mirroring historical tables.
      void addHistoryTableName​(java.lang.String sourceTableName, java.lang.String historyTableName)
      PUBLIC: Use to specify the names of the mirroring historical tables.
      Expression additionalHistoryExpression​(Expression context, Expression base)
      INTERNAL: Add any temporal querying conditions to this object expression.
      Expression additionalHistoryExpression​(Expression context, Expression base, java.lang.Integer tableIndex)
      INTERNAL: Add any temporal querying conditions to this object expression.
      void addStartFieldName​(java.lang.String startFieldName)
      PUBLIC: Sets the name of the start field.
      java.lang.Object clone()
      PUBLIC: Performs a sufficiently deep clone.
      java.lang.Object getCurrentTime​(org.eclipse.persistence.internal.sessions.AbstractSession session)
      PUBLIC: Whenever a historical record is logically deleted (updated) or inserted, the end and start fields respectively will be set to this value.
      ClassDescriptor getDescriptor()
      PUBLIC: Return the descriptor of the policy.
      java.lang.String getEndFieldName()
      PUBLIC:
      java.util.List<org.eclipse.persistence.internal.helper.DatabaseField> getEndFields()
      INTERNAL:
      java.util.List<org.eclipse.persistence.internal.helper.DatabaseTable> getHistoricalTables()
      INTERNAL:
      java.util.List<java.lang.String> getHistoryTableNames()
      PUBLIC:
      DatabaseMapping getMapping()
      PUBLIC:
      long getMinimumTimeIncrement​(org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Return a minimal time increment supported by the platform.
      java.lang.String getStartFieldName()
      PUBLIC: Answers the name of the start field.
      java.util.List<org.eclipse.persistence.internal.helper.DatabaseField> getStartFields()
      INTERNAL:
      void initialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Initialize a HistoryPolicy.
      void logicalDelete​(ModifyQuery writeQuery, boolean isUpdate)
      INTERNAL: Performs a logical delete (update) on the historical schema.
      void logicalDelete​(ModifyQuery writeQuery, boolean isUpdate, boolean isShallow)
      INTERNAL: Performs a logical delete (update) on the historical schema.
      void logicalInsert​(ObjectLevelModifyQuery writeQuery, boolean isUpdate)
      INTERNAL: Perform a logical insert into the historical schema, creating a new version of an object.
      void mappingLogicalDelete​(ModifyQuery originalQuery, org.eclipse.persistence.internal.sessions.AbstractRecord arguments, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Performs a logical delete (update) on the historical schema.
      void mappingLogicalInsert​(DataModifyQuery originalQuery, org.eclipse.persistence.internal.sessions.AbstractRecord arguments, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Performs a logical insert into the historical schema.
      void postDelete​(ModifyQuery deleteQuery)
      INTERNAL:
      void postInsert​(ObjectLevelModifyQuery writeQuery)
      INTERNAL:
      void postUpdate​(ObjectLevelModifyQuery writeQuery)
      INTERNAL:
      void postUpdate​(ObjectLevelModifyQuery writeQuery, boolean isShallow)
      INTERNAL:
      void setDescriptor​(ClassDescriptor descriptor)
      PUBLIC:
      void setEndFieldType​(java.lang.String fieldName, java.lang.Class type)
      ADVANCED:
      void setHistoricalTables​(java.util.List<org.eclipse.persistence.internal.helper.DatabaseTable> historicalTables)
      INTERNAL:
      void setMapping​(DatabaseMapping mapping)
      INTERNAL:
      void setShouldHandleWrites​(boolean value)
      Sets if TopLink is responsible for writing history.
      void setShouldUseDatabaseTime​(boolean value)
      Sets if the Timestamp used in maintainaing history should be the current time according to the database.
      void setStartFieldType​(java.lang.Class type)
      ADVANCED: Sets the type of all start fields.
      boolean shouldHandleWrites()
      Answers if TopLink is responsible for writing history.
      boolean shouldUseDatabaseTime()
      Answers if the Timestamp used in maintaining history should be the current time according to the database.
      boolean shouldUseLocalTime()
      Answers if the Timestamp used in maintaining history should be System.currentTimeMillis();
      void useDatabaseTime()
      Answers if the Timestamp used in maintaining history should be the current time according to the database.
      void useLocalTime()
      Answers if the Timestamp used in maintaining history should be System.currentTimeMillis();
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • HistoryPolicy

        public HistoryPolicy()
    • Method Detail

      • additionalHistoryExpression

        public Expression additionalHistoryExpression​(Expression context,
                                                      Expression base)
        INTERNAL: Add any temporal querying conditions to this object expression.
      • additionalHistoryExpression

        public Expression additionalHistoryExpression​(Expression context,
                                                      Expression base,
                                                      java.lang.Integer tableIndex)
        INTERNAL: Add any temporal querying conditions to this object expression.
        Parameters:
        tableIndex - not null indicates that only expression for a single table should be returned.
      • clone

        public java.lang.Object clone()
        PUBLIC: Performs a sufficiently deep clone. Use to quickly setup standard policies on multiple descriptors.
      • getCurrentTime

        public java.lang.Object getCurrentTime​(org.eclipse.persistence.internal.sessions.AbstractSession session)
        PUBLIC: Whenever a historical record is logically deleted (updated) or inserted, the end and start fields respectively will be set to this value.
      • getMinimumTimeIncrement

        public long getMinimumTimeIncrement​(org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Return a minimal time increment supported by the platform.
      • getDescriptor

        public ClassDescriptor getDescriptor()
        PUBLIC: Return the descriptor of the policy.
      • getHistoricalTables

        public final java.util.List<org.eclipse.persistence.internal.helper.DatabaseTable> getHistoricalTables()
        INTERNAL:
      • getHistoryTableNames

        public java.util.List<java.lang.String> getHistoryTableNames()
        PUBLIC:
      • getStartFieldName

        public java.lang.String getStartFieldName()
        PUBLIC: Answers the name of the start field. Assumes that multiple tables for a descriptor have the same field names.
      • getStartFields

        public java.util.List<org.eclipse.persistence.internal.helper.DatabaseField> getStartFields()
        INTERNAL:
      • getEndFieldName

        public java.lang.String getEndFieldName()
        PUBLIC:
      • getEndFields

        public java.util.List<org.eclipse.persistence.internal.helper.DatabaseField> getEndFields()
        INTERNAL:
      • setDescriptor

        public void setDescriptor​(ClassDescriptor descriptor)
        PUBLIC:
      • initialize

        public void initialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Initialize a HistoryPolicy.
      • addHistoryTableName

        public void addHistoryTableName​(java.lang.String name)
        PUBLIC: Use to specify the names of the mirroring historical tables.

        Assumes that the order in which tables are added with descriptor.addTableName() matches the order in which mirroring historical tables are added with descriptor.addHistoryTableName().

      • addHistoryTableName

        public void addHistoryTableName​(java.lang.String sourceTableName,
                                        java.lang.String historyTableName)
        PUBLIC: Use to specify the names of the mirroring historical tables.

        Explicitly states that sourceTableName is mirrored by history table historyTableName. The order in which tables are added with descriptor.addTableName() should still match the order in which mirroring historical tables are added with descriptor.addMirroringHistoryTableName().

      • setHistoricalTables

        public void setHistoricalTables​(java.util.List<org.eclipse.persistence.internal.helper.DatabaseTable> historicalTables)
        INTERNAL:
      • setMapping

        public void setMapping​(DatabaseMapping mapping)
        INTERNAL:
      • addStartFieldName

        public void addStartFieldName​(java.lang.String startFieldName)
        PUBLIC: Sets the name of the start field.

        By default all tables belonging to a descriptor have the same primary key field names, and so the same start field names also.

        However, if startFieldName is qualified, i.e. of the form "EMPLOYEE_HIST.EMP_START", then this call will only set the start field name for a single historical table.

      • setStartFieldType

        public void setStartFieldType​(java.lang.Class type)
        ADVANCED: Sets the type of all start fields. Not required to be set as the default of Timestamp is assumed.
      • setShouldHandleWrites

        public void setShouldHandleWrites​(boolean value)
        Sets if TopLink is responsible for writing history.

        If history is maintained via low level database triggers or application logic a policy is still needed for point in time querying.

        If Oracle flashback is used no HistoryPolicy is needed.

        Setting this to false lets you use History for many other applications. For instance a table that tracks available flights or hotel deals may benefit from a HistoryPolicy just to simplify temporal querying.

        If all hotel discounts have a start and end date, you could query on all discounts available at a certain date.

      • shouldHandleWrites

        public boolean shouldHandleWrites()
        Answers if TopLink is responsible for writing history.

        If history is maintained via low level database triggers or application logic a policy is still usefull for point in time querying.

        If Oracle flashback is used no HistoryPolicy is needed.

        Returns:
        true by default
        See Also:
        setShouldHandleWrites(boolean)
      • setShouldUseDatabaseTime

        public void setShouldUseDatabaseTime​(boolean value)
        Sets if the Timestamp used in maintainaing history should be the current time according to the database.
        Parameters:
        value - if false uses localTime (default) instead
      • shouldUseLocalTime

        public boolean shouldUseLocalTime()
        Answers if the Timestamp used in maintaining history should be System.currentTimeMillis();
        Returns:
        true by default
        See Also:
        shouldUseDatabaseTime(), useLocalTime()
      • shouldUseDatabaseTime

        public boolean shouldUseDatabaseTime()
        Answers if the Timestamp used in maintaining history should be the current time according to the database.
        Returns:
        false by default
        See Also:
        shouldUseLocalTime(), useDatabaseTime()
      • useDatabaseTime

        public void useDatabaseTime()
        Answers if the Timestamp used in maintaining history should be the current time according to the database.
        See Also:
        useLocalTime(), shouldUseDatabaseTime()
      • postDelete

        public void postDelete​(ModifyQuery deleteQuery)
        INTERNAL:
      • logicalInsert

        public void logicalInsert​(ObjectLevelModifyQuery writeQuery,
                                  boolean isUpdate)
        INTERNAL: Perform a logical insert into the historical schema, creating a new version of an object.

        Called by postInsert() and also postUpdate() (which first does a logicalDelete of the previous version).

      • mappingLogicalInsert

        public void mappingLogicalInsert​(DataModifyQuery originalQuery,
                                         org.eclipse.persistence.internal.sessions.AbstractRecord arguments,
                                         org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Performs a logical insert into the historical schema. Direct collections and many to many mappings are maintained through the session events.
      • logicalDelete

        public void logicalDelete​(ModifyQuery writeQuery,
                                  boolean isUpdate)
        INTERNAL: Performs a logical delete (update) on the historical schema.
      • logicalDelete

        public void logicalDelete​(ModifyQuery writeQuery,
                                  boolean isUpdate,
                                  boolean isShallow)
        INTERNAL: Performs a logical delete (update) on the historical schema.
      • mappingLogicalDelete

        public void mappingLogicalDelete​(ModifyQuery originalQuery,
                                         org.eclipse.persistence.internal.sessions.AbstractRecord arguments,
                                         org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Performs a logical delete (update) on the historical schema. Direct collections and many to many mappings are maintained through the session events.