Package 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
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
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`
`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`
`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 Details

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