    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    }