001 /* $Id: RuleFinder.java 729120 2008-12-23 21:11:38Z rahul $ 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 package org.apache.commons.digester.plugins; 020 021 import java.util.Properties; 022 import org.apache.commons.digester.Digester; 023 024 /** 025 * Each concrete implementation of RuleFinder is an algorithm for 026 * locating a source of digester rules for a plugin. The algorithm may 027 * use info explicitly provided by the user as part of the plugin 028 * declaration, or not (in which case the concrete RuleFinder subclass 029 * typically has Dflt as part of its name). 030 * <p> 031 * Instances of this class can also be regarded as a Factory for RuleLoaders, 032 * except that an instance of a RuleLoader is only created if the particular 033 * finder algorithm can locate a suitable source of rules given the plugin 034 * class and associated properties. 035 * <p> 036 * This is an abstract class rather than an interface in order to make 037 * it possible to enhance this class in future without breaking binary 038 * compatibility; it is possible to add methods to an abstract class, but 039 * not to an interface. 040 * 041 * @since 1.6 042 */ 043 044 public abstract class RuleFinder { 045 046 /** 047 * Apply the finder algorithm to attempt to locate a source of 048 * digester rules for the specified plugin class. 049 * <p> 050 * This method is invoked when a plugin is declared by the user, either 051 * via an explicit use of PluginDeclarationRule, or implicitly via an 052 * "inline declaration" where the declaration and use are simultaneous. 053 * <p> 054 * If dynamic rules for the specified plugin class are located, then 055 * the RuleFinder will return a RuleLoader object encapsulating those 056 * rules, and this object will be invoked each time the user actually 057 * requests an instance of the declared plugin class, to load the 058 * custom rules associated with that plugin instance. 059 * <p> 060 * If no dynamic rules can be found, null is returned. This is not an 061 * error; merely an indication that this particular algorithm found 062 * no matches. 063 * <p> 064 * The properties object holds any xml attributes the user may have 065 * specified on the plugin declaration in order to indicate how to locate 066 * the plugin rules. 067 * <p> 068 * @throws PluginConfigurationException if the algorithm finds a source 069 * of rules, but there is something invalid about that source. 070 */ 071 072 public abstract RuleLoader findLoader( 073 Digester d, Class<?> pluginClass, 074 Properties p) throws PluginException; 075 } 076