View Javadoc

1   /*
2    * Copyright (C) 2004-2006 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 program is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU General Public License as published by
9    * the Free Software Foundation; either version 2 of the License, or
10   * (at your option) any later version.
11   *
12   * This program 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
15   * GNU General Public License for more details.
16   *
17   * You should have received a copy of the GNU General Public License
18   * along with this program; if not, visit
19   * http://www.gnu.org/licenses/gpl.html or write to the Free Software
20   * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
21   */
22  package de.fu_berlin.ties.filter;
23  
24  import java.io.File;
25  import java.io.IOException;
26  
27  import org.dom4j.Document;
28  import org.dom4j.Element;
29  
30  import de.fu_berlin.ties.ProcessingException;
31  
32  /***
33   * Interface for classes that decide whether or not to accept elements in XML
34   * documents. This interface cannot extend the {@link org.dom4j.NodeFilter}
35   * interface because the {@link #matches(Element)}method is allowed to throw an
36   * {@link de.fu_berlin.ties.ProcessingException}.
37   * 
38   * @author Christian Siefkes
39   * @version $Revision: 1.8 $, $Date: 2006/10/21 16:04:19 $, $Author: siefkes $
40   */
41  public interface ElementFilter {
42  
43      /***
44       * Resets the filter to start processing a new document. This method must be
45       * called for each document to be procesed by this filter prior to calling
46       * {@link #matches(Element)}or {@link #prefers(Element)}on elements of
47       * this document.
48       * 
49       * @param document the document to process
50       * @param filename the file name of the document
51       * @throws ProcessingException if an error occurs while starting to
52       * process the document
53       * @throws IOException if an I/O error occurs
54       */
55      void init(final Document document, final File filename)
56      throws ProcessingException, IOException;
57  
58      /***
59       * Whether the filter would avoid to filter an element, if possible. Any
60       * filter must be able to filter all elements, but some filters like to
61       * avoid elements of a certain type, for example.
62       * 
63       * @param element the element to consider
64       * @return <code>true</code> if this would prefer to avoid filtering the
65       * element; <code>false</code> otherwise
66       */
67      boolean avoids(final Element element);
68  
69      /***
70       * Decides whether an element is accepted by this filter.
71       * 
72       * @param element the element to test
73       * @return <code>true</code> if this filter accepts the element;
74       * <code>false</code> otherwise
75       * @throws ProcessingException if an error occurs during filtering
76       */
77      boolean matches(final Element element) throws ProcessingException;
78  
79      /***
80       * Whether the filter would prefer to filter an element. Any filter must be
81       * able to filter all elements, but some filters prefer elements of a
82       * certain type, for example.
83       * 
84       * @param element the element to consider
85       * @return <code>true</code> if this would prefer to filter the element;
86       * <code>false</code> otherwise
87       */
88      boolean prefers(final Element element);
89  
90  }