001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: SessionProvider.java,v 1.7 2008/06/25 05:47:28 qcheng Exp $
026 *
027 */
028
029package com.sun.identity.plugin.session;
030
031import java.util.Map;
032import javax.servlet.http.HttpServletRequest;
033import javax.servlet.http.HttpServletResponse;
034
035/**
036 * Interface used for creating sessions, and for accessing session
037 * information.
038 *
039 * @supported.all.api
040 */
041public interface SessionProvider {
042
043    /**
044     * This constant string is used in the implementation and calling
045     * of the first method for passing a realm name in a map.
046     */
047    String REALM = "realm";
048
049    /**
050     * This constant string is used in the implementation and calling
051     * of the first method for passing a principal name in a map.
052     */
053    String PRINCIPAL_NAME = "principalName";
054
055    /**
056     * This constant string is used in the implementation and calling
057     * of the first method for passing an authentication level in a map.
058     */
059    String AUTH_LEVEL = "AuthLevel";
060
061    /**
062     * This constant string is used as a property name to indicate
063     * the authentication method. Typically it is used as the second
064     * name parameter in the <code>getProperty</code> method.
065     */
066    String AUTH_METHOD = "authMethod";
067
068    /**
069     * This constant string is used as a property name to indicate
070     * the authentication instant. Typically it is used as the second
071     * name parameter in the <code>getProperty</code> method.
072     */
073    String AUTH_INSTANT = "authInstant";
074  
075    /**
076     * This constant string is used as a property name to indicate
077     * the client host.
078     */
079    String HOST = "Host";
080
081    /**
082     * This constant string is used as a property name to indicate
083     * the client hostname.
084     */
085    String HOST_NAME = "HostName";
086
087    /** 
088     * Meaningful only for Service Provider side, the implementation of this
089     * method will create a local session for the local user identified by
090     * the information in the map. The underline mechanism of the
091     * session creation and management is application specific.
092     * For example, it could be cookie setting or URL rewriting, which 
093     * is expected to be done by the implementation of this method.
094     * Note that only the first input parameter is mandatory. Normally,
095     * at least one of the last two parameters should not be null
096     * 
097     * @param info a Map with keys and values being of type String; The
098     *        keys will include <code>SessionProvider.PRINCIPAL_NAME</code>
099     *        (returned from <code>SPAccountMapper</code>),
100     *        <code>SessionProvider.REALM</code>, 
101     *        <code>SessionProvider.AUTH_LEVEL</code>, 
102     *        <code>SessionProvider.AUTH_INSTANT</code>, and may include
103     *        <code>"resourceOffering"</code> and/or <code>"idpEntityID"</code>;
104     *        The implementation of this method could choose to set some of
105     *        the information contained in the map into the newly created
106     *        Session by calling <code>setProperty()</code>, later the target
107     *        application may consume the information. 
108     * @param request the <code>HttpServletRequesa</code>t the user made to
109     *        initiate the Single Sign On; Note that it should be the initial
110     *        request coming from the browser as opposed to the possible
111     *        subsequent back-channel HTTP request for delivering
112     *        SOAP message.
113     * @param response the <code>HttpServletResponse</code> that will be sent
114     *        to the user (for example it could be used to set a cookie).
115     * @param targetApplication the original resource that was requested
116     *        as the target of the Single Sign On by the end user; If needed,
117     *        this String could be modified, e.g., by appending query
118     *        string(s) or by URL rewriting, hence this is an in/out parameter.
119     * @return the newly created local user session.
120     * @throws SessionException if an error occurred during session creation.
121     */ 
122    public Object createSession(
123        Map info,                       // in
124        HttpServletRequest request,     // in
125        HttpServletResponse response,   // in/out
126        StringBuffer targetApplication  // in/out
127    ) throws SessionException;
128
129    /**
130     * Returns the corresponding session object.
131     * May be used by both SP and IDP side for getting an existing
132     * session given an session ID.
133     * @param sessionID the unique session handle.
134     * @return the corresponding session object.
135     * @throws SessionException if an error occurred during session
136     * retrieval.
137     */
138    public Object getSession(String sessionID)
139        throws SessionException;
140
141    /**
142     * Returns the corresponding session object.
143     * May be used by both SP and IDP side for getting an existing
144     * session given a browser initiated HTTP request.
145     * @param request the browser initiated HTTP request.
146     * @return the corresponding session object.
147     * @throws SessionException if an error occurred during session
148     * retrieval.
149     */
150    public Object getSession(HttpServletRequest request)
151        throws SessionException;
152
153    /**
154     * May be used by both SP and IDP side to invalidate a session.
155     * In case of SLO with SOAP, the last two input parameters
156     * would have to be null
157     * @param session the session to be invalidated
158     * @param request the browser initiated HTTP request.
159     * @param response the HTTP response going back to browser.
160     * @throws SessionException if an error occurred during session
161     * retrieval.     
162     */
163    public void invalidateSession(
164        Object session,
165        HttpServletRequest request,   // optional input
166        HttpServletResponse response  // optional input
167    ) throws SessionException;
168
169    /**
170     * Returns <code>true</code> if the session is valid.
171     * This is useful for toolkit clean-up thread.
172     *
173     * @param session Session object.
174     * @return <code>true</code> if the session is valid.
175     */
176    public boolean isValid(Object session)
177        throws SessionException;
178
179    /**
180     * Returns session ID.
181     * The returned session ID should be unique and not 
182     * change during the lifetime of this session
183     *
184     * @return session ID.
185     */
186    public String getSessionID(Object session);
187
188    /**
189     * Returns princiapl name, or user name given the session
190     * object. 
191     * @param session Session object.
192     * @return principal name, or user name.
193     * @throws SessionException if getting the principal name
194     * causes an error.
195     */
196    public String getPrincipalName(Object session)
197        throws SessionException;
198        
199    /**
200     * Stores a property in the session object. This is an
201     * optional method.
202     *
203     * @param session the session object.
204     * @param name the property name.
205     * @param values the property values.
206     * @throws UnsupportedOperationException if this method
207     * is not supported.
208     * @throws SessionException if setting the property in
209     * the session causes an error.
210     */
211    public void setProperty(
212        Object session,
213        String name,
214        String[] values
215    ) throws UnsupportedOperationException, SessionException;
216
217    /**
218     * Returns property value of a session object. This
219     * is an optional method.
220     *
221     * @param session the session object.
222     * @param name the property name.
223     * @return the property values.
224     * @throws UnsupportedOperationException if this method
225     * is not supported.
226     * @throws SessionException if getting the property from
227     * the session causes an error.
228     */
229    public String[] getProperty(Object session, String name)
230        throws UnsupportedOperationException, SessionException;
231
232    /**
233     * Returns rewritten URL.
234     * Rewrites an URL with session information in case
235     * cookie setting is not supported.
236     *
237     * @param session the session object.
238     * @param URL the URL to be rewritten.
239     * @return the rewritten URL.
240     * @throws SessionException if rewritting the URL
241     * causes an error.
242     */
243    public String rewriteURL(Object session, String URL)
244        throws SessionException;
245    
246    /**
247     * Registers a listener for the session. This is an optional
248     * method.
249     * @param session the session object.
250     * @param listener listener for the session invalidation event.
251     * @throws UnsupportedOperationException if this method
252     * is not supported.
253     * @throws SessionException if adding the listener in the
254     * session causes an error.
255     */
256    public void addListener(Object session, SessionListener listener)
257        throws UnsupportedOperationException, SessionException;
258    
259    /**
260     * Sets a load balancer cookie in the suppled HTTP response. The load
261     * balancer cookie's value is set per server instance and is used to
262     * support sticky load balancing.
263     * 
264     * @param response the <code>HttpServletResponse</code> that will be sent
265     *        to the user.
266     */
267    public void setLoadBalancerCookie(HttpServletResponse response);
268
269    /**
270     * Returns the time left for this session in seconds.
271     * @param session Session object.
272     * @return The time left for this session.
273     * @exception A SessionException is thrown if the session reached its maximum
274     * session time, or the session was destroyed, or there was an error during
275     * communication with session service.
276     */
277    public long getTimeLeft(Object session) throws SessionException; 
278}
279