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

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