org.apache.commons.digester3.WithDefaultsRulesWrapper Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of commons-digester3 Show documentation
The Apache Commons Digester package lets you configure an XML to Java object mapping module which triggers certain actions called rules whenever a particular pattern of nested XML elements is recognized.
There is a newer version: 3.2
Show newest version
package org.apache.commons.digester3;

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.
 */

import java.util.ArrayList;
import java.util.List;

import org.xml.sax.Attributes;

/**
 * 
 * Rules Decorator that returns default rules when no matches are returned by the wrapped
 * implementation.
 * 
 * 
 * This allows default Rule instances to be added to any existing Rules implementation. These
 * default Rule instances will be returned for any match for which the wrapped implementation does not
 * return any matches.
 * 
 * 
 * For example,
 * 
 * 
 *   Rule alpha;
 *   ...
 *   WithDefaultsRulesWrapper rules = new WithDefaultsRulesWrapper(new BaseRules());
 *   rules.addDefault(alpha);
 *   ...
 *   digester.setRules(rules);
 *   ...
 * 
 * 
 * when a pattern does not match any other rule, then rule alpha will be called.
 * 
 * 
 * WithDefaultsRulesWrapper follows the Decorator pattern.
 * 
 * 
 * @since 1.6
 */
public class WithDefaultsRulesWrapper
    implements Rules
{

    // --------------------------------------------------------- Fields

    /** The Rules implementation that this class wraps. */
    private Rules wrappedRules;

    /** Rules to be fired when the wrapped implementations returns none. */
    private List defaultRules = new ArrayList();

    /** All rules (preserves order in which they were originally added) */
    private List allRules = new ArrayList();

    // --------------------------------------------------------- Constructor

    /**
     * Base constructor.
     *
     * @param wrappedRules the wrapped Rules implementation, not null
     */
    public WithDefaultsRulesWrapper( Rules wrappedRules )
    {
        if ( wrappedRules == null )
        {
            throw new IllegalArgumentException( "Wrapped rules must not be null" );
        }
        this.wrappedRules = wrappedRules;
    }

    // --------------------------------------------------------- Properties

    /**
     * {@inheritDoc}
     */
    public Digester getDigester()
    {
        return wrappedRules.getDigester();
    }

    /**
     * {@inheritDoc}
     */
    public void setDigester( Digester digester )
    {
        wrappedRules.setDigester( digester );
        for ( Rule rule : defaultRules )
        {
            rule.setDigester( digester );
        }
    }

    /**
     * {@inheritDoc}
     */
    public String getNamespaceURI()
    {
        return wrappedRules.getNamespaceURI();
    }

    /**
     * {@inheritDoc}
     */
    public void setNamespaceURI( String namespaceURI )
    {
        wrappedRules.setNamespaceURI( namespaceURI );
    }

    /**
     * Gets Rule's which will be fired when the wrapped implementation returns no matches
     *
     * @return Rule's which will be fired when the wrapped implementation returns no matches
     **/
    public List getDefaults()
    {
        return defaultRules;
    }

    // --------------------------------------------------------- Public Methods

    /**
     * {@inheritDoc}
     */
    public List match( String namespaceURI, String pattern, String name, Attributes attributes )
    {
        List matches = wrappedRules.match( namespaceURI, pattern, name, attributes );
        if ( matches == null || matches.isEmpty() )
        {
            // a little bit of defensive programming
            return new ArrayList( defaultRules );
        }
        // otherwise
        return matches;
    }

    /**
     * Adds a rule to be fired when wrapped implementation returns no matches
     *
     * @param rule a Rule to be fired when wrapped implementation returns no matches
     **/
    public void addDefault( Rule rule )
    {
        // set up rule
        if ( wrappedRules.getDigester() != null )
        {
            rule.setDigester( wrappedRules.getDigester() );
        }

        if ( wrappedRules.getNamespaceURI() != null )
        {
            rule.setNamespaceURI( wrappedRules.getNamespaceURI() );
        }

        defaultRules.add( rule );
        allRules.add( rule );
    }

    /**
     * {@inheritDoc}
     */
    public List rules()
    {
        return allRules;
    }

    /**
     * {@inheritDoc}
     */
    public void clear()
    {
        wrappedRules.clear();
        allRules.clear();
        defaultRules.clear();
    }

    /**
     * {@inheritDoc}
     */
    public void add( String pattern, Rule rule )
    {
        wrappedRules.add( pattern, rule );
        allRules.add( rule );
    }

}