/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2014 Red Hat, Inc., and individual contributors
 * as indicated by the @author tags.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package io.undertow.server.session;

import io.undertow.server.HttpServerExchange;
import io.undertow.util.AttachmentKey;

import java.util.Set;

Interface that manages sessions.

The session manager is responsible for maintaining session state.
 As part of session creation the session manager MUST attempt to retrieve the SessionCookieConfig from the HttpServerExchange and use it to set the session cookie. The frees up the session manager from needing to know details of the cookie configuration. When invalidating a session the session manager MUST also use this to clear the session cookie. 
Author:
Stuart Douglas/**
 * Interface that manages sessions.
 * <p>
 * The session manager is responsible for maintaining session state.
 * <p>
 * As part of session creation the session manager MUST attempt to retrieve the {@link SessionCookieConfig} from
 * the {@link HttpServerExchange} and use it to set the session cookie. The frees up the session manager from
 * needing to know details of the cookie configuration. When invalidating a session the session manager MUST
 * also use this to clear the session cookie.
 *
 * @author Stuart Douglas
 */
public interface SessionManager {

    AttachmentKey<SessionManager> ATTACHMENT_KEY = AttachmentKey.create(SessionManager.class);

    
Uniquely identifies this session manager
Returns:
a unique identifier/**
     * Uniquely identifies this session manager
     * @return a unique identifier
     */
    String getDeploymentName();

    
Starts the session manager
/**
     * Starts the session manager
     */
    void start();

    
stops the session manager
/**
     * stops the session manager
     */
    void stop();

    
Creates a new session. Any SessionListeners registered with this manager will be notified of the session creation. 
 This method *MUST* call SessionConfig.findSessionId(HttpServerExchange) (io.undertow.server.HttpServerExchange)} first to determine if an existing session ID is present in the exchange. If this id is present then it must be used as the new session ID. If a session with this ID already exists then an IllegalStateException must be thrown. 

 This requirement exists to allow forwards across servlet contexts to work correctly. The session manager is responsible for making sure that a newly created session is accessible to later calls to getSession(HttpServerExchange, SessionConfig) from the same request. It is recommended that a non static attachment key be used to store the newly created session as an attachment. The attachment key must be static to prevent different session managers from interfering with each other. 
Returns:
The created session/**
     * Creates a new session. Any {@link SessionListener}s registered with this manager will be notified
     * of the session creation.
     * <p>
     * This method *MUST* call {@link SessionConfig#findSessionId(io.undertow.server.HttpServerExchange)} (io.undertow.server.HttpServerExchange)} first to
     * determine if an existing session ID is present in the exchange. If this id is present then it must be used
     * as the new session ID. If a session with this ID already exists then an {@link IllegalStateException} must be
     * thrown.
     * <p>
     * <p>
     * This requirement exists to allow forwards across servlet contexts to work correctly.
     *
     * The session manager is responsible for making sure that a newly created session is accessible to later calls to
     * {@link #getSession(io.undertow.server.HttpServerExchange, SessionConfig)} from the same request. It is recommended
     * that a non static attachment key be used to store the newly created session as an attachment. The attachment key
     * must be static to prevent different session managers from interfering with each other.
     *
     * @return The created session
     */
    Session createSession(final HttpServerExchange serverExchange, final SessionConfig sessionCookieConfig);

    
Returns:
An IoFuture that can be used to retrieve the session, or an IoFuture that will return null if not found/**
     * @return An IoFuture that can be used to retrieve the session, or an IoFuture that will return null if not found
     */
    Session getSession(final HttpServerExchange serverExchange, final SessionConfig sessionCookieConfig);

    
Retrieves a session with the given session id
Params:
sessionId – The session ID
Returns:
The session, or null if it does not exist/**
     * Retrieves a session with the given session id
     *
     * @param sessionId The session ID
     * @return The session, or null if it does not exist
     */
    Session getSession(final String sessionId);

    
Registers a session listener for the session manager
Params:
listener – The listener/**
     * Registers a session listener for the session manager
     *
     * @param listener The listener
     */
    void registerSessionListener(final SessionListener listener);

    
Removes a session listener from the session manager
Params:
listener – the listener/**
     * Removes a session listener from the session manager
     *
     * @param listener the listener
     */
    void removeSessionListener(final SessionListener listener);

    
Sets the default session timeout
Params:
timeout – the timeout/**
     * Sets the default session timeout
     *
     * @param timeout the timeout
     */
    void setDefaultSessionTimeout(final int timeout);

    
Returns the identifiers of those sessions that would be lost upon
shutdown of this node
/**
     * Returns the identifiers of those sessions that would be lost upon
     * shutdown of this node
     */
    Set<String> getTransientSessions();

    
Returns the identifiers of those sessions that are active on this
node, excluding passivated sessions
/**
     * Returns the identifiers of those sessions that are active on this
     * node, excluding passivated sessions
     */
    Set<String> getActiveSessions();

    
Returns the identifiers of all sessions, including both active and
passive
/**
     * Returns the identifiers of all sessions, including both active and
     * passive
     */
    Set<String> getAllSessions();

    
Returns the statistics for this session manager, or null, if statistics are not supported.
/**
     * Returns the statistics for this session manager, or null, if statistics are not supported.
     */
    SessionManagerStatistics getStatistics();
}