View Javadoc
1   /*
2    * reserved comment block
3    * DO NOT REMOVE OR ALTER!
4    */
5   /*
6    * Copyright 2001, 2002,2004 The Apache Software Foundation.
7    *
8    * Licensed under the Apache License, Version 2.0 (the "License");
9    * you may not use this file except in compliance with the License.
10   * You may obtain a copy of the License at
11   *
12   *      http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  
21  package com.sun.org.apache.xerces.internal.xni;
22  
23  import java.util.Enumeration;
24  import java.util.Vector;
25  
26  /**
27   * Represents an interface to query namespace information.
28   * <p>
29   * The prefix and namespace must be identical references for equal strings, thus
30   * each string should be internalized (@see String.intern())
31   * or added to the <code>SymbolTable</code>
32   *
33   * @see <a href="../../../../../xerces2/com/sun/org/apache/xerces/internal/util/SymbolTable.html">
34   * com.sun.org.apache.xerces.internal.util.SymbolTable</a>
35   *
36   * @author Andy Clark, IBM
37   *
38   */
39  public interface NamespaceContext {
40  
41      //
42      // Constants
43      //
44  
45      /**
46       * The XML Namespace ("http://www.w3.org/XML/1998/namespace"). This is
47       * the Namespace URI that is automatically mapped to the "xml" prefix.
48       */
49      public final static String XML_URI = "http://www.w3.org/XML/1998/namespace".intern();
50  
51      /**
52       * XML Information Set REC
53       * all namespace attributes (including those named xmlns,
54       * whose [prefix] property has no value) have a namespace URI of http://www.w3.org/2000/xmlns/
55       */
56      public final static String XMLNS_URI = "http://www.w3.org/2000/xmlns/".intern();
57  
58      //
59      // NamespaceContext methods
60      //
61  
62      /**
63       * Start a new Namespace context.
64       * <p>
65       * A new context should be pushed at the beginning
66       * of each XML element: the new context will automatically inherit
67       * the declarations of its parent context, but it will also keep
68       * track of which declarations were made within this context.
69       * <p>
70       *
71       * @see #popContext
72       */
73      public void pushContext();
74  
75     /**
76       * Revert to the previous Namespace context.
77       * <p>
78       * The context should be popped at the end of each
79       * XML element.  After popping the context, all Namespace prefix
80       * mappings that were previously in force are restored.
81       * <p>
82       * Users must not attempt to declare additional Namespace
83       * prefixes after popping a context, unless you push another
84       * context first.
85       *
86       * @see #pushContext
87       */
88      public void popContext();
89  
90      /**
91       * Declare a Namespace prefix.
92       * <p>
93       * This method declares a prefix in the current Namespace
94       * context; the prefix will remain in force until this context
95       * is popped, unless it is shadowed in a descendant context.
96       * <p>
97       * Note that to declare a default Namespace, use the empty string.
98       * The prefixes "xml" and "xmlns" can't be rebound.
99       * <p>
100      * Note that you must <em>not</em> declare a prefix after
101      * you've pushed and popped another Namespace.
102      *
103      * @param prefix The prefix to declare, or null for the empty
104      *        string.
105      * @param uri The Namespace URI to associate with the prefix.
106      *
107      * @return true if the prefix was legal, false otherwise
108      *
109      * @see #getURI
110      * @see #getDeclaredPrefixAt
111      */
112     public boolean declarePrefix(String prefix, String uri);
113 
114 
115     /**
116      * Look up a prefix and get the currently-mapped Namespace URI.
117      * <p>
118      * This method looks up the prefix in the current context. If no mapping
119      * is found, this methods will continue lookup in the parent context(s).
120      * Use the empty string ("") for the default Namespace.
121      *
122      * @param prefix The prefix to look up.
123      *
124      * @return The associated Namespace URI, or null if the prefix
125      *         is undeclared in this context.
126      */
127     public String getURI(String prefix);
128 
129     /**
130      * Look up a namespace URI and get one of the mapped prefix.
131      * <p>
132      * This method looks up the namespace URI in the current context.
133      * If more than one prefix is currently mapped to the same URI,
134      * this method will make an arbitrary selection
135      * If no mapping is found, this methods will continue lookup in the
136      * parent context(s).
137      *
138      * @param uri The namespace URI to look up.
139      *
140      * @return One of the associated prefixes, or null if the uri
141      *         does not map to any prefix.
142      *
143      * @see #getPrefix
144      */
145     public String getPrefix(String uri);
146 
147 
148     /**
149      * Return a count of locally declared prefixes, including
150      * the default prefix if bound.
151      */
152     public int getDeclaredPrefixCount();
153 
154     /**
155      * Returns the prefix at the specified index in the current context.
156      */
157     public String getDeclaredPrefixAt(int index);
158 
159         /**
160          * Return an enumeration of all prefixes whose declarations are active
161      * in the current context. This includes declarations from parent contexts
162      * that have not been overridden.
163          * @return Enumeration
164          */
165     public Enumeration getAllPrefixes();
166 
167     /**
168      * Reset this Namespace support object for reuse.
169      *
170      * <p>It is necessary to invoke this method before reusing the
171      * Namespace support object for a new session.</p>
172      *
173      * <p>Note that implementations of this method need to ensure that
174      * the declaration of the prefixes "xmlns" and "xml" are available.</p>
175      */
176     public void reset();
177 
178 
179 } // interface NamespaceContext