alvinalexander.com | career | drupal | java | mac | mysql | perl | scala | uml | unix  

What this is

This file is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.

Other links

The source code

/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2000 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.netbeans.spi.editor.fold;

import javax.swing.event.DocumentEvent;
import org.netbeans.api.editor.fold.Fold;
import org.netbeans.api.editor.fold.FoldType;

/**
 * Fold manager maintains folds in the hierarchy for which it is constructed.
 * 
* There can be multiple individually operating managers * over a single fold hierarchy each managing its own set of folds. *
* The only time when the fold managers can collide is when they * attempt to add overlapping folds into fold hierarchy. *
* In that case the fold from the manager with a higher priority * (will be explained later) will be added to the hierarchy * and the other one will remain outside of the hierarchy * until the colliding fold will get removed from the hierarchy. *
* The priority of the manager (and all its folds) * in the list of the managers for the particular hierarchy * is defined by the order of the fold manager's factories * in the layer * (see {@link FoldManagerFactory} for more information). * *

* The fold manager typically creates an initial set of folds * during the {@link #initFolds(FoldHierarchyTransaction)}. * Those folds typically mimic certain "primary data structure" * e.g. java folds mimic certain AST nodes created by a java parser. *
* Typically the fold manager attaches a listener * to a primary data structure and once it gets * notified about its change it should rebuild the folds accordingly. *
* That set can later be modified upon notifications * from primary data structure. * *

* Upon notification the folds can be updated synchronously * but that can potentially lead to deadlocks in case the view * hierarchy (which shares the same lock with fold hierarchy) would * access the primary data structure at the same time. *
* A safer approach is to remember the changes during notification * from the primary data structure * and schedule the updates to the fold hierarchy to be done * independently. *
* Ideally the physical creation of folds should be done in EDT * (Event Dispatch Thread) because there would be no risk * of the document switching in the text component * by {@link javax.swing.text.JTextComponent#setDocument(javax.swing.text.Document)}. * * @author Miloslav Metelka * @version 1.00 */ public interface FoldManager { /** * Initialize this manager. * * @param operation fold hierarchy operation dedicated to the fold manager. */ void init(FoldOperation operation); /** * Initialize the folds provided by this manager. *
* The fold manager should create initial set of folds here * if it does not require too much resource consumption. *
* As this method is by default called at the file opening time * then it may be better to schedule the initial fold computations * for later time and do nothing here. * *

* Any listeners necessary for the maintenance of the folds * can be attached here. *
* Generally there should be just weak listeners used * to not prevent the GC of the text component. * * @param transaction transaction in terms of which the intial * fold changes can be performed. */ void initFolds(FoldHierarchyTransaction transaction); /** * Called by hierarchy upon the insertion to the underlying document. *
* If there would be any fold modifications required they may be added * to the given transaction. * * @param evt document event describing the document modification. * @param transaction open transaction to which the manager can add * the fold changes. */ void insertUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction); /** * Called by hierarchy upon the removal in the underlying document. *
* If there would be any fold modifications required they may be added * to the given transaction. * * @param evt document event describing the document modification. * @param transaction open transaction to which the manager can add * the fold changes. */ void removeUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction); /** * Called by hierarchy upon the change in the underlying document. *
* If there would be any fold modifications required they may be added * to the given transaction. * * @param evt document event describing the document change. * @param transaction open transaction to which the manager can add * the fold changes. */ void changedUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction); /** * Notify that the fold was removed from hierarchy automatically * by fold hierarchy infrastructure processing * because it became empty (by a document modification). */ void removeEmptyNotify(Fold epmtyFold); /** * Notify that the fold was removed from hierarchy automatically * by fold hierarchy infrastructure processing * because it was damaged by a document modification. */ void removeDamagedNotify(Fold damagedFold); /** * Notify that the fold was expanded automatically * by fold hierarchy infrastructure processing * because its isExpandNecessary() * return true. */ void expandNotify(Fold expandedFold); /** * Notification that this manager will no longer be used by the hierarchy. *
* The folds that it maintains are still valid but after this method * finishes they will be removed from the hierarchy. * *

* This method is not guaranteed to be called. Therefore the manager * must only listen weekly on the related information providers * so that it does not block the hierarchy from being garbage collected. */ void release(); }

... this post is sponsored by my books ...

#1 New Release!

FP Best Seller

 

new blog posts

 

Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.