001 /* 002 * Copyright 2001-2004 The Apache Software Foundation 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 package org.apache.commons.cache; 017 018 import java.io.Serializable; 019 020 /** 021 * A {@link Cache} defines an API for storing and later 022 * retrieving {@link Object}s based upon key values. 023 * <p> 024 * A {@link Cache} supports an event subscription/publication 025 * system. 026 * 027 * @version $Id: Cache.java 155435 2005-02-26 13:17:27Z dirkv $ 028 * @author Rodney Waldhoff 029 */ 030 public interface Cache extends Serializable { 031 /** 032 * Store the specified <i>val</i> under the specified 033 * <i>key</i>. 034 * 035 * @param key the key used to later obtain the <i>val</i> from me, 036 * which MUST NOT be <tt>null</tt>. 037 * @param val the val to store, which MUST NOT be <tt>null</tt>. 038 * @param expiry the timestamp at which the given <i>val</i> becomes stale, or <tt>null</tt>. 039 * @param cost the implemenation dependent cost of generating the <i>val</i>, or <tt>null</tt>. 040 * @return <tt>true</tt> if the <i>val</i> was stored, <tt>false</tt> otherwise. 041 */ 042 public boolean store(Serializable key, Serializable val, Long expiry, Long cost); 043 044 /** 045 * Store the specified <i>val</i> under the specified 046 * <i>key</i> and the specified <i>group</i>. 047 * 048 * @param key the key used to later obtain the <i>val</i> from me, 049 * which MUST NOT be <tt>null</tt>. 050 * @param group a meta-key which can be used to clear the object later 051 * @param val the val to store, which MUST NOT be <tt>null</tt>. 052 * @param expiry the timestamp at which the given <i>val</i> becomes stale, or <tt>null</tt>. 053 * @param cost the implemenation dependent cost of generating the <i>val</i>, or <tt>null</tt>. 054 * @return <tt>true</tt> if the <i>val</i> was stored, <tt>false</tt> otherwise. 055 */ 056 public boolean store(Serializable key, Serializable val, Long expiry, Long cost, Serializable group); 057 058 /** 059 * Obtain the value previously {@link #store stored} under 060 * the given <i>key</i>. 061 * 062 * @param key the key which MUST NOT be <tt>null</tt>. 063 * @return the previously {@link #store stored} value, or <tt>null</tt>. 064 */ 065 public Serializable retrieve(Serializable key); 066 067 public Serializable[] getKeysForGroup(Serializable group); 068 069 /** 070 * Returns <tt>true</tt> if I have a value associated with 071 * the given <i>key</i>, <tt>false</tt> otherwise. 072 * 073 * @param key the key which MUST NOT be <tt>null</tt>. 074 * @return <tt>true</tt> if I have a value associated with 075 * the given <i>key</i>, <tt>false</tt> otherwise. 076 */ 077 public boolean contains(Serializable key); 078 079 /** 080 * Remove any value previously {@link #store stored} under 081 * the given <i>key</i>. 082 * 083 * @param key the key which MUST NOT be <tt>null</tt>. 084 */ 085 public void clear(Serializable key); 086 087 /** 088 * Remove any value previously {@link #store stored} under 089 * the given <i>group</i>. 090 * 091 * @param group the group which MUST NOT be <tt>null</tt>. 092 */ 093 public void clearGroup(Serializable group); 094 095 /** 096 * Remove all values previously {@link #store stored}. 097 */ 098 public void clear(); 099 100 /** 101 * Add the given {@link StorageListener} to my 102 * set of {@link StorageListener}s. 103 * @link obs the observer to add 104 */ 105 public abstract void registerStorageListener(StorageListener obs); 106 107 /** 108 * Remove the given {@link StorageListener} from my 109 * set of {@link StorageListener}s. 110 * @link obs the observer to remove 111 */ 112 public abstract void unregisterStorageListener(StorageListener obs); 113 114 /** 115 * Clear my set of {@link StorageListener}s. 116 */ 117 public abstract void unregisterStorageListeners(); 118 119 /** 120 * Add the given {@link RetrievalListener} to my 121 * set of {@link RetrievalListener}s. 122 * @link obs the observer to add 123 */ 124 public abstract void registerRetrievalListener(RetrievalListener obs); 125 126 /** 127 * Remove the given {@link RetrievalListener} from my 128 * set of {@link RetrievalListener}s. 129 * @link obs the observer to remove 130 */ 131 public abstract void unregisterRetrievalListener(RetrievalListener obs); 132 133 /** 134 * Clear my set of {@link RetrievalListener}s. 135 */ 136 public abstract void unregisterRetrievalListeners(); 137 138 public abstract long getStat(CacheStat stat) throws UnsupportedOperationException; 139 }