    001    /* ========================================================================
    002     * JCommon : a free general purpose class library for the Java(tm) platform
    003     * ========================================================================
    004     *
    005     * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
    006     *
    007     * Project Info:  http://www.jfree.org/jcommon/index.html
    008     *
    009     * This library is free software; you can redistribute it and/or modify it
    010     * under the terms of the GNU Lesser General Public License as published by
    011     * the Free Software Foundation; either version 2.1 of the License, or
    012     * (at your option) any later version.
    013     *
    014     * This library is distributed in the hope that it will be useful, but
    015     * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    016     * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
    017     * License for more details.
    018     *
    019     * You should have received a copy of the GNU Lesser General Public
    020     * License along with this library; if not, write to the Free Software
    021     * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
    022     * USA.
    023     *
    024     * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
    025     * in the United States and other countries.]
    026     *
    027     * -------------------
    028     * CommentHandler.java
    029     * -------------------
    030     * (C)opyright 2003-2005, by Thomas Morgner and Contributors.
    031     *
    032     * Original Author:  Thomas Morgner;
    033     * Contributor(s):   David Gilbert (for Object Refinery Limited);
    034     *
    035     * $Id: CommentHandler.java,v 1.3 2005/10/18 13:25:44 mungady Exp $
    036     *
    037     * Changes
    038     * -------------------------
    039     * 20-Jul-2003 : Initial version
    040     *
    041     */
    042
    043    package org.jfree.xml;
    044
    045    import java.util.ArrayList;
    046
    047    import org.xml.sax.SAXException;
    048    import org.xml.sax.ext.LexicalHandler;
    049
    050    /**
    051     * The comment handler is used to collect all XML comments from the
    052     * SAX parser. The parser implementation must support comments to make
    053     * this feature work.
    054     *
    055     * @author Thomas Morgner
    056     */
    057    public class CommentHandler implements LexicalHandler {
    058
    059      /** A constant marking a comment on the opening tag. */
    060      public static final String OPEN_TAG_COMMENT = "parser.comment.open";
    061
    062      /** A constant marking a comment on the closing tag. */
    063      public static final String CLOSE_TAG_COMMENT = "parser.comment.close";
    064
    065      /** A list containing all collected comments. */
    066      private final ArrayList comment;
    067
    068      /** a flag marking whether the SAX parser is currently working in the DTD. */
    069      private boolean inDTD;
    070
    071      /**
    072       * DefaultConstructor.
    073       */
    074      public CommentHandler() {
    075        this.comment = new ArrayList();
    076      }
    077
    078      /**
    079       * Report the start of DTD declarations, if any.
    080       *
    081       * <p>This method is empty.</p>
    082       *
    083       * @param name The document type name.
    084       * @param publicId The declared public identifier for the
    085       *        external DTD subset, or null if none was declared.
    086       * @param systemId The declared system identifier for the
    087       *        external DTD subset, or null if none was declared.
    088       * @exception org.xml.sax.SAXException The application may raise an
    089       *            exception.
    090       * @see #endDTD()
    091       * @see #startEntity(String)
    092       */
    093      public void startDTD(final String name, final String publicId,
    094                           final String systemId) throws SAXException {
    095        this.inDTD = true;
    096      }
    097
    098      /**
    099       * Report the end of DTD declarations.
    100       *
    101       * <p>This method is empty.</p>
    102       *
    103       * @exception org.xml.sax.SAXException The application may raise an exception.
    104       */
    105      public void endDTD()
    106          throws SAXException {
    107        this.inDTD = false;
    108      }
    109
    110      /**
    111       * Report the beginning of some internal and external XML entities.
    112       *
    113       * <p>This method is empty.</p>
    114       *
    115       * @param name The name of the entity.  If it is a parameter
    116       *        entity, the name will begin with '%', and if it is the
    117       *        external DTD subset, it will be "[dtd]".
    118       * @exception org.xml.sax.SAXException The application may raise an exception.
    119       * @see #endEntity(String)
    120       * @see org.xml.sax.ext.DeclHandler#internalEntityDecl
    121       * @see org.xml.sax.ext.DeclHandler#externalEntityDecl
    122       */
    123      public void startEntity(final String name)
    124          throws SAXException {
    125        // do nothing
    126      }
    127
    128      /**
    129       * Report the end of an entity.
    130       *
    131       * <p>This method is empty.</p>
    132       *
    133       * @param name The name of the entity that is ending.
    134       * @exception org.xml.sax.SAXException The application may raise an exception.
    135       * @see #startEntity(String)
    136       */
    137      public void endEntity(final String name) throws SAXException {
    138        // do nothing
    139      }
    140
    141      /**
    142       * Report the start of a CDATA section.
    143       *
    144       * <p>This method is empty.</p>
    145       *
    146       * @exception org.xml.sax.SAXException The application may raise an exception.
    147       * @see #endCDATA()
    148       */
    149      public void startCDATA() throws SAXException {
    150        // do nothing
    151      }
    152
    153      /**
    154       * Report the end of a CDATA section.
    155       *
    156       * <p>This method is empty.</p>
    157       *
    158       * @exception org.xml.sax.SAXException The application may raise an exception.
    159       * @see #startCDATA()
    160       */
    161      public void endCDATA() throws SAXException {
    162        // do nothing
    163      }
    164
    165      /**
    166       * Report an XML comment anywhere in the document.
    167       *
    168       * <p>This callback will be used for comments inside or outside the
    169       * document element, including comments in the external DTD
    170       * subset (if read).  Comments in the DTD must be properly
    171       * nested inside start/endDTD and start/endEntity events (if
    172       * used).</p>
    173       *
    174       * @param ch An array holding the characters in the comment.
    175       * @param start The starting position in the array.
    176       * @param length The number of characters to use from the array.
    177       * @exception org.xml.sax.SAXException The application may raise an exception.
    178       */
    179      public void comment(final char[] ch, final int start, final int length) throws SAXException {
    180        if (!this.inDTD) {
    181            this.comment.add(new String(ch, start, length));
    182        }
    183      }
    184
    185      /**
    186       * Returns all collected comments as string array.
    187       * @return the array containing all comments.
    188       */
    189      public String[] getComments() {
    190        if (this.comment.isEmpty()) {
    191          return null;
    192        }
    193        return (String[]) this.comment.toArray(new String[this.comment.size()]);
    194      }
    195
    196      /**
    197       * Clears all comments.
    198       */
    199      public void clearComments() {
    200        this.comment.clear();
    201      }
    202    }