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 }