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;

  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. }