org.eclipse.persistence.history
Class HistoryPolicy

java.lang.Object
  org.eclipse.persistence.history.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.

See Also:

Serialized Form

Author:

Stephen McRitchie

Since:

10

Field Summary

protected ClassDescriptor	descriptor
protected java.util.Vector	endFields
protected java.util.Vector	historicalTables
protected DatabaseMapping	mapping
protected boolean	shouldHandleWrites
protected java.util.Vector	startFields
protected boolean	usesLocalTime

Constructor Summary

HistoryPolicy()

Method Summary

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(org.eclipse.persistence.internal.expressions.ObjectExpression expression) INTERNAL: Add any temporal querying conditions to this object expression.
void	addStartFieldName(java.lang.String startFieldName) PUBLIC: Sets the name of the start field.
protected boolean	checkWastedVersioning(org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow, org.eclipse.persistence.internal.helper.DatabaseTable table) INTERNAL: Checks for the case where an object has multiple tables but only some are part of a minimal update.
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.
protected org.eclipse.persistence.internal.helper.DatabaseField	getEnd() INTERNAL:
protected org.eclipse.persistence.internal.helper.DatabaseField	getEnd(int i) INTERNAL:
java.lang.String	getEndFieldName() PUBLIC:
java.util.Vector	getEndFields() INTERNAL:
java.util.Vector	getHistoricalTables() INTERNAL:
java.util.Vector	getHistoryTableNames() PUBLIC:
DatabaseMapping	getMapping() PUBLIC:
long	getMinimumTimeIncrement(org.eclipse.persistence.internal.sessions.AbstractSession session) INTERNAL: Return a minimal time increment supported by the platform.
protected org.eclipse.persistence.internal.helper.DatabaseField	getStart() INTERNAL:
protected org.eclipse.persistence.internal.helper.DatabaseField	getStart(int i) INTERNAL:
java.lang.String	getStartFieldName() PUBLIC: Answers the name of the start field.
java.util.Vector	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:
protected void	setEndFields(java.util.Vector endFields) INTERNAL:
void	setEndFieldType(java.lang.String fieldName, java.lang.Class type) ADVANCED:
void	setHistoricalTables(java.util.Vector 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.
protected void	setStartFields(java.util.Vector startFields) INTERNAL:
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();
protected void	verifyTableQualifiers(org.eclipse.persistence.internal.databaseaccess.DatasourcePlatform platform) INTERNAL: Check that the qualifiers on the historical tables are properly set.

Methods inherited from class java.lang.Object

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

Field Detail

descriptor

protected ClassDescriptor descriptor

mapping

protected DatabaseMapping mapping

historicalTables

protected java.util.Vector historicalTables

startFields

protected java.util.Vector startFields

endFields

protected java.util.Vector endFields

shouldHandleWrites

protected boolean shouldHandleWrites

usesLocalTime

protected boolean usesLocalTime

Constructor Detail

HistoryPolicy

public HistoryPolicy()

Method Detail

additionalHistoryExpression

public Expression additionalHistoryExpression(org.eclipse.persistence.internal.expressions.ObjectExpression expression)

INTERNAL: Add any temporal querying conditions to this object expression.

clone

public java.lang.Object clone()

PUBLIC: Performs a sufficiently deep clone. Use to quickly setup standard policies on multiple descriptors.

Overrides:

clone in class java.lang.Object

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.Vector getHistoricalTables()

INTERNAL:

getHistoryTableNames

public java.util.Vector getHistoryTableNames()

PUBLIC:

getMapping

public DatabaseMapping getMapping()

PUBLIC:

getStart

protected org.eclipse.persistence.internal.helper.DatabaseField getStart()

INTERNAL:

getStart

protected org.eclipse.persistence.internal.helper.DatabaseField getStart(int i)

INTERNAL:

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.Vector getStartFields()

INTERNAL:

getEnd

protected org.eclipse.persistence.internal.helper.DatabaseField getEnd()

INTERNAL:

getEnd

protected org.eclipse.persistence.internal.helper.DatabaseField getEnd(int i)

INTERNAL:

getEndFieldName

public java.lang.String getEndFieldName()

PUBLIC:

getEndFields

public java.util.Vector 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.Vector historicalTables)

INTERNAL:

setMapping

public void setMapping(DatabaseMapping mapping)

INTERNAL:

setStartFields

protected void setStartFields(java.util.Vector startFields)

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.

setEndFields

protected void setEndFields(java.util.Vector endFields)

INTERNAL:

addEndFieldName

public void addEndFieldName(java.lang.String endFieldName)

PUBLIC:

See Also:

addStartFieldName(java.lang.String)

setEndFieldType

public void setEndFieldType(java.lang.String fieldName,
                            java.lang.Class type)

ADVANCED:

See Also:

setStartFieldType(java.lang.Class)

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()

useLocalTime

public void useLocalTime()

Answers if the Timestamp used in maintaining history should be System.currentTimeMillis();

See Also:

useDatabaseTime(), shouldUseLocalTime()

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()

verifyTableQualifiers

protected void verifyTableQualifiers(org.eclipse.persistence.internal.databaseaccess.DatasourcePlatform platform)

INTERNAL: Check that the qualifiers on the historical tables are properly set.

A similar method exists on ClassDescriptor.

checkWastedVersioning

protected boolean checkWastedVersioning(org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow,
                                        org.eclipse.persistence.internal.helper.DatabaseTable table)

INTERNAL: Checks for the case where an object has multiple tables but only some are part of a minimal update.

postDelete

public void postDelete(ModifyQuery deleteQuery)

INTERNAL:

postUpdate

public void postUpdate(ObjectLevelModifyQuery writeQuery)

INTERNAL:

postUpdate

public void postUpdate(ObjectLevelModifyQuery writeQuery,
                       boolean isShallow)

INTERNAL:

postInsert

public void postInsert(ObjectLevelModifyQuery writeQuery)

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.