001: /* Copyright 2004 Acegi Technology Pty Limited
002: *
003: * Licensed under the Apache License, Version 2.0 (the "License");
004: * you may not use this file except in compliance with the License.
005: * You may obtain a copy of the License at
006: *
007: * http://www.apache.org/licenses/LICENSE-2.0
008: *
009: * Unless required by applicable law or agreed to in writing, software
010: * distributed under the License is distributed on an "AS IS" BASIS,
011: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: * See the License for the specific language governing permissions and
013: * limitations under the License.
014: */
015:
016: package org.acegisecurity.providers.cas;
017:
018: /**
019: * Caches CAS service tickets and CAS proxy tickets for stateless connections.
020: *
021: * <p>
022: * When a service ticket or proxy ticket is validated against the CAS server,
023: * it is unable to be used again. Most types of callers are stateful and are
024: * associated with a given <code>HttpSession</code>. This allows the
025: * affirmative CAS validation outcome to be stored in the
026: * <code>HttpSession</code>, meaning the removal of the ticket from the CAS
027: * server is not an issue.
028: * </p>
029: *
030: * <P>
031: * Stateless callers, such as remoting protocols, cannot take advantage of
032: * <code>HttpSession</code>. If the stateless caller is located a significant
033: * network distance from the CAS server, acquiring a fresh service ticket or
034: * proxy ticket for each invocation would be expensive.
035: * </p>
036: *
037: * <P>
038: * To avoid this issue with stateless callers, it is expected stateless callers
039: * will obtain a single service ticket or proxy ticket, and then present this
040: * same ticket to the Acegi Security System secured application on each
041: * occasion. As no <code>HttpSession</code> is available for such callers, the
042: * affirmative CAS validation outcome cannot be stored in this location.
043: * </p>
044: *
045: * <P>
046: * The <code>StatelessTicketCache</code> enables the service tickets and proxy
047: * tickets belonging to stateless callers to be placed in a cache. This
048: * in-memory cache stores the <code>CasAuthenticationToken</code>, effectively
049: * providing the same capability as a <code>HttpSession</code> with the ticket
050: * identifier being the key rather than a session identifier.
051: * </p>
052: *
053: * <P>
054: * Implementations should provide a reasonable timeout on stored entries, such
055: * that the stateless caller are not required to unnecessarily acquire fresh
056: * CAS service tickets or proxy tickets.
057: * </p>
058: *
059: * @author Ben Alex
060: * @version $Id: StatelessTicketCache.java 1784 2007-02-24 21:00:24Z luke_t $
061: */
062: public interface StatelessTicketCache {
063: //~ Methods ================================================================
064:
065: /**
066: * Retrieves the <code>CasAuthenticationToken</code> associated with the
067: * specified ticket.
068: *
069: * <P>
070: * If not found, returns a
071: * <code>null</code><code>CasAuthenticationToken</code>.
072: * </p>
073: *
074: * @return the fully populated authentication token
075: */
076: CasAuthenticationToken getByTicketId(String serviceTicket);
077:
078: /**
079: * Adds the specified <code>CasAuthenticationToken</code> to the cache.
080: *
081: * <P>
082: * The {@link CasAuthenticationToken#getCredentials()} method is used to
083: * retrieve the service ticket number.
084: * </p>
085: *
086: * @param token to be added to the cache
087: */
088: void putTicketInCache(CasAuthenticationToken token);
089:
090: /**
091: * Removes the specified ticket from the cache, as per {@link
092: * #removeTicketFromCache(String)}.
093: *
094: * <P>
095: * Implementations should use {@link
096: * CasAuthenticationToken#getCredentials()} to obtain the ticket and then
097: * delegate to to the {@link #removeTicketFromCache(String)} method.
098: * </p>
099: *
100: * @param token to be removed
101: */
102: 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: void removeTicketFromCache(String serviceTicket);
116: }
|