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

void	addComponent(Component comp) Adds a component to this page.
void	addPage(Page page) Adds a page to this desktop.
boolean	ceaseSuspendedThread(EventProcessingThread evtthd, java.lang.String cause) Ceases the specified event thread.
void	destroy() Called when the desktop is about to be destroyed.
org.zkoss.util.media.Media	getDownloadMedia(java.lang.String medId, boolean remove) Returns the media that is associated with Desktop.getDownloadMediaURI(org.zkoss.util.media.Media, java.lang.String), or null if not found.
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	getResponseSequence(boolean advance) Returns the sequence ID of the response.
java.util.Collection	getSuspendedThreads() Returns a collection of suspended event processing threads, or empty if no suspended thread at all.
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	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	setBookmarkByClient(java.lang.String name) Sets the bookmark when receiving the onBookmarkChanged command from the client.
void	setExecution(Execution exec) Sets the execution (used to represent a lock).
void	setId(java.lang.String id) Sets the desktop identifier.
void	setResponseSequence(int seqId) Sets the sequence ID of the response.

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.

setExecution

void setExecution(Execution exec)

Sets the execution (used to represent a lock). Called only internally (by UIEngine's implementation to activate an execution).

setBookmarkByClient

void setBookmarkByClient(java.lang.String name)

Sets the bookmark when receiving the onBookmarkChanged command from the client.

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.

getResponseSequence

int getResponseSequence(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 0~1023.

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

setResponseSequence

void setResponseSequence(int seqId)

Sets the sequence ID of the response.

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

Parameters:

seqId - a value between 0 and 1023. Since ZK 2.4.1, you can reset the sequence by passing a negative value to this argument.

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

org.zkoss.util.media.Media getDownloadMedia(java.lang.String medId,
                                            boolean remove)

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:

remove - whether to remove it from cache once returned.

Returns:

the media or null if not found.