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 }