public abstract class AbstractHTMLContext extends java.lang.Object implements HTMLContext, HTTPReplyHandler
GUIContext enables the usage of HTML as graphical user
interface. Due to the synchronous, user-initiated communication protocol
(HTTP) used with HTML, the methods and usage of this context differs from
other GUI-contexts: Clients (a browser) send requests which will be processed
by the server (the application using the context) and responded to. This
strict request-response-protocol has to be respected. getResponse(de.aristaflow.adept2.ui.htmlgui.HTMLContext.HTTPReply)
while the application sets the corresponding response via
setResponse(de.aristaflow.adept2.ui.htmlgui.HTMLContext.HTTPReply, de.aristaflow.adept2.ui.htmlgui.HTMLContext.Response)
. However, there are two special cases: The initial content which is a
response that can to be set before the corresponding request has arrived,
and the final response which needs to be set when the application terminates.
All other communication will take place via
getResponse(de.aristaflow.adept2.ui.htmlgui.HTMLContext.HTTPReply)
called by the browser request and
setResponse(de.aristaflow.adept2.ui.htmlgui.HTMLContext.HTTPReply, de.aristaflow.adept2.ui.htmlgui.HTMLContext.Response).
Meanwhile the application just waits
for requests from the browser until either the timeout occurs or the
corresponding thread is interrupted for instance due to a signal from the
outside.
As always, the GUI of an application needs to be created when initialising
the application. In case of an application using this context, the GUI will
be HTML, for instance an HTML-form. This usually contains several URLs at
least one for returning the data entered in the form. The application has to
use the URLs returned by this context (getURL() and
getURL(Map)), otherwise the requests from the browser cannot be
assigned to this context. The created initial HTML-content can be set via
setInitialContent(String) and the application can finish its
initialisation. Since the strict request-response-protocol also applies to
the initial content, the browser to show the created HTML needs to request it
initially. Usually the browser will have a URL to GET the HTML, the content
may also be provided directly by a get-method of (a subclass of) this
context or by the application as response to an empty client request via
getResponse(de.aristaflow.adept2.ui.htmlgui.HTMLContext.HTTPReply).
However, when setting the
initial content via this class, the initial content will be used as the
response to the very first request (received via
getResponse(de.aristaflow.adept2.ui.htmlgui.HTMLContext.HTTPReply).
When running, the application usually just
waits for requests from the browser. As
soon as a request arrives, the application will be provided with the
corresponding data. It then needs to create an appropriate response and
provide this to the browser via
setResponse(de.aristaflow.adept2.ui.htmlgui.HTMLContext.HTTPReply, de.aristaflow.adept2.ui.htmlgui.HTMLContext.Response).
The thread providing the browser request is blocked until the response is
available.
This HTML context allows for sophisticated request-response-scenarios for
instance keeping requests from the browser unresponded when using Ajax.
Therefore multiple requests need to be handled concurrently which requires to
provide the reply when setting the response. Otherwise this context cannot
correlate the response to the corresponding request.
When waiting for a request from the browser, the application thread will be
interrupted in case of a signal from the runtime environment to the
application. Additionally, it will stop waiting when the provided timeout
elapsed. This allows for instance to support a keep alive protocol to check
whether the browser has been terminated meanwhile. In this case the
application does not need to wait any longer since its UI has been vanished
(on client-side).
However, signals from the runtime environment (for instance a kill signal) lead to a sudden end of the application but the UI will not be notified (since the application cannot contact the UI except by responding to a request). Therefore the application should always set a final response before finally terminating. This response will be used for all requests arriving afterwards.
As always, methods called from the application will check for the right
executing thread and will throw an
InvalidExecutorThreadException if this is not the case.
Subclasses need to provide a method for closing the HTML context. Additionally, they can override any method. This can be useful for instance to provide a special handling of the initial content.
HTMLContext.Attachment, HTMLContext.HTTPReply, HTMLContext.Response| Modifier and Type | Field and Description |
|---|---|
protected java.net.URL |
baseURL
The base URL for this HTML context which is a URL relative to the
HTTP-service handling the HTTP-requests (containing the reply data) sent to
this context.
|
static HTMLContext.Response |
DEFAULT_FINAL_RESPONSE
A response that can be used as default for the final response.
|
protected HTMLContext.Response |
finalResponse
The final response that will be used for all HTTP-request after the reply
handler has been shut down.
|
protected HTMLContext.Response |
initialContent
The response containing the initial HTML-content.
|
protected java.util.logging.Logger |
logger
My logger.
|
protected java.util.Map<HTMLContext.HTTPReply,java.util.concurrent.CountDownLatch> |
replies
All replies that are currently pending and waiting for a response.
|
protected boolean |
replyHandlerTerminated
Whether the reply handler (the component executing thread) has terminated
and does not process any more HTTP-requests any more.
|
protected java.util.Map<HTMLContext.HTTPReply,HTMLContext.Response> |
responses
All responses that are currently set for the corresponding reply and are
waiting for the corresponding replying thread to get them.
|
protected java.lang.Thread |
thread
The thread which executes the application using this context.
|
| Constructor and Description |
|---|
AbstractHTMLContext(java.lang.Thread thread)
Creates a new abstract HTML context providing the usual behaviour needed
for an HTML context.
|
| Modifier and Type | Method and Description |
|---|---|
protected void |
checkForValidExecutorThread()
Checks if the method is called by the main thread of the application.
|
HTMLContext.Response |
getResponse(HTMLContext.HTTPReply reply)
Provides the reply handler with the parameters retrieved by the
HTTP-request.
|
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 |
setBaseURL(java.net.URL baseURL)
Sets the base URL on which the reply handler is reachable via HTTP.
|
void |
setFinalResponse(HTMLContext.Response response)
Sets the designated response as feedback to currently open replies from
previous calls to
HTMLContext.waitForHTTPReply(long) and/or as general
response for all following requests. |
protected void |
setFinalResponse(HTMLContext.Response response,
boolean checkThread)
Sets the final response to the designated one and optionally checks for the
valid executor thread.
|
void |
setInitialContent(java.lang.String initialContent)
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
HTMLContext.waitForHTTPReply(long). |
HTMLContext.HTTPReply |
waitForHTTPReply(long timeout)
Waits for the reply of the client sent as response to the provided
HTML-document.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitclosepublic static final HTMLContext.Response DEFAULT_FINAL_RESPONSE
protected final java.util.logging.Logger logger
protected final java.lang.Thread thread
protected java.net.URL baseURL
protected HTMLContext.Response initialContent
protected final java.util.Map<HTMLContext.HTTPReply,java.util.concurrent.CountDownLatch> replies
protected final java.util.Map<HTMLContext.HTTPReply,HTMLContext.Response> responses
protected HTMLContext.Response finalResponse
protected volatile boolean replyHandlerTerminated
finalResponse that applies to all following requests. public AbstractHTMLContext(java.lang.Thread thread)
thread - The thread which executes the application using this context.public java.net.URL getURL()
HTMLContextHTMLContext.waitForHTTPReply(long). InvalidExecutorThreadException will be thrown if the
method is not called by the main thread of the corresponding component.getURL in interface HTMLContextpublic java.net.URL getURL(java.util.Map<java.lang.String,java.lang.String> query)
HTMLContextInvalidExecutorThreadException will be thrown if the
method is not called by the main thread of the corresponding component.getURL in interface HTMLContextquery - 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.HTMLContext.getURL()public void setInitialContent(java.lang.String initialContent)
HTMLContextURL and by HTMLContext.waitForHTTPReply(long). HTMLContext.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. InvalidExecutorThreadException will be thrown if the method
is not called by the main thread of the corresponding component.setInitialContent in interface HTMLContextinitialContent - The content of this HTML-context, that is the
user-interface in HTML for the executed application.public void setResponse(HTMLContext.HTTPReply reply, HTMLContext.Response response)
HTMLContextHTMLContext.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. InvalidExecutorThreadException will be
thrown if the method is not called by the main thread of the corresponding
component. setResponse in interface HTMLContextreply - 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 HTMLContext.waitForHTTPReply(long).public void setFinalResponse(HTMLContext.Response response)
HTMLContextHTMLContext.waitForHTTPReply(long) and/or as general
response for all following requests. This method indicates that no further
requests (normally received by HTMLContext.waitForHTTPReply(long)) will be
accepted and processed. Instead all requests will receive the designated
response. HTMLContext.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.
setFinalResponse in interface HTMLContextresponse - The response to send back as general response to all
outstanding and all following requests.protected final void setFinalResponse(HTMLContext.Response response, boolean checkThread)
HTMLContext.close() since closing is usually not called
from the executor thread.response - The response to send back as general response to all
outstanding and all following requests.checkThread - Whether to check for the valid executor thread. Usually
this should be done. Only when setting from HTMLContext.close() the
thread must not be checked.public HTMLContext.HTTPReply waitForHTTPReply(long timeout) throws java.lang.InterruptedException
HTMLContextRuntimeEnvironment.dispatch()
). If no signal is set, it should just reenter this method. 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. 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.
waitForHTTPReply in interface HTMLContexttimeout - The time (in milliseconds) to wait for a HTTP-request. If
the timeout elapsed before a request has been received,
null will be returned.null if the
timeout occurred or the final response has already been set.java.lang.InterruptedException - If the waiting thread is interrupted due to a
signal sent by the runtime environment, an
InterruptedException will be thrown.protected void checkForValidExecutorThread()
InvalidExecutorThreadException is thrown.InvalidExecutorThreadException - If the current thread is not the
dedicated thread for the component execution, a
InvalidExecutorThreadException will be thrown.public void setBaseURL(java.net.URL baseURL)
HTTPReplyHandlersetBaseURL in interface HTTPReplyHandlerbaseURL - The URL on which this reply handler is reachable via HTTP.public HTMLContext.Response getResponse(HTMLContext.HTTPReply reply) throws java.lang.InterruptedException
HTTPReplyHandlerInterruptedException to indicate an exceptional situation
which will not be responded to by this handler.getResponse in interface HTTPReplyHandlerreply - The parameters sent by the HTTP-client to the URL of this
handler. This must not be null!java.lang.InterruptedException - If the waiting thread is interrupted and
should no longer wait for a response, an
InterruptedException will be thrown.