001package 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
022import java.util.List;
023
024import 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 */
031public 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}