View Javadoc

1   /* Copyright 2004 Acegi Technology Pty Limited
2    *
3    * Licensed under the Apache License, Version 2.0 (the "License");
4    * you may not use this file except in compliance with the License.
5    * You may obtain a copy of the License at
6    *
7    *     http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  
16  package org.acegisecurity.providers.cas;
17  
18  /***
19   * Caches CAS service tickets and CAS proxy tickets for stateless connections.
20   * 
21   * <p>
22   * When a service ticket or proxy ticket is validated against the CAS server,
23   * it is unable to be used again. Most types of callers are stateful and are
24   * associated with a given <code>HttpSession</code>. This allows the
25   * affirmative CAS validation outcome to be stored in the
26   * <code>HttpSession</code>, meaning the removal of the ticket from the CAS
27   * server is not an issue.
28   * </p>
29   * 
30   * <P>
31   * Stateless callers, such as remoting protocols, cannot take advantage of
32   * <code>HttpSession</code>. If the stateless caller is located a significant
33   * network distance from the CAS server, acquiring a fresh service ticket or
34   * proxy ticket for each invocation would be expensive.
35   * </p>
36   * 
37   * <P>
38   * To avoid this issue with stateless callers, it is expected stateless callers
39   * will obtain a single service ticket or proxy ticket, and then present this
40   * same ticket to the Acegi Security System secured application on each
41   * occasion. As no <code>HttpSession</code> is available for such callers, the
42   * affirmative CAS validation outcome cannot be stored in this location.
43   * </p>
44   * 
45   * <P>
46   * The <code>StatelessTicketCache</code> enables the service tickets and proxy
47   * tickets belonging to stateless callers to be placed in a cache. This
48   * in-memory cache stores the <code>CasAuthenticationToken</code>, effectively
49   * providing the same capability as a <code>HttpSession</code> with the ticket
50   * identifier being the key rather than a session identifier.
51   * </p>
52   * 
53   * <P>
54   * Implementations should provide a reasonable timeout on stored entries, such
55   * that the stateless caller are not required to unnecessarily acquire fresh
56   * CAS service tickets or proxy tickets.
57   * </p>
58   *
59   * @author Ben Alex
60   * @version $Id: StatelessTicketCache.java,v 1.3 2005/11/17 00:55:47 benalex Exp $
61   */
62  public interface StatelessTicketCache {
63      //~ Methods ================================================================
64  
65      /***
66       * Retrieves the <code>CasAuthenticationToken</code> associated with the
67       * specified ticket.
68       * 
69       * <P>
70       * If not found, returns a
71       * <code>null</code><code>CasAuthenticationToken</code>.
72       * </p>
73       *
74       * @return the fully populated authentication token
75       */
76      public CasAuthenticationToken getByTicketId(String serviceTicket);
77  
78      /***
79       * Adds the specified <code>CasAuthenticationToken</code> to the cache.
80       * 
81       * <P>
82       * The {@link CasAuthenticationToken#getCredentials()} method is used to
83       * retrieve the service ticket number.
84       * </p>
85       *
86       * @param token to be added to the cache
87       */
88      public void putTicketInCache(CasAuthenticationToken token);
89  
90      /***
91       * Removes the specified ticket from the cache, as per  {@link
92       * #removeTicketFromCache(String)}.
93       * 
94       * <P>
95       * Implementations should use {@link
96       * CasAuthenticationToken#getCredentials()} to obtain the ticket and then
97       * delegate to to the  {@link #removeTicketFromCache(String)} method.
98       * </p>
99       *
100      * @param token to be removed
101      */
102     public void removeTicketFromCache(CasAuthenticationToken token);
103 
104     /***
105      * Removes the specified ticket from the cache, meaning that future calls
106      * will require a new service ticket.
107      * 
108      * <P>
109      * This is in case applications wish to provide a session termination
110      * capability for their stateless clients.
111      * </p>
112      *
113      * @param serviceTicket to be removed
114      */
115     public void removeTicketFromCache(String serviceTicket);
116 }