1  // HTMLParser Library $Name: v1_6_20060319 $ - A java-based parser for HTML
 2  // http://sourceforge.org/projects/htmlparser
 3  // Copyright (C) 2003 Derrick Oswald
 4  //
 5  // Revision Control Information
 6  //
 7  // $Source: /cvsroot/htmlparser/htmlparser/src/org/htmlparser/NodeFactory.java,v $
 8  // $Author: derrickoswald $
 9  // $Date: 2005/05/15 11:49:03 $
10  // $Revision: 1.3 $
11  //
12  // This library is free software; you can redistribute it and/or
13  // modify it under the terms of the GNU Lesser General Public
14  // License as published by the Free Software Foundation; either
15  // version 2.1 of the License, or (at your option) any later version.
16  //
17  // This library is distributed in the hope that it will be useful,
18  // but WITHOUT ANY WARRANTY; without even the implied warranty of
19  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20  // Lesser General Public License for more details.
21  //
22  // You should have received a copy of the GNU Lesser General Public
23  // License along with this library; if not, write to the Free Software
24  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25  //
26  
27  package org.htmlparser;
28  
29  import java.util.Vector;
30  
31  import org.htmlparser.lexer.Page;
32  import org.htmlparser.util.ParserException;
33  
34  /**
35   * This interface defines the methods needed to create new nodes.
36   * <p>The factory is used when lexing to generate the nodes passed
37   * back to the caller. By implementing this interface, and setting
38   * that concrete object as the node factory for the
39   * {@link org.htmlparser.lexer.Lexer#setNodeFactory lexer} (perhaps via the
40   * {@link Parser#setNodeFactory parser}), the way that nodes are generated
41   * can be customized.</p>
42   * <p>In general, replacing the factory with a custom factory is not required
43   * because of the flexibility of the {@link PrototypicalNodeFactory}.</p>
44   * <p>Creation of Text and Remark nodes is straight forward, because essentially
45   * they are just sequences of characters extracted from the page. Creation of a
46   * Tag node requires that the attributes from the tag be remembered as well.
47   * @see PrototypicalNodeFactory
48   */
49  public interface NodeFactory
50  {
51      /**
52       * Create a new text node.
53       * @param page The page the node is on.
54       * @param start The beginning position of the string.
55       * @param end The ending positiong of the string.
56       * @throws ParserException If there is a problem encountered
57       * when creating the node.
58       * @return A text node comprising the indicated characters from the page.
59       */
60      Text createStringNode (Page page, int start, int end)
61          throws
62              ParserException;
63  
64      /**
65       * Create a new remark node.
66       * @param page The page the node is on.
67       * @param start The beginning position of the remark.
68       * @param end The ending positiong of the remark.
69       * @throws ParserException If there is a problem encountered
70       * when creating the node.
71       * @return A remark node comprising the indicated characters from the page.
72       */
73      Remark createRemarkNode (Page page, int start, int end)
74          throws
75              ParserException;
76  
77      /**
78       * Create a new tag node.
79       * Note that the attributes vector contains at least one element,
80       * which is the tag name (standalone attribute) at position zero.
81       * This can be used to decide which type of node to create, or
82       * gate other processing that may be appropriate.
83       * @param page The page the node is on.
84       * @param start The beginning position of the tag.
85       * @param end The ending positiong of the tag.
86       * @param attributes The attributes contained in this tag.
87       * @throws ParserException If there is a problem encountered
88       * when creating the node.
89       * @return A tag node comprising the indicated characters from the page.
90       */
91      Tag createTagNode (Page page, int start, int end, Vector attributes)
92          throws
93              ParserException;
94  }