package org.eclipse.jdt.core; /* * (c) Copyright IBM Corp. 2000, 2001. * All Rights Reserved. */ 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 IOpenable. * If a buffer does not have an underlying resource, saving the buffer has no effect. * Buffers can be read-only. *

* This interface is not intended to be implemented by clients. *

*/ public interface IBuffer { /** * Adds the given listener for changes to this buffer. * Has no effect if an identical listener is already registered. * * @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. * *

Has no effect if this buffer is read-only. * * @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. * *

Has no effect if this buffer is read-only. * * @param text the String 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. * 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. * * @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. *

* 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. *

* * @return the characters contained in this buffer */ public char[] getCharacters(); /** * Returns the contents of this buffer as a String. Like all strings, * the result is an immutable value object. * * @return the contents of this buffer as a String */ public String getContents(); /** * Returns number of characters stored in this buffer. * * @return the number of characters in this buffer */ public int getLength(); /** * Returns the Java 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. * * @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 null if this buffer was not opened on a resource. * * @return the underlying resource for this buffer, or null * 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 true. * * @return a boolean indicating presence of unsaved changes (in * the absence of any underlying resource, it will always return true). */ public boolean hasUnsavedChanges(); /** * Returns whether this buffer has been closed. * * @return a boolean indicating whether this buffer is closed. */ public boolean isClosed(); /** * Returns whether this buffer is read-only. * * @return a boolean 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. * * @param listener the listener */ public void removeBufferChangedListener(IBufferChangedListener listener); /** * Replaces the given range of characters in this buffer with the given text. * position and position + length must be in the range [0, getLength()]. * length must not be negative. * * @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. * position and position + length must be in the range [0, getLength()]. * length must not be negative. * * @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 String */ 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. *

* The force parameter controls how this method deals with * cases where the workbench is not completely in sync with the local file system. * If false 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 true 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). * * @param monitor the progress monitor to notify * @param force a boolean flag indicating how to deal with resource * inconsistencies. * * @exception JavaModelException if an error occurs writing the buffer * to the underlying resource * * @see org.eclipse.core.resources.IFile#setContents(InputStream, boolean, boolean, IProgressMonitor) */ public void save(IProgressMonitor progress, boolean force) throws JavaModelException; /** * 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. *

* Equivalent to replace(0,getLength(),contents). *

* *

Has no effect if this buffer is read-only. * * @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 String. * 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. *

* Equivalent to replace(0,getLength(),contents). *

* *

Has no effect if this buffer is read-only. * * @param contents the new contents of this buffer as a String */ public void setContents(String contents); }