IAnnotationModel


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.text.source;
12  
13  
14  import java.util.Iterator  ;
15  
16  import org.eclipse.jface.text.IDocument;
17  import org.eclipse.jface.text.Position;
18  
19  
20  /**
21   * This interface defines the model for managing annotations attached to a document.
22   * The model maintains a set of annotations for a given document and notifies registered annotation
23   * model listeners about annotation model changes. It also provides methods
24   * for querying the current position of an annotation managed
25   * by this model.
26   * <p>
27   * In order to provide backward compatibility for clients of <code>IAnnotationModel</code>, extension
28   * interfaces are used to provide a means of evolution. The following extension interfaces
29   * exist:
30   * <ul>
31   * <li> {@link org.eclipse.jface.text.source.IAnnotationModelExtension} since version 3.0 introducing the concept
32   *      of model piggybacking annotation models, modification time stamps, and enhanced manipulation methods.
33   * </li>
34   * </ul>
35   * </p>
36   *
37   * Clients may implement this interface or use the default implementation provided
38   * by <code>AnnotationModel</code>.
39   *
40   * @see org.eclipse.jface.text.source.IAnnotationModelExtension
41   * @see org.eclipse.jface.text.source.Annotation
42   * @see org.eclipse.jface.text.source.IAnnotationModelListener
43   */
44  public interface IAnnotationModel {
45  
46      /**
47       * Registers the annotation model listener with this annotation model.
48       * After registration listener is informed about each change of this model.
49       * If the listener is already registered nothing happens.
50       *
51       * @param listener the listener to be registered, may not be <code>null</code>
52       */
53      void addAnnotationModelListener(IAnnotationModelListener listener);
54  
55      /**
56       * Removes the listener from the model's list of annotation model listeners.
57       * If the listener is not registered with the model nothing happens.
58       *
59       * @param listener the listener to be removed, may not be <code>null</code>
60       */
61      void removeAnnotationModelListener(IAnnotationModelListener listener);
62  
63      /**
64       * Connects the annotation model to a document. The annotations managed
65       * by this model must subsequently update according to the changes applied
66       * to the document. Once an annotation model is connected to a document,
67       * all further <code>connect</code> calls must mention the document the
68       * model is already connected to. An annotation model primarily uses
69       * <code>connect</code> and <code>disconnect</code> for reference counting
70       * the document. Reference counting frees the clients from keeping tracker
71       * whether a model has already been connected to a document.
72       *
73       * @param document the document the model gets connected to,
74       *      may not be <code>null</code>
75       *
76       * @see #disconnect(IDocument)
77       */
78      void connect(IDocument document);
79  
80      /**
81       * Disconnects this model from a document. After that, document changes no longer matter.
82       * An annotation model may only be disconnected from a document to which it has been
83       * connected before. If the model reference counts the connections to a document,
84       * the connection to the document may only be terminated if the reference count does
85       * down to 0.
86       *
87       * @param document the document the model gets disconnected from,
88       *      may not be <code>null</code>
89       *
90       * @see #connect(IDocument) for further specification details
91       */
92      void disconnect(IDocument document);
93  
94      /**
95       * Adds a annotation to this annotation model. The annotation is associated with
96       * with the given position which describes the range covered by the annotation.
97       * All registered annotation model listeners are informed about the change.
98       * If the model is connected to a document, the position is automatically
99       * updated on document changes. If the annotation is already managed by
100      * this annotation model or is not a valid position in the connected nothing happens.
101      * <p>
102      * <strong>Performance hint:</strong> Use {@link IAnnotationModelExtension#replaceAnnotations(Annotation[], java.util.Map)}
103      * if several annotations are added and/or removed.
104      * </p>
105      *
106      * @param annotation the annotation to add, may not be <code>null</code>
107      * @param position the position describing the range covered by this annotation,
108      *      may not be <code>null</code>
109      */
110     void addAnnotation(Annotation annotation, Position position);
111 
112     /**
113      * Removes the given annotation from the model. I.e. the annotation is no
114      * longer managed by this model. The position associated with the annotation
115      * is no longer updated on document changes. If the annotation is not
116      * managed by this model, nothing happens.
117      * <p>
118      * <strong>Performance hint:</strong> Use {@link IAnnotationModelExtension#replaceAnnotations(Annotation[], java.util.Map)}
119      * if several annotations are removed and/or added.
120      * </p>
121      *
122      * @param annotation the annotation to be removed from this model,
123      *      may not be <code>null</code>
124      */
125     void removeAnnotation(Annotation annotation);
126 
127     /**
128      * Returns all annotations managed by this model.
129      *
130      * @return all annotations managed by this model
131      */
132     Iterator   getAnnotationIterator();
133 
134     /**
135      * Returns the position associated with the given annotation.
136      *
137      * @param annotation the annotation whose position should be returned
138      * @return the position of the given annotation or <code>null</code> if no
139      *      associated annotation exists
140      */
141     Position getPosition(Annotation annotation);
142 }
143 
144
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags