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 */
21package org.apache.xml.serializer;
22
23import javax.xml.transform.SourceLocator;
24
25import 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 */
47public 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