KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > org > apache > xml > internal > serializer > ExtendedContentHandler


1 /*
2  * Copyright 2003-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 /*
17  * $Id: ExtendedContentHandler.java,v 1.3 2004/02/17 04:18:18 minchau Exp $
18  */

19 package com.sun.org.apache.xml.internal.serializer;
20
21 import javax.xml.transform.SourceLocator JavaDoc;
22
23 import org.xml.sax.SAXException JavaDoc;
24
25 /**
26  * This interface describes extensions to the SAX ContentHandler interface.
27  * It is intended to be used by a serializer. The methods on this interface will
28  * implement SAX- like behavior. This allows the gradual collection of
29  * information rather than having it all up front. For example the call
30  * <pre>
31  * startElement(namespaceURI,localName,qName,atts)
32  * </pre>
33  * could be replaced with the calls
34  * <pre>
35  * startElement(namespaceURI,localName,qName)
36  * addAttributes(atts)
37  * </pre>
38  * If there are no attributes the second call can be dropped. If attributes are
39  * to be added one at a time with calls to
40  * <pre>
41  * addAttribute(namespaceURI, localName, qName, type, value)
42  * </pre>
43  */

44 public interface ExtendedContentHandler extends org.xml.sax.ContentHandler JavaDoc
45 {
46     /**
47      * Add at attribute to the current element
48      * @param uri the namespace URI of the attribute name
49      * @param localName the local name of the attribute (without prefix)
50      * @param rawName the qualified name of the attribute
51      * @param type the attribute type typically character data (CDATA)
52      * @param value the value of the attribute
53      * @throws SAXException
54      */

55     public void addAttribute(
56         String JavaDoc uri,
57         String JavaDoc localName,
58         String JavaDoc rawName,
59         String JavaDoc type,
60         String JavaDoc value)
61         throws SAXException JavaDoc;
62     /**
63      * Add attributes to the current element
64      * @param atts the attributes to add.
65      * @throws SAXException
66      */

67     public void addAttributes(org.xml.sax.Attributes JavaDoc atts)
68         throws org.xml.sax.SAXException JavaDoc;
69     /**
70      * Add an attribute to the current element. The namespace URI of the
71      * attribute will be calculated from the prefix of qName. The local name
72      * will be derived from qName and the type will be assumed to be "CDATA".
73      * @param qName
74      * @param value
75      */

76     public void addAttribute(String JavaDoc qName, String JavaDoc value);
77     
78     /**
79      * This method is used to notify of a character event, but passing the data
80      * as a character String rather than the standard character array.
81      * @param chars the character data
82      * @throws SAXException
83      */

84     public void characters(String JavaDoc chars) throws SAXException JavaDoc;
85     /**
86      * This method is used to notify that an element has ended. Unlike the
87      * standard SAX method
88      * <pre>
89      * endElement(namespaceURI,localName,qName)
90      * </pre>
91      * only the last parameter is passed. If needed the serializer can derive
92      * the localName from the qualified name and derive the namespaceURI from
93      * its implementation.
94      * @param elemName the fully qualified element name.
95      * @throws SAXException
96      */

97     public void endElement(String JavaDoc elemName) throws SAXException JavaDoc;
98
99     /**
100      * This method is used to notify that an element is starting.
101      * This method is just like the standard SAX method
102      * <pre>
103      * startElement(uri,localName,qname,atts)
104      * </pre>
105      * but without the attributes.
106      * @param uri the namespace URI of the element
107      * @param localName the local name (without prefix) of the element
108      * @param qName the qualified name of the element
109      *
110      * @throws SAXException
111      */

112     public void startElement(String JavaDoc uri, String JavaDoc localName, String JavaDoc qName)
113         throws org.xml.sax.SAXException JavaDoc;
114
115     /**
116      * This method is used to notify of the start of an element
117      * @param qName the fully qualified name of the element
118      * @throws SAXException
119      */

120     public void startElement(String JavaDoc qName) throws SAXException JavaDoc;
121     /**
122      * This method is used to notify that a prefix mapping is to start, but
123      * after an element is started. The SAX method call
124      * <pre>
125      * startPrefixMapping(prefix,uri)
126      * </pre>
127      * is used just before an element starts and applies to the element to come,
128      * not to the current element. This method applies to the current element.
129      * For example one could make the calls in this order:
130      * <pre>
131      * startElement("prfx8:elem9")
132      * namespaceAfterStartElement("http://namespace8","prfx8")
133      * </pre>
134      *
135      * @param uri the namespace URI being declared
136      * @param prefix the prefix that maps to the given namespace
137      * @throws SAXException
138      */

139     public void namespaceAfterStartElement(String JavaDoc uri, String JavaDoc prefix)
140         throws SAXException JavaDoc;
141
142     /**
143      * This method is used to notify that a prefix maping is to start, which can
144      * be for the current element, or for the one to come.
145      * @param prefix the prefix that maps to the given URI
146      * @param uri the namespace URI of the given prefix
147      * @param shouldFlush if true this call is like the SAX
148      * startPrefixMapping(prefix,uri) call and the mapping applies to the
149      * element to come. If false the mapping applies to the current element.
150      * @return boolean false if the prefix mapping was already in effect (in
151      * other words we are just re-declaring), true if this is a new, never
152      * before seen mapping for the element.
153      * @throws SAXException
154      */

155     public boolean startPrefixMapping(
156         String JavaDoc prefix,
157         String JavaDoc uri,
158         boolean shouldFlush)
159         throws SAXException JavaDoc;
160     /**
161      * Notify of an entity reference.
162      * @param entityName the name of the entity
163      * @throws SAXException
164      */

165     public void entityReference(String JavaDoc entityName) throws SAXException JavaDoc;
166
167     /**
168      * This method returns an object that has the current namespace mappings in
169      * effect.
170      *
171      * @return NamespaceMappings an object that has the current namespace
172      * mappings in effect.
173      */

174     public NamespaceMappings getNamespaceMappings();
175     /**
176      * This method returns the prefix that currently maps to the given namespace
177      * URI.
178      * @param uri the namespace URI
179      * @return String the prefix that currently maps to the given URI.
180      */

181     public String JavaDoc getPrefix(String JavaDoc uri);
182     /**
183      * This method gets the prefix associated with a current element or
184      * attribute name.
185      * @param name the qualified name of an element, or attribute
186      * @param isElement true if it is an element name, false if it is an
187      * atttribute name
188      * @return String the namespace URI associated with the element or
189      * attribute.
190      */

191     public String JavaDoc getNamespaceURI(String JavaDoc name, boolean isElement);
192     /**
193      * This method returns the namespace URI currently associated with the
194      * prefix.
195      * @param prefix a prefix of an element or attribute.
196      * @return String the namespace URI currently associated with the prefix.
197      */

198     public String JavaDoc getNamespaceURIFromPrefix(String JavaDoc prefix);
199
200     /**
201      * This method is used to set the source locator, which might be used to
202      * generated an error message.
203      * @param locator the source locator
204      */

205     public void setSourceLocator(SourceLocator JavaDoc locator);
206
207     // Bit constants for addUniqueAttribute().
208

209     // The attribute value contains no bad characters. A "bad" character is one which
210
// is greater than 126 or it is one of '<', '>', '&' or '"'.
211
public static final int NO_BAD_CHARS = 0x1;
212     
213     // An HTML empty attribute (e.g. <OPTION selected>).
214
public static final int HTML_ATTREMPTY = 0x2;
215     
216     // An HTML URL attribute
217
public static final int HTML_ATTRURL = 0x4;
218
219     /**
220      * Add a unique attribute to the current element.
221      * The attribute is guaranteed to be unique here. The serializer can write
222      * it out immediately without saving it in a table first. The integer
223      * flag contains information about the attribute, which helps the serializer
224      * to decide whether a particular processing is needed.
225      *
226      * @param qName the fully qualified attribute name.
227      * @param value the attribute value
228      * @param flags a bitwise flag
229      */

230     public void addUniqueAttribute(String JavaDoc qName, String JavaDoc value, int flags)
231         throws SAXException JavaDoc;
232 }
233
Popular Tags