001/**
002 *   GRANITE DATA SERVICES
003 *   Copyright (C) 2006-2013 GRANITE DATA SERVICES S.A.S.
004 *
005 *   This file is part of the Granite Data Services Platform.
006 *
007 *                               ***
008 *
009 *   Community License: GPL 3.0
010 *
011 *   This file is free software: you can redistribute it and/or modify
012 *   it under the terms of the GNU General Public License as published
013 *   by the Free Software Foundation, either version 3 of the License,
014 *   or (at your option) any later version.
015 *
016 *   This file is distributed in the hope that it will be useful, but
017 *   WITHOUT ANY WARRANTY; without even the implied warranty of
018 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
019 *   GNU General Public License for more details.
020 *
021 *   You should have received a copy of the GNU General Public License
022 *   along with this program. If not, see <http://www.gnu.org/licenses/>.
023 *
024 *                               ***
025 *
026 *   Available Commercial License: GraniteDS SLA 1.0
027 *
028 *   This is the appropriate option if you are creating proprietary
029 *   applications and you are not prepared to distribute and share the
030 *   source code of your application under the GPL v3 license.
031 *
032 *   Please visit http://www.granitedataservices.com/license for more
033 *   details.
034 */
035package org.granite.client.tide;
036
037import java.util.List;
038
039/**
040 * Main interface for Tide context management
041 * The context manager is meant to be a singleton in the application and should be defined as a singleton in a DI container
042 *
043 * <pre>
044 * {@code
045 * ContextManager contextManager = new SimpleContextManager();
046 * Context context = contextManager.getContext();
047 * ...
048 * }
049 * </pre>
050 *
051 * @author William DRAI
052 */
053public interface ContextManager {
054
055    /**
056     * Get the global context
057     * @return global context
058     */
059    public Context getContext();
060
061    /**
062     * Get the context from its id
063     * @param contextId context id
064     * @return context
065     */
066    public Context getContext(String contextId);
067
068    /**
069     * Get a context from its id with the specified parent id, and create it if it does not exist
070     * @param contextId context id
071     * @param parentContextId parent context id
072     * @param create if true, create a context if not exist
073     * @return the context
074     */
075    public Context getContext(String contextId, String parentContextId, boolean create);
076
077    /**
078     * Create a context with the specified id and parent id if it does not exist
079     * @param contextId context id
080     * @param parentContextId parent context id
081     * @return the created context
082     */
083    public Context newContext(String contextId, String parentContextId);
084
085    /**
086     * Get or create the context for the specified context id and server conversation flags
087     * @param sourceContext source context
088     * @param contextId conversation context id
089     * @param wasConversationCreated true if the conversation was just created by the last request on the server
090     * @param wasConversationEnded true if the conversation was just ended by the last request on the server
091     * @return the matching context
092     */
093    public Context retrieveContext(Context sourceContext, String contextId, boolean wasConversationCreated, boolean wasConversationEnded);
094
095    /**
096     * Update the context id for an existing context
097     *
098     * @param previousContextId previous context id
099     * @param context context to update
100     */
101    public void updateContextId(String previousContextId, Context context);
102
103    /**
104     * Destroy a context
105     *
106     * @param contextId context id
107     */
108    public void destroyContext(String contextId);
109
110    /**
111     * Get a list of all conversation contexts
112     *
113     * @return list of conversation contexts
114     */
115    public List<Context> getAllContexts();
116    
117    // function forEachChildContext(parentContext:Context, callback:Function, token:Object = null):void;
118
119    /**
120     *  Destroy all contexts
121     */
122    public void destroyContexts();
123
124    /**
125     *  Destroy finished contexts and reset current pending contexts
126     */
127    public void destroyFinishedContexts();
128
129    /**
130     * Schedule a context for destruction after the next remote call
131     * @param contextId context id
132     */
133    public void addToContextsToDestroy(String contextId);
134
135    /**
136     * Deschedule destruction of context
137     * @param contextId context id
138     */
139    public void removeFromContextsToDestroy(String contextId);
140}