001    package org.apache.commons.digester3;
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    
022    import java.util.List;
023    
024    import org.xml.sax.Attributes;
025    
026    /**
027     * Public interface defining a collection of Rule instances (and corresponding matching patterns) plus an implementation
028     * of a matching policy that selects the rules that match a particular pattern of nested elements discovered during
029     * parsing.
030     */
031    public interface Rules
032    {
033    
034        // ------------------------------------------------------------- Properties
035    
036        /**
037         * Return the Digester instance with which this Rules instance is associated.
038         *
039         * @return the Digester instance with which this Rules instance is associated
040         */
041        Digester getDigester();
042    
043        /**
044         * Set the Digester instance with which this Rules instance is associated.
045         * 
046         * @param digester The newly associated Digester instance
047         */
048        void setDigester( Digester digester );
049    
050        /**
051         * Return the namespace URI that will be applied to all subsequently added <code>Rule</code> objects.
052         *
053         * @return the namespace URI that will be applied to all subsequently added <code>Rule</code> objects.
054         */
055        String getNamespaceURI();
056    
057        /**
058         * Set the namespace URI that will be applied to all subsequently added <code>Rule</code> objects.
059         * 
060         * @param namespaceURI Namespace URI that must match on all subsequently added rules, or <code>null</code> for
061         *            matching regardless of the current namespace URI
062         */
063        void setNamespaceURI( String namespaceURI );
064    
065        // --------------------------------------------------------- Public Methods
066    
067        /**
068         * Register a new Rule instance matching the specified pattern.
069         * 
070         * @param pattern Nesting pattern to be matched for this Rule
071         * @param rule Rule instance to be registered
072         */
073        void add( String pattern, Rule rule );
074    
075        /**
076         * Clear all existing Rule instance registrations.
077         */
078        void clear();
079    
080        /**
081         * Return a List of all registered Rule instances that match the specified nesting pattern, or a zero-length List if
082         * there are no matches. If more than one Rule instance matches, they <strong>must</strong> be returned in the order
083         * originally registered through the <code>add()</code> method.
084         * 
085         * @param namespaceURI Namespace URI for which to select matching rules, or <code>null</code> to match regardless of
086         *            namespace URI
087         * @param pattern Nesting pattern to be matched
088         * @param name the local name if the parser is namespace aware, or just the element name otherwise
089         * @param attributes The attribute list of the current matching element
090         * @return a List of all registered Rule instances that match the specified nesting pattern
091         */
092        List<Rule> match( String namespaceURI, String pattern, String name, Attributes attributes );
093    
094        /**
095         * Return a List of all registered Rule instances, or a zero-length List if there are no registered Rule instances.
096         * If more than one Rule instance has been registered, they <strong>must</strong> be returned in the order
097         * originally registered through the <code>add()</code> method.
098         *
099         * @return a List of all registered Rule instances
100         */
101        List<Rule> rules();
102    
103    }