|
Oracle Fusion Middleware Java API Reference for Oracle Extension SDK 11g Release 2 (11.1.2.2.0) E17493-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
oracle.ide.model.Node
public class Node
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. |
|
|
callUnderReadLock(java.util.concurrent.Callable<V> callable) Calls a Callable while holding the node read lock. |
|
|
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 Element s 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 |
readLockInterruptibly() Read locks the node for the current thread. |
|
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. |
|
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 |
writeLockInterruptibly() Write locks the node for the current thread. |
|
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 |
---|
protected static final Log LOG_READONLY
Constructor Detail |
---|
public Node()
public Node(java.net.URL url)
URL
pointing to the persistent location of the Node
's contents.
url
- URL
identifying the persistent location of the Node
.Method Detail |
---|
protected ReadWriteLock nodeLock()
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.protected void readLock()
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.
protected void readLockInterruptibly() throws java.lang.InterruptedException
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.
java.lang.InterruptedException
- if the current thread is in or gets put in the interrupted state. The interrupted state is cleared when this exception is thrown.protected void readUnlock()
The Node
implementation invokes readUnlock()
on the node lock.
protected void writeLock()
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.
protected void writeLockInterruptibly() throws java.lang.InterruptedException
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.
java.lang.InterruptedException
- if the current thread is in or gets put in the interrupted state. The interrupted state is cleared when this exception is thrown.protected void writeUnlock()
The Node
implementation invokes writeUnlock()
on the node lock.
protected void upgradeLock()
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.
protected void upgradeUnlock()
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.protected final boolean isReadOrWriteLocked()
protected final boolean isReadLocked()
protected final boolean isWriteLocked()
protected final int lockCount()
protected final int readLockCount()
protected final int writeLockCount()
public static void addNodeListenerForType(java.lang.Class type, NodeListener listener)
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)
type
- the exact Node type whose events should be delivered to the listenerlistener
- the NodeListener
to registerpublic static void removeNodeListenerForType(java.lang.Class type, NodeListener listener)
addNodeListenerForType(Class,NodeListener)
.type
- the Node type for which the listener had been registeredlistener
- the NodeListener
to unregisterpublic static void addNodeListenerForTypeHierarchy(java.lang.Class type, NodeListener listener)
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)
.type
- the Node type (and its subtypes) whose events should be delivered to the listenerlistener
- the NodeListener
to registerpublic static void removeNodeListenerForTypeHierarchy(java.lang.Class type, NodeListener listener)
addNodeListenerForTypeHierarchy(Class,NodeListener)
.type
- the Node type for which the listener had been registeredlistener
- the NodeListener
to unregisterpublic final void addNodeListener(NodeListener listener)
listener
- the listener to addpublic final void removeNodeListener(NodeListener listener)
listener
- the listener to removepublic java.net.URL getURL()
Locatable
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.getURL
in interface Locatable
URL
identifying this Locatable
.public void setURL(java.net.URL newURL)
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.setURL
in interface Locatable
newURL
- The URL
to set.Locatable.setURL(URL)
protected boolean isTrackedInNodeCache()
true
. Node types that should not be tracked by the NodeFactory cache should override this method to return false
.true
if this Node should be tracked by the IDE's NodeFactory cache; false
otherwise.public boolean isDirty()
Dirtyable
isDirty
in interface Dirtyable
true
if the data in the object has been modified.public void markDirty(boolean dirty)
Dirtyable
markDirty(...)
instead of setDirty(...)
so that the JavaBeans Introspector
will not mistakenly identify "dirty" as a JavaBean property.markDirty
in interface Dirtyable
dirty
- If true
, sets the object as being dirty; if false
, sets the object as being up-to-date.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>".getShortLabel
in interface Displayable
Displayable
that can be shown to the user.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>".getLongLabel
in interface Displayable
Displayable
that can be shown to the user.public javax.swing.Icon getIcon()
Displayable
interface method. The Node class returns a generic icon.getIcon
in interface Displayable
Icon
to be displayed for the Displayable
.public java.lang.String getToolTipText()
Displayable
interface method. The Node class returns returns the String form of the currently set URL
.getToolTipText
in interface Displayable
Displayable
.public final void attach(Observer observer)
Subject
Subject
interface changes. Implementors should do nothing when the same observer is added more than once.attach
in interface Subject
observer
- the Observer
interested in change notification messages.public final void detach(Observer observer)
Subject
Subject
interface changes. Implementors should do nothing when the same observer is removed more than once.detach
in interface Subject
observer
- the Observer
disinterested in change notification messages.public void notifyObservers(java.lang.Object observed, UpdateMessage change)
Subject
notifyObservers
in interface Subject
observed
- the subject whose state has changed.change
- what changed.protected final Subject getSubject()
Subject
interface. This implementation returns an IdeSubject
but subclasses should override the createSubject
method in order to provide a different implementation of a Subject
.protected Subject createSubject()
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.public java.lang.Object getData()
Element
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
.getData
in interface Element
Element
instance.public boolean mayHaveChildren()
Element
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.
mayHaveChildren
in interface Element
true
if this Element
may contain child Element
s.public java.util.Iterator getChildren()
Element
Element
interface to provide a convenient way of getting an Iterator
over any contained child Element
s 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 Element
s or null
if there are no children.
getChildren
in interface Element
Iterator
over any child Element
s contained by this Element
. If there are no children, null
is returned.public Attributes getAttributes()
Element
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.getAttributes
in interface Element
public final java.util.Map getTransientProperties()
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.
public void open() throws java.io.IOException
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.
java.io.IOException
- Signals that an I/O exception occurred while trying to open this Node.public final void close() throws java.io.IOException
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.
java.io.IOException
- Signals that an I/O exception occurred while trying to close this Node.public final void save() throws java.io.IOException
java.io.IOException
- Signals that an I/O exception of some sort occurred.public final void revert() throws java.io.IOException
java.io.IOException
public final void delete()
public final Node rename(java.net.URL newURL) throws java.io.IOException
java.io.IOException
public final boolean isOpen()
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.
isOpen
in interface LazyLoadable
public boolean isReadOnly()
true
if the Node is read-only.public boolean setReadOnly(boolean readOnly)
protected void urlReadOnlyChanged()
Node
implementation is empty.public final boolean isMigrating()
true
if the Node is currently in the process of being migrated.protected final void setMigrating()
protected final void unsetMigrating(boolean fireEvents)
fireEvents
must be set to false. This will repress the unnecessary firing of node events.public final long getTimestamp()
public final long getUnmodifiedTimestamp()
protected final long refreshTimestamp()
This should be invoked under a write lock, but that is not yet enforced.
protected final void setTimestampDirectly(long timestamp)
This should be invoked under a write lock, but that is not yet enforced.
public final long getTimestampLoadedUnsafe()
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.
public java.io.InputStream getInputStream() throws java.io.IOException
InputStream
that can be used to read the contents of the Node.InputStream
, or null
if the document has no contents.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.public final boolean isNew()
true
if the Node's data has never been saved.public java.lang.String toString()
Displayable
toString
method in java.lang.Object
.
Implementors of the Displayable
interface should override this as appropriate. The default implementation is the same as getShortLabel
toString
in interface Displayable
toString
in class java.lang.Object
Object.toString()
, Displayable.getShortLabel()
public final void runUnderReadLock(java.lang.Runnable runnable)
Runnable
while holding the node read lock.public final void runUnderWriteLock(java.lang.Runnable runnable)
Runnable
while holding the node write lock.public final <V> V callUnderReadLock(java.util.concurrent.Callable<V> callable) throws java.lang.Exception
Callable
while holding the node read lock.java.lang.Exception
public final <V> V callUnderWriteLock(java.util.concurrent.Callable<V> callable) throws java.lang.Exception
Callable
while holding the node write lock.java.lang.Exception
public final boolean tryRunUnderReadLock(java.lang.Runnable runnable)
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
.runnable
- the runnable to executetrue
if the read lock was available, false
otherwisepublic static void beginThreadNodeUsageCycle()
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.
public static void endThreadNodeUsageCycle()
beginThreadNodeUsageCycle()
public static void endThreadNodeUsage(Node node)
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.
beginThreadNodeUsageCycle()
protected void openImpl() throws java.io.IOException
open()
invokes this only if the node is not open, under write lock. The Node
implementation does nothing.java.io.IOException
- if an I/O error occurred while openingprotected void closeImpl() throws java.io.IOException
close()
invokes this only if the node is open, under write lock. The Node
implementation does nothing.java.io.IOException
- if an I/O error occurred while closingprotected void markDirtyImpl(boolean dirty)
markDirty(boolean)
invokes this only if the dirty state is changing, under write lock. The Node
implementation does nothing.protected void saveImpl() throws java.io.IOException
save()
invokes this only if the node is dirty, under write lock. The Node
implementation does nothing.java.io.IOException
- if an I/O error occurred while savingprotected void revertImpl() throws java.io.IOException
revert()
invokes this only if the node is dirty, under write lock. The Node
implementation invokes closeImpl()
followed by openImpl()
.java.io.IOException
- if an I/O error occurred while revertingprotected void deleteImpl() throws java.io.IOException
Node
invokes this under write lock. The Node
implementation does nothing.java.io.IOException
- if an I/O error occurred while deletingprotected void renameImpl(java.net.URL oldURL, java.net.URL newURL) throws java.io.IOException
Node
invokes this under write lock. The Node
implementation does nothing.java.io.IOException
- if an I/O error occurred while renamingprotected final boolean equalsImpl(Node node)
)
that can also be used by subclasses that implement)
.node
-protected final void setOpen(boolean open)
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.
public final boolean ensureOpen()
open()
.protected void reportOpenException(java.lang.Exception e)
public final boolean isLoaded()
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.
public void setEventLog(Log log)
|
Oracle Fusion Middleware Java API Reference for Oracle Extension SDK 11g Release 2 (11.1.2.2.0) E17493-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |