KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > IBuffer


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.jdt.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> (for example,
24  * <code>IType.createMethod(...)</code>) ensures that the same line delimiter
25  * (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 or if the buffer is closed.
51  *
52  * @param text the given character array to append to contents of the buffer
53  */

54 public void append(char[] text);
55 /**
56  * Appends the given string to the contents of the buffer.
57  * This buffer will now have unsaved changes.
58  * Any client can append to the contents of the buffer, not just the owner of the buffer.
59  * Reports a buffer changed event.
60  * <p>
61  * Has no effect if this buffer is read-only or if the buffer is closed.
62  *
63  * @param text the <code>String</code> to append to the contents of the buffer
64  */

65 public void append(String JavaDoc text);
66 /**
67  * Closes the buffer. Any unsaved changes are lost. Reports a buffer changed event
68  * with a 0 offset and a 0 length. When this event is fired, the buffer should already
69  * be closed.
70  * <p>
71  * Further operations on the buffer are not allowed, except for close. If an
72  * attempt is made to close an already closed buffer, the second attempt has no effect.
73  */

74 public void close();
75 /**
76  * Returns the character at the given position in this buffer.
77  * <p>
78  * The returned value is undefined if the buffer is closed.
79  *
80  * @param position a zero-based source offset in this buffer
81  * @return the character at the given position in this buffer
82  */

83 public char getChar(int position);
84 /**
85  * Returns the contents of this buffer as a character array, or <code>null</code> if
86  * the buffer has not been initialized.
87  * <p>
88  * Callers should make no assumption about whether the returned character array
89  * is or is not the genuine article or a copy. In other words, if the client
90  * wishes to change this array, they should make a copy. Likewise, if the
91  * client wishes to hang on to the array in its current state, they should
92  * make a copy.
93  * </p><p>
94  * The returned value is undefined if the buffer is closed.
95  *
96  * @return the characters contained in this buffer
97  */

98 public char[] getCharacters();
99 /**
100  * Returns the contents of this buffer as a <code>String</code>. Like all strings,
101  * the result is an immutable value object., It can also answer <code>null</code> if
102  * the buffer has not been initialized.
103  * <p>
104  * The returned value is undefined if the buffer is closed.
105  *
106  * @return the contents of this buffer as a <code>String</code>
107  */

108 public String JavaDoc getContents();
109 /**
110  * Returns number of characters stored in this buffer.
111  * <p>
112  * The returned value is undefined if the buffer is closed.
113  *
114  * @return the number of characters in this buffer
115  */

116 public int getLength();
117 /**
118  * Returns the Java openable element owning of this buffer.
119  *
120  * @return the openable element owning this buffer
121  */

122 public IOpenable getOwner();
123 /**
124  * Returns the given range of text in this buffer.
125  * <p>
126  * The returned value is undefined if the buffer is closed.
127  *
128  * @param offset the zero-based starting offset
129  * @param length the number of characters to retrieve
130  * @return the given range of text in this buffer
131  */

132 public String JavaDoc getText(int offset, int length);
133 /**
134  * Returns the underlying resource for which this buffer was opened,
135  * or <code>null</code> if this buffer was not opened on a resource.
136  *
137  * @return the underlying resource for this buffer, or <code>null</code>
138  * if none.
139  */

140 public IResource getUnderlyingResource();
141 /**
142  * Returns whether this buffer has been modified since it
143  * was opened or since it was last saved.
144  * If a buffer does not have an underlying resource, this method always
145  * returns <code>true</code>.
146  * <p>
147  * NOTE: when a buffer does not have unsaved changes, the model may decide to close it
148  * to claim some memory back. If the associated element needs to be reopened later on, its
149  * buffer factory will be requested to create a new buffer.
150  * </p>
151  * @return a <code>boolean</code> indicating presence of unsaved changes (in
152  * the absence of any underlying resource, it will always return <code>true</code>).
153  */

154 public boolean hasUnsavedChanges();
155 /**
156  * Returns whether this buffer has been closed.
157  *
158  * @return a <code>boolean</code> indicating whether this buffer is closed.
159  */

160 public boolean isClosed();
161 /**
162  * Returns whether this buffer is read-only.
163  *
164  * @return a <code>boolean</code> indicating whether this buffer is read-only
165  */

166 public boolean isReadOnly();
167 /**
168  * Removes the given listener from this buffer.
169  * Has no affect if an identical listener is not registered or if the buffer is closed.
170  *
171  * @param listener the listener
172  */

173 public void removeBufferChangedListener(IBufferChangedListener listener);
174 /**
175  * Replaces the given range of characters in this buffer with the given text.
176  * <code>position</code> and <code>position + length</code> must be in the range [0, getLength()].
177  * <code>length</code> must not be negative.
178  * <p>
179  * Has no effect if this buffer is read-only or if the buffer is closed.
180  *
181  * @param position the zero-based starting position of the affected text range in this buffer
182  * @param length the length of the affected text range in this buffer
183  * @param text the replacing text as a character array
184  */

185 public void replace(int position, int length, char[] text);
186 /**
187  * Replaces the given range of characters in this buffer with the given text.
188  * <code>position</code> and <code>position + length</code> must be in the range [0, getLength()].
189  * <code>length</code> must not be negative.
190  * <p>
191  * Has no effect if this buffer is read-only or if the buffer is closed.
192  *
193  * @param position the zero-based starting position of the affected text range in this buffer
194  * @param length the length of the affected text range in this buffer
195  * @param text the replacing text as a <code>String</code>
196  */

197 public void replace(int position, int length, String JavaDoc text);
198 /**
199  * Saves the contents of this buffer to its underlying resource. If
200  * successful, this buffer will have no unsaved changes.
201  * The buffer is left open. Saving a buffer with no unsaved
202  * changes has no effect - the underlying resource is not changed.
203  * If the buffer does not have an underlying resource or is read-only, this
204  * has no effect.
205  * <p>
206  * The <code>force</code> parameter controls how this method deals with
207  * cases where the workbench is not completely in sync with the local file system.
208  * If <code>false</code> is specified, this method will only attempt
209  * to overwrite a corresponding file in the local file system provided
210  * it is in sync with the workbench. This option ensures there is no
211  * unintended data loss; it is the recommended setting.
212  * However, if <code>true</code> is specified, an attempt will be made
213  * to write a corresponding file in the local file system,
214  * overwriting any existing one if need be.
215  * In either case, if this method succeeds, the resource will be marked
216  * as being local (even if it wasn't before).
217  * <p>
218  * Has no effect if this buffer is read-only or if the buffer is closed.
219  *
220  * @param progress the progress monitor to notify
221  * @param force a <code> boolean </code> flag indicating how to deal with resource
222  * inconsistencies.
223  *
224  * @exception JavaModelException if an error occurs writing the buffer
225  * to the underlying resource
226  *
227  * @see org.eclipse.core.resources.IFile#setContents(java.io.InputStream, boolean, boolean, org.eclipse.core.runtime.IProgressMonitor)
228  */

229 public void save(IProgressMonitor progress, boolean force) throws JavaModelException;
230 /**
231  * Sets the contents of this buffer to the given character array.
232  * This buffer will now have unsaved changes.
233  * Any client can set the contents of the buffer, not just the owner of the buffer.
234  * Reports a buffer changed event.
235  * <p>
236  * Equivalent to <code>replace(0,getLength(),contents)</code>.
237  * </p><p>
238  * Has no effect if this buffer is read-only or if the buffer is closed.
239  *
240  * @param contents the new contents of this buffer as a character array
241  */

242 public void setContents(char[] contents);
243 /**
244  * Sets the contents of this buffer to the given <code>String</code>.
245  * This buffer will now have unsaved changes.
246  * Any client can set the contents of the buffer, not just the owner of the buffer.
247  * Reports a buffer changed event.
248  * <p>
249  * Equivalent to <code>replace(0,getLength(),contents)</code>.
250  * </p><p>
251  * Has no effect if this buffer is read-only or if the buffer is closed.
252  *
253  * @param contents the new contents of this buffer as a <code>String</code>
254  */

255 public void setContents(String JavaDoc contents);
256 }
257
Popular Tags