commonj.sdo

Interface ChangeSummary

public interface ChangeSummary

A change summary is used to record changes to DataObjects, allowing applications to efficiently and incrementally update back-end storage when required.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ChangeSummary.Setting A setting encapsulates a property and a corresponding single value of the property's type.

Method Summary

Modifier and Type	Method and Description
void	beginLogging() Clears the List of changes and turns change logging on.
void	endLogging() An implementation that requires logging may throw an UnsupportedOperationException.
List<DataObject>	getChangedDataObjects() Returns a list consisting of all the data objects that have been changed while logging.
DataGraph	getDataGraph() Returns the data graph associated with this change summary or null.
DataObject	getOldContainer(DataObject dataObject) Returns the value of the container data object at the point when logging began.
Property	getOldContainmentProperty(DataObject dataObject) Returns the value of the containment property data object property at the point when logging began.
Sequence	getOldSequence(DataObject dataObject) Returns the value of the sequence for the data object at the point when logging began.
ChangeSummary.Setting	getOldValue(DataObject dataObject, Property property) Returns a setting for the specified property representing the property value of the given dataObject at the point when logging began.
List<ChangeSummary.Setting>	getOldValues(DataObject dataObject) Returns a list of settings that represent the property values of the given dataObject at the point when logging began.
DataObject	getRootObject() Returns the ChangeSummary root DataObject - the object from which changes are tracked.
boolean	isCreated(DataObject dataObject) Returns whether or not the specified data object was created while logging.
boolean	isDeleted(DataObject dataObject) Returns whether or not the specified data object was deleted while logging.
boolean	isLogging() Indicates whether change logging is on (true) or off ( false).
boolean	isModified(DataObject dataObject) Returns whether or not the specified data object was updated while logging.
void	undoChanges() This method is intended for use by service implementations only.

Method Detail

isLogging

boolean isLogging()

Indicates whether change logging is on (true) or off ( false).

Returns:

true if change logging is on.

See Also:

beginLogging(), endLogging()

getDataGraph

DataGraph getDataGraph()

Returns the data graph associated with this change summary or null.

Returns:

the data graph.

See Also:

DataGraph.getChangeSummary()

getChangedDataObjects

List<DataObject> getChangedDataObjects()

Returns a list consisting of all the data objects that have been changed while logging.

The new and modified objects in the List are references to objects associated with this ChangeSummary. The deleted objects in the List are references to objects at the time that event logging was enabled;

Each changed object must have exactly one of the following methods return true: isCreated, isDeleted, or isModified.

Returns:

a list of changed data objects.

See Also:

isCreated(DataObject), isDeleted(DataObject), isModified(DataObject)

isCreated

boolean isCreated(DataObject dataObject)

Returns whether or not the specified data object was created while logging. Any object that was added to the scope but was not in the scope when logging began, will be considered created.

Parameters:

dataObject - the data object in question.

Returns:

true if the specified data object was created.

See Also:

getChangedDataObjects()

isDeleted

boolean isDeleted(DataObject dataObject)

Returns whether or not the specified data object was deleted while logging. Any object that is not in scope but was in scope when logging began will be considered deleted.

Parameters:

dataObject - the data object in question.

Returns:

true if the specified data object was deleted.

See Also:

getChangedDataObjects()

getOldValues

List<ChangeSummary.Setting> getOldValues(DataObject dataObject)

Returns a list of settings that represent the property values of the given dataObject at the point when logging began.

In the case of a deleted object, the List will include settings for all the Properties.

An old value setting indicates the value at the point logging begins. A setting is only produced for modified objects if either the old value differs from the current value or if the isSet differs from the current value.

No settings are produced for created objects.

Parameters:

dataObject - the object in question.

Returns:

a list of settings.

See Also:

getChangedDataObjects()

beginLogging

void beginLogging()

Clears the List of changes and turns change logging on. No operation occurs if logging is already on.

See Also:

endLogging(), isLogging()

endLogging

void endLogging()

An implementation that requires logging may throw an UnsupportedOperationException. Turns change logging off. No operation occurs if logging is already off.

See Also:

beginLogging(), isLogging()

isModified

boolean isModified(DataObject dataObject)

Returns whether or not the specified data object was updated while logging. An object that was contained in the scope when logging began and remains in the scope when logging ends will be considered potentially modified.

An object considered modified must have at least one old value setting.

Parameters:

dataObject - the data object in question.

Returns:

true if the specified data object was modified.

See Also:

getChangedDataObjects()

getRootObject

DataObject getRootObject()

Returns the ChangeSummary root DataObject - the object from which changes are tracked. When a DataGraph is used, this is the same as getDataGraph().getRootObject().

Returns:

the ChangeSummary root DataObject

getOldValue

ChangeSummary.Setting getOldValue(DataObject dataObject,
                                  Property property)

Returns a setting for the specified property representing the property value of the given dataObject at the point when logging began.

Returns null if the property was not modified and has not been deleted.

Parameters:

dataObject - the object in question.

property - the property of the object.

Returns:

the Setting for the specified property.

See Also:

getChangedDataObjects()

getOldContainer

DataObject getOldContainer(DataObject dataObject)

Returns the value of the container data object at the point when logging began.

Parameters:

dataObject - the object in question.

Returns:

the old container data object.

getOldContainmentProperty

Property getOldContainmentProperty(DataObject dataObject)

Returns the value of the containment property data object property at the point when logging began.

Parameters:

dataObject - the object in question.

Returns:

the old containment property.

getOldSequence

Sequence getOldSequence(DataObject dataObject)

Returns the value of the sequence for the data object at the point when logging began.

Parameters:

dataObject - the object in question.

Returns:

the old containment property.

undoChanges

void undoChanges()

This method is intended for use by service implementations only. Undoes all changes in the log to restore the tree of DataObjects to its original state when logging began. isLogging() is unchanged. The log is cleared.

See Also:

beginLogging(), endLogging(), isLogging()