package org.apache.commons.digester;

/**
 * Interface to enable objects created by the ObjectCreationRule
 * to add it's own rules for sub elements.
 * After the object has been created, the configureAdditionalRules() method of it is called. In this method, the object may register additional rules, that are processed when the parsing of the XML document is continued. Rules are not applied backwards.
 * 
 * This enables developers to create configurable child objects depending on what parent object is really instantiated.
 * For example, Valve usually has no child objects
 * . If you want to create childs, you have to pass all necessary configuration as attributes to the Valve. With SelfConfigureObjects, a specific implementation can add further rules. If for example FancyValve needs a FancyValveRessource and a FancyValveManager as child objects, you don't need to change the location where this Valve is configured to be created by the Digester, but instead you can simply implement the SelfConfigureObject interface and put the digester configuration code in your configreAdditionalRules method:
 * <pre>
 * public class FancyValve extends ValveBase implements Lifecycle, SelfConfigureObject {
 * 
 * 	// ...
 * 
 * 	public void configureAdditionalRules(Digester digester){
 *
 *              String pattern = digester.getMatch();
 * 
 *         		digester.addObjectCreate(pattern + "/FancyValveRessource",
 *                                  		null, // MUST be specified in the element
 *                                  		"className");
 *         		digester.addSetProperties(pattern + "/FancyValveRessource");
 *         		digester.addSetNext(pattern + "/FancyValveRessource",
 *                             	"setValveRessource",
 *                             	"my.domain.valves.ValveRessourceInterface");
 * 
 *         		digester.addObjectCreate(pattern + "/FancyValveManager",
 *                                  		null, // MUST be specified in the element
 *                                  		"className");
 *         		digester.addSetProperties(pattern + "/FancyValveManager");
 *         		digester.addSetNext(pattern + "/FancyValveManager",
 *                             	"setManager",
 *                             	"my.domain.valves.FancyValveManager");
 * 	}
 * 
 * }
 * </pre>
 * The digester callback getMatch() enables you to create matching rules relative to the matched parent. For example if you place the example valve under &lt;Host/&gt; and under &lt;Engine/&gt;, the absolute matchstring would need to be different. However, you are not restricted to provide rules below the matched rule. The only restriction is, that all rules you add are only matched down the document, i.e. to all tags that are processed after the tag that lead to the creation of that rules.
 * @author Mika Göckel mika@goeckel.net
 */

public interface SelfConfigureObject {
    /** This method is called directly after the object is
     * created.
     * @param Digester The digester that created the object
     */
    public void configureAdditionalRules(Digester digester);
}