GrammarQuery


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.xml.api.model;
21  
22  import java.util.Enumeration  ;
23  
24  import org.w3c.dom.Node  ;
25  import org.w3c.dom.NodeList  ;
26  
27  /**
28   * A query interface returning possible fenomens as given by document grammar.
29   * <p>
30   * It provides at specified <code>HintContext</code> following information:
31   * <ul>
32   *  <li>allowed element names and namespaces
33   *  <li>allowed entity names
34   *  <li>allowed notation names
35   *  <li>allowed attribute names
36   *  <li>allowed values of attribute values or element content
37   * </ul>
38   * This information are returned as <code>Enumeration</code>. Every member of
39   * the enumeration represents one possible option. Empty enumeration signals
40   * that no hint can be derived from grammar in given context.
41   * <p>
42   * Every option represents DOM <code>Node</code> that can have children. These children
43   * represents mandatory content for given option. Providing them is optional.
44   * On the other hand <code>EMPTY</code> elements may not provide any children.
45   *
46   * <h3>Context Representation</h3>
47   * Query context is represented by a read-only DOM1 model Core and XML modules
48   * (it may be replaced with DOM2).
49   * 
50   * <h3>Implementation Note:</h3>
51   * <p>
52   * DOM1 does describe only non-DTD part of document. 
53   * <p>
54   * Passed context may represent errorous XML document. The code must
55   * take into account that it can get <code>null</code>s even on places
56   * where it does not expect it. E.g. <code>getParentNode()</code> as
57   * the DOM document can be constructed as a <b>best effort</b> one.
58   * <p>
59   * Also as the context may originate from a text editor it is better to 
60   * rely on <code>getPreviousSibling</code> rather then <code>getNextSibling</code>
61   * as user usaully types text from document begining.
62   *
63   * @author  Petr Kuzel
64   */   
65  public interface GrammarQuery {
66      
67      /**
68       * @semantics Navigates through read-only Node tree to determine context and provide right results.
69       * @postconditions Let ctx unchanged
70       * @time Performs fast up to 300 ms.
71       * @stereotype query
72       * @param virtualElementCtx represents virtual element Node that has to be replaced, its own attributes does not name sense, it can be used just as the navigation start point.
73       * @return enumeration of <code>GrammarResult</code>s (ELEMENT_NODEs) that can be queried on name, and attributes.
74       *         Every list member represents one possibility.  
75       */
76      Enumeration   queryElements(HintContext virtualElementCtx);
77  
78      /**
79       * Query attribute options for given context. All implementations must handle
80       * queries based on owner element context.
81       * @stereotype query
82       * @output list of results that can be queried on name, and attributes
83       * @time Performs fast up to 300 ms. 
84       * @param ownerElementCtx represents owner <code>Element</code> that will host result.
85       * @return enumeration of <code>GrammarResult</code>s (ATTRIBUTE_NODEs) that can be queried on name, and attributes.
86       *         Every list member represents one possibility.  
87       */
88      Enumeration   queryAttributes(HintContext ownerElementCtx);
89  
90      /**
91       * Return options for value at given context.
92       * It could be also used for completing of value parts such as Ant or XSLT property names (how to trigger it?).
93       * @semantics Navigates through read-only Node tree to determine context and provide right results.
94       * @postconditions Let ctx unchanged
95       * @time Performs fast up to 300 ms.
96       * @stereotype query
97       * @param virtualTextCtx represents virtual Node that has to be replaced (parent can be either Attr or Element), its own attributes does not name sense, it can be used just as the navigation start point.
98       * @return enumeration of <code>GrammarResult</code>s (TEXT_NODEs) that can be queried on name, and attributes.
99       *         Every list member represents one possibility.  
100      */
101     Enumeration   queryValues(HintContext virtualTextCtx);
102 
103     /**
104      * query default value for given context. Two context types must be handled:
105      * an attribute and an element context.
106      * @param parentNodeCtx context for which default is queried
107      * @return default value or <code>null</code>
108      */
109     GrammarResult queryDefault(HintContext parentNodeCtx);
110 
111     /**
112      * Allow to get names of <b>parsed general entities</b>.
113      * @param prefix prefix filter
114      * @return enumeration of <code>GrammarResult</code>s (ENTITY_REFERENCE_NODEs)
115      */
116     Enumeration   queryEntities(String   prefix);
117 
118     /**
119      * Allow to get names of <b>declared notations</b>.
120      * @param prefix prefix filter
121      * @return enumeration of <code>GrammarResult</code>s (NOTATION_NODEs)
122      */    
123     Enumeration   queryNotations(String   prefix);
124 
125     /**
126      * Distinquieshes between empty enumaration types.
127      * @return <code>true</code> there is no known result 
128      *         <code>false</code> grammar does not allow here a result
129      */
130     boolean isAllowed(Enumeration   en);
131     
132     
133     
134     // Candidates for separate interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135     
136     /**
137      * Allows Grammars to supply customizer for the HintContext
138      * @param ctx the hint context node
139      * @return a Component which can be used to customize the context node
140      */
141     java.awt.Component   getCustomizer(HintContext nodeCtx);
142     
143     /**
144      * Allows Grammars to supply customizer from the HintContext
145      * @param ctx the hint context node
146      * @return true if a customizer is available for this context
147      */
148     boolean hasCustomizer(HintContext nodeCtx);
149 
150     /**
151      * Allows Grammars to supply properties for the HintContext
152      * @param ctx the hint context node
153      * @return an array of properties for this context
154      */
155     org.openide.nodes.Node.Property[] getProperties(HintContext nodeCtx);
156 }
157
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags