IOpenable. If a buffer does not have an
* underlying resource, saving the buffer has no effect. Buffers can be
* read-only.
*
* Note that java model operations that manipulate an IBuffer
* (for example, IType.createMethod(...)) ensures that the same
* line delimiter (either "\n" or "\r" or
* "\r\n") 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 IBuffer might not do such
* transformations beforehand.
*
* This interface may 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 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. ** Has no effect if this buffer is read-only. *
* A RuntimeException might be thrown 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.
*
* Has no effect if this buffer is read-only. *
* A RuntimeException might be thrown if the buffer is
* closed.
*
* @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 with a 0 offset and a 0 length. When this event is fired, the
* buffer should already be closed.
*
* 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. *
* A RuntimeException might be thrown 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
* null if the buffer has not been initialized.
*
* 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. *
*
* A RuntimeException might be thrown if the buffer is
* closed.
*
* @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., It can also answer
* null if the buffer has not been initialized.
*
* A RuntimeException might be thrown if the buffer is
* closed.
*
* @return the contents of this buffer as a String
*/
public String getContents();
/**
* Returns number of characters stored in this buffer.
*
* A RuntimeException might be thrown if the buffer is
* closed.
*
* @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.
*
* A RuntimeException might be thrown 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
* 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 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. position and position + length must
* be in the range [0, getLength()]. length must not be
* negative.
*
* A RuntimeException might be thrown 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. position and position + length must
* be in the range [0, getLength()]. length must not be
* negative.
*
* A RuntimeException might be thrown 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 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).
*
* A RuntimeException might be thrown if the buffer is
* closed.
*
* @param progress
* 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(java.io.InputStream,
* boolean, boolean, org.eclipse.core.runtime.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. *
* A RuntimeException might be thrown 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 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. *
* A RuntimeException might be thrown if the buffer is
* closed.
*
* @param contents
* the new contents of this buffer as a String
*/
public void setContents(String contents);
}