Package org.eclipse.jface.text.source

## Class AnnotationModel

- java.lang.Object
- - org.eclipse.jface.text.source.AnnotationModel

All Implemented Interfaces:
  `ISynchronizable`, `IAnnotationModel`, `IAnnotationModelExtension`, `IAnnotationModelExtension2`

Direct Known Subclasses:
  `AbstractMarkerAnnotationModel`, `ProjectionAnnotationModel`

    public class AnnotationModel
    extends Object
    implements IAnnotationModel, IAnnotationModelExtension, IAnnotationModelExtension2, ISynchronizable

Standard implementation of `IAnnotationModel` and its extension interfaces. This class can directly be used by clients. Subclasses may adapt this annotation model to other existing annotation mechanisms. This class also implements `ISynchronizable`. All modifications of the model's internal annotation map are synchronized using the model's lock object.

### Field Summary

Fields
`protected ArrayList<IAnnotationModelListener>` `fAnnotationModelListeners` The list of annotation model listeners
`protected Map<Annotation,​Position>` `fAnnotations` Deprecated. since 3.0 use `getAnnotationMap` instead
`protected IDocument` `fDocument` The document connected with this model

### Constructor Summary

Constructors
`AnnotationModel()` Creates a new annotation model.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addAnnotation​(Annotation annotation, Position position)` Adds a annotation to this annotation model.
`protected void` `addAnnotation​(Annotation annotation, Position position, boolean fireModelChanged)` Adds the given annotation to this model.
`void` `addAnnotationModel​(Object key, IAnnotationModel attachment)` Attaches `attachment` to the receiver.
`void` `addAnnotationModelListener​(IAnnotationModelListener listener)` Registers the annotation model listener with this annotation model.
`protected void` `addPosition​(IDocument document, Position position)` Adds the given position to the default position category of the given document.
`protected void` `cleanup​(boolean fireModelChanged)` Removes all annotations from the model whose associated positions have been deleted.
`void` `connect​(IDocument document)` Connects the annotation model to a document.
`protected void` `connected()` Hook method.
`protected AnnotationModelEvent` `createAnnotationModelEvent()` Creates and returns a new annotation model event.
`void` `disconnect​(IDocument document)` Disconnects this model from a document.
`protected void` `disconnected()` Hook method.
`protected void` `fireModelChanged()` Informs all annotation model listeners that this model has been changed.
`protected void` `fireModelChanged​(AnnotationModelEvent event)` Informs all annotation model listeners that this model has been changed as described in the annotation model event.
`Iterator<Annotation>` `getAnnotationIterator()` Returns all annotations managed by this model.
`protected Iterator<Annotation>` `getAnnotationIterator​(boolean cleanup)` Returns all annotations managed by this model.
`Iterator<Annotation>` `getAnnotationIterator​(int offset, int length, boolean canStartBefore, boolean canEndAfter)` Returns an iterator over all annotations managed by this model that are inside the given region.
`protected IAnnotationMap` `getAnnotationMap()` Returns the annotation map internally used by this annotation model.
`IAnnotationModel` `getAnnotationModel​(Object key)` Returns the attached `IAnnotationModel` for `key`, or `null` if none is attached for `key`.
`protected AnnotationModelEvent` `getAnnotationModelEvent()` Returns the current annotation model event.
`Object` `getLockObject()` Returns the lock object or `null` if there is none.
`Object` `getModificationStamp()` Returns the modification stamp of this annotation model.
`Position` `getPosition​(Annotation annotation)` Returns the position associated with the given annotation.
`protected void` `modifyAnnotation​(Annotation annotation, boolean fireModelChanged)` Modifies the given annotation if the annotation is managed by this annotation model.
`void` `modifyAnnotationPosition​(Annotation annotation, Position position)` Modifies the position associated with the given annotation to equal the given position.
`protected void` `modifyAnnotationPosition​(Annotation annotation, Position position, boolean fireModelChanged)` Modifies the associated position of the given annotation to the given position.
`void` `removeAllAnnotations()` Removes all annotations from this annotation model.
`protected void` `removeAllAnnotations​(boolean fireModelChanged)` Removes all annotations from the annotation model.
`void` `removeAnnotation​(Annotation annotation)` Removes the given annotation from the model.
`protected void` `removeAnnotation​(Annotation annotation, boolean fireModelChanged)` Removes the given annotation from the annotation model.
`IAnnotationModel` `removeAnnotationModel​(Object key)` Removes and returns the attached `IAnnotationModel` for `key`.
`void` `removeAnnotationModelListener​(IAnnotationModelListener listener)` Removes the listener from the model's list of annotation model listeners.
`protected void` `removeAnnotations​(List<? extends Annotation> annotations, boolean fireModelChanged, boolean modelInitiated)` Removes the given annotations from this model.
`protected void` `removePosition​(IDocument document, Position position)` Removes the given position from the default position category of the given document.
`void` `replaceAnnotations​(Annotation[] annotationsToRemove, Map<? extends Annotation,​? extends Position> annotationsToAdd)` Adds and removes annotations to/from this annotation model in a single step.
`protected void` `replaceAnnotations​(Annotation[] annotationsToRemove, Map<? extends Annotation,​? extends Position> annotationsToAdd, boolean fireModelChanged)` Replaces the given annotations in this model and if advised fires a model change event.
`void` `setLockObject​(Object lockObject)` Sets the lock object for this object.

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

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

### Field Detail

#### fAnnotations

    @Deprecated
    protected Map<Annotation,​Position> fAnnotations

Deprecated.
since 3.0 use `getAnnotationMap` instead
The list of managed annotations

#### fAnnotationModelListeners

    protected ArrayList<IAnnotationModelListener> fAnnotationModelListeners

The list of annotation model listeners

#### fDocument

    protected IDocument fDocument

The document connected with this model

### Constructor Detail

#### AnnotationModel

    public AnnotationModel()

Creates a new annotation model. The annotation is empty, i.e. does not manage any annotations and is not connected to any document.

### Method Detail

#### getAnnotationMap

    protected IAnnotationMap getAnnotationMap()

Returns the annotation map internally used by this annotation model.

Returns:
  the annotation map internally used by this annotation model
Since:
  3.0

#### getLockObject

    public Object getLockObject()

Description copied from interface: `ISynchronizable`
Returns the lock object or `null` if there is none. Clients should use the lock object in order to synchronize concurrent access to the implementer.

Specified by:
  `getLockObject` in interface `ISynchronizable`
Returns:
  the lock object or `null`

#### setLockObject

    public void setLockObject​(Object lockObject)

Description copied from interface: `ISynchronizable`
Sets the lock object for this object. If the lock object is not `null` subsequent calls to specified methods of this object are synchronized on this lock object. Which methods are synchronized is specified by the implementer.

You should not override an existing lock object unless you own that lock object yourself. Use the existing lock object instead.

Specified by:
  `setLockObject` in interface `ISynchronizable`
Parameters:
  `lockObject` - the lock object. May be `null`.

#### getAnnotationModelEvent

    protected final AnnotationModelEvent getAnnotationModelEvent()

Returns the current annotation model event. This is the event that will be sent out when calling `fireModelChanged`.

Returns:
  the current annotation model event
Since:
  3.0

#### addAnnotation

    public void addAnnotation​(Annotation annotation,
                              Position position)

Description copied from interface: `IAnnotationModel`
Adds a annotation to this annotation model. The annotation is associated with with the given position which describes the range covered by the annotation. All registered annotation model listeners are informed about the change. If the model is connected to a document, the position is automatically updated on document changes. If the annotation is already managed by this annotation model or is not a valid position in the connected document nothing happens.

Performance hint: Use `IAnnotationModelExtension.replaceAnnotations(Annotation[], java.util.Map)` if several annotations are added and/or removed.

Specified by:
  `addAnnotation` in interface `IAnnotationModel`
Parameters:
  `annotation` - the annotation to add, may not be `null`
  `position` - the position describing the range covered by this annotation, may not be `null`

#### replaceAnnotations

    public void replaceAnnotations​(Annotation[] annotationsToRemove,
                                   Map<? extends Annotation,​? extends Position> annotationsToAdd)

Description copied from interface: `IAnnotationModelExtension`
Adds and removes annotations to/from this annotation model in a single step. The annotations to remove are given in an array. The annotations to add are provided in a map associating the annotations with the positions at which they should be added. All registered annotation model listeners are informed about the change. If the model is connected to a document, the positions are automatically updated on document changes. Annotations that are already managed by this annotation model or are not associated with a valid position in the connected document have no effect.

Specified by:
  `replaceAnnotations` in interface `IAnnotationModelExtension`
Parameters:
  `annotationsToRemove` - the annotations to be removed, may be `null`
  `annotationsToAdd` - the annotations which will be added, may be `null` each map entry has an `Annotation` as key and a `Position` as value

#### replaceAnnotations

    protected void replaceAnnotations​(Annotation[] annotationsToRemove,
                                      Map<? extends Annotation,​? extends Position> annotationsToAdd,
                                      boolean fireModelChanged)
                               throws BadLocationException

Replaces the given annotations in this model and if advised fires a model change event.

Parameters:
  `annotationsToRemove` - the annotations to be removed
  `annotationsToAdd` - the annotations to be added
  `fireModelChanged` - `true` if a model change event should be fired, `false` otherwise
Throws:
  `BadLocationException` - in case an annotation should be added at an invalid position
Since:
  3.0

#### addAnnotation

    protected void addAnnotation​(Annotation annotation,
                                 Position position,
                                 boolean fireModelChanged)
                          throws BadLocationException

Adds the given annotation to this model. Associates the annotation with the given position. If requested, all annotation model listeners are informed about this model change. If the annotation is already managed by this model nothing happens.

Parameters:
  `annotation` - the annotation to add
  `position` - the associate position
  `fireModelChanged` - indicates whether to notify all model listeners
Throws:
  `BadLocationException` - if the position is not a valid document position

#### addAnnotationModelListener

    public void addAnnotationModelListener​(IAnnotationModelListener listener)

Description copied from interface: `IAnnotationModel`
Registers the annotation model listener with this annotation model. After registration listener is informed about each change of this model. If the listener is already registered nothing happens.

Specified by:
  `addAnnotationModelListener` in interface `IAnnotationModel`
Parameters:
  `listener` - the listener to be registered, may not be `null`

#### addPosition

    protected void addPosition​(IDocument document,
                               Position position)
                        throws BadLocationException

Adds the given position to the default position category of the given document.

Parameters:
  `document` - the document to which to add the position
  `position` - the position to add
Throws:
  `BadLocationException` - if the position is not a valid document position

#### removePosition

    protected void removePosition​(IDocument document,
                                  Position position)

Removes the given position from the default position category of the given document.

Parameters:
  `document` - the document to which to add the position
  `position` - the position to add
Since:
  3.0

#### connect

    public void connect​(IDocument document)

Description copied from interface: `IAnnotationModel`
Connects the annotation model to a document. The annotations managed by this model must subsequently update according to the changes applied to the document. Once an annotation model is connected to a document, all further `connect` calls must mention the document the model is already connected to. An annotation model primarily uses `connect` and `disconnect` for reference counting the document. Reference counting frees the clients from keeping tracker whether a model has already been connected to a document.

Specified by:
  `connect` in interface `IAnnotationModel`
Parameters:
  `document` - the document the model gets connected to, may not be `null`
See Also:
  `IAnnotationModel.disconnect(IDocument)`

#### connected

    protected void connected()

Hook method. Is called as soon as this model becomes connected to a document. Subclasses may re-implement.

#### disconnected

    protected void disconnected()

Hook method. Is called as soon as this model becomes disconnected from its document. Subclasses may re-implement.

#### disconnect

    public void disconnect​(IDocument document)

Description copied from interface: `IAnnotationModel`
Disconnects this model from a document. After that, document changes no longer matter. An annotation model may only be disconnected from a document to which it has been connected before. If the model reference counts the connections to a document, the connection to the document may only be terminated if the reference count does down to 0.

Specified by:
  `disconnect` in interface `IAnnotationModel`
Parameters:
  `document` - the document the model gets disconnected from, may not be `null`
See Also:
  `for further specification details`

#### fireModelChanged

    protected void fireModelChanged()

Informs all annotation model listeners that this model has been changed.

#### createAnnotationModelEvent

    protected AnnotationModelEvent createAnnotationModelEvent()

Creates and returns a new annotation model event. Subclasses may override.

Returns:
  a new and empty annotation model event
Since:
  3.0

#### fireModelChanged

    protected void fireModelChanged​(AnnotationModelEvent event)

Informs all annotation model listeners that this model has been changed as described in the annotation model event. The event is sent out to all listeners implementing `IAnnotationModelListenerExtension`. All other listeners are notified by just calling `modelChanged(IAnnotationModel)`.

Parameters:
  `event` - the event to be sent out to the listeners
Since:
  2.0

#### removeAnnotations

    protected void removeAnnotations​(List<? extends Annotation> annotations,
                                     boolean fireModelChanged,
                                     boolean modelInitiated)

Removes the given annotations from this model. If requested all annotation model listeners will be informed about this change. `modelInitiated` indicates whether the deletion has been initiated by this model or by one of its clients.

Parameters:
  `annotations` - the annotations to be removed
  `fireModelChanged` - indicates whether to notify all model listeners
  `modelInitiated` - indicates whether this changes has been initiated by this model

#### cleanup

    protected void cleanup​(boolean fireModelChanged)

Removes all annotations from the model whose associated positions have been deleted. If requested inform all model listeners about the change.

Parameters:
  `fireModelChanged` - indicates whether to notify all model listeners

#### getAnnotationIterator

    public Iterator<Annotation> getAnnotationIterator()

Description copied from interface: `IAnnotationModel`
Returns all annotations managed by this model.

Specified by:
  `getAnnotationIterator` in interface `IAnnotationModel`
Returns:
  all annotations managed by this model

#### getAnnotationIterator

    public Iterator<Annotation> getAnnotationIterator​(int offset,
                                                      int length,
                                                      boolean canStartBefore,
                                                      boolean canEndAfter)

Returns an iterator over all annotations managed by this model that are inside the given region.

Specified by:
  `getAnnotationIterator` in interface `IAnnotationModelExtension2`
Parameters:
  `offset` - the start position of the region, must be >= 0
  `length` - the length of the region, must be >= 0
  `canStartBefore` - if `true` then annotations are included which start before the region if they end at or after the region's start
  `canEndAfter` - if `true` then annotations are included which end after the region if they start at or before the region's end
Returns:
  all annotations inside the region managed by this model
Since:
  3.4

#### getAnnotationIterator

    protected Iterator<Annotation> getAnnotationIterator​(boolean cleanup)

Returns all annotations managed by this model. `cleanup` indicates whether all annotations whose associated positions are deleted should previously be removed from the model.

Parameters:
  `cleanup` - indicates whether annotations with deleted associated positions are removed
Returns:
  all annotations managed by this model

#### getPosition

    public Position getPosition​(Annotation annotation)

Description copied from interface: `IAnnotationModel`
Returns the position associated with the given annotation.

Specified by:
  `getPosition` in interface `IAnnotationModel`
Parameters:
  `annotation` - the annotation whose position should be returned
Returns:
  the position of the given annotation or `null` if no associated annotation exists

#### removeAllAnnotations

    public void removeAllAnnotations()

Description copied from interface: `IAnnotationModelExtension`
Removes all annotations from this annotation model.

Specified by:
  `removeAllAnnotations` in interface `IAnnotationModelExtension`

#### removeAllAnnotations

    protected void removeAllAnnotations​(boolean fireModelChanged)

Removes all annotations from the annotation model. If requested inform all model change listeners about this change.

Parameters:
  `fireModelChanged` - indicates whether to notify all model listeners

#### removeAnnotation

    public void removeAnnotation​(Annotation annotation)

Description copied from interface: `IAnnotationModel`
Removes the given annotation from the model. I.e. the annotation is no longer managed by this model. The position associated with the annotation is no longer updated on document changes. If the annotation is not managed by this model, nothing happens.

Performance hint: Use `IAnnotationModelExtension.replaceAnnotations(Annotation[], java.util.Map)` if several annotations are removed and/or added.

Specified by:
  `removeAnnotation` in interface `IAnnotationModel`
Parameters:
  `annotation` - the annotation to be removed from this model, may not be `null`

#### removeAnnotation

    protected void removeAnnotation​(Annotation annotation,
                                    boolean fireModelChanged)

Removes the given annotation from the annotation model. If requested inform all model change listeners about this change.

Parameters:
  `annotation` - the annotation to be removed
  `fireModelChanged` - indicates whether to notify all model listeners

#### modifyAnnotationPosition

    public void modifyAnnotationPosition​(Annotation annotation,
                                         Position position)

Description copied from interface: `IAnnotationModelExtension`
Modifies the position associated with the given annotation to equal the given position. If the annotation is not yet managed by this annotation model, the annotation is added. If the given position is `null` the annotation is removed from the model. All annotation model change listeners will be informed about the change.

Specified by:
  `modifyAnnotationPosition` in interface `IAnnotationModelExtension`
Parameters:
  `annotation` - the annotation whose associated position should be modified
  `position` - the position to whose values the associated position should be changed

#### modifyAnnotationPosition

    protected void modifyAnnotationPosition​(Annotation annotation,
                                            Position position,
                                            boolean fireModelChanged)

Modifies the associated position of the given annotation to the given position. If the annotation is not yet managed by this annotation model, the annotation is added. When the position is `null`, the annotation is removed from the model.

If requested, all annotation model change listeners will be informed about the change.

Parameters:
  `annotation` - the annotation whose associated position should be modified
  `position` - the position to whose values the associated position should be changed
  `fireModelChanged` - indicates whether to notify all model listeners
Since:
  3.0

#### modifyAnnotation

    protected void modifyAnnotation​(Annotation annotation,
                                    boolean fireModelChanged)

Modifies the given annotation if the annotation is managed by this annotation model.

If requested, all annotation model change listeners will be informed about the change.

Parameters:
  `annotation` - the annotation to be modified
  `fireModelChanged` - indicates whether to notify all model listeners
Since:
  3.0

#### removeAnnotationModelListener

    public void removeAnnotationModelListener​(IAnnotationModelListener listener)

Description copied from interface: `IAnnotationModel`
Removes the listener from the model's list of annotation model listeners. If the listener is not registered with the model nothing happens.

Specified by:
  `removeAnnotationModelListener` in interface `IAnnotationModel`
Parameters:
  `listener` - the listener to be removed, may not be `null`

#### addAnnotationModel

    public void addAnnotationModel​(Object key,
                                   IAnnotationModel attachment)

Description copied from interface: `IAnnotationModelExtension`
Attaches `attachment` to the receiver. Connects `attachment` to the currently connected document. If `attachment` is already attached (even) under a different key), it is not attached again.

Specified by:
  `addAnnotationModel` in interface `IAnnotationModelExtension`
Parameters:
  `key` - the key through which the attachment is identified.
  `attachment` - the attached `IAnnotationModel`

#### getAnnotationModel

    public IAnnotationModel getAnnotationModel​(Object key)

Description copied from interface: `IAnnotationModelExtension`
Returns the attached `IAnnotationModel` for `key`, or `null` if none is attached for `key`.

Specified by:
  `getAnnotationModel` in interface `IAnnotationModelExtension`
Parameters:
  `key` - the key through which the attachment is identified.
Returns:
  an `IAnnotationModel` attached under `key`, or `null`

#### removeAnnotationModel

    public IAnnotationModel removeAnnotationModel​(Object key)

Description copied from interface: `IAnnotationModelExtension`
Removes and returns the attached `IAnnotationModel` for `key`.

Specified by:
  `removeAnnotationModel` in interface `IAnnotationModelExtension`
Parameters:
  `key` - the key through which the attachment is identified.
Returns:
  an `IAnnotationModel` attached under `key`, or `null`

#### getModificationStamp

    public Object getModificationStamp()

Description copied from interface: `IAnnotationModelExtension`
Returns the modification stamp of this annotation model.

Specified by:
  `getModificationStamp` in interface `IAnnotationModelExtension`
Returns:
  the modification stamp of this annotation model