001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.modules.xml.api.model;
043:
044: import java.util.Enumeration;
045:
046: /**
047: * A query interface returning possible fenomens as given by document grammar.
048: * <p>
049: * It provides at specified <code>HintContext</code> following information:
050: * <ul>
051: * <li>allowed element names and namespaces
052: * <li>allowed entity names
053: * <li>allowed notation names
054: * <li>allowed attribute names
055: * <li>allowed values of attribute values or element content
056: * </ul>
057: * This information are returned as <code>Enumeration</code>. Every member of
058: * the enumeration represents one possible option. Empty enumeration signals
059: * that no hint can be derived from grammar in given context.
060: * <p>
061: * Every option represents DOM <code>Node</code> that can have children. These children
062: * represents mandatory content for given option. Providing them is optional.
063: * On the other hand <code>EMPTY</code> elements may not provide any children.
064: *
065: * <h3>Context Representation</h3>
066: * Query context is represented by a read-only DOM1 model Core and XML modules
067: * (it may be replaced with DOM2).
068: *
069: * <h3>Implementation Note:</h3>
070: * <p>
071: * DOM1 does describe only non-DTD part of document.
072: * <p>
073: * Passed context may represent errorous XML document. The code must
074: * take into account that it can get <code>null</code>s even on places
075: * where it does not expect it. E.g. <code>getParentNode()</code> as
076: * the DOM document can be constructed as a <b>best effort</b> one.
077: * <p>
078: * Also as the context may originate from a text editor it is better to
079: * rely on <code>getPreviousSibling</code> rather then <code>getNextSibling</code>
080: * as user usaully types text from document begining.
081: *
082: * @author Petr Kuzel
083: */
084: public interface GrammarQuery {
085:
086: /**
087: * @semantics Navigates through read-only Node tree to determine context and provide right results.
088: * @postconditions Let ctx unchanged
089: * @time Performs fast up to 300 ms.
090: * @stereotype query
091: * @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.
092: * @return enumeration of <code>GrammarResult</code>s (ELEMENT_NODEs) that can be queried on name, and attributes.
093: * Every list member represents one possibility.
094: */
095: Enumeration<GrammarResult> queryElements(
096: HintContext virtualElementCtx);
097:
098: /**
099: * Query attribute options for given context. All implementations must handle
100: * queries based on owner element context.
101: * @stereotype query
102: * @output list of results that can be queried on name, and attributes
103: * @time Performs fast up to 300 ms.
104: * @param ownerElementCtx represents owner <code>Element</code> that will host result.
105: * @return enumeration of <code>GrammarResult</code>s (ATTRIBUTE_NODEs) that can be queried on name, and attributes.
106: * Every list member represents one possibility.
107: */
108: Enumeration<GrammarResult> queryAttributes(
109: HintContext ownerElementCtx);
110:
111: /**
112: * Return options for value at given context.
113: * It could be also used for completing of value parts such as Ant or XSLT property names (how to trigger it?).
114: * @semantics Navigates through read-only Node tree to determine context and provide right results.
115: * @postconditions Let ctx unchanged
116: * @time Performs fast up to 300 ms.
117: * @stereotype query
118: * @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.
119: * @return enumeration of <code>GrammarResult</code>s (TEXT_NODEs) that can be queried on name, and attributes.
120: * Every list member represents one possibility.
121: */
122: Enumeration<GrammarResult> queryValues(HintContext virtualTextCtx);
123:
124: /**
125: * query default value for given context. Two context types must be handled:
126: * an attribute and an element context.
127: * @param parentNodeCtx context for which default is queried
128: * @return default value or <code>null</code>
129: */
130: GrammarResult queryDefault(HintContext parentNodeCtx);
131:
132: /**
133: * Allow to get names of <b>parsed general entities</b>.
134: * @param prefix prefix filter
135: * @return enumeration of <code>GrammarResult</code>s (ENTITY_REFERENCE_NODEs)
136: */
137: Enumeration<GrammarResult> queryEntities(String prefix);
138:
139: /**
140: * Allow to get names of <b>declared notations</b>.
141: * @param prefix prefix filter
142: * @return enumeration of <code>GrammarResult</code>s (NOTATION_NODEs)
143: */
144: Enumeration<GrammarResult> queryNotations(String prefix);
145:
146: /**
147: * Distinquieshes between empty enumaration types.
148: * @return <code>true</code> there is no known result
149: * <code>false</code> grammar does not allow here a result
150: */
151: boolean isAllowed(Enumeration<GrammarResult> en);
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: }
|