oracle.javatools.db.event

Class DBObjectChange

java.lang.Object

oracle.javatools.db.event.DBObjectChange

Direct Known Subclasses:

DBObjectChange

public class DBObjectChange
extends java.lang.Object

A DBObjectChange is used to notify of changes to a DBObject. It is passed to any appropriate listeners when the provider creates, updates or removes objects. A DBObjectChange is not limited to one type of change, it can contain multiple changes (e.g. children removed as well as children added). A DBObjectChange can include changes to child objects as well through the getOwnedObjectsChanged() method.

Since:

11.1.2.0.0

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	NAME_PROPERTY Key for the property map to see if an object's name has been changed.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DBObjectChange(DBObject obj, DBObjectProvider pro)

Method Summary

Modifier and Type	Method and Description
void	ensureProvider(DBObjectProvider pro) Ensures the DBObjectProvider that the changed object is from is set on this change.
static void	fireChildrenAdded(DBObject obj, java.util.List added) Fires a message that children have been added to the given object.
static void	fireChildrenRemoved(DBObject obj, java.util.List removed) Fires a message that children have been removed from the given object.
static void	fireObjectUpdated(DBObject obj) Fires an empty change message on the given object.
static void	fireObjectUpdated(DBObject obj, java.util.List<DBObject> added, java.util.List<DBObject> removed, java.util.Map<java.lang.String,java.beans.PropertyChangeEvent> props) Fires a compound event with added/removed children and changed properties.
static void	firePropertiesChanged(DBObject obj, java.util.Map<java.lang.String,java.beans.PropertyChangeEvent> props) Fires a message that the given properties have been changed on an object.
static void	firePropertyChanged(DBObject obj, java.beans.PropertyChangeEvent... pces) Fires a message that the given properties have been changed on an object.
java.util.Collection<java.lang.String>	getAllChangedProperties() Gets a list of all the properties that have changed in this event.
DBObject	getDBObject() Gets the object this change has been on.
java.util.List<DBObject>	getOwnedObjectsAdded() Returns any owned objects added to the DBObject as a result of the change.
java.util.List<DBObject>	getOwnedObjectsRemoved() Returns any owned objects removed from the DBObject as a result of the change.
java.util.Map<DBObject,DBObjectChange>	getOwnedObjectsUpdated() Returns any changes that have happened to any owned objects.
java.util.Collection<DBObjectChange>	getOwnedObjectsUpdated(java.lang.String childPropName) Gets the changes for any owned object updates for the given property name.
DBObjectChange	getOwnedObjectUpdate(DBObject child) Gets the change for a particular owned DBObject.
java.util.Map<java.lang.String,java.beans.PropertyChangeEvent>	getPropertiesChanged() Returns any properties changed on the DBObject as a result of the change.
java.beans.PropertyChangeEvent	getPropertyChange(java.lang.String propertyName) Gets the PropertyChangeEvent for the given property name.
DBObjectProvider	getProvider() Gets the DBObjectProvider that the changed object is from.
boolean	hasNameChanged() Convinience method to identify whether the "name" property has been changed - looks in the properties changed map for the property as a key.
static DBObjectChange	merge(DBObjectChange... changes) Merges two changes into a single change.

Methods inherited from class java.lang.Object

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

Field Detail

NAME_PROPERTY

public static final java.lang.String NAME_PROPERTY

Key for the property map to see if an object's name has been changed. This is a convinience member that simple equates to Property.name.

See Also:

hasNameChanged(), Property.name, Constant Field Values

Constructor Detail

DBObjectChange

protected DBObjectChange(DBObject obj,
                         DBObjectProvider pro)

Method Detail

getProvider

public final DBObjectProvider getProvider()

Gets the DBObjectProvider that the changed object is from. This can be null as DBObjectChange events can be fired on isolated objects. This method is only guarenteed to return a DBObjectProvider if the DBObjectChange is being passed to a listener registered with that DBObjectProvider.

Returns:

the DBObjectProvider containing the changed object.

ensureProvider

public final void ensureProvider(DBObjectProvider pro)

Ensures the DBObjectProvider that the changed object is from is set on this change. If this change already has a provider this method does nothing.

Parameters:

the - DBObjectProvider containing the changed object.

getDBObject

public final DBObject getDBObject()

Gets the object this change has been on.

getOwnedObjectsAdded

public java.util.List<DBObject> getOwnedObjectsAdded()

Returns any owned objects added to the DBObject as a result of the change.

getOwnedObjectsRemoved

public java.util.List<DBObject> getOwnedObjectsRemoved()

Returns any owned objects removed from the DBObject as a result of the change.

getPropertiesChanged

public java.util.Map<java.lang.String,java.beans.PropertyChangeEvent> getPropertiesChanged()

Returns any properties changed on the DBObject as a result of the change. The key is the property name and the value a PropertyChangeEvent.

If you require information about a specific property it is better to call getPropertyChange(String) as that won't initialise the change events for all properties.

Note: changes to properties on owned objects will not cause a PropertyChangeEvent on the parent (because the property value for the parent has not changed). Check getOwnedObjectsUpdated() to see whether an existing child object's properties have changed.

See Also:

getPropertyChange(String)

getPropertyChange

public java.beans.PropertyChangeEvent getPropertyChange(java.lang.String propertyName)

Gets the PropertyChangeEvent for the given property name. If the property hasn't been changed, null is returned.

Note: changes to properties on owned objects will not cause a PropertyChangeEvent on the parent (because the property value for the parent has not changed). Check getOwnedObjectsUpdated() to see whether an existing child object's properties have changed.

See Also:

getPropertiesChanged()

getOwnedObjectsUpdated

public java.util.Map<DBObject,DBObjectChange> getOwnedObjectsUpdated()

Returns any changes that have happened to any owned objects. The key is the owned object, and the value a DBObjectChange.

To check for an update to a specific, known, child use getOwnedObjectUpdate(DBObject).

It should be safe to call contains/get with a DBObject on the returned Map. Implementations should ensure that they use a Map implementation that does not do unnecessary comparison (e.g. IdentityHashMap).

getOwnedObjectUpdate

public DBObjectChange getOwnedObjectUpdate(DBObject child)

Gets the change for a particular owned DBObject.

Parameters:

child - the child to get the change for

Returns:

the change for the given owned object, or null if the owned object has not changed.

See Also:

getOwnedObjectsUpdated(), #getOwnedObjectUpdate(String)

getOwnedObjectsUpdated

public java.util.Collection<DBObjectChange> getOwnedObjectsUpdated(java.lang.String childPropName)

Gets the changes for any owned object updates for the given property name. For an update to a single child property there will be a single change in the returned collection. For a child list property there will be a change in the returned collection for every child that has been updated.

Parameters:

childPropName - the name of the child property for owned object changes.

Returns:

the changes associated with the given property name, or an empty array if there are none.

getAllChangedProperties

public java.util.Collection<java.lang.String> getAllChangedProperties()

Gets a list of all the properties that have changed in this event. This includes owned objects that have been updated as well as simple properties that have been changed.

Returns:

all the changed property names.

hasNameChanged

public boolean hasNameChanged()

Convinience method to identify whether the "name" property has been changed - looks in the properties changed map for the property as a key.

See Also:

NAME_PROPERTY

merge

public static DBObjectChange merge(DBObjectChange... changes)

Merges two changes into a single change. None of the given changes will be modified, the result will be a new change. At least two changes must be provided, and no change can be null. The changes must all be for the same DBObject instance, and the same DBObjectProvider.

Parameters:

changes - the changes to merge

Returns:

a new change with all the changes from both argument merged.

Throws:

java.lang.IllegalArgumentException - if no changes are provided, or if the merged changes are for different objects, or objects from different providers.

fireObjectUpdated

public static void fireObjectUpdated(DBObject obj)

Fires an empty change message on the given object. Where possible use a more specific message.

See Also:

fireChildrenAdded(oracle.javatools.db.DBObject, java.util.List), fireChildrenRemoved(oracle.javatools.db.DBObject, java.util.List), firePropertiesChanged(oracle.javatools.db.DBObject, java.util.Map<java.lang.String, java.beans.PropertyChangeEvent>)

fireChildrenAdded

public static void fireChildrenAdded(DBObject obj,
                                     java.util.List added)

Fires a message that children have been added to the given object.

fireChildrenRemoved

public static void fireChildrenRemoved(DBObject obj,
                                       java.util.List removed)

Fires a message that children have been removed from the given object.

firePropertyChanged

public static void firePropertyChanged(DBObject obj,
                                       java.beans.PropertyChangeEvent... pces)

Fires a message that the given properties have been changed on an object.

firePropertiesChanged

public static void firePropertiesChanged(DBObject obj,
                                         java.util.Map<java.lang.String,java.beans.PropertyChangeEvent> props)

Fires a message that the given properties have been changed on an object.

fireObjectUpdated

public static void fireObjectUpdated(DBObject obj,
                                     java.util.List<DBObject> added,
                                     java.util.List<DBObject> removed,
                                     java.util.Map<java.lang.String,java.beans.PropertyChangeEvent> props)

Fires a compound event with added/removed children and changed properties.