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