1 /*

     2  * Copyright 2000-2005 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 // LexicalHandler.java - optional handler for lexical parse events.

    27 // http://www.saxproject.org

    28 // Public Domain: no warranty.

    29 // $Id: LexicalHandler.java,v 1.2 2004/11/03 22:49:08 jsuttor Exp $

    30 

    31 package org.xml.sax.ext;

    32 

    33 import org.xml.sax.SAXException;

    34 

    35 /**

    36  * SAX2 extension handler for lexical events.

    37  *

    38  * <blockquote>

    39  * <em>This module, both source code and documentation, is in the

    40  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>

    41  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>

    42  * for further information.

    43  * </blockquote>

    44  *

    45  * <p>This is an optional extension handler for SAX2 to provide

    46  * lexical information about an XML document, such as comments

    47  * and CDATA section boundaries.

    48  * XML readers are not required to recognize this handler, and it

    49  * is not part of core-only SAX2 distributions.</p>

    50  *

    51  * <p>The events in the lexical handler apply to the entire document,

    52  * not just to the document element, and all lexical handler events

    53  * must appear between the content handler's startDocument and

    54  * endDocument events.</p>

    55  *

    56  * <p>To set the LexicalHandler for an XML reader, use the

    57  * {@link org.xml.sax.XMLReader#setProperty setProperty} method

    58  * with the property name

    59  * <code>http://xml.org/sax/properties/lexical-handler</code>

    60  * and an object implementing this interface (or null) as the value.

    61  * If the reader does not report lexical events, it will throw a

    62  * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}

    63  * when you attempt to register the handler.</p>

    64  *

    65  * @since SAX 2.0 (extensions 1.0)

    66  * @author David Megginson

    67  */

    68 public interface LexicalHandler

    69 {

    70 

    71     /**

    72      * Report the start of DTD declarations, if any.

    73      *

    74      * <p>This method is intended to report the beginning of the

    75      * DOCTYPE declaration; if the document has no DOCTYPE declaration,

    76      * this method will not be invoked.</p>

    77      *

    78      * <p>All declarations reported through

    79      * {@link org.xml.sax.DTDHandler DTDHandler} or

    80      * {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear

    81      * between the startDTD and {@link #endDTD endDTD} events.

    82      * Declarations are assumed to belong to the internal DTD subset

    83      * unless they appear between {@link #startEntity startEntity}

    84      * and {@link #endEntity endEntity} events.  Comments and

    85      * processing instructions from the DTD should also be reported

    86      * between the startDTD and endDTD events, in their original

    87      * order of (logical) occurrence; they are not required to

    88      * appear in their correct locations relative to DTDHandler

    89      * or DeclHandler events, however.</p>

    90      *

    91      * <p>Note that the start/endDTD events will appear within

    92      * the start/endDocument events from ContentHandler and

    93      * before the first

    94      * {@link org.xml.sax.ContentHandler#startElement startElement}

    95      * event.</p>

    96      *

    97      * @param name The document type name.

    98      * @param publicId The declared public identifier for the

    99      *        external DTD subset, or null if none was declared.

   100      * @param systemId The declared system identifier for the

   101      *        external DTD subset, or null if none was declared.

   102      *        (Note that this is not resolved against the document

   103      *        base URI.)

   104      * @exception SAXException The application may raise an

   105      *            exception.

   106      * @see #endDTD

   107      * @see #startEntity

   108      */

   109     public abstract void startDTD (String name, String publicId,

   110                                    String systemId)

   111         throws SAXException;

   112 

   113 

   114     /**

   115      * Report the end of DTD declarations.

   116      *

   117      * <p>This method is intended to report the end of the

   118      * DOCTYPE declaration; if the document has no DOCTYPE declaration,

   119      * this method will not be invoked.</p>

   120      *

   121      * @exception SAXException The application may raise an exception.

   122      * @see #startDTD

   123      */

   124     public abstract void endDTD ()

   125         throws SAXException;

   126 

   127 

   128     /**

   129      * Report the beginning of some internal and external XML entities.

   130      *

   131      * <p>The reporting of parameter entities (including

   132      * the external DTD subset) is optional, and SAX2 drivers that

   133      * report LexicalHandler events may not implement it; you can use the

   134      * <code

   135      * >http://xml.org/sax/features/lexical-handler/parameter-entities</code>

   136      * feature to query or control the reporting of parameter entities.</p>

   137      *

   138      * <p>General entities are reported with their regular names,

   139      * parameter entities have '%' prepended to their names, and

   140      * the external DTD subset has the pseudo-entity name "[dtd]".</p>

   141      *

   142      * <p>When a SAX2 driver is providing these events, all other

   143      * events must be properly nested within start/end entity

   144      * events.  There is no additional requirement that events from

   145      * {@link org.xml.sax.ext.DeclHandler DeclHandler} or

   146      * {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p>

   147      *

   148      * <p>Note that skipped entities will be reported through the

   149      * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}

   150      * event, which is part of the ContentHandler interface.</p>

   151      *

   152      * <p>Because of the streaming event model that SAX uses, some

   153      * entity boundaries cannot be reported under any

   154      * circumstances:</p>

   155      *

   156      * <ul>

   157      * <li>general entities within attribute values</li>

   158      * <li>parameter entities within declarations</li>

   159      * </ul>

   160      *

   161      * <p>These will be silently expanded, with no indication of where

   162      * the original entity boundaries were.</p>

   163      *

   164      * <p>Note also that the boundaries of character references (which

   165      * are not really entities anyway) are not reported.</p>

   166      *

   167      * <p>All start/endEntity events must be properly nested.

   168      *

   169      * @param name The name of the entity.  If it is a parameter

   170      *        entity, the name will begin with '%', and if it is the

   171      *        external DTD subset, it will be "[dtd]".

   172      * @exception SAXException The application may raise an exception.

   173      * @see #endEntity

   174      * @see org.xml.sax.ext.DeclHandler#internalEntityDecl

   175      * @see org.xml.sax.ext.DeclHandler#externalEntityDecl

   176      */

   177     public abstract void startEntity (String name)

   178         throws SAXException;

   179 

   180 

   181     /**

   182      * Report the end of an entity.

   183      *

   184      * @param name The name of the entity that is ending.

   185      * @exception SAXException The application may raise an exception.

   186      * @see #startEntity

   187      */

   188     public abstract void endEntity (String name)

   189         throws SAXException;

   190 

   191 

   192     /**

   193      * Report the start of a CDATA section.

   194      *

   195      * <p>The contents of the CDATA section will be reported through

   196      * the regular {@link org.xml.sax.ContentHandler#characters

   197      * characters} event; this event is intended only to report

   198      * the boundary.</p>

   199      *

   200      * @exception SAXException The application may raise an exception.

   201      * @see #endCDATA

   202      */

   203     public abstract void startCDATA ()

   204         throws SAXException;

   205 

   206 

   207     /**

   208      * Report the end of a CDATA section.

   209      *

   210      * @exception SAXException The application may raise an exception.

   211      * @see #startCDATA

   212      */

   213     public abstract void endCDATA ()

   214         throws SAXException;

   215 

   216 

   217     /**

   218      * Report an XML comment anywhere in the document.

   219      *

   220      * <p>This callback will be used for comments inside or outside the

   221      * document element, including comments in the external DTD

   222      * subset (if read).  Comments in the DTD must be properly

   223      * nested inside start/endDTD and start/endEntity events (if

   224      * used).</p>

   225      *

   226      * @param ch An array holding the characters in the comment.

   227      * @param start The starting position in the array.

   228      * @param length The number of characters to use from the array.

   229      * @exception SAXException The application may raise an exception.

   230      */

   231     public abstract void comment (char ch[], int start, int length)

   232         throws SAXException;

   233 

   234 }

   235 

   236 // end of LexicalHandler.java