oracle.ide.model
Class Node

java.lang.Object
  oracle.ide.model.Node

All Implemented Interfaces:

oracle.javatools.data.Dirtyable, Dirtyable, Displayable, Element, LazyLoadable, Locatable, Subject

Direct Known Subclasses:

DataNode, DefaultContainer, ImageNode, Layout, RegisteredDynamicNode, TextNode, XMLDataNode

public class Node

extends java.lang.Object

implements Locatable, Element, Subject, Dirtyable, LazyLoadable

The Node class is the base class for all document types that need to interact with the IDE framework.

Constructor Summary

Node()
Default constructor.

Node(java.net.URL url)
Constructor that takes an URL pointing to the persistent location of the Node's contents.

Method Summary

protected ReadWriteLock	_getReadWriteLockInternal() Fetch the lock instance used for Node state and data synchronization.
void	addNodeListener(NodeListener listener) Adds the specified NodeListener to this Node instance.
static void	addNodeListenerForType(java.lang.Class type, NodeListener listener) Statically registers the specified NodeListener to be called back for node events for the specified node type.
static void	addNodeListenerForTypeHierarchy(java.lang.Class type, NodeListener listener) Statically registeres the specified NodeListener to be called back for node events for the specified node type and its subtypes.
void	attach(Observer observer) Registers an observer interested in being notified when the internal state of the class implementing the Subject interface changes.
void	close() Closes the Node and unloads any associated data.
protected void	closeImpl() Subclasses should override this method to customize the close() behavior.
protected Subject	createSubject() Creates an instance of a Subject implementation.
void	delete() This method closes the current node (if open), deletes the Node from disk, and removes this Node from the NodeFactory's cache.
protected void	deleteImpl() Subclasses should override this method to customize the delte() behavior.
void	detach(Observer observer) Unregisters an observer that is not interested anymore in being notified when the internal state of the class implementing the Subject interface changes.
boolean	ensureOpen() Call this method to make sure that the Node is properly opened before accessing its data.
protected boolean	equalsImpl(Node node) This is a helper method for)that can also be used by subclasses that implement).
Attributes	getAttributes() This method returns an Attributes object that encodes the attributes of the Element.
java.util.Iterator	getChildren() This method is part of the Element interface to provide a convenient way of getting an Iterator over any contained child Elements without having to test the object's type with the instanceof operator or having to downcast to a more specific type.
java.lang.Object	getData() Returns the data object associated with this Element.
javax.swing.Icon	getIcon() Displayable interface method.
java.io.InputStream	getInputStream() Gets an InputStream that can be used to read the contents of the Node.
java.lang.String	getLongLabel() Displayable interface method.
java.lang.String	getShortLabel() Displayable interface method.
protected Subject	getSubject() Gets the implementation of the Subject interface.
long	getTimestamp() Returns the timestamp associated with the Node, which indicates the time at which the Node was last modified.
java.lang.String	getToolTipText() Displayable interface method.
java.net.URL	getURL() Returns the URL that identifies this Locatable.
boolean	isDirty()
boolean	isNew() Returns true if the Node's data has never been saved.
boolean	isOpen() Returns true if the object's data has already been loaded.
boolean	isReadOnly() Returns true if the Node is read-only.
protected boolean	isTrackedInNodeCache() The return value of this method indicates whether this Node should be tracked by the NodeFactory cache.
void	markDirty(boolean dirty)
boolean	mayHaveChildren() This method is part of the Element interface to provide a convenient way of determining whether an object may have children without having to test the object's type with the instanceof operator or having to downcast to a more specific type.
void	notifyObservers(java.lang.Object observed, UpdateMessage change) Notifies all observers that the state of the subject has changed.
void	open() Opens the Node and loads any associated data into the appropriate data structures.
protected void	openImpl() Subclasses should override this method to customize the open() behavior.
protected void	postCloseImpl() This method is called after nodeClosed(..) has been called on all registered NodeListeners.
protected long	refreshTimestamp() Protected method that can be used to refresh the timestamp of the Node based on the timestamp that can be obtained through the URL.
void	removeNodeListener(NodeListener listener) Removes the specified NodeListener from this Node instance.
static void	removeNodeListenerForType(java.lang.Class type, NodeListener listener) Unregisters a listener that had been registered via addNodeListenerForType(Class,NodeListener).
static void	removeNodeListenerForTypeHierarchy(java.lang.Class type, NodeListener listener) Unregisters a listener that had been registered via addNodeListenerForTypeHierarchy(Class,NodeListener).
Node	rename(java.net.URL newURL) This method renames the current node and recaches this Node under its new URL in the NodeFactory.
protected void	renameImpl(java.net.URL oldURL, java.net.URL newURL) Subclasses should override this method to customize the rename() behavior.
protected void	reportOpenException(java.lang.Exception e) This routine is given a chance to handle or report an Exception that occurred during open().
void	revert()
protected void	revertImpl() Subclasses should override this method to customize the revert() behavior.
protected void	runWhileSynchronized(java.lang.Runnable runnable) Executes the specified runnable implementation while under the Node's exclusive locking protection.
void	save() Saves the contents of the Node.
protected void	saveImpl() Subclasses should override this method to customize the save() behavior.
protected void	setOpen(boolean isOpen) Protected accessor for the#_isOpenflag.
protected void	setTimestampDirectly(long timestamp) Accessor for allowing subclasses to set the timestamp directly.
void	setURL(java.net.URL newURL) Sets the URL associated with this Node and recaches the Node in the NodeFactory with the new URL so that subsequent queries for the Node will return successfully.
java.lang.String	toString() Returns the Short Label displayed to a user.

Methods inherited from class java.lang.Object

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

Constructor Detail

Node

public Node()

Default constructor.

Node

public Node(java.net.URL url)

Constructor that takes an URL pointing to the persistent location of the Node's contents.

Parameters:

url - URL identifying the persistent location of the Node.

Method Detail

addNodeListenerForType

public static final void addNodeListenerForType(java.lang.Class type,
                                                NodeListener listener)

Statically registers the specified NodeListener to be called back for node events for the specified node type. Only events for the exact type will be delivered. To receive events for all types and subtypes, use addNodeListenerForTypeHierarchy(Class,NodeListener)

Parameters:

type - the exact Node type whose events should be delivered to the listener

listener - the NodeListener to register

removeNodeListenerForType

public static final void removeNodeListenerForType(java.lang.Class type,
                                                   NodeListener listener)

Unregisters a listener that had been registered via addNodeListenerForType(Class,NodeListener).

Parameters:

type - the Node type for which the listener had been registered

listener - the NodeListener to unregister

addNodeListenerForTypeHierarchy

public static final void addNodeListenerForTypeHierarchy(java.lang.Class type,
                                                         NodeListener listener)

Statically registeres the specified NodeListener to be called back for node events for the specified node type and its subtypes. To receive events instead for a specific node type and not its subtypes, use addNodeListenerForType(Class,NodeListener).

Parameters:

type - the Node type (and its subtypes) whose events should be delivered to the listener

listener - the NodeListener to register

removeNodeListenerForTypeHierarchy

public static final void removeNodeListenerForTypeHierarchy(java.lang.Class type,
                                                            NodeListener listener)

Unregisters a listener that had been registered via addNodeListenerForTypeHierarchy(Class,NodeListener).

Parameters:

type - the Node type for which the listener had been registered

listener - the NodeListener to unregister

addNodeListener

public final void addNodeListener(NodeListener listener)

Adds the specified NodeListener to this Node instance.

Parameters:

listener - the listener to add

removeNodeListener

public final void removeNodeListener(NodeListener listener)

Removes the specified NodeListener from this Node instance.

Parameters:

listener - the listener to remove

getURL

public java.net.URL getURL()

Description copied from interface: Locatable

Returns the URL that identifies this Locatable. Parts of the IDE will use the value of this URL as a hash key for caching UI components for this Locatable. Therefore, URL uniqueness is important.

Specified by:

getURL in interface Locatable

Returns:

The URL identifying this Locatable.

setURL

public void setURL(java.net.URL newURL)

Sets the URL associated with this Node and recaches the Node in the NodeFactory with the new URL so that subsequent queries for the Node will return successfully.

Specified by:

setURL in interface Locatable

Parameters:

newURL - The URL to set.

See Also:

Locatable.setURL(URL)

isTrackedInNodeCache

protected boolean isTrackedInNodeCache()

The return value of this method indicates whether this Node should be tracked by the NodeFactory cache. The default return value is true. Node types that should not be tracked by the NodeFactory cache should override this method to return false.

Returns:

true if this Node should be tracked by the IDE's NodeFactory cache; false otherwise.

isDirty

public boolean isDirty()

Specified by:

isDirty in interface oracle.javatools.data.Dirtyable

markDirty

public void markDirty(boolean dirty)

Specified by:

markDirty in interface oracle.javatools.data.Dirtyable

getShortLabel

public java.lang.String getShortLabel()

Displayable interface method. The Node class returns the file name part of the currently set URL. If the currently set URL is null, then this method returns "<null>".

Specified by:

getShortLabel in interface Displayable

Returns:

a short descriptive label of the Displayable that can be shown to the user.

getLongLabel

public java.lang.String getLongLabel()

Displayable interface method. The Node class returns the path name part of the currently set URL. If the currently set URL is null, then this method returns "<null>".

Specified by:

getLongLabel in interface Displayable

Returns:

a long descriptive label of the Displayable that can be shown to the user.

getIcon

public javax.swing.Icon getIcon()

Displayable interface method. The Node class returns a generic icon.

Specified by:

getIcon in interface Displayable

Returns:

the Icon to be displayed for the Displayable.

getToolTipText

public java.lang.String getToolTipText()

Displayable interface method. The Node class returns returns the String form of the currently set URL.

Specified by:

getToolTipText in interface Displayable

Returns:

the tooltip to show when the mouse pointer pauses over a UI component that represents this Displayable.

attach

public final void attach(Observer observer)

Description copied from interface: Subject

Registers an observer interested in being notified when the internal state of the class implementing the Subject interface changes. Implementors should do nothing when the same observer is added more than once.

Specified by:

attach in interface Subject

Parameters:

observer - the Observer interested in change notification messages.

detach

public final void detach(Observer observer)

Description copied from interface: Subject

Unregisters an observer that is not interested anymore in being notified when the internal state of the class implementing the Subject interface changes. Implementors should do nothing when the same observer is removed more than once.

Specified by:

detach in interface Subject

Parameters:

observer - the Observer disinterested in change notification messages.

notifyObservers

public void notifyObservers(java.lang.Object observed,
                            UpdateMessage change)

Description copied from interface: Subject

Notifies all observers that the state of the subject has changed.

Specified by:

notifyObservers in interface Subject

Parameters:

observed - the subject whose state has changed.

change - what changed.

getSubject

protected final Subject getSubject()

Gets the implementation of the Subject interface. This implementation returns an IdeSubject but subclasses should override the createSubject method in order to provide a different implementation of a Subject.

createSubject

protected Subject createSubject()

Creates an instance of a Subject implementation. This method is called from getSubject() the first time the subject is created. Subclasses should override this method to provide their own Subject implementation.

getData

public java.lang.Object getData()

Description copied from interface: Element

Returns the data object associated with this Element. Implementations will often simply return this, since the Element is often its own data object.

Specified by:

getData in interface Element

Returns:

the data object associated with this Element instance.

mayHaveChildren

public boolean mayHaveChildren()

Description copied from interface: Element

This method is part of the Element interface to provide a convenient way of determining whether an object may have children without having to test the object's type with the instanceof operator or having to downcast to a more specific type.

An implementation of Element that represents a leaf in a tree structure should return false from this method. An implementation of Element that could represent a non-leaf in a tree structure should return true from this method, even if it does not currently contain any children.

Specified by:

mayHaveChildren in interface Element

Returns:

true if this Element may contain child Elements.

getChildren

public java.util.Iterator getChildren()

Description copied from interface: Element

This method is part of the Element interface to provide a convenient way of getting an Iterator over any contained child Elements without having to test the object's type with the instanceof operator or having to downcast to a more specific type.

An implementation of Element that represents a leaf in a tree structure should return null from this method. An implementation of Element that could represent a non-leaf in a tree structure should return either an Iterator over the child Elements or null if there are no children.

Specified by:

getChildren in interface Element

Returns:

an Iterator over any child Elements contained by this Element. If there are no children, null is returned.

getAttributes

public Attributes getAttributes()

Description copied from interface: Element

This method returns an Attributes object that encodes the attributes of the Element. Changing the attribute settings on the return object changes the element attributes. Subclasses should use their super class attributes object to define their own attributes. This allows subclasses to inherit their super class attributes. If a subclass does not wish to inherit attributes, they should first call getAttributes().clear() and define new attributes.

Specified by:

getAttributes in interface Element

open

public final void open()
                throws java.io.IOException

Opens the Node and loads any associated data into the appropriate data structures. If the implementation of this method completes successfully, the isOpen() method should then return true.

In addition, this method should fire an oracle.ide.addin.UpdateMessage#OBJECT_OPENED update message when the node is opened.

Throws:

java.io.IOException - Signals that an I/O exception occurred while trying to open this Node.

close

public final void close()
                 throws java.io.IOException

Closes the Node and unloads any associated data. When this method returns, the state of the Node object should be equivalent to when the Node object has just been instantiated but not yet opened.

Implementations of the close method should not fire object closing update messages. The IDE takes care of firing those events when Nodes are closed.

Throws:

java.io.IOException - Signals that an I/O exception occurred while trying to close this Node.

save

public final void save()
                throws java.io.IOException

Saves the contents of the Node.

Throws:

java.io.IOException - Signals that an I/O exception of some sort occurred.

revert

public final void revert()
                  throws java.io.IOException

Throws:

java.io.IOException

delete

public final void delete()
                  throws java.io.IOException

This method closes the current node (if open), deletes the Node from disk, and removes this Node from the NodeFactory's cache. The NodeListener event nodeDeleted is fired during this process. The nodeDeleted message comes after the Node has been removed from the NodeFactory cache.

Throws:

java.io.IOException

rename

public final Node rename(java.net.URL newURL)
                  throws java.io.IOException

This method renames the current node and recaches this Node under its new URL in the NodeFactory. The NodeListener event nodeDeleted is fired at the end of this process, after the Node has been recached under its new URL. The Node returned by this method is the Node at the new URL. Usually, this will be the same Node as 'this', but in cases where the Node type changes, the new Node will be returned.

Returns:

The new Node as a result of the rename.

Throws:

java.io.IOException

isOpen

public boolean isOpen()

Description copied from interface: LazyLoadable

Returns true if the object's data has already been loaded.

Specified by:

isOpen in interface LazyLoadable

isReadOnly

public boolean isReadOnly()

Returns true if the Node is read-only.

getTimestamp

public long getTimestamp()

Returns the timestamp associated with the Node, which indicates the time at which the Node was last modified. The returned long is expressed in milliseconds since 00:00:00 GMT Jan 1, 1970.

Returns:

the Node's time stamp.

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

Gets an InputStream that can be used to read the contents of the Node.

Returns:

an InputStream, or null if the document has no contents.

Throws:

java.net.UnknownServiceException - if the URL's protocol does not support input.

java.io.IOException - if an I/O error occurs when trying to open the InputStream.

java.lang.SecurityException - if a security manager exists and its checkRead method denies read access.

isNew

public final boolean isNew()

Returns true if the Node's data has never been saved.

toString

public java.lang.String toString()

Description copied from interface: Displayable

Returns the Short Label displayed to a user. This overrides the toString method in java.lang.Object.

Implementors of the Displayable interface should override this as appropriate. The default implementation is the same as getShortLabel

Specified by:

toString in interface Displayable

runWhileSynchronized

protected final void runWhileSynchronized(java.lang.Runnable runnable)

Executes the specified runnable implementation while under the Node's exclusive locking protection.

Parameters:

runnable - the runnable to execute while locked with the Node's locking

_getReadWriteLockInternal

protected final ReadWriteLock _getReadWriteLockInternal()

Fetch the lock instance used for Node state and data synchronization. The primary purpose of this routine is to provide additional flexibility to subclasses which contain additional data in their model (such as TextBuffer for TextNode) which requires locking that is coordinated with the locking in Node in such a way to avoid deadlock.

openImpl

protected void openImpl()
                 throws java.io.IOException

Subclasses should override this method to customize the open() behavior.

Throws:

java.io.IOException - if an I/O error occurred while opening

closeImpl

protected void closeImpl()
                  throws java.io.IOException

Subclasses should override this method to customize the close() behavior.

Throws:

java.io.IOException - if an I/O error occurred while closing

postCloseImpl

protected void postCloseImpl()

This method is called after nodeClosed(..) has been called on all registered NodeListeners. It allows a Node subtype to cleanup state that needs to remain available while NodeListener are being called but should get cleaned up before close() returns.

saveImpl

protected void saveImpl()
                 throws java.io.IOException

Subclasses should override this method to customize the save() behavior.

Throws:

java.io.IOException - if an I/O error occurred while saving

revertImpl

protected void revertImpl()
                   throws java.io.IOException

Subclasses should override this method to customize the revert() behavior.

Throws:

java.io.IOException - if an I/O error occurred while reverting

deleteImpl

protected void deleteImpl()
                   throws java.io.IOException

Subclasses should override this method to customize the delte() behavior. By the time deleteImpl() is called, the file has already been deleted from its URL location.

Throws:

java.io.IOException - if an I/O error occurred while deleting

renameImpl

protected void renameImpl(java.net.URL oldURL,
                          java.net.URL newURL)
                   throws java.io.IOException

Subclasses should override this method to customize the rename() behavior. By the time renameImpl() has been called, the file has already been renamed from its old URL to its new URL and recached in the NodeFactory under the new URL.

Throws:

java.io.IOException - if an I/O error occurred while renaming

equalsImpl

protected final boolean equalsImpl(Node node)

This is a helper method for)that can also be used by subclasses that implement). It assumes that the argument is not null.

Parameters:

node -

Returns:

setOpen

protected final void setOpen(boolean isOpen)

Protected accessor for the#_isOpenflag. This method must remain protected in order to avoid being picked up by theIntrospectoras a read/writeable JavaBean property.

Parameters:

isOpen -

refreshTimestamp

protected final long refreshTimestamp()

Protected method that can be used to refresh the timestamp of the Node based on the timestamp that can be obtained through the URL.

Returns:

the refreshed timestamp that is now associated with this Node.

setTimestampDirectly

protected final void setTimestampDirectly(long timestamp)

Accessor for allowing subclasses to set the timestamp directly.

ensureOpen

public final boolean ensureOpen()

Call this method to make sure that the Node is properly opened before accessing its data.

Returns:

true if the opening of the Node succeeded or if the Node was already open; false if an exception was caught while calling open().

reportOpenException

protected void reportOpenException(java.lang.Exception e)

This routine is given a chance to handle or report an Exception that occurred during open(). Note that clients that want to receive the IOException on open() should call open() directly instead of ensureOpen().