oracle.ide.model

Class UpdateMessage

java.lang.Object

oracle.ide.model.UpdateMessage

public final class UpdateMessage
extends java.lang.Object

An UpdateMessage represents the message from a Subject to an Observer about a change that has already happened or, in the case of vetoable updates, a change that is about to happen.

An update message consists of three lists: add, remove, and modify lists. A subject 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.
• CAN_ADD_CHILD -- Indicates that children of a container object are about to be added.
• CAN_REMOVE_CHILD -- Indicates that children are about to be removed.
• CAN_RENAME_CHILD -- Indicates that children are about to be renamed.

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, VetoObserver

Field Summary

Fields

Modifier and Type	Field and Description
static int	ATTRIBUTE_CHANGED Indicates that an element attribute has changed.
static int	CAN_ADD_CHILD Indicates that children are about to be added to a folder object.
static int	CAN_REMOVE_CHILD Indicates that children of a folder object is about to be removed.
static int	CAN_RENAME_CHILD Indicates the child is about to be renamed.
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 Indicates the a child of a folder was renamed.
static java.lang.String	COMMAND_ID_PROP The command ID property key.
static int	CONTENT_MODIFIED Indicates that the content (e.g.
static int	NO_MESSAGE Indicates an empty message.
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 Indicates the object was renamed.
static int	PROPERTY_SET Indicates that a property has changed
static int	STRUCTURE_CHANGED Indicates that complex structure change has taken place

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static java.lang.StringBuilder	appendMessageName(java.lang.StringBuilder builder, int messageId)
boolean	containsProperty(java.lang.String name)
UpdateMessage	copyMessage() Makes a copy of this UpdateMessage and returns it.
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	fireCanAddChild(VetoableSubject subject, java.lang.Object element) This method sends an UpdateMessage whose ID is CAN_ADD_CHILD to all Observers of the specified Subject.
static void	fireCanAddChildren(VetoableSubject subject, java.util.Collection children) This method sends an UpdateMessage whose ID is CAN_ADD_CHILD to all Observers of the specified Subject.
static void	fireCanRemoveChild(VetoableSubject subject, java.lang.Object element) This method sends an UpdateMessage whose ID is CAN_REMOVE_CHILD to all Observers of the specified VetoableSubject.
static void	fireCanRemoveChildren(VetoableSubject subject, java.util.Collection children) This method sends an UpdateMessage whose ID is CAN_REMOVE_CHILD to all Observers of the specified VetoableSubject.
static void	fireCanRenameChild(VetoableSubject subject, java.lang.Object child) This method sends an UpdateMessage whose ID is CAN_RENAME_CHILD to all Observers of the specified VetoableSubject.
static void	fireChildAdded(Subject subject, Element element) 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	fireChildrenAdded(Subject subject, java.util.Collection childElements) 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	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	fireObjectRenamed(Subject subject) This method sends an UpdateMessage whose ID is OBJECT_RENAMED 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	forNewMessageID(int newMessageID) Makes a copy of this UpdateMessage and, in the copy, replaces the message ID with the specified newMessageID.
UpdateMessage	forNewOrigin(java.lang.Object newOrigin) Makes a copy of this UpdateMessage and, in the copy, replaces the origin with newOrigin.
java.util.List	getAddObjects() Retrieves the list of objects added during a Subject change.
Context	getContext() Get the context under which notification is taking place.
int	getMessageID() Retrieves the message identifier.
java.util.List	getModifyObjects() Retrieves the list of objects modified during a Subject change.
java.lang.Object	getOrigin() Retrieves the originator of the message.
java.lang.Object	getProperty(java.lang.String name) Get the property with the specified name from this message.
java.util.List	getRemoveObjects() Retrieves the list of objects removed during a Subject change.
static int	newMessageID(java.lang.String debugString) Generates a new unique integer for a message ID.
void	removeProperty(java.lang.String name) Removes the property with the specified name from this message.
void	setContext(Context context) Set the context under which notification is taking place.
void	setProperty(java.lang.String name, java.lang.Object value) Sets a property with the specified name and value on this message.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

NO_MESSAGE

public static final int NO_MESSAGE

Indicates an empty message. This is useful for creating an UpdateMessage template that will later be used with forNewMessageID(int) to provide the real message ID.

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.

CHILD_ADDED

public static final int CHILD_ADDED

Indicates that children have been added to a folder object

STRUCTURE_CHANGED

public static final int STRUCTURE_CHANGED

Indicates that complex structure change has taken place

PROPERTY_SET

public static final int PROPERTY_SET

Indicates that a property has changed

OBJECT_RENAMED

public static final int OBJECT_RENAMED

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.

CHILD_RENAMED

public static final int CHILD_RENAMED

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.

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.

OBJECT_OPENED

public static final int OBJECT_OPENED

Indicates that a node has been opened.

OBJECT_RELOADED

public static final int OBJECT_RELOADED

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

ATTRIBUTE_CHANGED

public static final int ATTRIBUTE_CHANGED

Indicates that an element attribute has changed. The method getModifyObjects() containes an Integer with the old attribute 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.

CAN_REMOVE_CHILD

public static final int CAN_REMOVE_CHILD

Indicates that children of a folder object is about to be removed. The suject of the message is the container that owns the child.

CAN_ADD_CHILD

public static final int CAN_ADD_CHILD

Indicates that children are about to be added to a folder object. The suject of the message is the container that owns the child.

CAN_RENAME_CHILD

public static final int CAN_RENAME_CHILD

Indicates the child is about to be renamed. The suject of the message is the object about to be renamed.

CONTENT_MODIFIED

public static final int CONTENT_MODIFIED

Indicates that the content (e.g. text in a text buffer) of the object has been modified.

COMMAND_ID_PROP

public static final java.lang.String COMMAND_ID_PROP

The command ID property key.

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:

messageID - the message identifier.

origin - the Object which originated this UpdateMessage, usually the Subject of the message.

Method Detail

getProperty

public final java.lang.Object getProperty(java.lang.String name)

Get the property with the specified name from this message. If the property is not defined, this method returns null.

Parameters:

name - the property name.

setProperty

public final void setProperty(java.lang.String name,
                              java.lang.Object value)

Sets a property with the specified name and value on this message. The name may be null, and the value may be null. Setting a null value means the message contains a property with an explicitly set null value. To remove a property, use removeProperty(java.lang.String).

Parameters:

name - the name of the property. The name may be null.

value - the value of the property. The value may be null.

removeProperty

public final void removeProperty(java.lang.String name)

Removes the property with the specified name from this message.

containsProperty

public final boolean containsProperty(java.lang.String name)

Returns:

true if this Message contains a property with the specified name.

getMessageID

public final int getMessageID()

Retrieves the message identifier.

Returns:

the message identifier.

newMessageID

public static final int newMessageID(java.lang.String debugString)

Generates a new unique integer for a message ID. This ID can then be used to create a Message instance for an extension-specific message.

This method takes an optional debug string as an argument, for which you are strongly encouraged to pass a meaningful value. This greatly facilitates debugging, when you need to know what the message ID for an UpdateMessage represents. By convention, you should pass a String that represents the public static field that holds the message ID. For example, for PROPERTY_SET the string "UpdateMessage.PROPERTY_SET" is used.

Parameters:

debugString - The string to display in the JDeveloper debugger when an UpdateMessage has the message ID returned from this method.

Returns:

a new unique message ID

getOrigin

public final java.lang.Object getOrigin()

Retrieves the originator of the message. Usually an Observer.

Returns:

the originator of the message.

getAddObjects

public final java.util.List getAddObjects()

Retrieves the list of objects added during a Subject change.

Returns:

the list of objects added during a Subject change.

getRemoveObjects

public final java.util.List getRemoveObjects()

Retrieves the list of objects removed during a Subject change.

Returns:

the list of objects removed during a Subject change.

getModifyObjects

public final java.util.List getModifyObjects()

Retrieves the list of objects modified during a Subject change.

Returns:

the list of objects modified during a Subject change.

getContext

public final Context getContext()

Get the context under which notification is taking place. This may be null.

setContext

public final void setContext(Context context)

Set the context under which notification is taking place.

copyMessage

public final UpdateMessage copyMessage()

Makes a copy of this UpdateMessage and returns it.

forNewMessageID

public final UpdateMessage forNewMessageID(int newMessageID)

Makes a copy of this UpdateMessage and, in the copy, replaces the message ID with the specified newMessageID.

forNewOrigin

public final UpdateMessage forNewOrigin(java.lang.Object newOrigin)

Makes a copy of this UpdateMessage and, in the copy, replaces the origin with newOrigin.

fireChildAdded

public static void fireChildAdded(Subject subject,
                                  Element element)

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.

fireChildrenAdded

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

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.

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.

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.

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 getProperty(String) 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 getProperty(String) 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.

fireObjectRenamed

public static void fireObjectRenamed(Subject subject)

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

Parameters:

subject - The Subject whose Observers are to be notified.

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.

fireCanAddChild

public static void fireCanAddChild(VetoableSubject subject,
                                   java.lang.Object element)
                            throws ChangeVetoException

This method sends an UpdateMessage whose ID is CAN_ADD_CHILD 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.

Throws:

ChangeVetoException

fireCanAddChildren

public static void fireCanAddChildren(VetoableSubject subject,
                                      java.util.Collection children)
                               throws ChangeVetoException

This method sends an UpdateMessage whose ID is CAN_ADD_CHILD 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.

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

Throws:

ChangeVetoException

fireCanRemoveChild

public static void fireCanRemoveChild(VetoableSubject subject,
                                      java.lang.Object element)
                               throws ChangeVetoException

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

Parameters:

subject - The VetoableSubject whose Observers are to be notified.

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

Throws:

ChangeVetoException

fireCanRemoveChildren

public static void fireCanRemoveChildren(VetoableSubject subject,
                                         java.util.Collection children)
                                  throws ChangeVetoException

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

Parameters:

subject - The VetoableSubject whose Observers are to be notified.

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

Throws:

ChangeVetoException

fireCanRenameChild

public static void fireCanRenameChild(VetoableSubject subject,
                                      java.lang.Object child)
                               throws ChangeVetoException

This method sends an UpdateMessage whose ID is CAN_RENAME_CHILD to all Observers of the specified VetoableSubject.

Parameters:

subject - The VetoableSubject whose Observers are to be notified.

child - The child about to be renamed.

Throws:

ChangeVetoException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

appendMessageName

public static java.lang.StringBuilder appendMessageName(java.lang.StringBuilder builder,
                                                        int messageId)