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 }
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags