001 /* $Id: DigesterLoader.java 992060 2010-09-02 19:09:47Z simonetripodi $
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one or more
004 * contributor license agreements. See the NOTICE file distributed with
005 * this work for additional information regarding copyright ownership.
006 * The ASF licenses this file to You under the Apache License, Version 2.0
007 * (the "License"); you may not use this file except in compliance with
008 * the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019
020 package org.apache.commons.digester.xmlrules;
021
022
023 import java.io.IOException;
024 import java.io.InputStream;
025 import java.io.Reader;
026 import java.net.URL;
027
028 import org.apache.commons.digester.Digester;
029 import org.apache.commons.digester.RuleSet;
030
031 import org.xml.sax.SAXException;
032 import org.xml.sax.InputSource;
033
034
035 /**
036 * This class manages the creation of Digester instances from XML digester
037 * rules files.
038 *
039 * @since 1.2
040 */
041
042 public class DigesterLoader {
043
044 /**
045 * Creates a new digester and initializes it from the specified InputSource
046 * @param rulesSource load the xml rules from this InputSource
047 * @return a new Digester initialized with the rules
048 */
049 public static Digester createDigester(InputSource rulesSource) {
050 RuleSet ruleSet = new FromXmlRuleSet(rulesSource);
051 Digester digester = new Digester();
052 digester.addRuleSet(ruleSet);
053 return digester;
054 }
055
056 /**
057 * Creates a new digester and initializes it from the specified InputSource.
058 * This constructor allows the digester to be used to load the rules to be specified.
059 * This allows properties to be configured on the Digester instance before it is used.
060 *
061 * @param rulesSource load the xml rules from this InputSource
062 * @param rulesDigester digester to load the specified XML file.
063 * @return a new Digester initialized with the rules
064 */
065 public static Digester createDigester(InputSource rulesSource, Digester rulesDigester) {
066 RuleSet ruleSet = new FromXmlRuleSet(rulesSource, rulesDigester);
067 Digester digester = new Digester();
068 digester.addRuleSet(ruleSet);
069 return digester;
070 }
071
072 /**
073 * Creates a new digester and initializes it from the specified XML file
074 * @param rulesXml URL to the XML file defining the digester rules
075 * @return a new Digester initialized with the rules
076 */
077 public static Digester createDigester(URL rulesXml) {
078 RuleSet ruleSet = new FromXmlRuleSet(rulesXml);
079 Digester digester = new Digester();
080 digester.addRuleSet(ruleSet);
081 return digester;
082 }
083
084 /**
085 * Creates a new digester and initializes it from the specified XML file.
086 * This constructor allows specifing a rulesDigester to do the XML file
087 * loading; thus no matter the XML files is packed into a jar, a war, or a
088 * ear, the rulesDigester can always find the XML files with properly set
089 * ClassLoader.
090 *
091 * @param rulesXml URL to the XML file defining the digester rules
092 * @param rulesDigester digester to load the specified XML file.
093 * @return a new Digester initialized with the rules
094 */
095 public static Digester createDigester(URL rulesXml, Digester rulesDigester) {
096 RuleSet ruleSet = new FromXmlRuleSet(rulesXml, rulesDigester);
097 Digester digester = new Digester();
098 digester.addRuleSet(ruleSet);
099 return digester;
100 }
101
102 /**
103 * Given the digester rules XML file, a class loader, and an XML input file,
104 * this method parses the input file into Java objects. The class loader
105 * is used by the digester to create the Java objects.
106 * @param digesterRules URL to the XML document defining the digester rules
107 * @param classLoader the ClassLoader to register with the digester
108 * @param fileURL URL to the XML file to parse into Java objects
109 * @return an Object which is the root of the network of Java objects
110 * created by digesting fileURL
111 */
112 public static Object load(URL digesterRules, ClassLoader classLoader,
113 URL fileURL) throws IOException, SAXException, DigesterLoadingException {
114 return load(digesterRules, classLoader, fileURL.openStream());
115 }
116
117 /**
118 * Given the digester rules XML file, a class loader, and an input stream,
119 * this method parses the input into Java objects. The class loader
120 * is used by the digester to create the Java objects.
121 * @param digesterRules URL to the XML document defining the digester rules
122 * @param classLoader the ClassLoader to register with the digester
123 * @param input InputStream over the XML file to parse into Java objects
124 * @return an Object which is the root of the network of Java objects
125 * created by digesting fileURL
126 */
127 public static Object load(URL digesterRules, ClassLoader classLoader,
128 InputStream input) throws IOException, SAXException, DigesterLoadingException {
129 Digester digester = createDigester(digesterRules);
130 digester.setClassLoader(classLoader);
131 try {
132 return digester.parse(input);
133 } catch (XmlLoadException ex) {
134 // This is a runtime exception that can be thrown by
135 // FromXmlRuleSet#addRuleInstances, which is called by the Digester
136 // before it parses the file.
137 throw new DigesterLoadingException(ex.getMessage(), ex);
138 }
139 }
140
141 /**
142 * Given the digester rules XML file, a class loader, and an input stream,
143 * this method parses the input into Java objects. The class loader
144 * is used by the digester to create the Java objects.
145 * @param digesterRules URL to the XML document defining the digester rules
146 * @param classLoader the ClassLoader to register with the digester
147 * @param reader Reader over the XML file to parse into Java objects
148 * @return an Object which is the root of the network of Java objects
149 * created by digesting fileURL
150 */
151 public static Object load(
152 URL digesterRules,
153 ClassLoader classLoader,
154 Reader reader)
155 throws
156 IOException,
157 SAXException,
158 DigesterLoadingException {
159 Digester digester = createDigester(digesterRules);
160 digester.setClassLoader(classLoader);
161 try {
162 return digester.parse(reader);
163 } catch (XmlLoadException ex) {
164 // This is a runtime exception that can be thrown by
165 // FromXmlRuleSet#addRuleInstances, which is called by the Digester
166 // before it parses the file.
167 throw new DigesterLoadingException(ex.getMessage(), ex);
168 }
169 }
170
171
172 /**
173 * Given the digester rules XML file, a class loader, and an XML input file,
174 * this method parses the input file into Java objects. The class loader
175 * is used by the digester to create the Java objects.
176 * @param digesterRules URL to the XML document defining the digester rules
177 * @param classLoader the ClassLoader to register with the digester
178 * @param fileURL URL to the XML file to parse into Java objects
179 * @param rootObject an Object to push onto the digester's stack, prior
180 * to parsing the input
181 * @return an Object which is the root of the network of Java objects.
182 * Usually, this will be the same object as rootObject
183 * created by digesting fileURL
184 */
185 public static Object load(URL digesterRules, ClassLoader classLoader,
186 URL fileURL, Object rootObject) throws IOException, SAXException,
187 DigesterLoadingException {
188 return load(digesterRules, classLoader, fileURL.openStream(), rootObject);
189 }
190
191 /**
192 * Given the digester rules XML file, a class loader, and an input stream,
193 * this method parses the input into Java objects. The class loader
194 * is used by the digester to create the Java objects.
195 * @param digesterRules URL to the XML document defining the digester rules
196 * @param classLoader the ClassLoader to register with the digester
197 * @param input InputStream over the XML file to parse into Java objects
198 * @param rootObject an Object to push onto the digester's stack, prior
199 * to parsing the input
200 * @return an Object which is the root of the network of Java objects
201 * created by digesting fileURL
202 */
203 public static Object load(URL digesterRules, ClassLoader classLoader,
204 InputStream input, Object rootObject) throws IOException, SAXException,
205 DigesterLoadingException {
206 Digester digester = createDigester(digesterRules);
207 digester.setClassLoader(classLoader);
208 digester.push(rootObject);
209 try {
210 return digester.parse(input);
211 } catch (XmlLoadException ex) {
212 // This is a runtime exception that can be thrown by
213 // FromXmlRuleSet#addRuleInstances, which is called by the Digester
214 // before it parses the file.
215 throw new DigesterLoadingException(ex.getMessage(), ex);
216 }
217 }
218
219 /**
220 * Given the digester rules XML file, a class loader, and an input stream,
221 * this method parses the input into Java objects. The class loader
222 * is used by the digester to create the Java objects.
223 * @param digesterRules URL to the XML document defining the digester rules
224 * @param classLoader the ClassLoader to register with the digester
225 * @param input Reader over the XML file to parse into Java objects
226 * @param rootObject an Object to push onto the digester's stack, prior
227 * to parsing the input
228 * @return an Object which is the root of the network of Java objects
229 * created by digesting fileURL
230 */
231 public static Object load(
232 URL digesterRules,
233 ClassLoader classLoader,
234 Reader input,
235 Object rootObject)
236 throws
237 IOException,
238 SAXException,
239 DigesterLoadingException {
240 Digester digester = createDigester(digesterRules);
241 digester.setClassLoader(classLoader);
242 digester.push(rootObject);
243 try {
244 return digester.parse(input);
245 } catch (XmlLoadException ex) {
246 // This is a runtime exception that can be thrown by
247 // FromXmlRuleSet#addRuleInstances, which is called by the Digester
248 // before it parses the file.
249 throw new DigesterLoadingException(ex.getMessage(), ex);
250 }
251 }
252 }