Package spark

Class Service

java.lang.Object
spark.Service
public final class Service extends Object
Represents a Spark server "session". If a user wants multiple 'Sparks' in his application the method ignite() should be statically imported and used to create instances. The instance should typically be named so when prefixing the 'routing' methods the semantic makes sense. For example 'http' is a good variable name since when adding routes it would be: Service http = ignite(); ... http.get("/hello", (q, a) -> "Hello World");

  • Field Details

    • SPARK_DEFAULT_PORT

      public static final int SPARK_DEFAULT_PORT
      See Also:

    • DEFAULT_ACCEPT_TYPE

      protected static final String DEFAULT_ACCEPT_TYPE
      See Also:

    • initialized

      protected boolean initialized

    • port

      protected int port

    • ipAddress

      protected String ipAddress

    • sslStores

      protected SslStores sslStores

    • webSocketHandlers

      protected Map<String,WebSocketHandlerWrapper> webSocketHandlers

    • maxThreads

      protected int maxThreads

    • minThreads

      protected int minThreads

    • threadIdleTimeoutMillis

      protected int threadIdleTimeoutMillis

    • webSocketIdleTimeoutMillis

      protected Optional<Integer> webSocketIdleTimeoutMillis

    • server

      protected EmbeddedServer server

    • pathDeque

      protected Deque<String> pathDeque

    • routes

      protected Routes routes

    • redirect

      public final Redirect redirect

    • staticFiles

      public final Service.StaticFiles staticFiles

  • Method Details

    • ignite

      public static Service ignite()
      Creates a new Service (a Spark instance). This should be used instead of the static API if the user wants multiple services in one process.
      Returns:
      the newly created object

    • embeddedServerIdentifier

      public void embeddedServerIdentifier(Object obj)
      Set the identifier used to select the EmbeddedServer; null for the default.
      Parameters:
      obj - the identifier passed to EmbeddedServers.

    • embeddedServerIdentifier

      public Object embeddedServerIdentifier()
      Get the identifier used to select the EmbeddedServer; null for the default.
      Parameters:
      obj - the identifier passed to EmbeddedServers.

    • ipAddress

      public Service 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
      Returns:
      the object with IP address set

    • port

      public Service 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
      Returns:
      the object with port set

    • port

      public 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

    • secure

      public Service 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). By default, client certificates are not checked. 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
      Returns:
      the object with connection set to be secure

    • secure

      public Service 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). By default, client certificates are not checked. 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
      Returns:
      the object with connection set to be secure

    • secure

      public Service 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
      Returns:
      the object with connection set to be secure

    • secure

      public Service 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
      Returns:
      the object with connection set to be secure

    • threadPool

      public Service threadPool(int maxThreads)
      Configures the embedded web server's thread pool.
      Parameters:
      maxThreads - max nbr of threads.
      Returns:
      the object with the embedded web server's thread pool configured

    • threadPool

      public Service 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).
      Returns:
      the object with the embedded web server's thread pool configured

    • staticFileLocation

      public Service staticFileLocation(String folder)
      Sets the folder in classpath serving static files. Observe: this method must be called before all other methods.
      Parameters:
      folder - the folder in classpath.
      Returns:
      the object with folder set

    • externalStaticFileLocation

      public Service externalStaticFileLocation(String externalFolder)
      Sets the external folder serving static files. Observe: this method must be called before all other methods.
      Parameters:
      externalFolder - the external folder serving static files.
      Returns:
      the object with external folder set

    • unmap

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

    • webSocket

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

      This is currently only available in the embedded server mode.

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

    • webSocket

      public void webSocket(String path, Object handler)
      Maps the given path to the given WebSocket handler instance.

      This is currently only available in the embedded server mode.

      Parameters:
      path - the WebSocket path.
      handler - the handler instance that will manage the WebSocket connection to the given path.

    • webSocketIdleTimeoutMillis

      public Service webSocketIdleTimeoutMillis(int timeoutMillis)
      Sets the max idle timeout in milliseconds for WebSocket connections.
      Parameters:
      timeoutMillis - The max idle timeout in milliseconds.
      Returns:
      the object with max idle timeout set for WebSocket connections

    • notFound

      public void notFound(String page)
      Maps 404 errors to the provided custom page
      Parameters:
      page - the custom 404 error page.

    • internalServerError

      public void internalServerError(String page)
      Maps 500 internal server errors to the provided custom page
      Parameters:
      page - the custom 500 internal server error page.

    • notFound

      public void notFound(Route route)
      Maps 404 errors to the provided route.

    • internalServerError

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

    • awaitInitialization

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

    • stop

      public void stop()
      Stops the Spark server and clears all routes.

    • awaitStop

      public void awaitStop()
      Waits for the Spark server to stop. Warning: this method should not be called from a request handler.

    • path

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

    • getPaths

      public String getPaths()

    • routes

      public List<RouteMatch> routes()
      Returns:
      all routes information from this service

    • addRoute

      public void addRoute(HttpMethod httpMethod, RouteImpl route)
      Adds a route
      Parameters:
      httpMethod - the HTTP method
      route - the route implementation

    • addFilter

      public void addFilter(HttpMethod httpMethod, FilterImpl filter)
      Adds a filter
      Parameters:
      httpMethod - the HTTP method
      filter - the route implementation

    • addRoute

      @Deprecated public void addRoute(String httpMethod, RouteImpl route)
      Deprecated.

    • addFilter

      @Deprecated public void addFilter(String httpMethod, FilterImpl filter)
      Deprecated.

    • init

      public void init()

    • activeThreadCount

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

    • exception

      public <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 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
      Returns:
      HaltException object

    • halt

      public 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
      Returns:
      HaltException object with status code set

    • halt

      public 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
      Returns:
      HaltException object with body set

    • halt

      public 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
      Returns:
      HaltException object with status and body set

    • initExceptionHandler

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

    • get

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

    • post

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

    • put

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

    • patch

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

    • delete

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

    • head

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

    • trace

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

    • connect

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

    • options

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

    • before

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

    • after

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

    • get

      public 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 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 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 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 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 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 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 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 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 void before(Filter filter)
      Maps a filter to be executed before any matching routes
      Parameters:
      filter - The filter

    • after

      public void after(Filter filter)
      Maps a filter to be executed after any matching routes
      Parameters:
      filter - The filter

    • before

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

    • after

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

    • afterAfter

      public void afterAfter(Filter filter)
      Maps a filter to be executed after any matching routes even if the route throws any exception
      Parameters:
      filter - The filter

    • afterAfter

      public void afterAfter(String path, Filter filter)
      Maps a filter to be executed after any matching routes even if the route throws any exception
      Parameters:
      filter - The filter

    • get

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

    • defaultResponseTransformer

      public void defaultResponseTransformer(ResponseTransformer transformer)
      Sets default response transformer
      Parameters:
      transformer -