View Javadoc

1   /**
2    * Copyright 2005-2006 the original author or authors.
3    *
4    * Licensed under the Gnu General Pubic License, Version 2.0 (the
5    * "License"); you may not use this file except in compliance with
6    * the License. You may obtain a copy of the License at
7    *
8    *      http://www.opensource.org/licenses/gpl-license.php
9    *
10   * This program is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13   * See the Gnu General Public License for more details.
14   */
15  package org.figure8.join.services.cache;
16  
17  import java.io.Serializable;
18  import java.util.List;
19  /**
20   * Interface defining a standard basic cache. Implementors may encapsulate
21   * existing Cache providers (EHCache, JBossTree, ...). Join Caches restrict
22   * keys and elements to be {@link Serializable} : this should help if wanting
23   * to have clustered and distributed caches.
24   * @author <a href="mailto:laurent.broudoux@free.fr">Laurent Broudoux</a>
25   * @version $Revision: 1.2 $
26   *
27   * @see java.io.Serializable
28   */
29  public interface Cache{
30  
31     // Public -------------------------------------------------------------------
32  
33     /**
34      * Get the key this cache is registred within CacheManager
35      * @return This cache key (ie. its name)
36      */
37     public abstract String getKey();
38  
39     /**
40      * Get all the elements of this cache. This method returns a list
41      * that do not prevent from having duplicates ! 
42      * @return A List of the cache elements
43      */
44     public abstract List getElements();
45  
46     /**
47      * Get the value of a cache element which matches the key
48      * @param key The key of the element to return
49      * @return The value placed into the cache with an earlier put, or null if not found or expired
50      */
51     public abstract Serializable get(Serializable key);
52  
53     /**
54      * Puts an object into the cache
55      * @param key a serializable key
56      * @param value a serializable value
57      * @throws CacheException if object cannot be put into cache
58      */
59     public abstract void put(Serializable key, Serializable value) throws CacheException;
60  
61     /**
62      * Remove an object from the cache
63      * @param key a serializable key
64      * @throws CacheException if something went wrong during removal
65      */
66     public abstract void remove(Serializable key) throws CacheException;
67  
68     /**
69      * Remove all elements from this cache but leave it in a usable state
70      * @throws CacheException if cache cannot be cleared
71      */
72     public abstract void clear() throws CacheException;
73  
74     /**
75      * Remove all elements from this cache and the cache itself. It is
76      * no longer usable. <code>CacheManager</code> should no longer offer
77      * access to this cache until explicit cache re-creation.
78      * @throws CacheException if cache cannot be cleaned up
79      */
80     public abstract void cleanUp() throws CacheException;
81  }