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 }