001 /* $Id: Rules.java 992060 2010-09-02 19:09:47Z simonetripodi $
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 @Deprecated
102 public List<Rule> match(String pattern);
103
104
105 /**
106 * Return a List of all registered Rule instances that match the specified
107 * nesting pattern, or a zero-length List if there are no matches. If more
108 * than one Rule instance matches, they <strong>must</strong> be returned
109 * in the order originally registered through the <code>add()</code>
110 * method.
111 *
112 * @param namespaceURI Namespace URI for which to select matching rules,
113 * or <code>null</code> to match regardless of namespace URI
114 * @param pattern Nesting pattern to be matched
115 */
116 public List<Rule> match(String namespaceURI, String pattern);
117
118
119 /**
120 * Return a List of all registered Rule instances, or a zero-length List
121 * if there are no registered Rule instances. If more than one Rule
122 * instance has been registered, they <strong>must</strong> be returned
123 * in the order originally registered through the <code>add()</code>
124 * method.
125 */
126 public List<Rule> rules();
127
128
129 }