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