An abstract base implementation for the
Document
interface.
This class provides some common functionality for all
Element
s,
most notably it implements a locking mechanism to make document modification
thread-safe.
createBranchElement
protected Element createBranchElement(Element parent,
AttributeSet attributes)
Creates and returns a branch element with the specified
parent
and
attributes
. Note that the new
Element
is linked to the parent
Element
through
Element.getParentElement()
, but it is not yet added
to the parent
Element
as child.
parent
- the parent Element
for the new branch elementattributes
- the text attributes to be installed in the new element
createLeafElement
protected Element createLeafElement(Element parent,
AttributeSet attributes,
int start,
int end)
Creates and returns a leaf element with the specified
parent
and
attributes
. Note that the new
Element
is linked to the parent
Element
through
Element.getParentElement()
, but it is not yet added
to the parent
Element
as child.
parent
- the parent Element
for the new branch elementattributes
- the text attributes to be installed in the new element
dump
public void dump(PrintStream out)
Dumps diagnostic information to the specified PrintStream
.
out
- the stream to write the diagnostic information to
fireChangedUpdate
protected void fireChangedUpdate(DocumentEvent event)
Notifies all registered listeners when the document model changes.
event
- the DocumentEvent
to be fired
fireInsertUpdate
protected void fireInsertUpdate(DocumentEvent event)
Notifies all registered listeners when content is inserted in the document
model.
event
- the DocumentEvent
to be fired
fireRemoveUpdate
protected void fireRemoveUpdate(DocumentEvent event)
Notifies all registered listeners when content is removed from the
document model.
event
- the DocumentEvent
to be fired
fireUndoableEditUpdate
protected void fireUndoableEditUpdate(UndoableEditEvent event)
Notifies all registered listeners when an UndoableEdit
has
been performed on this Document
.
event
- the UndoableEditEvent
to be fired
getAsynchronousLoadPriority
public int getAsynchronousLoadPriority()
Returns the asynchronous loading priority. Returns -1
if this
document should not be loaded asynchronously.
- the asynchronous loading priority
getBidiRootElement
public Element getBidiRootElement()
Returns the root element for bidirectional content.
- the root element for bidirectional content
getCurrentWriter
protected Thread getCurrentWriter()
Returns the thread that currently modifies this Document
if there is one, otherwise null
. This can be used to
distinguish between a method call that is part of an ongoing modification
or if it is a separate modification for which a new lock must be aquired.
- the thread that currently modifies this
Document
if there is one, otherwise null
getDefaultRootElement
public abstract Element getDefaultRootElement()
Returns the default root
Element
of this
Document
.
Usual
Document
s only have one root element and return this.
However, there may be
Document
implementations that
support multiple root elements, they have to return a default root element
here.
- getDefaultRootElement in interface Document
- the default root
Element
of this Document
getLength
public int getLength()
Returns the length of this Document
's content.
- getLength in interface Document
- the length of this
Document
's content
getListeners
public EventListener[] getListeners(Class listenerType)
Returns all registered listeners of a given listener type.
listenerType
- the type of the listeners to be queried
- all registered listeners of the specified type
getParagraphElement
public abstract Element getParagraphElement(int pos)
Returns the paragraph
Element
that holds the specified position.
pos
- the position for which to get the paragraph element
- the paragraph
Element
that holds the specified position
getProperty
public Object getProperty(Object key)
Returns a property from this Document
's property list.
- getProperty in interface Document
key
- the key of the property to be fetched
- the property for
key
or null
if there
is no such property stored
getRootElements
public Element[] getRootElements()
Returns all root elements of this
Document
. By default
this just returns the single root element returned by
getDefaultRootElement()
.
Document
implementations
that support multiple roots must override this method and return all roots
here.
- getRootElements in interface Document
- all root elements of this
Document
getText
public String getText(int offset,
int length)
throws BadLocationException
Returns a piece of this Document
's content.
- getText in interface Document
offset
- the start offset of the contentlength
- the length of the content
- the piece of content specified by
offset
and
length
getText
public void getText(int offset,
int length,
Segment segment)
throws BadLocationException
Fetches a piece of this
Document
's content and stores
it in the given
Segment
.
- getText in interface Document
offset
- the start offset of the contentlength
- the length of the contentsegment
- the Segment
to store the content in
insertString
public void insertString(int offset,
String text,
AttributeSet attributes)
throws BadLocationException
Inserts a String into this Document
at the specified
position and assigning the specified attributes to it.
- insertString in interface Document
offset
- the location at which the string should be insertedtext
- the content to be insertedattributes
- the text attributes to be assigned to that string
insertUpdate
protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
AttributeSet attr)
Called to indicate that text has been inserted into this
Document
. The default implementation does nothing.
This method is executed within a write lock.
chng
- the DefaultDocumentEvent
describing the changeattr
- the attributes of the changed content
postRemoveUpdate
protected void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
Called after some content has been removed from this
Document
. The default implementation does nothing.
This method is executed within a write lock.
chng
- the DefaultDocumentEvent
describing the change
putProperty
public void putProperty(Object key,
Object value)
Stores a property in this Document
's property list.
- putProperty in interface Document
key
- the key of the property to be storedvalue
- the value of the property to be stored
readLock
public void readLock()
Blocks until a read lock can be obtained. Must block if there is
currently a writer modifying the Document
.
readUnlock
public void readUnlock()
Releases the read lock. If this was the only reader on this
Document
, writing may begin now.
remove
public void remove(int offset,
int length)
throws BadLocationException
Removes a piece of content from this Document
.
- remove in interface Document
offset
- the start offset of the fragment to be removedlength
- the length of the fragment to be removed
removeUpdate
protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Called before some content gets removed from this Document
.
The default implementation does nothing but may be overridden by
subclasses to modify the Document
structure in response
to a remove request. The method is executed within a write lock.
chng
- the DefaultDocumentEvent
describing the change
render
public void render(Runnable runnable)
Called to render this
Document
visually. It obtains a read
lock, ensuring that no changes will be made to the
document
during the rendering process. It then calls the
Runnable.run()
method on
runnable
. This method
must not attempt
to modifiy the
Document
, since a deadlock will occur if it
tries to obtain a write lock. When the
Runnable.run()
method
completes (either naturally or by throwing an exception), the read lock
is released. Note that there is nothing in this method related to
the actual rendering. It could be used to execute arbitrary code within
a read lock.
- render in interface Document
replace
public void replace(int offset,
int length,
String text,
AttributeSet attributes)
throws BadLocationException
Replaces a piece of content in this Document
with
another piece of content.
offset
- the start offset of the fragment to be removedlength
- the length of the fragment to be removedtext
- the text to replace the content withattributes
- the text attributes to assign to the new content
setAsynchronousLoadPriority
public void setAsynchronousLoadPriority(int p)
Sets the asynchronous loading priority for this Document
.
A value of -1
indicates that this Document
should be loaded synchronously.
p
- the asynchronous loading priority to set
writeLock
protected void writeLock()
Blocks until a write lock can be obtained. Must wait if there are
readers currently reading or another thread is currently writing.
writeUnlock
protected void writeUnlock()
Releases the write lock. This allows waiting readers or writers to
obtain the lock.
AbstractDocument.java --
Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.