de.aristaflow.adept2.ui.htmlgui

Interface HTMLContext

All Superinterfaces:

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

Author:

Ulrich Kreher

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	HTMLContext.Attachment An Attachment represents either binary data or a (text) file uploaded to the HTTP-service.
static class	HTMLContext.HTTPReply The HTTPReply wraps the data sent as GET or POST to the web server.
static class	HTMLContext.Response A HTTP-response to be sent to the HTTP-client.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this HTMLContext.
java.net.URL	getURL() Gets the URL which the server provides for responses and signals to the executed application corresponding to this context.
java.net.URL	getURL(java.util.Map<java.lang.String,java.lang.String> query) 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 '?')
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.
void	setInitialContent(java.lang.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.
void	setResponse(HTMLContext.HTTPReply reply, HTMLContext.Response response) Responds to the designated reply that has been received via waitForHTTPReply(long).
HTMLContext.HTTPReply	waitForHTTPReply(long timeout) Waits for the reply of the client sent as response to the provided HTML-document.

Method Detail

getURL

java.net.URL getURL()

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.

getURL

java.net.URL getURL(java.util.Map<java.lang.String,java.lang.String> query)

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

setInitialContent

void setInitialContent(java.lang.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.

response - The response to send back to the user as response to the values provided by waitForHTTPReply(long).

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.

close

void close()

Closes this HTMLContext. Implementations have to clean up which usually involves deregistering the HTML-context from the corresponding HTTP-server, for instance de.aristaflow.adept2.ui.htmlgui.httpservice.HTTPService#deregisterReplyHandler(de.aristaflow.adept2.base.sessionmanagement.SessionToken, String) . Additionally, a final response should be set here in case it has not been set before. This will unblock threads currently waiting for a response that will not come any more.

Specified by:

close in interface GUIContext

waitForHTTPReply

HTMLContext.HTTPReply waitForHTTPReply(long timeout)
                                throws java.lang.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.

Throws:

java.lang.InterruptedException - If the waiting thread is interrupted due to a signal sent by the runtime environment, an InterruptedException will be thrown.