oracle.ide.model
Class TextNode

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

All Implemented Interfaces:

Displayable, Element, LazyLoadable, Locatable, Subject, Dirtyable

Direct Known Subclasses:

BaseDBObjectTextNode, DeployableTextNode, PatchNode, TextMergeNode

public class TextNode
extends Node

A base class for Nodes representing text files.

Locking
Node uses a ReadWriteLock to protect most of its state; TextNode uses the same lock to protect its state, including its text content.

Memory Management
{@link TextNode} must avoid avoid pinning large numbers of {@link TextBuffer}s, holding large amounts of character data, in memory. The chosen mechanism is to automatically close a node, releasing the text buffer, as soon as all clients using it have dropped their references. Doing this requires some trickery: TextNode never dispenses the real text buffer, but instead dispenses a facade which it holds only with a weak reference, and polls the reference queue to detect when the facade is garbage collected. When this happens, the node is closed and node closed events are fired. When the node is dirty, this mechanism is disabled.

Field Summary

Fields inherited from class oracle.ide.model.Node

LOG_READONLY

Constructor Summary

TextNode()
Creates a text node with an undefined URL.

TextNode(java.net.URL url)
Creates a text node.

Method Summary

TextBuffer	acquireTextBuffer() Gets a TextBuffer with the content of this node, or null if the content cannot be loaded.
TextBuffer	acquireTextBufferOrThrow() Gets a TextBuffer with the content of this node.
boolean	addTextBufferListener(TextBufferListener listener) Adds a text buffer listener to the text buffer of this node whether or not the node is open.
protected void	closeImpl() Subclasses should override this method to customize the close() behavior.
protected java.io.OutputStreamWriter	createOutputStreamWriter(java.io.OutputStream outStream)
protected java.io.Reader	createReader(java.net.URL url) Fetch a Reader for reading the contents of this node from the given URL.
java.io.InputStream	getInputStream() Deprecated.
java.io.InputStream	getInputStream(boolean warn) Deprecated.
java.lang.String	getLoadEncoding() Returns a Java supported encoding name to use to create the InputStreamReader for reading data from the URL into the TextBuffer (called from revert()).
java.io.Reader	getReader() Fetch a Reader for accessing the buffer contents of this TextNode.
java.lang.String	getSaveEncoding() Returns a Java supported encoding name to use to create the OutputStreamWriter for writing the TextBuffer to a file (called from save()).
protected TextBuffer	getTextBufferDirectly() Gets the text buffer if the node is open, or null if not.
boolean	hasEmptyTextBuffer() Gets whether the TextBuffer for this TextNode is empty.
boolean	isDirty() First checks if the superclass has its dirty flag set; if so, returns true.
boolean	isReadOnly() Returns true if the Node is read-only.
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.
protected void	openImpl() Subclasses should override this method to customize the open() behavior.
protected void	readUnlock() Read unlocks the node for the current thread.
void	releaseTextBuffer() Informs the document that the previously acquired TextBuffer instance is no longer needed.
void	removeTextBufferListener(TextBufferListener listener) Removes a text buffer listener from the text buffer of this node.
protected void	reportOpenException(java.lang.Exception e) This routine is given a chance to handle or report an Exception that occurred during open().
protected void	revertImpl() Subclasses should override this method to customize the revert() behavior.
protected void	saveImpl() Subclasses should override this method to customize the save() behavior.
protected void	setDefaultLineTerminator(TextBuffer textBuffer) Sets up the default line terminator to use for the text buffer.
void	setLoadEncoding(java.lang.String loadEncoding) Sets a Java supported encoding name to use to create the InputStreamReader for reading data from the URL into the TextBuffer (called from revert()).
void	setSaveEncoding(java.lang.String saveEncoding) Sets a Java supported encoding name to use to create the OutputStreamWriter for writing the TextBuffer to a file (called from save()).
TextBuffer	tryAcquireTextBuffer() Non-blocking version of acquireTextBuffer().
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	writeUnlock() Read unlocks the node for the current thread.

Methods inherited from class oracle.ide.model.Node

addNodeListener, addNodeListenerForType, addNodeListenerForTypeHierarchy, attach, beginThreadNodeUsageCycle, callUnderReadLock, callUnderWriteLock, close, createSubject, delete, deleteImpl, detach, endThreadNodeUsage, endThreadNodeUsageCycle, ensureOpen, equalsImpl, getAttributes, getChildren, getData, getIcon, getLongLabel, getShortLabel, getSubject, getTimestamp, getTimestampLoadedUnsafe, getToolTipText, getTransientProperties, getUnmodifiedTimestamp, getURL, isLoaded, isMigrating, isNew, isOpen, isReadLocked, isReadOrWriteLocked, isTrackedInNodeCache, isWriteLocked, lockCount, mayHaveChildren, nodeLock, notifyObservers, open, readLock, readLockCount, refreshTimestamp, removeNodeListener, removeNodeListenerForType, removeNodeListenerForTypeHierarchy, rename, renameImpl, revert, runUnderReadLock, runUnderWriteLock, save, setEventLog, setMigrating, setOpen, setReadOnly, setTimestampDirectly, setURL, toString, tryRunUnderReadLock, unsetMigrating, upgradeLock, writeLock, writeLockCount

Methods inherited from class java.lang.Object

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

Constructor Detail

TextNode

public TextNode()

Creates a text node with an undefined URL.

TextNode

public TextNode(java.net.URL url)

Creates a text node.

Parameters:

url - The URL of the file represented by this node. The URL need not represent an existing file.

Method Detail

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. Overridden to clear facadeBuffer when the node is not dirty and the current thread releases its last lock.

Overrides:

readUnlock in class Node

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. Overridden to clear facadeBuffer when the node is not dirty and the current thread releases its last lock.

Overrides:

writeUnlock in class Node

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. Overridden to clear facadeBuffer when the node is not dirty and the current thread releases its last lock.

Overrides:

upgradeUnlock in class Node

urlReadOnlyChanged

protected void urlReadOnlyChanged()

Description copied from class: Node

Reports that the read-only state of the URL of this node changed. The Node implementation is empty.

Overrides:

urlReadOnlyChanged in class Node

isReadOnly

public boolean isReadOnly()

Returns true if the Node is read-only.

TextNode overrides to force the underlying buffer to be read only.

Overrides:

isReadOnly in class Node

See Also:

Node.isReadOnly()

isDirty

public boolean isDirty()

First checks if the superclass has its dirty flag set; if so, returns true. Otherwise, the determination of the dirty state is delegated to the underlying TextBuffer implementation. If the current TextBuffer is null, false is returned.

Specified by:

isDirty in interface Dirtyable

Overrides:

isDirty in class Node

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

Overrides:

markDirty in class Node

Parameters:

dirty - If true, sets the object as being dirty; if false, sets the object as being up-to-date.

markDirtyImpl

protected void markDirtyImpl(boolean dirty)

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

The TextNode implementation clears the modified property of the text buffer if the node is open and the dirty state is cleared.

Overrides:

markDirtyImpl in class Node

openImpl

protected void openImpl()
                 throws java.io.IOException

Description copied from class: Node

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

Overrides:

openImpl in class Node

Throws:

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

closeImpl

protected void closeImpl()
                  throws java.io.IOException

Description copied from class: Node

Subclasses should override this method to customize the close() behavior. Node.close() invokes this only if the node is open, under write lock. The Node implementation does nothing.

Overrides:

closeImpl in class Node

Throws:

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

saveImpl

protected void saveImpl()
                 throws java.io.IOException

Description copied from class: Node

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

Overrides:

saveImpl in class Node

Throws:

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

revertImpl

protected void revertImpl()
                   throws java.io.IOException

Description copied from class: Node

Subclasses should override this method to customize the revert() behavior. Node.revert() invokes this only if the node is dirty, under write lock. The Node implementation invokes Node.closeImpl() followed by Node.openImpl().

Overrides:

revertImpl in class Node

Throws:

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

setDefaultLineTerminator

protected void setDefaultLineTerminator(TextBuffer textBuffer)

Sets up the default line terminator to use for the text buffer. Note that the TextNode will still use the regular behavior of maintaining the EOL for existing files.

Parameters:

textBuffer - the text buffer that backs up the contents of this node

acquireTextBuffer

public final TextBuffer acquireTextBuffer()

Gets a TextBuffer with the content of this node, or null if the content cannot be loaded.

acquireTextBufferOrThrow

public final TextBuffer acquireTextBufferOrThrow()
                                          throws java.io.IOException

Gets a TextBuffer with the content of this node.

Throws:

java.io.IOException - if the content cannot be loaded.

tryAcquireTextBuffer

public final TextBuffer tryAcquireTextBuffer()

Non-blocking version of acquireTextBuffer(). Returns null immediately if the buffer cannot be obtained without blocking.

Returns:

the TextBuffer instance, or null if the buffer could not be obtained without blocking

releaseTextBuffer

public final void releaseTextBuffer()

Informs the document that the previously acquired TextBuffer instance is no longer needed. This frees up the need for the Document to maintain the TextBuffer instance.

getTextBufferDirectly

protected TextBuffer getTextBufferDirectly()

Gets the text buffer if the node is open, or null if not. A subclass which needs to ensure that the node is not opened between the call to this method and the test of the return value should protect the call and test with the text buffer lock.

addTextBufferListener

public boolean addTextBufferListener(TextBufferListener listener)

Adds a text buffer listener to the text buffer of this node whether or not the node is open. Unlike acquireTextBuffer().addTextBufferListener(), this method does not open the node if it is not already open.

Be aware that all text buffer listeners are cleared when the node is closed. Typically, a client using this method from outside of a NodeListener should already have added a NodeListener that will add this text buffer listener on node opened (possibly redundantly).

Also be aware that if the node is not open and never gets opened, the text buffer listeners will never be cleared. Typically, a client using this method when the node may be closed will protect itself against leaking the listener by explicitly removing this text buffer listener as soon as it is no longer needed.

Parameters:

listener - The text buffer listener.

Returns:

whether the listener was actually added.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

removeTextBufferListener

public void removeTextBufferListener(TextBufferListener listener)

Removes a text buffer listener from the text buffer of this node.

Parameters:

listener - The text buffer listener.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

getReader

public java.io.Reader getReader()
                         throws java.io.IOException

Fetch a Reader for accessing the buffer contents of this TextNode. The TextBuffer will be locked with a read-level lock for the life of this Reader. Clients must remember to close this Reader instance when it is no longer needed to avoid holding the read-level lock for longer than necessary.

Returns:

a Reader for accessing the buffer contents of this node

Throws:

java.io.IOException

hasEmptyTextBuffer

public boolean hasEmptyTextBuffer()

Gets whether the TextBuffer for this TextNode is empty.

getLoadEncoding

public java.lang.String getLoadEncoding()

Returns a Java supported encoding name to use to create the InputStreamReader for reading data from the URL into the TextBuffer (called from revert()). The base implementation returns the explicitly set encoding, or the IDE default encoding. Subclasses (like XMLSourceNode) may override this with a different encoding determined from the URL data

Returns:

a Java supported encoding name for reading

getSaveEncoding

public java.lang.String getSaveEncoding()

Returns a Java supported encoding name to use to create the OutputStreamWriter for writing the TextBuffer to a file (called from save()). The base implementation returns the explicitly set encoding, or the IDE default encoding. Subclasses (like XMLSourceNode) may override this with a different encoding determined from the TextBuffer data

Returns:

a Java supported encoding name for writing

setLoadEncoding

public void setLoadEncoding(java.lang.String loadEncoding)

Sets a Java supported encoding name to use to create the InputStreamReader for reading data from the URL into the TextBuffer (called from revert()). This default encoding will be effective if a subclass does not override getLoadEncoding() with a different encoding determined from the TextBuffer data

Parameters:

loadEncoding - a Java supported encoding name for reading

setSaveEncoding

public void setSaveEncoding(java.lang.String saveEncoding)

Sets a Java supported encoding name to use to create the OutputStreamWriter for writing the TextBuffer to a file (called from save()). This default encoding will be effective if a subclass does not override getSaveEncoding() with a different encoding determined from the TextBuffer data

Parameters:

saveEncoding - a Java supported encoding name for writing

createReader

protected java.io.Reader createReader(java.net.URL url)
                               throws java.io.IOException

Fetch a Reader for reading the contents of this node from the given URL. Subclasses may override this if they have special requirements for creating the Reader.

Parameters:

url - the URL to fetch a Reader for

Returns:

a Reader for loading the contents of this node from storage

Throws:

java.io.IOException

createOutputStreamWriter

protected java.io.OutputStreamWriter createOutputStreamWriter(java.io.OutputStream outStream)
                                                       throws java.io.UnsupportedEncodingException

Throws:

java.io.UnsupportedEncodingException

getInputStream

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

Deprecated.

NOTE: Use of TextNode.getInputStream() is highly discouraged because of the NLS issues raised by using byte streams for text and the associated poor performance caused by char-to-byte conversion. Use TextNode.getReader() instead whenever possible.

Returns an InputStream that's backed by the current TextBuffer.

Overrides:

getInputStream in class Node

Returns:

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

Throws:

java.lang.IllegalStateException - if the current TextBuffer is null.

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.

getInputStream

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

Deprecated.

NOTE: Use of TextNode.getInputStream() is highly discouraged because of the NLS issues raised by using byte streams for text and the associated poor performance caused by char-to-byte conversion. Use TextNode.getReader() instead whenever possible.

Returns an InputStream that's backed by the current TextBuffer.

Throws:

java.lang.IllegalStateException - if the current TextBuffer is null.

java.io.IOException

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

Overrides:

reportOpenException in class Node