Interface UiEngine

  • All Known Implementing Classes:
    UiEngineImpl

    public interface UiEngine
    UI engine is responsible to process requests from the client, sends the response back to the client with the assistance of ExecutionCtrl.

    ExecutionCtrl encapsulates protocol-dependent codes, such that UiEngine works independent of any protocol (such as HTTP).

    Note: each application (a ServletContext in HTTP) has its own UI Engine (Singleton per app).

    Author:
    tomyeh
    • Method Detail

      • start

        void start​(WebApp wapp)
        Starts the engine.
      • stop

        void stop​(WebApp wapp)
        Stops the engine. Called only if the server is about to stop.
      • desktopDestroyed

        void desktopDestroyed​(Desktop desktop)
        Called when a desktop is being removed.

        Application developers don't need to remove pages and desktops. They are removed and cleaned up automatically.

      • setOwner

        Component setOwner​(Component comp)
        Called before a component redraws itself if the component might include another page.

        If a new page is created, the specified component will become the owner of the new page.

        It must reset the owner in the finally clause.

        old = ue.setOwner(this);
        try{
          ...
        } finally {
          ue.setOwner(old);
        }

        Since 5.0.6, the owner must implement Includer.

        Returns:
        the previous owner
        Since:
        5.0.0
      • isInvalidated

        boolean isInvalidated​(Component comp)
        Returns if this component needs to be redrawn.

        Note:

        1. It always returns true if the current execution is not an asynchronous update.
        2. If its parent is invalidated, this component will be redrawn too, but this method returns false since addInvalidate(Component) was not called against this component.
        Since:
        3.0.5
      • addInvalidate

        void addInvalidate​(Page page)
        Invalidates the page to cause all of its components to redraw.
      • addSmartUpdate

        void addSmartUpdate​(Component comp,
                            java.lang.String attr,
                            java.lang.Object value,
                            boolean append)
        Smart-updates a property of the peer widget.
        Parameters:
        append - whether to append the updates of properties with the same name. If false, only the last value of the same property will be sent to the client.
        Since:
        5.0.2
      • addSmartUpdate

        void addSmartUpdate​(Component comp,
                            java.lang.String attr,
                            java.lang.Object value,
                            int priority)
        Adds a smart update that will be executed at the given priority. The higher priority, the earlier the update is executed. If addSmartUpdate(Component, String, Object, boolean) is invoked, the priority is assumed to 0.

        If the priority is the same, the update is executed in the order of first-in-first out. You rarely need to control the sequence, unless the update is used to instantiate client-side widgets that other updates might depend on. In this case, it is suggested to specify the priority as 10000 (and not to use priority higher than 10000 for other situation).

        Since:
        6.0.0
      • clearSmartUpdate

        void clearSmartUpdate​(Component comp)
        Clears all existing smart updates that belong to the given component.
        Since:
        10.0.0
      • addResponse

        void addResponse​(java.lang.String key,
                         AuResponse response,
                         int priority)
        Adds a response with the given priority. The higher priority, the earlier the update is executed. The priority of addResponse(String, AuResponse) and addResponse(AuResponse) is assumed to be 0.

        If the priority is the same, the update is executed in the order of first-in-first out.

        Since:
        6.0.1
      • addMoved

        void addMoved​(Component comp,
                      Component oldparent,
                      Page oldpg,
                      Page newpg)
        Called to update (redraw) a component, when a component is moved. If a component's page or parent is changed, this method need to be called only once for the top one.
        Parameters:
        oldparent - the parent before moved
        oldpg - the page before moved
        newpg - the page after moved
      • addUuidChanged

        void addUuidChanged​(Component comp)
        Called before changing the component's UUID.
        Since:
        5.0.3
      • execNewPage

        void execNewPage​(Execution exec,
                         PageDefinition pagedef,
                         Page page,
                         java.io.Writer out)
                  throws java.io.IOException
        Creates components specified in the given page definition. Called when a new page is creates.
        Throws:
        java.io.IOException
      • recycleDesktop

        void recycleDesktop​(Execution exec,
                            Page page,
                            java.io.Writer out)
                     throws java.io.IOException
        Reuse the desktop and generate the output.
        Throws:
        java.io.IOException
        Since:
        5.0.0
      • execUpdate

        void execUpdate​(Execution exec,
                        java.util.List<AuRequest> requests,
                        AuWriter out)
                 throws java.io.IOException
        Executes an asynchronous update to a component (or page). It is the same as execUpdate(exec, requests, null, out).

        Note: the output must be XML and UTF-8.

        Parameters:
        requests - a list of AuRequest.
        Throws:
        java.io.IOException
      • finishUpdate

        JSONArray finishUpdate​(java.lang.Object ctx,
                               java.util.List<java.lang.Throwable> errs)
                        throws java.io.IOException
        Finishes the update and returns the result in an array of JSON object. Notice it does not deactivate the execution. Rather, the caller has to invoke closeUpdate(java.lang.Object).

        It is designed to implement Bridge.

        Parameters:
        ctx - the context returned by the previous call to startUpdate(org.zkoss.zk.ui.Execution)
        errs - the collection of errors if any.
        Throws:
        java.io.IOException
        Since:
        10.0.0
        See Also:
        finishUpdate(Object)
      • sendRedirect

        void sendRedirect​(java.lang.String uri,
                          java.lang.String target)
        Sends a temporary redirect response to the client using the specified redirect location URL.

        After calling this method, the caller shall end the processing immediately (by returning). All pending requests and events will be dropped.

        Parameters:
        uri - the URI to redirect to, or null to reload the same page
        target - the new target, or null to denote the same browser window
      • setAbortingReason

        void setAbortingReason​(AbortingReason aborting)
        Aborts the current execution. if not null, it means the current execution is aborting

        Note: if setAbortingReason is ever set with non-null, you CANNOT set it back to null.

        After call this method, you shall not keep processing the page because the rendering is dropped and the client is out-of-sync with the server.

        Parameters:
        aborting - the aborting reason.
      • notify

        void notify​(java.lang.Object obj)
        Wakes up a single event processing thread that is waiting on the specified object.

        Unlike notify(Desktop, Object), this method can be invoked only if the same desktop is locked for processing requests.

        Parameters:
        obj - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object).
        Throws:
        UiException - if it is called not during event processing.
        See Also:
        notify(Desktop, Object), notifyAll(Object)
      • notify

        void notify​(Desktop desktop,
                    java.lang.Object obj)
        Wakes up a single event processing thread for the specified desktop that is waiting on the specified object.

        Unlike notify(Object), this method can be called any time. It is designed to let working threads resume an event processing thread.

        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).

        Parameters:
        desktop - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.
        obj - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object).
        See Also:
        notify(Object), notifyAll(Desktop, Object)
      • notifyAll

        void notifyAll​(java.lang.Object obj)
        Wakes up all event processing thread that are waiting on the specified object.

        Unlike notify(Desktop, Object), this method can be invoked only if the same desktop is locked for processing requests.

        Parameters:
        obj - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object).
        Throws:
        UiException - if it is called not during event processing.
        See Also:
        notify(Desktop, Object), notifyAll(Object)
      • notifyAll

        void notifyAll​(Desktop desktop,
                       java.lang.Object obj)
        Wakes up all event processing threads for the specified desktop that are waiting on the specified object.

        Unlike notifyAll(Object), this method can be called any time. It is designed to let working threads resume an event processing thread.

        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).

        Parameters:
        desktop - the desktop which the suspended thread is processing. It must be the same desktop of the suspended thread.
        obj - any non-null object to identify what to notify. It must be same object passed to wait(java.lang.Object).
        See Also:
        notify(Object), notifyAll(Desktop, Object)
      • activate

        boolean activate​(Execution exec,
                         int timeout)
        Activates an execution such that you can access a component. Unlike activate(Execution), you could specify an amount of time (timeout), and it returns false if it takes longer than the given amount of time before granted.
        Parameters:
        timeout - the number of milliseconds to wait before giving up. It is ignored if negative, i.e., it waits until granted if negative.
        Returns:
        whether the activation succeeds
        Since:
        5.0.6
      • deactivate

        void deactivate​(Execution exec)
        Deactivates an execution, such that other threads could activate and access components.
      • beginUpdate

        void beginUpdate​(Execution exec)
        Activates and prepare for asynchronous update
        Since:
        3.5.0
      • endUpdate

        void endUpdate​(Execution exec)
                throws java.io.IOException
        Executes posted events, deactivate and ends the asynchronous update.
        Throws:
        java.io.IOException
        Since:
        5.0.0
      • getNativeContent

        java.lang.String getNativeContent​(Component comp,
                                          java.util.List<NodeInfo> children,
                                          Native.Helper helper)
        Retrieve the native content for a property of the specified component. The native content is a value of a property that is represented by a XML fragment (actually NativeInfo).

        Example:

        <html>
         <attribute name="content">
          <br/>
         </attribute>
        </html>
        Parameters:
        comp - the component that the native content will be assigned to. It is the object that the self variable is assigned when evaluating EL expressions.
        children - a list of NativeInfo, TextInfo and others. This method evaluates them one-by-one and returns the result which is the value that will be assigned.
        helper - the helper used to generate the content.
        Since:
        3.5.0
        See Also:
        Property
      • hasSuspendedThread

        boolean hasSuspendedThread()
        Returns if any suspended event processing thread in the whole system.
      • getSuspendedThreads

        java.util.Collection<EventProcessingThread> getSuspendedThreads​(Desktop desktop)
        Returns a collection of suspended event processing threads belonging to the specified desktop, or empty if no suspended thread at all.

        An event processing thread is an instance of EventProcessingThread

        Parameters:
        desktop - the desktop that the suspended event processing threads belong to (never null).
      • ceaseSuspendedThread

        boolean ceaseSuspendedThread​(Desktop desktop,
                                     EventProcessingThread evtthd,
                                     java.lang.String cause)
        Ceases the specified event thread.
        Parameters:
        desktop - which desktop the event thread belongs to
        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.
      • disableClientUpdate

        boolean disableClientUpdate​(Component comp,
                                    boolean disable)
        Sets whether to disable the update of the client widget. By default, if a component is attached to a page, modifications that change the visual representation will be sent to the client to ensure the consistency.
        Returns:
        whether it has been disabled before this invocation, i.e., the previous disable status
        Since:
        3.6.2