    001    /* $Id: AbstractRulesImpl.java 729095 2008-12-23 20:32:22Z rahul $
    002     *
    003     * Licensed to the Apache Software Foundation (ASF) under one or more
    004     * contributor license agreements.  See the NOTICE file distributed with
    005     * this work for additional information regarding copyright ownership.
    006     * The ASF licenses this file to You under the Apache License, Version 2.0
    007     * (the "License"); you may not use this file except in compliance with
    008     * the License.  You may obtain a copy of the License at
    009     *
    010     *      http://www.apache.org/licenses/LICENSE-2.0
    011     *
    012     * Unless required by applicable law or agreed to in writing, software
    013     * distributed under the License is distributed on an "AS IS" BASIS,
    014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    015     * See the License for the specific language governing permissions and
    016     * limitations under the License.
    017     */
    018
    019
    020    package org.apache.commons.digester;
    021
    022
    023    import java.util.List;
    024
    025
    026    /**
    027     * <p><code>AbstractRuleImpl</code> provides basic services for <code>Rules</code> implementations.
    028     * Extending this class should make it easier to create a <code>Rules</code> implementation.</p>
    029     *
    030     * <p><code>AbstractRuleImpl</code> manages the <code>Digester</code>
    031     * and <code>namespaceUri</code> properties.
    032     * If the subclass overrides {@link #registerRule} (rather than {@link #add}),
    033     * then the <code>Digester</code> and <code>namespaceURI</code> of the <code>Rule</code>
    034     * will be set correctly before it is passed to <code>registerRule</code>.
    035     * The subclass can then perform whatever it needs to do to register the rule.</p>
    036     *
    037     * @since 1.5
    038     */
    039
    040    abstract public class AbstractRulesImpl implements Rules {
    041
    042        // ------------------------------------------------------------- Fields
    043
    044        /** Digester using this <code>Rules</code> implementation */
    045        private Digester digester;
    046        /** Namespace uri to assoicate with subsequent <code>Rule</code>'s */
    047        private String namespaceURI;
    048
    049        // ------------------------------------------------------------- Properties
    050
    051        /**
    052         * Return the Digester instance with which this Rules instance is
    053         * associated.
    054         */
    055        public Digester getDigester() {
    056            return digester;
    057        }
    058
    059        /**
    060         * Set the Digester instance with which this Rules instance is associated.
    061         *
    062         * @param digester The newly associated Digester instance
    063         */
    064        public void setDigester(Digester digester) {
    065            this.digester = digester;
    066        }
    067
    068        /**
    069         * Return the namespace URI that will be applied to all subsequently
    070         * added <code>Rule</code> objects.
    071         */
    072        public String getNamespaceURI() {
    073            return namespaceURI;
    074        }
    075
    076        /**
    077         * Set the namespace URI that will be applied to all subsequently
    078         * added <code>Rule</code> objects.
    079         *
    080         * @param namespaceURI Namespace URI that must match on all
    081         *  subsequently added rules, or <code>null</code> for matching
    082         *  regardless of the current namespace URI
    083         */
    084        public void setNamespaceURI(String namespaceURI) {
    085            this.namespaceURI = namespaceURI;
    086        }
    087
    088        // --------------------------------------------------------- Public Methods
    089
    090        /**
    091         * Registers a new Rule instance matching the specified pattern.
    092         * This implementation sets the <code>Digester</code> and the
    093         * <code>namespaceURI</code> on the <code>Rule</code> before calling {@link #registerRule}.
    094         *
    095         * @param pattern Nesting pattern to be matched for this Rule
    096         * @param rule Rule instance to be registered
    097         */
    098        public void add(String pattern, Rule rule) {
    099            // set up rule
    100            if (this.digester != null) {
    101                rule.setDigester(this.digester);
    102            }
    103
    104            if (this.namespaceURI != null) {
    105                rule.setNamespaceURI(this.namespaceURI);
    106            }
    107
    108            registerRule(pattern, rule);
    109
    110        }
    111
    112        /**
    113         * Register rule at given pattern.
    114         * The the Digester and namespaceURI properties of the given <code>Rule</code>
    115         * can be assumed to have been set properly before this method is called.
    116         *
    117         * @param pattern Nesting pattern to be matched for this Rule
    118         * @param rule Rule instance to be registered
    119         */
    120        abstract protected void registerRule(String pattern, Rule rule);
    121
    122        /**
    123         * Clear all existing Rule instance registrations.
    124         */
    125        abstract public void clear();
    126
    127
    128        /**
    129         * Return a List of all registered Rule instances that match the specified
    130         * nesting pattern, or a zero-length List if there are no matches.  If more
    131         * than one Rule instance matches, they <strong>must</strong> be returned
    132         * in the order originally registered through the <code>add()</code>
    133         * method.
    134         *
    135         * @param pattern Nesting pattern to be matched
    136         *
    137         * @deprecated Call match(namespaceURI,pattern) instead.
    138         */
    139        public List<Rule> match(String pattern) {
    140            return match(namespaceURI, pattern);
    141        }
    142
    143
    144        /**
    145         * Return a List of all registered Rule instances that match the specified
    146         * nesting pattern, or a zero-length List if there are no matches.  If more
    147         * than one Rule instance matches, they <strong>must</strong> be returned
    148         * in the order originally registered through the <code>add()</code>
    149         * method.
    150         *
    151         * @param namespaceURI Namespace URI for which to select matching rules,
    152         *  or <code>null</code> to match regardless of namespace URI
    153         * @param pattern Nesting pattern to be matched
    154         */
    155        abstract public List<Rule> match(String namespaceURI, String pattern);
    156
    157
    158        /**
    159         * Return a List of all registered Rule instances, or a zero-length List
    160         * if there are no registered Rule instances.  If more than one Rule
    161         * instance has been registered, they <strong>must</strong> be returned
    162         * in the order originally registered through the <code>add()</code>
    163         * method.
    164         */
    165        abstract public List<Rule> rules();
    166
    167    }