← Back to branch summary

~ubuntu-branches/ubuntu/quantal/netbeans/quantal

« back to all changes in this revision

Viewing changes to xml/core/src/org/netbeans/modules/xml/api/model/GrammarQuery.java

  • Committer: Bazaar Package Importer
  • Author(s): Marek Slama
  • Date: 2008-01-29 14:11:22 UTC
  • Revision ID: james.westby@ubuntu.com-20080129141122-fnzjbo11ntghxfu7
Tags: upstream-6.0.1
Import upstream version 6.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
xml/core/src/org/netbeans/modules/xml/api/model/GrammarQuery.java
 
1
/*
 
2
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 
3
 *
 
4
 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 
5
 *
 
6
 * The contents of this file are subject to the terms of either the GNU
 
7
 * General Public License Version 2 only ("GPL") or the Common
 
8
 * Development and Distribution License("CDDL") (collectively, the
 
9
 * "License"). You may not use this file except in compliance with the
 
10
 * License. You can obtain a copy of the License at
 
11
 * http://www.netbeans.org/cddl-gplv2.html
 
12
 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
 
13
 * specific language governing permissions and limitations under the
 
14
 * License.  When distributing the software, include this License Header
 
15
 * Notice in each file and include the License file at
 
16
 * nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this
 
17
 * particular file as subject to the "Classpath" exception as provided
 
18
 * by Sun in the GPL Version 2 section of the License file that
 
19
 * accompanied this code. If applicable, add the following below the
 
20
 * License Header, with the fields enclosed by brackets [] replaced by
 
21
 * your own identifying information:
 
22
 * "Portions Copyrighted [year] [name of copyright owner]"
 
23
 *
 
24
 * Contributor(s):
 
25
 *
 
26
 * The Original Software is NetBeans. The Initial Developer of the Original
 
27
 * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
 
28
 * Microsystems, Inc. All Rights Reserved.
 
29
 *
 
30
 * If you wish your version of this file to be governed by only the CDDL
 
31
 * or only the GPL Version 2, indicate your decision by adding
 
32
 * "[Contributor] elects to include this software in this distribution
 
33
 * under the [CDDL or GPL Version 2] license." If you do not indicate a
 
34
 * single choice of license, a recipient has the option to distribute
 
35
 * your version of this file under either the CDDL, the GPL Version 2 or
 
36
 * to extend the choice of license to its licensees as provided above.
 
37
 * However, if you add GPL Version 2 code and therefore, elected the GPL
 
38
 * Version 2 license, then the option applies only if the new code is
 
39
 * made subject to such option by the copyright holder.
 
40
 */
 
41
 
 
42
package org.netbeans.modules.xml.api.model;
 
43
 
 
44
import java.util.Enumeration;
 
45
 
 
46
/**
 
47
 * A query interface returning possible fenomens as given by document grammar.
 
48
 * <p>
 
49
 * It provides at specified <code>HintContext</code> following information:
 
50
 * <ul>
 
51
 *  <li>allowed element names and namespaces
 
52
 *  <li>allowed entity names
 
53
 *  <li>allowed notation names
 
54
 *  <li>allowed attribute names
 
55
 *  <li>allowed values of attribute values or element content
 
56
 * </ul>
 
57
 * This information are returned as <code>Enumeration</code>. Every member of
 
58
 * the enumeration represents one possible option. Empty enumeration signals
 
59
 * that no hint can be derived from grammar in given context.
 
60
 * <p>
 
61
 * Every option represents DOM <code>Node</code> that can have children. These children
 
62
 * represents mandatory content for given option. Providing them is optional.
 
63
 * On the other hand <code>EMPTY</code> elements may not provide any children.
 
64
 *
 
65
 * <h3>Context Representation</h3>
 
66
 * Query context is represented by a read-only DOM1 model Core and XML modules
 
67
 * (it may be replaced with DOM2).
 
68
 * 
 
69
 * <h3>Implementation Note:</h3>
 
70
 * <p>
 
71
 * DOM1 does describe only non-DTD part of document. 
 
72
 * <p>
 
73
 * Passed context may represent errorous XML document. The code must
 
74
 * take into account that it can get <code>null</code>s even on places
 
75
 * where it does not expect it. E.g. <code>getParentNode()</code> as
 
76
 * the DOM document can be constructed as a <b>best effort</b> one.
 
77
 * <p>
 
78
 * Also as the context may originate from a text editor it is better to 
 
79
 * rely on <code>getPreviousSibling</code> rather then <code>getNextSibling</code>
 
80
 * as user usaully types text from document begining.
 
81
 *
 
82
 * @author  Petr Kuzel
 
83
 */   
 
84
public interface GrammarQuery {
 
85
    
 
86
    /**
 
87
     * @semantics Navigates through read-only Node tree to determine context and provide right results.
 
88
     * @postconditions Let ctx unchanged
 
89
     * @time Performs fast up to 300 ms.
 
90
     * @stereotype query
 
91
     * @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.
 
92
     * @return enumeration of <code>GrammarResult</code>s (ELEMENT_NODEs) that can be queried on name, and attributes.
 
93
     *         Every list member represents one possibility.  
 
94
     */
 
95
    Enumeration<GrammarResult> queryElements(HintContext virtualElementCtx);
 
96
 
 
97
    /**
 
98
     * Query attribute options for given context. All implementations must handle
 
99
     * queries based on owner element context.
 
100
     * @stereotype query
 
101
     * @output list of results that can be queried on name, and attributes
 
102
     * @time Performs fast up to 300 ms. 
 
103
     * @param ownerElementCtx represents owner <code>Element</code> that will host result.
 
104
     * @return enumeration of <code>GrammarResult</code>s (ATTRIBUTE_NODEs) that can be queried on name, and attributes.
 
105
     *         Every list member represents one possibility.  
 
106
     */
 
107
    Enumeration<GrammarResult> queryAttributes(HintContext ownerElementCtx);
 
108
 
 
109
    /**
 
110
     * Return options for value at given context.
 
111
     * It could be also used for completing of value parts such as Ant or XSLT property names (how to trigger it?).
 
112
     * @semantics Navigates through read-only Node tree to determine context and provide right results.
 
113
     * @postconditions Let ctx unchanged
 
114
     * @time Performs fast up to 300 ms.
 
115
     * @stereotype query
 
116
     * @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.
 
117
     * @return enumeration of <code>GrammarResult</code>s (TEXT_NODEs) that can be queried on name, and attributes.
 
118
     *         Every list member represents one possibility.  
 
119
     */
 
120
    Enumeration<GrammarResult> queryValues(HintContext virtualTextCtx);
 
121
 
 
122
    /**
 
123
     * query default value for given context. Two context types must be handled:
 
124
     * an attribute and an element context.
 
125
     * @param parentNodeCtx context for which default is queried
 
126
     * @return default value or <code>null</code>
 
127
     */
 
128
    GrammarResult queryDefault(HintContext parentNodeCtx);
 
129
 
 
130
    /**
 
131
     * Allow to get names of <b>parsed general entities</b>.
 
132
     * @param prefix prefix filter
 
133
     * @return enumeration of <code>GrammarResult</code>s (ENTITY_REFERENCE_NODEs)
 
134
     */
 
135
    Enumeration<GrammarResult> queryEntities(String prefix);
 
136
 
 
137
    /**
 
138
     * Allow to get names of <b>declared notations</b>.
 
139
     * @param prefix prefix filter
 
140
     * @return enumeration of <code>GrammarResult</code>s (NOTATION_NODEs)
 
141
     */    
 
142
    Enumeration<GrammarResult> queryNotations(String prefix);
 
143
 
 
144
    /**
 
145
     * Distinquieshes between empty enumaration types.
 
146
     * @return <code>true</code> there is no known result 
 
147
     *         <code>false</code> grammar does not allow here a result
 
148
     */
 
149
    boolean isAllowed(Enumeration<GrammarResult> en);
 
150
    
 
151
    
 
152
    
 
153
    // Candidates for separate interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
154
    
 
155
    /**
 
156
     * Allows Grammars to supply customizer for the HintContext
 
157
     * @param ctx the hint context node
 
158
     * @return a Component which can be used to customize the context node
 
159
     */
 
160
    java.awt.Component getCustomizer(HintContext nodeCtx);
 
161
    
 
162
    /**
 
163
     * Allows Grammars to supply customizer from the HintContext
 
164
     * @param ctx the hint context node
 
165
     * @return true if a customizer is available for this context
 
166
     */
 
167
    boolean hasCustomizer(HintContext nodeCtx);
 
168
 
 
169
    /**
 
170
     * Allows Grammars to supply properties for the HintContext
 
171
     * @param ctx the hint context node
 
172
     * @return an array of properties for this context
 
173
     */
 
174
    org.openide.nodes.Node.Property[] getProperties(HintContext nodeCtx);
 
175
}