001    /**
002     *
003     *  Licensed to the Apache Software Foundation (ASF) under one or more
004     *  contributor license agreements.  See the NOTICE file distributed with
005     *  this work for additional information regarding copyright ownership.
006     *  The ASF licenses this file to You under the Apache License, Version 2.0
007     *  (the "License"); you may not use this file except in compliance with
008     *  the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     *  Unless required by applicable law or agreed to in writing, software
013     *  distributed under the License is distributed on an "AS IS" BASIS,
014     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     *  See the License for the specific language governing permissions and
016     *  limitations under the License.
017     */
018    package org.apache.geronimo.clustering;
019    
020    /**
021     * Represents a local SessionManager.
022     * <p>
023     * A local SessionManager works collaboratively with remote SessionManagers to manage Session instances. A local 
024     * SessionMananger along with its associated remote SessionManagers are a single space where Session instances live.
025     * In this space, each Session is ensured to have a unique sessionId. This contract is enforced during creation of
026     * a Session instance by a local SessionManager. A Session in this space is preemptively migrated from one local 
027     * SessionManager to another. The interposition of a ClusteredInvocation between a Client and the Session he wants to
028     * access ensures that at any point in time a Session is uniquely instantiated once cluster wide. Clients can
029     * receive migration callbacks via the registration of SessionListener.
030     *
031     * @version $Rev$ $Date$
032     */
033    public interface SessionManager {
034        
035        /**
036         * Creates a Session having the specified sessionId.
037         * 
038         * @param sessionId Unique identifier of the Session instance.
039         * @return Session instance.
040         * @throws SessionAlreadyExistException Thrown when the provided sessiondId already exists in the Session space
041         * of this local SessionManager and its associated remote SessionManagers.
042         */
043        Session createSession(String sessionId) throws SessionAlreadyExistException;
044        
045        /**
046         * Registers a migration listener. 
047         */
048        void registerListener(SessionListener listener);    
049    
050        /**
051         * Unregisters a migration listener.
052         */
053        void unregisterListener(SessionListener listener);    
054    
055        /**
056         * Gets the Node hosting this local SessionManager.
057         * 
058         * @return Hosting Node.
059         */
060        Node getNode();
061    
062    }