Interface IDocument
- All Known Implementing Classes:
AbstractDocument
,ChildDocument
,Document
,ProjectionDocument
IDocument
represents text providing support for
- text manipulation
- positions
- partitions
- line information
- document change listeners
- document partition change listeners
replace
method which substitutes a given
string for a specified text range in the document. On each document change, all
registered document listeners are informed exactly once.
Positions are stickers to the document's text that are updated when the
document is changed. Positions are updated by IPositionUpdater
s. Position
updaters are managed as a list. The list defines the sequence in which position
updaters are invoked. This way, position updaters may rely on each other.
Positions are grouped into categories. A category is a ordered list of positions.
the document defines the order of position in a category based on the position's offset
based on the implementation of the method computeIndexInCategory
.
Each document must support a default position category whose name is specified by this
interface.
A document can be considered consisting of a sequence of not overlapping partitions.
A partition is defined by its offset, its length, and its type. Partitions are
updated on every document manipulation and ensured to be up-to-date when the document
listeners are informed. A document uses an IDocumentPartitioner
to
manage its partitions. A document may be unpartitioned which happens when there is no
partitioner. In this case, the document is considered as one single partition of a
default type. The default type is specified by this interface. If a document change
changes the document's partitioning all registered partitioning listeners are
informed exactly once. The extension interface IDocumentExtension3
introduced in version 3.0 extends the concept of partitions and allows a document to
not only manage one but multiple partitioning. Each partitioning has an id which must
be used to refer to a particular partitioning.
An IDocument
provides methods to map line numbers and character
positions onto each other based on the document's line delimiters. When moving text
between documents using different line delimiters, the text must be converted to
use the target document's line delimiters.
An IDocument
does not care about mixed line delimiters. Clients who
want to ensure a single line delimiter in their document should use the line
delimiter returned by TextUtilities.getDefaultLineDelimiter(IDocument)
.
IDocument
throws BadLocationException
if the parameters of
queries or manipulation requests are not inside the bounds of the document. The purpose
of this style of exception handling is
- prepare document for multi-thread access
- allow clients to implement backtracking recovery methods
- prevent clients from up-front contract checking when dealing with documents.
A document support for searching has deprecated since version 3.0. The recommended way
for searching is to use a FindReplaceDocumentAdapter
.
In order to provide backward compatibility for clients of IDocument
, extension
interfaces are used to provide a means of evolution. The following extension interfaces
exist:
-
IDocumentExtension
since version 2.0 introducing the concept of post notification replaces in order to allow document listeners to manipulate the document while receiving a document change notification -
IDocumentExtension2
since version 2.1 introducing configuration methods for post notification replaces and document change notification. -
IDocumentExtension3
since version 3.0 replacing the original partitioning concept by allowing multiple partitionings at the same time and introducing zero- length partitions in conjunction with the distinction between open and closed partitions. -
IDocumentExtension4
since version 3.1 introducing the concept of rewrite sessions. A rewrite session is a sequence of document replace operations that form a semantic unit. It also introduces a modification stamp and the ability to set the initial line delimiter and to query the default line delimiter.
Clients may implement this interface and its extension interfaces or use the default
implementation provided by AbstractDocument
and Document
.
-
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addDocumentListener
(IDocumentListener listener) Registers the document listener with the document.void
Registers the document partitioning listener with the document.void
addPosition
(String category, Position position) Adds the position to the specified position category of the document.void
addPosition
(Position position) Adds the position to the document's default position category.void
addPositionCategory
(String category) Adds a new position category to the document.void
addPositionUpdater
(IPositionUpdater updater) Appends a new position updater to the document's list of position updaters.void
addPrenotifiedDocumentListener
(IDocumentListener documentAdapter) Adds the given document listener as one which is notified before those document listeners added withaddDocumentListener
are notified.int
computeIndexInCategory
(String category, int offset) Computes the index at which aPosition
with the specified offset would be inserted into the given category.int
computeNumberOfLines
(String text) Computes the number of lines in the given text.computePartitioning
(int offset, int length) Computes the partitioning of the given document range using the document's partitioner.boolean
containsPosition
(String category, int offset, int length) Determines whether a position described by the parameters is managed by this document.boolean
containsPositionCategory
(String category) Checks the presence of the specified position category.get()
Returns this document's complete text.get
(int offset, int length) Returns this document's text for the specified range.char
getChar
(int offset) Returns the character at the given document offset in this document.getContentType
(int offset) Returns the type of the document partition containing the given offset.Returns this document's partitioner.String[]
Returns the set of legal content types of document partitions.String[]
Returns the document's legal line delimiters.int
Returns the number of characters in this document.getLineDelimiter
(int line) Returns the line delimiter of that line ornull
if the line is not closed with a line delimiter.getLineInformation
(int line) Returns a description of the specified line.getLineInformationOfOffset
(int offset) Returns a description of the line at the given offset.int
getLineLength
(int line) Returns the length of the given line including the line's delimiter.int
getLineOffset
(int line) Determines the offset of the first character of the given line.int
getLineOfOffset
(int offset) Returns the number of the line at which the character of the specified position is located.int
Returns the number of lines in this document.int
getNumberOfLines
(int offset, int length) Returns the number of lines which are occupied by a given text range.getPartition
(int offset) Returns the document partition in which the position is located.String[]
Returns all position categories of this document.Position[]
getPositions
(String category) Returns all positions of the given position category.Returns the list of position updaters attached to the document.void
insertPositionUpdater
(IPositionUpdater updater, int index) Inserts the position updater at the specified index in the document's list of position updaters.void
removeDocumentListener
(IDocumentListener listener) Removes the listener from the document's list of document listeners.void
Removes the listener from this document's list of document partitioning listeners.void
removePosition
(String category, Position position) Removes the given position from the specified position category.void
removePosition
(Position position) Removes the given position from the document's default position category.void
removePositionCategory
(String category) Deletes the position category from the document.void
removePositionUpdater
(IPositionUpdater updater) Removes the position updater from the document's list of position updaters.void
removePrenotifiedDocumentListener
(IDocumentListener documentAdapter) Removes the given document listener from the document's list of pre-notified document listeners.void
Substitutes the given text for the specified document range.int
search
(int startOffset, String findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord) Deprecated.void
Replaces the content of the document with the given text.void
setDocumentPartitioner
(IDocumentPartitioner partitioner) Sets this document's partitioner.
-
Field Details
-
DEFAULT_CATEGORY
The identifier of the default position category.- See Also:
-
DEFAULT_CONTENT_TYPE
The identifier of the default partition content type.- See Also:
-
-
Method Details
-
getChar
Returns the character at the given document offset in this document.- Parameters:
offset
- a document offset- Returns:
- the character at the offset
- Throws:
BadLocationException
- if the offset is invalid in this document
-
getLength
int getLength()Returns the number of characters in this document.- Returns:
- the number of characters in this document
-
get
String get()Returns this document's complete text.- Returns:
- the document's complete text
-
get
Returns this document's text for the specified range.- Parameters:
offset
- the document offsetlength
- the length of the specified range- Returns:
- the document's text for the specified range
- Throws:
BadLocationException
- if the range is invalid in this document
-
set
Replaces the content of the document with the given text. Sends aDocumentEvent
to all registeredIDocumentListener
. This method is a convenience method forreplace(0, getLength(), text)
.- Parameters:
text
- the new content of the document- See Also:
-
replace
Substitutes the given text for the specified document range. Sends aDocumentEvent
to all registeredIDocumentListener
.- Parameters:
offset
- the document offsetlength
- the length of the specified rangetext
- the substitution text- Throws:
BadLocationException
- if the offset is invalid in this document- See Also:
-
addDocumentListener
Registers the document listener with the document. After registration the IDocumentListener is informed about each change of this document. If the listener is already registered nothing happens.An
IDocumentListener
may call back to this method when being inside a document notification.- Parameters:
listener
- the listener to be registered
-
removeDocumentListener
Removes the listener from the document's list of document listeners. If the listener is not registered with the document nothing happens.An
IDocumentListener
may call back to this method when being inside a document notification.- Parameters:
listener
- the listener to be removed
-
addPrenotifiedDocumentListener
Adds the given document listener as one which is notified before those document listeners added withaddDocumentListener
are notified. If the given listener is also registered usingaddDocumentListener
it will be notified twice. If the listener is already registered nothing happens.This method is not for public use.
- Parameters:
documentAdapter
- the listener to be added as pre-notified document listener- See Also:
-
removePrenotifiedDocumentListener
Removes the given document listener from the document's list of pre-notified document listeners. If the listener is not registered with the document nothing happens.This method is not for public use.
- Parameters:
documentAdapter
- the listener to be removed- See Also:
-
addPositionCategory
Adds a new position category to the document. If the position category already exists nothing happens.- Parameters:
category
- the category to be added
-
removePositionCategory
Deletes the position category from the document. All positions in this category are thus deleted as well.- Parameters:
category
- the category to be removed- Throws:
BadPositionCategoryException
- if category is undefined in this document
-
getPositionCategories
String[] getPositionCategories()Returns all position categories of this document. This includes the default position category.- Returns:
- the document's position categories
-
containsPositionCategory
Checks the presence of the specified position category.- Parameters:
category
- the category to check- Returns:
true
if category is defined
-
addPosition
Adds the position to the document's default position category. This is a convenience method foraddPosition(DEFAULT_CATEGORY, position)
.- Parameters:
position
- the position to be added- Throws:
BadLocationException
- if position describes an invalid range in this document
-
removePosition
Removes the given position from the document's default position category. This is a convenience method forremovePosition(DEFAULT_CATEGORY, position)
.- Parameters:
position
- the position to be removed
-
addPosition
void addPosition(String category, Position position) throws BadLocationException, BadPositionCategoryException Adds the position to the specified position category of the document. Positions may be added multiple times. The order of the category is maintained.Note: The position is only updated on each change applied to the document if a
IPositionUpdater
has been registered that handles the given category.- Parameters:
category
- the category to which to addposition
- the position to be added- Throws:
BadLocationException
- if position describes an invalid range in this documentBadPositionCategoryException
- if the category is undefined in this document
-
removePosition
Removes the given position from the specified position category. If the position is not part of the specified category nothing happens. If the position has been added multiple times, only the first occurrence is deleted.- Parameters:
category
- the category from which to deleteposition
- the position to be deleted- Throws:
BadPositionCategoryException
- if category is undefined in this document
-
getPositions
Returns all positions of the given position category. The positions are ordered according to the category's order. Manipulating this list does not affect the document, but manipulating the position does affect the document.- Parameters:
category
- the category- Returns:
- the list of all positions
- Throws:
BadPositionCategoryException
- if category is undefined in this document
-
containsPosition
Determines whether a position described by the parameters is managed by this document.- Parameters:
category
- the category to checkoffset
- the offset of the position to findlength
- the length of the position to find- Returns:
true
if position is found
-
computeIndexInCategory
int computeIndexInCategory(String category, int offset) throws BadLocationException, BadPositionCategoryException Computes the index at which aPosition
with the specified offset would be inserted into the given category. As the ordering inside a category only depends on the offset, the index must be chosen to be the first of all positions with the same offset.- Parameters:
category
- the category in which would be addedoffset
- the position offset to be considered- Returns:
- the index into the category
- Throws:
BadLocationException
- if offset is invalid in this documentBadPositionCategoryException
- if category is undefined in this document
-
addPositionUpdater
Appends a new position updater to the document's list of position updaters. Position updaters may be added multiple times.An
IPositionUpdater
may call back to this method when being inside a document notification.- Parameters:
updater
- the updater to be added
-
removePositionUpdater
Removes the position updater from the document's list of position updaters. If the position updater has multiple occurrences only the first occurrence is removed. If the position updater is not registered with this document, nothing happens.An
IPositionUpdater
may call back to this method when being inside a document notification.- Parameters:
updater
- the updater to be removed
-
insertPositionUpdater
Inserts the position updater at the specified index in the document's list of position updaters. Positions updaters may be inserted multiple times.An
IPositionUpdater
may call back to this method when being inside a document notification.- Parameters:
updater
- the updater to be insertedindex
- the index in the document's updater list
-
getPositionUpdaters
IPositionUpdater[] getPositionUpdaters()Returns the list of position updaters attached to the document.- Returns:
- the list of position updaters
-
getLegalContentTypes
String[] getLegalContentTypes()Returns the set of legal content types of document partitions. This set can be empty. The set can contain more content types than contained by the result ofgetPartitioning(0, getLength())
.Use
IDocumentExtension3.getLegalContentTypes(String)
when the document supports multiple partitionings. In that case this method is equivalent to:IDocumentExtension3 extension= (IDocumentExtension3) document; return extension.getLegalContentTypes(IDocumentExtension3.DEFAULT_PARTITIONING);
- Returns:
- the set of legal content types
-
getContentType
Returns the type of the document partition containing the given offset. This is a convenience method forgetPartition(offset).getType()
.Use
IDocumentExtension3.getContentType(String, int, boolean)
when the document supports multiple partitionings. In that case this method is equivalent to:IDocumentExtension3 extension= (IDocumentExtension3) document; return extension.getContentType(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);
- Parameters:
offset
- the document offset- Returns:
- the partition type
- Throws:
BadLocationException
- if offset is invalid in this document
-
getPartition
Returns the document partition in which the position is located.Use
IDocumentExtension3.getPartition(String, int, boolean)
when the document supports multiple partitionings. In that case this method is equivalent:IDocumentExtension3 extension= (IDocumentExtension3) document; return extension.getPartition(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);
- Parameters:
offset
- the document offset- Returns:
- a specification of the partition
- Throws:
BadLocationException
- if offset is invalid in this document
-
computePartitioning
Computes the partitioning of the given document range using the document's partitioner.Use
IDocumentExtension3.computePartitioning(String, int, int, boolean)
when the document supports multiple partitionings. In that case this method is equivalent:IDocumentExtension3 extension= (IDocumentExtension3) document; return extension.computePartitioning(IDocumentExtension3.DEFAULT_PARTITIONING, offset, length, false);
- Parameters:
offset
- the document offset at which the range startslength
- the length of the document range- Returns:
- a specification of the range's partitioning
- Throws:
BadLocationException
- if the range is invalid in this document
-
addDocumentPartitioningListener
Registers the document partitioning listener with the document. After registration the document partitioning listener is informed about each partition change cause by a document manipulation or by changing the document's partitioner. If a document partitioning listener is also a document listener, the following notification sequence is guaranteed if a document manipulation changes the document partitioning:- listener.documentAboutToBeChanged(DocumentEvent);
- listener.documentPartitioningChanged();
- listener.documentChanged(DocumentEvent);
An
IDocumentPartitioningListener
may call back to this method when being inside a document notification.- Parameters:
listener
- the listener to be added
-
removeDocumentPartitioningListener
Removes the listener from this document's list of document partitioning listeners. If the listener is not registered with the document nothing happens.An
IDocumentPartitioningListener
may call back to this method when being inside a document notification.- Parameters:
listener
- the listener to be removed
-
setDocumentPartitioner
Sets this document's partitioner. The caller of this method is responsible for disconnecting the document's old partitioner from the document and to connect the new partitioner to the document. Informs all document partitioning listeners about this change.Use
IDocumentExtension3.setDocumentPartitioner(String, IDocumentPartitioner)
when the document supports multiple partitionings. In that case this method is equivalent to:IDocumentExtension3 extension= (IDocumentExtension3) document; extension.setDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING, partitioner);
- Parameters:
partitioner
- the document's new partitioner- See Also:
-
getDocumentPartitioner
IDocumentPartitioner getDocumentPartitioner()Returns this document's partitioner.Use
IDocumentExtension3.getDocumentPartitioner(String)
when the document supports multiple partitionings. In that case this method is equivalent to:IDocumentExtension3 extension= (IDocumentExtension3) document; return extension.getDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING);
- Returns:
- this document's partitioner
-
getLineLength
Returns the length of the given line including the line's delimiter.- Parameters:
line
- the line of interest- Returns:
- the length of the line
- Throws:
BadLocationException
- if the line number is invalid in this document
-
getLineOfOffset
Returns the number of the line at which the character of the specified position is located. The first line has the line number 0. A new line starts directly after a line delimiter.(offset == document length)
is a valid argument although there is no corresponding character.- Parameters:
offset
- the document offset- Returns:
- the number of the line
- Throws:
BadLocationException
- if the offset is invalid in this document
-
getLineOffset
Determines the offset of the first character of the given line.- Parameters:
line
- the line of interest- Returns:
- the document offset
- Throws:
BadLocationException
- if the line number is invalid in this document
-
getLineInformation
Returns a description of the specified line. The line is described by its offset and its length excluding the line's delimiter.- Parameters:
line
- the line of interest- Returns:
- a line description
- Throws:
BadLocationException
- if the line number is invalid in this document
-
getLineInformationOfOffset
Returns a description of the line at the given offset. The description contains the offset and the length of the line excluding the line's delimiter.- Parameters:
offset
- the offset whose line should be described- Returns:
- a region describing the line
- Throws:
BadLocationException
- if offset is invalid in this document
-
getNumberOfLines
int getNumberOfLines()Returns the number of lines in this document.Note that a document always has at least one line.
- Returns:
- the number of lines in this document.
-
getNumberOfLines
Returns the number of lines which are occupied by a given text range.- Parameters:
offset
- the offset of the specified text rangelength
- the length of the specified text range- Returns:
- the number of lines occupied by the specified range
- Throws:
BadLocationException
- if specified range is invalid in this tracker
-
computeNumberOfLines
Computes the number of lines in the given text. For a given implementer of this interface this method returns the same result asset(text); getNumberOfLines()
.- Parameters:
text
- the text whose number of lines should be computed- Returns:
- the number of lines in the given text
-
getLegalLineDelimiters
String[] getLegalLineDelimiters()Returns the document's legal line delimiters.- Returns:
- the document's legal line delimiters
-
getLineDelimiter
Returns the line delimiter of that line ornull
if the line is not closed with a line delimiter.- Parameters:
line
- the line of interest- Returns:
- the line's delimiter or
null
if line does not have a delimiter - Throws:
BadLocationException
- if the line number is invalid in this document
-
search
@Deprecated int search(int startOffset, String findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord) throws BadLocationException Deprecated.as of 3.0 search is provided byFindReplaceDocumentAdapter
Returns the offset of a given search string in the document based on a set of search criteria.- Parameters:
startOffset
- document offset at which search startsfindString
- the string to findforwardSearch
- the search directioncaseSensitive
- indicates whether lower and upper case should be distinguishedwholeWord
- indicates whether the findString should be limited by white spaces as defined by Character.isWhiteSpace- Returns:
- the offset of the first occurrence of findString based on the parameters or -1 if no match is found
- Throws:
BadLocationException
- if startOffset is an invalid document offset
-
FindReplaceDocumentAdapter