Package de.aristaflow.adept2.ui.htmlgui

Interface HTMLContext

  • All Superinterfaces:
    AutoCloseable, Closeable, GUIContext
    All Known Implementing Classes:
    AbstractHTMLContext, RemoteHTMLContext, SwtHtmlContext
    public interface HTMLContext
extends GUIContext
    HTMLContext provides the means to create an HTML-document as user-interface for an executed component. It encapsulates the special HTTP-communication (initiated by the client, simple request-response model, document-oriented), that is HTTP-requests are parsed and provided via this interface.

    The initial content of the user-interface, that is the plain HTML can be created and set) in the initialisation ( ExecutableComponent.init(de.aristaflow.adept2.model.runtimeenvironment.SessionContext) or ExecutableComponent.initResume(String, de.aristaflow.adept2.model.runtimeenvironment.SessionContext) ) of the corresponding component. This is not mandatory but if it is done, this context will handle the first request by sending this initial content. Otherwise the component needs to wait for the first request by the client and return the initial content in response to this.

    Replies to the HTML user-interface, for instance form data provided via HTTP-POST or HTTP-GET, has to be sent to the (relative) URLs provided by this interface. This allows the server to identify the appropriate application including its HTMLContext and provide the data appropriately ( waitForHTTPReply(long)). As stated before, no data need to be provided which is a normal HTTP—request to get the content (again).

    To allow for pre-parsed reply content, only URL-encoded GET or URL-encoded POST as well as multipart POST are allowed. These data will be parsed to a HTTPReply that provides simple string-string maps (that is mapping parameter names to the corresponding values) and string-attachment maps for parameters providing binary and/or file content. Additionally, parameters may have several values, in which case the simple maps provide lists as values - for strings as well as for attachments. Whether a parameter has a simple or a list value is determined by whether the parameter occurs only once in the reply or several times.

    Running the component just consists of waiting for replies of the client and processing them appropriately. It may handle several replies concurrently which allows for flexible Ajax-support.

    After retrieval of a reply, the executed component eventually has to provide a response. The response is then sent to the client again, just like the initial document. The component then just needs to wait for another reply of the client again. Since several replies can be handled concurrently, setting a response requires providing the corresponding reply again.
    If the component terminates be sure to call setFinalResponse(Response) to indicate to all requests (the open ones as well as the following ones), that they will not processed any more.

    Call these methods only with the valid component executing thread. Otherwise an InvalidExecutorThreadException will be thrown.

    • Method Detail

      • getURL

        @Deprecated
URL getURL()
        Deprecated.
        Use getRelativeLink() instead unless you absolutely need an absolute URL. For these cases this method will not be removed.
        Gets the URL which the server provides for responses and signals to the executed application corresponding to this context. For instance, the generated HTML-content may provide data via HTTP-POST or HTTP-GET to this URL. The data is handled by the server and provided via waitForHTTPReply(long).
        An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.
        Returns:
        The URL for submitting data from the HTML-content back to the application.

      • getRelativeLink

        default String getRelativeLink()
        Gets the path relative to the server resource corresponding to this context. This allows for relative links sending HTTP requests to this context, i. e. responses and signals to the executed application corresponding to this context. For instance, the generated HTML-content may provide data via HTTP-POST or HTTP-GET to this (relative) URL. The data is handled by the server and provided via waitForHTTPReply(long).
        An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.
        Returns:
        The string identifying the server resource of this context for submitting data from the HTML-content back to the application.

      • getURL

        @Deprecated
URL getURL​(Map<String,​String> query)
        Deprecated.
        Use getRelativeLink(Map) instead.
        Gets the URL which the server provides for responses and signals to the executed application corresponding to this URL context appended by the designated string map as URL query (after a '?'), that is the key and value-pairs are appended and separated by &.
        An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.
        Parameters:
        query - Key-value-pairs to be appended as query to the URL for responses and signals to the executed application. The strings for keys and values will be encoded appropriately for usage in a URL.
        Returns:
        The URL for submitting data from the HTML-content back to the application appended by the designated query-string.
        See Also:
        getURL()

      • getRelativeLink

        default String getRelativeLink​(Map<String,​String> query)
        Gets the path relative to the server resource corresponding to this context. This allows for relative links sending HTTP requests to this context, i. e. responses and signals to the executed application corresponding to this context. The relative link will be prepended by the designated URL query (after a '?'), that is the key and the value pars are appended by &.
        An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.
        Parameters:
        query - Key-value-pairs to be appended as query to the relative path for responses and signals to the executed application. The strings for keys and values will be encoded appropriately for usage in a (relative) URL.
        Returns:
        The string identifying the server resource of this context for submitting data from the HTML-content back to the application appended by the designated query-string.

      • setInitialContent

        void setInitialContent​(String htmlContent)
        Sets the initial (HTML-)content of this context, that is the designated content is sent as response to the first to the client for visualising the executed application. Feedback/data can be retrieved via the usage of the provided URL and by waitForHTTPReply(long).
        The content is only provided once. Afterwards, setResponse(HTTPReply, Response) has to be used for sending HTML to the user. If you want to set the initial content, be sure to set it before the first request arrives! However, you need not set it here, you can also provide it to a received empty request.
        An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.
        Parameters:
        htmlContent - The content of this HTML-context, that is the user-interface in HTML for the executed application.

      • setResponse

        void setResponse​(HTMLContext.HTTPReply reply,
                 HTMLContext.Response response)
        Responds to the designated reply that has been received via waitForHTTPReply(long). The response can be a simple HTML-document indicating the successful completion of the activity, some HTML as response to an Ajax-request or even the complete HTML again, that has been initially sent, in case of missing values.
        Providing the reply here again allows to handle several HTTP-requests concurrently and send responses to the corresponding replies in an arbitrary order. However, each reply waits for an appropriate response. Therefore make sure to set a response for each retrieved reply (HTTP-request).
        If the reply handler An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.
        This method does not wait for the server to accept the reply. Rather the reply is sent as the next reply to a HTTP-request.
        Parameters:
        reply - The reply to which the designated response should be assigned. This allows to handle several replies concurrently and send responses in an arbitrary order. The caller is responsible for closing, however, usually this is provided by waitForHTTPReply(long) in which case this HTMLContext is responsible for closing.
        response - The response to send back to the user as response to the values provided by waitForHTTPReply(long). The HTMLContext.Response will be coupled to this HTMLContext, so do not close it; clone it if required longer than this HTMLContext.

      • setFinalResponse

        void setFinalResponse​(HTMLContext.Response response)
        Sets the designated response as feedback to currently open replies from previous calls to waitForHTTPReply(long) and/or as general response for all following requests. This method indicates that no further requests (normally received by waitForHTTPReply(long)) will be accepted and processed. Instead all requests will receive the designated response.
        Note that other than setResponse(HTTPReply, Response) the response here must not be null!

        Be sure to call this method if you do not intend to process another request! Afterwards you must not wait for another reply since all replies will be responded to with the response set here.
        An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

        Parameters:
        response - The response to send back as general response to all outstanding and all following requests. The response will be closed after the creation.

      • waitForHTTPReply

        HTMLContext.HTTPReply waitForHTTPReply​(long timeout)
                                throws InterruptedException
        Waits for the reply of the client sent as response to the provided HTML-document. The calling thread blocks until the response arrived, a signal for the component was sent or a timeout happened. In case of the signal, the calling thread is interrupted. It should then check for signals in the environment ( RuntimeEnvironment.dispatch() ). If no signal is set, it should just reenter this method.
        In case of a timeout, null will be returned and the calling thread can handle this appropriately. The timeout allows the component to be notified in case the client showing the HTML-document is not responding. It may then signal this to the RuntimeEnvironment by failing.
        An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

        Do not forget so set an appropriate response after retrieval of the reply. Since the data for the reply is sent via a HTTP-request, a corresponding response is needed. Otherwise the corresponding request will be left unanswered.
        An empty reply (not having any parameters or attachments) indicates a request for the complete initial or rather the complete current HTML.

        Parameters:
        timeout - The time (in milliseconds) to wait for a HTTP-request. If the timeout elapsed before a request has been received, null will be returned.
        Returns:
        The reply sent by the client. This contains key-value-pairs or even lists of values, the values being either simple strings or attachments (binary data and/or file uploads) sent via the GET- and POST-method. The maps of the reply will be empty if the client does not send a reply. The reply will be null if the timeout occurred or the final response has already been set. The HTMLContext.HTTPReply will be coupled to this HTMLContext, so do not close it; clone it if required longer than this HTMLContext.
        Throws:
        InterruptedException - If the waiting thread is interrupted due to a signal sent by the runtime environment, an InterruptedException will be thrown.