oracle.ide.addin
Class UpdateMessage

java.lang.Object
  oracle.ide.addin.Message
      oracle.ide.addin.UpdateMessage

Direct Known Subclasses:

DBObjectUpdateMessage, RenameMessage

public class UpdateMessage

extends Message

The UpdateMessage class is the update message send to an Observer to notify it about a Subject change.

An update message consists of four lists: add, remove, modify, and container lists. A subject simply includes all applicable change information in one or more update messages.

This class also defines a set of constants identifying specific changes, such as:

• CHILD_REMOVED -- Indicates that children of a container object has been removed.
• CHILD_ADDED -- Indicates that children have been added to the observed container.

Together, UpdateMessage, Observer, and Subject are based on the Observer Update Message pattern. In designs using this pattern, the subject usually consists of a number of objects. A state change in such a design is usually complex, involving multiple objects, and can be characterized by a series of new object creations (add), old object deletions (remove), and current object modifications (modify) at certain locations (container).

See Also:

Observer, Subject

Field Summary

static int	ATTRIBUTE_CHANGED Indicates that an element attribute has changed.
static int	CHILD_ADDED Indicates that children have been added to a folder object
static int	CHILD_REMOVED Indicates that children of a folder object has been removed.
static int	CHILD_RENAMED NOTE: It is recommended to use the RenameMessage API to get at the child rename information.
static int	OBJECT_CLOSED Indicates the object contents are closed or unloaded.
static int	OBJECT_CLOSING Indicates the object contents are about to be closed or unloaded.
static int	OBJECT_OPENED Indicates that a node has been opened.
static int	OBJECT_RELOADED Indicates that a node has been reloaded (i.e., modified externally)
static int	OBJECT_RENAMED NOTE: It is recommended to use the RenameMessage API to get at the object rename information.
static int	PROPERTY_SET Indicates that a property has changed
static int	STRUCTURE_CHANGED Indicates that complex structure change has taken place

Fields inherited from class oracle.ide.addin.Message

add, COMMAND_ID_PROP, container, context, messageID, messageProperties, modify, origin, remove

Constructor Summary

UpdateMessage(int messageID, java.lang.Object origin)
Constructs an update message of the specified message id.

UpdateMessage(UpdateMessage msg)

Method Summary

static void	fireAttributeChanged(Subject subject, Attributes oldAttributes) This method sends an UpdateMessage whose ID is ATTRIBUTE_CHANGED to all Observers of the specified Subject.
static void	fireChildAdded(Subject subject, Element element) Identical to fireChildAdded(Subject,Element,Object) with null for the extraData parameter.
static void	fireChildAdded(Subject subject, Element element, java.lang.Object extraData) This method sends an UpdateMessage whose ID is CHILD_ADDED to all Observers of the specified Subject.
static void	fireChildRemoved(Subject subject, Element element) This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject.
static void	fireChildRemoved(Subject subject, Element element, java.util.Map messageProperties) This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject.
static void	fireChildrenAdded(Subject subject, java.util.Collection childElements) Identical to fireChildrenAdded(Subject,Collection,Object) with null for the extraData parameter.
static void	fireChildrenAdded(Subject subject, java.util.Collection childElements, java.lang.Object extraData) This method sends an UpdateMessage whose ID is CHILD_ADDED to all Observers of the specified Subject.
static void	fireChildrenRemoved(Subject subject, java.util.Collection childElements) This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject.
static void	fireChildrenRemoved(Subject subject, java.util.Collection childElements, java.util.Map messageProperties) This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject.
static void	fireObjectClosed(Subject subject) This method sends an UpdateMessage whose ID is OBJECT_CLOSED to all Observers of the specified Subject.
static void	fireObjectOpened(Subject subject) This method sends an UpdateMessage whose ID is OBJECT_OPENED to all Observers of the specified Subject.
static void	fireObjectReloaded(Subject subject) This method sends an UpdateMessage whose ID is OBJECT_RELOADED to all Observers of the specified Subject.
static void	firePropertiesChanged(Subject subject, java.beans.PropertyChangeEvent[] propertyChangeEvents, java.lang.Object origin) This method sends an UpdateMessage with ID PROPERTY_SET to all Observers of the specified Subject.
static void	fireStructureChanged(Subject subject) This method sends an UpdateMessage whose ID is STRUCTURE_CHANGED to all Observers of the specified Subject.
static void	fireStructureChanged(Subject subject, java.util.Collection modifyObjects) This method sends an UpdateMessage whose ID is STRUCTURE_CHANGED to all Observers of the specified Subject.
UpdateMessage	fromNewOrigin(java.lang.Object newOrigin) Makes a copy of this UpdateMessage, except that the origin is set to newOrigin, replacing the current origin.
java.util.List	getContainer() Retrieves the list of the parents containing the objects listed in the add, remove, and/or modify lists.
java.util.Map	getMessageMap() Retrieves the map where user data is stored for the UpdateMessage.
java.util.Map	getPropertyMap() Retrieves the Map of property names PropertyChangeEvents modified during a Subject change.
static int	getUniqueMessageID()
protected static void	notifyObserversOnEventThread(Subject subject, UpdateMessage message)
void	setPropertyMap(java.util.Map propertyMap) Assigns the Map of property names PropertyChangeEvents modified during a Subject change.

Methods inherited from class oracle.ide.addin.Message

getAddObjects, getContext, getExtraData, getMessageID, getModifyObjects, getOrigin, getProperty, getRemoveObjects, setContext, setExtraData, setProperty

Methods inherited from class java.lang.Object

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

Field Detail

CHILD_REMOVED

public static final int CHILD_REMOVED

Indicates that children of a folder object has been removed. This message is sent immediately after the OBJECT_CLOSED notification. Observers should do all necessary cleanup on the OBJECT_CLOSED notification. Once the CHILD_REMOVED message is received, observers should not access data stored by the object being removed. Doing so will re-open the object again.

See Also:

Constant Field Values

CHILD_ADDED

public static final int CHILD_ADDED

Indicates that children have been added to a folder object

See Also:

Constant Field Values

STRUCTURE_CHANGED

public static final int STRUCTURE_CHANGED

Indicates that complex structure change has taken place

See Also:

Constant Field Values

PROPERTY_SET

public static final int PROPERTY_SET

Indicates that a property has changed

See Also:

Constant Field Values

OBJECT_RENAMED

public static final int OBJECT_RENAMED

NOTE: It is recommended to use the RenameMessage API to get at the object rename information. Indicates the object was renamed. The update message contains the following information:

Case 1) Simple node rename: getModifyObjects() contains the old URL.

Case 2) Renaming node changes the node's type: getModifyObjects() contains the old URL. getRemoveObjects() contains the node being renamed. getAddObjects() contains the new node instance created by conversion.

Case 3) Node being renamed the same as an existing node of the same type: getModifyObjects() contains the old URL. getRemoveObjects() contains the node being renamed. getAddObjects() may contain the existing node instance if that instance is not part of the project containing the original node.

Case 4) Node being renamed the same as an existing node of different type: Not yet supported.

See Also:

Constant Field Values

CHILD_RENAMED

public static final int CHILD_RENAMED

NOTE: It is recommended to use the RenameMessage API to get at the child rename information. Indicates the a child of a folder was renamed. The update message contains the following information:

Case 1) Simple object rename: getModifyObjects() contains the old URL and the child being renamed.

Case 2) Renaming node changes the node's type getModifyObjects() contains the old URL. getRemoveObjects() contains the node being renamed. getAddObjects() contains the new node instance created by conversion.

Case 3) Node being renamed the same as an existing node of the same type: getModifyObjects() contains the old URL and the owner of the node being renamed. getRemoveObjects() contains the node being renamed. getAddObjects() may contain the existing node instance if that instance is not part of the project containing the original node.

Case 4) Node being renamed the same as an existing node of different type: Not yet supported.

See Also:

Constant Field Values

OBJECT_CLOSING

public static final int OBJECT_CLOSING

Indicates the object contents are about to be closed or unloaded. Observers can access data contained by the object being closed when this notification message is received. The object will be closed after this notification message has been sent.

See Also:

Constant Field Values

OBJECT_CLOSED

public static final int OBJECT_CLOSED

Indicates the object contents are closed or unloaded. Observers can should not access data contained by the object being closed when this notification message is received. The object has been closed before this notification message has been sent and accessing data reopens the closed object.

See Also:

Constant Field Values

OBJECT_OPENED

public static final int OBJECT_OPENED

Indicates that a node has been opened.

See Also:

Constant Field Values

OBJECT_RELOADED

public static final int OBJECT_RELOADED

Indicates that a node has been reloaded (i.e., modified externally)

See Also:

Constant Field Values

ATTRIBUTE_CHANGED

public static final int ATTRIBUTE_CHANGED

Indicates that an element attribute has changed. The method getModifyObjects() containes an Interger with the old attribute values.

See Also:

Constant Field Values

Constructor Detail

UpdateMessage

public UpdateMessage(int messageID,
                     java.lang.Object origin)

Constructs an update message of the specified message id.

Parameters:

origin - the Object which originated this message. Usually an Observer.

messageID - the message identifier.

UpdateMessage

public UpdateMessage(UpdateMessage msg)

Method Detail

getPropertyMap

public java.util.Map getPropertyMap()

Retrieves the Map of property names PropertyChangeEvents modified during a Subject change. If null, the Observer must assume that any or all properties on this subject have changed, and respond accordingly.

Returns:

the Map of objects modified during a Subject change, or null if one or more PropertyChangeEvents has a null propertyName.

setPropertyMap

public void setPropertyMap(java.util.Map propertyMap)

Assigns the Map of property names PropertyChangeEvents modified during a Subject change. If null, the Observer must assume that any or all properties on this subject have changed, and respond accordingly.

Parameters:

propertyMap - the Map of property names PropertyChangeEvents modified during a Subject change, or null to indicate any or all properties may have changed.

getContainer

public java.util.List getContainer()

Retrieves the list of the parents containing the objects listed in the add, remove, and/or modify lists.

Returns:

the list of objects modified during a Subject change.

getUniqueMessageID

public static int getUniqueMessageID()

getMessageMap

public java.util.Map getMessageMap()

Retrieves the map where user data is stored for the UpdateMessage.

Returns:

the Map of user properties associated with this message.

See Also:

Message.messageProperties

fromNewOrigin

public UpdateMessage fromNewOrigin(java.lang.Object newOrigin)

Makes a copy of this UpdateMessage, except that the origin is set to newOrigin, replacing the current origin.

fireChildAdded

public static void fireChildAdded(Subject subject,
                                  Element element,
                                  java.lang.Object extraData)

This method sends an UpdateMessage whose ID is CHILD_ADDED to all Observers of the specified Subject. The specified Element is the content of the "add objects" of the message.

Parameters:

subject - The Subject whose Observers are to be notified.

element - The Element that makes up the "add objects" content of the message.

extraData - A reference to an arbitrary Object containing user data related to the message.

fireChildAdded

public static void fireChildAdded(Subject subject,
                                  Element element)

Identical to fireChildAdded(Subject,Element,Object) with null for the extraData parameter.

fireChildrenAdded

public static void fireChildrenAdded(Subject subject,
                                     java.util.Collection childElements,
                                     java.lang.Object extraData)

This method sends an UpdateMessage whose ID is CHILD_ADDED to all Observers of the specified Subject. The specified Collection of Element instances is the content of the "add objects" of the message.

Parameters:

subject - The Subject whose Observers are to be notified.

childElements - The Collection of Element instances that make up the "add objects" of the message.

extraData - A reference to an arbitrary Object containing user data related to the message.

fireChildrenAdded

public static void fireChildrenAdded(Subject subject,
                                     java.util.Collection childElements)

Identical to fireChildrenAdded(Subject,Collection,Object) with null for the extraData parameter.

fireChildRemoved

public static void fireChildRemoved(Subject subject,
                                    Element element)

This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject. The specified Element is the content of the "remove objects" of the message.

Parameters:

subject - The Subject whose Observers are to be notified.

element - The Element that makes up the "remove objects" content of the message.

fireChildRemoved

public static void fireChildRemoved(Subject subject,
                                    Element element,
                                    java.util.Map messageProperties)

This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject. The specified Element is the content of the "remove objects" of the message.

Parameters:

subject - The Subject whose Observers are to be notified.

element - The Element that makes up the "remove objects" content of the message.

messageProperties - The map of properties related to this message.

fireChildrenRemoved

public static void fireChildrenRemoved(Subject subject,
                                       java.util.Collection childElements)

This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject. The specified Collection of Element instances is the content of the "remove objects" of the message.

Parameters:

subject - The Subject whose Observers are to be notified.

childElements - The Collection of Element instances that make up the "remove objects" of the message.

fireChildrenRemoved

public static void fireChildrenRemoved(Subject subject,
                                       java.util.Collection childElements,
                                       java.util.Map messageProperties)

This method sends an UpdateMessage whose ID is CHILD_REMOVED to all Observers of the specified Subject. The specified Collection of Element instances is the content of the "remove objects" of the message.

Parameters:

subject - The Subject whose Observers are to be notified.

childElements - The Collection of Element instances that make up the "remove objects" of the message.

messageProperties - The map of properties related to this message.

fireStructureChanged

public static void fireStructureChanged(Subject subject,
                                        java.util.Collection modifyObjects)

This method sends an UpdateMessage whose ID is STRUCTURE_CHANGED to all Observers of the specified Subject. The specified Collection of Element instances is the content of the "modify objects" of the message.

Parameters:

subject - The Subject whose Observers are to be notified.

modifyObjects - The Collection of Element instances that make up the "modify objects" of the message.

fireStructureChanged

public static void fireStructureChanged(Subject subject)

This method sends an UpdateMessage whose ID is STRUCTURE_CHANGED to all Observers of the specified Subject.

Parameters:

subject - The Subject whose Observers are to be notified.

firePropertiesChanged

public static void firePropertiesChanged(Subject subject,
                                         java.beans.PropertyChangeEvent[] propertyChangeEvents,
                                         java.lang.Object origin)

This method sends an UpdateMessage with ID PROPERTY_SET to all Observers of the specified Subject.

In general, each member of the propertyChangeEvents array is mapped to by its propertyName (PropertyChangeEvent.getPropertyName()) and available to Observers through the getPropertyMap() method. However, in the event that one or more members of the propertyChangeEvents array has a null property name, the propertyChangeEvents are discarded, and the return value is null, indicating that any or all properties on the subject may have changed.

Consequently, Observer objects notified by this method must first check for a null value from getPropertyMap() and then can search for any properties they are interested in by calling:

updateMessage.getPropertyMap().get(propertyName)

It is presumed that all members of the propertyChangeEvent array belong to, or are at least logically affiliated with, the Subject.

Parameters:

subject - The Subject whose Observers are to be notified.

propertyChangeEvents - The PropertyChangeEvent array to store in the message.

origin - The Object responsible for making the property changes.

fireObjectOpened

public static void fireObjectOpened(Subject subject)

This method sends an UpdateMessage whose ID is OBJECT_OPENED to all Observers of the specified Subject.

Parameters:

subject - The Subject whose Observers are to be notified.

fireObjectReloaded

public static void fireObjectReloaded(Subject subject)

This method sends an UpdateMessage whose ID is OBJECT_RELOADED to all Observers of the specified Subject.

Parameters:

subject - The Subject whose Observers are to be notified.

fireObjectClosed

public static void fireObjectClosed(Subject subject)

This method sends an UpdateMessage whose ID is OBJECT_CLOSED to all Observers of the specified Subject.

Parameters:

subject - The Subject whose Observers are to be notified.

fireAttributeChanged

public static void fireAttributeChanged(Subject subject,
                                        Attributes oldAttributes)

This method sends an UpdateMessage whose ID is ATTRIBUTE_CHANGED to all Observers of the specified Subject. Attribute change notification is done in the event thread since it observers will perform GUI updates.

Parameters:

subject - The Subject whose Observers are to be notified.

notifyObserversOnEventThread

protected static void notifyObserversOnEventThread(Subject subject,
                                                   UpdateMessage message)