org.eclipse.jface.text.rules

## Class FastPartitioner

- java.lang.Object
- - org.eclipse.jface.text.rules.FastPartitioner

All Implemented Interfaces:
  IDocumentPartitioner, IDocumentPartitionerExtension, IDocumentPartitionerExtension2, IDocumentPartitionerExtension3

    public class FastPartitioner
    extends Object
    implements IDocumentPartitioner, IDocumentPartitionerExtension, IDocumentPartitionerExtension2, IDocumentPartitionerExtension3

A standard implementation of a document partitioner. It uses an `IPartitionTokenScanner` to scan the document and to determine the document's partitioning. The tokens returned by the scanner must return the partition type as their data. The partitioner remembers the document's partitions in the document itself rather than maintaining its own data structure.

To reduce array creations in `IDocument.getPositions(String)`, the positions get cached. The cache is cleared after updating the positions in `documentChanged2(DocumentEvent)`. Subclasses need to call `clearPositionCache()` after modifying the partitioner's positions. The cached positions may be accessed through `getPositions()`.

Since:
  3.1
See Also:
  `IPartitionTokenScanner`

### Field Summary

Fields
`protected int` `fDeleteOffset` The offset at which a partition has been deleted
`protected IDocument` `fDocument` The partitioner's document
`protected int` `fEndOffset` The offset at which the last changed partition ends
`protected String[]` `fLegalContentTypes` The legal content types of this partitioner
`protected DefaultPositionUpdater` `fPositionUpdater` The position updater used to for the default updating of partitions
`protected int` `fPreviousDocumentLength` The document length before a document change occurred
`protected IPartitionTokenScanner` `fScanner` The partitioner's scanner
`protected int` `fStartOffset` The offset at which the first changed partition starts

### Constructor Summary

Constructors
Constructor and Description
`FastPartitioner(IPartitionTokenScanner scanner, String[] legalContentTypes)` Creates a new partitioner that uses the given scanner and may return partitions of the given legal content types.

### Method Summary

All Methods Instance Methods Concrete Methods
`protected void` `checkInitialization()` Calls `initialize()` if the receiver is not yet initialized.
`protected void` `clearPositionCache()` Clears the position cache.
`ITypedRegion[]` `computePartitioning(int offset, int length)` Returns the partitioning of the given range of the connected document.
`ITypedRegion[]` `computePartitioning(int offset, int length, boolean includeZeroLengthPartitions)` Returns the partitioning of the given range of the connected document.
`void` `connect(IDocument document)` Connects the partitioner to a document.
`void` `connect(IDocument document, boolean delayInitialization)` Connects this partitioner to a document.
`void` `disconnect()` Disconnects the partitioner from the document it is connected to.
`void` `documentAboutToBeChanged(DocumentEvent e)` Informs about a forthcoming document change.
`boolean` `documentChanged(DocumentEvent e)` The document has been changed.
`IRegion` `documentChanged2(DocumentEvent e)` The document has been changed.
`protected TypedPosition` `findClosestPosition(int offset)` Returns the position in the partitoner's position category which is close to the given offset.
`protected void` `flushRewriteSession()` Flushes the active rewrite session.
`DocumentRewriteSession` `getActiveRewriteSession()` Returns the active rewrite session of this document or `null`.
`String` `getContentType(int offset)` Returns the content type of the partition containing the given offset in the connected document.
`String` `getContentType(int offset, boolean preferOpenPartitions)` Returns the content type of the partition containing the given offset in the connected document.
`String[]` `getLegalContentTypes()` Returns the set of all legal content types of this partitioner.
`String[]` `getManagingPositionCategories()` Returns the position categories that this partitioners uses in order to manage the partitioning information of the documents.
`ITypedRegion` `getPartition(int offset)` Returns the partition containing the given offset of the connected document.
`ITypedRegion` `getPartition(int offset, boolean preferOpenPartitions)` Returns the partition containing the given offset of the connected document.
`protected Position[]` `getPositions()` Returns the partitioners positions.
`protected String` `getTokenContentType(IToken token)` Returns a content type encoded in the given token.
`protected void` `initialize()` Performs the initial partitioning of the partitioner's document.
`protected boolean` `isSupportedContentType(String contentType)` Returns whether the given type is one of the legal content types.
`void` `startRewriteSession(DocumentRewriteSession session)` Tells the document partitioner that a rewrite session started.
`void` `stopRewriteSession(DocumentRewriteSession session)` Tells the document partitioner that the rewrite session has finished.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### fScanner

    protected final IPartitionTokenScanner fScanner

The partitioner's scanner

#### fLegalContentTypes

    protected final String[] fLegalContentTypes

The legal content types of this partitioner

#### fDocument

    protected IDocument fDocument

The partitioner's document

#### fPreviousDocumentLength

    protected int fPreviousDocumentLength

The document length before a document change occurred

#### fPositionUpdater

    protected final DefaultPositionUpdater fPositionUpdater

The position updater used to for the default updating of partitions

#### fStartOffset

    protected int fStartOffset

The offset at which the first changed partition starts

#### fEndOffset

    protected int fEndOffset

The offset at which the last changed partition ends

#### fDeleteOffset

    protected int fDeleteOffset

The offset at which a partition has been deleted

### Constructor Detail

#### FastPartitioner

    public FastPartitioner(IPartitionTokenScanner scanner,
                           String[] legalContentTypes)

Creates a new partitioner that uses the given scanner and may return partitions of the given legal content types.

Parameters:
  `scanner` - the scanner this partitioner is supposed to use
  `legalContentTypes` - the legal content types of this partitioner

### Method Detail

#### getManagingPositionCategories

    public String[] getManagingPositionCategories()

Description copied from interface: `IDocumentPartitionerExtension2`
Returns the position categories that this partitioners uses in order to manage the partitioning information of the documents. Returns `null` if no position category is used.

Specified by:
  `getManagingPositionCategories` in interface `IDocumentPartitionerExtension2`
Returns:
  the position categories used to manage partitioning information or `null`

#### connect

    public final void connect(IDocument document)

Description copied from interface: `IDocumentPartitioner`
Connects the partitioner to a document. Connect indicates the begin of the usage of the receiver as partitioner of the given document. Thus, resources the partitioner needs to be operational for this document should be allocated.

The caller of this method must ensure that this partitioner is also set as the document's document partitioner.

This method has been replaced with `IDocumentPartitionerExtension3.connect(IDocument, boolean)`. Implementers should default a call `connect(document)` to `connect(document, false)` in order to sustain the same semantics.

Specified by:
  `connect` in interface `IDocumentPartitioner`
Parameters:
  `document` - the document to be connected to

#### connect

    public void connect(IDocument document,
                        boolean delayInitialization)

Connects this partitioner to a document. Connect indicates the begin of the usage of the receiver as partitioner of the given document. Thus, resources the partitioner needs to be operational for this document should be allocated.

The caller of this method must ensure that this partitioner is also set as the document's document partitioner.

`delayInitialization` indicates whether the partitioner is allowed to delay it initial computation of the document's partitioning until it has to answer the first query. Replaces `IDocumentPartitioner.connect(IDocument)`.

May be extended by subclasses.

Specified by:
  `connect` in interface `IDocumentPartitionerExtension3`
Parameters:
  `document` - the document to be connected to
  `delayInitialization` - `true` if initialization can be delayed, `false` otherwise

#### checkInitialization

    protected final void checkInitialization()

Calls `initialize()` if the receiver is not yet initialized.

#### initialize

    protected void initialize()

Performs the initial partitioning of the partitioner's document.

May be extended by subclasses.

#### disconnect

    public void disconnect()

Disconnects the partitioner from the document it is connected to. Disconnect indicates the end of the usage of the receiver as partitioner of the connected document. Thus, resources the partitioner needed to be operation for its connected document should be deallocated.

The caller of this method should also must ensure that this partitioner is no longer the document's partitioner.

May be extended by subclasses.

Specified by:
  `disconnect` in interface `IDocumentPartitioner`

#### documentAboutToBeChanged

    public void documentAboutToBeChanged(DocumentEvent e)

Informs about a forthcoming document change. Will be called by the connected document and is not intended to be used by clients other than the connected document.

May be extended by subclasses.

Specified by:
  `documentAboutToBeChanged` in interface `IDocumentPartitioner`
Parameters:
  `e` - the event describing the forthcoming change

#### documentChanged

    public final boolean documentChanged(DocumentEvent e)

Description copied from interface: `IDocumentPartitioner`
The document has been changed. The partitioner updates the document's partitioning and returns whether the structure of the document partitioning has been changed, i.e. whether partitions have been added or removed. Will be called by the connected document and is not intended to be used by clients other than the connected document.

This method has been replaced by `IDocumentPartitionerExtension.documentChanged2(DocumentEvent)`.

Specified by:
  `documentChanged` in interface `IDocumentPartitioner`
Parameters:
  `e` - the event describing the document change
Returns:
  `true` if partitioning changed

#### documentChanged2

    public IRegion documentChanged2(DocumentEvent e)

The document has been changed. The partitioner updates the document's partitioning and returns the minimal region that comprises all partition changes caused in response to the given document event. This method returns `null` if the partitioning did not change.

Will be called by the connected document and is not intended to be used by clients other than the connected document.

Replaces `IDocumentPartitioner.documentChanged(DocumentEvent)`.

May be extended by subclasses.

Specified by:
  `documentChanged2` in interface `IDocumentPartitionerExtension`
Parameters:
  `e` - the event describing the document change
Returns:
  the region of the document in which the partition type changed or `null`

#### findClosestPosition

    protected TypedPosition findClosestPosition(int offset)

Returns the position in the partitoner's position category which is close to the given offset. This is, the position has either an offset which is the same as the given offset or an offset which is smaller than the given offset. This method profits from the knowledge that a partitioning is a ordered set of disjoint position.

May be extended or replaced by subclasses.

Parameters:
  `offset` - the offset for which to search the closest position
Returns:
  the closest position in the partitioner's category

#### getContentType

    public String getContentType(int offset)

Returns the content type of the partition containing the given offset in the connected document. There must be a document connected to this partitioner.

Use `IDocumentPartitionerExtension2.getContentType(int, boolean)` when zero-length partitions are supported. In that case this method is equivalent:

        IDocumentPartitionerExtension2 extension= (IDocumentPartitionerExtension2) partitioner;
        return extension.getContentType(offset, false);

May be replaced or extended by subclasses.

Specified by:
  `getContentType` in interface `IDocumentPartitioner`
Parameters:
  `offset` - the offset in the connected document
Returns:
  the content type of the offset's partition

#### getPartition

    public ITypedRegion getPartition(int offset)

Returns the partition containing the given offset of the connected document. There must be a document connected to this partitioner.

Use `IDocumentPartitionerExtension2.getPartition(int, boolean)` when zero-length partitions are supported. In that case this method is equivalent:

        IDocumentPartitionerExtension2 extension= (IDocumentPartitionerExtension2) partitioner;
        return extension.getPartition(offset, false);

May be replaced or extended by subclasses.

Specified by:
  `getPartition` in interface `IDocumentPartitioner`
Parameters:
  `offset` - the offset for which to determine the partition
Returns:
  the partition containing the offset

#### computePartitioning

    public final ITypedRegion[] computePartitioning(int offset,
                                                    int length)

Description copied from interface: `IDocumentPartitioner`
Returns the partitioning of the given range of the connected document. There must be a document connected to this partitioner.

Use `IDocumentPartitionerExtension2.computePartitioning(int, int, boolean)` when zero-length partitions are supported. In that case this method is equivalent:

        IDocumentPartitionerExtension2 extension= (IDocumentPartitionerExtension2) partitioner;
        return extension.computePartitioning(offset, length, false);

Specified by:
  `computePartitioning` in interface `IDocumentPartitioner`
Parameters:
  `offset` - the offset of the range of interest
  `length` - the length of the range of interest
Returns:
  the partitioning of the range

#### getLegalContentTypes

    public String[] getLegalContentTypes()

Returns the set of all legal content types of this partitioner. I.e. any result delivered by this partitioner may not contain a content type which would not be included in this method's result.

May be replaced or extended by subclasses.

Specified by:
  `getLegalContentTypes` in interface `IDocumentPartitioner`
Returns:
  the set of legal content types

#### isSupportedContentType

    protected boolean isSupportedContentType(String contentType)

Returns whether the given type is one of the legal content types.

May be extended by subclasses.

Parameters:
  `contentType` - the content type to check
Returns:
  `true` if the content type is a legal content type

#### getTokenContentType

    protected String getTokenContentType(IToken token)

Returns a content type encoded in the given token. If the token's data is not `null` and a string it is assumed that it is the encoded content type.

May be replaced or extended by subclasses.

Parameters:
  `token` - the token whose content type is to be determined
Returns:
  the token's content type

#### getContentType

    public String getContentType(int offset,
                                 boolean preferOpenPartitions)

Returns the content type of the partition containing the given offset in the connected document. There must be a document connected to this partitioner.

If `preferOpenPartitions` is `true`, precedence is given to an open partition ending at `offset` over a delimited partition starting at `offset`.

This method replaces `IDocumentPartitioner.getContentType(int)`and behaves like it when `prepreferOpenPartitions` is `false`, i.e. precedence is always given to the partition that does not end at `offset`.

May be replaced or extended by subclasses.

Specified by:
  `getContentType` in interface `IDocumentPartitionerExtension2`
Parameters:
  `offset` - the offset in the connected document
  `preferOpenPartitions` - `true` if precedence should be given to a open partition ending at `offset` over a delimited partition starting at `offset`
Returns:
  the content type of the offset's partition

#### getPartition

    public ITypedRegion getPartition(int offset,
                                     boolean preferOpenPartitions)

Returns the partition containing the given offset of the connected document. There must be a document connected to this partitioner.

If `preferOpenPartitions` is `true`, precedence is given to an open partition ending at `offset` over a delimited partition starting at `offset`.

This method replaces `IDocumentPartitioner.getPartition(int)`and behaves like it when <preferOpenPartitions is `false` , i.e. precedence is always given to the partition that does not end at `offset`.

May be replaced or extended by subclasses.

Specified by:
  `getPartition` in interface `IDocumentPartitionerExtension2`
Parameters:
  `offset` - the offset for which to determine the partition
  `preferOpenPartitions` - `true` if precedence should be given to a open partition ending at `offset` over a delimited partition starting at `offset`
Returns:
  the partition containing the offset

#### computePartitioning

    public ITypedRegion[] computePartitioning(int offset,
                                              int length,
                                              boolean includeZeroLengthPartitions)

Returns the partitioning of the given range of the connected document. There must be a document connected to this partitioner.

If `includeZeroLengthPartitions` is `true`, a zero-length partition of an open partition type (usually the default partition) is included between two delimited partitions. If it is `false`, no zero-length partitions are included.

This method replaces `IDocumentPartitioner.computePartitioning(int, int)`and behaves like it when `includeZeroLengthPartitions` is `false`.

May be replaced or extended by subclasses.

Specified by:
  `computePartitioning` in interface `IDocumentPartitionerExtension2`
Parameters:
  `offset` - the offset of the range of interest
  `length` - the length of the range of interest
  `includeZeroLengthPartitions` - `true` if zero-length partitions should be returned as part of the computed partitioning
Returns:
  the partitioning of the range

#### startRewriteSession

    public void startRewriteSession(DocumentRewriteSession session)
                             throws IllegalStateException

Description copied from interface: `IDocumentPartitionerExtension3`
Tells the document partitioner that a rewrite session started. A rewrite session is a sequence of replace operations that form a semantic unit. The document partitioner is allowed to use that information for internal optimization.

Specified by:
  `startRewriteSession` in interface `IDocumentPartitionerExtension3`
Parameters:
  `session` - the rewrite session
Throws:
  `IllegalStateException` - in case there is already an active rewrite session

#### stopRewriteSession

    public void stopRewriteSession(DocumentRewriteSession session)

Tells the document partitioner that the rewrite session has finished. This method is only called when `startRewriteSession` has been called before.

May be extended by subclasses.

Specified by:
  `stopRewriteSession` in interface `IDocumentPartitionerExtension3`
Parameters:
  `session` - the rewrite session

#### getActiveRewriteSession

    public DocumentRewriteSession getActiveRewriteSession()

Returns the active rewrite session of this document or `null`.

May be extended by subclasses.

Specified by:
  `getActiveRewriteSession` in interface `IDocumentPartitionerExtension3`
Returns:
  the active rewrite session or `null`

#### flushRewriteSession

    protected final void flushRewriteSession()

Flushes the active rewrite session.

#### clearPositionCache

    protected final void clearPositionCache()

Clears the position cache. Needs to be called whenever the positions have been updated.

#### getPositions

    protected final Position[] getPositions()
                                     throws BadPositionCategoryException

Returns the partitioners positions.

Returns:
  the partitioners positions
Throws:
  `BadPositionCategoryException` - if getting the positions from the document fails