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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 264 public void addAttribute( 265 String uri, 266 String localName, 267 String rawName, 268 String type, 269 String value) 270 throws SAXException; 271 } 272
