001    /* $Id: Rules.java 471661 2006-11-06 08:09:25Z skitching $
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 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 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 rules();
126    
127    
128    }