| /******************************************************************************* |
| * Copyright (c) 2000, 2015 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * 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: |
| * <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> |
| * </p> |
| * |
| * 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); |
| } |
| |