Package org.zkoss.zk.ui.impl

Class DesktopImpl

  • All Implemented Interfaces:
    java.io.Serializable, Desktop, Scope, DesktopCtrl
    public class DesktopImpl
extends java.lang.Object
implements Desktop, DesktopCtrl, java.io.Serializable
    The implementation of Desktop.

    Note: though DesktopImpl is serializable, it is designed to work with Web container to enable the serialization of sessions. It is not suggested to serialize and deserialize it directly since many fields might be lost.

    On the other hand, it is OK to serialize and deserialize Component.

    Author:
    tomyeh
    See Also:
    Serialized Form

    • Constructor Detail

      • DesktopImpl

        public DesktopImpl​(WebApp wapp,
                   java.lang.String updateURI,
                   java.lang.String path,
                   java.lang.String deviceType,
                   java.lang.Object request)
        Parameters:
        wapp - the web application
        updateURI - the URI to access the update engine (no expression allowed). Note: it is NOT encoded yet.
        path - the path that causes this desktop to create. If null or empty is specified, it means not available.
        deviceType - the device type. If null or empty is specified, "ajax" is assumed.
        request - the request (HttpServletRequest if HTTP)
        Since:
        3.0.1

      • DesktopImpl

        public DesktopImpl​(WebApp wapp,
                   java.lang.String updateURI,
                   java.lang.String resourceURI,
                   java.lang.String path,
                   java.lang.String deviceType,
                   java.lang.Object request)
        Parameters:
        wapp - the web application
        updateURI - the URI to access the update engine (no expression allowed). Note: it is NOT encoded yet.
        resourceURI - the URI to access the resource engine (no expression allowed). Note: it is NOT encoded yet.
        path - the path that causes this desktop to create. If null or empty is specified, it means not available.
        deviceType - the device type. If null or empty is specified, "ajax" is assumed.
        request - the request (HttpServletRequest if HTTP)
        Since:
        9.5.0

    • Method Detail

      • getQueryString

        public java.lang.String getQueryString()
        Description copied from interface: Desktop
        Returns the query string that is contained in the request URL after the path (Desktop.getRequestPath()), or null if the URL does not have a query string.
        Specified by:
        getQueryString in interface Desktop

      • getId

        public java.lang.String getId()
        Description copied from interface: Desktop
        Returns ID of this desktop. It is unique in the whole session.
        Specified by:
        getId in interface Desktop

      • newRequestQueue

        protected RequestQueue newRequestQueue()
        Creates the request queue. It is called when the desktop is initialized.

        You may override it to provide your implementation of RequestQueue to control how to optimize the AU requests.

        Default: creates an instance from RequestQueueImpl;

        Since:
        2.4.0

      • getDeviceType

        public java.lang.String getDeviceType()
        Description copied from interface: Desktop
        Returns the device type that this desktop belongs to.

        A device type identifies the type of a client. For example, "ajax" represents the Web browsers with Ajax support, while "mil" represents clients that supports Mobile Interactive markup Language (on Limited Connected Device, such as mobile phones).

        A desktop can use the languages belonging to the same device type. See also LanguageDefinition.getDeviceType().

        A component can be added to a desktop only if they belong to the same device type.

        Default: depends on the extension of the resource path, "ajax" if the path or extension not available. If Richlet is used, its language definition's device type is assumed.

        Specified by:
        getDeviceType in interface Desktop

      • getDevice

        public Device getDevice()
        Description copied from interface: Desktop
        Returns the device that is associated with this desktop.

        Note: the device is shared by all desktops of the same device type.

        Specified by:
        getDevice in interface Desktop

      • setDeviceType

        public void setDeviceType​(java.lang.String deviceType)
        Description copied from interface: Desktop
        Sets the device type that this desktop belongs to.

        Note: you can change the device type only before any component is attached to a page of the desktop. In other words, you can set the device type only at the initialization stage.

        If the device type is changed, any device allocated for this desktop (Desktop.getDevice()) will be dropped and recreated at the next invocation to Desktop.getDevice().

        Specified by:
        setDeviceType in interface Desktop

      • getExecution

        public Execution getExecution()
        Description copied from interface: Desktop
        Returns the execution, or null if this desktop is not serving any execution (a.k.a., not locked).
        Specified by:
        getExecution in interface Desktop

      • getSession

        public final Session getSession()
        Description copied from interface: Desktop
        Returns the session of this desktop.
        Specified by:
        getSession in interface Desktop

      • getUpdateURI

        public java.lang.String getUpdateURI​(java.lang.String pathInfo)
        Description copied from interface: Desktop
        Returns the URI for asynchronous update.

        You rarely need this method unless for implementing special components, such as file upload.

        Specified by:
        getUpdateURI in interface Desktop
        Parameters:
        pathInfo - the path to append to the returned URI, or null to ignore

      • getResourceURI

        public java.lang.String getResourceURI​(java.lang.String pathInfo)
        Description copied from interface: Desktop
        Returns the URI for ZK resource.
        Specified by:
        getResourceURI in interface Desktop
        Parameters:
        pathInfo - the path to append to the returned URI, or null to ignore

      • getDownloadMediaURI

        public java.lang.String getDownloadMediaURI​(org.zkoss.util.media.Media media,
                                            java.lang.String pathInfo)
        Description copied from interface: Desktop
        Returns URI for a media that is used to download to the client. The client will open a Save As dialog to save the specified file.

        Note: once called, the media belongs to desktop and it is purged automatically. Thus, don't access it again after calling this method.

        Specified by:
        getDownloadMediaURI in interface Desktop

      • getPage

        public Page getPage​(java.lang.String pageId)
        Description copied from interface: Desktop
        Returns the page of the specified ID or UUID.

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

        Specified by:
        getPage in interface Desktop
        Parameters:
        pageId - the page's ID or UUID. ID has the higher priority.

      • getPageIfAny

        public Page getPageIfAny​(java.lang.String pageId)
        Description copied from interface: Desktop
        Returns the page of the specified ID or UUID, or null if no such page.
        Specified by:
        getPageIfAny in interface Desktop
        Parameters:
        pageId - the page's ID or UUID. ID has the higher priority.

      • hasPage

        public boolean hasPage​(java.lang.String pageId)
        Description copied from interface: Desktop
        Returns whether a page exists.
        Specified by:
        hasPage in interface Desktop

      • getPages

        public java.util.Collection<Page> getPages()
        Description copied from interface: Desktop
        Returns a readonly collection of all Page in this desktop.
        Specified by:
        getPages in interface Desktop

      • getFirstPage

        public Page getFirstPage()
        Description copied from interface: Desktop
        Returns the first page, or null if no page at all (happens when the desktop has been destroyed)
        Specified by:
        getFirstPage in interface Desktop

      • getBookmark

        public java.lang.String getBookmark()
        Description copied from interface: Desktop
        Returns the current bookmark (never null). The returned might be the same as the last call to Desktop.setBookmark(java.lang.String), because user might use BACK, FORWARD or others to change the bookmark.
        Specified by:
        getBookmark in interface Desktop

      • setBookmark

        public void setBookmark​(java.lang.String name)
        Description copied from interface: Desktop
        Sets a bookmark to this desktop. Then, when user press BACK, FORWARD or specify an URL with this bookmark, the onBookmarkChange event is sent to all pages of the desktop.

        It is the same as setBookmark(name, false)

        Specified by:
        setBookmark in interface Desktop

      • setBookmark

        public void setBookmark​(java.lang.String name,
                        boolean replace)
        Description copied from interface: Desktop
        Sets the bookmark to this desktop. with more control.
        Specified by:
        setBookmark in interface Desktop
        Parameters:
        name - the name of the bookmark
        replace - if true, the bookmark is replaced (in the history list)
        See Also:
        Desktop.setBookmark(String)

      • getComponents

        public java.util.Collection<Component> getComponents()
        Description copied from interface: Desktop
        Returns all components contained in this desktop.
        Specified by:
        getComponents in interface Desktop

      • addComponent

        public void addComponent​(Component comp)
        Description copied from interface: DesktopCtrl
        Adds a component to this page.

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

        Specified by:
        addComponent in interface DesktopCtrl

      • removeComponent

        public boolean removeComponent​(Component comp)
        Description copied from interface: DesktopCtrl
        Removes a component to this page.

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

        Specified by:
        removeComponent in interface DesktopCtrl
        Returns:
        false always since 10.0.0 (Deprecated: whether UUID is recycled. If true, the caller shall reset UUID of the give component.)

      • getAttributes

        public java.util.Map<java.lang.String,​java.lang.Object> getAttributes()
        Description copied from interface: Desktop
        Returns all custom attributes associated with this desktop.
        Specified by:
        getAttributes in interface Desktop
        Specified by:
        getAttributes in interface Scope

      • getAttribute

        public java.lang.Object getAttribute​(java.lang.String name)
        Description copied from interface: Desktop
        Returns the value of the specified custom attribute associated with the desktop.
        Specified by:
        getAttribute in interface Desktop
        Specified by:
        getAttribute in interface Scope

      • getAttribute

        public java.lang.Object getAttribute​(java.lang.String name,
                                     boolean recurse)
        Description copied from interface: Scope
        Returns the custom attribute associated with this object.
        Specified by:
        getAttribute in interface Scope
        recurse - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

      • hasAttribute

        public boolean hasAttribute​(java.lang.String name)
        Description copied from interface: Scope
        Returns if a custom attribute is associated with this object (scope).

        Notice that null is a valid value, so you can tell if an attribute is associated by examining the return value of Scope.getAttribute(java.lang.String).

        Specified by:
        hasAttribute in interface Scope

      • hasAttribute

        public boolean hasAttribute​(java.lang.String name,
                            boolean recurse)
        Description copied from interface: Scope
        Returns if a custom attribute is associated with this object.

        Notice that null is a valid value, so you can tell if an attribute is associated by examining the return value of Scope.getAttribute(java.lang.String).

        Specified by:
        hasAttribute in interface Scope
        recurse - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

      • setAttribute

        public java.lang.Object setAttribute​(java.lang.String name,
                                     java.lang.Object value)
        Description copied from interface: Desktop
        Sets the value of the specified custom attribute associated with the desktop.
        Specified by:
        setAttribute in interface Desktop
        Specified by:
        setAttribute in interface Scope
        Returns:
        the previous value associated with the attribute, if any

      • setAttribute

        public java.lang.Object setAttribute​(java.lang.String name,
                                     java.lang.Object value,
                                     boolean recurse)
        Description copied from interface: Scope
        Sets the custom attribute associated with this scope, or the parent scope.
        Specified by:
        setAttribute in interface Scope
        recurse - whether to look up the parent scope for the existence of the attribute.
        If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is replaced. Otherwise, it is the same as Scope.setAttribute(String,Object).

      • removeAttribute

        public java.lang.Object removeAttribute​(java.lang.String name)
        Description copied from interface: Desktop
        Removes the specified custom attribute associated with the desktop.
        Specified by:
        removeAttribute in interface Desktop
        Specified by:
        removeAttribute in interface Scope
        Returns:
        the previous value associated with the attribute, if any,

      • removeAttribute

        public java.lang.Object removeAttribute​(java.lang.String name,
                                        boolean recurse)
        Description copied from interface: Scope
        Removes the custom attribute associated with this scope.
        Specified by:
        removeAttribute in interface Scope
        recurse - whether to look up the parent scope for the existence of the attribute.
        If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is removed. Otherwise, it is the same as Scope.removeAttribute(String).

      • addScopeListener

        public boolean addScopeListener​(ScopeListener listener)
        Description copied from interface: Scope
        Adds a listener to listen whether this scope is changed. The listener is called when a custom attribute is added, removed, or the parent is changed.
        Specified by:
        addScopeListener in interface Scope
        Returns:
        weather the listener is added successfully. Note: if the resolver was added before, it won't be added again and this method returns false.

      • removeScopeListener

        public boolean removeScopeListener​(ScopeListener listener)
        Description copied from interface: Scope
        Removes a change listener from this scope.
        Specified by:
        removeScopeListener in interface Scope
        Returns:
        false if listener is not added before.

      • getWebApp

        public WebApp getWebApp()
        Description copied from interface: Desktop
        Returns the Web application this desktop belongs to.
        Specified by:
        getWebApp in interface Desktop

      • getRequestPath

        public java.lang.String getRequestPath()
        Description copied from interface: Desktop
        Returns the path of the request that causes this desktop to be created, or "" if not available. In other words, it is the request path of the first page (see Page.getRequestPath()).

        For example, "/foo/index.zul" (a ZUML page is requested) or /test (a richlet).

        Specified by:
        getRequestPath in interface Desktop
        See Also:
        Page.getRequestPath()

      • getCurrentDirectory

        public java.lang.String getCurrentDirectory()
        Description copied from interface: Desktop
        Returns the current directory (never null). It is empty if no current directory at all. Otherwise, it must end with '/'. In other words, you could use getCurrentDirectory() + relative_path.
        Specified by:
        getCurrentDirectory in interface Desktop

      • setCurrentDirectory

        public void setCurrentDirectory​(java.lang.String dir)
        Description copied from interface: Desktop
        Sets the current directory.
        Specified by:
        setCurrentDirectory in interface Desktop
        Parameters:
        dir - the current directory. If null, an empty string is assumed (means no current directory at all).

      • getNextKey

        public int getNextKey()
        Description copied from interface: DesktopCtrl
        Returns the next available key which is unique in the whole desktop.
        Specified by:
        getNextKey in interface DesktopCtrl

      • getNextUuid

        public java.lang.String getNextUuid​(Page page)
        Description copied from interface: DesktopCtrl
        Returns the next available UUID for a page. 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), integer overflow (too many UUID in one session, which can be considered as impossible), or a custom ID generator (IdGenerator) is used.
        Specified by:
        getNextUuid in interface DesktopCtrl

      • getNextUuid

        public java.lang.String getNextUuid​(Component comp)
        Description copied from interface: DesktopCtrl
        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), integer overflow (too many UUID in one session, which can be considered as impossible), or a custom ID generator (IdGenerator) is used.
        Specified by:
        getNextUuid in interface DesktopCtrl

      • addPage

        public void addPage​(Page page)
        Description copied from interface: DesktopCtrl
        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.

        Specified by:
        addPage in interface DesktopCtrl

      • removePage

        public void removePage​(Page page)
        Description copied from interface: DesktopCtrl
        Removes a page from this desktop.

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

        Specified by:
        removePage in interface DesktopCtrl

      • recoverDidFail

        public void recoverDidFail​(java.lang.Throwable ex)
        Description copied from interface: DesktopCtrl
        Called when the recovering failed.
        Specified by:
        recoverDidFail in interface DesktopCtrl

      • recycle

        public void recycle()
        Description copied from interface: DesktopCtrl
        Called when the desktop has been recycled. More precisely, it is called when the desktop is no longer used and ready to be re-used later.
        Specified by:
        recycle in interface DesktopCtrl

      • isAlive

        public boolean isAlive()
        Description copied from interface: Desktop
        Returns whether the desktop is still alive. It returns false once it is destroyed.
        Specified by:
        isAlive in interface Desktop
        See Also:
        DesktopCtrl.destroy()

      • destroy

        public void destroy()
        Description copied from interface: DesktopCtrl
        Called when the desktop is about to be destroyed.
        Specified by:
        destroy in interface DesktopCtrl

      • getSuspendedThreads

        public java.util.Collection<EventProcessingThread> getSuspendedThreads()
        Description copied from interface: DesktopCtrl
        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 pattern 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();) {
          //...
        }
        }
        }
        Specified by:
        getSuspendedThreads in interface DesktopCtrl

      • ceaseSuspendedThread

        public boolean ceaseSuspendedThread​(EventProcessingThread evtthd,
                                    java.lang.String cause)
        Description copied from interface: DesktopCtrl
        Ceases the specified event thread.
        Specified by:
        ceaseSuspendedThread in interface DesktopCtrl
        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.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • sessionWillPassivate

        public void sessionWillPassivate​(Session sess)
        Description copied from interface: DesktopCtrl
        Notification that the session, which owns this desktop, is about to be passivated (a.k.a., serialized) by the Web container.
        Specified by:
        sessionWillPassivate in interface DesktopCtrl

      • sessionDidActivate

        public void sessionDidActivate​(Session sess)
        Description copied from interface: DesktopCtrl
        Notification that the session, which owns this desktop, has just been activated (a.k.a., deserialized) by the Web container.
        Specified by:
        sessionDidActivate in interface DesktopCtrl

      • removeListener

        public boolean removeListener​(java.lang.Object listener)
        Description copied from interface: Desktop
        Removes a listener.
        Specified by:
        removeListener in interface Desktop
        Returns:
        whether the listener is removed successfully. Object.equals(java.lang.Object) is used to check whether a listener is added.

      • enableServerPush

        public boolean enableServerPush​(boolean enable,
                                java.io.Serializable enabler)
        Description copied from interface: DesktopCtrl
        Enable/Disable serverpush using reference counting, so that multiple enablers can use the same serverpush and deregister whenever they want.
        Specified by:
        enableServerPush in interface DesktopCtrl
        Parameters:
        enable - true/false enable/disable serverpush
        enabler - the same reference must be used to disable again
        Returns:
        Currently only used by DesktopEventQueue to enable several eventqueues to use the same ServerPush

      • enableServerPush

        public boolean enableServerPush​(ServerPush serverpush)
        Description copied from interface: DesktopCtrl
        Enables the server-push feature with the specified server-push controller. If you want to use the default serverpush, use Desktop.enableServerPush(boolean) instead. This method allows the caller to provide a server push for more control.

        Example: 

        desktop.enableServerPush(new PollingServerPush(1000,6000,5));

        Notice: a server push controller can be used in one desktop. It cannot be shared.

        Specified by:
        enableServerPush in interface DesktopCtrl
        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.
        See Also:
        Desktop.enableServerPush(boolean)

      • isServerPushEnabled

        public boolean isServerPushEnabled()
        Description copied from interface: Desktop
        Returns whether the server-push feature is enabled for this desktop.

        Default: false.

        Specified by:
        isServerPushEnabled in interface Desktop

      • scheduledServerPush

        public boolean scheduledServerPush()
        Description copied from interface: DesktopCtrl
        Returns if there is any scheduled task for server push.
        Specified by:
        scheduledServerPush in interface DesktopCtrl

      • onPiggybackListened

        public void onPiggybackListened​(Component comp,
                                boolean listen)
        Description copied from interface: DesktopCtrl
        Called when a component added or removed a listener for Events.ON_PIGGYBACK.

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

        Specified by:
        onPiggybackListened in interface DesktopCtrl
        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).

      • onPiggyback

        public void onPiggyback()
        Description copied from interface: DesktopCtrl
        Called each time when ZK Update Engine retrieves events. It is used to implement the piggyback feature by posting the events (see Events.ON_PIGGYBACK). The implementation could post events here. It should not process event here (since event thread might be used).

        Used only internally. Application developers shall not call it.

        Specified by:
        onPiggyback in interface DesktopCtrl

      • responseSent

        public void responseSent​(java.lang.String reqId,
                         java.lang.Object response)
        Description copied from interface: DesktopCtrl
        Called when ZK Update Engine has sent a response to the client.
        Specified by:
        responseSent in interface DesktopCtrl
        Parameters:
        reqId - the request ID that the response is generated for. Ignore if null.
        response - the response. Ignored if reqId is null.

      • getResponseId

        public int getResponseId​(boolean advance)
        Description copied from interface: DesktopCtrl
        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.

        Specified by:
        getResponseId in interface DesktopCtrl
        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

      • setResponseId

        public void setResponseId​(int resId)
        Description copied from interface: DesktopCtrl
        Sets the sequence ID of the response.

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

        Specified by:
        setResponseId in interface DesktopCtrl
        Parameters:
        resId - a value between 1 and 999. You can reset the ID by passing a non-positive value.

      • piggyResponse

        public java.util.List<AuResponse> piggyResponse​(java.util.Collection<AuResponse> response,
                                                boolean reset)
        Description copied from interface: DesktopCtrl
        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.

        Specified by:
        piggyResponse in interface DesktopCtrl
        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.

      • invalidate

        public void invalidate()
        Description copied from interface: Desktop
        Invalidates the desktop. All pages will be redrawn.
        Specified by:
        invalidate in interface Desktop

      • getStorage

        public Storage getStorage()
        Description copied from interface: Desktop
        Returns the storage in a desktop scope.
        Specified by:
        getStorage in interface Desktop
        Returns:
        a storage implementation, never null.

      • pushHistoryState

        public void pushHistoryState​(java.lang.Object state,
                             java.lang.String title,
                             java.lang.String url)
        Description copied from interface: Desktop
        Pushes a new history state.
        Specified by:
        pushHistoryState in interface Desktop
        Parameters:
        state - a state object.
        title - a title for the state. May be ignored by some browsers.
        url - the history entry's URL. Could be null.

      • replaceHistoryState

        public void replaceHistoryState​(java.lang.Object state,
                                java.lang.String title,
                                java.lang.String url)
        Description copied from interface: Desktop
        Replaces the current history state.
        Specified by:
        replaceHistoryState in interface Desktop
        Parameters:
        state - a state object.
        title - a title for the state. May be ignored by some browsers.
        url - the history entry's URL. Could be null.