Source for org.jfree.xml.CommentHandler

   1: /* ========================================================================
   2:  * JCommon : a free general purpose class library for the Java(tm) platform
   3:  * ========================================================================
   4:  *
   5:  * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
   6:  * 
   7:  * Project Info:  http://www.jfree.org/jcommon/index.html
   8:  *
   9:  * This library is free software; you can redistribute it and/or modify it 
  10:  * under the terms of the GNU Lesser General Public License as published by 
  11:  * the Free Software Foundation; either version 2.1 of the License, or 
  12:  * (at your option) any later version.
  13:  *
  14:  * This library is distributed in the hope that it will be useful, but 
  15:  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
  16:  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
  17:  * License for more details.
  18:  *
  19:  * You should have received a copy of the GNU Lesser General Public
  20:  * License along with this library; if not, write to the Free Software
  21:  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
  22:  * USA.  
  23:  *
  24:  * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
  25:  * in the United States and other countries.]
  26:  * 
  27:  * -------------------
  28:  * CommentHandler.java
  29:  * -------------------
  30:  * (C)opyright 2003-2005, by Thomas Morgner and Contributors.
  31:  *
  32:  * Original Author:  Thomas Morgner;
  33:  * Contributor(s):   David Gilbert (for Object Refinery Limited);
  34:  *
  35:  * $Id: CommentHandler.java,v 1.3 2005/10/18 13:25:44 mungady Exp $
  36:  *
  37:  * Changes
  38:  * -------------------------
  39:  * 20-Jul-2003 : Initial version
  40:  *
  41:  */
  42: 
  43: package org.jfree.xml;
  44: 
  45: import java.util.ArrayList;
  46: 
  47: import org.xml.sax.SAXException;
  48: import org.xml.sax.ext.LexicalHandler;
  49: 
  50: /**
  51:  * The comment handler is used to collect all XML comments from the
  52:  * SAX parser. The parser implementation must support comments to make
  53:  * this feature work.
  54:  *
  55:  * @author Thomas Morgner
  56:  */
  57: public class CommentHandler implements LexicalHandler {
  58:     
  59:   /** A constant marking a comment on the opening tag. */
  60:   public static final String OPEN_TAG_COMMENT = "parser.comment.open";
  61:   
  62:   /** A constant marking a comment on the closing tag. */
  63:   public static final String CLOSE_TAG_COMMENT = "parser.comment.close";
  64: 
  65:   /** A list containing all collected comments. */
  66:   private final ArrayList comment;
  67:   
  68:   /** a flag marking whether the SAX parser is currently working in the DTD. */
  69:   private boolean inDTD;
  70: 
  71:   /**
  72:    * DefaultConstructor.
  73:    */
  74:   public CommentHandler() {
  75:     this.comment = new ArrayList();
  76:   }
  77: 
  78:   /**
  79:    * Report the start of DTD declarations, if any.
  80:    *
  81:    * <p>This method is empty.</p>
  82:    *
  83:    * @param name The document type name.
  84:    * @param publicId The declared public identifier for the
  85:    *        external DTD subset, or null if none was declared.
  86:    * @param systemId The declared system identifier for the
  87:    *        external DTD subset, or null if none was declared.
  88:    * @exception org.xml.sax.SAXException The application may raise an
  89:    *            exception.
  90:    * @see #endDTD()
  91:    * @see #startEntity(String)
  92:    */
  93:   public void startDTD(final String name, final String publicId,
  94:                        final String systemId) throws SAXException {
  95:     this.inDTD = true;
  96:   }
  97: 
  98:   /**
  99:    * 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: }