• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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