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 }