1 /* 2 * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved. 3 */ 4 /* 5 * Licensed to the Apache Software Foundation (ASF) under one or more 6 * contributor license agreements. See the NOTICE file distributed with 7 * this work for additional information regarding copyright ownership. 8 * The ASF licenses this file to You under the Apache License, Version 2.0 9 * (the "License"); you may not use this file except in compliance with 10 * the License. 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 25 /** 26 * Represents an interface to query namespace information. 27 * <p> 28 * The prefix and namespace must be identical references for equal strings, thus 29 * each string should be internalized (@see String.intern()) 30 * or added to the <code>SymbolTable</code> 31 * 32 * @see <a href="../../../../../xerces2/com/sun/org/apache/xerces/internal/util/SymbolTable.html"> 33 * com.sun.org.apache.xerces.internal.util.SymbolTable</a> 34 * 35 * @author Andy Clark, IBM 36 * 37 * @LastModified: Oct 2017 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 */ pushContext()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 */ popContext()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 */ declarePrefix(String prefix, String uri)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 */ getURI(String prefix)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 */ getPrefix(String uri)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 */ getDeclaredPrefixCount()152 public int getDeclaredPrefixCount(); 153 154 /** 155 * Returns the prefix at the specified index in the current context. 156 */ getDeclaredPrefixAt(int index)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 */ getAllPrefixes()165 public Enumeration<String> 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 */ reset()176 public void reset(); 177 178 179 } // interface NamespaceContext 180