KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > modules > editor > structure > spi > DocumentModelProvider


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.modules.editor.structure.spi;
21
22 import org.netbeans.modules.editor.structure.api.DocumentModel;
23 import org.netbeans.modules.editor.structure.api.DocumentModel.DocumentChange;
24 import org.netbeans.modules.editor.structure.api.DocumentModel.DocumentModelModificationTransaction;
25 import org.netbeans.modules.editor.structure.api.DocumentModel.DocumentModelTransactionCancelledException;
26 import org.netbeans.modules.editor.structure.api.DocumentModelException;
27
28 /**
29  * The DocumentModelProvider is responsible for parsing the text document
30  * and updating the tree structure of elements held by DocumentModel.
31  * The provider accomplished this by adding a 'requests' to add or remove
32  * an element into the transaction. For more detailed information see
33  * {@link org.netbeans.modules.editor.structure.api.DocumentModel.DocumentModelModificationTransaction}
34  * <br>
35  * When the model decides that there is a need to update the structure of the
36  * elements (after there is a document change(s)) it calls the provider's
37  * update method. The model passes an instance of DocumentModelModificationTransaction,
38  * the model itself and an array of changes made in the text document.
39  * Then it's up to the provider implementation what parts of the document will
40  * be reparsed and how the elements will be tailored. In principal the
41  * provider can add or remove elements from the model. This is accomplished by
42  * adding change requests into the transaction. Once the provider finishes its
43  * work the model commits the transaction and the model structure is definitively
44  * updated.
45  * <br>
46  * When the text document is changed during the call of the update method, the
47  * model cancels the transaction so next attempt to add something into the transaction
48  * will cause DocumentModelTransactionCancelledException to be thrown.
49  * The provider should not catch this exception - it is a legal mechanism, how
50  * to break no more valid model update.
51  *
52  * Instancies of this class are registered via layer mechanism into the
53  * IDE and associated with a particullar mime-types.
54  *
55  * The registration are read from the following folder in the system FS:
56  * <pre>
57  * Editors/&lt;mime-type&gt;/DocumentModel
58  * </pre>
59  *
60  * @author Marek Fukala
61  * @version 1.0
62  * @see org.netbeans.modules.editor.structure.api.DocumentModel
63  *
64  */
65 public interface DocumentModelProvider {
66     
67     /** Method called by the DocumentModel when the model content needs to be updated.
68      * For more info see the overall description of this class.
69      * @param trans the transaction the provider puts the change requests into
70      * @param model the DocumentModel instance
71      * @param changes the array of changes made in the document from the last model update
72      *
73      * @throws DocumentModelTransactionCancelledException when the transaction passed
74      * into the provider has been cancelled.
75      *
76      */
77     public void updateModel(DocumentModelModificationTransaction trans,
78             DocumentModel model, DocumentChange[] changes) throws DocumentModelException, DocumentModelTransactionCancelledException;
79     
80 }
81
Popular Tags