001: /* DesktopCtrl.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Fri Jul 29 08:47:19 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 java.util.Collection;
022:
023: import org.zkoss.util.media.Media;
024:
025: import org.zkoss.zk.ui.Session;
026: import org.zkoss.zk.ui.Page;
027: import org.zkoss.zk.ui.Component;
028: import org.zkoss.zk.ui.Execution;
029: import org.zkoss.zk.ui.UiException;
030: import org.zkoss.zk.ui.event.Event;
031: import org.zkoss.zk.ui.util.EventInterceptor;
032:
033: /**
034: * An addition interface to {@link org.zkoss.zk.ui.Desktop}
035: * for implementation.
036: *
037: * <p>Note: applications shall never access this interface.
038: *
039: * @author tomyeh
040: */
041: public interface DesktopCtrl {
042: /** Returns the request queue.
043: */
044: public RequestQueue getRequestQueue();
045:
046: /** Returns the next available key which is unique in the whole desktop.
047: */
048: public int getNextKey();
049:
050: /** Returns the next available UUID for a component.
051: * The returned UUID is unique in the desktop.
052: * You can consider it as unique in the whole session, though
053: * it may not be true if {@link org.zkoss.zk.ui.ext.RawId} is used
054: * (developer's responsibility to avoid conflict),
055: * or integer overflow (too many UUID in one session, which
056: * can be considered as impossible).
057: */
058: public String getNextUuid();
059:
060: /** Adds a component to this page.
061: * <p>It is used internally and developers shall not invoke it
062: * explicityly.
063: */
064: public void addComponent(Component comp);
065:
066: /** Removes a component to this page.
067: * <p>It is used internally and developers shall not invoke it
068: * explicityly.
069: */
070: public void removeComponent(Component comp);
071:
072: /** Adds a page to this desktop.
073: * It must be called when a page is created.
074: *
075: * <p>This is one of the only few method you could access
076: * before activating an execution.
077: */
078: public void addPage(Page page);
079:
080: /** Removes a page from this desktop.
081: * <p>NOTE: once a page is removed, you can NOT add it back.
082: * You shall just GC it.
083: */
084: public void removePage(Page page);
085:
086: /** Sets the execution (used to represent a lock).
087: * Called only internally (by UIEngine's implementation to activate
088: * an execution).
089: */
090: public void setExecution(Execution exec);
091:
092: /** Sets the bookmark when receiving the onBookmarkChanged command
093: * from the client.
094: */
095: public void setBookmarkByClient(String name);
096:
097: /** Sets the desktop identifier.
098: *
099: * <p>It is callable only if it is the recovering phase, i.e.,
100: * {@link ExecutionCtrl#isRecovering} is true.
101: * In other words, callable only in the invocation of
102: * {@link FailoverManager#recover}.
103: *
104: * @exception IllegalStateException if it is NOT in recovering.
105: */
106: public void setId(String id);
107:
108: /** Called when the recoving failed.
109: */
110: public void recoverDidFail(Throwable ex);
111:
112: /** Returns the sequence ID of the response.
113: * The client and server uses the sequence ID to make sure
114: * the responses are processed in the correct order.
115: *
116: * <p>The range of the sequence IDs is 0~1023.
117: *
118: * @param advance whether to advance the number before returning.
119: * If true, the ID is increased and then returned.
120: * If false, the previous value is returned
121: */
122: public int getResponseSequence(boolean advance);
123:
124: /** Sets the sequence ID of the response.
125: *
126: * <p>It is rarely called other than in the recovering mode, i.e.,
127: * {@link ExecutionCtrl#isRecovering} is true.
128: *
129: * @param seqId a value between 0 and 1023.
130: * Since ZK 2.4.1, you can reset the sequence by passing a negative
131: * value to this argument.
132: */
133: public void setResponseSequence(int seqId);
134:
135: /** Notification that the session, which owns this desktop,
136: * is about to be passivated (aka., serialized) by the Web container.
137: */
138: public void sessionWillPassivate(Session sess);
139:
140: /** Notification that the session, which owns this desktop,
141: * has just been activated (aka., deserialized) by the Web container.
142: */
143: public void sessionDidActivate(Session sess);
144:
145: /** Called when the desktop is about to be destroyed.
146: */
147: public void destroy();
148:
149: /** Returns a collection of suspended event processing threads, or empty
150: * if no suspended thread at all.
151: *
152: * <p>An event processing thread is an instance of
153: * {@link EventProcessingThread}
154: *
155: * <p>Note: if you access this method NOT in an event listener for
156: * the SAME desktop, you have to synchronize the iteration
157: * (though the returned collection is synchronized).
158: * Of course, it is always safe to test whether it is empty
159: * ({@link Collection#isEmpty}).
160: *
161: * <pre><code>
162: //Use the following pathern IF it is not in the SAME desktop's listener
163: Collection c = otherDesktop.getSuspendedThreads();
164: if (c.isEmpty()) {
165: //do something accordingly
166: } else {
167: synchronized (c) {
168: for (Iterator it = c.iterator(); it.hasNext();) {
169: //...
170: }
171: }
172: }</code></pre>
173: */
174: public Collection getSuspendedThreads();
175:
176: /** Ceases the specified event thread.
177: *
178: * @param cause an arbitrary text to describe the cause.
179: * It will be the message of the thrown InterruptedException.
180: * @return true if the event processing thread is ceased successfully;
181: * false if no such thread or it is not suspended.
182: */
183: public boolean ceaseSuspendedThread(EventProcessingThread evtthd,
184: String cause);
185:
186: /** Returns the media that is associated with
187: * {@link org.zkoss.zk.ui.Desktop#getDownloadMediaURI}, or
188: * null if not found.
189: *
190: * <p>This method is used internally. Developers rarely need to
191: * access this method.
192: *
193: * @param remove whether to remove it from cache once returned.
194: * @return the media or null if not found.
195: */
196: public Media getDownloadMedia(String medId, boolean remove);
197:
198: /** Called when a component added or removed a listener for
199: * {@link org.zkoss.zk.ui.event.Events#ON_PIGGYBACK}.
200: *
201: * <p>The implementation usualy uses it to optimize whether to
202: * call the listener when {@link #onPiggyback} is called.
203: *
204: * @param comp the component that adds an listener for
205: * {@link org.zkoss.zk.ui.event.Events#ON_PIGGYBACK}.
206: * The component may or may not be a root component.
207: * @param listen whether the listener is added (or removed).
208: * @since 3.0.0
209: */
210: public void onPiggybackListened(Component comp, boolean listen);
211:
212: /** Called each time ZK Update Engine processes all events.
213: * It is used to implement the piggyback feature
214: * (see {@link org.zkoss.zk.ui.event.Events#ON_PIGGYBACK}).
215: *
216: * <p>Used only internally. Application develepers shall not call it.
217: *
218: * @since 3.0.0
219: */
220: public void onPiggyback();
221:
222: /** Returns the server-push controller, or null if it is not enabled
223: * yet.
224: */
225: public ServerPush getServerPush();
226:
227: /** Enables the server-push feature with the specified server-push
228: * controller.
229: *
230: * @param serverpush the server-push controller. If null,
231: * the server-push feature is disabled (for this desktop).
232: * Note: this method will invoke {@link ServerPush#start}, so the
233: * caller doesn't need to do it.
234: * @since 3.0.0
235: * @see org.zkoss.zk.ui.Desktop#enableServerPush
236: */
237: public boolean enableServerPush(ServerPush serverpush);
238:
239: /** Invokes {@link EventInterceptor#beforeSendEvent}
240: * registered by {@link org.zkoss.zk.ui.Desktop#addEventInterceptor}.
241: *
242: * <p>Note: it invokes
243: * {@link org.zkoss.zk.ui.util.Configuration#beforeSendEvent}
244: * automatically.
245: * @since 3.0.0
246: */
247: public Event beforeSendEvent(Event event);
248:
249: /** Invokes {@link EventInterceptor#beforePostEvent}
250: * registered by {@link org.zkoss.zk.ui.Desktop#addEventInterceptor}.
251: *
252: * <p>Note: it invokes
253: * {@link org.zkoss.zk.ui.util.Configuration#beforePostEvent}
254: * automatically.
255: * @since 3.0.0
256: */
257: public Event beforePostEvent(Event event);
258:
259: /** Invokes {@link EventInterceptor#beforeProcessEvent}
260: * registered by {@link org.zkoss.zk.ui.Desktop#addEventInterceptor}.
261: *
262: * <p>Note: it invokes
263: * {@link org.zkoss.zk.ui.util.Configuration#beforeProcessEvent}
264: * automatically.
265: * @since 3.0.0
266: */
267: public Event beforeProcessEvent(Event event);
268:
269: /** Invokes {@link EventInterceptor#afterProcessEvent}
270: * registered by {@link org.zkoss.zk.ui.Desktop#addEventInterceptor}.
271: *
272: * <p>Note: it invokes
273: * {@link org.zkoss.zk.ui.util.Configuration#afterProcessEvent}
274: * automatically.
275: * @since 3.0.0
276: */
277: public void afterProcessEvent(Event event);
278: }
|