FoldManager


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.spi.editor.fold;
21  
22  import javax.swing.event.DocumentEvent  ;
23  import org.netbeans.api.editor.fold.Fold;
24  import org.netbeans.api.editor.fold.FoldType;
25  
26  /**
27   * Fold manager maintains folds in the hierarchy for which it is constructed.
28   * <br>
29   * There can be multiple individually operating managers
30   * over a single fold hierarchy each managing its own set of folds.
31   * <br>
32   * The only time when the fold managers can collide is when they
33   * attempt to add overlapping folds into fold hierarchy.
34   * <br>
35   * In that case the fold from the manager with a higher priority
36   * (will be explained later) will be added to the hierarchy
37   * and the other one will remain outside of the hierarchy
38   * until the colliding fold will get removed from the hierarchy.
39   * <br>
40   * The priority of the manager (and all its folds)
41   * in the list of the managers for the particular hierarchy
42   * is defined by the order of the fold manager's factories
43   * in the layer
44   * (see {@link FoldManagerFactory} for more information).
45   *
46   * <p>
47   * The fold manager typically creates an initial set of folds
48   * during the {@link #initFolds(FoldHierarchyTransaction)}.
49   * Those folds typically mimic certain "primary data structure"
50   * e.g. java folds mimic certain AST nodes created by a java parser.
51   * <br>
52   * Typically the fold manager attaches a listener
53   * to a primary data structure and once it gets
54   * notified about its change it should rebuild the folds accordingly.
55   * <br>
56   * That set can later be modified upon notifications
57   * from primary data structure.
58   *
59   * <p>
60   * Upon notification the folds can be updated synchronously
61   * but that can potentially lead to deadlocks in case the view
62   * hierarchy (which shares the same lock with fold hierarchy) would 
63   * access the primary data structure at the same time.
64   * <br>
65   * A safer approach is to remember the changes during notification
66   * from the primary data structure
67   * and schedule the updates to the fold hierarchy to be done
68   * independently.
69   * <br>
70   * Ideally the physical creation of folds should be done in EDT
71   * (Event Dispatch Thread) because there would be no risk
72   * of the document switching in the text component
73   * by {@link javax.swing.text.JTextComponent#setDocument(javax.swing.text.Document)}.
74   *
75   * @author Miloslav Metelka
76   * @version 1.00
77   */
78  
79  public interface FoldManager {
80      
81      /**
82       * Initialize this manager.
83       *
84       * @param operation fold hierarchy operation dedicated to the fold manager.
85       */
86      void init(FoldOperation operation);
87      
88      /**
89       * Initialize the folds provided by this manager.
90       * <br>
91       * The fold manager should create initial set of folds here
92       * if it does not require too much resource consumption.
93       * <br>
94       * As this method is by default called at the file opening time
95       * then it may be better to schedule the initial fold computations
96       * for later time and do nothing here. 
97       *
98       * <p>
99       * Any listeners necessary for the maintenance of the folds
100      * can be attached here.
101      * <br>
102      * Generally there should be just weak listeners used
103      * to not prevent the GC of the text component.
104      *
105      * @param transaction transaction in terms of which the intial
106      *  fold changes can be performed.
107      */
108     void initFolds(FoldHierarchyTransaction transaction);
109     
110     /**
111      * Called by hierarchy upon the insertion to the underlying document.
112      * <br>
113      * If there would be any fold modifications required they may be added
114      * to the given transaction.
115      *
116      * @param evt document event describing the document modification.
117      * @param transaction open transaction to which the manager can add
118      *  the fold changes.
119      */
120     void insertUpdate(DocumentEvent   evt, FoldHierarchyTransaction transaction);
121     
122     /**
123      * Called by hierarchy upon the removal in the underlying document.
124      * <br>
125      * If there would be any fold modifications required they may be added
126      * to the given transaction.
127      *
128      * @param evt document event describing the document modification.
129      * @param transaction open transaction to which the manager can add
130      *  the fold changes.
131      */
132     void removeUpdate(DocumentEvent   evt, FoldHierarchyTransaction transaction);
133     
134     /**
135      * Called by hierarchy upon the change in the underlying document.
136      * <br>
137      * If there would be any fold modifications required they may be added
138      * to the given transaction.
139      *
140      * @param evt document event describing the document change.
141      * @param transaction open transaction to which the manager can add
142      *  the fold changes.
143      */
144     void changedUpdate(DocumentEvent   evt, FoldHierarchyTransaction transaction);
145     
146     /**
147      * Notify that the fold was removed from hierarchy automatically
148      * by fold hierarchy infrastructure processing
149      * because it became empty (by a document modification).
150      */
151     void removeEmptyNotify(Fold epmtyFold);
152     
153     /**
154      * Notify that the fold was removed from hierarchy automatically
155      * by fold hierarchy infrastructure processing
156      * because it was damaged by a document modification.
157      */
158     void removeDamagedNotify(Fold damagedFold);
159     
160     /**
161      * Notify that the fold was expanded automatically
162      * by fold hierarchy infrastructure processing
163      * because its <code>isExpandNecessary()</code>
164      * return true.
165      */
166     void expandNotify(Fold expandedFold);
167 
168     /**
169      * Notification that this manager will no longer be used by the hierarchy.
170      * <br>
171      * The folds that it maintains are still valid but after this method
172      * finishes they will be removed from the hierarchy.
173      *
174      * <p>
175      * This method is not guaranteed to be called. Therefore the manager
176      * must only listen weekly on the related information providers
177      * so that it does not block the hierarchy from being garbage collected.
178      */
179     void release();
180 
181 }
182
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags