1 package org.apache.commons.digester3; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import java.util.List; 23 24 import org.xml.sax.Attributes; 25 26 /** 27 * Public interface defining a collection of Rule instances (and corresponding matching patterns) plus an implementation 28 * of a matching policy that selects the rules that match a particular pattern of nested elements discovered during 29 * parsing. 30 */ 31 public interface Rules 32 { 33 34 // ------------------------------------------------------------- Properties 35 36 /** 37 * Return the Digester instance with which this Rules instance is associated. 38 * 39 * @return the Digester instance with which this Rules instance is associated 40 */ 41 Digester getDigester(); 42 43 /** 44 * Set the Digester instance with which this Rules instance is associated. 45 * 46 * @param digester The newly associated Digester instance 47 */ 48 void setDigester( Digester digester ); 49 50 /** 51 * Return the namespace URI that will be applied to all subsequently added <code>Rule</code> objects. 52 * 53 * @return the namespace URI that will be applied to all subsequently added <code>Rule</code> objects. 54 */ 55 String getNamespaceURI(); 56 57 /** 58 * Set the namespace URI that will be applied to all subsequently added <code>Rule</code> objects. 59 * 60 * @param namespaceURI Namespace URI that must match on all subsequently added rules, or <code>null</code> for 61 * matching regardless of the current namespace URI 62 */ 63 void setNamespaceURI( String namespaceURI ); 64 65 // --------------------------------------------------------- Public Methods 66 67 /** 68 * Register a new Rule instance matching the specified pattern. 69 * 70 * @param pattern Nesting pattern to be matched for this Rule 71 * @param rule Rule instance to be registered 72 */ 73 void add( String pattern, Rule rule ); 74 75 /** 76 * Clear all existing Rule instance registrations. 77 */ 78 void clear(); 79 80 /** 81 * Return a List of all registered Rule instances that match the specified nesting pattern, or a zero-length List if 82 * there are no matches. If more than one Rule instance matches, they <strong>must</strong> be returned in the order 83 * originally registered through the <code>add()</code> method. 84 * 85 * @param namespaceURI Namespace URI for which to select matching rules, or <code>null</code> to match regardless of 86 * namespace URI 87 * @param pattern Nesting pattern to be matched 88 * @param name the local name if the parser is namespace aware, or just the element name otherwise 89 * @param attributes The attribute list of the current matching element 90 * @return a List of all registered Rule instances that match the specified nesting pattern 91 */ 92 List<Rule> match( String namespaceURI, String pattern, String name, Attributes attributes ); 93 94 /** 95 * Return a List of all registered Rule instances, or a zero-length List if there are no registered Rule instances. 96 * If more than one Rule instance has been registered, they <strong>must</strong> be returned in the order 97 * originally registered through the <code>add()</code> method. 98 * 99 * @return a List of all registered Rule instances 100 */ 101 List<Rule> rules(); 102 103 }