001package org.apache.commons.digester3.plugins.strategies;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.io.InputStream;
023import java.util.Properties;
024
025import org.apache.commons.digester3.Digester;
026import org.apache.commons.digester3.plugins.PluginException;
027import org.apache.commons.digester3.plugins.RuleFinder;
028import org.apache.commons.digester3.plugins.RuleLoader;
029
030/**
031 * A rule-finding algorithm which looks for a resource file in the classpath whose name is derived from the plugin class
032 * name plus a specified suffix.
033 * <p>
034 * If the resource-file is found, then it is expected to define a set of Digester rules in xmlrules format.
035 * 
036 * @since 1.6
037 */
038public class FinderFromDfltResource
039    extends RuleFinder
040{
041
042    private static final String DFLT_RESOURCE_SUFFIX = "RuleInfo.xml";
043
044    private final String resourceSuffix;
045
046    /** See {@link #findLoader}. */
047    public FinderFromDfltResource()
048    {
049        this( DFLT_RESOURCE_SUFFIX );
050    }
051
052    /**
053     * Create a rule-finder which can load an xmlrules file, cache the rules away, and later add them as a plugin's
054     * custom rules when that plugin is referenced.
055     * 
056     * @param resourceSuffix must be non-null.
057     */
058    public FinderFromDfltResource( String resourceSuffix )
059    {
060        this.resourceSuffix = resourceSuffix;
061    }
062
063    /**
064     * If there exists a resource file whose name is equal to the plugin class name + the suffix specified in the
065     * constructor, then load that file, run it through the xmlrules module and return an object encapsulating those
066     * rules.
067     * <p>
068     * If there is no such resource file, then just return null.
069     * <p>
070     * The returned object (when non-null) will add the selected rules to the digester whenever its addRules method is
071     * invoked.
072     *
073     * @param d The digester instance where locating plugin classes
074     * @param pluginClass The plugin Java class
075     * @param p The properties object that holds any xml attributes the user may have specified on the plugin
076     *          declaration in order to indicate how to locate the plugin rules.
077     * @return a source of digester rules for the specified plugin class.
078     * @throws PluginException if the algorithm finds a source of rules, but there is something invalid
079     *         about that source.
080     */
081    @Override
082    public RuleLoader findLoader( Digester d, Class<?> pluginClass, Properties p )
083        throws PluginException
084    {
085
086        String resourceName = pluginClass.getName().replace( '.', '/' ) + resourceSuffix;
087
088        InputStream is = pluginClass.getClassLoader().getResourceAsStream( resourceName );
089
090        if ( is == null )
091        {
092            // ok, no such resource
093            return null;
094        }
095
096        return FinderFromResource.loadRules( d, pluginClass, is, resourceName );
097    }
098
099}