templates.plugins.spincast-routing.spincast-routing.html Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of spincast-website Show documentation
Show all versions of spincast-website Show documentation
Source code for the https://www.spincast.org website.
The newest version!
{#==========================================
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 %}
Plugins- 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.
-
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.
-
void cors()
Enables Cross-Origin Resource Sharing (Cors) on all
matching requests (except the static resources,
for whom cors has to be activated directly!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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!)
-
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.
-
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.
-
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.
-
IRouteBuilder<R> cache(int seconds, boolean isPrivate)
Adds cache headers.
-
IRouteBuilder<R> cache(int seconds, boolean isPrivate, Integer secondsCdn)
Adds cache headers.
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.
-
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()
-
IStaticResourceBuilder<R> cors()
Enables Cross-Origin Resource Sharing (Cors)
-
IStaticResourceBuilder<R> cors(Set<String> allowedOrigins)
Enables Cross-Origin Resource Sharing (Cors)
-
IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead)
Enables Cross-Origin Resource Sharing (Cors)
-
IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent)
Enables Cross-Origin Resource Sharing (Cors)
-
IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies)
Enables Cross-Origin Resource Sharing (Cors)
-
IStaticResourceBuilder<R> cors(Set<String> allowedOrigins, Set<String> extraHeadersAllowedToBeRead, Set<String> extraHeadersAllowedToBeSent, boolean allowCookies, int maxAgeInSeconds)
Enables Cross-Origin Resource Sharing (Cors)
-
IStaticResourceBuilder<R> cache(int seconds)
Adds public cache headers.
-
IStaticResourceBuilder<R> cache(int seconds, boolean isPrivate)
Adds cache headers.
-
IStaticResourceBuilder<R> cache(int seconds, boolean isPrivate, Integer secondsCdn)
Adds cache headers.
-
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.
-
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 %}
Spincast Routing 
Spincast Routing © 2015 - 2025 Weber Informatics LLC | Privacy Policy