001: /* ExecutionCtrl.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Mon Jun 6 14:36:47 2005, Created by tomyeh
010: }}IS_NOTE
011:
012: Copyright (C) 2005 Potix Corporation. All Rights Reserved.
013:
014: {{IS_RIGHT
015: This program is distributed under GPL Version 2.0 in the hope that
016: it will be useful, but WITHOUT ANY WARRANTY.
017: }}IS_RIGHT
018: */
019: package org.zkoss.zk.ui.sys;
020:
021: import org.zkoss.zk.ui.Desktop;
022: import org.zkoss.zk.ui.Page;
023: import org.zkoss.zk.ui.Component;
024: import org.zkoss.zk.ui.UiException;
025: import org.zkoss.zk.ui.event.Event;
026: import org.zkoss.zk.ui.metainfo.PageDefinition;
027:
028: /**
029: * Additional interface to {@link org.zkoss.zk.ui.Execution}
030: * for implementation.
031: *
032: * <p>Application developers shall never access any of this methods.
033: *
034: * @author tomyeh
035: */
036: public interface ExecutionCtrl {
037: /** Returns the current page.
038: * Though an execution might process many pages, it processes update
039: * requests one-by-one and each update request is associated
040: * with a page.
041: *
042: * <p>Design decision: we put it here because user need not to know
043: * about the conccept of the current page.
044: *
045: * @see Desktop#getPage
046: */
047: public Page getCurrentPage();
048:
049: /** Sets the current page.
050: * Though an execution might process many pages, it processes update requests
051: * one-by-one and each update request is associated with a page.
052: */
053: public void setCurrentPage(Page page);
054:
055: /** Returns the current page definition, which is pushed when
056: * evaluating a page (from a page definition).
057: */
058: public PageDefinition getCurrentPageDefinition();
059:
060: /** Sets the current page definition.
061: * @param pgdef the page definition. If null, it means it is the same
062: * as getCurrentPage().getPageDefinition().
063: */
064: public void setCurrentPageDefinition(PageDefinition pgdef);
065:
066: /** Returns the next event queued by
067: * {@link org.zkoss.zk.ui.Execution#postEvent}, or null if no event queued.
068: */
069: public Event getNextEvent();
070:
071: /** Returns whether this execution is activated.
072: */
073: public boolean isActivated();
074:
075: /** Called when this execution is about to become the current execution
076: * {@link org.zkoss.zk.ui.Executions#getCurrent}.
077: *
078: * <p>Note: an execution might spread over several threads, so
079: * this method might be called several times to activate the states
080: * in each thread. Also, an execution might be activated before another
081: * is deactivate. For example, when a component includes another page,
082: * the second exec is activated to render the included page.
083: *
084: * <p>It is used as callback notification.
085: *
086: * <p>Note: don't throw any exception in this method.
087: */
088: public void onActivate();
089:
090: /** Called when this execution is about to become a non-current execution.
091: *
092: * <p>It is used as callback notification.
093: *
094: * <p>Note: don't throw any exception in this method.
095: *
096: * @see #onActivate
097: */
098: public void onDeactivate();
099:
100: /** Returns whether this execution is in recovering.
101: * In other words, it is in the invocation of {@link FailoverManager#recover}.
102: * If in recovering, no response is sent to the client.
103: * It assumes the server is recovering the desktop and all it contains
104: * to match the client's status.
105: */
106: public boolean isRecovering();
107:
108: /** Sets the {@link Visualizer} for this execution.
109: * It could be anything that {@link UiEngine} requires.
110: */
111: public void setVisualizer(Visualizer ei);
112:
113: /** Returns the {@link Visualizer} for this execution
114: * (set by {@link #setVisualizer}.
115: */
116: public Visualizer getVisualizer();
117:
118: /** Sets a responseheader with the given name and value.
119: *
120: * @param value the additional header value If it contains octet string,
121: * it should be encoded according to RFC 2047
122: * (http://www.ietf.org/rfc/rfc2047.txt).
123: */
124: public void setHeader(String name, String value);
125:
126: /** Sets a response header with the given name and date-value.
127: * The date is specified in terms of milliseconds since the epoch.
128: * This method allows response headers to have multiple values.
129: * @since 3.0.0
130: */
131: public void setDateHeader(String name, long value);
132:
133: /** Adds a responseheader with the given name and value.
134: *
135: * @param value the additional header value If it contains octet string,
136: * it should be encoded according to RFC 2047
137: * (http://www.ietf.org/rfc/rfc2047.txt).
138: * @since 3.0.0
139: */
140: public void addHeader(String name, String value);
141:
142: /** Adds a response header with the given name and date-value.
143: * The date is specified in terms of milliseconds since the epoch.
144: * This method allows response headers to have multiple values.
145: * @since 3.0.0
146: */
147: public void addDateHeader(String name, long value);
148:
149: /** Returns the value of an attribute in the client request
150: * (e.g., HTTP request) that creates this execution.
151: *
152: * <p>Notice that a servlet might include serveral ZK pages,
153: * while an independent execution is created for adding a new page.
154: * It means, each client request might create several executions.
155: * Thus, the attribute set by this method might last for several
156: * executions (until the request ends).
157: */
158: public Object getRequestAttribute(String name);
159:
160: /** Sets the value of an attribute to the client request
161: * (e.g., HTTP request) that creates this execution.
162: */
163: public void setRequestAttribute(String name, Object value);
164:
165: /** Sets the desktop associated with this execution.
166: * You rarely need to use this method, since the desktop is associated
167: * when this execution is created.
168: *
169: * <p>Currently, it is used to communicate between WebManager.newDesktop
170: * and DesktopImpl's constructor.
171: *
172: * @exception IllegalArgumentException if desktop is null
173: * @exception IllegalStateException if there is already a desktop
174: * is associated with it.
175: * @since 3.0.0
176: */
177: public void setDesktop(Desktop desktop);
178: }
|