//----------------------------BEGIN LICENSE----------------------------
/* 
 * Willow : the Open Source WorkFlow Project
 * Distributable under GNU LGPL license by gun.org
 *
 * Copyright (C) 2004-2010 huihoo.org 
 * Copyright (C) 2004-2010  ZosaTapo <dertyang@hotmail.com> 
 * 
 * ====================================================================
 * Project Homepage : http://www.huihoo.org/willow
 * Source Forge     : http://sourceforge.net/projects/huihoo
 * Mailing list     : willow@lists.sourceforge.net 
 */
//----------------------------END  LICENSE-----------------------------
package org.huihoo.workflow.desktop;

import java.util.Hashtable;

import org.huihoo.workflow.WorkflowException;
import org.huihoo.workflow.server.WorkflowSession;

public interface WorkflowDesktop
{
	public WorkflowSession getSession();

	public WorkflowImplementation findImplementation(String xpdlid) throws WorkflowException;
	public WorkflowImplementation[] findImplementations() throws WorkflowException;

	/**
	 * Adds a new environment property to the environment of this
	 * desktop.  If the property already exists, its value is overwritten.
	 * See class description for more details on environment properties.
	 *
	 * @param propName
	 *		the name of the environment property to add; may not be null
	 * @param propVal
	 *		the value of the property to add; may not be null
	 * @return	the previous value of the property, or null if the property was
	 *		not in the environment before
	 * @throws	WorkflowException if a workflow exception is encountered
	 *
	 * @see #getEnvironment()
	 * @see #removeFromEnvironment(String)
	 */
	public Object addToEnvironment(String propName, Object propVal) throws WorkflowException;

	/**
	 * Removes an environment property from the environment of this
	 * desktop.  See class description for more details on environment
	 * properties.
	 *
	 * @param propName
	 *		the name of the environment property to remove; may not be null
	 * @return	the previous value of the property, or null if the property was
	 *		not in the environment
	 * @throws	WorkflowException if a workflow exception is encountered
	 *
	 * @see #getEnvironment()
	 * @see #addToEnvironment(String, Object)
	 */
	public Object removeFromEnvironment(String propName) throws WorkflowException;

	/**
	 * Retrieves the environment in effect for this desktop.
	 * See class description for more details on environment properties.
	 *
	 * <p> The caller should not make any changes to the object returned:
	 * their effect on the desktop is undefined.
	 * The environment of this desktop may be changed using
	 * <tt>addToEnvironment()</tt> and <tt>removeFromEnvironment()</tt>.
	 *
	 * @return	the environment of this desktop; never null
	 * @throws	WorkflowException if a workflow exception is encountered
	 *
	 * @see #addToEnvironment(String, Object)
	 * @see #removeFromEnvironment(String)
	 */
	public Hashtable getEnvironment() throws WorkflowException;


	/**
	 * Closes this desktop.
	 * This method releases this desktop's resources immediately, instead of
	 * waiting for them to be released automatically by the garbage collector.
	 *
	 * <p> This method is idempotent:  invoking it on a desktop that has
	 * already been closed has no effect.  Invoking any other method
	 * on a closed desktop is not allowed, and results in undefined behaviour.
	 *
	 * @throws	WorkflowException if a workflow exception is encountered
	 */
	public void close() throws WorkflowException;
	
	/**
	 * Constant that holds the name of the environment property
	 * for specifying the initial desktop factory to use. The value
	 * of the property should be the fully qualified class name
	 * of the factory class that will create an initial desktop.
	 * This property may be specified in the environment parameter
	 * passed to the initial desktop constructor, an applet parameter,
	 * a system property, or an application resource file.
	 * If it is not specified in any of these sources,
	 * <tt>DesktopNotFoundException</tt> is thrown when an initial
	 * desktop is required to complete an operation.
	 *
	 * <p> The value of this constant is "workflow.desktop.factory.initial".
	 *
	 * @see #addToEnvironment(String, Object)
	 * @see #removeFromEnvironment(String)
	 * @see #APPLET
	 */
	String INITIAL_DESKTOP_FACTORY = "workflow.desktop.factory.initial";

	/**
	 * Constant that holds the name of the environment property
	 * for specifying configuration information for the service provider
	 * to use. The value of the property should contain a URL string
	 * 
	 * (e.g.     "serial://workflow_server_host[:workflow_server_port]" 
	 *  or       "object://workflow_engine_name").
	 *
	 *  This property may be specified in the environment,
	 * an applet parameter, a system property, or a resource file.
	 * If it is not specified in any of these sources,
	 * the default configuration is determined by the service provider.
	 *
	 * <p> The value of this constant is "workflow.desktop.provider.url".
	 *
	 * @see #addToEnvironment(String, Object)
	 * @see #removeFromEnvironment(String)
	 * @see #APPLET
	 */
	String PROVIDER_URL = "workflow.desktop.provider.url";

	/**
	 * Constant that holds the name of the environment property for
	 * specifying the identity of the principal for authenticating
	 * the caller to the service. The format of the principal
	 * depends on the authentication scheme.
	 * If this property is unspecified,
	 * the behaviour is determined by the service provider.
	 *
	 * <p> The value of this constant is "workflow.desktop.security.principal".
	 *
	 * @see #addToEnvironment(String, Object)
	 * @see #removeFromEnvironment(String)
	 */
	String SECURITY_PRINCIPAL = "workflow.desktop.security.principal";

	/**
	 * Constant that holds the name of the environment property for
	 * specifying the credentials of the principal for authenticating
	 * the caller to the service. The value of the property depends
	 * on the authentication scheme. For example, it could be a hashed
	 * password, clear-text password, key, certificate, and so on.
	 * If this property is unspecified,
	 * the behaviour is determined by the service provider.
	 *
	 * <p> The value of this constant is "workflow.desktop.security.credentials".
	 *
	 * @see #addToEnvironment(String, Object)
	 * @see #removeFromEnvironment(String)
	 */

	String SECURITY_CREDENTIALS = "workflow.desktop.security.credentials";

//-------------------------------------------------------------------------
// WorkflowDesktop RMI/IIOP export network address pair
//-------------------------------------------------------------------------
	String DESKTOP_IIOP_PORT = "workflow.desktop.localport";
	String DESKTOP_IIOP_ADDRESS = "workflow.desktop.localaddress";

//-------------------------------------------------------------------------
// WorkflowDesktop protocol
//-------------------------------------------------------------------------	
	String REMOTE_DESKTOP_PROTOCOL = "remote";
	String LOCAL_DESKTOP_PROTOCOL = "local";
}
