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: 706640 $ $Date: 2008-10-21 14:44:05 +0000 (Tue, 21 Oct 2008) $
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 }