templates.docs.overview.html Maven / Gradle / Ivy
Show all versions of spincast-website Show documentation
{#==========================================
Docs : "overview"
==========================================#}
Spincast overview
{#==========================================
Section "overview / introduction"
==========================================#}
Introduction
Spincast is based on the shoulders of a giant, Guice
(from Google).
Other Java web frameworks may claim they support Guice, and maybe even have a
section of their documentation dedicated to the topic. Spincast is one of those that is totally built on
Guice, from the ground up! If you already know Guice, Spincast will be really easy to grasp for you.
Guice is not only (in our opinion) the best dependency injection library of the Java ecosystem, but also a
fantastic base to build modular applications. Everything is divided into modules which
are swappable and overridable. Each module can declare which dependencies it requires from other
modules. In fact, Guice is so flexible that you may even find ways of using Spincast we haven't think about!
If you know another dependency injection library, like Spring, it can also help but
you'll probably have to learn one of two new tricks!
Here's what using Spincast looks like at a very high level:
Users make requests to your web application. This application can
have an HTML interface, built using popular tools like
jQuery, React,
Ember, Angular, etc. That
HTML interface can be generated by Spincast (using a built-in templating engine) or
can be a Single Page Application where Spincast is used as a bootstrapper and a
data provider (JSON or XML) for the SPA.
Spincast is also a good platform to build REST web services or microservices,
without any user interface, since it "talks" JSON and XML natively.
{#==========================================
Section "Overview / Architecture"
==========================================#}
Architecture
Spincast is composed of a core plugin and a set of default
plugins. The core plugin is responsible for validating that an implementation for all the
components required in a Spincast application has been bound by other plugins. The
default plugins provide such default implementations.
You use the Bootstrapper to initialize your application. This bootstrapper
will automatically bind the core plugin and the default plugins, but will also let
you install extra plugin and custom modules for the components specific to your application :
{#==========================================
Section "architecture / request handling"
==========================================#}
Request handling
Here's how a request made by a user is handled by Spincast :
First, the embedded HTTP Server receives a request from a user. This server consists
of a Server interface and an
implementation. The default implementation is provided by
the spincast-plugins-undertow
plugin which uses the Undertow HTTP/Websocket server.
If the request is for a Static Resource, the server serves it directly without even reaching the
framework. Note that it's also possible to generate the resource, using a standard route, so the request does
enter the framework. There is even a third option which is what we call
Dynamic Resources:
if a request is made for a request which currently doesn't exist, the server will pass the request to the framework, the
framework can then create the resource and return it... The following requests for the same resource will use
the generated resource and won't reach the framework anymore!
If the request is not for a static resource, the server passes it to the core
Spincast component : the Front Controller. The Front Controller is at the very center
of Spincast! This is one of the very few components that is actually bound by the core plugin
itself.
The job of the Front Controller is to:
-
Ask the
Router for the appropriate route to use when a request arrives.
-
Call the
Route Handlers of the matching route. A route can have many handlers :
they are Filters which are run before the Main Handler, the Main Handler
itself, and some Filters which are run after the Main Handler.
-
If the request is for a
WebSocket connection, the handling of the request
is made by a WebSocket Controller instead of a Route Handler.
Also, the result is not a simple response but a permanent and full duplex connection where each side
can send messages to the other side.
Have a look at the WebSockets section for more information!
-
If no matching route is returned by the
Router, the Front Controller
will use a Not Found route. The Not Found route can be a custom
one, or the default one provided by Spincast.
-
If any exception occures during any of those steps, the
Front Controller
will use an Exception route. The Exception route can be a custom
one, or the default one provided by Spincast.
The job of the Router is to determine the appropriate
route to use, given the URL of the request, its HTTP method, etc. It will also
extract the value of the dynamic path tokens, if any. For example, a route path could be
"/user/${userId}/tasks". If a "/user/42/tasks" request is made, the router will
extract "42" as the value of the userId parameter and make this available to the rest of the
framework.
Finally:
-
The
Route Handlers receive a Request Context (which represents the request),
and decide what to return as the response. This can be anything: Json, HTML,
XML or even bytes.
or:
-
A
WebSocket Controller receives the request for a WebSocket connection, allows or
denies it, and then receives and sends messages on that connection.
{#==========================================
The main components
==========================================#}
The main components
The main components are those without which a Spincast application can't even run.
Any class, any plugin, can assume those components are available, so they can
inject them and use them!
Those main components are all installed by the default plugins.
Have a look at those default plugins for a quick overview of the big blocks constituting Spincast!
Spincast is very modular and you can replace any plugin, even the default one. But, when you do this,
you are responsible for providing any required components this plugin was binding.
{#==========================================
Section "architecture / Transitive dependencies"
==========================================#}
Transitive dependencies
The spincast-core Maven artifact only has two direct dependencies which are external to Spincast:
-
Guice, which itself pulls some transitive dependencies,
such as "
Guava" and "jsr305".
-
SLF4J : The logging facade.
The versions used for those dependencies are defined in the spincast-parent
Maven artifact's pom.xml.
Spincast core also uses some Apache commons libraries,
but those are shaded, their classes have been relocated under Spincast's
org.spincast.shaded package, so they won't conflit with your own dependencies.
That said, each Plugin also adds its own dependencies! If you start with
the spincast-default Maven artifact, a bunch of transitive dependencies
will be included. If you need full control over the transitives dependencies added to
your application, start with the spincast-core Maven artifact and pick, one by one, the
plugins and implementations you want to use.