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   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   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   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   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   contents);
256 }
257
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags