View Javadoc

1   /*
2    * Copyright (C) 2004 Christian Siefkes <christian@siefkes.net>.
3    * Development of this software is supported by the German Research Society,
4    * Berlin-Brandenburg Graduate School in Distributed Information Systems
5    * (DFG grant no. GRK 316).
6    *
7    * This library is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU Lesser General Public
9    * License as published by the Free Software Foundation; either
10   * version 2.1 of the License, or (at your option) any later version.
11   *
12   * This library is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15   * Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public
18   * License along with this library; if not, visit
19   * http://www.gnu.org/licenses/lgpl.html or write to the Free Software
20   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
21   */
22  package de.fu_berlin.ties.filter;
23  
24  import org.dom4j.Document;
25  import org.dom4j.Element;
26  
27  import de.fu_berlin.ties.ProcessingException;
28  
29  /***
30   * Interface for classes that decide whether or not to accept elements in XML
31   * documents. This interface cannot extend the {@link org.dom4j.NodeFilter}
32   * interface because the {@link #matches(Element)}method is allowed to throw an
33   * {@link de.fu_berlin.ties.ProcessingException}.
34   * 
35   * @author Christian Siefkes
36   * @version $Revision: 1.3 $, $Date: 2004/08/27 15:08:14 $, $Author: siefkes $
37   */
38  public interface ElementFilter {
39  
40      /***
41       * Resets the filter to start processing a new document. This method must be
42       * called for each document to be procesed by this filter prior to calling
43       * {@link #matches(Element)}or {@link #prefers(Element)}on elements of
44       * this document.
45       * 
46       * @param document the document to process
47       */
48      void init(final Document document);
49  
50      /***
51       * Whether the filter would avoid to filter an element, if possible. Any
52       * filter must be able to filter all elements, but some filters like to
53       * avoid elements of a certain type, for example.
54       * 
55       * @param element the element to consider
56       * @return <code>true</code> if this would prefer to avoid filtering the
57       * element; <code>false</code> otherwise
58       */
59      boolean avoids(final Element element);
60  
61      /***
62       * Decides whether an element is accepted by this filter.
63       * 
64       * @param element the element to test
65       * @return <code>true</code> if this filter accepts the element;
66       * <code>false</code> otherwise
67       * @throws ProcessingException if an error occurs during filtering
68       */
69      boolean matches(final Element element) throws ProcessingException;
70  
71      /***
72       * Whether the filter would prefer to filter an element. Any filter must be
73       * able to filter all elements, but some filters prefer elements of a
74       * certain type, for example.
75       * 
76       * @param element the element to consider
77       * @return <code>true</code> if this would prefer to filter the element;
78       * <code>false</code> otherwise
79       */
80      boolean prefers(final Element element);
81  
82  }