001: /*
002: * Copyright 2004-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.springframework.webflow.conversation;
017:
018: /**
019: * A service interface for working with state associated with a single logical
020: * user interaction called a "conversation" in the scope of a single request.
021: * Conversation objects are not thread safe and should not be shared among
022: * multiple threads.
023: * <p>
024: * A conversation provides a "task" context that is begun and eventually ends.
025: * Between the beginning and the end attributes can be placed in and read from a
026: * conversation's context.
027: * <p>
028: * A conversation needs to be {@link #lock() locked} to obtain exclusive
029: * access to it before it can be manipulated. Once manipulation is finished, you need to
030: * {@link #unlock() unlock} the conversation. So code interacting with a
031: * conversation always looks like this:
032: *
033: * <pre>
034: * Conversation conv = ...;
035: * conv.lock();
036: * try {
037: * // work with the Conversation object, calling methods like
038: * // getAttribute(), putAttribute() and end()
039: * }
040: * finally {
041: * conv.unlock();
042: * }
043: * </pre>
044: *
045: * <p>
046: * Note that the attributes associated with a conversation are not
047: * "conversation scope" as defined for a flow execution. They can be
048: * any attributes, possibly technical in nature, associated with the
049: * conversation.
050: *
051: * @author Keith Donald
052: * @author Erwin Vervaet
053: */
054: public interface Conversation {
055:
056: /**
057: * Returns the unique id assigned to this conversation. This id remains the
058: * same throughout the life of the conversation. This method can be safely
059: * called without owning the lock of this conversation.
060: * @return the conversation id
061: */
062: public ConversationId getId();
063:
064: /**
065: * Lock this conversation. May block until the lock is available, if someone
066: * else has acquired the lock.
067: */
068: public void lock();
069:
070: /**
071: * Returns the conversation attribute with the specified name.
072: * You need to aquire the lock on this conversation before calling this method.
073: * @param name the attribute name
074: * @return the attribute value
075: */
076: public Object getAttribute(Object name);
077:
078: /**
079: * Puts a conversation attribute into this context.
080: * You need to aquire the lock on this conversation before calling this method.
081: * @param name the attribute name
082: * @param value the attribute value
083: */
084: public void putAttribute(Object name, Object value);
085:
086: /**
087: * Removes a conversation attribute.
088: * You need to aquire the lock on this conversation before calling this method.
089: * @param name the attribute name
090: */
091: public void removeAttribute(Object name);
092:
093: /**
094: * Ends this conversation. This method should only be called once to
095: * terminate the conversation and cleanup any allocated resources.
096: * You need to aquire the lock on this conversation before calling this method.
097: */
098: public void end();
099:
100: /**
101: * Unlock this conversation, making it available to others for
102: * manipulation.
103: */
104: public void unlock();
105: }
|