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 org.apache.xml.serializer;
20  
21  import javax.xml.transform.SourceLocator  ;
22  
23  import org.xml.sax.SAXException  ;
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  
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   uri,
57          String   localName,
58          String   rawName,
59          String   type,
60          String   value)
61          throws SAXException  ;
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   atts)
68          throws org.xml.sax.SAXException  ;
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   qName, String   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   chars) throws SAXException  ;
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   elemName) throws SAXException  ;
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   uri, String   localName, String   qName)
113         throws org.xml.sax.SAXException  ;
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   qName) throws SAXException  ;
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   uri, String   prefix)
140         throws SAXException  ;
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   prefix,
157         String   uri,
158         boolean shouldFlush)
159         throws SAXException  ;
160     /**
161      * Notify of an entity reference.
162      * @param entityName the name of the entity
163      * @throws SAXException
164      */
165     public void entityReference(String   entityName) throws SAXException  ;
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   getPrefix(String   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   getNamespaceURI(String   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   getNamespaceURIFromPrefix(String   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   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   qName, String   value, int flags)
231         throws SAXException  ;
232 }
233
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags