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: 
christian@417: import java.util.LinkedList;
felix@353: import java.util.List;
ingo@331: 
ingo@248: import org.w3c.dom.Document;
ingo@248: import org.w3c.dom.Node;
ingo@248: 
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 {
ingo@248:         void setup(Document config, Node listenerNode);
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:     /**
ingo@330:      * Returns true, if the object forked a background thread and has not
ingo@330:      * finished it yet.
ingo@330:      */
ingo@330:     boolean isInBackground();
ingo@330: 
ingo@330:     /**
ingo@331:      * Adds a background message for the current Artifact or Collection.
ingo@331:      *
ingo@331:      * @param msg The message.
ingo@331:      */
ingo@331:     void addBackgroundMessage(Message msg);
ingo@331: 
ingo@331:     /**
ingo@331:      * Returns the background messages of the current Artifact or Collection.
ingo@331:      *
ingo@331:      * @return the list of background messages.
ingo@331:      */
ingo@331:     LinkedList<Message> getBackgroundMessages();
ingo@331: 
ingo@331:     /**
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.
christian@417:      * @return The value stored for the specified 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();
felix@353: 
felix@353:     /**
felix@353:      * Get a list of DataProvider that get provide 'key' type of data to
felix@353:      * other facets.
felix@353:      */
felix@353:     public List<DataProvider> getDataProvider(Object key);
felix@353: 
felix@353:     /**
felix@353:      * Register a DataProvider that can provide 'key' type of data to
felix@353:      * other facets.
felix@353:      */
felix@353:     public Object registerDataProvider(Object key, DataProvider provider);
sascha@32: }
sascha@85: // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :