001: /*
002: * Copyright 2003-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: /*
017: * $Id: ExtendedContentHandler.java,v 1.7 2005/02/18 04:35:18 minchau Exp $
018: */
019: package org.apache.xml.serializer;
020:
021: import javax.xml.transform.SourceLocator;
022:
023: import org.xml.sax.SAXException;
024:
025: /**
026: * This interface describes extensions to the SAX ContentHandler interface.
027: * It is intended to be used by a serializer. The methods on this interface will
028: * implement SAX- like behavior. This allows the gradual collection of
029: * information rather than having it all up front. For example the call
030: * <pre>
031: * startElement(namespaceURI,localName,qName,atts)
032: * </pre>
033: * could be replaced with the calls
034: * <pre>
035: * startElement(namespaceURI,localName,qName)
036: * addAttributes(atts)
037: * </pre>
038: * If there are no attributes the second call can be dropped. If attributes are
039: * to be added one at a time with calls to
040: * <pre>
041: * addAttribute(namespaceURI, localName, qName, type, value)
042: * </pre>
043: * @xsl.usage internal
044: */
045: abstract interface ExtendedContentHandler extends
046: org.xml.sax.ContentHandler {
047: /**
048: * Add at attribute to the current element
049: * @param uri the namespace URI of the attribute name
050: * @param localName the local name of the attribute (without prefix)
051: * @param rawName the qualified name of the attribute
052: * @param type the attribute type typically character data (CDATA)
053: * @param value the value of the attribute
054: * @param XSLAttribute true if the added attribute is coming from an xsl:attribute element
055: * @throws SAXException
056: */
057: public void addAttribute(String uri, String localName,
058: String rawName, String type, String value,
059: boolean XSLAttribute) throws SAXException;
060:
061: /**
062: * Add attributes to the current element
063: * @param atts the attributes to add.
064: * @throws SAXException
065: */
066: public void addAttributes(org.xml.sax.Attributes atts)
067: throws org.xml.sax.SAXException;
068:
069: /**
070: * Add an attribute to the current element. The namespace URI of the
071: * attribute will be calculated from the prefix of qName. The local name
072: * will be derived from qName and the type will be assumed to be "CDATA".
073: * @param qName
074: * @param value
075: */
076: public void addAttribute(String qName, String value);
077:
078: /**
079: * This method is used to notify of a character event, but passing the data
080: * as a character String rather than the standard character array.
081: * @param chars the character data
082: * @throws SAXException
083: */
084: public void characters(String chars) throws SAXException;
085:
086: /**
087: * This method is used to notify of a character event, but passing the data
088: * as a DOM Node rather than the standard character array.
089: * @param node a DOM Node containing text.
090: * @throws SAXException
091: */
092: public void characters(org.w3c.dom.Node node)
093: throws org.xml.sax.SAXException;
094:
095: /**
096: * This method is used to notify that an element has ended. Unlike the
097: * standard SAX method
098: * <pre>
099: * endElement(namespaceURI,localName,qName)
100: * </pre>
101: * only the last parameter is passed. If needed the serializer can derive
102: * the localName from the qualified name and derive the namespaceURI from
103: * its implementation.
104: * @param elemName the fully qualified element name.
105: * @throws SAXException
106: */
107: public void endElement(String elemName) throws SAXException;
108:
109: /**
110: * This method is used to notify that an element is starting.
111: * This method is just like the standard SAX method
112: * <pre>
113: * startElement(uri,localName,qname,atts)
114: * </pre>
115: * but without the attributes.
116: * @param uri the namespace URI of the element
117: * @param localName the local name (without prefix) of the element
118: * @param qName the qualified name of the element
119: *
120: * @throws SAXException
121: */
122: public void startElement(String uri, String localName, String qName)
123: throws org.xml.sax.SAXException;
124:
125: /**
126: * This method is used to notify of the start of an element
127: * @param qName the fully qualified name of the element
128: * @throws SAXException
129: */
130: public void startElement(String qName) throws SAXException;
131:
132: /**
133: * This method is used to notify that a prefix mapping is to start, but
134: * after an element is started. The SAX method call
135: * <pre>
136: * startPrefixMapping(prefix,uri)
137: * </pre>
138: * is used just before an element starts and applies to the element to come,
139: * not to the current element. This method applies to the current element.
140: * For example one could make the calls in this order:
141: * <pre>
142: * startElement("prfx8:elem9")
143: * namespaceAfterStartElement("http://namespace8","prfx8")
144: * </pre>
145: *
146: * @param uri the namespace URI being declared
147: * @param prefix the prefix that maps to the given namespace
148: * @throws SAXException
149: */
150: public void namespaceAfterStartElement(String uri, String prefix)
151: throws SAXException;
152:
153: /**
154: * This method is used to notify that a prefix maping is to start, which can
155: * be for the current element, or for the one to come.
156: * @param prefix the prefix that maps to the given URI
157: * @param uri the namespace URI of the given prefix
158: * @param shouldFlush if true this call is like the SAX
159: * startPrefixMapping(prefix,uri) call and the mapping applies to the
160: * element to come. If false the mapping applies to the current element.
161: * @return boolean false if the prefix mapping was already in effect (in
162: * other words we are just re-declaring), true if this is a new, never
163: * before seen mapping for the element.
164: * @throws SAXException
165: */
166: public boolean startPrefixMapping(String prefix, String uri,
167: boolean shouldFlush) throws SAXException;
168:
169: /**
170: * Notify of an entity reference.
171: * @param entityName the name of the entity
172: * @throws SAXException
173: */
174: public void entityReference(String entityName) throws SAXException;
175:
176: /**
177: * This method returns an object that has the current namespace mappings in
178: * effect.
179: *
180: * @return NamespaceMappings an object that has the current namespace
181: * mappings in effect.
182: */
183: public NamespaceMappings getNamespaceMappings();
184:
185: /**
186: * This method returns the prefix that currently maps to the given namespace
187: * URI.
188: * @param uri the namespace URI
189: * @return String the prefix that currently maps to the given URI.
190: */
191: public String getPrefix(String uri);
192:
193: /**
194: * This method gets the prefix associated with a current element or
195: * attribute name.
196: * @param name the qualified name of an element, or attribute
197: * @param isElement true if it is an element name, false if it is an
198: * atttribute name
199: * @return String the namespace URI associated with the element or
200: * attribute.
201: */
202: public String getNamespaceURI(String name, boolean isElement);
203:
204: /**
205: * This method returns the namespace URI currently associated with the
206: * prefix.
207: * @param prefix a prefix of an element or attribute.
208: * @return String the namespace URI currently associated with the prefix.
209: */
210: public String getNamespaceURIFromPrefix(String prefix);
211:
212: /**
213: * This method is used to set the source locator, which might be used to
214: * generated an error message.
215: * @param locator the source locator
216: */
217: public void setSourceLocator(SourceLocator locator);
218:
219: // Bit constants for addUniqueAttribute().
220:
221: // The attribute value contains no bad characters. A "bad" character is one which
222: // is greater than 126 or it is one of '<', '>', '&' or '"'.
223: public static final int NO_BAD_CHARS = 0x1;
224:
225: // An HTML empty attribute (e.g. <OPTION selected>).
226: public static final int HTML_ATTREMPTY = 0x2;
227:
228: // An HTML URL attribute
229: public static final int HTML_ATTRURL = 0x4;
230:
231: /**
232: * Add a unique attribute to the current element.
233: * The attribute is guaranteed to be unique here. The serializer can write
234: * it out immediately without saving it in a table first. The integer
235: * flag contains information about the attribute, which helps the serializer
236: * to decide whether a particular processing is needed.
237: *
238: * @param qName the fully qualified attribute name.
239: * @param value the attribute value
240: * @param flags a bitwise flag
241: */
242: public void addUniqueAttribute(String qName, String value, int flags)
243: throws SAXException;
244:
245: /**
246: * Add an attribute from an xsl:attribute element.
247: * @param qName the qualified attribute name (prefix:localName)
248: * @param value the attributes value
249: * @param uri the uri that the prefix of the qName is mapped to.
250: */
251: public void addXSLAttribute(String qName, final String value,
252: 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(String uri, String localName,
265: String rawName, String type, String value)
266: throws SAXException;
267: }
|