org.eclipse.jface.text.IDocumentExtension4 Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of aspectjtools Show documentation

AspectJ tools most notably contains the AspectJ compiler (AJC). AJC applies aspects to Java classes during compilation, fully replacing Javac for plain Java classes and also compiling native AspectJ or annotation-based @AspectJ syntax. Furthermore, AJC can weave aspects into existing class files in a post-compile binary weaving step. This library is a superset of AspectJ weaver and hence also of AspectJ runtime.

There is a newer version: 1.9.22.1

Show newest version

/*******************************************************************************
 * Copyright (c) 2000, 2008 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;

/**
 * Extension interface for {@link org.eclipse.jface.text.IDocument}. It adds the
 * following concepts:
 * 
 *   Rewrite sessions. A rewrite session is a sequence of replace operations
 *       that form a semantic unit.
 *   A modification stamp on the document
 *   The ability to set the initial line delimiter and to query the default
 *       line delimiter
 * 
 *
 * @since 3.1
 */
public interface IDocumentExtension4 {

	/**
	 * Tells the document that it is about to be rewritten. That is, a sequence
	 * of replace operations that form a semantic unit will be performed on this
	 * document. A specification of the nature of the operation sequence is
	 * given in form of the session type.
	 * 
	 * The document is considered being in rewrite mode as long as
	 * stopRewriteSession has not been called.
	 *
	 * @param sessionType the session type
	 * @return the started rewrite session
	 * @throws IllegalStateException in case there is already an active rewrite session
	 */
	DocumentRewriteSession startRewriteSession(DocumentRewriteSessionType sessionType) throws IllegalStateException;

	/**
	 * Tells the document to stop the rewrite session. This method has only any
	 * effect if startRewriteSession has been called before.
	 * 

	 * This method does not have any effect if the given session is not the
	 * active rewrite session.
	 *
	 * @param session the session to stop
	 */
	void stopRewriteSession(DocumentRewriteSession session);

	/**
	 * Returns the active rewrite session of this document or null.
	 *
	 * @return the active rewrite session or null
	 */
	DocumentRewriteSession getActiveRewriteSession();

	/**
	 * Registers the document rewrite session listener with the document. After
	 * registration the IDocumentRewriteSessionListener is
	 * informed about each state change of rewrite sessions performed on this
	 * document.
	 * 

	 * If the listener is already registered nothing happens.
	 * 

	 * An IRewriteSessionDocumentListener may call back to this
	 * document when being inside a document notification.
	 *
	 * @param listener the listener to be registered
	 */
	void addDocumentRewriteSessionListener(IDocumentRewriteSessionListener listener);

	/**
	 * Removes the listener from the document's list of document rewrite session
	 * listeners. If the listener is not registered with the document nothing
	 * happens.
	 * 

	 * An IDocumentRewriteSessionListener may call back to this
	 * document when being inside a document notification.
	 *
	 * @param listener the listener to be removed
	 */
	void removeDocumentRewriteSessionListener(IDocumentRewriteSessionListener listener);

	/**
	 * Substitutes the given text for the specified document range.
	 * Sends a DocumentEvent to all registered IDocumentListener.
	 *
	 * @param offset the document offset
	 * @param length the length of the specified range
	 * @param text the substitution text
	 * @param modificationStamp of the document after replacing
	 * @exception BadLocationException if the offset is invalid in this document
	 *
	 * @see DocumentEvent
	 * @see IDocumentListener
	 */
	void replace(int offset, int length, String text, long modificationStamp) throws BadLocationException;

	/**
	 * Replaces the content of the document with the given text.
	 * Sends a DocumentEvent to all registered IDocumentListener.
	 * This method is a convenience method for replace(0, getLength(), text).
	 *
	 * @param text the new content of the document
	 * @param modificationStamp of the document after setting the content
	 *
	 * @see DocumentEvent
	 * @see IDocumentListener
	 */
	void set(String text, long modificationStamp);

	/**
	 * The unknown modification stamp.
	 */
	long UNKNOWN_MODIFICATION_STAMP= -1;

	/**
	 * Returns the modification stamp of this document. The modification stamp
	 * is updated each time a modifying operation is called on this document. If
	 * two modification stamps of the same document are identical then the document
	 * content is too, however, same content does not imply same modification stamp.
	 * 

	 * The magnitude or sign of the numerical difference between two modification stamps
	 * is not significant.
	 * 
	 *
	 * @return the modification stamp of this document or UNKNOWN_MODIFICATION_STAMP
	 */
	long getModificationStamp();

	/**
	 * Returns this document's default line delimiter.
	 * 
	 * This default line delimiter should be used by clients who
	 * want unique delimiters (e.g. 'CR's) in the document.
	 *
	 * @return the default line delimiter or null if none
	 */
	String getDefaultLineDelimiter();

	/**
	 * Sets this document's initial line delimiter i.e. the one
	 * which is returned by getDefaultLineDelimiter
	 * if the document does not yet contain any line delimiter.
	 *
	 * @param lineDelimiter the default line delimiter
	 */
	void setInitialLineDelimiter(String lineDelimiter);
}