001    /* $Id: DigesterLoader.java 471661 2006-11-06 08:09:25Z skitching $
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    }