/* 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 javax.servlet.jsp.el.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.util.Evaluator;import org.zkoss.zk.ui.metainfo.PageDefinition;import org.zkoss.zk.ui.metainfo.LanguageDefinition;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 extends Evaluator {	/** Returns the desktop for this execution.	 * Each execution is against exactly one desktop.	 */	public Desktop getDesktop();	/** Returns whether this execution does asynchronous updates for the	 * specified page (thru zkau).	 *	 * @return false if page is null, or page is not the page being	 * asynchronous updated.	 * Each execution remembers what page is being creating (or none being	 * created). 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();	/** 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.	 *	 * @param comp used as the self variable and to retrieve the function	 * mapper. Ignored if null.	 * @see #getVariableResolver	 */	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.	 *	 * @param page used as the self variable and to retrieve the function	 * mapper. Ignored if null.	 * @see #getVariableResolver	 */	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 this execution is included some other pages.	 */	public boolean isIncluded();	/** 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.	 *	 * @param skipInclude whether not to convert to an absolute URI if	 * the current page is included by another page.	 * When use the include directive, skipInclude shall be true.	 */	public String toAbsoluteURI(String uri, boolean skipInclude);	/** Encodes an URL.	 *	 * <p>It resolves "*" contained in URI, if any, to the proper Locale,	 * and the browser code.	 * Refer to {@link Servlets#locate(ServletContext, ServletRequest, String, Locator)}	 * for details. 	 */	public String encodeURL(String uri);	/** Returns a java.security.Principal object containing the name of the	 * current authenticated user.	 * If the user has not been authenticated, the method returns null.	 */	public Principal getUserPrincipal();	/** Returns a boolean indicating whether the authenticated user is	 * included in the specified logical "role". Roles and role membership	 * can be defined using deployment descriptors.	 * If the user has not been authenticated, the method returns false.	 *	 * @param role a String specifying the name of the role	 */	public boolean isUserInRole(String role);	/** Returns the login of the user making this request, if the user has	 * been authenticated, or null if the user has not been authenticated.	 * Whether the user name is sent with each subsequent request depends on	 * the browser and type of authentication.	 */	public String getRemoteUser();	/** Returns the fully qualified name of the client or the last proxy	 * that sent the request.	 * If the engine cannot or chooses not to resolve the hostname	 * (to improve performance), this method returns the dotted-string form of	 * the IP address.	 */	public String getRemoteName();	/**  Returns the Internet Protocol (IP) address of the client or last	 * proxy that sent the request.	 */	public String getRemoteAddr();	/** Returns the host name of the server to which the request was sent.	 * It is the value of the part before ":" in the Host header value, if any,	 * or the resolved server name, or the server IP address.	 *	 * @see #getLocalName	 */	public String getServerName();	/** Returns the port number to which the request was sent.	 * It is the value of the part after ":" in the Host header value, if any,	 * or the server port where the client connection was accepted on.	 *	 * @see #getLocalPort	 */	public int getServerPort();	/** Returns the host name of the Internet Protocol (IP) interface	 * on which the request was received.	 *	 * <p>Note: it is the host name defined in the server. To retrieve the name	 * in URL, use {@link #getServerName}.	 *	 * @see #getServerName	 */	public String getLocalName();	/** Returns the Internet Protocol (IP) address of the interface on which	 * the request was received.	 */	public String getLocalAddr();	/** Returns the Internet Protocol (IP) port number of the interface on which	 * the request was received.	 *	 * @see #getServerPort	 */	public int getLocalPort();	/** Returns the portion of the request URI that indicates the context of	 * the current execution. The path starts with a "/" character but does not end with	 * a "/" character. For servlets in the default (root) context,	 * this method returns "".	 *	 * <p>If the client is not using HTTP to access, this method return "";	 *	 * @see Page#getRequestPath	 */	public String getContextPath();	//-- page utilities --//	/** Returns the page definition from the page file specified by an URI.	 *	 * <p>Implemetation Notes: this method must invoke	 * {@link org.zkoss.zk.ui.sys.UiFactory#getPageDefinition(org.zkoss.zk.ui.sys.RequestInfo, String)}	 *