executions.java

ZK 基础介绍 功能操作 模块 结合数据库操作

	 * for the specified object.
	 *
	 * <p>It can only be called when the current thread is processing an event.
	 * And, when called, the current processing is suspended and ZK continues
	 * to process the next event and finally render the result.
	 *
	 * <p>It is typical use to implement a modal dialog where it won't return
	 * until the modal dialog ends.
	 *
	 * @param mutex any non-null object to identify what to notify.
	 * It must be same object passed to {@link #notify(Desktop, Object)}.
	 * If there is racing issue, you have to enclose it with
	 * <code>synchronized</code> (though it is optional).
	 * @exception UiException if it is called not during event processing.
	 * @exception SuspendNotAllowedException if there are too many suspended
	 * exceptions.
	 * Deployers can control the maximal allowed number of suspended exceptions
	 * by specifying <code>max-suspended-thread</code> in <code>zk.xml</code>,
	 * or invoking {@link org.zkoss.zk.ui.util.Configuration#setMaxSuspendedThreads}.
	 */
	public static final void wait(Object mutex)
	throws InterruptedException, SuspendNotAllowedException {
		getUiEngine().wait(mutex);
	}
	/** Wakes up a single event processing thread that is waiting on the
	 * specified object.
	 *
	 * <p>Unlike {@link #notify(Desktop, Object)}, this method can be invoked only
	 * in the event listener that processing the same desktop.
	 * In addition, this method can be called under the event listener.
	 *
	 * <p>Use {@link #notify(Desktop, Object)} if you want to notify in other
	 * thread, such as a working thread.
	 *
	 * @param mutex any non-null object to identify what to notify.
	 * It must be same object passed to {@link #wait}.
	 * If there is racing issue, you have to enclose it with
	 * <code>synchronized</code> (though it is optional).
	 * @see #notify(Desktop, Object)
	 * @see #notifyAll(Object)
	 * @exception UiException if it is called not during event processing.
	 */
	public static final void notify(Object mutex) {
		getUiEngine().notify(mutex);
	}
	/** Wakes up all event processing thread that are waiting on the
	 * specified object.
	 *
	 * <p>Unlike {@link #notify(Desktop, Object)}, this method can be invoked only
	 * in the event listener that processing the same desktop.
	 * In addition, this method can be called under the event listener.
	 *
	 * <p>Use {@link #notifyAll(Desktop, Object)} if you want to notify in other
	 * thread, such as a working thread.
	 *
	 * @param mutex any non-null object to identify what to notify.
	 * It must be same object passed to {@link #wait}.
	 * If there is racing issue, you have to enclose it with
	 * <code>synchronized</code> (though it is optional).
	 * @see #notify(Desktop, Object)
	 * @see #notifyAll(Object)
	 * @exception UiException if it is called not during event processing.
	 */
	public static final void notifyAll(Object mutex) {
		getUiEngine().notifyAll(mutex);
	}
	/** Wakes up a single event processing thread for the specified desktop
	 * that is waiting on the specified object.
	 *
	 * <p>Unlike {@link #notify(Object)}, this method can be called any time.
	 * It is designed to let working threads resume an event processing
	 * thread.
	 *
	 * <p>Notice: if this method is NOT called in an event processing thread,
	 * the resumed thread won't execute until the next request is received.
	 * To enforce it happen, you might use the timer component (found in ZUL).
	 *
	 * <p>Notice: to resolve racing issue, you usually need to follow
	 * this pattern.
	 * <pre><code>
//Event Handling Thread
synchronized (mutex) {
	final WorkingThread worker = new WorkingThread(desktop);
	synchronized (mutex) {
		worker.start();
		Executions.wait(mutex);
	}
	....
}
//Working Thread
public void run() {
	....
	synchronized (mutex) {
		Executions.notify(desktop, mutex);
	}
}
	 </code></pre>
	 *
	 * @param desktop the desktop which the suspended thread is processing.
	 * It must be the same desktop of the suspended thread.
	 * @param mutex any non-null object to identify what to notify.
	 * It must be same object passed to {@link #wait}.
	 * If there is racing issue, you have to enclose it with
	 * <code>synchronized</code> (though it is optional).
	 * @see #notify(Object)
	 * @see #notifyAll(Desktop, Object)
	 */
	public static final void notify(Desktop desktop, Object mutex) {
		getUiEngine(desktop).notify(desktop, mutex);
	}
	/** Wakes up all event processing theads for the specified desktop
	 * that are waiting on the specified object.
	 *
	 * <p>Unlike {@link #notifyAll(Object)}, this method can be called any time.
	 * It is designed to let working threads resume an event processing
	 * thread.
	 *
	 * <p>Notice: if this method is NOT called in an event processing thread,
	 * the resumed thread won't execute until the next request is received.
	 * To enforce it happen, you might use the timer component (found in ZUL).
	 *
	 * <p>Notice: to resolve racing issue, you usually need to follow
	 * this pattern.
	 * <pre><code>
//Event Handling Thread
synchronized (mutex) {
	final WorkingThread worker = new WorkingThread(desktop);
	synchronized (mutex) {
		worker.start();
		Executions.wait(mutex);
	}
	....
}
//Working Thread
public void run() {
	....
	synchronized (mutex) {
		Executions.notifyAll(desktop, mutex);
	}
}
	 </code></pre>
	 *
	 * @param desktop the desktop which the suspended thread is processing.
	 * It must be the same desktop of the suspended thread.
	 * @param mutex any non-null object to identify what to notify.
	 * It must be same object passed to {@link #wait}.
	 * If there is racing issue, you have to enclose it with
	 * <code>synchronized</code> (though it is optional).
	 * @see #notify(Object)
	 * @see #notifyAll(Desktop, Object)
	 */
	public static final void notifyAll(Desktop desktop, Object mutex) {
		getUiEngine(desktop).notifyAll(desktop, mutex);
	}

	/** Activates a server-push thread.
	 * It causes the current thread to wait until the desktop is available
	 * to access, the desktop no longer exists,
	 * or some other thread interrupts this thread.
	 *
	 * <p>A server-push thread is a working thread that manipulates a desktop
	 * independent of event listeners. It can manipulate the components
	 * of the desktop as long as it is activated.
	 *
	 * <p>Due to the overhead of using server-push threads, the server-push
	 * feature is disabled by default. To use it, you have to enable
	 * it first with {@link Desktop#enableServerPush}.
	 * Once enabled, you can use as many as sevrer-push threads you like
	 * (for the desktop with the server-push feature enabled).
	 *
	 * <p>Before a server-push thread can access the components of the
	 * desktop it belongs, you have to activate it first.
	 * To activate a server-push thread, you have to invoke {@link #activate}.
	 * Once it returns, the server-push thread is activated and it, like
	 * event listeners, can manipulate the components of the corresponding
	 * desktop directly.
	 *
	 * <p>A typical use pattern:
	 *
	 * <pre><code>class MyWorkingThread extends Thread {
	 *  public void run() {
	 *    while (anything_to_publish) {
	 *       //prepare something to publish
	 *       //you can create new components and manipulate them before
	 *       //activation, as long as they are not attached to the desktop
	 *
	 *       Executions.activate(desktop);
	 *       try {
	 *         try {
	 *           //activated
	 *           //manipulate the components that are attached the desktop
	 *         } finally {
	 *           Executions.deactivate(desktop)
	 *         }
	 *       } catch (DesktopUnavailableException ex) {
	 *         //clean up (since desktop is dead)
	*       }
	 *   }
	 * }
	 *}</code></pre>
	 *
	 * <p>Note: the access of components is sequentialized. That is,
	 * at most one server-push thread is activated. All others, including
	 * the event listeners, have to wait util it is deactivated
	 * (i.e., until {@link #deactivate} is called).
	 * Thus, it is better to minimize the time remaining activated.
	 * A typical practice is to create new components and manipulate them
	 * before activated. Then, you have to only attach them after activated.
	 *
	 * <pre><code> Tree tree = new Tree();
	 * new Treechildren().setParent(tree); //initialize the tree
	 * Exections.activate(desktop);
	 * try {
	 *   tree.setPage(page); //assume page is a page of desktop
	 *</code></pre>
	 *
	 * <p>Note: you don't need to invoke this method in the event listener
	 * since it is already activated when an event listen starts execution.
	 *
	 * @exception InterruptedException if it is interrupted by other thread
	 * @exception DesktopUnavailableException if the desktop is removed
	 * (when activating).
	 * @since 3.0.0
	 */
	public static final void activate(Desktop desktop)
	throws InterruptedException, DesktopUnavailableException {
		activate(desktop, 0);
	}
	/** Activates a server-push thread with, or until a certain amount of
	 * real time has elapsed.
	 * It causes the current thread to wait until the desktop is available
	 * to access, the desktop no longer exists,
	 * some other thread interrupts this thread,
	 * or a certain amount of real time has elapsed.
	 *
	 * @param timeout the maximum time to wait in milliseconds.
	 * Ingored (i.e., never timeout) if non-positive.
	 * @return whether it is activated or it is timeout.
	 * The only reason it returns false is timeout.
	 * @exception InterruptedException if it is interrupted by other thread
	 * @exception DesktopUnavailableException if the desktop is removed
	 * (when activating).
	 * @exception IllegalStateException if the server push is not
	 * enabled for this desktop yet ({@link Desktop#enableServerPush}).
	 * @since 3.0.0
	 * @see #activate(Desktop)
	 */
	public static final boolean activate(Desktop desktop, long timeout)
	throws InterruptedException, DesktopUnavailableException {
		final ServerPush spush = ((DesktopCtrl)desktop).getServerPush();
		if (spush == null)
			if (desktop.isAlive())
				throw new IllegalStateException("Before activation, the server push must be enabled for "+desktop);
			else
				throw new DesktopUnavailableException("Stopped");
		return spush.activate(timeout);
	}
	/** Deactivates a server-push thread.
	 * @since 3.0.0
	 */
	public static final void deactivate(Desktop desktop) {
		final ServerPush spush = ((DesktopCtrl)desktop).getServerPush();
		if (spush != null)
			spush.deactivate();
	}

	private static final UiEngine getUiEngine(Desktop desktop) {
		if (desktop == null)
			throw new IllegalArgumentException("desktop cannot be null");
		return ((WebAppCtrl)desktop.getWebApp()).getUiEngine();
	}
	private static final UiEngine getUiEngine() {
		final Execution exec = getCurrent();
		if (exec == null)
			throw new IllegalStateException("This method can be called only under an event listener");
		return ((WebAppCtrl)exec.getDesktop().getWebApp()).getUiEngine();
	}
}