001: /* Desktop.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Fri Dec 9 16:27:21 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;
020:
021: import java.util.Map;
022: import java.util.Collection;
023:
024: import org.zkoss.util.media.Media;
025:
026: import org.zkoss.zk.ui.util.EventInterceptor;
027: import org.zkoss.zk.ui.util.Configuration;
028: import org.zkoss.zk.device.Device;
029:
030: /**
031: * Represents a desktop.
032: * All pages that is created from the same URL is called a desktop.
033: *
034: * <p>A desktop is created automatically when the first page is created
035: * during a request.
036: *
037: * <p>To access a {@link Page}, its desktop must be locked first.
038: * Once a desktop is locked to a request, all pages
039: * contained in this desktop are free to access.
040: *
041: * @author tomyeh
042: */
043: public interface Desktop {
044: /** Returns the device type that this desktop belongs to.
045: *
046: * <p>A device type identifies the type of a client. For example, "ajax"
047: * represents the Web browsers with Ajax support,
048: * while "mil" represents clients that supports
049: * <i>Mobile Interactive markup Language</i> (on Limited Connected Device,
050: * such as mobile phones).
051: *
052: * <p>A desktop can use the languages belonging to the same device type.
053: * See also {@link org.zkoss.zk.ui.metainfo.LanguageDefinition#getDeviceType}.
054: *
055: * <p>A component can be added to a desktop only if they belong to the same
056: * device type.
057: *
058: * <p>Default: depends on the extension of the resource path,
059: * "ajax" if the path or extension not available.
060: * If {@link Richlet} is used, its language definition's device type is
061: * assumed.
062: */
063: public String getDeviceType();
064:
065: /** Sets the device type that this desktop belongs to.
066: *
067: * <p>Note: you can change the device type only before any component
068: * is attached to a page of the desktop.
069: * In other words, you can set the device type only at the initialization
070: * stage.
071: *
072: * <p>If the device type is changed, any device allocated for this desktop
073: * ({@link #getDevice}) will be dropped and recreated at the next
074: * invocation to {@link #getDevice}.
075: *
076: * @exception UiException if any component is attached to a page of the desktop.
077: */
078: public void setDeviceType(String deviceType);
079:
080: /** Returns the device that is associated with this desktop.
081: * <p>Note: the device is shared by all desktops of the same device type.
082: */
083: public Device getDevice();
084:
085: /** Returns whether the desktop is still alive.
086: * It returns false once it is destroyed.
087: * @see org.zkoss.zk.ui.sys.DesktopCtrl#destroy
088: */
089: public boolean isAlive();
090:
091: /** Returns ID of this desktop.
092: * It is unique in the whole session.
093: */
094: public String getId();
095:
096: /** Returns the execution, or null if this desktop is not under
097: * seving any execution (aka., not locked).
098: */
099: public Execution getExecution();
100:
101: /** Returns the session of this desktop.
102: */
103: public Session getSession();
104:
105: /** Returns the Web application this desktop belongs to.
106: */
107: public WebApp getWebApp();
108:
109: /** Returns the page of the specified ID.
110: *
111: * <p>This is one of the only few method you could access
112: * before activating an execution.
113: *
114: * @exception ComponentNotFoundException if page not found
115: */
116: public Page getPage(String pageId)
117: throws ComponentNotFoundException;
118:
119: /** Returns the page of the specified ID, or null if no such page.
120: *
121: * @since 2.4.1
122: */
123: public Page getPageIfAny(String pageId);
124:
125: /** Returns a readonly collection of all {@link Page} in this desktop.
126: */
127: public Collection getPages();
128:
129: /** Returns whether a page exists.
130: */
131: public boolean hasPage(String id);
132:
133: /** Returns all custom attributes associated with this desktop.
134: */
135: public Map getAttributes();
136:
137: /** Returns the value of the specified custom attribute associated with the desktop.
138: */
139: public Object getAttribute(String name);
140:
141: /** Sets the value of the specified custom attribute associated with the desktop.
142: */
143: public Object setAttribute(String name, Object value);
144:
145: /** Removes the specified custom attribute associated with the desktop.
146: */
147: public Object removeAttribute(String name);
148:
149: /** Returns all components contained in this desktop.
150: */
151: public Collection getComponents();
152:
153: /** Returns the component of the specified UUID ({@link Component#getUuid}).
154: * @exception ComponentNotFoundException if component not found
155: */
156: public Component getComponentByUuid(String uuid);
157:
158: /** Returns the component of the specified UUID
159: * ({@link Component#getUuid}), or null if not found.
160: */
161: public Component getComponentByUuidIfAny(String uuid);
162:
163: /** Returns the URI for asynchronous update.
164: *
165: * <p>You rarely need this method unless for implementing special
166: * components, such as file upload.
167: *
168: * @param pathInfo the path to append to the returned URI, or null
169: * to ignore
170: */
171: public String getUpdateURI(String pathInfo);
172:
173: /** Returns the path of the request that causes
174: * this desktop to be created, or "" if not available.
175: * In other words, it is the request path of the first page
176: * (see {@link Page#getRequestPath}).
177: *
178: * <p>For example, "/userguide/index.zul" (a ZUML page is requested)
179: * or /test (a richlet).
180: *
181: * @see Page#getRequestPath
182: * @since 3.0.0
183: */
184: public String getRequestPath();
185:
186: /** Returns the current directory (never null).
187: * It is empty if no current directory at all.
188: * Otherwise, it must end with '/'.
189: * In other words, you could use getCurrentDirectory() + relative_path.
190: */
191: public String getCurrentDirectory();
192:
193: /** Sets the current directory.
194: * @param dir the current directory. If null, an empty string is assumed
195: * (means no current directory at all).
196: */
197: public void setCurrentDirectory(String dir);
198:
199: /** Returns the current bookmark (never null).
200: * The returned might be the same as the last call to {@link #setBookmark},
201: * because user might use BACK, FORWARD or others to change the bookmark.
202: */
203: public String getBookmark();
204:
205: /** Sets a bookmark to this desktop. Then, when user press BACK, FORWARD
206: * or specify an URL with this bookmark, the onBookmarkChanged event
207: * is sent to all pages of the desktop.
208: */
209: public void setBookmark(String name);
210:
211: /** Returns URI for a dynamic generated media associated with a component.
212: * ZK Update Engine will then invoke invoke
213: * {@link org.zkoss.zk.ui.ext.render.DynamicMedia#getMedia} to response.
214: *
215: * <p>Note: to use with this method, {@link org.zkoss.zk.ui.ext.render.DynamicMedia}
216: * must be implemented as part of the object returned by
217: * {@link org.zkoss.zk.ui.sys.ComponentCtrl#getExtraCtrl}.
218: *
219: * <p>Used mainly for component implementation.
220: */
221: public String getDynamicMediaURI(Component comp, String pathInfo);
222:
223: /** Returns URI for a media that is used to download to the client.
224: * The client will open a Save As dialog to save the specified file.
225: *
226: * <p>Note: once called, the media belongs to desktop and it is
227: * purged automatically. Thus, don't access it again after calling
228: * this method.
229: */
230: public String getDownloadMediaURI(Media media, String pathInfo);
231:
232: /** Enables or disables the server-push feature.
233: * Before using any server-push threads, you have to enable it
234: * for the particular desktop first by use of this method.
235: * Refer to {@link Executions#activate} for more details.
236: *
237: * <p>Default: false
238: *
239: * <p>This method uses the default class
240: * (defined by {@link Device#getServerPushClass})
241: * to instantiate the server-push controller.
242: *
243: * @param enable whether to enable or to disable the server-push
244: * feature.
245: * @see Executions#activate
246: * @see Device#getServerPushClass
247: * @since 3.0.0
248: */
249: public boolean enableServerPush(boolean enable);
250:
251: /** Sets the delay between each polling.
252: * It can be called only the server push is enabled for this desktop
253: * (by use of {@link #enableServerPush}).
254: *
255: * <p>Note: not all server-push controllers support this method.
256: * Currently, only on the client-polling-based controller (the default)
257: * supports this method.
258: *
259: * <p>To make the system more scalable, the implementation usually
260: * change the delay dynamically based on the loading.
261: * By specifying the minimal and maximal values, you can control
262: * the frequence to poll the server depending on the character
263: * of your Web applications.
264: *
265: * <p>Default: It looks up the value defined in the preferences
266: * ({@link Configuration#getPreference}):
267: * <code>PollingServerPush.delay.min</code>
268: * <code>PollingServerPush.delay.max</code>,
269: and <code>PollingServerPush.delay.factor</code>.
270: * If not defined, min is 1100, max is 10000 and factor is 5.
271: *
272: * @param min the minimal delay to poll the server for any pending
273: * server-push threads.
274: * Ignore (aka., the default value is used) if non-positive.
275: * Unit: milliseconds.
276: * @param max the maximal delay to poll the server for any pending
277: * server-push threads.
278: * Ignore (aka., the default value is used) if non-positive.
279: * Unit: milliseconds.
280: * @param factor the delay factor. The real delay is the processing
281: * time multiplies the delay factor. For example, if the last request
282: * took 1 second to process, then the client polling will be delayed
283: * for 1 x factor seconds, unless it is value
284: * Ignore (aka., the default value is used) if non-positive.
285: * @since 3.0.0
286: */
287: public void setServerPushDelay(int min, int max, int factor);
288:
289: /** Returns whether the server-push feature is enabled for this
290: * desktop.
291: *
292: * <p>Default: false.
293: *
294: * @since 3.0.0
295: */
296: public boolean isServerPushEnabled();
297:
298: /** Adds an event interceptor to this desktop.
299: * @since 3.0.0
300: */
301: public void addEventInterceptor(EventInterceptor ei);
302:
303: /** Removes an event interceptor from this desktop.
304: * @return whether the interceptor is removed successfully.
305: * @since 3.0.0
306: */
307: public boolean removeEventInterceptor(EventInterceptor ei);
308: }
|