1
2
3
4
5
6
7
8
9
10
11 package org.astrogrid.xmlutils;
12
13 import java.io.Reader;
14 import org.xml.sax.SAXNotRecognizedException;
15 import org.xml.sax.SAXException;
16
17 import java.util.Map;
18
19 /***
20 * <p>Interface class for syntactic and semantic validation of XML
21 * input documents.
22 *
23 * <p>Intended to provide a generic interface for which particular
24 * implementations (Xerces-based, custom etc) can be supplied
25 * as required.
26 *
27 * <p>See Validate.java for a command-line harness.
28 *
29 * <p><strong>Usage example with namespace map:</strong>
30 * <pre>
31 * // Required includes
32 * //
33 * import java.util.Map;
34 * import java.util.TreeMap;
35 * import org.astrogrid.xmlutils.XmlValidatorIfc;
36 * import org.astrogrid.xmlutils.XmlValidatorXercesImpl;
37 *
38 * // Usage snippet
39 * //
40 * XmlValidatorIfc validator = new XmlValidatorXercesImpl();
41 * validator.setFeature("UseNamespaces",true);
42 *
43 * Map namespaceMap = new TreeMap();
44 * namespaceMap.put(
45 * "http://www.astrogrid.org/namespace/AceInput-1_0",
46 * "http://astrogrid.ast.cam.ac.uk/namespace/AceInput-1_0.xsd"
47 * );
48 * namespaceMap.put(
49 * "http://www.astrogrid.org/namespace/AceInput",
50 * "http://astrogrid.ast.cam.ac.uk/namespace/AceInput.xsd"
51 * );
52 * namespaceMap.put(
53 * "http://www.astrogrid.org/namespace/SExtractor_2_2_2",
54 * "http://astrogrid.ast.cam.ac.uk/namespace/SExtractor_2_2_2.xsd"
55 * );
56 *
57 * validator.validate("blah.xml",namespaceMap);
58 * </pre>
59 *
60 * @see org.astrogrid.xmlutils.XmlValidatorXercesImpl
61 * @see org.astrogrid.xmlutils.Validate
62 *
63 * @author Kona Andrews,
64 * <a href="mailto:kea@ast.cam.ac.uk">kea@ast.cam.ac.uk</a>
65 * @version 1.0
66 *
67 *
68 * (c) Copyright Astrogrid 2002; all rights reserved.
69 * See http://www.astrogrid.org/code_licence.html for terms of usage.
70 */
71 public interface XmlValidatorIfc
72 {
73 /***
74 * Syntactically and semantically validates an input XML file
75 * against its schema(s), the location of which must be specified
76 * in the <tt>xsi:schemaLocation</tt> attribute of the toplevel
77 * document element.
78 *
79 * @param reader A (pre-initialised) reader for the input XML.
80 *
81 * @throws org.xml.sax.SAXException if input document is invalid.
82 */
83 public void validate(Reader reader) throws SAXException;
84
85
86 /***
87 * Syntactically and semantically validates an input XML file
88 * against its schema(s), the location of which must be specified
89 * in the supplied Map matching namespaces to schema locations.
90 *
91 * @param reader A (pre-initialised) reader for the input XML.
92 * @param namespaceMap A Map type containing string:string pairs,
93 * the key being a namespace URI, the value being the location of
94 * the schema for that namespace.
95 *
96 * @throws org.xml.sax.SAXException if input document is invalid.
97 */
98 public void validate(Reader reader, Map namespaceMap) throws SAXException;
99
100
101 /***
102 * Syntactically and semantically validates an input XML file
103 * against its schema(s), the location of which must be specified
104 * in the <tt>xsi:schemaLocation</tt> attribute of the toplevel
105 * document element.
106 *
107 * @param systemResource The filename of the input XML.
108 *
109 * @throws org.xml.sax.SAXException if input document is invalid.
110 */
111 public void validate(String fileName) throws SAXException;
112
113 /***
114 * Syntactically and semantically validates an input XML file
115 * against its schema, the location of which must be specified
116 * in the supplied Map matching namespaces to schema locations.
117 *
118 * @param systemResource The specified system resource from which to
119 * read the input XML (e.g. a local filename).
120 *
121 * @param namespaceMap A Map type containing string:string pairs,
122 * the key being a namespace URI, the value being the location of
123 * the schema for that namespace.
124 *
125 * @throws org.xml.sax.SAXException if input document is invalid.
126 */
127 public void validate(String fileName, Map namespaceMap) throws SAXException;
128
129
130 /***
131 * Allows named features to be switched on or off in the underlying
132 * implementation class (supported feature-set may vary from
133 * implementation to implementation).
134 *
135 * @param feature A string identifying a feature by name.
136 * @param value The boolean value to which the named feature
137 * should be set.
138 *
139 * @throws org.xml.sax.SAXNotRecognizedException if the named
140 * feature is not recognised.
141 */
142 public void setFeature(String feature, boolean value)
143 throws org.xml.sax.SAXNotRecognizedException;
144
145
146 /***
147 * Allows named features to be interrogated for their current value in
148 * in the underlying implementation class (supported feature-set may
149 * vary from implementation to implementation).
150 *
151 * @param feature A string identifying a feature by name.
152 *
153 * @return The current boolean value of the named feature.
154 *
155 * @throws org.xml.sax.SAXNotRecognizedException if the named
156 * feature is not recognised.
157 */
158 public boolean getFeature(String feature)
159 throws org.xml.sax.SAXNotRecognizedException;
160 }
161