Package spark

Class Spark

java.lang.Object
spark.Spark

public class Spark extends Object
The main building block of a Spark application is a set of routes. A route is made up of three simple pieces:
  • A verb (get, post, put, delete, head, trace, connect, options)
  • A path (/hello, /users/:name)
  • A callback (request, response)
Example: get("/hello", (request, response) -> { return "Hello World!"; }); The public methods and fields in this class should be statically imported for the semantic to make sense. Ie. one should use: 'post("/books")' without the prefix 'Spark.'
  • Field Details

    • redirect

      public static final Redirect redirect
      Statically import this for redirect utility functionality, see Redirect
    • staticFiles

      public static final Service.StaticFiles staticFiles
      Statically import this for static files utility functionality, see Service.StaticFiles
  • Constructor Details

    • Spark

      protected Spark()
  • Method Details

    • getInstance

      private static Service getInstance()
    • path

      public static void path(String path, RouteGroup routeGroup)
      Add a path-prefix to the routes declared in the routeGroup The path() method adds a path-fragment to a path-stack, adds routes from the routeGroup, then pops the path-fragment again. It's used for separating routes into groups, for example: path("/api/email", () -> { ....post("/add", EmailApi::addEmail); ....put("/change", EmailApi::changeEmail); ....etc }); Multiple path() calls can be nested.
      Parameters:
      path - the path to prefix routes with
      routeGroup - group of routes (can also contain path() calls)
    • get

      public static void get(String path, Route route)
      Map the route for HTTP GET requests
      Parameters:
      path - the path
      route - The route
    • post

      public static void post(String path, Route route)
      Map the route for HTTP POST requests
      Parameters:
      path - the path
      route - The route
    • put

      public static void put(String path, Route route)
      Map the route for HTTP PUT requests
      Parameters:
      path - the path
      route - The route
    • patch

      public static void patch(String path, Route route)
      Map the route for HTTP PATCH requests
      Parameters:
      path - the path
      route - The route
    • delete

      public static void delete(String path, Route route)
      Map the route for HTTP DELETE requests
      Parameters:
      path - the path
      route - The route
    • head

      public static void head(String path, Route route)
      Map the route for HTTP HEAD requests
      Parameters:
      path - the path
      route - The route
    • trace

      public static void trace(String path, Route route)
      Map the route for HTTP TRACE requests
      Parameters:
      path - the path
      route - The route
    • connect

      public static void connect(String path, Route route)
      Map the route for HTTP CONNECT requests
      Parameters:
      path - the path
      route - The route
    • options

      public static void options(String path, Route route)
      Map the route for HTTP OPTIONS requests
      Parameters:
      path - the path
      route - The route
    • before

      public static void before(String path, Filter filter)
      Maps a filter to be executed before any matching routes
      Parameters:
      path - the path
      filter - The filter
    • before

      public static void before(String path, Filter... filters)
      Maps an array of filters to be executed before any matching routes
      Parameters:
      path - the path
      filters - the filters
    • after

      public static void after(String path, Filter filter)
      Maps a filter to be executed after any matching routes
      Parameters:
      path - the path
      filter - The filter
    • after

      public static void after(String path, Filter... filters)
      Maps an array of filters to be executed after any matching routes
      Parameters:
      path - the path
      filters - The filters
    • get

      public static void get(String path, String acceptType, Route route)
      Map the route for HTTP GET requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • post

      public static void post(String path, String acceptType, Route route)
      Map the route for HTTP POST requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • put

      public static void put(String path, String acceptType, Route route)
      Map the route for HTTP PUT requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • patch

      public static void patch(String path, String acceptType, Route route)
      Map the route for HTTP PATCH requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • delete

      public static void delete(String path, String acceptType, Route route)
      Map the route for HTTP DELETE requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • head

      public static void head(String path, String acceptType, Route route)
      Map the route for HTTP HEAD requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • trace

      public static void trace(String path, String acceptType, Route route)
      Map the route for HTTP TRACE requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • connect

      public static void connect(String path, String acceptType, Route route)
      Map the route for HTTP CONNECT requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • options

      public static void options(String path, String acceptType, Route route)
      Map the route for HTTP OPTIONS requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
    • before

      public static void before(Filter... filters)
      Maps one or many filters to be executed before any matching routes
      Parameters:
      filters - The filters
    • after

      public static void after(Filter... filters)
      Maps one or many filters to be executed after any matching routes
      Parameters:
      filters - The filters
    • before

      public static void before(String path, String acceptType, Filter... filters)
      Maps one or many filters to be executed before any matching routes
      Parameters:
      path - the path
      acceptType - the accept type
      filters - The filters
    • after

      public static void after(String path, String acceptType, Filter... filters)
      Maps one or many filters to be executed after any matching routes
      Parameters:
      path - the path
      acceptType - the accept type
      filters - The filters
    • afterAfter

      public static void afterAfter(String path, Filter filter)
      Execute after route even if the route throws exception
      Parameters:
      path - the path
      filter - the filter
    • afterAfter

      public static void afterAfter(Filter filter)
      Execute after any matching route even if the route throws exception
      Parameters:
      filter - the filter
    • get

      public static void get(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP GET requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • get

      public static void get(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP GET requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • post

      public static void post(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP POST requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • post

      public static void post(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP POST requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • put

      public static void put(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP PUT requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • put

      public static void put(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP PUT requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • delete

      public static void delete(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP DELETE requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • delete

      public static void delete(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP DELETE requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • patch

      public static void patch(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP PATCH requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • patch

      public static void patch(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP PATCH requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • head

      public static void head(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP HEAD requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • head

      public static void head(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP HEAD requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • trace

      public static void trace(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP TRACE requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • trace

      public static void trace(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP TRACE requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • connect

      public static void connect(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP CONNECT requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • connect

      public static void connect(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP CONNECT requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • options

      public static void options(String path, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP OPTIONS requests
      Parameters:
      path - the path
      route - The route
      engine - the template engine
    • options

      public static void options(String path, String acceptType, TemplateViewRoute route, TemplateEngine engine)
      Map the route for HTTP OPTIONS requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      engine - the template engine
    • get

      public static void get(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP GET requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • get

      public static void get(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP GET requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • post

      public static void post(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP POST requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • post

      public static void post(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP POST requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • put

      public static void put(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP PUT requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • put

      public static void put(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP PUT requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • delete

      public static void delete(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP DELETE requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • delete

      public static void delete(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP DELETE requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • head

      public static void head(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP HEAD requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • head

      public static void head(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP HEAD requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • connect

      public static void connect(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP CONNECT requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • connect

      public static void connect(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP CONNECT requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • trace

      public static void trace(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP TRACE requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • trace

      public static void trace(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP TRACE requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • options

      public static void options(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP OPTIONS requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • options

      public static void options(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP OPTIONS requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • patch

      public static void patch(String path, Route route, ResponseTransformer transformer)
      Map the route for HTTP PATCH requests
      Parameters:
      path - the path
      route - The route
      transformer - the response transformer
    • patch

      public static void patch(String path, String acceptType, Route route, ResponseTransformer transformer)
      Map the route for HTTP PATCH requests
      Parameters:
      path - the path
      acceptType - the accept type
      route - The route
      transformer - the response transformer
    • unmap

      public static boolean unmap(String path)
      Unmaps a particular route from the collection of those that have been previously routed. Search for previously established routes using the given path and unmaps any matches that are found.
      Parameters:
      path - the route path
      Returns:
      true if this is a matching route which has been previously routed
      Throws:
      IllegalArgumentException - if path is null or blank
    • unmap

      public static boolean unmap(String path, String httpMethod)
      Unmaps a particular route from the collection of those that have been previously routed. Search for previously established routes using the given path and HTTP method, unmaps any matches that are found.
      Parameters:
      path - the route path
      httpMethod - the http method
      Returns:
      true if this is a matching route that has been previously routed
      Throws:
      IllegalArgumentException - if path is null or blank or if httpMethod is null, blank, or an invalid HTTP method
    • exception

      public static <T extends Exception> void exception(Class<T> exceptionClass, ExceptionHandler<? super T> handler)
      Maps an exception handler to be executed when an exception occurs during routing
      Parameters:
      exceptionClass - the exception class
      handler - The handler
    • halt

      public static HaltException halt()
      Immediately stops a request within a filter or route NOTE: When using this don't catch exceptions of type HaltException, or if catched, re-throw otherwise halt will not work
    • halt

      public static HaltException halt(int status)
      Immediately stops a request within a filter or route with specified status code NOTE: When using this don't catch exceptions of type HaltException, or if catched, re-throw otherwise halt will not work
      Parameters:
      status - the status code
    • halt

      public static HaltException halt(String body)
      Immediately stops a request within a filter or route with specified body content NOTE: When using this don't catch exceptions of type HaltException, or if catched, re-throw otherwise halt will not work
      Parameters:
      body - The body content
    • halt

      public static HaltException halt(int status, String body)
      Immediately stops a request within a filter or route with specified status code and body content NOTE: When using this don't catch exceptions of type HaltException, or if catched, re-throw otherwise halt will not work
      Parameters:
      status - The status code
      body - The body content
    • setIpAddress

      public static void setIpAddress(String ipAddress)
      Deprecated.
      replaced by ipAddress(String)
      Set the IP address that Spark should listen on. If not called the default address is '0.0.0.0'. This has to be called before any route mapping is done.
      Parameters:
      ipAddress - The ipAddress
    • ipAddress

      public static void ipAddress(String ipAddress)
      Set the IP address that Spark should listen on. If not called the default address is '0.0.0.0'. This has to be called before any route mapping is done.
      Parameters:
      ipAddress - The ipAddress
    • defaultResponseTransformer

      public static void defaultResponseTransformer(ResponseTransformer transformer)
      Set the default response transformer. All requests not using a custom transformer will use this one
      Parameters:
      transformer -
    • setPort

      public static void setPort(int port)
      Deprecated.
      replaced by port(int)
      Set the port that Spark should listen on. If not called the default port is 4567. This has to be called before any route mapping is done. If provided port = 0 then the an arbitrary available port will be used.
      Parameters:
      port - The port number
    • port

      public static void port(int port)
      Set the port that Spark should listen on. If not called the default port is 4567. This has to be called before any route mapping is done. If provided port = 0 then the an arbitrary available port will be used.
      Parameters:
      port - The port number
    • port

      public static int port()
      Retrieves the port that Spark is listening on.
      Returns:
      The port Spark server is listening on.
      Throws:
      IllegalStateException - when the server is not started
    • setSecure

      public static void setSecure(String keystoreFile, String keystorePassword, String truststoreFile, String truststorePassword)
      Set the connection to be secure, using the specified keystore and truststore. This has to be called before any route mapping is done. You have to supply a keystore file, truststore file is optional (keystore will be reused). This method is only relevant when using embedded Jetty servers. It should not be used if you are using Servlets, where you will need to secure the connection in the servlet container
      Parameters:
      keystoreFile - The keystore file location as string
      keystorePassword - the password for the keystore
      truststoreFile - the truststore file location as string, leave null to reuse keystore
      truststorePassword - the trust store password
    • secure

      public static void secure(String keystoreFile, String keystorePassword, String truststoreFile, String truststorePassword)
      Set the connection to be secure, using the specified keystore and truststore. This has to be called before any route mapping is done. You have to supply a keystore file, truststore file is optional (keystore will be reused). This method is only relevant when using embedded Jetty servers. It should not be used if you are using Servlets, where you will need to secure the connection in the servlet container
      Parameters:
      keystoreFile - The keystore file location as string
      keystorePassword - the password for the keystore
      truststoreFile - the truststore file location as string, leave null to reuse keystore
      truststorePassword - the trust store password
    • secure

      public static void secure(String keystoreFile, String keystorePassword, String certAlias, String truststoreFile, String truststorePassword)
      Set the connection to be secure, using the specified keystore and truststore. This has to be called before any route mapping is done. You have to supply a keystore file, truststore file is optional (keystore will be reused). This method is only relevant when using embedded Jetty servers. It should not be used if you are using Servlets, where you will need to secure the connection in the servlet container
      Parameters:
      keystoreFile - The keystore file location as string
      keystorePassword - the password for the keystore
      certAlias - the default certificate Alias
      truststoreFile - the truststore file location as string, leave null to reuse keystore
      truststorePassword - the trust store password
    • initExceptionHandler

      public static void initExceptionHandler(Consumer<Exception> initExceptionHandler)
      Overrides default exception handler during initialization phase
      Parameters:
      initExceptionHandler - The custom init exception handler
    • secure

      public static void secure(String keystoreFile, String keystorePassword, String truststoreFile, String truststorePassword, boolean needsClientCert)
      Set the connection to be secure, using the specified keystore and truststore. This has to be called before any route mapping is done. You have to supply a keystore file, truststore file is optional (keystore will be reused). This method is only relevant when using embedded Jetty servers. It should not be used if you are using Servlets, where you will need to secure the connection in the servlet container
      Parameters:
      keystoreFile - The keystore file location as string
      keystorePassword - the password for the keystore
      truststoreFile - the truststore file location as string, leave null to reuse keystore
      truststorePassword - the trust store password
      needsClientCert - Whether to require client certificate to be supplied in request
    • secure

      public static void secure(String keystoreFile, String keystorePassword, String certAlias, String truststoreFile, String truststorePassword, boolean needsClientCert)
      Set the connection to be secure, using the specified keystore and truststore. This has to be called before any route mapping is done. You have to supply a keystore file, truststore file is optional (keystore will be reused). This method is only relevant when using embedded Jetty servers. It should not be used if you are using Servlets, where you will need to secure the connection in the servlet container
      Parameters:
      keystoreFile - The keystore file location as string
      keystorePassword - the password for the keystore
      certAlias - the default certificate Alias
      truststoreFile - the truststore file location as string, leave null to reuse keystore
      truststorePassword - the trust store password
      needsClientCert - Whether to require client certificate to be supplied in request
    • threadPool

      public static void threadPool(int maxThreads)
      Configures the embedded web server's thread pool.
      Parameters:
      maxThreads - max nbr of threads.
    • threadPool

      public static void threadPool(int maxThreads, int minThreads, int idleTimeoutMillis)
      Configures the embedded web server's thread pool.
      Parameters:
      maxThreads - max nbr of threads.
      minThreads - min nbr of threads.
      idleTimeoutMillis - thread idle timeout (ms).
    • staticFileLocation

      public static void staticFileLocation(String folder)
      Sets the folder in classpath serving static files. Observe: this method must be called before all other methods. - Note: contemplate changing tonew static files paradigm Service.StaticFiles
      Parameters:
      folder - the folder in classpath.
    • externalStaticFileLocation

      public static void externalStaticFileLocation(String externalFolder)
      Sets the external folder serving static files. Observe: this method must be called before all other methods. - Note: contemplate use of new static files paradigm Service.StaticFiles
      Parameters:
      externalFolder - the external folder serving static files.
    • awaitInitialization

      public static void awaitInitialization()
      Waits for the spark server to be initialized. If it's already initialized will return immediately
    • stop

      public static void stop()
      Stops the Spark server and clears all routes
    • awaitStop

      public static void awaitStop()
      Waits for the Spark server to be stopped. If it's already stopped, will return immediately.
    • webSocket

      public static void webSocket(String path, Class<?> handler)
      Maps the given path to the given WebSocket handler.

      This is currently only available in the embedded server mode.

      Parameters:
      path - the WebSocket path.
      handler - the handler class that will manage the WebSocket connection to the given path.
    • webSocket

      public static void webSocket(String path, Object handler)
    • webSocketIdleTimeoutMillis

      public static void webSocketIdleTimeoutMillis(int timeoutMillis)
      Sets the max idle timeout in milliseconds for WebSocket connections.
      Parameters:
      timeoutMillis - The max idle timeout in milliseconds.
    • notFound

      public static void notFound(String page)
      Maps 404 Not Found errors to the provided custom page
    • internalServerError

      public static void internalServerError(String page)
      Maps 500 internal server errors to the provided custom page
    • notFound

      public static void notFound(Route route)
      Maps 404 Not Found errors to the provided route.
    • internalServerError

      public static void internalServerError(Route route)
      Maps 500 internal server errors to the provided route.
    • init

      public static void init()
      Initializes the Spark server. SHOULD just be used when using the Websockets functionality.
    • modelAndView

      public static ModelAndView modelAndView(Object model, String viewName)
      Constructs a ModelAndView with the provided model and view name
      Parameters:
      model - the model
      viewName - the view name
      Returns:
      the model and view
    • routes

      public static List<RouteMatch> routes()
      Returns:
      All routes available
    • activeThreadCount

      public static int activeThreadCount()
      Returns:
      The approximate number of currently active threads in the embedded Jetty server