net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IBuffer.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import org.eclipse.core.resources.IResource;
  14 import org.eclipse.core.runtime.IProgressMonitor;
  15
  16 /**
  17  * A buffer contains the text contents of a resource. It is not
  18  * language-specific. The contents may be in the process of being edited,
  19  * differing from the actual contents of the underlying resource. A buffer has
  20  * an owner, which is an <code>IOpenable</code>. If a buffer does not have an
  21  * underlying resource, saving the buffer has no effect. Buffers can be
  22  * read-only.
  23  * <p>
  24  * Note that java model operations that manipulate an <code>IBuffer</code>
  25  * (for example, <code>IType.createMethod(...)</code>) ensures that the same
  26  * line delimiter (either <code>"\n"</code> or <code>"\r"</code> or
  27  * <code>"\r\n"</code>) is used across the whole buffer. Thus these
  28  * operations may change the line delimiter(s) included in the string to be
  29  * append, or replaced. However implementers of this interface should be aware
  30  * that other clients of <code>IBuffer</code> might not do such
  31  * transformations beforehand.
  32  * <p>
  33  * This interface may be implemented by clients.
  34  * </p>
  35  */
  36 public interface IBuffer {
  37
  38         /**
  39          * Adds the given listener for changes to this buffer. Has no effect if an
  40          * identical listener is already registered or if the buffer is closed.
  41          *
  42          * @param listener
  43          *            the listener of buffer changes
  44          */
  45         public void addBufferChangedListener(IBufferChangedListener listener);
  46
  47         /**
  48          * Appends the given character array to the contents of the buffer. This
  49          * buffer will now have unsaved changes. Any client can append to the
  50          * contents of the buffer, not just the owner of the buffer. Reports a
  51          * buffer changed event.
  52          * <p>
  53          * Has no effect if this buffer is read-only.
  54          * <p>
  55          * A <code>RuntimeException</code> might be thrown if the buffer is
  56          * closed.
  57          *
  58          * @param text
  59          *            the given character array to append to contents of the buffer
  60          */
  61         public void append(char[] text);
  62
  63         /**
  64          * Appends the given string to the contents of the buffer. This buffer will
  65          * now have unsaved changes. Any client can append to the contents of the
  66          * buffer, not just the owner of the buffer. Reports a buffer changed event.
  67          * <p>
  68          * Has no effect if this buffer is read-only.
  69          * <p>
  70          * A <code>RuntimeException</code> might be thrown if the buffer is
  71          * closed.
  72          *
  73          * @param text
  74          *            the <code>String</code> to append to the contents of the
  75          *            buffer
  76          */
  77         public void append(String text);
  78
  79         /**
  80          * Closes the buffer. Any unsaved changes are lost. Reports a buffer changed
  81          * event with a 0 offset and a 0 length. When this event is fired, the
  82          * buffer should already be closed.
  83          * <p>
  84          * Further operations on the buffer are not allowed, except for close. If an
  85          * attempt is made to close an already closed buffer, the second attempt has
  86          * no effect.
  87          */
  88         public void close();
  89
  90         /**
  91          * Returns the character at the given position in this buffer.
  92          * <p>
  93          * A <code>RuntimeException</code> might be thrown if the buffer is
  94          * closed.
  95          *
  96          * @param position
  97          *            a zero-based source offset in this buffer
  98          * @return the character at the given position in this buffer
  99          */
 100         public char getChar(int position);
 101
 102         /**
 103          * Returns the contents of this buffer as a character array, or
 104          * <code>null</code> if the buffer has not been initialized.
 105          * <p>
 106          * Callers should make no assumption about whether the returned character
 107          * array is or is not the genuine article or a copy. In other words, if the
 108          * client wishes to change this array, they should make a copy. Likewise, if
 109          * the client wishes to hang on to the array in its current state, they
 110          * should make a copy.
 111          * </p>
 112          * <p>
 113          * A <code>RuntimeException</code> might be thrown if the buffer is
 114          * closed.
 115          *
 116          * @return the characters contained in this buffer
 117          */
 118         public char[] getCharacters();
 119
 120         /**
 121          * Returns the contents of this buffer as a <code>String</code>. Like all
 122          * strings, the result is an immutable value object., It can also answer
 123          * <code>null</code> if the buffer has not been initialized.
 124          * <p>
 125          * A <code>RuntimeException</code> might be thrown if the buffer is
 126          * closed.
 127          *
 128          * @return the contents of this buffer as a <code>String</code>
 129          */
 130         public String getContents();
 131
 132         /**
 133          * Returns number of characters stored in this buffer.
 134          * <p>
 135          * A <code>RuntimeException</code> might be thrown if the buffer is
 136          * closed.
 137          *
 138          * @return the number of characters in this buffer
 139          */
 140         public int getLength();
 141
 142         /**
 143          * Returns the Java openable element owning of this buffer.
 144          *
 145          * @return the openable element owning this buffer
 146          */
 147         public IOpenable getOwner();
 148
 149         /**
 150          * Returns the given range of text in this buffer.
 151          * <p>
 152          * A <code>RuntimeException</code> might be thrown if the buffer is
 153          * closed.
 154          *
 155          * @param offset
 156          *            the zero-based starting offset
 157          * @param length
 158          *            the number of characters to retrieve
 159          * @return the given range of text in this buffer
 160          */
 161         public String getText(int offset, int length);
 162
 163         /**
 164          * Returns the underlying resource for which this buffer was opened, or
 165          * <code>null</code> if this buffer was not opened on a resource.
 166          *
 167          * @return the underlying resource for this buffer, or <code>null</code>
 168          *         if none.
 169          */
 170         public IResource getUnderlyingResource();
 171
 172         /**
 173          * Returns whether this buffer has been modified since it was opened or
 174          * since it was last saved. If a buffer does not have an underlying
 175          * resource, this method always returns <code>true</code>.
 176          *
 177          * @return a <code>boolean</code> indicating presence of unsaved changes
 178          *         (in the absence of any underlying resource, it will always return
 179          *         <code>true</code>).
 180          */
 181         public boolean hasUnsavedChanges();
 182
 183         /**
 184          * Returns whether this buffer has been closed.
 185          *
 186          * @return a <code>boolean</code> indicating whether this buffer is
 187          *         closed.
 188          */
 189         public boolean isClosed();
 190
 191         /**
 192          * Returns whether this buffer is read-only.
 193          *
 194          * @return a <code>boolean</code> indicating whether this buffer is
 195          *         read-only
 196          */
 197         public boolean isReadOnly();
 198
 199         /**
 200          * Removes the given listener from this buffer. Has no affect if an
 201          * identical listener is not registered or if the buffer is closed.
 202          *
 203          * @param listener
 204          *            the listener
 205          */
 206         public void removeBufferChangedListener(IBufferChangedListener listener);
 207
 208         /**
 209          * Replaces the given range of characters in this buffer with the given
 210          * text. <code>position</code> and <code>position + length</code> must
 211          * be in the range [0, getLength()]. <code>length</code> must not be
 212          * negative.
 213          * <p>
 214          * A <code>RuntimeException</code> might be thrown if the buffer is
 215          * closed.
 216          *
 217          * @param position
 218          *            the zero-based starting position of the affected text range in
 219          *            this buffer
 220          * @param length
 221          *            the length of the affected text range in this buffer
 222          * @param text
 223          *            the replacing text as a character array
 224          */
 225         public void replace(int position, int length, char[] text);
 226
 227         /**
 228          * Replaces the given range of characters in this buffer with the given
 229          * text. <code>position</code> and <code>position + length</code> must
 230          * be in the range [0, getLength()]. <code>length</code> must not be
 231          * negative.
 232          * <p>
 233          * A <code>RuntimeException</code> might be thrown if the buffer is
 234          * closed.
 235          *
 236          * @param position
 237          *            the zero-based starting position of the affected text range in
 238          *            this buffer
 239          * @param length
 240          *            the length of the affected text range in this buffer
 241          * @param text
 242          *            the replacing text as a <code>String</code>
 243          */
 244         public void replace(int position, int length, String text);
 245
 246         /**
 247          * Saves the contents of this buffer to its underlying resource. If
 248          * successful, this buffer will have no unsaved changes. The buffer is left
 249          * open. Saving a buffer with no unsaved changes has no effect - the
 250          * underlying resource is not changed. If the buffer does not have an
 251          * underlying resource or is read-only, this has no effect.
 252          * <p>
 253          * The <code>force</code> parameter controls how this method deals with
 254          * cases where the workbench is not completely in sync with the local file
 255          * system. If <code>false</code> is specified, this method will only
 256          * attempt to overwrite a corresponding file in the local file system
 257          * provided it is in sync with the workbench. This option ensures there is
 258          * no unintended data loss; it is the recommended setting. However, if
 259          * <code>true</code> is specified, an attempt will be made to write a
 260          * corresponding file in the local file system, overwriting any existing one
 261          * if need be. In either case, if this method succeeds, the resource will be
 262          * marked as being local (even if it wasn't before).
 263          * <p>
 264          * A <code>RuntimeException</code> might be thrown if the buffer is
 265          * closed.
 266          *
 267          * @param progress
 268          *            the progress monitor to notify
 269          * @param force
 270          *            a <code> boolean </code> flag indicating how to deal with
 271          *            resource inconsistencies.
 272          *
 273          * @exception JavaModelException
 274          *                if an error occurs writing the buffer to the underlying
 275          *                resource
 276          *
 277          * @see org.eclipse.core.resources.IFile#setContents(java.io.InputStream,
 278          *      boolean, boolean, org.eclipse.core.runtime.IProgressMonitor)
 279          */
 280         public void save(IProgressMonitor progress, boolean force)
 281                         throws JavaModelException;
 282
 283         /**
 284          * Sets the contents of this buffer to the given character array. This
 285          * buffer will now have unsaved changes. Any client can set the contents of
 286          * the buffer, not just the owner of the buffer. Reports a buffer changed
 287          * event.
 288          * <p>
 289          * Equivalent to <code>replace(0,getLength(),contents)</code>.
 290          * </p>
 291          * <p>
 292          * Has no effect if this buffer is read-only.
 293          * <p>
 294          * A <code>RuntimeException</code> might be thrown if the buffer is
 295          * closed.
 296          *
 297          * @param contents
 298          *            the new contents of this buffer as a character array
 299          */
 300         public void setContents(char[] contents);
 301
 302         /**
 303          * Sets the contents of this buffer to the given <code>String</code>.
 304          * This buffer will now have unsaved changes. Any client can set the
 305          * contents of the buffer, not just the owner of the buffer. Reports a
 306          * buffer changed event.
 307          * <p>
 308          * Equivalent to <code>replace(0,getLength(),contents)</code>.
 309          * </p>
 310          * <p>
 311          * Has no effect if this buffer is read-only.
 312          * <p>
 313          * A <code>RuntimeException</code> might be thrown if the buffer is
 314          * closed.
 315          *
 316          * @param contents
 317          *            the new contents of this buffer as a <code>String</code>
 318          */
 319         public void setContents(String contents);
 320 }