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
020package org.apache.commons.digester.xmlrules;
021
022
023import java.io.IOException;
024import java.io.InputStream;
025import java.io.Reader;
026import java.net.URL;
027
028import org.apache.commons.digester.Digester;
029import org.apache.commons.digester.RuleSet;
030
031import org.xml.sax.SAXException;
032import 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
042public 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}