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 }