JspParserAPI


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.web.jsps.parserapi;
21  
22  import java.beans.PropertyChangeListener  ;
23  import java.io.File  ;
24  import java.io.IOException  ;
25  import java.net.URLClassLoader  ;
26  import java.util.Map  ;
27  
28  import org.openide.filesystems.FileObject;
29  import org.openide.filesystems.FileSystem;
30  
31  import org.netbeans.modules.web.jspparser.ContextUtil;
32  
33  /**
34   *
35   * @author  pj97932
36   * @version
37   */
38  public interface JspParserAPI {
39  
40      public static abstract class WebModule {
41  
42          /**
43           * Property name that denotes the libraries of the web module. A PropertyChangeEvent with this property is fired if
44           * the list of libraries changes, or if the timestamp of any of these libraries changes.
45           * @deprecated use classpath API to obtain classpath for document base folder
46           */
47          public static final String   PROP_LIBRARIES = "libraries"; // NOI18N
48          
49          /**
50           * Property name that denotes the package root directories of the web module. A PropertyChangeEvent with this property is fired if
51           * the list of package roots changes, or if the timestamp of any of the files contained in these package roots changes.
52           * @deprecated use classpath API to obtain classpath for document base folder
53           */
54          public static final String   PROP_PACKAGE_ROOTS = "package_roots"; // NOI18N
55          
56          /** Returns the document base directory of the web module.
57           * May return null if we are parsing a tag file that is outside a web module
58           * (that will be packaged into a tag library).
59           */
60          public abstract FileObject getDocumentBase();
61          
62          
63          /** This method returns the entries, which are needed for parsing jsp files, but are
64           *  not directly included in the project (as library). For example there are taglibraries
65           *  which are offered by the target server(J2EE Platform), so the project has these entries
66           *  on the classpath, but they are not defined by the project. It can return null.   
67           */
68          public abstract File  [] getExtraClasspathEntries();
69          
70          /** Returns InputStream for the file open in editor or null
71           * if the file is not open.
72           */
73          public abstract java.io.InputStream   getEditorInputStream (FileObject fo);
74          
75          public abstract void addPropertyChangeListener(PropertyChangeListener   l);
76          
77          public abstract void removePropertyChangeListener(PropertyChangeListener   l);
78      }
79      
80      /** Mode in which some errors (such as error parsing a tag library) are ignored. */
81      public static final int ERROR_IGNORE = 1;
82      /** Mode in which some errors (such as error parsing a tag library) are reported, 
83       * but no accurate error description is needed. */
84      public static final int ERROR_REPORT_ANY = 2;
85      /** Mode in which an accurate description of all errors is required, so an actual attempt to parse all
86       * tag libraries is done, so the parser throws a root cause exception. */
87      public static final int ERROR_REPORT_ACCURATE = 3;
88      
89      public static final String   TAG_MIME_TYPE = "text/x-tag"; // NOI18N
90      
91      /** Returns the information necessary for opening a JSP page in the editor.
92       * 
93       * @param jspFile the page to analyze
94       * @param wm web module in whose context to compile
95       * @param useEditor whether to use data from the existing open JSP document, or from the file on the disk
96       * @return open information, using either the editor, or the file on the disk
97       */    
98      public JspOpenInfo getJspOpenInfo(FileObject jspFile, WebModule wm, boolean useEditor);
99      
100     /** Analyzes JSP and returns the parsed data about the page.
101      * 
102      * @param wmRoot root of the web module which gives context to this page,
103      *   may be null if the page is not within a web module
104      * @param jspFile the page to analyze
105      * @param proj project in whose context to compile
106      * @param errorReportingMode mode for reporting errors, see above
107      * @return Parsing results.
108      */    
109     public JspParserAPI.ParseResult analyzePage(FileObject jspFile, WebModule wm,
110         int errorReportingMode);
111     
112     
113     /** Returns the classloader which loads classes from the given web module 
114      * (within a project context).
115      */
116     public URLClassLoader   getModuleClassLoader(WebModule wm);
117     
118     /** Creates a description of a tag library. */
119     //public TagLibParseSupport.TagLibData createTagLibData(JspInfo.TagLibraryData info, FileSystem fs);
120     
121     /**
122      * Returns the mapping of the 'global' tag library URI to the location (resource
123      * path) of the TLD associated with that tag library. 
124      * @param wmRoot the web module for which to return the map
125      * @return Map which maps global tag library URI to the location 
126      * (resource path) of its tld. The location is
127      * returned as a String array:
128      *    [0] The location
129      *    [1] If the location is a jar file, this is the location of the tld.
130      */
131     public Map   getTaglibMap(WebModule wm) throws IOException  ;
132     
133     /** This class represents a result of parsing. It indicates either success
134      * or failure. In case of success, provides information about the parsed page,
135      * in case of failure, provides information about parsing errors.
136      */
137     public static class ParseResult {
138         
139         protected PageInfo   pageInfo;
140         protected Node.Nodes nodes;
141         protected JspParserAPI.ErrorDescriptor[] errors;
142         protected boolean parsedOK;
143        
144         /** Creates a new ParseResult in case of parse success.
145          * @param pageInfo information about the parsed page (from Jasper)
146          * @param node exact structure of the  (from Jasper)
147          */
148         public ParseResult(PageInfo pageInfo, Node.Nodes nodes) {
149             this (pageInfo, nodes, null);
150         }
151         
152         /** Creates a new ParseResult in case of parse failure.
153          * @param errors information about parse errors
154          */
155         public ParseResult(JspParserAPI.ErrorDescriptor[] errors) {
156             this (null, null, errors);
157         }
158         
159         /** Creates a new ParseResult. If the errors array is null or empty,
160          *  the parse is considered successful.
161          * @param pageInfo information about the parsed page (from Jasper), may be null
162          * @param node exact structure of the  (from Jasper), may be null
163          * @param errors information about parse errors, or null, if parsing was successful
164          */
165         public ParseResult(PageInfo pageInfo, Node.Nodes nodes, JspParserAPI.ErrorDescriptor[] errors) {
166             this.pageInfo = pageInfo;
167             this.nodes = nodes;
168             this.errors = errors;
169             this.parsedOK = ((errors == null) || (errors.length == 0));
170         }
171         
172         /** Indicates success or failure of parsing.
173          */
174         public boolean isParsingSuccess() {
175             return parsedOK;
176         }
177         
178         /** Returns all global information about the parsed page.
179          *  @exception IllegalStateException if parsing failed
180          */
181         public PageInfo getPageInfo() {
182             return pageInfo;
183         }
184         
185         /** Returns the hierarchical structure of the page.
186          *  @exception IllegalStateException if parsing failed
187          */
188         public Node.Nodes getNodes() {
189             return nodes;
190         }
191         
192         /** Returns information about the parse errors if parsing failed.
193          *  @exception IllegalStateException if parsing succeeded
194          */
195         public JspParserAPI.ErrorDescriptor[] getErrors() {
196             if (!(parsedOK)) {
197                 return errors;
198             }
199             throw new IllegalStateException  ();
200         }
201         
202         public String   toString() {
203             StringBuffer   result = new StringBuffer  ();
204             result.append("--------- JspParserAPI.parseResult(), success: ");
205             result.append(isParsingSuccess());
206             result.append("\n");
207             if (pageInfo != null) {
208                 result.append(" ---- PAGEINFO\n");
209                 result.append(pageInfo.toString());
210             }
211             if (nodes != null) {
212                 result.append("\n ---- NODES\n");
213                 result.append(nodes.toString());
214                 result.append("\n");
215             }
216             if (!isParsingSuccess()) {
217                 result.append("\n ---- ERRORS\n");
218                 for (int i = 0; i < errors.length; i++) {
219                     result.append(errors[i].toString());
220                 }
221             }
222             return result.toString();
223         }
224         
225     }
226     
227     /** Contains data important for opening the page
228      * in the editor, e.g. whether the page is in classic
229      * or XML syntax, or what is the file encoding.
230      */
231     public static class JspOpenInfo {
232         
233         private boolean isXml;
234         private String   encoding;
235         
236         public JspOpenInfo(boolean isXml, String   encoding) {
237             this.isXml = isXml;
238             this.encoding = encoding;
239         }
240         
241         public boolean isXmlSyntax() {
242             return isXml;
243         }
244         
245         public String   getEncoding() {
246             return encoding;
247         }
248         
249         public boolean equals(Object   o) {
250             if (o instanceof JspOpenInfo) {
251                 JspOpenInfo openInfo2 = (JspOpenInfo)o;
252                 return (getEncoding().equals(openInfo2.getEncoding()) &&
253                         isXmlSyntax() == openInfo2.isXmlSyntax());
254             }
255             else {
256                 return false;
257             }
258         }
259         
260         public int hashCode() {
261             return encoding.hashCode() + (isXml ? 1 : 0);
262         }
263         
264         public String   toString() {
265             return super.toString() + " [isXml: " + isXml + ", encoding: " + encoding + "]";
266         }
267         
268     }
269 
270     /** Represents a description of a parse error.
271      */
272     public static class ErrorDescriptor {
273 
274         protected FileObject wmRoot;
275         protected FileObject source;
276         protected int line;
277         protected int column;
278         protected String   errorMessage;
279         protected String   referenceText;
280 
281         /** Creates a new ErrorDescriptor. 
282          * @param wmRoot the web module in which the error occurs. May be null in some (unusual) cases.
283          * @param source the file in which the error occurred. This may be different from the page that was 
284          *  originally compiled/parsed, if this is a page segment.
285          * @param line line number on which the error occurred
286          * @param column column number on which the error occurred
287          * @param errorMessage message containing the description of the error
288          * @param rererenceText a piece of code (line) that contains the error. May be empty.
289          */
290         public ErrorDescriptor(FileObject wmRoot, FileObject source, int line, 
291         int column, String   errorMessage, String   referenceText) {
292             this.wmRoot = wmRoot;
293             this.source = source;
294             this.line = line;
295             this.column = column;
296             this.errorMessage = errorMessage;
297             this.referenceText = referenceText;
298         }
299 
300         /** Returns a file containing the error. */
301         public FileObject getSource() {
302             return source;
303         }
304 
305         /** Get the line of the error. */
306         public int getLine() {
307             return line;
308         }
309 
310         /** Get the column of the error. */
311         public int getColumn() {
312             return column;
313         }
314 
315         /** Get the error message associated with the error. */
316         public String   getErrorMessage() {
317             return errorMessage;
318         }
319 
320         /** Get the string which contains the error (i.e. contents of the line containing the error. */
321         public String   getReferenceText() {
322             return referenceText;
323         }
324         
325         public String   toString() {
326             StringBuffer   result = new StringBuffer  ();
327             result.append("ERROR in ")
328                   .append(getSourcePath())
329                   .append(" at [")
330                   .append(getLine())
331                   .append(", ")
332                   .append(getColumn())
333                   .append("] ")
334                   .append(getErrorMessage())
335                   .append("\n")
336                   .append(getReferenceText())
337                   .append("\n");
338             return result.toString();
339         }
340         
341         private String   getSourcePath() {
342             if (wmRoot == null) {
343                 return getSource().getNameExt();
344             }
345             else {
346                 return ContextUtil.findRelativeContextPath(wmRoot, getSource());
347             }
348         }
349     }
350     
351     
352 }
353
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags