org.zkoss.zk.ui.sys
Interface DesktopCtrl

All Known Implementing Classes:
DesktopImpl

public interface DesktopCtrl

An addition interface to Desktop for implementation.

Note: applications shall never access this interface.

Author:
tomyeh

Method Summary
 boolean activateServerPush(long timeout)
          Activates the server push.
 void addComponent(Component comp)
          Adds a component to this page.
 void addPage(Page page)
          Adds a page to this desktop.
 void afterComponentAttached(Component comp, Page page)
          Invokes UiLifeCycle.afterComponentAttached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).
 void afterComponentDetached(Component comp, Page prevpage)
          Invokes UiLifeCycle.afterComponentDetached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).
 void afterComponentMoved(Component parent, Component child, Component prevparent)
          Invokes UiLifeCycle.afterComponentMoved(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component).
 void afterProcessEvent(Event event)
          Invokes EventInterceptor.afterProcessEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
 Event beforePostEvent(Event event)
          Invokes EventInterceptor.beforePostEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
 Event beforeProcessEvent(Event event)
          Invokes EventInterceptor.beforeProcessEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
 Event beforeSendEvent(Event event)
          Invokes EventInterceptor.beforeSendEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).
 boolean ceaseSuspendedThread(EventProcessingThread evtthd, java.lang.String cause)
          Ceases the specified event thread.
 void deactivateServerPush()
          Deactivates the server push.
 void destroy()
          Called when the desktop is about to be destroyed.
 boolean enableServerPush(ServerPush serverpush)
          Enables the server-push feature with the specified server-push controller.
 java.lang.Object getActivationLock()
          Returns the lock used to activate an execution.
 Media getDownloadMedia(java.lang.String medId, boolean reserved)
          Returns the media that is associated with Desktop.getDownloadMediaURI(org.zkoss.util.media.Media, java.lang.String), or null if not found.
 java.lang.Object getLastResponse(java.lang.String reqId)
          Returns the response for the last request, or null if no response yet, or the specified request ID doesn't match the last one (passed to responseSent(java.lang.String, java.lang.Object)).
 int getNextKey()
          Returns the next available key which is unique in the whole desktop.
 java.lang.String getNextUuid()
          Returns the next available UUID for a component.
 RequestQueue getRequestQueue()
          Returns the request queue.
 int getResponseId(boolean advance)
          Returns the sequence ID of the response.
 ServerPush getServerPush()
          Returns the server-push controller, or null if it is not enabled yet.
 java.util.Collection getSuspendedThreads()
          Returns a collection of suspended event processing threads, or empty if no suspended thread at all.
 Visualizer getVisualizer()
          Returns the visualizer associated with this desktop.
 void invokeDesktopCleanups()
          Invokes DesktopCleanup.cleanup(org.zkoss.zk.ui.Desktop) for each relevant listener registered by Desktop.addListener(java.lang.Object).
 void invokeExecutionCleanups(Execution exec, Execution parent, java.util.List errs)
          Invokes ExecutionCleanup.cleanup(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution, java.util.List) for each relevant listener registered by Desktop.addListener(java.lang.Object).
 void invokeExecutionInits(Execution exec, Execution parent)
          Invokes ExecutionInit.init(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution) for each relevant listener registered by Desktop.addListener(java.lang.Object).
 void onPiggyback()
          Called each time ZK Update Engine processes all events.
 void onPiggybackListened(Component comp, boolean listen)
          Called when a component added or removed a listener for Events.ON_PIGGYBACK.
 java.util.List piggyResponse(java.util.List response, boolean reset)
          Adds the responses to the so-called piggy-back queue.
 void recoverDidFail(java.lang.Throwable ex)
          Called when the recoving failed.
 void removeComponent(Component comp)
          Removes a component to this page.
 void removePage(Page page)
          Removes a page from this desktop.
 void responseSent(java.lang.String reqId, java.lang.Object resInfo)
          Called when ZK Update Engine has sent a response to the client.
 void service(AuRequest request, boolean everError)
          Processes an AU request.
 void sessionDidActivate(Session sess)
          Notification that the session, which owns this desktop, has just been activated (aka., deserialized) by the Web container.
 void sessionWillPassivate(Session sess)
          Notification that the session, which owns this desktop, is about to be passivated (aka., serialized) by the Web container.
 void setExecution(Execution exec)
          Sets the execution (used to represent a lock).
 void setId(java.lang.String id)
          Sets the desktop identifier.
 void setResponseId(int resId)
          Sets the sequence ID of the response.
 void setVisualizer(Visualizer uv)
          Sets the visualizer associated with is desktop.
 

Method Detail

getRequestQueue

RequestQueue getRequestQueue()
Returns the request queue.


getNextKey

int getNextKey()
Returns the next available key which is unique in the whole desktop.


getNextUuid

java.lang.String getNextUuid()
Returns the next available UUID for a component. The returned UUID is unique in the desktop. You can consider it as unique in the whole session, though it may not be true if RawId is used (developer's responsibility to avoid conflict), or integer overflow (too many UUID in one session, which can be considered as impossible).


addComponent

void addComponent(Component comp)
Adds a component to this page.

It is used internally and developers shall not invoke it explicityly.


removeComponent

void removeComponent(Component comp)
Removes a component to this page.

It is used internally and developers shall not invoke it explicityly.


addPage

void addPage(Page page)
Adds a page to this desktop. It must be called when a page is created.

This is one of the only few method you could access before activating an execution.


removePage

void removePage(Page page)
Removes a page from this desktop.

NOTE: once a page is removed, you can NOT add it back. You shall just GC it.


setId

void setId(java.lang.String id)
Sets the desktop identifier.

It is callable only if it is the recovering phase, i.e., ExecutionCtrl.isRecovering() is true. In other words, callable only in the invocation of FailoverManager.recover(org.zkoss.zk.ui.Session, org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Desktop).

Throws:
java.lang.IllegalStateException - if it is NOT in recovering.

recoverDidFail

void recoverDidFail(java.lang.Throwable ex)
Called when the recoving failed.


sessionWillPassivate

void sessionWillPassivate(Session sess)
Notification that the session, which owns this desktop, is about to be passivated (aka., serialized) by the Web container.


sessionDidActivate

void sessionDidActivate(Session sess)
Notification that the session, which owns this desktop, has just been activated (aka., deserialized) by the Web container.


destroy

void destroy()
Called when the desktop is about to be destroyed.


getSuspendedThreads

java.util.Collection getSuspendedThreads()
Returns a collection of suspended event processing threads, or empty if no suspended thread at all.

An event processing thread is an instance of EventProcessingThread

Note: if you access this method NOT in an event listener for the SAME desktop, you have to synchronize the iteration (though the returned collection is synchronized). Of course, it is always safe to test whether it is empty (Collection.isEmpty()).


//Use the following pathern IF it is not in the SAME desktop's listener
Collection c = otherDesktop.getSuspendedThreads();
if (c.isEmpty()) {
        //do something accordingly
} else {
  synchronized (c) {
    for (Iterator it = c.iterator(); it.hasNext();) {
      //...
    }
  }
}


ceaseSuspendedThread

boolean ceaseSuspendedThread(EventProcessingThread evtthd,
                             java.lang.String cause)
Ceases the specified event thread.

Parameters:
cause - an arbitrary text to describe the cause. It will be the message of the thrown InterruptedException.
Returns:
true if the event processing thread is ceased successfully; false if no such thread or it is not suspended.

getDownloadMedia

Media getDownloadMedia(java.lang.String medId,
                       boolean reserved)
Returns the media that is associated with Desktop.getDownloadMediaURI(org.zkoss.util.media.Media, java.lang.String), or null if not found.

This method is used internally. Developers rarely need to access this method.

Parameters:
reserved - reserved for future use.
Returns:
the media or null if not found.

onPiggybackListened

void onPiggybackListened(Component comp,
                         boolean listen)
Called when a component added or removed a listener for Events.ON_PIGGYBACK.

The implementation usualy uses it to optimize whether to call the listener when onPiggyback() is called.

Parameters:
comp - the component that adds an listener for Events.ON_PIGGYBACK. The component may or may not be a root component.
listen - whether the listener is added (or removed).
Since:
3.0.0

onPiggyback

void onPiggyback()
Called each time ZK Update Engine processes all events. It is used to implement the piggyback feature (see Events.ON_PIGGYBACK).

Used only internally. Application develepers shall not call it.

Since:
3.0.0

getServerPush

ServerPush getServerPush()
Returns the server-push controller, or null if it is not enabled yet.


enableServerPush

boolean enableServerPush(ServerPush serverpush)
Enables the server-push feature with the specified server-push controller.

Parameters:
serverpush - the server-push controller. If null, the server-push feature is disabled (for this desktop). Note: this method will invoke ServerPush.start(org.zkoss.zk.ui.Desktop), so the caller doesn't need to do it.
Since:
3.0.0
See Also:
Desktop.enableServerPush(boolean)

beforeSendEvent

Event beforeSendEvent(Event event)
Invokes EventInterceptor.beforeSendEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).

Note: it invokes Configuration.beforeSendEvent(org.zkoss.zk.ui.event.Event) automatically.

Since:
3.0.0

beforePostEvent

Event beforePostEvent(Event event)
Invokes EventInterceptor.beforePostEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).

Note: it invokes Configuration.beforePostEvent(org.zkoss.zk.ui.event.Event) automatically.

Since:
3.0.0

beforeProcessEvent

Event beforeProcessEvent(Event event)
Invokes EventInterceptor.beforeProcessEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).

Note: it invokes Configuration.beforeProcessEvent(org.zkoss.zk.ui.event.Event) automatically.

Since:
3.0.0

afterProcessEvent

void afterProcessEvent(Event event)
Invokes EventInterceptor.afterProcessEvent(org.zkoss.zk.ui.event.Event) registered by Desktop.addListener(java.lang.Object).

Note: it invokes Configuration.afterProcessEvent(org.zkoss.zk.ui.event.Event) automatically.

Since:
3.0.0

invokeDesktopCleanups

void invokeDesktopCleanups()
Invokes DesktopCleanup.cleanup(org.zkoss.zk.ui.Desktop) for each relevant listener registered by Desktop.addListener(java.lang.Object).

Used only internally.

It never throws an exception.

Since:
3.0.6

invokeExecutionInits

void invokeExecutionInits(Execution exec,
                          Execution parent)
                          throws UiException
Invokes ExecutionInit.init(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution) for each relevant listener registered by Desktop.addListener(java.lang.Object).

Used only internally.

Parameters:
exec - the execution that is created
parent - the previous execution, or null if no previous at all
Throws:
UiException - to prevent an execution from being created
Since:
3.0.6

invokeExecutionCleanups

void invokeExecutionCleanups(Execution exec,
                             Execution parent,
                             java.util.List errs)
Invokes ExecutionCleanup.cleanup(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Execution, java.util.List) for each relevant listener registered by Desktop.addListener(java.lang.Object).

Used only internally.

It never throws an exception but logs and adds it to the errs argument, if not null.

Parameters:
exec - the execution that is being destroyed
parent - the previous execution, or null if no previous at all
errs - a list of exceptions (java.lang.Throwable) if any exception occured before this method is called, or null if no exeption at all. Note: you can manipulate the list directly to add or clean up exceptions. For example, if exceptions are fixed correctly, you can call errs.clear() such that no error message will be displayed at the client.
Since:
3.0.6

afterComponentAttached

void afterComponentAttached(Component comp,
                            Page page)
Invokes UiLifeCycle.afterComponentAttached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).

Since:
3.0.6

afterComponentDetached

void afterComponentDetached(Component comp,
                            Page prevpage)
Invokes UiLifeCycle.afterComponentDetached(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Page).

Since:
3.0.6

afterComponentMoved

void afterComponentMoved(Component parent,
                         Component child,
                         Component prevparent)
Invokes UiLifeCycle.afterComponentMoved(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component).

Parameters:
prevparent - the previous parent. If it is the same as comp's Component.getParent(), comp is moved in the same parent.
Since:
3.0.6

responseSent

void responseSent(java.lang.String reqId,
                  java.lang.Object resInfo)
Called when ZK Update Engine has sent a response to the client.

Parameters:
reqId - the request ID that the response is generated for. Ingore if null.
resInfo - the response. Ignored if reqId is null.
Since:
5.0.0

getLastResponse

java.lang.Object getLastResponse(java.lang.String reqId)
Returns the response for the last request, or null if no response yet, or the specified request ID doesn't match the last one (passed to responseSent(java.lang.String, java.lang.Object)).

The return value is the value passed to resInfo when calling responseSent(java.lang.String, java.lang.Object).

Since:
5.0.0

getResponseId

int getResponseId(boolean advance)
Returns the sequence ID of the response. The client and server uses the sequence ID to make sure the responses are processed in the correct order.

The range of the sequence IDs is 1~999.

Parameters:
advance - whether to advance the number before returning. If true, the ID is increased and then returned. If false, the previous value is returned
Since:
3.5.0

setResponseId

void setResponseId(int resId)
Sets the sequence ID of the response.

It is rarely called other than in the recovering mode, i.e., ExecutionCtrl.isRecovering() is true.

Parameters:
resId - a value between 1 and 999. You can reset the ID by passing a non-positive value.
Since:
3.5.0

piggyResponse

java.util.List piggyResponse(java.util.List response,
                             boolean reset)
Adds the responses to the so-called piggy-back queue. The responses in the piggy-back queue will be sent in the next AU request.

This method is useful for working thread that wants to sent the responses back to the client. A typical example is the Comet-based server push.

Parameters:
response - the responses to be appended to the piggy-back queue.
reset - whether to reset the piggy-back queue after returning the queued responses.
Returns:
all responses in the piggy-back queue, or null if nothing in the queue.
Since:
5.0.0

activateServerPush

boolean activateServerPush(long timeout)
                           throws java.lang.InterruptedException
Activates the server push. It is called by Executions.activate(org.zkoss.zk.ui.Desktop).

Note: the server push must be enabled first (by use of Desktop.enableServerPush(boolean)).

Parameters:
timeout - the maximum time to wait in milliseconds. Ingored (i.e., never timeout) if non-positive.
Throws:
java.lang.InterruptedException
Since:
3.5.2

deactivateServerPush

void deactivateServerPush()
Deactivates the server push. It is called by Executions.deactivate(org.zkoss.zk.ui.Desktop).

Since:
3.5.2

service

void service(AuRequest request,
             boolean everError)
Processes an AU request. If AuRequest.getComponent() is not nul Notice that not only the requests for a deskop but also the requests for any component in the deskop will go thru this method.

To override the default processing, register an AU request service AuService by invoking Desktop.addListener(java.lang.Object).

  1. This method first invokes the registered AU request service (AuService) one-by-one, until the first one returns true.
  2. If none of them returns true or no AU service at all, it checks if the request is targeting a component (i.e., AuRequest.getComponent() is not null).
  3. If it is targeting a component, it invokes ComponentCtrl.service(org.zkoss.zk.au.AuRequest, boolean) to handle the service.
  4. If it is not targeting a component (i.e., targeting to this desktop), it handles as follows.

Notice that the registered AU request service (AuService) will be called, no matter the request is targeting a component or a desktop. And, it can 'intercept' or 'filter' it by returning false.

To send reponses to the client, use AbstractComponent.smartUpdate(java.lang.String, java.lang.Object), AbstractComponent.response(java.lang.String, org.zkoss.zk.au.AuResponse) or Component.invalidate().

Parameters:
everError - if any error ever occured before processing this request. In other words, indicates if the previous request causes any exception.
Since:
5.0.0

setExecution

void setExecution(Execution exec)
Sets the execution (used to represent a lock).

Used only to implement UiEngine.


getVisualizer

Visualizer getVisualizer()
Returns the visualizer associated with this desktop.

Used only to implement UiEngine.

Since:
3.6.2

setVisualizer

void setVisualizer(Visualizer uv)
Sets the visualizer associated with is desktop.

Used only to implement UiEngine.

Since:
3.6.2

getActivationLock

java.lang.Object getActivationLock()
Returns the lock used to activate an execution. Before calling setVisualizer(org.zkoss.zk.ui.sys.Visualizer), this object returned by this method must be locked first.

Used only to implement UiEngine.

Since:
3.6.2


Copyright © 2005-2009 Potix Corporation. All Rights Reserved. SourceForge.net Logo