Class SiteRunner
- All Implemented Interfaces:
AutoCloseable
Your application passes the requests that it receives to the site, from a web view of its own for instance, and gets the responses back:
var runner = new SiteRunner()
.scheme("myapp")
.serverName("app")
.staticUberJarResourceBase("webapp")
.start(new MySite());
var response = runner.handle("/login", new SiteRequest(RequestMethod.POST)
.header("Content-Type", "application/x-www-form-urlencoded")
.bodyAsBytes(body));
A response is returned once it's complete, or you can receive it while
it's being written with a SiteResponseListener, which is better
suited for large downloads and event streams.
Requests can be handled from any number of threads at the same time.
A request runs on the thread that calls handle, and the only
thread it can start is a short one that purges the continuations that
expired. Sessions are kept in memory and identified with a
cookie, and an optional SiteCookieJar can act as the browser for
the cookies when your web view doesn't keep them.
When no route handles a request and no static file is served for it,
the response has the status 404 and SiteResponse.isHandled()
returns false, so that your application can still answer it in its
own way.
Several site runners can run side by side, but keep in mind that the engine configuration is shared by all the sites of a process. Its proxy root URL doesn't apply to a site runner, since you configure the scheme and the server name of the runner directly.
- Since:
- 1.11.0
- See Also:
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionInstantiates a new site runner, whose properties have the system properties as their parent.SiteRunner(HierarchicalProperties properties) Instantiates a new site runner that will set up its site with the properties that you provide. -
Method Summary
Modifier and TypeMethodDescriptionvoidclose()Stops this site runner, which makes it possible to use it inside a try-with-resources block.contextPath(String contextPath) Configures the context path that the site is reached at.cookieJar(SiteCookieJar jar) Configures the cookie jar that keeps the cookies of the responses and adds them to the requests, like a browser does.protected CookiecreateSessionCookie(SiteRequest request, String id) Creates the cookie that identifies a new session.Retrieves the context path that the site is reached at.Retrieves the root URL of the origin that the site is reached at,myapp://appfor instance.getSite()Retrieves the site that's being run.Handles aGETrequest.handle(String url, SiteRequest request) Handles a request and returns its response once it's complete.handle(String url, SiteRequest request, SiteResponseListener listener) Handles a request and gives its response to a listener while it's being written.protected booleanIndicates whether a detached event stream stays open when there's no listener for the response, so that out-of-container tests can look at the events that are sent afterwards.protected booleanIndicates whether a request can be handled more than once, which out-of-container tests have always been able to do.protected booleanIndicates whether requests are still handled after this runner was stopped and its site was shut down.protected booleanIndicates whether static files are served for the requests that no route handles.protected booleanIndicates whether the cookies that a site sets are checked for characters that can't be sent, like with Jetty.maxFormContentSize(int size) Configures the maximum size of a urlencoded form body.maxFormParameters(int parameters) Configures the maximum number of parameters in a urlencoded form body, where all the values of one name count as one parameter.Retrieves the hierarchical properties that the site is set up with.Configures the scheme of the origin that the site is reached at, which can be a custom scheme that only your application uses.secure(boolean secure) Configures whether the origin is secure even though its scheme isn'thttps, which is the case for a custom scheme that can only be reached from within your application.serverName(String serverName) Configures the host name of the origin that the site is reached at.serverPort(int serverPort) Configures the port of the origin that the site is reached at.sessionCookieName(String name) Configures the name of the cookie that identifies the session.sessionTimeout(int seconds) Configures after how many seconds a session that isn't used will expire.sessionUrlParameters(boolean enabled) Configures whether a session can also be identified by a;jsessionid=path parameter, whichResponse.encodeURL(java.lang.String)will then add when the session didn't come from a cookie.Sets up and deploys a site, after which it will handle requests.staticResourceBase(String base) Configures the directory with the static files of the site.Configures the base directory in the classpath where the static files of the site will be looked up from, which in a native image means its embedded resources.voidstop()Shuts the site down, closes the detached event streams that are still open and forgets the sessions.
-
Field Details
-
DEFAULT_SCHEME
- See Also:
-
DEFAULT_SERVER_NAME
- See Also:
-
DEFAULT_SERVER_PORT
public static final int DEFAULT_SERVER_PORT- See Also:
-
DEFAULT_CONTEXT_PATH
- See Also:
-
DEFAULT_SESSION_TIMEOUT
public static final int DEFAULT_SESSION_TIMEOUT- See Also:
-
DEFAULT_SESSION_COOKIE_NAME
- See Also:
-
DEFAULT_MAX_FORM_CONTENT_SIZE
public static final int DEFAULT_MAX_FORM_CONTENT_SIZE- See Also:
-
DEFAULT_MAX_FORM_PARAMETERS
public static final int DEFAULT_MAX_FORM_PARAMETERS- See Also:
-
-
Constructor Details
-
SiteRunner
public SiteRunner()Instantiates a new site runner, whose properties have the system properties as their parent.- Since:
- 1.11.0
-
SiteRunner
Instantiates a new site runner that will set up its site with the properties that you provide.They're used as they are, without the system properties being added as a parent.
- Parameters:
properties- the properties of the site- Since:
- 1.11.0
-
-
Method Details
-
scheme
Configures the scheme of the origin that the site is reached at, which can be a custom scheme that only your application uses.- Parameters:
scheme- the scheme (defaults tohttp)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
serverName
Configures the host name of the origin that the site is reached at.- Parameters:
serverName- the host name (defaults tolocalhost)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
serverPort
Configures the port of the origin that the site is reached at.- Parameters:
serverPort- the port, or-1to leave it out of the URLs (defaults to-1)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
contextPath
Configures the context path that the site is reached at. The paths that are handled have to start with it.- Parameters:
contextPath- the context path (defaults to none)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
getContextPath
Retrieves the context path that the site is reached at.- Returns:
- the context path, which is empty when there's none
- Since:
- 1.11.0
- See Also:
-
getServerRootUrl
Retrieves the root URL of the origin that the site is reached at,myapp://appfor instance.- Returns:
- the root URL, without the context path
- Since:
- 1.11.0
-
staticResourceBase
Configures the directory with the static files of the site. They're served for theGETandHEADrequests that no route handles and for the ones that end with a pass-through suffix.Like with
Server, there's one static resource base, so this replaces a base that was set before. TheMETA-INF/resourcesdirectory of web jars is always searched as well, even without a static resource base.- Parameters:
base- the path of the directory, ornullfor none- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
- See Also:
-
staticUberJarResourceBase
Configures the base directory in the classpath where the static files of the site will be looked up from, which in a native image means its embedded resources.Like with
Server, there's one static resource base, so this replaces a base that was set before. TheMETA-INF/resourcesdirectory of web jars is always searched as well.This can't be the root of the classpath, since your classes and your configuration would then be served too.
- Parameters:
base- the base directory in the classpath,webappfor instance- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
- See Also:
-
sessionTimeout
Configures after how many seconds a session that isn't used will expire.- Parameters:
seconds- the timeout, or zero or less for sessions that only end when they're invalidated (defaults to1800)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
sessionCookieName
Configures the name of the cookie that identifies the session.- Parameters:
name- the name of the cookie (defaults toJSESSIONID)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
sessionUrlParameters
Configures whether a session can also be identified by a;jsessionid=path parameter, whichResponse.encodeURL(java.lang.String)will then add when the session didn't come from a cookie.This is disabled by default, since such a link can put someone in another person's session.
- Parameters:
enabled-trueto identify sessions in URLs; orfalseotherwise (defaults tofalse)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
secure
Configures whether the origin is secure even though its scheme isn'thttps, which is the case for a custom scheme that can only be reached from within your application.The requests will then be secure, so that cookies that are marked as secure can be set and sent.
- Parameters:
secure-trueif the origin is secure; orfalseotherwise (defaults tofalse)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
maxFormContentSize
Configures the maximum size of a urlencoded form body. A request with a larger body will be answered with400, like with Jetty.- Parameters:
size- the maximum size in bytes, or a negative number for no limit (defaults to200000)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
maxFormParameters
Configures the maximum number of parameters in a urlencoded form body, where all the values of one name count as one parameter. A request with more parameters will be answered with400, like with Jetty.- Parameters:
parameters- the maximum number of parameters, or a negative number for no limit (defaults to1000)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
cookieJar
Configures the cookie jar that keeps the cookies of the responses and adds them to the requests, like a browser does.The jar then replaces the
Cookieheader of the requests that it applies to, so that only the cookies that the site set reach it.- Parameters:
jar- the cookie jar, ornullwhen your application keeps the cookies itself (defaults to none)- Returns:
- the instance of the site runner that's being configured
- Since:
- 1.11.0
-
properties
Retrieves the hierarchical properties that the site is set up with.- Returns:
- the properties of the site
- Since:
- 1.11.0
-
start
Sets up and deploys a site, after which it will handle requests.Errors while the site is set up are handled like in a deployed site: the requests will get the error page, or the error is thrown when pretty engine exceptions are disabled.
When you set a file upload path of your own, the uploads that an earlier run of your application left there are removed, since they're otherwise only deleted when the JVM exits.
- Parameters:
site- the site to run- Returns:
- the instance of the site runner that's being started
- Throws:
IllegalArgumentException- when the site isnullIllegalStateException- when the runner was already started or stopped- Since:
- 1.11.0
-
getSite
Retrieves the site that's being run.- Returns:
- the site; or
nullif the runner hasn't been started yet - Since:
- 1.11.0
-
stop
public void stop()Shuts the site down, closes the detached event streams that are still open and forgets the sessions. Calling this method more than once doesn't have any additional effect.Schedulers and datasources belong to the whole process, so they aren't stopped here. When your application ends, you can stop them with
Scheduler.stopAllActiveSchedulers()andDatasource.closeAllActiveDatasources().Closing an event stream waits for the event that's being written to its listener. This means that you shouldn't stop the runner from a thread that your listener is waiting for, since neither of them would be able to continue.
- Since:
- 1.11.0
-
close
public void close()Stops this site runner, which makes it possible to use it inside a try-with-resources block.- Specified by:
closein interfaceAutoCloseable- Since:
- 1.11.0
- See Also:
-
isServingAfterStop
protected boolean isServingAfterStop()Indicates whether requests are still handled after this runner was stopped and its site was shut down. This is what out-of-container testing has always done. The event streams and the sessions are then kept as well.This returns
falseby default.- Returns:
trueif requests are still handled after a stop; orfalseotherwise- Since:
- 1.11.0
-
isReusingRequests
protected boolean isReusingRequests()Indicates whether a request can be handled more than once, which out-of-container tests have always been able to do.This returns
falseby default.- Returns:
trueif a request can be handled again; orfalseotherwise- Since:
- 1.11.0
-
isKeepingDetachedStreamsOpen
protected boolean isKeepingDetachedStreamsOpen()Indicates whether a detached event stream stays open when there's no listener for the response, so that out-of-container tests can look at the events that are sent afterwards.This returns
falseby default, since there's otherwise nothing that could receive those events.- Returns:
trueif detached event streams stay open; orfalseotherwise- Since:
- 1.11.0
-
isValidatingCookies
protected boolean isValidatingCookies()Indicates whether the cookies that a site sets are checked for characters that can't be sent, like with Jetty. Out-of-container tests have always been able to set any value.This returns
trueby default.- Returns:
trueif cookies are checked; orfalseotherwise- Since:
- 1.11.0
-
isServingStaticResources
protected boolean isServingStaticResources()Indicates whether static files are served for the requests that no route handles. Out-of-container tests have never served them.This returns
trueby default.- Returns:
trueif static files are served; orfalseotherwise- Since:
- 1.11.0
-
handle
Handles aGETrequest.- Parameters:
url- the path with its raw query string, or a complete URL of the origin of this runner- Returns:
- the response
- Throws:
IllegalArgumentException- when the URL isnullIllegalStateException- when the runner isn't running- Since:
- 1.11.0
- See Also:
-
handle
Handles a request and returns its response once it's complete.The exceptions that the site doesn't handle itself are thrown, like a deployed site leaves them to the servlet container. A detached event stream is closed as soon as its element returns, since its later events could only reach a listener.
- Parameters:
url- the path with its raw query string, or a complete URL of the origin of this runnerrequest- the request, which can only be handled once- Returns:
- the response
- Throws:
IllegalArgumentException- when an argument isnullIllegalStateException- when the runner isn't running or the request was already handled- Since:
- 1.11.0
- See Also:
-
handle
Handles a request and gives its response to a listener while it's being written.This method returns once the element is done, while the response of a detached event stream continues after that. The failures of the site go to
SiteResponseListener.failed(java.lang.Throwable), and so do the requests that arrive after the runner was stopped. This method only throws for a mistake in how it's called, and the listener then isn't called at all.- Parameters:
url- the path with its raw query string, or a complete URL of the origin of this runnerrequest- the request, which can only be handled oncelistener- the listener that receives the response- Returns:
- the response, for its status and its headers
- Throws:
IllegalArgumentException- when an argument isnullIllegalStateException- when the runner wasn't started or the request was already handled- Since:
- 1.11.0
-
createSessionCookie
Creates the cookie that identifies a new session. Extending classes can override this to change its attributes.- Parameters:
request- the request that created the sessionid- the identifier of the session- Returns:
- the session cookie
- Since:
- 1.11.0
-