Oracle Fusion Middleware Java API Reference for Oracle Extension SDK Reference
11g Release 1 (11.1.1.7.0)

E13403-08

oracle.ide.model
Class Node

java.lang.Object
  extended by oracle.ide.model.Node
All Implemented Interfaces:
Displayable, Element, LazyLoadable, Locatable, Subject, Dirtyable
Direct Known Subclasses:
BaseDBObjectNode, DataContainer, DataNode, DefaultContainer, ImageNode, Layout, LibraryDataNode, RegisteredDynamicNode, TextNode, VersionHistoryNode, XMLDataNode

public class Node
extends java.lang.Object
implements Locatable, Element, Subject, Dirtyable, LazyLoadable

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

Locking
Node uses a ReadWriteLock to protect most of its state (it would be better to use if for all state, but with current usage patterns, using the lock for some getters frequently causes deadlocks).


Field Summary
protected static Log LOG_READONLY
           
 
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
 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.
static void beginThreadNodeUsageCycle()
          Begins a processing cycle of a background thread which loads nodes.
<V> V
callUnderReadLock(java.util.concurrent.Callable<V> callable)
          Calls a Callable while holding the node read lock.
<V> V
callUnderWriteLock(java.util.concurrent.Callable<V> callable)
          Calls a Callable while holding the node write lock.
 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 delete() 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.
static void endThreadNodeUsage(Node node)
          Ends the usage of a particular node within a processing cycle of a background thread which loads nodes, closing the node if loaded by the background thread and not used by any other thread.
static void endThreadNodeUsageCycle()
          Ends a processing cycle of a background thread which loads nodes, closing any nodes loaded by the the background thread and not used by any other thread.
 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()
          Gets the timestamp of this node.
 long getTimestampLoadedUnsafe()
          Gets the time stamp of this loaded node, or -1 if the node is not loaded.
 java.lang.String getToolTipText()
          Displayable interface method.
 java.util.Map getTransientProperties()
          This method returns a Map that the caller can use to store 'transient' properties with the Node instance.
 long getUnmodifiedTimestamp()
          Gets the timestamp of this node.
 java.net.URL getURL()
          Returns the URL that identifies this Locatable.
 boolean isDirty()
          True if the data in the object has been modified.
 boolean isLoaded()
          Gets whether the node has reached the loaded state.
 boolean isMigrating()
          Returns true if the Node is currently in the process of being migrated.
 boolean isNew()
          Returns true if the Node's data has never been saved.
 boolean isOpen()
          Gets whether the node has reached the open state.
protected  boolean isReadLocked()
           
 boolean isReadOnly()
          Returns true if the Node is read-only.
protected  boolean isReadOrWriteLocked()
           
protected  boolean isTrackedInNodeCache()
          The return value of this method indicates whether this Node should be tracked by the NodeFactory cache.
protected  boolean isWriteLocked()
           
protected  int lockCount()
           
 void markDirty(boolean dirty)
          Marks the data with the specified dirty state.
protected  void markDirtyImpl(boolean dirty)
          Subclasses should override this method to customize the markDirty() behavior.
 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.
protected  ReadWriteLock nodeLock()
          Gets the node lock, a ReadWriteLock used to protect node state.
 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 readLock()
          Read locks the node for the current thread.
protected  int readLockCount()
           
protected  void readUnlock()
          Read unlocks the node for the current thread.
protected  long refreshTimestamp()
          Resets the node timestamp to the last modified time of 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.
 void runUnderReadLock(java.lang.Runnable runnable)
          Executes a Runnable while holding the node read lock.
 void runUnderWriteLock(java.lang.Runnable runnable)
          Executes a Runnable while holding the node write lock.
 void save()
          Saves the contents of the Node.
protected  void saveImpl()
          Subclasses should override this method to customize the save() behavior.
 void setEventLog(Log log)
           
protected  void setMigrating()
          This method tells the node that it is in the process of being migrated.
protected  void setOpen(boolean open)
          Opens or closes the node without invoking the subclass implementation methods (loadImpl(), @link #openImpl}, closeImpl(), and/or unloadImpl()).
 boolean setReadOnly(boolean readOnly)
          Sets whether this node is read-only.
protected  void setTimestampDirectly(long timestamp)
          Sets the timestamp of this node.
 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.
 boolean tryRunUnderReadLock(java.lang.Runnable runnable)
          Executes a Runnable while holding the node read lock, if available.
 boolean tryRunUnderWriteLock(java.lang.Runnable runnable)
          Executes a Runnable while holding the node write lock, if available.
protected  void unsetMigrating(boolean fireEvents)
          This method tells the node that it has been migrated.
protected  void upgradeLock()
          Write locks the node for the current thread, upgrading a read lock if necessary.
protected  void upgradeUnlock()
          Write locks the node for the current thread.
protected  void urlReadOnlyChanged()
          Reports that the read-only state of the URL of this node changed.
protected  void writeLock()
          Write locks the node for the current thread.
protected  int writeLockCount()
           
protected  void writeUnlock()
          Read unlocks the node for the current thread.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LOG_READONLY

protected static final Log LOG_READONLY
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

nodeLock

protected ReadWriteLock nodeLock()
Gets the node lock, a ReadWriteLock used to protect node state. This object is exposed for subclasses that use this lock to protect their content models, e.g. TextNode and TextBuffer, or XmlSourceNode and XmlModel. For use strictly inside a Node subclass, use readLock(), writeLock() and related methods instead.


readLock

protected void readLock()
Read locks the node for the current thread. The proper pattern for calling this method is:
 readLock();
 try
 {
   // access protected state...
 }
 finally
 {
   readUnlock();
 }
 
Note that a number of Node extensions points are called with a read or write lock held, and are so documented.

The Node implementation invokes readLock() on the node lock.


readUnlock

protected void readUnlock()
Read unlocks the node for the current thread. The node must have been locked on the current thread.

The Node implementation invokes readUnlock() on the node lock.


writeLock

protected void writeLock()
Write locks the node for the current thread. The node must not be read locked on the current thread. The proper pattern for calling this method is:
 writeLock();
 try
 {
   // access and/or update protected state...
 }
 finally
 {
   writeUnlock();
 }
 
Note that a number of Node extension points are called with a read or write lock held, and are so documented.

The Node implementation invokes writeLock() on the node lock.


writeUnlock

protected void writeUnlock()
Read unlocks the node for the current thread. The node must have been locked on the current thread.

The Node implementation invokes writeUnlock() on the node lock.


upgradeLock

protected void upgradeLock()
Write locks the node for the current thread, upgrading a read lock if necessary. Any read locks held by the current thread will be briefly dropped as part of upgrading, so any protected state that was checked under the read lock must be rechecked before proceeding. The proper pattern for calling this method is:
 upgradeLock();
 try
 {
   // recheck preconditions in protected state that were checked under read lock
   // access and/or update protected state...
 }
 finally
 {
   upgradeUnlock();
 }
 
Note that a number of Node extensions points are called with a read or write lock held, and are so documented.

The primary use of this method is allow the node to be safely loaded or opened in circumstances where the thread already holds a read lock.

The Node implementation invokes readUnlock() iteratively to reduce the number of read locks held by the current thread to zero; invokes writeUnlock() on the node lock; and then invokes readLock() iteratively to restore the number of read locks held to its initial number.


upgradeUnlock

protected void upgradeUnlock()
Write locks the node for the current thread. The proper pattern for calling this method is:
 writeLock();
 try
 {
   // access and/or update protected state...
 }
 finally
 {
   writeUnlock();
 }
 
Note that a number of Node extensions points are called with a read or write lock held, and are so documented.


isReadOrWriteLocked

protected final boolean isReadOrWriteLocked()

isReadLocked

protected final boolean isReadLocked()

isWriteLocked

protected final boolean isWriteLocked()

lockCount

protected final int lockCount()

readLockCount

protected final int readLockCount()

writeLockCount

protected final int writeLockCount()

addNodeListenerForType

public 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. 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 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 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 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()
Description copied from interface: Dirtyable
True if the data in the object has been modified.

Specified by:
isDirty in interface Dirtyable
Returns:
true if the data in the object has been modified.

markDirty

public void markDirty(boolean dirty)
Description copied from interface: Dirtyable
Marks the data with the specified dirty state. This method is called markDirty(...) instead of setDirty(...) so that the JavaBeans Introspector will not mistakenly identify "dirty" as a JavaBean property.

Specified by:
markDirty in interface Dirtyable
Parameters:
dirty - If true, sets the object as being dirty; if false, sets the object as being up-to-date.

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. If the implementation returns an object other than this, be sure to set ElementAttributes.DECORATES_DATA_ELEMENT.

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

getTransientProperties

public final java.util.Map getTransientProperties()
This method returns a Map that the caller can use to store 'transient' properties with the Node instance. Transient properties are not persistent, so they do not affect the dirty flag. They also have no effect on the result of calling Object.equals(Object) and they are not copied by copyToImpl(Node). Null keys and values are not supported by the returned Map.

Transient properties are available while the Node is in the loaded or opened state. Once a Node transitions to the unloaded state, its transient properties are also discarded.

While a close() operation is in progress, the Node remains in the loaded state while processing closeImpl() and calling the nodeClosed(..) method on all registered NodeListeners. It's not until after nodeClosed(..) that the Node is unloaded. This means that the transient properties are still available to a NodeListener during nodeClosed(..).

Using a NodeListener is also the recommended approach for initializing a transient property in response to the Node opening.


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


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 final boolean isOpen()
Gets whether the node has reached the open state.

Note that unless the calling thread holds a read or write lock, the actual state of the node may have changed by the time the calling thread processes the returned value.

Specified by:
isOpen in interface LazyLoadable

isReadOnly

public boolean isReadOnly()
Returns true if the Node is read-only.


setReadOnly

public boolean setReadOnly(boolean readOnly)
Sets whether this node is read-only. The return value indicates whether or not the setting of the read-only flag succeeded.

Returns:
true of the setting of the read-only status flag succeeded

urlReadOnlyChanged

protected void urlReadOnlyChanged()
Reports that the read-only state of the URL of this node changed. The Node implementation is empty.


isMigrating

public final boolean isMigrating()
Returns true if the Node is currently in the process of being migrated.


setMigrating

protected final void setMigrating()
This method tells the node that it is in the process of being migrated. While the node is being migrated, all event firing is supressed.


unsetMigrating

protected final void unsetMigrating(boolean fireEvents)
This method tells the node that it has been migrated. If the setMigrating() method is called, the unsetMigrating() method must also be called when migration is completed. If the node was not migrated, the parameter fireEvents must be set to false. This will repress the unnecessary firing of node events.


getTimestamp

public final long getTimestamp()
Gets the timestamp of this node. When the node is loaded or open, this timestamp indicates the time of last modification. The returned long is the number of milliseconds since the epoch (00:00:00 GMT Jan 1, 1970).


getUnmodifiedTimestamp

public final long getUnmodifiedTimestamp()
Gets the timestamp of this node. When the node is loaded or open, this timestamp indicates the time of last modification. The returned long is the number of milliseconds since the epoch (00:00:00 GMT Jan 1, 1970).


refreshTimestamp

protected final long refreshTimestamp()
Resets the node timestamp to the last modified time of the URL.

This should be invoked under a write lock, but that is not yet enforced.

Returns:
the new timestamp of this node (the number of milliseconds since the epoch (00:00:00 GMT Jan 1, 1970).

setTimestampDirectly

protected final void setTimestampDirectly(long timestamp)
Sets the timestamp of this node.

This should be invoked under a write lock, but that is not yet enforced.


getTimestampLoadedUnsafe

public final long getTimestampLoadedUnsafe()
Gets the time stamp of this loaded node, or -1 if the node is not loaded.

This method is regarded as "unsafe" because it does not block if invoked while the node is changing state and is generally only well-suited for background scanning threads and the like.


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
Overrides:
toString in class java.lang.Object
See Also:
Object.toString(), Displayable.getShortLabel()

runUnderReadLock

public final void runUnderReadLock(java.lang.Runnable runnable)
Executes a Runnable while holding the node read lock.


runUnderWriteLock

public final void runUnderWriteLock(java.lang.Runnable runnable)
Executes a Runnable while holding the node write lock.


callUnderReadLock

public final <V> V callUnderReadLock(java.util.concurrent.Callable<V> callable)
                          throws java.lang.Exception
Calls a Callable while holding the node read lock.

Throws:
java.lang.Exception

callUnderWriteLock

public final <V> V callUnderWriteLock(java.util.concurrent.Callable<V> callable)
                           throws java.lang.Exception
Calls a Callable while holding the node write lock.

Throws:
java.lang.Exception

tryRunUnderReadLock

public final boolean tryRunUnderReadLock(java.lang.Runnable runnable)
Executes a Runnable while holding the node read lock, if available. If the lock is not available, the Runnable is not run, and the method will return false.

Parameters:
runnable - the runnable to execute
Returns:
true if the read lock was available, false otherwise

tryRunUnderWriteLock

public final boolean tryRunUnderWriteLock(java.lang.Runnable runnable)
Executes a Runnable while holding the node write lock, if available. If the lock is not available, the Runnable is not run, and the method will return false.

Parameters:
runnable - the runnable to execute
Returns:
true if the write lock was available, false otherwise

beginThreadNodeUsageCycle

public static void beginThreadNodeUsageCycle()
Begins a processing cycle of a background thread which loads nodes.

For a background thread, closing nodes that it loads is problematic, because (1) it may not be aware of what nodes it loads and (2) even for nodes it is aware of, it cannot be sure that another node hasn't started using the node during the processing cycle (load, unload, open, and close are not reference counted).

beginThreadNodeUsageCycle() and endThreadNodeUsageCycle() allow a background thread to demarcate its processing cycle. The begin method begins tracking node usage by thread, the end method removes any methods loaded by the background thread and not loaded or otherwise accessed by any other thread.

{@link


endThreadNodeUsageCycle

public static void endThreadNodeUsageCycle()
Ends a processing cycle of a background thread which loads nodes, closing any nodes loaded by the the background thread and not used by any other thread.

See Also:
beginThreadNodeUsageCycle()

endThreadNodeUsage

public static void endThreadNodeUsage(Node node)
Ends the usage of a particular node within a processing cycle of a background thread which loads nodes, closing the node if loaded by the background thread and not used by any other thread.

This method allows a background thread which explicitly loads nodes to explicitly close them, if no other thread accesses them, sooner than the end of the processing cycle.

See Also:
beginThreadNodeUsageCycle()

openImpl

protected void openImpl()
                 throws java.io.IOException
Subclasses should override this method to customize the open() behavior. open() invokes this only if the node is not open, under write lock. The Node implementation does nothing.

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. close() invokes this only if the node is open, under write lock. The Node implementation does nothing.

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

markDirtyImpl

protected void markDirtyImpl(boolean dirty)
Subclasses should override this method to customize the markDirty() behavior. markDirty(boolean) invokes this only if the dirty state is changing, under write lock. The Node implementation does nothing.


saveImpl

protected void saveImpl()
                 throws java.io.IOException
Subclasses should override this method to customize the save() behavior. save() invokes this only if the node is dirty, under write lock. The Node implementation does nothing.

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. revert() invokes this only if the node is dirty, under write lock. The Node implementation invokes closeImpl() followed by openImpl().

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 delete() behavior. By the time deleteImpl() is called, the file has already been deleted from its URL location. Node invokes this under write lock. The Node implementation does nothing.

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. Node invokes this under write lock. The Node implementation does nothing.

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).

Parameters:
node -

setOpen

protected final void setOpen(boolean open)
Opens or closes the node without invoking the subclass implementation methods (loadImpl(), @link #openImpl}, closeImpl(), and/or unloadImpl()).

The old implementation simply set a flag, entirely subverting the node state machinery. The current implementation executes all the normal open or close processing, except that it does not invoke the implementation methods. The main difference is that now all the usual state transition events are fired; a consequence of this is that a read lock is always acquired, and if a state transition is necessary, the write lock is acquired.


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


isLoaded

public final boolean isLoaded()
Gets whether the node has reached the loaded state.

Note that unless the calling thread holds a read or write lock, the actual state of the node may have changed by the time the calling thread processes the returned value.


setEventLog

public void setEventLog(Log log)

Oracle Fusion Middleware Java API Reference for Oracle Extension SDK Reference
11g Release 1 (11.1.1.7.0)

E13403-08

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