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 }