KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > text > IDocument


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
12 package org.eclipse.jface.text;
13
14
15 /**
16  * An <code>IDocument</code> represents text providing support for
17  * <ul>
18  * <li> text manipulation
19  * <li> positions
20  * <li> partitions
21  * <li> line information
22  * <li> document change listeners
23  * <li> document partition change listeners
24  * </ul>
25  *
26  * A document allows to set its content and to manipulate it. For manipulation
27  * a document provides the <code>replace</code> method which substitutes a given
28  * string for a specified text range in the document. On each document change, all
29  * registered document listeners are informed exactly once.
30  * <p>
31  * Positions are stickers to the document's text that are updated when the
32  * document is changed. Positions are updated by {@link org.eclipse.jface.text.IPositionUpdater}s. Position
33  * updaters are managed as a list. The list defines the sequence in which position
34  * updaters are invoked. This way, position updaters may rely on each other.
35  * Positions are grouped into categories. A category is a ordered list of positions.
36  * the document defines the order of position in a category based on the position's offset
37  * based on the implementation of the method <code>computeIndexInCategory</code>.
38  * Each document must support a default position category whose name is specified by this
39  * interface.</p>
40  * <p>
41  * A document can be considered consisting of a sequence of not overlapping partitions.
42  * A partition is defined by its offset, its length, and its type. Partitions are
43  * updated on every document manipulation and ensured to be up-to-date when the document
44  * listeners are informed. A document uses an <code>IDocumentPartitioner</code> to
45  * manage its partitions. A document may be unpartitioned which happens when there is no
46  * partitioner. In this case, the document is considered as one single partition of a
47  * default type. The default type is specified by this interface. If a document change
48  * changes the document's partitioning all registered partitioning listeners are
49  * informed exactly once. The extension interface {@link org.eclipse.jface.text.IDocumentExtension3}
50  * introduced in version 3.0 extends the concept of partitions and allows a document to
51  * not only manage one but multiple partitioning. Each partitioning has an id which must
52  * be used to refer to a particular partitioning.</p>
53  * <p>
54  * An <code>IDocument</code> provides methods to map line numbers and character
55  * positions onto each other based on the document's line delimiters. When moving text
56  * between documents using different line delimiters, the text must be converted to
57  * use the target document's line delimiters.</p>
58  * <p>
59  * An <code>IDocument</code> does not care about mixed line delimiters. Clients who
60  * want to ensure a single line delimiter in their document should use the line
61  * delimiter returned by {@link org.eclipse.jface.text.TextUtilities#getDefaultLineDelimiter(IDocument)}.</p>
62  * <p>
63  * <code>IDocument</code> throws <code>BadLocationException</code> if the parameters of
64  * queries or manipulation requests are not inside the bounds of the document. The purpose
65  * of this style of exception handling is
66  * <ul>
67  * <li> prepare document for multi-thread access
68  * <li> allow clients to implement backtracking recovery methods
69  * <li> prevent clients from up-front contract checking when dealing with documents.
70  * </ul></p>
71  * <p>
72  * A document support for searching has deprecated since version 3.0. The recommended way
73  * for searching is to use a {@link org.eclipse.jface.text.FindReplaceDocumentAdapter}.</p>
74  * <p>
75  * In order to provide backward compatibility for clients of <code>IDocument</code>, extension
76  * interfaces are used to provide a means of evolution. The following extension interfaces
77  * exist:
78  * <ul>
79  * <li> {@link org.eclipse.jface.text.IDocumentExtension} since version 2.0 introducing the concept
80  * of post notification replaces in order to allow document listeners to manipulate the document
81  * while receiving a document change notification </li>
82  * <li> {@link org.eclipse.jface.text.IDocumentExtension2} since version 2.1 introducing configuration
83  * methods for post notification replaces and document change notification. </li>
84  * <li> {@link org.eclipse.jface.text.IDocumentExtension3} since version 3.0 replacing the original
85  * partitioning concept by allowing multiple partitionings at the same time and introducing zero-
86  * length partitions in conjunction with the distinction between open and closed partitions. </li>
87  * <li> {@link org.eclipse.jface.text.IDocumentExtension4} since version 3.1 introducing the
88  * concept of rewrite sessions. A rewrite session is a sequence of document replace operations
89  * that form a semantic unit. It also introduces a modification stamp and the ability to
90  * set the initial line delimiter and to query the default line delimiter.</li>
91  * </ul></p>
92  * <p>
93  * Clients may implement this interface and its extension interfaces or use the default
94  * implementation provided by <code>AbstractDocument</code> and <code>Document</code>.</p>
95  *
96  * @see org.eclipse.jface.text.IDocumentExtension
97  * @see org.eclipse.jface.text.IDocumentExtension2
98  * @see org.eclipse.jface.text.IDocumentExtension3
99  * @see org.eclipse.jface.text.IDocumentExtension4
100  * @see org.eclipse.jface.text.Position
101  * @see org.eclipse.jface.text.IPositionUpdater
102  * @see org.eclipse.jface.text.IDocumentPartitioner
103  * @see org.eclipse.jface.text.ILineTracker
104  * @see org.eclipse.jface.text.IDocumentListener
105  * @see org.eclipse.jface.text.IDocumentPartitioningListener
106  */

107 public interface IDocument {
108
109
110     /**
111      * The identifier of the default position category.
112      */

113     final static String JavaDoc DEFAULT_CATEGORY= "__dflt_position_category"; //$NON-NLS-1$
114

115     /**
116      * The identifier of the default partition content type.
117      */

118     final static String JavaDoc DEFAULT_CONTENT_TYPE= "__dftl_partition_content_type"; //$NON-NLS-1$
119

120
121
122
123     /* --------------- text access and manipulation --------------------------- */
124
125     /**
126      * Returns the character at the given document offset in this document.
127      *
128      * @param offset a document offset
129      * @return the character at the offset
130      * @exception BadLocationException if the offset is invalid in this document
131      */

132     char getChar(int offset) throws BadLocationException;
133
134     /**
135      * Returns the number of characters in this document.
136      *
137      * @return the number of characters in this document
138      */

139     int getLength();
140
141     /**
142      * Returns this document's complete text.
143      *
144      * @return the document's complete text
145      */

146     String JavaDoc get();
147
148     /**
149      * Returns this document's text for the specified range.
150      *
151      * @param offset the document offset
152      * @param length the length of the specified range
153      * @return the document's text for the specified range
154      * @exception BadLocationException if the range is invalid in this document
155      */

156     String JavaDoc get(int offset, int length) throws BadLocationException;
157
158     /**
159      * Replaces the content of the document with the given text.
160      * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>.
161      * This method is a convenience method for <code>replace(0, getLength(), text)</code>.
162      *
163      * @param text the new content of the document
164      *
165      * @see DocumentEvent
166      * @see IDocumentListener
167      */

168     void set(String JavaDoc text);
169
170     /**
171      * Substitutes the given text for the specified document range.
172      * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>.
173      *
174      * @param offset the document offset
175      * @param length the length of the specified range
176      * @param text the substitution text
177      * @exception BadLocationException if the offset is invalid in this document
178      *
179      * @see DocumentEvent
180      * @see IDocumentListener
181      */

182     void replace(int offset, int length, String JavaDoc text) throws BadLocationException;
183
184     /**
185      * Registers the document listener with the document. After registration
186      * the IDocumentListener is informed about each change of this document.
187      * If the listener is already registered nothing happens.<p>
188      * An <code>IDocumentListener</code> may call back to this method
189      * when being inside a document notification.
190      *
191      * @param listener the listener to be registered
192      */

193     void addDocumentListener(IDocumentListener listener);
194
195     /**
196      * Removes the listener from the document's list of document listeners.
197      * If the listener is not registered with the document nothing happens.<p>
198      * An <code>IDocumentListener</code> may call back to this method
199      * when being inside a document notification.
200      *
201      * @param listener the listener to be removed
202      */

203     void removeDocumentListener(IDocumentListener listener);
204
205     /**
206      * Adds the given document listener as one which is notified before
207      * those document listeners added with <code>addDocumentListener</code>
208      * are notified. If the given listener is also registered using
209      * <code>addDocumentListener</code> it will be notified twice.
210      * If the listener is already registered nothing happens.<p>
211      *
212      * This method is not for public use.
213      *
214      * @param documentAdapter the listener to be added as pre-notified document listener
215      *
216      * @see #removePrenotifiedDocumentListener(IDocumentListener)
217      */

218     void addPrenotifiedDocumentListener(IDocumentListener documentAdapter);
219
220     /**
221      * Removes the given document listener from the document's list of
222      * pre-notified document listeners. If the listener is not registered
223      * with the document nothing happens. <p>
224      *
225      * This method is not for public use.
226      *
227      * @param documentAdapter the listener to be removed
228      *
229      * @see #addPrenotifiedDocumentListener(IDocumentListener)
230      */

231     void removePrenotifiedDocumentListener(IDocumentListener documentAdapter);
232
233
234
235     /* -------------------------- positions ----------------------------------- */
236
237     /**
238      * Adds a new position category to the document. If the position category
239      * already exists nothing happens.
240      *
241      * @param category the category to be added
242      */

243     void addPositionCategory(String JavaDoc category);
244
245     /**
246      * Deletes the position category from the document. All positions
247      * in this category are thus deleted as well.
248      *
249      * @param category the category to be removed
250      * @exception BadPositionCategoryException if category is undefined in this document
251      */

252     void removePositionCategory(String JavaDoc category) throws BadPositionCategoryException;
253
254     /**
255      * Returns all position categories of this document. This
256      * includes the default position category.
257      *
258      * @return the document's position categories
259      */

260     String JavaDoc[] getPositionCategories();
261
262     /**
263      * Checks the presence of the specified position category.
264      *
265      * @param category the category to check
266      * @return <code>true</code> if category is defined
267      */

268     boolean containsPositionCategory(String JavaDoc category);
269
270     /**
271      * Adds the position to the document's default position category.
272      * This is a convenience method for <code>addPosition(DEFAULT_CATEGORY, position)</code>.
273      *
274      * @param position the position to be added
275      * @exception BadLocationException if position describes an invalid range in this document
276      */

277     void addPosition(Position position) throws BadLocationException;
278
279     /**
280      * Removes the given position from the document's default position category.
281      * This is a convenience method for <code>removePosition(DEFAULT_CATEGORY, position)</code>.
282      *
283      * @param position the position to be removed
284      */

285     void removePosition(Position position);
286
287     /**
288      * Adds the position to the specified position category of the document.
289      * A position that has been added to a position category is updated on each
290      * change applied to the document. Positions may be added multiple times.
291      * The order of the category is maintained.
292      *
293      * @param category the category to which to add
294      * @param position the position to be added
295      * @exception BadLocationException if position describes an invalid range in this document
296      * @exception BadPositionCategoryException if the category is undefined in this document
297      */

298     void addPosition(String JavaDoc category, Position position) throws BadLocationException, BadPositionCategoryException;
299
300     /**
301      * Removes the given position from the specified position category.
302      * If the position is not part of the specified category nothing happens.
303      * If the position has been added multiple times, only the first occurrence is deleted.
304      *
305      * @param category the category from which to delete
306      * @param position the position to be deleted
307      * @exception BadPositionCategoryException if category is undefined in this document
308      */

309     void removePosition(String JavaDoc category, Position position) throws BadPositionCategoryException;
310
311     /**
312      * Returns all positions of the given position category.
313      * The positions are ordered according to the category's order.
314      * Manipulating this list does not affect the document, but manipulating the
315      * position does affect the document.
316      *
317      * @param category the category
318      * @return the list of all positions
319      * @exception BadPositionCategoryException if category is undefined in this document
320      */

321     Position[] getPositions(String JavaDoc category) throws BadPositionCategoryException;
322
323     /**
324      * Determines whether a position described by the parameters is managed by this document.
325      *
326      * @param category the category to check
327      * @param offset the offset of the position to find
328      * @param length the length of the position to find
329      * @return <code>true</code> if position is found
330      */

331     boolean containsPosition(String JavaDoc category, int offset, int length);
332
333     /**
334      * Computes the index at which a <code>Position</code> with the
335      * specified offset would be inserted into the given category. As the
336      * ordering inside a category only depends on the offset, the index must be
337      * chosen to be the first of all positions with the same offset.
338      *
339      * @param category the category in which would be added
340      * @param offset the position offset to be considered
341      * @return the index into the category
342      * @exception BadLocationException if offset is invalid in this document
343      * @exception BadPositionCategoryException if category is undefined in this document
344      */

345     int computeIndexInCategory(String JavaDoc category, int offset) throws BadLocationException, BadPositionCategoryException;
346
347     /**
348      * Appends a new position updater to the document's list of position updaters.
349      * Position updaters may be added multiple times.<p>
350      * An <code>IPositionUpdater</code> may call back to this method
351      * when being inside a document notification.
352      *
353      * @param updater the updater to be added
354      */

355     void addPositionUpdater(IPositionUpdater updater);
356
357     /**
358      * Removes the position updater from the document's list of position updaters.
359      * If the position updater has multiple occurrences only the first occurrence is
360      * removed. If the position updater is not registered with this document, nothing
361      * happens.<p>
362      * An <code>IPositionUpdater</code> may call back to this method
363      * when being inside a document notification.
364      *
365      * @param updater the updater to be removed
366      */

367     void removePositionUpdater(IPositionUpdater updater);
368
369     /**
370      * Inserts the position updater at the specified index in the document's
371      * list of position updaters. Positions updaters may be inserted multiple times.<p>
372      * An <code>IPositionUpdater</code> may call back to this method
373      * when being inside a document notification.
374      *
375      * @param updater the updater to be inserted
376      * @param index the index in the document's updater list
377      */

378     void insertPositionUpdater(IPositionUpdater updater, int index);
379
380     /**
381      * Returns the list of position updaters attached to the document.
382      *
383      * @return the list of position updaters
384      */

385     IPositionUpdater[] getPositionUpdaters();
386
387
388
389
390     /* -------------------------- partitions ---------------------------------- */
391
392     /**
393      * Returns the set of legal content types of document partitions.
394      * This set can be empty. The set can contain more content types than
395      * contained by the result of <code>getPartitioning(0, getLength())</code>.
396      * <p>
397      * Use {@link IDocumentExtension3#getLegalContentTypes(String)} when the document
398      * supports multiple partitionings. In that case this method is equivalent to:
399      * <pre>
400      * IDocumentExtension3 extension= (IDocumentExtension3) document;
401      * return extension.getLegalContentTypes(IDocumentExtension3.DEFAULT_PARTITIONING);
402      * </pre>
403      *
404      * @return the set of legal content types
405      */

406     String JavaDoc[] getLegalContentTypes();
407
408     /**
409      * Returns the type of the document partition containing the given offset.
410      * This is a convenience method for <code>getPartition(offset).getType()</code>.
411      * <p>
412      * Use {@link IDocumentExtension3#getContentType(String, int, boolean)} when
413      * the document supports multiple partitionings. In that case this method is
414      * equivalent to:
415      * <pre>
416      * IDocumentExtension3 extension= (IDocumentExtension3) document;
417      * return extension.getContentType(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);
418      * </pre>
419      *
420      * @param offset the document offset
421      * @return the partition type
422      * @exception BadLocationException if offset is invalid in this document
423      */

424     String JavaDoc getContentType(int offset) throws BadLocationException;
425
426     /**
427      * Returns the document partition in which the position is located.
428      * <p>
429      * Use {@link IDocumentExtension3#getPartition(String, int, boolean)} when
430      * the document supports multiple partitionings. In that case this method is
431      * equivalent:
432      * <pre>
433      * IDocumentExtension3 extension= (IDocumentExtension3) document;
434      * return extension.getPartition(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);
435      * </pre>
436      *
437      * @param offset the document offset
438      * @return a specification of the partition
439      * @exception BadLocationException if offset is invalid in this document
440      */

441     ITypedRegion getPartition(int offset) throws BadLocationException;
442
443     /**
444      * Computes the partitioning of the given document range using the
445      * document's partitioner.
446      * <p>
447      * Use {@link IDocumentExtension3#computePartitioning(String, int, int, boolean)} when
448      * the document supports multiple partitionings. In that case this method is
449      * equivalent:
450      * <pre>
451      * IDocumentExtension3 extension= (IDocumentExtension3) document;
452      * return extension.computePartitioning(IDocumentExtension3.DEFAULT_PARTITIONING, offset, length, false);
453      * </pre>
454      *
455      * @param offset the document offset at which the range starts
456      * @param length the length of the document range
457      * @return a specification of the range's partitioning
458      * @exception BadLocationException if the range is invalid in this document
459      */

460     ITypedRegion[] computePartitioning(int offset, int length) throws BadLocationException;
461
462     /**
463      * Registers the document partitioning listener with the document. After registration
464      * the document partitioning listener is informed about each partition change
465      * cause by a document manipulation or by changing the document's partitioner.
466      * If a document partitioning listener is also
467      * a document listener, the following notification sequence is guaranteed if a
468      * document manipulation changes the document partitioning:
469      * <ul>
470      * <li>listener.documentAboutToBeChanged(DocumentEvent);
471      * <li>listener.documentPartitioningChanged();
472      * <li>listener.documentChanged(DocumentEvent);
473      * </ul>
474      * If the listener is already registered nothing happens.<p>
475      * An <code>IDocumentPartitioningListener</code> may call back to this method
476      * when being inside a document notification.
477      *
478      * @param listener the listener to be added
479      */

480     void addDocumentPartitioningListener(IDocumentPartitioningListener listener);
481
482     /**
483      * Removes the listener from this document's list of document partitioning
484      * listeners. If the listener is not registered with the document nothing
485      * happens.<p>
486      * An <code>IDocumentPartitioningListener</code> may call back to this method
487      * when being inside a document notification.
488      *
489      * @param listener the listener to be removed
490      */

491     void removeDocumentPartitioningListener(IDocumentPartitioningListener listener);
492
493     /**
494      * Sets this document's partitioner. The caller of this method is responsible for
495      * disconnecting the document's old partitioner from the document and to
496      * connect the new partitioner to the document. Informs all document partitioning
497      * listeners about this change.
498      * <p>
499      * Use {@link IDocumentExtension3#setDocumentPartitioner(String, IDocumentPartitioner)} when
500      * the document supports multiple partitionings. In that case this method is equivalent to:
501      * <pre>
502      * IDocumentExtension3 extension= (IDocumentExtension3) document;
503      * extension.setDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING, partitioner);
504      * </pre>
505      *
506      * @param partitioner the document's new partitioner
507      *
508      * @see IDocumentPartitioningListener
509      */

510     void setDocumentPartitioner(IDocumentPartitioner partitioner);
511
512     /**
513      * Returns this document's partitioner.
514      * <p>
515      * Use {@link IDocumentExtension3#getDocumentPartitioner(String)} when
516      * the document supports multiple partitionings. In that case this method is
517      * equivalent to:
518      * <pre>
519      * IDocumentExtension3 extension= (IDocumentExtension3) document;
520      * return extension.getDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING);
521      * </pre>
522      *
523      * @return this document's partitioner
524      */

525     IDocumentPartitioner getDocumentPartitioner();
526
527
528
529     /* ---------------------- line information -------------------------------- */
530
531     /**
532      * Returns the length of the given line including the line's delimiter.
533      *
534      * @param line the line of interest
535      * @return the length of the line
536      * @exception BadLocationException if the line number is invalid in this document
537      */

538     int getLineLength(int line) throws BadLocationException;
539
540     /**
541      * Returns the number of the line at which the character of the specified position is located.
542      * The first line has the line number 0. A new line starts directly after a line
543      * delimiter. <code>(offset == document length)</code> is a valid argument although there is no
544      * corresponding character.
545      *
546      * @param offset the document offset
547      * @return the number of the line
548      * @exception BadLocationException if the offset is invalid in this document
549      */

550     int getLineOfOffset(int offset) throws BadLocationException;
551
552     /**
553      * Determines the offset of the first character of the given line.
554      *
555      * @param line the line of interest
556      * @return the document offset
557      * @exception BadLocationException if the line number is invalid in this document
558      */

559     int getLineOffset(int line) throws BadLocationException;
560
561     /**
562      * Returns a description of the specified line. The line is described by its
563      * offset and its length excluding the line's delimiter.
564      *
565      * @param line the line of interest
566      * @return a line description
567      * @exception BadLocationException if the line number is invalid in this document
568      */

569     IRegion getLineInformation(int line) throws BadLocationException;
570
571     /**
572      * Returns a description of the line at the given offset.
573      * The description contains the offset and the length of the line
574      * excluding the line's delimiter.
575      *
576      * @param offset the offset whose line should be described
577      * @return a region describing the line
578      * @exception BadLocationException if offset is invalid in this document
579      */

580     IRegion getLineInformationOfOffset(int offset) throws BadLocationException;
581
582     /**
583      * Returns the number of lines in this document
584      *
585      * @return the number of lines in this document
586      */

587     int getNumberOfLines();
588
589     /**
590      * Returns the number of lines which are occupied by a given text range.
591      *
592      * @param offset the offset of the specified text range
593      * @param length the length of the specified text range
594      * @return the number of lines occupied by the specified range
595      * @exception BadLocationException if specified range is invalid in this tracker
596      */

597     int getNumberOfLines(int offset, int length) throws BadLocationException;
598
599     /**
600      * Computes the number of lines in the given text. For a given
601      * implementer of this interface this method returns the same
602      * result as <code>set(text); getNumberOfLines()</code>.
603      *
604      * @param text the text whose number of lines should be computed
605      * @return the number of lines in the given text
606      */

607     int computeNumberOfLines(String JavaDoc text);
608
609
610     /* ------------------ line delimiter conversion --------------------------- */
611
612     /**
613      * Returns the document's legal line delimiters.
614      *
615      * @return the document's legal line delimiters
616      */

617     String JavaDoc[] getLegalLineDelimiters();
618
619     /**
620      * Returns the line delimiter of that line or <code>null</code> if the
621      * line is not closed with a line delimiter.
622      *
623      * @param line the line of interest
624      * @return the line's delimiter or <code>null</code> if line does not have a delimiter
625      * @exception BadLocationException if the line number is invalid in this document
626      */

627     String JavaDoc getLineDelimiter(int line) throws BadLocationException;
628
629
630     /* ---------------------------- search ------------------------------------ */
631
632     /**
633      * Returns the offset of a given search string in the document based on a set of search criteria.
634      *
635      * @param startOffset document offset at which search starts
636      * @param findString the string to find
637      * @param forwardSearch the search direction
638      * @param caseSensitive indicates whether lower and upper case should be distinguished
639      * @param wholeWord indicates whether the findString should be limited by white spaces as
640      * defined by Character.isWhiteSpace
641      * @return the offset of the first occurrence of findString based on the parameters or -1 if no match is found
642      * @exception BadLocationException if startOffset is an invalid document offset
643      * @deprecated as of 3.0 search is provided by {@link FindReplaceDocumentAdapter}
644      */

645     int search(int startOffset, String JavaDoc findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord) throws BadLocationException;
646 }
647
Popular Tags