001    /* DocumentParser.java -- A parser for HTML documents.
002       Copyright (C) 2005 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.swing.text.html.parser;
040    
041    import javax.swing.text.html.parser.Parser;
042    
043    import java.io.IOException;
044    import java.io.Reader;
045    
046    import javax.swing.text.BadLocationException;
047    import javax.swing.text.SimpleAttributeSet;
048    import javax.swing.text.html.HTMLEditorKit;
049    
050    /**
051     * <p>A simple error-tolerant HTML parser that uses a DTD document
052     * to access data on the possible tokens, arguments and syntax.</p>
053     * <p> The parser reads an HTML content from a Reader and calls various
054     * notifying methods (which should be overridden in a subclass)
055     * when tags or data are encountered.</p>
056     * <p>Some HTML elements need no opening or closing tags. The
057     * task of this parser is to invoke the tag handling methods also when
058     * the tags are not explicitly specified and must be supposed using
059     * information, stored in the DTD.
060     * For  example, parsing the document
061     * <p>&lt;table&gt;&lt;tr&gt;&lt;td&gt;a&lt;td&gt;b&lt;td&gt;c&lt;/tr&gt; <br>
062     * will invoke exactly the handling methods exactly in the same order
063     * (and with the same parameters) as if parsing the document: <br>
064     * <em>&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;table&gt;&lt;
065     * tbody&gt;</em>&lt;tr&gt;&lt;td&gt;a<em>&lt;/td&gt;</em>&lt;td&gt;b<em>
066     * &lt;/td&gt;</em>&lt;td&gt;c<em>&lt;/td&gt;&lt;/tr&gt;</em>&lt;
067     * <em>/tbody&gt;&lt;/table&gt;&lt;/body&gt;&lt;/html&gt;</em></p>
068     * (supposed tags are given in italics). The parser also supports
069     * obsolete elements of HTML syntax.<p>
070     * </p>
071     * In this implementation, DocumentParser is directly derived from its
072     * ancestor without changes of functionality.
073     * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
074     */
075    public class DocumentParser
076      extends Parser
077      implements DTDConstants
078    {
079      /**
080       * The enclosed working parser class.
081       */
082      private class gnuParser
083        extends gnu.javax.swing.text.html.parser.support.Parser
084      {
085        private gnuParser(DTD d)
086        {
087          super(d);
088        }
089    
090        protected final void handleComment(char[] comment)
091        {
092          parser.handleComment(comment);
093          callBack.handleComment(comment, hTag.where.startPosition);
094        }
095    
096        protected final void handleEmptyTag(TagElement tag)
097          throws javax.swing.text.ChangedCharSetException
098        {
099          parser.handleEmptyTag(tag);
100          callBack.handleSimpleTag(tag.getHTMLTag(), getAttributes(),
101                                   hTag.where.startPosition
102                                  );
103        }
104    
105        protected final void handleEndTag(TagElement tag)
106        {
107          parser.handleEndTag(tag);
108          callBack.handleEndTag(tag.getHTMLTag(), hTag.where.startPosition);
109        }
110    
111        protected final void handleError(int line, String message)
112        {
113          parser.handleError(line, message);
114          callBack.handleError(message, hTag.where.startPosition);
115        }
116    
117        protected final void handleStartTag(TagElement tag)
118        {
119          parser.handleStartTag(tag);
120          SimpleAttributeSet attributes = gnu.getAttributes();
121    
122          if (tag.fictional())
123            attributes.addAttribute(HTMLEditorKit.ParserCallback.IMPLIED,
124                                    Boolean.TRUE
125                                   );
126    
127          callBack.handleStartTag(tag.getHTMLTag(), attributes,
128                                  hTag.where.startPosition
129                                 );
130        }
131    
132        protected final void handleText(char[] text)
133        {
134          parser.handleText(text);
135          callBack.handleText(text, hTag.where.startPosition);
136        }
137    
138        DTD getDTD()
139        {
140          return dtd;
141        }
142      }
143    
144      /**
145       * This field is used to access the identically named
146       * methods of the outer class.
147       * This is package-private to avoid an accessor method.
148       */
149      DocumentParser parser = this;
150    
151      /**
152       * The callback.
153       * This is package-private to avoid an accessor method.
154       */
155      HTMLEditorKit.ParserCallback callBack;
156    
157      /**
158       * The reference to the working class of HTML parser that is
159       * actually used to parse the document.
160       * This is package-private to avoid an accessor method.
161       */
162      gnuParser gnu;
163    
164      /**
165       * Creates a new parser that uses the given DTD to access data on the
166       * possible tokens, arguments and syntax. There is no single - step way
167       * to get a default DTD; you must either refer to the implementation -
168       * specific packages, write your own DTD or obtain the working instance
169       * of parser in other way, for example, by calling
170       * {@link javax.swing.text.html.HTMLEditorKit#getParser()}.
171       *
172       * @param a_dtd a DTD to use.
173       */
174      public DocumentParser(DTD a_dtd)
175      {
176        super(a_dtd);
177        gnu = new gnuParser(a_dtd);
178      }
179    
180      /**
181       * Parses the HTML document, calling methods of the provided
182       * callback. This method must be multithread - safe.
183       * @param reader The reader to read the HTML document from
184       * @param aCallback The callback that is notifyed about the presence
185       * of HTML elements in the document.
186       * @param ignoreCharSet If thrue, any charset changes during parsing
187       * are ignored.
188       * @throws java.io.IOException
189       */
190      public void parse(Reader reader, HTMLEditorKit.ParserCallback aCallback,
191                        boolean ignoreCharSet
192                       )
193                 throws IOException
194      {
195        callBack = aCallback;
196        gnu.parse(reader);
197    
198        callBack.handleEndOfLineString(gnu.getEndOfLineSequence());
199        try
200          {
201            callBack.flush();
202          }
203        catch (BadLocationException ex)
204          {
205            // Convert this into the supported type of exception.
206            throw new IOException(ex.getMessage());
207          }
208      }
209    
210      /**
211       * Handle HTML comment. The default method returns without action.
212       * @param comment the comment being handled
213       */
214      protected void handleComment(char[] comment)
215      {
216        // This default implementation does nothing.
217      }
218    
219      /**
220       * Handle the tag with no content, like &lt;br&gt;. The method is
221       * called for the elements that, in accordance with the current DTD,
222       * has an empty content.
223       * @param tag the tag being handled.
224       * @throws javax.swing.text.ChangedCharSetException
225       */
226      protected void handleEmptyTag(TagElement tag)
227                             throws javax.swing.text.ChangedCharSetException
228      {
229        // This default implementation does nothing.
230      }
231    
232      /**
233       * The method is called when the HTML closing tag ((like &lt;/table&gt;)
234       * is found or if the parser concludes that the one should be present
235       * in the current position.
236       * @param tag The tag being handled
237       */
238      protected void handleEndTag(TagElement tag)
239      {
240        // This default implementation does nothing.
241      }
242    
243      /* Handle error that has occured in the given line. */
244      protected void handleError(int line, String message)
245      {
246        // This default implementation does nothing.
247      }
248    
249      /**
250       * The method is called when the HTML opening tag ((like &lt;table&gt;)
251       * is found or if the parser concludes that the one should be present
252       * in the current position.
253       * @param tag The tag being handled
254       */
255      protected void handleStartTag(TagElement tag)
256      {
257        // This default implementation does nothing.
258      }
259    
260      /**
261       * Handle the text section.
262       * @param text a section text.
263       */
264      protected void handleText(char[] text)
265      {
266        // This default implementation does nothing.
267      }
268    }