Package rife.engine

Class SiteRunner

java.lang.Object
rife.engine.SiteRunner
All Implemented Interfaces:
AutoCloseable

public class SiteRunner extends Object implements AutoCloseable
Runs a site inside your own application, in the same process, without a servlet container and without a socket.

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 Details

  • Constructor Details

    • SiteRunner

      public SiteRunner()
      Instantiates a new site runner, whose properties have the system properties as their parent.
      Since:
      1.11.0
    • SiteRunner

      public SiteRunner(HierarchicalProperties properties)
      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

      public SiteRunner scheme(String 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 to http)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • serverName

      public SiteRunner serverName(String serverName)
      Configures the host name of the origin that the site is reached at.
      Parameters:
      serverName - the host name (defaults to localhost)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • serverPort

      public SiteRunner serverPort(int serverPort)
      Configures the port of the origin that the site is reached at.
      Parameters:
      serverPort - the port, or -1 to 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

      public SiteRunner contextPath(String 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

      public String 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

      public String getServerRootUrl()
      Retrieves the root URL of the origin that the site is reached at, myapp://app for instance.
      Returns:
      the root URL, without the context path
      Since:
      1.11.0
    • staticResourceBase

      public SiteRunner staticResourceBase(String base)
      Configures the directory with the static files of the site. They're served for the GET and HEAD requests 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. The META-INF/resources directory of web jars is always searched as well, even without a static resource base.

      Parameters:
      base - the path of the directory, or null for none
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
      See Also:
    • staticUberJarResourceBase

      public SiteRunner staticUberJarResourceBase(String base)
      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. The META-INF/resources directory 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, webapp for instance
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
      See Also:
    • sessionTimeout

      public SiteRunner sessionTimeout(int seconds)
      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 to 1800)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • sessionCookieName

      public SiteRunner sessionCookieName(String name)
      Configures the name of the cookie that identifies the session.
      Parameters:
      name - the name of the cookie (defaults to JSESSIONID)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • sessionUrlParameters

      public SiteRunner sessionUrlParameters(boolean enabled)
      Configures whether a session can also be identified by a ;jsessionid= path parameter, which Response.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 - true to identify sessions in URLs; or false otherwise (defaults to false)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • secure

      public SiteRunner secure(boolean secure)
      Configures whether the origin is secure even though its scheme isn't https, 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 - true if the origin is secure; or false otherwise (defaults to false)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • maxFormContentSize

      public SiteRunner maxFormContentSize(int size)
      Configures the maximum size of a urlencoded form body. A request with a larger body will be answered with 400, like with Jetty.
      Parameters:
      size - the maximum size in bytes, or a negative number for no limit (defaults to 200000)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • maxFormParameters

      public SiteRunner 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. A request with more parameters will be answered with 400, like with Jetty.
      Parameters:
      parameters - the maximum number of parameters, or a negative number for no limit (defaults to 1000)
      Returns:
      the instance of the site runner that's being configured
      Since:
      1.11.0
    • cookieJar

      public SiteRunner cookieJar(SiteCookieJar jar)
      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 Cookie header of the requests that it applies to, so that only the cookies that the site set reach it.

      Parameters:
      jar - the cookie jar, or null when 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

      public HierarchicalProperties properties()
      Retrieves the hierarchical properties that the site is set up with.
      Returns:
      the properties of the site
      Since:
      1.11.0
    • start

      public SiteRunner start(Site site)
      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 is null
      IllegalStateException - when the runner was already started or stopped
      Since:
      1.11.0
    • getSite

      public Site getSite()
      Retrieves the site that's being run.
      Returns:
      the site; or

      null if 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() and Datasource.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:
      close in interface AutoCloseable
      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 false by default.

      Returns:
      true if requests are still handled after a stop; or

      false otherwise

      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 false by default.

      Returns:
      true if a request can be handled again; or

      false otherwise

      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 false by default, since there's otherwise nothing that could receive those events.

      Returns:
      true if detached event streams stay open; or

      false otherwise

      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 true by default.

      Returns:
      true if cookies are checked; or

      false otherwise

      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 true by default.

      Returns:
      true if static files are served; or

      false otherwise

      Since:
      1.11.0
    • handle

      public SiteResponse handle(String url)
      Handles a GET request.
      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 is null
      IllegalStateException - when the runner isn't running
      Since:
      1.11.0
      See Also:
    • handle

      public SiteResponse handle(String url, SiteRequest request)
      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 runner
      request - the request, which can only be handled once
      Returns:
      the response
      Throws:
      IllegalArgumentException - when an argument is null
      IllegalStateException - when the runner isn't running or the request was already handled
      Since:
      1.11.0
      See Also:
    • handle

      public SiteResponse handle(String url, SiteRequest request, SiteResponseListener listener)
      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 runner
      request - the request, which can only be handled once
      listener - the listener that receives the response
      Returns:
      the response, for its status and its headers
      Throws:
      IllegalArgumentException - when an argument is null
      IllegalStateException - when the runner wasn't started or the request was already handled
      Since:
      1.11.0
    • createSessionCookie

      protected Cookie createSessionCookie(SiteRequest request, String id)
      Creates the cookie that identifies a new session. Extending classes can override this to change its attributes.
      Parameters:
      request - the request that created the session
      id - the identifier of the session
      Returns:
      the session cookie
      Since:
      1.11.0