01660ae0414c435b3575274853cc2f2c24a4ff7e
[phpeclipse.git] / 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 }