src/java/org/apache/commons/digester/plugins/Declaration.java

/* $Id: Declaration.java,v 1.17 2004/05/10 06:44:13 skitching Exp $
 *
 * Copyright 2003-2004 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */ 
package org.apache.commons.digester.plugins;

import java.io.IOException;
import java.util.Properties;
import java.util.List;

import org.apache.commons.logging.Log;
import org.apache.commons.digester.Digester;

/**
 * Represents a Class that can be instantiated by a PluginCreateRule, plus
 * info on how to load custom digester rules for mapping xml into that
 * plugged-in class.
 *
 * @since 1.6
 */
public class Declaration {
   
    /** The class of the object to be instantiated. */
    private Class pluginClass;

    /** The name of the class of the object to be instantiated. */
    private String pluginClassName;
    
    /** See {@link #setId}. */ 
    private String id;
    
    /** See {@link #setProperties}. */
    private Properties properties = new Properties();
    
    /** See {@link #init}. */
    private boolean initialized = false;

    /**
     * Class which is responsible for dynamically loading this
     * plugin's rules on demand.
     */
    private RuleLoader ruleLoader = null;
    
    //---------------------- constructors ----------------------------------

    /**
     * Constructor.
     */
    public Declaration(String pluginClassName) {
        // We can't load the pluginClass at this time, because we don't
        // have a digester instance yet to load it through. So just
        // save the name away, and we'll load the Class object in the
        // init method.
        this.pluginClassName = pluginClassName;
    }
    
    /**
     * Constructor.
     */
    public Declaration(Class pluginClass) {
        this.pluginClass = pluginClass;
        this.pluginClassName = pluginClass.getName();
    }
    
    /**
     * Create an instance where a fully-initialised ruleLoader instance
     * is provided by the caller instead of having the PluginManager
     * "discover" an appropriate one.
     */
    public Declaration(Class pluginClass, RuleLoader ruleLoader) {
        this.pluginClass = pluginClass;
        this.pluginClassName = pluginClass.getName();
        this.ruleLoader = ruleLoader;
    }
    
    //---------------------- properties -----------------------------------

    /** 
     * The id that the user associated with a particular plugin declaration
     * in the input xml. This id is later used in the input xml to refer
     * back to the original declaration.
     * <p>
     * For plugins declared "in-line", the id is null.
     */
    public void setId(String id) {
        this.id = id;
    }
    
    /**
     * Return the id associated with this declaration. For plugins
     * declared "inline", null will be returned.
     * 
     * @return The id value. May be null.
     */
    public String getId() {
        return id;
    }

    /** 
     * Copy all (key,value) pairs in the param into the properties member of
     * this object.
     * <p>
     * The declaration properties cannot be explicit member variables,
     * because the set of useful properties a user can provide on a declaration
     * depends on what RuleFinder classes are available - and extra RuleFinders
     * can be added by the user. So here we keep a map of the settings, and
     * let the RuleFinder objects look for whatever properties they consider
     * significant.
     * <p>
     * The "id" and "class" properties are treated differently.
     */
    public void setProperties(Properties p) {
        properties.putAll(p);
    }
    
    /**
     * Return plugin class associated with this declaration.
     * 
     * @return The pluginClass.
     */
    public Class getPluginClass() {
        return pluginClass;
    }

    //---------------------- methods -----------------------------------
    
    /**
     * Must be called exactly once, and must be called before any call
     * to the configure method.
     */
    public void init(Digester digester, PluginManager pm) throws PluginException {
        Log log = digester.getLogger();
        boolean debug = log.isDebugEnabled();
        if (debug) {
            log.debug("init being called!");
        }
        
        if (initialized) {
            throw new PluginAssertionFailure("Init called multiple times.");
        }

        if ((pluginClass == null) && (pluginClassName != null)) {
            try {
                // load the plugin class object
                pluginClass = 
                    digester.getClassLoader().loadClass(pluginClassName);
            } catch(ClassNotFoundException cnfe) {
                throw new PluginException(
                    "Unable to load class " + pluginClassName, cnfe);
            }
        }

        if (ruleLoader == null) {
            // the caller didn't provide a ruleLoader to the constructor,
            // so get the plugin manager to "discover" one.
            log.debug("Searching for ruleloader...");
            ruleLoader = pm.findLoader(digester, id, pluginClass, properties);
        } else {
            log.debug("This declaration has an explicit ruleLoader.");
        }
        
        if (debug) {
            if (ruleLoader == null) {
                log.debug(
                    "No ruleLoader found for plugin declaration"
                    + " id [" + id + "]"
                    + ", class [" + pluginClass.getClass().getName() + "].");
            } else {
                log.debug(
                    "RuleLoader of type [" + ruleLoader.getClass().getName()
                    + "] associated with plugin declaration"
                    + " id [" + id + "]"
                    + ", class [" + pluginClass.getClass().getName() + "].");
            }
        }
        
        initialized = true;        
    }
    
    /**
     * Attempt to load custom rules for the target class at the specified
     * pattern.
     * <p>
     * On return, any custom rules associated with the plugin class have
     * been loaded into the Rules object currently associated with the
     * specified digester object.
     */
     
    public void configure(Digester digester, String pattern)
                          throws PluginException {
        Log log = digester.getLogger();
        boolean debug = log.isDebugEnabled();
        if (debug) {
            log.debug("configure being called!");
        }
        
        if (!initialized) {
            throw new PluginAssertionFailure("Not initialized.");
        }

        if (ruleLoader != null) {
            ruleLoader.addRules(digester, pattern);
        }
    }
}