KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > digester > plugins > RuleFinder


1 /* $Id: RuleFinder.java 155412 2005-02-26 12:58:36Z dirkv $
2  *
3  * Copyright 2004 The Apache Software Foundation.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17  
18 package org.apache.commons.digester.plugins;
19
20 import java.util.Properties JavaDoc;
21 import org.apache.commons.digester.Digester;
22
23 /**
24  * Each concrete implementation of RuleFinder is an algorithm for
25  * locating a source of digester rules for a plugin. The algorithm may
26  * use info explicitly provided by the user as part of the plugin
27  * declaration, or not (in which case the concrete RuleFinder subclass
28  * typically has Dflt as part of its name).
29  * <p>
30  * Instances of this class can also be regarded as a Factory for RuleLoaders,
31  * except that an instance of a RuleLoader is only created if the particular
32  * finder algorithm can locate a suitable source of rules given the plugin
33  * class and associated properties.
34  * <p>
35  * This is an abstract class rather than an interface in order to make
36  * it possible to enhance this class in future without breaking binary
37  * compatibility; it is possible to add methods to an abstract class, but
38  * not to an interface.
39  *
40  * @since 1.6
41  */
42
43 public abstract class RuleFinder {
44
45     /**
46      * Apply the finder algorithm to attempt to locate a source of
47      * digester rules for the specified plugin class.
48      * <p>
49      * This method is invoked when a plugin is declared by the user, either
50      * via an explicit use of PluginDeclarationRule, or implicitly via an
51      * "inline declaration" where the declaration and use are simultaneous.
52      * <p>
53      * If dynamic rules for the specified plugin class are located, then
54      * the RuleFinder will return a RuleLoader object encapsulating those
55      * rules, and this object will be invoked each time the user actually
56      * requests an instance of the declared plugin class, to load the
57      * custom rules associated with that plugin instance.
58      * <p>
59      * If no dynamic rules can be found, null is returned. This is not an
60      * error; merely an indication that this particular algorithm found
61      * no matches.
62      * <p>
63      * The properties object holds any xml attributes the user may have
64      * specified on the plugin declaration in order to indicate how to locate
65      * the plugin rules.
66      * <p>
67      * @throws PluginConfigurationException if the algorithm finds a source
68      * of rules, but there is something invalid about that source.
69      */
70
71      public abstract RuleLoader findLoader(
72                         Digester d, Class JavaDoc pluginClass,
73                         Properties JavaDoc p) throws PluginException;
74 }
75
76
Popular Tags