1 /*
2 * Copyright [2007] [University Corporation for Advanced Internet Development, Inc.]
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.opensaml.xml.parse;
18
19 import java.io.InputStream;
20 import java.io.Reader;
21
22 import javax.xml.parsers.DocumentBuilder;
23 import javax.xml.validation.Schema;
24
25 import org.w3c.dom.Document;
26
27 /**
28 * A pool of XML parsers.
29 */
30 public interface ParserPool {
31
32 /**
33 * Gets a builder from the pool.
34 *
35 * @return a builder from the pool
36 *
37 * @throws XMLParserException thrown if the document builder factory is misconfigured
38 */
39 public DocumentBuilder getBuilder() throws XMLParserException;
40
41 /**
42 * Returns a builder to the pool.
43 *
44 * @param builder the builder to return
45 */
46 public void returnBuilder(DocumentBuilder builder);
47
48 /**
49 * Convience method for creating a new document with a pooled builder.
50 *
51 * @return created document
52 *
53 * @throws XMLParserException thrown if there is a problem retrieving a builder
54 */
55 public Document newDocument() throws XMLParserException;
56
57 /**
58 * Convience method for parsing an XML file using a pooled builder.
59 *
60 * @param input XML to parse
61 *
62 * @return parsed document
63 *
64 * @throws XMLParserException thrown if there is a problem retrieving a builder, the input stream can not be read,
65 * or the XML was invalid
66 */
67 public Document parse(InputStream input) throws XMLParserException;
68
69 /**
70 * Convience method for parsing an XML file using a pooled builder.
71 *
72 * @param input XML to parse
73 *
74 * @return parsed document
75 *
76 * @throws XMLParserException thrown if there is a problem retrieving a builder, the input stream can not be read,
77 * or the XML was invalid
78 */
79 public Document parse(Reader input) throws XMLParserException;
80
81 /**
82 * Gets the schema builders use to validate.
83 *
84 * @return the schema builders use to validate
85 */
86 public Schema getSchema();
87
88 /**
89 * Sets the schema builders use to validate.
90 *
91 * @param newSchema the schema builders use to validate
92 */
93 public void setSchema(Schema newSchema);
94
95 }