/* Execution.java{{IS_NOTE	Purpose:			Description:			History:		Fri Jun  3 17:55:01     2005, Created by tomyeh}}IS_NOTECopyright (C) 2005 Potix Corporation. All Rights Reserved.{{IS_RIGHT	This program is distributed under GPL Version 2.0 in the hope that	it will be useful, but WITHOUT ANY WARRANTY.}}IS_RIGHT*/package org.zkoss.zk.ui;import java.util.Map;import java.io.Reader;import java.io.Writer;import java.io.IOException;import java.security.Principal;import org.zkoss.xel.VariableResolver;import org.zkoss.idom.Document;import org.zkoss.web.servlet.Servlets;import org.zkoss.web.servlet.http.Encodes;import org.zkoss.zk.ui.event.Event;import org.zkoss.zk.ui.metainfo.PageDefinition;import org.zkoss.zk.ui.metainfo.LanguageDefinition;import org.zkoss.zk.xel.Evaluator;import org.zkoss.zk.au.AuResponse;/** * An execution of a client request (e.g., ServletRequest). * When a request sent from a client, the server constructs * a {@link Execution} * object to hold execution relevant info, and then serves the request * thru this execution. * * <p>A client request, e.g., HttpServletRequest, might consist of * multiple ZK request ({@link org.zkoss.zk.au.AuRequest}). * However, these ZK requests * must target the same desktop of pages ({@link Page}). * * <p>Because a request might come from HTTP or other protocol, Execution * also serves as an isolation layer. * * @author tomyeh * @see Page */public interface Execution  {	/** Returns the desktop for this execution.	 * Each execution is against exactly one desktop.	 */	public Desktop getDesktop();	/** Returns whether this execution is asynchronous updating the	 * specified page (thru ZK Update Engine).	 *	 * @return whether the specified page is being asynchronous updated	 * by this execution.	 * If the specified page is null, this method returns	 * whether this execution is asynchronous updating a page	 * (rather than creating/loading a new page).	 * Each execution remembers the page being creating.	 * All other pages are consided as being asynchronous updated.	 */	public boolean isAsyncUpdate(Page page);	/** Returns an array of String objects containing all of the values	 * the given request parameter has, or null if the parameter does not exist.	 */	public String[] getParameterValues(String name);	/** Returns the value of a request parameter as a String,	 * or null if the parameter does not exist	 */	public String getParameter(String name);	/** Returns a Map of the parameters of this request.	 * Request parameters are extra information sent with the request.	 */	public Map getParameterMap();	/** Returns the evaluator (never null).	 * It is usually used to parse the expression into {@link org.zkoss.xel.Expression}	 * or used with {@link org.zkoss.zk.xel.ExValue}.	 * for performance improvement.	 *	 * @param page the page that this evaluator is associated.	 * If null, the current page and then the first page is assumed.	 * @param expfcls the implementation of {@link org.zkoss.xel.ExpressionFactory},	 * or null to use the default ({@link org.zkoss.zk.ui.util.Configuration#getExpressionFactoryClass}.	 * @since 3.0.0	 */	public Evaluator getEvaluator(Page page, Class expfcls);	/** Returns the evaluator of the current execution.	 * It is a shortcut of getEvaluator(comp != null ? comp.getPage(): null)	 *	 * @param comp the component to retrieve the page for the evaluator	 * @param expfcls the implementation of {@link org.zkoss.xel.ExpressionFactory},	 * or null to use the default ({@link org.zkoss.zk.ui.util.Configuration#getExpressionFactoryClass}.	 * @since 3.0.0	 */	public Evaluator getEvaluator(Component comp, Class expfcls);	/** Evluates the specified expression with ${link #getVariableResolver}	 * and {@link Page#getFunctionMapper} of the page of the specified	 * component.	 *	 * <p>The function mapper is retrieved from component's page's function	 * mapper ({@link Page#getFunctionMapper}).	 * If null, the current page, if any, is used to retrieve	 * the mapper.	 *	 * <p>For better performance, you can use the instance returned by	 *{@link #getEvaluator} to parse and cached the parsed expression.	 * {@link org.zkoss.zk.xel.ExValue} is a utility class to simply	 * the task.	 *	 * @param comp used as the self variable and to retrieve the function	 * mapper. Ignored if null.	 * @see #getVariableResolver	 * @see #getEvaluator	 */	public Object evaluate(Component comp, String expr, Class expectedType);	/** Evluates the specified expression with ${link #getVariableResolver}	 * and {@link Page#getFunctionMapper} of the specified	 * page.	 *	 * <p>The function mapper is retrieved from component's page's function	 * mapper ({@link Page#getFunctionMapper}).	 * If null, the current page, if any, is used to retrieve	 * the mapper.	 *	 * <p>For better performance, you can use the instance returned by	 *{@link #getEvaluator} to parse and cached the parsed expression.	 * {@link org.zkoss.zk.xel.ExValue} is a utility class to simply	 * the task.	 *	 * @param page used as the self variable and to retrieve the function	 * mapper. Ignored if null.	 * @see #getVariableResolver	 * @see #getEvaluator	 */	public Object evaluate(Page page, String expr, Class expectedType);	/** Returns the variable resolver for this execution, or null if not	 * available.	 *	 * <p>Note: the resolver is similar to PageContext's if this execution	 * is caused by a HTTP request.	 * @see #evaluate(Component,String,Class)	 */	public VariableResolver getVariableResolver();	/** Queues an event to the current execution.	 * The event will be processed (as if it is sent from the client).	 */	public void postEvent(Event evt);	/** Whether to overwrite uri if both uri and params contain the same	 * parameter.	 */	public static final int OVERWRITE_URI = Servlets.OVERWRITE_URI;	/** Whether to ignore params if both uri and params contain the same	 * parameter.	 */	public static final int IGNORE_PARAM = Servlets.IGNORE_PARAM;	/** Whether to append params if both uri and params contain the same	 * parameter. In other words, they both appear as the final query string.	 */	public static final int APPEND_PARAM = Servlets.APPEND_PARAM;	/** Whether the specified parameters shall be passed thru the request's	 * attribute called arg.	 */	public static final int PASS_THRU_ATTR = Servlets.PASS_THRU_ATTR;	/** Includes a page.	 *	 * @param writer the output to write. If null, the response's default	 * writer is used.	 * @param page the page's uri; null to denote the same request	 * @param mode one of {@link #OVERWRITE_URI}, {@link #IGNORE_PARAM},	 * {@link #APPEND_PARAM} and {@link #PASS_THRU_ATTR}.	 * It defines how to handle if both uri and params contains	 * the same parameter.	 * mode is used only if both uri contains query string and params is	 * not empty.	 */	public void include(Writer writer, String page, Map params, int mode)	throws IOException;	/** A shortcut of include(null, page, null, 0).	 */	public void include(String page)	throws IOException;	/** Forwards to another page.	 *	 * <p>Note: this method can be called only when loading a page.	 * Use {@link #sendRedirect(String)} instead if you want to change	 * to another desktop when processing a request from the client.	 *	 * @param writer the output to write. If null, the response's default	 * writer is used.	 * @param page the page's uri; null to denote the same request	 * @param mode one of {@link #OVERWRITE_URI}, {@link #IGNORE_PARAM},	 * {@link #APPEND_PARAM} and {@link #PASS_THRU_ATTR}.	 * It defines how to handle if both uri and params contains	 * the same parameter.	 * mode is used only if both uri contains query string and params is	 * not empty.	 */	public void forward(Writer writer, String page, Map params, int mode)	throws IOException;	/** A shortcut of forward(null, page, null, 0).	 */	public void forward(String page)	throws IOException;	/** Returns whether the execution is voided.	 * By void we mean the request is taken charged by other servlet.	 * The execution shall not do anything more. In other words,	 * the execution is avoided and won't generate any ouput.	 *	 * <p>The common cause of being voided is the invocation of	 * {@link #forward}.	 *	 * @since 2.4.0	 */	public boolean isVoided();	/** Sets whether the execution is voided.	 * By void we mean the request is taken charged by other servlet.	 *	 * <p>If you invoke {@link #forward}, this method is called automatically	 * with true. Thus, you rarely need to invoke this method, unless	 * you forward to other servlet by use javax.servlet.RequestDispatcher	 * directly.	 *	 * @since 2.4.1	 */	public void setVoided(boolean voided);	/** Returns whether this execution is included by some other pages.	 */	public boolean isIncluded();	/** Returns whether the execution is forwarded from other pages.	 * @since 2.4.0	 */	public boolean isForwarded();	/** Converts the specified URI to an absolute URI, if uri is related	 * and the current execution is not included ({@link #isIncluded}).	 *	 * <p>Note: an asynchrous update is processed by the update servlet.	 * It is different from the servlet for rendering the ZUML page.	 * In other words, a relative URI won't be interpreted correctly,	 * so you have to invoke this method to convert them if necessary.	 *	 * <p>In addtions, RequestDispatcher.include doesn't handle related URI	 * well.