1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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 }