Package jenkins.util

Class ProgressiveRendering

  • Direct Known Subclasses:
    RunListProgressiveRendering, View.AsynchPeople
    public abstract class ProgressiveRendering
extends Object
    A helper thread which does some computation in the background and displays incremental results using JavaScript. This is appropriate when the computation may be slow—too slow to do synchronously within the initial HTTP request—and has no side effects (since it may be canceled if the user simply browses to another page while it is running).
    1. Write a <script> section defining function display(data). (Call ts_refresh($('someid')) if using a sortable table.)
    2. Use <l:progressiveRendering handler="${it.something()}" callback="display"/> from your Jelly page to display a progress bar and initialize JavaScript infrastructure. (The callback attribute can take arbitrary JavaScript expression to be evaluated in the browser so long as it produces a function object.)
    3. Implement something() to create an instance of your subclass of ProgressiveRendering.
    4. Perform your work in compute().
    5. Periodically check canceled().
    6. As results become available, call progress(double).
    7. Make data() produce whatever JSON you want to send to the page to be displayed.
    ui-samples-plugin demonstrates all this.
    Since:
    1.484

    • Constructor Detail

      • ProgressiveRendering

        protected ProgressiveRendering()
        Constructor for subclasses.

    • Method Detail

      • start

        @JavaScriptMethod
public final void start()
        For internal use.

      • compute

        protected abstract void compute()
                         throws Exception
        Actually do the work.

        The security context will be that in effect when the web request was made. Stapler.getCurrentRequest() will also be similar to that in effect when the web request was made; at least, Ancestors and basic request properties (URI, locale, and so on) will be available.

        Throws:
        Exception - whenever you like; the progress bar will indicate that an error occurred but details go to the log only

      • data

        @NonNull
protected abstract net.sf.json.JSON data()
        Provide current data to the web page for display.

        While this could be an aggregate of everything that has been computed so far, more likely you want to supply only that data that is new since the last call (maybe just {} or []), so that the page can incrementally update bits of HTML rather than refreshing everything.

        You may want to make your implementation synchronized, so that it can track what was sent on a previous call, in which case any code running in compute() which modifies these fields should also temporarily be synchronized on the same monitor such as this.

        Returns:
        any JSON data you like

      • progress

        protected final void progress​(double completedFraction)
        Indicate what portion of the work has been done. (Once compute() returns, the work is assumed to be complete regardless of this method.)
        Parameters:
        completedFraction - estimated portion of work now done, from 0 (~ 0%) to 1 (~ 100%)

      • canceled

        protected final boolean canceled()
        Checks whether the task has been canceled. If the rendering page fails to send a heartbeat within a certain amount of time, the user is assumed to have moved on. Therefore compute() should periodically say: if (canceled()) return;
        Returns:
        true if user seems to have abandoned us, false if we should still run

      • news

        @JavaScriptMethod
public final net.sf.json.JSONObject news()
        For internal use.

      • executorService

        protected ExecutorService executorService()
        May be overridden to provide an alternate executor service.
        Returns:
        by default, Timer.get()

      • timeout

        protected long timeout()
        May be overridden to control the inactivity timeout. If no request from the browser is received within this time, the next call to canceled() will be true.
        Returns:
        timeout in milliseconds; by default, 15000 (~ 15 seconds)