1 package org.apache.commons.digester3.plugins.strategies; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import java.util.Properties; 23 24 import org.apache.commons.digester3.Digester; 25 import org.apache.commons.digester3.plugins.PluginException; 26 import org.apache.commons.digester3.plugins.RuleFinder; 27 import org.apache.commons.digester3.plugins.RuleLoader; 28 29 /** 30 * A rule-finding algorithm which expects the user to specify whether "automatic property setting" is desired. If this 31 * class discovers that this is in fact the case for a declaration, then a RuleLoader is returned which, when invoked, 32 * adds a single SetPropertiesRule instance to the digester. 33 * <p> 34 * This allows ordinary JavaBean classes to be used as plugins, and have xml attributes be mapped to bean properties of 35 * the same name, without any custom plugin rules being created for them. 36 * <p> 37 * This RuleFinder is typically used as the <i>last</i> RuleFinder, so that automatic property setting only occurs if 38 * there is no other source of custom rules available. 39 * 40 * @since 1.6 41 */ 42 public class FinderSetProperties 43 extends RuleFinder 44 { 45 46 private static final String DFLT_PROPS_ATTR = "setprops"; 47 48 private static final String DFLT_FALSEVAL = "false"; 49 50 private final String propsAttr; 51 52 private final String falseval; 53 54 /** See {@link #findLoader}. */ 55 public FinderSetProperties() 56 { 57 this( DFLT_PROPS_ATTR, DFLT_FALSEVAL ); 58 } 59 60 /** 61 * Create a rule-finder which will arrange for a SetPropertiesRule to be defined for each instance of a plugin, so 62 * that xml attributes map to bean properties. 63 * <p> 64 * Param falseval will commonly be the string "false" for config files written in English. 65 * 66 * @param propsAttr must be non-null. 67 * @param falseval must be non-null. 68 */ 69 public FinderSetProperties( String propsAttr, String falseval ) 70 { 71 this.propsAttr = propsAttr; 72 this.falseval = falseval; 73 } 74 75 /** 76 * Returns a RuleLoader <i>unless</i> the properties contain an entry with the name matching constructor param 77 * propsAttr, and the value matching what is in falseval. 78 * <p> 79 * If no custom source of rules for a plugin is found, then the user almost always wants xml attributes to map to 80 * java bean properties, so this is the default behaviour unless the user explicitly indicates that they do 81 * <i>not</i> want a SetPropertiesRule to be provided for the plugged-in class. 82 * <p> 83 * The returned object (when non-null) will add a SetPropertiesRule to the digester whenever its addRules method is 84 * invoked. 85 * 86 * @param d The digester instance where locating plugin classes 87 * @param pluginClass The plugin Java class 88 * @param p The properties object that holds any xml attributes the user may have specified on the plugin 89 * declaration in order to indicate how to locate the plugin rules. 90 * @return a source of digester rules for the specified plugin class. 91 * @throws PluginException if the algorithm finds a source of rules, but there is something invalid 92 * about that source. 93 */ 94 @Override 95 public RuleLoader findLoader( Digester d, Class<?> pluginClass, Properties p ) 96 throws PluginException 97 { 98 String state = p.getProperty( propsAttr ); 99 if ( ( state != null ) && state.equals( falseval ) ) 100 { 101 // user has explicitly disabled automatic setting of properties. 102 // this is not expected to be common, but allowed. 103 return null; 104 } 105 106 return new LoaderSetProperties(); 107 } 108 109 }