001    /**
002     *  Licensed to the Apache Software Foundation (ASF) under one or more
003     *  contributor license agreements.  See the NOTICE file distributed with
004     *  this work for additional information regarding copyright ownership.
005     *  The ASF licenses this file to You under the Apache License, Version 2.0
006     *  (the "License"); you may not use this file except in compliance with
007     *  the License.  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     *  Unless required by applicable law or agreed to in writing, software
012     *  distributed under the License is distributed on an "AS IS" BASIS,
013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     *  See the License for the specific language governing permissions and
015     *  limitations under the License.
016     */
017    package org.apache.geronimo.clustering;
018    
019    import java.util.Map;
020    
021    /**
022     * Represents a clustered session.
023     * <p>
024     * A Session is created by a SessionManager and is uniquely identified by its sessionId. More accurately, this 
025     * sessionId is unique within the set of SessionManagers from which this Session has been sourced. If two Sessions 
026     * have the same sessionId, then a client can be sure that they have been created from two distinct set of 
027     * SessionManagers.
028     * <p>
029     * A Session provides Map like contracts to manipulate state information. State information must be Serializable as
030     * it may be marshalled automatically by the underpinning local SessionManager. At any given point of time, a Session
031     * is uniquely "instantiated" once cluster wide. Also, cluster wide accesses to a given Session are 
032     * ensured to be serialized by the set of SessionManagers from which the Session has been sourced. The interposition
033     * of a ClusteredInvocation between a client and the Session this client would like to access enforces unique
034     * instantiation and access serialization cluster wide for a given Session.
035     *
036     * @version $Rev$ $Date$
037     */
038    public interface Session {
039        
040        /**
041         * Gets the sessionId.
042         * 
043         * @return sessionId.
044         */
045        String getSessionId();
046    
047        /**
048         * Map like contract to manipulate state information.
049         */
050        Object addState(String key, Object value);
051    
052        /**
053         * Map like contract to manipulate state information.
054         */
055        Object getState(String key);
056    
057        /**
058         * Map like contract to manipulate state information.
059         */
060        Object removeState(String key);
061        
062        /**
063         * Map like contract to manipulate state information.
064         * <p>
065         * The returned Map is mutable and is backed by the session.
066         */
067        Map getState();
068        
069        /**
070         * Releases the session.
071         * <p>
072         * When a Session is released, it is released from the underlying set of SessionManagers. In other words, its
073         * sessionId is unknown and its state is permanently lost. After the release of a Session, the behavior of
074         * the other methods is undefined.
075         */
076        void release();
077        
078        /**
079         * Notifies the session that state accesses are now completed. 
080         * <p>
081         * When state accesses end, the underlying local SessionManager may decide to replicate synchronously or
082         * asynchronously the current state to remote SessionManagers.
083         */
084        void onEndAccess();
085    }