1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 /* 19 * $Id: ExtendedContentHandler.java 468654 2006-10-28 07:09:23Z minchau $ 20 */ 21 package org.apache.xml.serializer; 22 23 import javax.xml.transform.SourceLocator; 24 25 import org.xml.sax.SAXException; 26 27 /** 28 * This interface describes extensions to the SAX ContentHandler interface. 29 * It is intended to be used by a serializer. The methods on this interface will 30 * implement SAX- like behavior. This allows the gradual collection of 31 * information rather than having it all up front. For example the call 32 * <pre> 33 * startElement(namespaceURI,localName,qName,atts) 34 * </pre> 35 * could be replaced with the calls 36 * <pre> 37 * startElement(namespaceURI,localName,qName) 38 * addAttributes(atts) 39 * </pre> 40 * If there are no attributes the second call can be dropped. If attributes are 41 * to be added one at a time with calls to 42 * <pre> 43 * addAttribute(namespaceURI, localName, qName, type, value) 44 * </pre> 45 * @xsl.usage internal 46 */ 47 public interface ExtendedContentHandler extends org.xml.sax.ContentHandler 48 { 49 /** 50 * Add at attribute to the current element 51 * @param uri the namespace URI of the attribute name 52 * @param localName the local name of the attribute (without prefix) 53 * @param rawName the qualified name of the attribute 54 * @param type the attribute type typically character data (CDATA) 55 * @param value the value of the attribute 56 * @param XSLAttribute true if the added attribute is coming from an xsl:attribute element 57 * @throws SAXException 58 */ addAttribute( String uri, String localName, String rawName, String type, String value, boolean XSLAttribute)59 public void addAttribute( 60 String uri, 61 String localName, 62 String rawName, 63 String type, 64 String value, 65 boolean XSLAttribute) 66 throws SAXException; 67 /** 68 * Add attributes to the current element 69 * @param atts the attributes to add. 70 * @throws SAXException 71 */ addAttributes(org.xml.sax.Attributes atts)72 public void addAttributes(org.xml.sax.Attributes atts) 73 throws org.xml.sax.SAXException; 74 /** 75 * Add an attribute to the current element. The namespace URI of the 76 * attribute will be calculated from the prefix of qName. The local name 77 * will be derived from qName and the type will be assumed to be "CDATA". 78 * @param qName 79 * @param value 80 */ addAttribute(String qName, String value)81 public void addAttribute(String qName, String value); 82 83 /** 84 * This method is used to notify of a character event, but passing the data 85 * as a character String rather than the standard character array. 86 * @param chars the character data 87 * @throws SAXException 88 */ characters(String chars)89 public void characters(String chars) throws SAXException; 90 91 /** 92 * This method is used to notify of a character event, but passing the data 93 * as a DOM Node rather than the standard character array. 94 * @param node a DOM Node containing text. 95 * @throws SAXException 96 */ characters(org.w3c.dom.Node node)97 public void characters(org.w3c.dom.Node node) throws org.xml.sax.SAXException; 98 /** 99 * This method is used to notify that an element has ended. Unlike the 100 * standard SAX method 101 * <pre> 102 * endElement(namespaceURI,localName,qName) 103 * </pre> 104 * only the last parameter is passed. If needed the serializer can derive 105 * the localName from the qualified name and derive the namespaceURI from 106 * its implementation. 107 * @param elemName the fully qualified element name. 108 * @throws SAXException 109 */ endElement(String elemName)110 public void endElement(String elemName) throws SAXException; 111 112 /** 113 * This method is used to notify that an element is starting. 114 * This method is just like the standard SAX method 115 * <pre> 116 * startElement(uri,localName,qname,atts) 117 * </pre> 118 * but without the attributes. 119 * @param uri the namespace URI of the element 120 * @param localName the local name (without prefix) of the element 121 * @param qName the qualified name of the element 122 * 123 * @throws SAXException 124 */ startElement(String uri, String localName, String qName)125 public void startElement(String uri, String localName, String qName) 126 throws org.xml.sax.SAXException; 127 128 /** 129 * This method is used to notify of the start of an element 130 * @param qName the fully qualified name of the element 131 * @throws SAXException 132 */ startElement(String qName)133 public void startElement(String qName) throws SAXException; 134 /** 135 * This method is used to notify that a prefix mapping is to start, but 136 * after an element is started. The SAX method call 137 * <pre> 138 * startPrefixMapping(prefix,uri) 139 * </pre> 140 * is used just before an element starts and applies to the element to come, 141 * not to the current element. This method applies to the current element. 142 * For example one could make the calls in this order: 143 * <pre> 144 * startElement("prfx8:elem9") 145 * namespaceAfterStartElement("http://namespace8","prfx8") 146 * </pre> 147 * 148 * @param uri the namespace URI being declared 149 * @param prefix the prefix that maps to the given namespace 150 * @throws SAXException 151 */ namespaceAfterStartElement(String uri, String prefix)152 public void namespaceAfterStartElement(String uri, String prefix) 153 throws SAXException; 154 155 /** 156 * This method is used to notify that a prefix maping is to start, which can 157 * be for the current element, or for the one to come. 158 * @param prefix the prefix that maps to the given URI 159 * @param uri the namespace URI of the given prefix 160 * @param shouldFlush if true this call is like the SAX 161 * startPrefixMapping(prefix,uri) call and the mapping applies to the 162 * element to come. If false the mapping applies to the current element. 163 * @return boolean false if the prefix mapping was already in effect (in 164 * other words we are just re-declaring), true if this is a new, never 165 * before seen mapping for the element. 166 * @throws SAXException 167 */ startPrefixMapping( String prefix, String uri, boolean shouldFlush)168 public boolean startPrefixMapping( 169 String prefix, 170 String uri, 171 boolean shouldFlush) 172 throws SAXException; 173 /** 174 * Notify of an entity reference. 175 * @param entityName the name of the entity 176 * @throws SAXException 177 */ entityReference(String entityName)178 public void entityReference(String entityName) throws SAXException; 179 180 /** 181 * This method returns an object that has the current namespace mappings in 182 * effect. 183 * 184 * @return NamespaceMappings an object that has the current namespace 185 * mappings in effect. 186 */ getNamespaceMappings()187 public NamespaceMappings getNamespaceMappings(); 188 /** 189 * This method returns the prefix that currently maps to the given namespace 190 * URI. 191 * @param uri the namespace URI 192 * @return String the prefix that currently maps to the given URI. 193 */ getPrefix(String uri)194 public String getPrefix(String uri); 195 /** 196 * This method gets the prefix associated with a current element or 197 * attribute name. 198 * @param name the qualified name of an element, or attribute 199 * @param isElement true if it is an element name, false if it is an 200 * atttribute name 201 * @return String the namespace URI associated with the element or 202 * attribute. 203 */ getNamespaceURI(String name, boolean isElement)204 public String getNamespaceURI(String name, boolean isElement); 205 /** 206 * This method returns the namespace URI currently associated with the 207 * prefix. 208 * @param prefix a prefix of an element or attribute. 209 * @return String the namespace URI currently associated with the prefix. 210 */ getNamespaceURIFromPrefix(String prefix)211 public String getNamespaceURIFromPrefix(String prefix); 212 213 /** 214 * This method is used to set the source locator, which might be used to 215 * generated an error message. 216 * @param locator the source locator 217 */ setSourceLocator(SourceLocator locator)218 public void setSourceLocator(SourceLocator locator); 219 220 // Bit constants for addUniqueAttribute(). 221 222 // The attribute value contains no bad characters. A "bad" character is one which 223 // is greater than 126 or it is one of '<', '>', '&' or '"'. 224 public static final int NO_BAD_CHARS = 0x1; 225 226 // An HTML empty attribute (e.g. <OPTION selected>). 227 public static final int HTML_ATTREMPTY = 0x2; 228 229 // An HTML URL attribute 230 public static final int HTML_ATTRURL = 0x4; 231 232 /** 233 * Add a unique attribute to the current element. 234 * The attribute is guaranteed to be unique here. The serializer can write 235 * it out immediately without saving it in a table first. The integer 236 * flag contains information about the attribute, which helps the serializer 237 * to decide whether a particular processing is needed. 238 * 239 * @param qName the fully qualified attribute name. 240 * @param value the attribute value 241 * @param flags a bitwise flag 242 */ addUniqueAttribute(String qName, String value, int flags)243 public void addUniqueAttribute(String qName, String value, int flags) 244 throws SAXException; 245 246 /** 247 * Add an attribute from an xsl:attribute element. 248 * @param qName the qualified attribute name (prefix:localName) 249 * @param value the attributes value 250 * @param uri the uri that the prefix of the qName is mapped to. 251 */ addXSLAttribute(String qName, final String value, final String uri)252 public void addXSLAttribute(String qName, final String value, final String uri); 253 254 /** 255 * Add at attribute to the current element, not from an xsl:attribute 256 * element. 257 * @param uri the namespace URI of the attribute name 258 * @param localName the local name of the attribute (without prefix) 259 * @param rawName the qualified name of the attribute 260 * @param type the attribute type typically character data (CDATA) 261 * @param value the value of the attribute 262 * @throws SAXException 263 */ addAttribute( String uri, String localName, String rawName, String type, String value)264 public void addAttribute( 265 String uri, 266 String localName, 267 String rawName, 268 String type, 269 String value) 270 throws SAXException; 271 } 272