    001    /* $Id: Rules.java 729086 2008-12-23 20:18: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     * Public interface defining a collection of Rule instances (and corresponding
    028     * matching patterns) plus an implementation of a matching policy that selects
    029     * the rules that match a particular pattern of nested elements discovered
    030     * during parsing.
    031     */
    032
    033    public interface Rules {
    034
    035
    036        // ------------------------------------------------------------- Properties
    037
    038
    039        /**
    040         * Return the Digester instance with which this Rules instance is
    041         * associated.
    042         */
    043        public Digester getDigester();
    044
    045
    046        /**
    047         * Set the Digester instance with which this Rules instance is associated.
    048         *
    049         * @param digester The newly associated Digester instance
    050         */
    051        public void setDigester(Digester digester);
    052
    053
    054        /**
    055         * Return the namespace URI that will be applied to all subsequently
    056         * added <code>Rule</code> objects.
    057         */
    058        public String getNamespaceURI();
    059
    060
    061        /**
    062         * Set the namespace URI that will be applied to all subsequently
    063         * added <code>Rule</code> objects.
    064         *
    065         * @param namespaceURI Namespace URI that must match on all
    066         *  subsequently added rules, or <code>null</code> for matching
    067         *  regardless of the current namespace URI
    068         */
    069        public void setNamespaceURI(String namespaceURI);
    070
    071
    072        // --------------------------------------------------------- Public Methods
    073
    074
    075        /**
    076         * Register a new Rule instance matching the specified pattern.
    077         *
    078         * @param pattern Nesting pattern to be matched for this Rule
    079         * @param rule Rule instance to be registered
    080         */
    081        public void add(String pattern, Rule rule);
    082
    083
    084        /**
    085         * Clear all existing Rule instance registrations.
    086         */
    087        public void clear();
    088
    089
    090        /**
    091         * Return a List of all registered Rule instances that match the specified
    092         * nesting pattern, or a zero-length List if there are no matches.  If more
    093         * than one Rule instance matches, they <strong>must</strong> be returned
    094         * in the order originally registered through the <code>add()</code>
    095         * method.
    096         *
    097         * @param pattern Nesting pattern to be matched
    098         *
    099         * @deprecated Call match(namespaceURI,pattern) instead.
    100         */
    101        public List<Rule> match(String pattern);
    102
    103
    104        /**
    105         * Return a List of all registered Rule instances that match the specified
    106         * nesting pattern, or a zero-length List if there are no matches.  If more
    107         * than one Rule instance matches, they <strong>must</strong> be returned
    108         * in the order originally registered through the <code>add()</code>
    109         * method.
    110         *
    111         * @param namespaceURI Namespace URI for which to select matching rules,
    112         *  or <code>null</code> to match regardless of namespace URI
    113         * @param pattern Nesting pattern to be matched
    114         */
    115        public List<Rule> match(String namespaceURI, String pattern);
    116
    117
    118        /**
    119         * Return a List of all registered Rule instances, or a zero-length List
    120         * if there are no registered Rule instances.  If more than one Rule
    121         * instance has been registered, they <strong>must</strong> be returned
    122         * in the order originally registered through the <code>add()</code>
    123         * method.
    124         */
    125        public List<Rule> rules();
    126
    127
    128    }