JavaParser


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.java.parser;
21  
22  import java.beans.PropertyChangeListener  ;
23  import java.io.Reader  ;
24  import java.io.InputStream  ;
25  import java.io.IOException  ;
26  import javax.swing.event.ChangeListener  ;
27  
28  import org.openide.cookies.SourceCookie;
29  import org.openide.nodes.Node;
30  import org.openide.src.*;
31  import org.openide.util.Task;
32  
33  import org.netbeans.modules.java.bridge.LangModel;
34  
35  /**
36   *
37   * @author  sdedic
38   * @version
39   */
40  public interface JavaParser extends SourceCookie {
41      /**
42       * This priority level is recommended for background operations, that the user
43       * does not need to wait for.
44       */
45      public static final int    PRIORITY_BACKGROUND = Thread.MIN_PRIORITY;
46      /**
47       * Normal priority is recommended for parse operations that needs to be completed soon,
48       * but should not block the IDE. This priority is internally used in prepare() call.
49       */
50      public static final int    PRIORITY_NORMAL = Thread.MIN_PRIORITY + 1;
51      /**
52       * Recommended priority for carrying out blocking calls. This priority is used
53       * by blocking calls on SourceElement.
54       */
55      public static final int    PRIORITY_DEMAND = Thread.MAX_PRIORITY - 1;
56      /**
57       * Recommended priority for hierarchy refresh operations. This priority is used
58       * in Java module in refresh operation after the user stops editing for a period of
59       * time.
60       */
61      public static final int    PRIORITY_REFRESH = PRIORITY_NORMAL;
62  
63      /**
64       * Shallow parser request. 
65       */
66      public static final String   SHALLOW_PARSER = "shallow"; // NOI18N
67      /**
68       * Deep parser request.
69       */
70      public static final String   DEEP_PARSER = "deep"; // NOI18N
71      /**
72       * MDR parser request.
73       */
74      public static final String   MDR_PARSER = "mdr"; // NOI18N
75      /**
76       * Adds a Listener on the parser.
77       */
78      public void addPropertyChangeListener(PropertyChangeListener   l);
79      
80      /**
81       * Removes the listener from the parser.
82       */
83      public void removePropertyChangeListener(PropertyChangeListener   l);
84      
85      /**
86       * Listens on parser state changes (more events than just PropertyChanges!)
87       */
88      public void addChangeListener(ChangeListener   l);
89      
90      /**
91       * Removes the change listener from the parser.
92       */
93      public void removeChangeListener(ChangeListener   l);
94      
95      /**
96       * Returns the Element representing the source.
97       */
98      public SourceElement    getSource();
99      
100     /**
101      * Prepares the source hierarchy; after the task is finished, there are some
102      * parsed data. If the model already exists, the task returned is already finished.
103      * The returned task, after it completes, also guarantees that the model will not
104      * be garbage collected.
105      */
106     public Task             prepare();
107     
108     /**
109      * Schedules a parse task with various parameters.
110      * @param force schedules a parse even if the underlying document contains no
111      * uparsed changes. The method returns a task that you can wait for, or attach
112      * TaskListeners to. See {@link #prepare} for more information.
113      * @param acceptErrors force model update even if the parsed data indicate syntax
114      * errors.
115      * @param priority priority of the task.
116      * @return task for synchronization purposes. The task is marked finished after the
117      * model is created or refreshed.
118      */
119     public Task             parse(int priority, boolean force, boolean acceptErrors);
120 
121     /**
122      * Schedules a parse task with various parameters.
123      * @param force schedules a parse even if the underlying document contains no
124      * uparsed changes. The method returns a task that you can wait for, or attach
125      * TaskListeners to. See {@link #prepare} for more information.
126      * @param acceptErrors force model update even if the parsed data indicate syntax
127      * errors.
128      * @param priority priority of the task.
129      * @return task for synchronization purposes. The task is marked finished after the
130      * model is created or refreshed.
131      */
132     public Task             parse(int priority, boolean force, boolean acceptErrors, ParsableObjectRequest request);
133     
134     /**
135      * Returns current running parser task, if there is no task running returns FinishedTask
136      * @return task for synchronization purposes.
137      */
138     public Task getCurrentTask();
139     
140     /**
141      * Returns the overall current parser's status. The returned value is one of
142      * the manifested constants SourceElement.STATUS_*.
143      * @return status information
144      */
145     public int              getStatus();
146     
147     /**
148      * Retrieves the exception that describes the last failure to parse the
149      * input. This will be mostly SourceException.IO.
150      */
151     public SourceException  getErrorCause();
152     
153     /**
154      * Returns the <B>real</B> implementation of the source provided by the data model.
155      */
156     public SourceElement.Impl   getSourceImpl();
157     
158     /**
159      * Returns the model the parser operatges on.
160      */
161     public LangModel            getModel();
162 
163     /**
164      * Interface that the support uses to talk to the outside world.
165      */
166     public interface Env {
167         /**
168          * Returns the FileObject corresponding to the source, if there's one.
169          * The method may return null if there is no FileObject == the source
170          * is only in memory.
171          * @return FileObject or <code>null</code>
172          */
173         public org.openide.filesystems.FileObject   getSourceFile();
174 
175         /**
176          * Returns the name of the source, if one was assigned. If {@link #getSourceFile}
177          * returns non-null, then this method must return getSourceFile().getNameExt().
178          * The returned value may used for error reporting when the passed source is
179          * not file-based.
180          *
181          * @return name of the source or <code>null</code>
182          */
183         public String         getSourceName();
184 
185         /** Retrieves the source text for parsing. Can throw IOException, if the
186          * source cannot be retrieved.
187          */
188         public Reader     getSourceText() throws IOException  ;
189 
190         /**
191          * Environment can find precompiled classes to speed up name resoltion
192          */
193         public InputStream    findCompiledClass(String   classFQN);
194         
195         /**
196          * Finds appropriate cookie for the element.
197          */
198         public Node.Cookie  findCookie(SourceElement el, Class   cls);
199         
200         /**
201          * Annotate the throwable with a localized message. The flag controls whether
202          * the error is a user-level one, or it is an internal failure.
203          */
204         public void annotateThrowable(Throwable   t, String   locMessage, boolean user);
205         
206         /**
207          * Annotates wrapping throwable with the nested one - whatever that means to the
208          * environment.
209          */
210         public void annotateThrowable(Throwable   wrapper, Throwable   nested);
211     }
212 }
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags