This package contains "rule-finding" strategy classes, and their associated "helper" loader classes.

Note that you do not need to understand or deal with any of the classes in this package in order to use the plugins functionality. If you wish to use plugins functionality in non-english languages and therefore want to change the attribute names used on plugin declaration tags ("id", "file", etc) then you will need some familiarity with this package. Otherwise, this package is only relevant to people really wishing to tweak plugins in unexpected ways. If this is the case, come and talk to us on the digester email lists as we would be interested in knowing about your requirements.

When the plugins module is being used and the input xml indicates that a specific plugin class is to be instantiated, that class may then wish to configure itself from the xml attributes on that tag or xml attributes and elements nested within that tag.

The question is: how is the digester going to figure out where the plugin keeps its custom rules which are to be applied to the xml within that plugin tag?

Well, the answer is that there is a list of "rule finding strategies", generally containing an instance of each of the Finder classes in this package in a specific order. The strategies provided here should satisfy just about everyone, but if they don't you can add extra strategies if desired.

A RuleFinder is essentially a "strategy" or "algorithm" for finding the dynamic rules associated with a plugin class. When a plugin declaration is encountered in the input xml, the PluginContext object is asked for the list of RuleFinder objects, then each RuleFinder instance in turn is passed the declaration parameters, and asked "are you able to locate custom parsing rules for this declaration?". When one can, it returns a RuleLoader instance which is remembered. When the input xml indicates that an instance of the declared plugin class is to be created, that RuleLoader is invoked to temporarily add the relevant custom rules to the Digester in order to map xml attributes/elements/etc into the instantiated plugin object. Once the end of the plugin tag is encountered, those temporary rules are removed. This repeats each time the input xml indicates that an instance of a plugin class is to be instantiated.

If the plugin is declared "inline", using the "plugin-class" attribute instead of using "plugin-id" to reference a previous declaration then the process is exactly the same, except that the RuleFinder objects don't have any user-provided attribute "hints" to tell them where the custom rules are.

The RuleFinder list is carefully ordered; classes which look at the user-provided data in the declaration come first, and classes which look in "well-known places" come later so that users can override default behaviour by providing the appropriate tags on the plugin declaration.

See the javadoc on the different Finder classes for information on what each does, and what attribute (if any) it looks for in the declaration.