{#========================================== Spincast Routing plugin ==========================================#} {% extends "../../layout.html" %} {% block sectionClasses %}plugins plugins-spincast-routing{% endblock %} {% block meta_title %}Plugins - Spincast Routing{% endblock %} {% block meta_description %}Routing related components.{% endblock %} {% block scripts %} {% endblock %} {% block body %}
  1. Plugins
  2. Spincast Routing plugin

Spincast Routing plugin

Spincast Routing plugin

Overview

The Spincast Routing plugin contains the Spincast router, which is an implementation of the IRouter interface and one of the most important component of a Spincast application.

It also provides a set of classes to help creating routes and manipulating them.

Finally, it provides an IRoutingRequestContextAddon implementation, which is a request context add-on giving your route handlers access to information about the current routing process.

Installation

If you use the spincast-default artifact, this plugin is already installed so you have nothing more to do!

If you start from scratch using the spincast-core artifact, you can use the plugin by adding this Maven artifact to your project: 

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-routing</artifactId>
    <version>{{spincastCurrrentVersion}}</version>
</dependency>

You then install the plugin's Guice module, by passing it to the Guice.createInjector(...) method: 

Injector guice = Guice.createInjector(
        new SpincastCoreGuiceModule(args),
        new SpincastRoutingPluginGuiceModule(IAppRequestContext.class, IAppWebsocketContext.class)
        // other modules...
        );

... or by using the install(...) method from your custom Guice module: 

public class AppModule extends SpincastCoreGuiceModule {

    @Override
    protected void configure() {
        super.configure();
        install(new SpincastRoutingPluginGuiceModule(getRequestContextType(), 
                                                     getWebsocketContextType()));
        // other modules...
    }
    
    // ...
}

The IRouter interface

To learn in depth about the router object, the routing process and how to create routes, please read the Routing section of the documentation! Here we are only going to list the available methods.

Router Methods :

  • IRouteBuilder<R> GET(String path)
    Starts the creation of a GET route.
  • IRouteBuilder<R> POST(String path)
    Starts the creation of a POST route.
  • IRouteBuilder<R> PUT(String path)
    Starts the creation of a PUT route.
  • IRouteBuilder<R> DELETE(String path)
    Starts the creation of a DELETE route.
  • IRouteBuilder<R> OPTIONS(String path)
    Starts the creation of a OPTIONS route.
  • IRouteBuilder<R> TRACE(String path)
    Starts the creation of a TRACE route.
  • IRouteBuilder<R> HEAD(String path)
    Starts the creation of a HEAD route.
  • IRouteBuilder<R> PATCH(String path)
    Starts the creation of a PATCH route.
  • IRouteBuilder<R> ALL(String path)
    Starts the creation of a route matching any HTTP method.
  • IRouteBuilder<R> SOME(String path, Set<HttpMethod> httpMethods)
    Starts the creation of a route matching the specified
    HTTP methods.
  • IRouteBuilder<R> SOME(String path, HttpMethod... httpMethods)
    Starts the creation of a route matching the specified
    HTTP methods.
  • void before(IHandler<R> handler)
    Creates a "before" filter.
    Synonym of : ALL("/*{path}").pos(-1).save(handler) and with the Routing types as returned by
    ISpincastRouterConfig#getFilterDefaultRoutingTypes()
  • void before(String path, IHandler<R> handler)
    Creates a "before" filter.
    Synonym of : ALL(path).pos(-1).save(handler) and with the Routing types as returned by
    ISpincastRouterConfig#getFilterDefaultRoutingTypes()
  • void after(IHandler<R> handler)
    Creates an "after" filter.
    Synonym of : ALL("/*{path}").pos(1).save(handler) and with the Routing types as returned by
    ISpincastRouterConfig#getFilterDefaultRoutingTypes()
  • void after(String path, IHandler<R> handler)
    Creates an "after" filter.
    Synonym of : ALL(path).pos(1).save(handler) and with the Routing types as returned by
    ISpincastRouterConfig#getFilterDefaultRoutingTypes()
  • void beforeAndAfter(IHandler<R> handler)
    Creates a "before" and an "after" filters.
    Synonym of : ALL("/*{path}").pos(-1).save(handler) and ALL("/*{path}").pos(1).save(handler) and with the Routing types as returned by
    ISpincastRouterConfig#getFilterDefaultRoutingTypes()
  • void beforeAndAfter(String path, IHandler<R> handler)
    Creates a "before" and an "after" filters.
    Synonym of : ALL(path).pos(-1).save(handler) and ALL(path).pos(1).save(handler) and with the Routing types as returned by
    ISpincastRouterConfig#getFilterDefaultRoutingTypes()
  • void exception(IHandler<R> handler)
    Creates a route considered during an "Exception" routing process.
    Synonym of : ALL("/*{path}").exception().save(handler)
  • void exception(String path, IHandler<R> handler)
    Creates a route considered during an "Exception" routing process.
    Synonym of : ALL(path).exception().save(handler)
  • void notFound(IHandler<R> handler)
    Creates a route considered during an "Not Found" routing process.
    Synonym of : ALL("/*{path}").notFound().save(handler)
  • void notFound(String path, IHandler<R> handler)
    Creates a route considered during an "Not Found" routing process.
    Synonym of : ALL(path).notFound().save(handler)
  • IStaticResourceBuilder<R> file(String url)
    Start the creation of a static resource file.
    No "before" and "after" filters will be applied to those, since the request won't even reach the framework.
    @param url The url which will trigger the output of this static resource.
  • IStaticResourceBuilder<R> dir(String url)
    Start the creation of a static resource directory.
    No "before" and "after" filters will be applied to those, since the request won't even reach the framework.
    @param url The url which will trigger the output of this static resource.
  • void cors()
    Enables Cross-Origin Resource Sharing (Cors) on all matching requests (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R)
  • void cors(Set<String> allowedOrigins)
    Enables Cross-Origin Resource Sharing (Cors) on matching requests (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set)
  • void cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead)
    Enables Cross-Origin Resource Sharing (Cors) on matching requests (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set)
  • void cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent)
    Enables Cross-Origin Resource Sharing (Cors) on matching requests (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set)
  • void cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies)
    Enables Cross-Origin Resource Sharing (Cors) on matching requests (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean)
  • void cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies, Set<HttpMethod> allowedMethods)
    Enables Cross-Origin Resource Sharing (Cors) on matching requests (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean, Set)
  • void cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies, Set<HttpMethod> allowedMethods, int maxAgeInSeconds)
    Enables Cross-Origin Resource Sharing (Cors) on matching requests (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean, Set, int)
  • void cors(String path)
    Enables Cross-Origin Resource Sharing (Cors) on all requests matching the specified path (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R)
  • void cors(String path, Set<String> allowedOrigins)
    Enables Cross-Origin Resource Sharing (Cors) on requests matching the specified path (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set)
  • void cors(String path, Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead)
    Enables Cross-Origin Resource Sharing (Cors) on requests matching the specified path (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set)
  • void cors(String path, Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent)
    Enables Cross-Origin Resource Sharing (Cors) on requests matching the specified path (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set)
  • void cors(String path, Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies)
    Enables Cross-Origin Resource Sharing (Cors) on requests matching the specified path (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean)
  • void cors(String path, Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies, Set<HttpMethod> allowedMethods)
    Enables Cross-Origin Resource Sharing (Cors) on requests matching the specified path (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean, Set)
  • void cors(String path, Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies, Set<HttpMethod> allowedMethods, int maxAgeInSeconds)
    Enables Cross-Origin Resource Sharing (Cors) on requests matching the specified path (except the static resources, for whom cors has to be activated directly!)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean, Set, int)
  • void addStaticResource(IStaticResource<R> staticResource)
    Adds a static resource route, directly.
  • IRoutingResult<R> route(R requestContext)
    Find the route to use to handle the current request. The result contains all handlers to use.
    @return the routing result or null if no route matches.
  • IRoutingResult<R> route(R requestContext, RoutingType routingType)
    Find the route to use to handle the current request, given the specified routing type. The result contains all handlers to use.
    @return the routing result or null if no route matches.
  • void addRoute(IRoute<R> route)
    Adds a route, directly.
  • void removeAllRoutes()
    Removes all routes.
  • void removeRoute(String routeId)
    Removes a route using its routeId.
  • IRoute<R> getRoute(String routeId)
    Gets a route using its routeId.
  • List<IRoute<R>> getGlobalBeforeFiltersRoutes()
    Gets the global "before" filters.
  • List<IRoute<R>> getMainRoutes()
    Gets the main routes.
  • List<IRoute<R>> getGlobalAfterFiltersRoutes()
    Gets the global "after" filters.
  • void addRouteParamPatternAlias(String alias, String pattern)
    Adds an alias for a path pattern. For example, the path of a route may be "/${param1:<XXX>}" : here "XXX" is the alias for the regular expression pattern to use.
  • Map<String, String> getRouteParamPatternAliases()
    The path patterns' aliases.
    Themap is mutable.
  • void httpAuth(String pathPrefix, String realmName)
    Creates HTTP authentication protection (realm) for the specified path prefix.
  • IWebsocketRouteBuilder<R, W> websocket(String path)
    Starts the creation of a Websocket route.
  • void addWebsocketRoute(IWebsocketRoute<R, W> websocketRoute)
    Adds a Websocket route, directly.

The IRouteBuilder interface

When you start the creation of a route, for example using router.GET("/"), a IRouteBuilder instance is returned. You use this builder object to complete the creation of your route.

Methods:

  • IRouteBuilder<R> id(String id)
    An id that can be used to identify the route. Must be unique.
  • IRouteBuilder<R> path(String path)
    The path of the route.
  • IRouteBuilder<R> pos(int position)
    The position of the handler. If "0", the handler is considered as the *main* handler. Only one main handler per request is run (the first one found)! The main handler is usually where the body of the response is created. A route with a position less than "0" is considered as a "before" filter and will be run before the main handler. A route with a position greater than "0" is considered as an "after" filter and will be run after the main handler. All the matching before and after filters are run, from the lower position to the higher. If two filters have the same position, they will be run in order they have been added to the router. More than one position is allowed. If not specified, "0" is used.
  • IRouteBuilder<R> found()
    This route will be considered during a Found routing process.
  • IRouteBuilder<R> notFound()
    This route will be considered during a Not Found routing process.
  • IRouteBuilder<R> exception()
    This route will be considered during an Exception routing process.
  • IRouteBuilder<R> allRoutingTypes()
    This route will be considered for all routing types.
  • IRouteBuilder<R> before(IHandler<R> beforeFilter)
    Adds a "before" filter which will only be applied to this particular route. If more than one filter is added, they will be run in order they have been added.
  • IRouteBuilder<R> after(IHandler<R> afterFilter)
    Adds an "after" filter which will only be applied to this particular route. If more than one filter is added, they will be run in order they have been added.
  • IRouteBuilder<R> acceptAsString(String... acceptedContentTypes)
    Sets the accepted Content-Types. This route will only be considered for requests specifying those Content-Types as being accepted (using the Accept header).
  • IRouteBuilder<R> acceptAsString(Set<String> acceptedContentTypes)
    Sets the accepted Content-Types. This route will only be considered for requests specifying those Content-Types as being accepted (using the Accept header).
  • IRouteBuilder<R> accept(ContentTypeDefaults... acceptedContentTypes)
    Sets the accepted Content-Types. This route will only be considered for requests specifying those Content-Types as being accepted (using the Accept header).
  • IRouteBuilder<R> accept(Set<ContentTypeDefaults> acceptedContentTypes)
    Sets the accepted Content-Types. This route will only be considered for requests specifying those Content-Types as being accepted (using the Accept header).
  • IRouteBuilder<R> html()
    Adds application/html as an accepted Content-Type.
  • IRouteBuilder<R> json()
    Adds application/json as an accepted Content-Type.
  • IRouteBuilder<R> xml()
    Adds application/xml as an accepted Content-Type.
  • IRouteBuilder<R> GET()
    Addss GET as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> POST()
    Adds POST as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> PUT()
    Adds PUT as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> DELETE()
    Adds DELETE as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> OPTIONS()
    Adds OPTIONS as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> TRACE()
    Adds TRACE as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> HEAD()
    Adds HEAD as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> PATCH()
    Adds PATCH as a supported HTTP method. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. This one will simply be added.
  • IRouteBuilder<R> ALL()
    Adds all HTTP methods as being supported. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. By calling this method, all methods will now be suported.
  • IRouteBuilder<R> SOME(Set<HttpMethod> httpMethods)
    Adds the specified HTTP methods as being supported. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. Those new ones will simply be added.
  • IRouteBuilder<R> SOME(HttpMethod... httpMethods)
    Adds the specified HTTP methods as being supported. If you started the creation of the route from an IRouter object, you already specified some supported HTTP methods. Those new ones will simply be added.
  • void save(IHandler<R> mainHandler)
    Creates the route and saves it to the router. If the creation of the route was not started using an IRouter object, an exception will be thrown.
  • IRoute<R> create(IHandler<R> mainHandler)
    Creates and returns the route without adding it to the router. NOTE : use save(...) instead to save the route to the router at the end of the build process!
  • IRouteBuilder<R> noCache()
    Automatically adds "no-cache" headers to the response.
  • IRouteBuilder<R> cache()
    Adds cache headers.

    Uses the default cache configurations, provided by org.spincast.core.config.ISpincastConfig ISpincastConfig

  • IRouteBuilder<R> cache(int seconds)
    Adds public cache headers.
    @param seconds The number of seconds the resource associated with this route should be cached.
  • IRouteBuilder<R> cache(int seconds, boolean isPrivate)
    Adds cache headers.
    @param seconds The number of seconds the resource associated with this route should be cached.
    @param isPrivate should the cache be private? (help)
  • IRouteBuilder<R> cache(int seconds, boolean isPrivate, Integer secondsCdn)
    Adds cache headers.
    @param seconds The number of seconds the resource associated with this route should be cached.
    @param isPrivate should the cache be private? (help)
    @param secondsCdn The number of seconds the resource associated with this route should be cached by a CDN/proxy. If null, it won't be used.

The IStaticResourceBuilder interface

When you start the creation of a static resource, for example using router.dir("/public"), a IStaticResourceBuilder instance is returned. You use this builder object to complete the creation of the resource route.

Methods:

  • IStaticResourceBuilder<R> url(String url)
    The URL pointing to the resource.
  • IStaticResourceBuilder<R> classpath(String path)
    The path to the resource, on the classpath.
  • IStaticResourceBuilder<R> pathAbsolute(String absolutePath)
    The absolute path to the resource, on the file system.
    @param absolutePath the absolute path to the resource. If this is a file and not a directory, remember that it will be served as a static resource, so its extension is important for the correct Content-Type to be sent!
  • IStaticResourceBuilder<R> pathRelative(String relativePath)
    The path to the resource, on the file system, relative to the temp Spincast directory, as returned by ISpincastConfig::getSpincastTempDir()
    @param relativePath the relative path to the resource. If this is a file and not a directory, remember that it will be served as a static resource, so its extension is important for the correct Content-Type to be sent!
  • IStaticResourceBuilder<R> cors()
    Enables Cross-Origin Resource Sharing (Cors)
    @see org.spincast.core.filters.ISpincastFilters#cors(R)
  • IStaticResourceBuilder<R> cors(Set<String> allowedOrigins)
    Enables Cross-Origin Resource Sharing (Cors)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set)
  • IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead)
    Enables Cross-Origin Resource Sharing (Cors)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set)
  • IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent)
    Enables Cross-Origin Resource Sharing (Cors)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean)
  • IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies)
    Enables Cross-Origin Resource Sharing (Cors)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean)
  • IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies, int maxAgeInSeconds)
    Enables Cross-Origin Resource Sharing (Cors)
    @see org.spincast.core.filters.ISpincastFilters#cors(R, Set, Set, Set, boolean)
  • IStaticResourceBuilder<R> cache(int seconds)
    Adds public cache headers.
    @param seconds The number of seconds the resource associated with this route should be cached.
  • IStaticResourceBuilder<R> cache(int seconds, boolean isPrivate)
    Adds cache headers.
    @param seconds The number of seconds the resource associated with this route should be cached.
    @param isPrivate should the cache be private? (help)
  • IStaticResourceBuilder<R> cache(int seconds, boolean isPrivate, Integer secondsCdn)
    Adds cache headers.
    @param seconds The number of seconds the resource associated with this route should be cached.
    @param isPrivate should the cache be private? (help)
    @param secondsCdn The number of seconds the resource associated with this route should be cached by a CDN/proxy. If null, it won't be used.
  • void save()
    Saves the static resource route to the router. If the creation of the resource was not started using an IRouter object, an exception will be thrown.
  • void save(IHandler<R> generator)
    Saves the static resource route. If the creation of the resource was not started using an IRouter object, an exception will be thrown.
    @param generator If the resource is not found, the specified generator will be used to generate it and the result will be saved.
  • IStaticResource<R> create()
    Creates and returns the static resource without adding it to the router. NOTE : use save(...) instead to save the static resource to the router at the end of the build process!

The IWebsocketRouteBuilder interface

When you start the creation of a Websocket route, using router.websocket("/somePath"), a IWebsocketRouteBuilder instance is returned. You use this builder object to complete the creation of your Websocket route.

Methods:

  • IWebsocketRouteBuilder<R, W> path(String path)
    The path that trigger the beginning of that
    HTTP to Websocket connection.
  • IWebsocketRouteBuilder<R, W> id(String id)
    The Websocket route id.
  • IWebsocketRouteBuilder<R, W> before(IHandler<R> beforeFilter)
    Adds a before filter. Those will be run before the
    Websocket connection handshake is started.


    Note that there are no "after" filters because once a
    Websocket connection is established, the HTTP one is no more.

  • void save(IWebsocketController<R, W> websocketController)
    Saves the Websocket route on the router.
  • IWebsocketRoute<R, W> create(IWebsocketController<R, W> websocketController)
    Creates and returns the Websocket route without adding it to the router.
    NOTE : use save(...) instead to save the route to the router at the end of the build process!

Configurations

You can bind a ISpincastRouterConfig implementation to tweak the default configurations used by the components this plugin provides. By default, the SpincastRouterConfigDefault class is used as the implementation.

  • Set<RoutingType> getFilterDefaultRoutingTypes()
    The routing types to apply a filter to when none is explicitly specified.
    Defaults to all route types.
  • int getCorsFilterPosition()
    The default position for a cors "before" filter. Must be < 0 !
    Defaults to -100.

The request context add-on

The plugin provides a IRoutingRequestContextAddon request context add-on. This add-on is mounted as .routing() on the default Spincast request context.

Quick example :

public void myHandler(IAppRequestContext context) {

    // Get information about the matches returned by 
    // the router.
    IRoutingResult<IAppRequestContext> routingResult = context.routing().getRoutingResult();
}

Add-on methods :

  • boolean isNotFoundRoute()
    Are we currently on a "Not Found" routing type?
  • boolean isExceptionRoute()
    Are we currently on an "Exception" routing type?
  • boolean isForwarded()
    Is the current route forwarded?
  • IRouteHandlerMatch<R> getCurrentRouteHandlerMatch()
    The current route handler being run (may be a filter) and its associated information.
  • IRoutingResult<R> getRoutingResult()
    The routing result for the current request, as returned by the router.
  • int getPosition()
    The current route handler position.
    If < 0 : is a "before" handler.
    If == 0 : is the main handler.
    If > 0 : is an "after" handler.

{% endblock %}