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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.resources.IResource;
14 import org.eclipse.core.runtime.IProgressMonitor;
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
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.
33 * This interface may be implemented by clients.
36 public interface IBuffer {
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.
43 * the listener of buffer changes
45 public void addBufferChangedListener(IBufferChangedListener listener);
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.
53 * Has no effect if this buffer is read-only.
55 * A <code>RuntimeException</code> might be thrown if the buffer is
59 * the given character array to append to contents of the buffer
61 public void append(char[] text);
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.
68 * Has no effect if this buffer is read-only.
70 * A <code>RuntimeException</code> might be thrown if the buffer is
74 * the <code>String</code> to append to the contents of the
77 public void append(String text);
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.
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
91 * Returns the character at the given position in this buffer.
93 * A <code>RuntimeException</code> might be thrown if the buffer is
97 * a zero-based source offset in this buffer
98 * @return the character at the given position in this buffer
100 public char getChar(int position);
103 * Returns the contents of this buffer as a character array, or
104 * <code>null</code> if the buffer has not been initialized.
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.
113 * A <code>RuntimeException</code> might be thrown if the buffer is
116 * @return the characters contained in this buffer
118 public char[] getCharacters();
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.
125 * A <code>RuntimeException</code> might be thrown if the buffer is
128 * @return the contents of this buffer as a <code>String</code>
130 public String getContents();
133 * Returns number of characters stored in this buffer.
135 * A <code>RuntimeException</code> might be thrown if the buffer is
138 * @return the number of characters in this buffer
140 public int getLength();
143 * Returns the Java openable element owning of this buffer.
145 * @return the openable element owning this buffer
147 public IOpenable getOwner();
150 * Returns the given range of text in this buffer.
152 * A <code>RuntimeException</code> might be thrown if the buffer is
156 * the zero-based starting offset
158 * the number of characters to retrieve
159 * @return the given range of text in this buffer
161 public String getText(int offset, int length);
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.
167 * @return the underlying resource for this buffer, or <code>null</code>
170 public IResource getUnderlyingResource();
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>.
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>).
181 public boolean hasUnsavedChanges();
184 * Returns whether this buffer has been closed.
186 * @return a <code>boolean</code> indicating whether this buffer is
189 public boolean isClosed();
192 * Returns whether this buffer is read-only.
194 * @return a <code>boolean</code> indicating whether this buffer is
197 public boolean isReadOnly();
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.
206 public void removeBufferChangedListener(IBufferChangedListener listener);
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
214 * A <code>RuntimeException</code> might be thrown if the buffer is
218 * the zero-based starting position of the affected text range in
221 * the length of the affected text range in this buffer
223 * the replacing text as a character array
225 public void replace(int position, int length, char[] text);
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
233 * A <code>RuntimeException</code> might be thrown if the buffer is
237 * the zero-based starting position of the affected text range in
240 * the length of the affected text range in this buffer
242 * the replacing text as a <code>String</code>
244 public void replace(int position, int length, String text);
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.
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).
264 * A <code>RuntimeException</code> might be thrown if the buffer is
268 * the progress monitor to notify
270 * a <code> boolean </code> flag indicating how to deal with
271 * resource inconsistencies.
273 * @exception JavaModelException
274 * if an error occurs writing the buffer to the underlying
277 * @see org.eclipse.core.resources.IFile#setContents(java.io.InputStream,
278 * boolean, boolean, org.eclipse.core.runtime.IProgressMonitor)
280 public void save(IProgressMonitor progress, boolean force)
281 throws JavaModelException;
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
289 * Equivalent to <code>replace(0,getLength(),contents)</code>.
292 * Has no effect if this buffer is read-only.
294 * A <code>RuntimeException</code> might be thrown if the buffer is
298 * the new contents of this buffer as a character array
300 public void setContents(char[] contents);
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.
308 * Equivalent to <code>replace(0,getLength(),contents)</code>.
311 * Has no effect if this buffer is read-only.
313 * A <code>RuntimeException</code> might be thrown if the buffer is
317 * the new contents of this buffer as a <code>String</code>
319 public void setContents(String contents);