Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 058d68224890fa9d49573e356f1b0c4b9e0b9e21 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
/*******************************************************************************
 * Copyright (c) 2000, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.text.source;

import java.util.Iterator;

import org.eclipse.jface.text.IDocument;
import org.eclipse.jface.text.Position;


/**
 * This interface defines the model for managing annotations attached to a document.
 * The model maintains a set of annotations for a given document and notifies registered annotation
 * model listeners about annotation model changes. It also provides methods
 * for querying the current position of an annotation managed
 * by this model.
 * <p>
 * In order to provide backward compatibility for clients of <code>IAnnotationModel</code>, extension
 * interfaces are used to provide a means of evolution. The following extension interfaces
 * exist:
 * </p>
 * <ul>
 * <li> {@link org.eclipse.jface.text.source.IAnnotationModelExtension} since version 3.0 introducing the concept
 *      of model piggybacking annotation models, modification time stamps, and enhanced manipulation methods.
 * </li>
 * <li> {@link org.eclipse.jface.text.source.IAnnotationModelExtension2} since version 3.4 allows to retrieve
 * 		annotations within a given region.
 * </li>
 * </ul>
 *
 * Clients may implement this interface or use the default implementation provided
 * by <code>AnnotationModel</code>.
 *
 * @see org.eclipse.jface.text.source.IAnnotationModelExtension
 * @see org.eclipse.jface.text.source.IAnnotationModelExtension2
 * @see org.eclipse.jface.text.source.Annotation
 * @see org.eclipse.jface.text.source.IAnnotationModelListener
 */
public 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.
	 *
	 * @param listener the listener to be registered, may not be <code>null</code>
	 */
	void addAnnotationModelListener(IAnnotationModelListener listener);

	/**
	 * Removes the listener from the model's list of annotation model listeners.
	 * If the listener is not registered with the model nothing happens.
	 *
	 * @param listener the listener to be removed, may not be <code>null</code>
	 */
	void removeAnnotationModelListener(IAnnotationModelListener listener);

	/**
	 * 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 <code>connect</code> calls must mention the document the
	 * model is already connected to. An annotation model primarily uses
	 * <code>connect</code> and <code>disconnect</code> for reference counting
	 * the document. Reference counting frees the clients from keeping tracker
	 * whether a model has already been connected to a document.
	 *
	 * @param document the document the model gets connected to,
	 *		may not be <code>null</code>
	 *
	 * @see #disconnect(IDocument)
	 */
	void connect(IDocument document);

	/**
	 * 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.
	 *
	 * @param document the document the model gets disconnected from,
	 *		may not be <code>null</code>
	 *
	 * @see #connect(IDocument) for further specification details
	 */
	void disconnect(IDocument document);

	/**
	 * 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.
	 * <p>
	 * <strong>Performance hint:</strong> Use {@link IAnnotationModelExtension#replaceAnnotations(Annotation[], java.util.Map)}
	 * if several annotations are added and/or removed.
	 * </p>
	 *
	 * @param annotation the annotation to add, may not be <code>null</code>
	 * @param position the position describing the range covered by this annotation,
	 *		may not be <code>null</code>
	 */
	void addAnnotation(Annotation annotation, Position position);

	/**
	 * 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.
	 * <p>
	 * <strong>Performance hint:</strong> Use {@link IAnnotationModelExtension#replaceAnnotations(Annotation[], java.util.Map)}
	 * if several annotations are removed and/or added.
	 * </p>
	 *
	 * @param annotation the annotation to be removed from this model,
	 *		may not be <code>null</code>
	 */
	void removeAnnotation(Annotation annotation);

	/**
	 * Returns all annotations managed by this model.
	 *
	 * @return all annotations managed by this model
	 */
	Iterator<Annotation> getAnnotationIterator();

	/**
	 * Returns the position associated with the given annotation.
	 *
	 * @param annotation the annotation whose position should be returned
	 * @return the position of the given annotation or <code>null</code> if no
	 *		associated annotation exists
	 */
	Position getPosition(Annotation annotation);
}

Back to the top