content: /*******************************************************************************
   * Copyright (c) 2000, 2007 IBM Corporation and others.
   * This program and the accompanying materials are made available under the
   * terms of the Eclipse Public License v. 2.0 which is available at
   * http://www.eclipse.org/legal/epl-2.0.
   * 
   * SPDX-License-Identifier: EPL-2.0
   *
   
   *******************************************************************************/
  package org.eclipse.dltk.core;
  
  //import org.eclipse.core.resources.IResource;
  //import org.eclipse.core.runtime.IProgressMonitor;
  
  /**
   * A buffer contains the text contents of a resource. It is not
   * language-specific. The contents may be in the process of being edited,
   * differing from the actual contents of the underlying resource. A buffer has
   * an owner, which is an <code>IOpenable</code>. If a buffer does not have an
   * underlying resource, saving the buffer has no effect. Buffers can be
   * read-only.
   * <p>
   * Note that model operations that manipulate an <code>IBuffer</code>
   * (for example, <code>IType.createMethod(...)</code>) ensures that the same
   * line delimiter (either <code>"\n"</code> or <code>"\r"</code> or
   * <code>"\r\n"</code>) is used across the whole buffer. Thus these
   * operations may change the line delimiter(s) included in the string to be
   * append, or replaced. However implementers of this interface should be aware
   * that other clients of <code>IBuffer</code> might not do such
   * transformations beforehand.
   * <p>
   * This interface may be implemented by clients.
   * </p>
   */
  public interface IBuffer {
  
  	/**
  	 * Adds the given listener for changes to this buffer. Has no effect if an
  	 * identical listener is already registered or if the buffer is closed.
  	 * 
  	 * @param listener
  	 *            the listener of buffer changes
  	 */
  	public void addBufferChangedListener(IBufferChangedListener listener);
  
  	/**
  	 * Appends the given character array to the contents of the buffer. This
  	 * buffer will now have unsaved changes. Any client can append to the
  	 * contents of the buffer, not just the owner of the buffer. Reports a
  	 * buffer changed event.
  	 * <p>
  	 * Has no effect if this buffer is read-only or if the buffer is closed.
  	 * 
  	 * @param text
  	 *            the given character array to append to contents of the buffer
  	 */
  	public void append(char[] text);
  
  	/**
  	 * Appends the given string to the contents of the buffer. This buffer will
  	 * now have unsaved changes. Any client can append to the contents of the
  	 * buffer, not just the owner of the buffer. Reports a buffer changed event.
  	 * <p>
  	 * Has no effect if this buffer is read-only or if the buffer is closed.
  	 * 
  	 * @param text
  	 *            the <code>String</code> to append to the contents of the
  	 *            buffer
  	 */
  	public void append(String text);
  
  	/**
  	 * Closes the buffer. Any unsaved changes are lost. Reports a buffer changed
  	 * event with a 0 offset and a 0 length. When this event is fired, the
  	 * buffer should already be closed.
  	 * <p>
  	 * Further operations on the buffer are not allowed, except for close. If an
  	 * attempt is made to close an already closed buffer, the second attempt has
  	 * no effect.
  	 */
  	public void close();
  
  	/**
  	 * Returns the character at the given position in this buffer.
  	 * <p>
  	 * The returned value is undefined if the buffer is closed.
  	 * 
  	 * @param position
  	 *            a zero-based source offset in this buffer
  	 * @return the character at the given position in this buffer
  	 */
  	public char getChar(int position);
  
  	/**
  	 * Returns the contents of this buffer as a character array, or
  	 * <code>null</code> if the buffer has not been initialized.
  	 * <p>
  	 * Callers should make no assumption about whether the returned character
  	 * array is or is not the genuine article or a copy. In other words, if the
  	 * client wishes to change this array, they should make a copy. Likewise, if
  	 * the client wishes to hang on to the array in its current state, they
  	 * should make a copy.
  	 * </p>
  	 * <p>
  	 * The returned value is undefined if the buffer is closed.
  	 * 
  	 * @return the characters contained in this buffer
  	 */
  	public char[] getCharacters();
  
  	/**
  	 * Returns the contents of this buffer as a <code>String</code>. Like all
  	 * strings, the result is an immutable value object., It can also answer
  	 * <code>null</code> if the buffer has not been initialized.
  	 * <p>
  	 * The returned value is undefined if the buffer is closed.
  	 * 
  	 * @return the contents of this buffer as a <code>String</code>
  	 */
  	public String getContents();
  
  	/**
  	 * Returns number of characters stored in this buffer.
  	 * <p>
  	 * The returned value is undefined if the buffer is closed.
  	 * 
  	 * @return the number of characters in this buffer
  	 */
  	public int getLength();
  
  	/**
  	 * Returns the openable element owning of this buffer.
  	 * 
  	 * @return the openable element owning this buffer
  	 */
  	public IOpenable getOwner();
  
  	/**
  	 * Returns the given range of text in this buffer.
  	 * <p>
  	 * The returned value is undefined if the buffer is closed.
  	 * 
  	 * @param offset
  	 *            the zero-based starting offset
  	 * @param length
  	 *            the number of characters to retrieve
  	 * @return the given range of text in this buffer
  	 */
  	public String getText(int offset, int length);
  
  //	/**
  //	 * Returns the underlying resource for which this buffer was opened, or
  //	 * <code>null</code> if this buffer was not opened on a resource.
  //	 *
  //	 * @return the underlying resource for this buffer, or <code>null</code>
  //	 *         if none.
  //	 */
  //	public IResource getUnderlyingResource();
  
  	/**
  	 * Returns whether this buffer has been modified since it was opened or
  	 * since it was last saved. If a buffer does not have an underlying
  	 * resource, this method always returns <code>true</code>.
  	 * <p>
  	 * NOTE: when a buffer does not have unsaved changes, the model may decide
  	 * to close it to claim some memory back. If the associated element needs to
  	 * be reopened later on, its buffer factory will be requested to create a
  	 * new buffer.
  	 * </p>
  	 * 
  	 * @return a <code>boolean</code> indicating presence of unsaved changes
  	 *         (in the absence of any underlying resource, it will always return
  	 *         <code>true</code>).
  	 */
  	public boolean hasUnsavedChanges();
  
  	/**
  	 * Returns whether this buffer has been closed.
  	 * 
  	 * @return a <code>boolean</code> indicating whether this buffer is
  	 *         closed.
  	 */
  	public boolean isClosed();
  
  	/**
  	 * Returns whether this buffer is read-only.
  	 * 
  	 * @return a <code>boolean</code> indicating whether this buffer is
  	 *         read-only
  	 */
  	public boolean isReadOnly();
  
  	/**
  	 * Removes the given listener from this buffer. Has no affect if an
  	 * identical listener is not registered or if the buffer is closed.
  	 * 
  	 * @param listener
  	 *            the listener
  	 */
  	public void removeBufferChangedListener(IBufferChangedListener listener);
  
  	/**
  	 * Replaces the given range of characters in this buffer with the given
  	 * text. <code>position</code> and <code>position + length</code> must
  	 * be in the range [0, getLength()]. <code>length</code> must not be
  	 * negative.
  	 * <p>
  	 * Has no effect if this buffer is read-only or if the buffer is closed.
  	 * 
  	 * @param position
  	 *            the zero-based starting position of the affected text range in
  	 *            this buffer
  	 * @param length
  	 *            the length of the affected text range in this buffer
  	 * @param text
  	 *            the replacing text as a character array
  	 */
  	public void replace(int position, int length, char[] text);
  
  	/**
  	 * Replaces the given range of characters in this buffer with the given
  	 * text. <code>position</code> and <code>position + length</code> must
  	 * be in the range [0, getLength()]. <code>length</code> must not be
  	 * negative.
  	 * <p>
  	 * Has no effect if this buffer is read-only or if the buffer is closed.
  	 * 
  	 * @param position
  	 *            the zero-based starting position of the affected text range in
  	 *            this buffer
  	 * @param length
  	 *            the length of the affected text range in this buffer
  	 * @param text
  	 *            the replacing text as a <code>String</code>
  	 */
  	public void replace(int position, int length, String text);
  
  //	/**
  //	 * Saves the contents of this buffer to its underlying resource. If
  //	 * successful, this buffer will have no unsaved changes. The buffer is left
  //	 * open. Saving a buffer with no unsaved changes has no effect - the
  //	 * underlying resource is not changed. If the buffer does not have an
  //	 * underlying resource or is read-only, this has no effect.
  //	 * <p>
  //	 * The <code>force</code> parameter controls how this method deals with
  //	 * cases where the workbench is not completely in sync with the local file
  //	 * system. If <code>false</code> is specified, this method will only
  //	 * attempt to overwrite a corresponding file in the local file system
  //	 * provided it is in sync with the workbench. This option ensures there is
  //	 * no unintended data loss; it is the recommended setting. However, if
  //	 * <code>true</code> is specified, an attempt will be made to write a
  //	 * corresponding file in the local file system, overwriting any existing one
  //	 * if need be. In either case, if this method succeeds, the resource will be
  //	 * marked as being local (even if it wasn't before).
  //	 * <p>
  //	 * Has no effect if this buffer is read-only or if the buffer is closed.
  //	 *
  //	 * @param progress
  //	 *            the progress monitor to notify
  //	 * @param force
  //	 *            a <code> boolean </code> flag indicating how to deal with
  //	 *            resource inconsistencies.
  //	 *
  //	 * @exception ModelException
  //	 *                if an error occurs writing the buffer to the underlying
  //	 *                resource
  //	 *
  //	 * @see org.eclipse.core.resources.IFile#setContents(java.io.InputStream,
  //	 *      boolean, boolean, org.eclipse.core.runtime.IProgressMonitor)
  //	 */
  //	public void save(IProgressMonitor progress, boolean force)
  //			throws ModelException;
  
  	/**
  	 * Sets the contents of this buffer to the given character array. This
  	 * buffer will now have unsaved changes. Any client can set the contents of
  	 * the buffer, not just the owner of the buffer. Reports a buffer changed
  	 * event.
  	 * <p>
  	 * Equivalent to <code>replace(0,getLength(),contents)</code>.
  	 * </p>
  	 * <p>
  	 * Has no effect if this buffer is read-only or if the buffer is closed.
  	 * 
  	 * @param contents
  	 *            the new contents of this buffer as a character array
  	 */
  	public void setContents(char[] contents);
  
  	/**
  	 * Sets the contents of this buffer to the given <code>String</code>.
  	 * This buffer will now have unsaved changes. Any client can set the
  	 * contents of the buffer, not just the owner of the buffer. Reports a
  	 * buffer changed event.
  	 * <p>
  	 * Equivalent to <code>replace(0,getLength(),contents)</code>.
  	 * </p>
  	 * <p>
  	 * Has no effect if this buffer is read-only or if the buffer is closed.
  	 * 
  	 * @param contents
  	 *            the new contents of this buffer as a <code>String</code>
  	 */
  	public void setContents(String contents);
  }
  