Interface to be implemented by any code to persist
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / serviceprovider / SessionCache.java
1 /*
2  * SessionCache.java
3  * 
4  * A Session Cache implementation saves the content of all current
5  * Session objects to some form of disk storage. This has two 
6  * advantages:
7  * 
8  * It allows the Sessions (and their saved Assertions) to be 
9  * restored after the host computer, Web server, or /shibboleth
10  * context are recycled. 
11  * 
12  * It allows the cookies, handles, and assertions to be shared
13  * (provided the cache is shared) between multiple hosts in a
14  * load balancing configuration.
15  * 
16  * Exactly where you cache Sessions is up to you. A few obvious
17  * possible implementations are:
18  * 
19  * Write the Session fields (Strings and XML) to columns of a 
20  * database table using JDBC. The primary key of the table is
21  * the sessionId.
22  * 
23  * Serialize the Session object to a file in a cache directory.
24  * The name of the file would be {sessionId}.xml
25  * 
26  * Use a persistance framework or Object Relational mapping
27  * system (Hibernate is popular) to persist the objects.
28  * 
29  * Note: The Assertions in the Session extend DOM objects, so
30  * they can be serialized to character strings and parsed on 
31  * the way back if your store doesn't support XML columns natively.
32  * 
33  * Design point: There are two ways to handle a reboot.
34  * 1) The Cache could return an iterator and the SessionManager could
35  * run through all its entries storing them in the collection.
36  * 2) The MemoryMananager can pass the collection to the Cache to
37  * fill in from persistent storage.
38  * This interface adopts the second approach, but that is just a
39  * value judgement. 
40  * 
41  * --------------------
42  * Copyright 2002, 2004 
43  * University Corporation for Advanced Internet Development, Inc. 
44  * All rights reserved
45  * [Thats all we have to say to protect ourselves]
46  * Your permission to use this code is governed by "The Shibboleth License".
47  * A copy may be found at http://shibboleth.internet2.edu/license.html
48  * [Nothing in copyright law requires license text in every file.]
49  */
50 package edu.internet2.middleware.shibboleth.serviceprovider;
51
52 import java.util.Map;
53
54 /**
55  * <p>An interface to be implemented by any Plug-In cache Session Cache.
56  * </p><p>
57  * To create a cache, write an implementation class for this interface
58  * and call SessionMananger.setSessionCache(...) passing the cache 
59  * implementation object. While the cache can be loaded as a Shibboleth
60  * Service Provider plugin, it can also be loaded, configured, and attached
61  * to the class using J2EE (web.xml) or other Framework (Spring, ...) services.
62  * </p>
63  * 
64  * <p>Restriction: There can be only one.</p>
65  * 
66  * @author Howard Gilbert
67  */
68 /**
69  * @author Howard Gilbert
70  */
71 public interface SessionCache {
72         
73         /**
74          * <p>Find a Session in the cache
75          * </p><p>
76          * This entry point is only meaningful if the cache is being
77          * used for load balancing. Then it finds Sessions created
78          * by another host in the cluster. In a single-host cache
79          * you can always return null because all Sessions will be
80          * in memory, and an id not found in memory will never be
81          * in the cache.</p>
82          * 
83          * @param sessionId Key string, typically the Cookie value
84          * @return Session object from cache
85          */
86         public Session find(String sessionId);
87         
88         public void add(Session s);
89         
90         public void update(Session s);
91         
92         public void remove(Session s);
93         
94         /**
95          * Scan all Sessions in the cache and store them in
96          * the in memory collection. Typically called after
97          * a reboot to restore prior sessions.
98          * 
99          * @param sessions The in memory map to be loaded.
100          */
101         public void reload(Map sessions);
102         
103         public void close();
104         
105 }