ingo@100: /*
ingo@100:  * Copyright (c) 2010 by Intevation GmbH
ingo@100:  *
ingo@100:  * This program is free software under the LGPL (>=v2.1)
ingo@100:  * Read the file LGPL.txt coming with the software for details
ingo@100:  * or visit http://www.gnu.org/licenses/ if it does not exist.
ingo@100:  */
ingo@100: 
sascha@32: package de.intevation.artifacts;
sascha@32: 
sascha@78: /**
sascha@78:  * Instances of this interface are given to feed(), advance(), describe()
sascha@78:  * and out() to enable the artifact to communicate with the runtime system.
sascha@78:  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
sascha@78:  */
sascha@32: public interface CallContext
sascha@32: {
sascha@245:     interface Listener {
sascha@245:         void init(CallContext callContext);
sascha@245:         void close(CallContext callContext);
sascha@245:     }
sascha@245: 
sascha@78:     /**
sascha@78:      * Constant to signal that nothing should be done
sascha@78:      * with the artifact after method return.
sascha@78:      */
sascha@32:     int NOTHING    = 0;
sascha@78:     /**
sascha@78:      * Constant to signal that the database timestamp
sascha@78:      * should be updated after method return.
sascha@78:      */
sascha@32:     int TOUCH      = 1;
sascha@78:     /**
sascha@78:      * Constant to signal that the artifact should be stored
sascha@78:      * after method return.
sascha@78:      */
sascha@32:     int STORE      = 2;
sascha@78:     /**
sascha@78:      * Constant to signal that the artifact fork a backgroud thread
sascha@78:      * and should be hold in memory till it signals that it has
sascha@78:      * finished its operation.
sascha@78:      */
sascha@32:     int BACKGROUND = 3;
sascha@32:     // int DELETE     = 4;
sascha@32:     // int FOREVER    = 5;
sascha@32: 
sascha@78:     /**
sascha@78:      * This method may be called from feed(), describe(), advance()
sascha@78:      * and out to signal what should happend with artefact after
sascha@78:      * the current method call returns.
sascha@78:      * @param action Valid values are NOTHING, TOUCH, STORE, BACKGROUND.
sascha@78:      */
sascha@32:     void afterCall(int action);
sascha@32: 
sascha@78:     /**
sascha@78:      * When send to background with a afterCall(BACKGROUND) this
sascha@78:      * method is to be called from the background thread to signal
sascha@78:      * that the background operation has ended.
sascha@78:      * @param action Same semantics as in afterCall.
sascha@78:      */
sascha@32:     void afterBackground(int action);
sascha@32: 
sascha@78:     /**
sascha@78:      * Access to the global context of the runtime system.
sascha@78:      * @return The global context.
sascha@78:      */
sascha@32:     Object globalContext();
sascha@48: 
sascha@78:     /**
sascha@78:      * Access to the artifact database itself.
sascha@78:      * @return The database.
sascha@78:      */
ingo@66:     ArtifactDatabase getDatabase();
ingo@66: 
sascha@78:     /**
sascha@78:      * The meta data of the current call. Used to transport
sascha@78:      * language preferences of the callee e.g.
sascha@78:      * @return The meta information of this call.
sascha@78:      */
sascha@48:     CallMeta getMeta();
sascha@86: 
sascha@78:     /**
sascha@78:      * Each call context has a clipboard.
sascha@78:      * getContextValue is used to fetch data from this board.
sascha@78:      * @param key Key of the requested item.
sascha@78:      * @return The value stored for the secified value, null if
sascha@78:      *         no item with this key exists.
sascha@78:      */
sascha@58:     Object getContextValue(Object key);
sascha@58: 
sascha@78:     /**
sascha@78:      * Each call context has a clipboard.
sascha@78:      * putContextValue is used to store a key/value pair onto this board.
sascha@78:      * @param key   The key of the pair
sascha@78:      * @param value The value of the pair.
sascha@78:      * @return The formerly stored value under the given key.
sascha@78:      */
sascha@58:     Object putContextValue(Object key, Object value);
ingo@84: 
ingo@84:     /**
ingo@84:      * Returns the time to live of the current artifact.
ingo@84:      * @return The time to live of the current artifact.
ingo@84:      */
ingo@84:     Long getTimeToLive();
sascha@32: }
sascha@85: // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :