View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */ 
16  
17  
18  package org.apache.asn1.ber.digester ;
19  
20  
21  import java.util.List;
22  
23  import org.apache.commons.collections.primitives.IntStack;
24  
25  
26  /***
27   * Public interface defining a collection of Rule instances (and corresponding
28   * matching patterns) plus an implementation of a matching policy that selects
29   * the rules that match a particular pattern of nested elements discovered
30   * during parsing.  The interface has been inspired by the rulesBase equivalent.
31   * 
32   * @author <a href="mailto:dev@directory.apache.org">
33   * Apache Directory Project</a>
34   * @version $Rev: 157644 $
35   */
36  public interface Rules 
37  {
38      /***
39       * Get the <code>BERDigester</code> instance with which this <code>Rules
40       * </code> instance is associated.
41       * 
42       * @return the BERDigester associated with this Rules instance
43       */
44      public BERDigester getDigester() ;
45  
46      /***
47       * Get the <code>BERDigester</code> instance with which this <code>Rules
48       * </code> instance is associated.
49       * 
50       * @param digester the new BERDigester to be associated with this Rules 
51       * instance
52       */
53      public void setDigester( BERDigester digester ) ;
54  
55      /***
56       * Register a new Rule instance matching the specified pattern.
57       *
58       * @param pattern Tag nesting pattern to be matched for this Rule
59       * @param rule Rule instance to be registered
60       */
61      public void add( int[] pattern, Rule rule ) ;
62  
63      /***
64       * Clear all existing Rule instance registrations.
65       */
66      public void clear() ;
67  
68      /***
69       * Return a List of all registered Rule instances that match the specified
70       * nesting pattern, or a zero-length List if there are no matches.  If more
71       * than one Rule instance matches, they <strong>must</strong> be returned
72       * in the order originally registered through the <code>add()</code>
73       * method.
74       *
75       * @param pattern Nesting pattern to be matched
76       */
77      public List match( int[] pattern ) ;
78  
79      /***
80       * Return a List of all registered Rule instances that match the specified
81       * nesting pattern, or a zero-length List if there are no matches.  If more
82       * than one Rule instance matches, they <strong>must</strong> be returned
83       * in the order originally registered through the <code>add()</code>
84       * method.  The IntStack argument should not be affected by the match call.
85       *
86       * @param pattern Nesting pattern to be matched
87       */
88      public List match( IntStack pattern ) ;
89      
90      /***
91       * Return a List of all registered Rule instances, or a zero-length List
92       * if there are no registered Rule instances.  If more than one Rule
93       * instance has been registered, they <strong>must</strong> be returned
94       * in the order originally registered through the <code>add()</code>
95       * method.
96       */
97      public List rules() ;
98  }