| com.pnfsoftware.jeb.core.output.text.ITextDocument |
 Known Indirect Subclasses
|
Class Overview
A text document is used to represent arbitrarily long buffers of interactive text data. A
document is indexed by anchors. A document may have up to 2^63 anchors. A
document can be seen as a partition of one or more non-overlapping, disjoint chunks containing 1
or more line (or one or more anchored blocks). Those chunks are represented by
parts. The first line of a chunk is called the anchor line, or anchor.
Classes implementing this interface should also support an optional coordinates -to-address (and vice-versa) addressing system, to offer front-ends the capability
to let clients know where they are in a text document.
Summary
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| abstract ICoordinates |
addressToCoordinates(String address)
Convert a unit-specific address to document-specific text coordinates.
| ||||||||||
| abstract ICoordinates |
addressToCoordinates(String address, CoordinatesConversionPrecision precision)
Convert a unit-specific address to document-specific text coordinates.
| ||||||||||
| abstract String |
coordinatesToAddress(ICoordinates coordinates)
Convert document-specific text coordinates to a unit-specific address using a default
conversion precision.
| ||||||||||
| abstract String |
coordinatesToAddress(ICoordinates coordinates, AddressConversionPrecision precision)
Convert document-specific text coordinates to a unit-specific address.
| ||||||||||
| abstract String |
format()
Format this text document.
| ||||||||||
| abstract long |
getAnchorCount()
Get the range of anchor points in the document.
| ||||||||||
| abstract IBinaryRepresentation |
getBinaryRepresentation()
Retrieve a binary representation of this document.
| ||||||||||
| abstract ITextDocumentPart |
getDocumentPart(long anchorId, int linesAfter)
Retrieve a document part.
| ||||||||||
| abstract ITextDocumentPart |
getDocumentPart(long anchorId, int linesAfter, int linesBefore)
Retrieve a document part.
| ||||||||||
| abstract ITextDocumentPart |
getDocumentPart2(long anchorBegin, long anchorEnd)
Retrieve the document part located between two anchor references.
| ||||||||||
| abstract long |
getFirstAnchor()
Get the first anchor identifier of the document.
| ||||||||||
| abstract long |
getInitialAnchor()
Get the anchor identifier that would represent the first logical section of a document
(meaning the anchor to focus on when opening a document).
| ||||||||||
| abstract boolean |
hasBinaryRepresentation()
Determine if this document offers binary representations.
| ||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
From interface
com.pnfsoftware.jeb.core.output.IGenericDocument
| |||||||||||
|
From interface
com.pnfsoftware.jeb.util.events.IEventSource
| |||||||||||
Public Methods
public abstract ICoordinates addressToCoordinates (String address)
Convert a unit-specific address to document-specific text coordinates. It is recommended to return canonical coordinates. The implementation might return approximate coordinates, ie the closest coordinates (in terms of distance) calculated as part of a best effort approach to minimize the return of null values.
Note: The addressing scheme is unit specific, and defined by the plugin developer. Addresses should not start with the reserved '@' prefix.
Parameters
| address | a textual address |
|---|
Returns
- the text coordinates, null on error
public abstract ICoordinates addressToCoordinates (String address, CoordinatesConversionPrecision precision)
Convert a unit-specific address to document-specific text coordinates. It is recommended to return canonical coordinates. The implementation might return approximate coordinates, ie the closest coordinates (in terms of distance) calculated as part of a best effort approach to minimize the return of null values.
Note: The addressing scheme is unit specific, and defined by the plugin developer. Addresses should not start with the reserved '@' prefix.
Parameters
| address | a textual address |
|---|
Returns
- the text coordinates, null on error
public abstract String coordinatesToAddress (ICoordinates coordinates)
Convert document-specific text coordinates to a unit-specific address using a default conversion precision.
Note: The addressing scheme is unit specific, and defined by the plugin developer. Addresses should not start with the reserved '@' prefix.
Parameters
| coordinates | the coordinates |
|---|
Returns
- the address, null on error
public abstract String coordinatesToAddress (ICoordinates coordinates, AddressConversionPrecision precision)
Convert document-specific text coordinates to a unit-specific address.
Note: The addressing scheme is unit specific, and defined by the plugin developer. Addresses should not start with the reserved '@' prefix.
Parameters
| coordinates | the coordinates |
|---|---|
| precision | indicate the precision of the address (
COARSE will return a raw address, with a faster
result while FINE will return a more precise
address that can be a bit longer). If COARSE
can not be retrieved, it may return a null result, and the user will need to
recall this method with another precision. |
Returns
- the address, null on error
public abstract String format ()
Format this text document.
public abstract long getAnchorCount ()
Get the range of anchor points in the document. Returning 1 means that the document returns a single part, holding the entire contents.
Note that the anchor at "getFirstAnchor() + getAnchorCount()" is the "end"
anchor (one after the last), and lies outside the document. It is not a valid anchor.
Returns
- the count/range of anchors in this document, must be greater than zero
public abstract IBinaryRepresentation getBinaryRepresentation ()
Retrieve a binary representation of this document. Implementation is optional; implementers may return null.
public abstract ITextDocumentPart getDocumentPart (long anchorId, int linesAfter)
Retrieve a document part. Equivalent to getDocumentPart(anchorId, linesAfter) .
Parameters
| anchorId | the anchor id |
|---|---|
| linesAfter | number of lines after |
Returns
- the document part
public abstract ITextDocumentPart getDocumentPart (long anchorId, int linesAfter, int linesBefore)
Retrieve a document part. Clients call this method to retrieve a document part starting at a specific anchor, and containing the given amount of lines after and before the anchor. It is the responsibility of the implementor to sanitize the input (eg, negative number of lines, invalid anchor, etc.) and provide appropriate response (eg, truncating). It is recommended that implementors try not to raise an exception on error. In the worst case scenario, an empty document can be returned.
Parameters
| anchorId | the anchor identifier |
|---|---|
| linesAfter | hint lines count to return after the given anchor, could be more or less |
| linesBefore | hint lines count to return before the given anchor, could be more or less |
Returns
- a document part containing as many anchors as required to honor the client requests. If linesAfter is non-null, the first anchor within the document part may not be anchorId, but one anchor before that. THis method should return null if an invalid anchor was provided
public abstract ITextDocumentPart getDocumentPart2 (long anchorBegin, long anchorEnd)
Retrieve the document part located between two anchor references. This method is optional.
Parameters
| anchorBegin | start anchor, inclusive |
|---|---|
| anchorEnd | final anchor, exclusive |
Returns
- the document part
Throws
| NotImplementedException | implementations should throw if this method is not implemented |
|---|
public abstract long getFirstAnchor ()
Get the first anchor identifier of the document. Most document will want to have 0 as their first anchor identifier.
Returns
- an integer greater or equal than zero
public abstract long getInitialAnchor ()
Get the anchor identifier that would represent the first logical section of a document (meaning the anchor to focus on when opening a document). If not specified, the first anchor is considered to be the initial anchor.
Returns
- an integer, 0 if not specified
public abstract boolean hasBinaryRepresentation ()
Determine if this document offers binary representations. If this method returns true,
getBinaryRepresentation() may be safely called and shall return a non-null object.