Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.1.0)

E17493-02

oracle.ide.model
Class UpdateMessage

java.lang.Object
  extended by 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:

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
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
UpdateMessage(int messageID, java.lang.Object origin)
          Constructs an update message of the specified message id.
 
Method Summary
 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 UpdateMessage#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 UpdateMessage#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.

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

Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.1.0)

E17493-02

Copyright © 1997, 2011, Oracle. All rights reserved.