001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 /*
019 * $Id: ExtendedContentHandler.java 468654 2006-10-28 07:09:23Z minchau $
020 */
021 package org.apache.xml.serializer;
022
023 import javax.xml.transform.SourceLocator;
024
025 import org.xml.sax.SAXException;
026
027 /**
028 * This interface describes extensions to the SAX ContentHandler interface.
029 * It is intended to be used by a serializer. The methods on this interface will
030 * implement SAX- like behavior. This allows the gradual collection of
031 * information rather than having it all up front. For example the call
032 * <pre>
033 * startElement(namespaceURI,localName,qName,atts)
034 * </pre>
035 * could be replaced with the calls
036 * <pre>
037 * startElement(namespaceURI,localName,qName)
038 * addAttributes(atts)
039 * </pre>
040 * If there are no attributes the second call can be dropped. If attributes are
041 * to be added one at a time with calls to
042 * <pre>
043 * addAttribute(namespaceURI, localName, qName, type, value)
044 * </pre>
045 * @xsl.usage internal
046 */
047 public interface ExtendedContentHandler extends org.xml.sax.ContentHandler
048 {
049 /**
050 * Add at attribute to the current element
051 * @param uri the namespace URI of the attribute name
052 * @param localName the local name of the attribute (without prefix)
053 * @param rawName the qualified name of the attribute
054 * @param type the attribute type typically character data (CDATA)
055 * @param value the value of the attribute
056 * @param XSLAttribute true if the added attribute is coming from an xsl:attribute element
057 * @throws SAXException
058 */
059 public void addAttribute(
060 String uri,
061 String localName,
062 String rawName,
063 String type,
064 String value,
065 boolean XSLAttribute)
066 throws SAXException;
067 /**
068 * Add attributes to the current element
069 * @param atts the attributes to add.
070 * @throws SAXException
071 */
072 public void addAttributes(org.xml.sax.Attributes atts)
073 throws org.xml.sax.SAXException;
074 /**
075 * Add an attribute to the current element. The namespace URI of the
076 * attribute will be calculated from the prefix of qName. The local name
077 * will be derived from qName and the type will be assumed to be "CDATA".
078 * @param qName
079 * @param value
080 */
081 public void addAttribute(String qName, String value);
082
083 /**
084 * This method is used to notify of a character event, but passing the data
085 * as a character String rather than the standard character array.
086 * @param chars the character data
087 * @throws SAXException
088 */
089 public void characters(String chars) throws SAXException;
090
091 /**
092 * This method is used to notify of a character event, but passing the data
093 * as a DOM Node rather than the standard character array.
094 * @param node a DOM Node containing text.
095 * @throws SAXException
096 */
097 public void characters(org.w3c.dom.Node node) throws org.xml.sax.SAXException;
098 /**
099 * 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 }