001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.caching;
018:
019: import java.io.Serializable;
020:
021: import org.apache.avalon.framework.component.Component;
022: import org.apache.cocoon.caching.validity.Event;
023:
024: /**
025: * The <code>EventRegistry</code> is responsible for the two-way many-to-many
026: * mapping between cache <code>Event</code>s and
027: * <code>PipelineCacheKey</code>s necessary to allow for efficient
028: * event-based cache invalidation.
029: *
030: * Because persistence and recovery between application shutdown and startup are
031: * internal concerns they are not defined here even though it is expected that most
032: * real-world implementers of this interface would require these features.
033: * On the other hand, EventRegistry must help the Cache to ensure that outdated
034: * content is never served, even if that means discarding potentially valid cached
035: * entries. For this reason, wasRecoverySuccessful() is defined here as part of
036: * the public contract with the Cache.
037: *
038: * @since 2.1
039: * @author <a href="mailto:ghoward@apache.org">Geoff Howard</a>
040: * @version CVS $Id: EventRegistry.java 433543 2006-08-22 06:22:54Z crossley $
041: */
042: public interface EventRegistry extends Component {
043:
044: /**
045: * The Avalon ROLE for this component
046: */
047: String ROLE = EventRegistry.class.getName();
048:
049: /**
050: * Map an event to a key
051: *
052: * @param e event
053: * @param key key
054: */
055: public void register(Event e, Serializable key);
056:
057: /**
058: * Remove all occurances of the specified key from the registry.
059: *
060: * @param key - The key to remove.
061: */
062: public void removeKey(Serializable key);
063:
064: /**
065: * Retrieve an array of all keys mapped to this event.
066: *
067: * @param e event
068: * @return an array of keys which should not be modified or null if
069: * no keys are mapped to this event.
070: */
071: public Serializable[] keysForEvent(Event e);
072:
073: /**
074: * Retrieve an array of all keys regardless of event mapping, or null if
075: * no keys are registered..
076: *
077: * @return an array of keys which should not be modified
078: */
079: public Serializable[] allKeys();
080:
081: /**
082: * Clear all event-key mappings from the registry.
083: */
084: public void clear();
085:
086: /**
087: * Returns whether the registry was successful in retrieving its
088: * persisted state during startup.
089: *
090: * If recovering persisted data was not successful, the component must
091: * signal that the Cache may contain orphaned EventValidity objects by
092: * returning false. The Cache should then ensure that all pipelines
093: * associated with EventValidities are either removed or re-associated
094: * (if possible).
095: *
096: * @return true if the Component recovered its state successfully,
097: * false otherwise.
098: */
099: public boolean wasRecoverySuccessful();
100: }
|