KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > caching > EventRegistry


1 /*
2  * Copyright 1999-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 package org.apache.cocoon.caching;
17
18 import java.io.Serializable JavaDoc;
19
20 import org.apache.avalon.framework.component.Component;
21 import org.apache.cocoon.caching.validity.Event;
22
23 /**
24  * The <code>EventRegistry</code> is responsible for the two-way many-to-many
25  * mapping between cache <code>Event</code>s and
26  * <code>PipelineCacheKey</code>s necessary to allow for efficient
27  * event-based cache invalidation.
28  *
29  * Because persistence and recovery between application shutdown and startup are
30  * internal concerns they are not defined here even though it is expected that most
31  * real-world implementers of this interface would require these features.
32  * On the other hand, EventRegistry must help the Cache to ensure that outdated
33  * content is never served, even if that means discarding potentially valid cached
34  * entries. For this reason, wasRecoverySuccessful() is defined here as part of
35  * the public contract with the Cache.
36  *
37  * @since 2.1
38  * @author <a HREF="mailto:ghoward@apache.org">Geoff Howard</a>
39  * @version CVS $Id: EventRegistry.java 30932 2004-07-29 17:35:38Z vgritsenko $
40  */
41 public interface EventRegistry extends Component {
42     
43     /**
44      * The Avalon ROLE for this component
45      */
46     String JavaDoc ROLE = EventRegistry.class.getName();
47     
48     /**
49      * Map an event to a key
50      *
51      * @param e event
52      * @param key key
53      */
54     public void register(Event e, Serializable JavaDoc key);
55     
56     /**
57      * Remove all occurances of the specified key from the registry.
58      *
59      * @param key - The key to remove.
60      */
61     public void removeKey(Serializable JavaDoc key);
62     
63     /**
64      * Retrieve an array of all keys mapped to this event.
65      *
66      * @param e event
67      * @return an array of keys which should not be modified or null if
68      * no keys are mapped to this event.
69      */
70     public Serializable JavaDoc[] keysForEvent(Event e);
71     
72     /**
73      * Retrieve an array of all keys regardless of event mapping, or null if
74      * no keys are registered..
75      *
76      * @return an array of keys which should not be modified
77      */
78     public Serializable JavaDoc[] allKeys();
79     
80     /**
81      * Clear all event-key mappings from the registry.
82      */
83     public void clear();
84     
85     /**
86      * Returns whether the registry was successful in retrieving its
87      * persisted state during startup.
88      *
89      * If recovering persisted data was not successful, the component must
90      * signal that the Cache may contain orphaned EventValidity objects by
91      * returning false. The Cache should then ensure that all pipelines
92      * associated with EventValidities are either removed or re-associated
93      * (if possible).
94      *
95      * @return true if the Component recovered its state successfully,
96      * false otherwise.
97      */
98     public boolean wasRecoverySuccessful();
99 }
100
Popular Tags