{#========================================== Index ==========================================#} {% extends "./layout.html" %} {% block sectionClasses %}index{% endblock %} {% block meta_title %}Java web framework{% endblock %} {% block meta_description %}Highly Flexible Java Web Framework Based On Guice{% endblock %} {% block body %}

Propulsion for your web backend

Spincast is an highly flexible and open source Java web framework, based on Guice.

{#========================================== Main content ==========================================#}
{#========================================== Spincast overview ==========================================#}

Spincast overview

Spincast is a Java framework to serve as a backend for Single Page Applications (SPA), to develop old-school HTML generated websites or even to be a REST web service / microservice platform, as it speaks Json and XML natively. It is made of a small core and a plugins ecosystem. It aims to be as flexible and enjoyable as possible, but not to be simple at all cost!

Simple things should be simple, complex things should be possible.

Alan Kay

Sane defaults are provided for pretty much all parts of the framework, but everything is overridable/configurable. For example, there are no private methods in the framework, the default method visibility is protected (learn more). Spincast is built from the ground up using the wonderful Guice and the modularity features this library provides. It uses an embedded HTTP server so it's easy to develop, test and deploy.

Configuration over convention!

Spincast is not the kind of microframeworks that quickly produces one-liner applications. There are no static methods, no magical conventions, no easy shortcuts. In our opinion, developers should always keep total control over what's going on, even if that requires a little bit more work from their part and some extra lines of code.

Learn more...

{#========================================== Hello World (quick version) ==========================================#}

Hello World! (quick and dirty version)

First, you add the latest version of the org.spincast:spincast-default Maven artifact to your pom.xml (or build.gradle) : 

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

Then you bootstrap everything using a main(...) method : 

public class App {

    public static void main(String[] args) {

        Injector guice = Guice.createInjector(new SpincastDefaultGuiceModule(args));

        IDefaultRouter router = guice.getInstance(IDefaultRouter.class);
        
        router.GET("/").save(context -> context.response().sendPlainText("Hello World!"));

        guice.getInstance(IServer.class).start();
    }
}

Explanation :
(Tip : try hovering/clicking the page numbers below!)

  • 3 : A good old Java's main(...) method! This is the entry point of a standard Spincast application.
  • 5 : The very first thing a Spincast application does is to create a Guice context. Here, we use the provided SpincastDefaultGuiceModule module. This module binds a default implementation for all the required components of a Spincast application.
  • 7 : We get the default router (IDefaultRouter) from Guice.
  • 9 : We add a GET route for the "/" index page, using a Java 8's lambdas syntax. This inline route handler sends a plain text "Hello World!" message to the user.
  • 11 : We get the HTTP server (IServer) from Guice and we start it!

Now, if you would point your browser to http://localhost:44419 (Spincast default port is 44419), you should see the "Hello World!" message.

Here's the exact same example but using Java 7, so without lambdas. We prefer this version for a first example because the types of the various components are more obvious!: 

public class App {

    public static void main(String[] args) {

        Injector guice = Guice.createInjector(new SpincastDefaultGuiceModule(args));

        IDefaultRouter router = guice.getInstance(IDefaultRouter.class);

        router.GET("/").save(new IDefaultHandler() {
            @Override
            public void handle(IDefaultRequestContext context) {
                context.response().sendPlainText("Hello World!");
            }
        });

        guice.getInstance(IServer.class).start();
    }
}

Explanation :

  • 9-14 : We can now clearly see that the save(...) method in fact takes a route handler as a parameter. In this simple example, the route handler is declared inline using the IDefaultHandler interface. We'll learn more about route handlers in the next example.

{#========================================== Hello World (more scalable version) ==========================================#}

Hello World! (more scalable version)

We're not big fans of those very short "Hello world!" examples because, in real life, you usually don't develop such basic applications. You want an architecture that is flexible and scalable! So, let's use a more flexible structure now.

In this second example we'll:

  • Make the App class itself being managed by Guice.
  • Use a custom Guice module.
  • Learn how to extend the request context type.

If you look carefully, in the previous example we used a lot of Default components ("IDefaultRouter" for example). Those Default components are useful to have a quick up and running Spincast application. But they hide the fact that they represent objects that are actually parameterized. In Spincast, most of the components related to the routing process are parameterized with the request context type. You can learn more about this topic in the The Request Context section of the documentation, but we'll introduce it briefly here.

A request context is the object Spincast passes to the matching route handlers when a request arrives. This object allows your handlers to access information about the current request (its body, headers, path parameters, etc.) and to build the response that is going to be sent back (its body, headers, http status, etc.). But there are also more generic utility methods on the request context, methods not directly related to the request or the response. Here's a quick example :

{% verbatim %}

public void myHandler(IDefaultRequestContext context) {

    Map<String, Object> params = new HashMap<String, Object>();
    params.put("name", "Stromgol");
    String result = context.templating().evaluate("Hello {{name}}", params);
    
    // Do something with the result...
}
{% endverbatim %}

Explanation :

  • 5 : The templating() "method" is not directly related to the request or the response. It's an add-on that provides utilities to the route handlers.

In our first "Hello World" example, the request context type was IDefaultRequestContext, which is the default. In Spincast, this default type can be extended, you can add extra functionalities to it! Those functionalities can be simple methods or full objects, called add-ons. Most of the time, those add-ons are provided by plugins.

But why would we want to extend the request context?

Imagine a plugin which job is to manage authentification and autorization. Wouldn't it be nice if this plugin could add some extra functionalities to the request context? For example : 

router.GET("/").save(new IDefaultHandler() {
    @Override
    public void handle(IDefaultRequestContext context) {

        if(context.auth().isAuthenticated()) {
            String username = context.auth().user().getUsername();
            // ...
        }
    }
});

This is what being able to extend the request context allows.

So in this new and improved "Hello world!" example, we're going to use a custom request context type: IAppRequestContext. We're going to add a simple method to it : translate(String sentence, Locale from, Locale to), which job will be to translate a sentence from one language to another. By adding this new method to our custom request context type, our route handlers will have easy access to it.

Note that, for this second example, we still have to include the org.spincast:spincast-default Maven artifact because, even if we'll use a custom request context type, we'll still be using all the other default components (the default HTTP server, for example).

Let's first have a look at what our new App class will be. We'll create the other required components after. 

public class App {

    public static void main(String[] args) {

        Injector guice = Guice.createInjector(new AppModule());

        App app = guice.getInstance(App.class);
        app.start();
    }

    private final IServer server;
    private final IRouter<IAppRequestContext> router;

    @Inject
    public App(IServer server, IRouter<IAppRequestContext> router) {
        this.server = server;
        this.router = router;
    }

    public void start() {

        this.router.GET("/").save(new IHandler<IAppRequestContext>() {

            @Override
            public void handle(IAppRequestContext context) {
                String translated = context.translate("Hello World!", 
                                                      Locale.ENGLISH, 
                                                      Locale.FRENCH);
                context.response().sendPlainText(translated);
            }
        });

        this.server.start();
    }
}

Explanation :

  • 1 : The App class is still the entry point of our application but, in this new example, it is also going to be part of the Guice context!
  • 5 : Instead of using the default SpincastDefaultGuiceModule Guice module provided by Spincast, we use a custom Guice module, AppModule (listed below).
  • 7-8 : When the Guice context is created, we get the App instance and we call its start() method. As you'll see, we'll bind the App class itself in our custom AppModule module, so Guice manages it!
  • 14-18 : Since the App instance is managed by Guice, all the required dependencies will be automatically injected in its constructor. Here, we inject the HTTP server (IServer) and a custom and parameterized router: IRouter<IAppRequestContext>. We'll see that because the router is parameterized with a custom request context type, "IAppRequestContext", our route handler will have access to a new translate(...) method...
  • 20 : The start() method called at line 8, once Guice context is created.
  • 22 : We add a GET route for the "/" index page. Here, we won't use Java 8 lambdas or method handles so you can clearly see the types involved. Since the router, IRouter<IAppRequestContext>, is parameterized with our custom request context type, the handler type, IHandler<IAppRequestContext>, will also be.
  • 25 : The handle(...) method receives an instance of our custom request context type, "IAppRequestContext".
  • 26-28 : We can now use our new translate(...) method, available directly on the request context object!
  • 33 : We start the server.

Now that we looked at the new App class, let's create our custom IAppRequestContext type in which the new translate(...) method will be defined : 

public interface IAppRequestContext extends IRequestContext<IAppRequestContext> {

    public String translate(String sentence, Locale from, Locale to);

    // Other custom methods and/or add-ons...
}

Explanation :

  • 1 : A custom request context interface must extend the IRequestContext base interface and parameterize it using its own type. To learn more about this, check the Extending the default request context type section of the documentation.
  • 3 : We declare our custom translate(...) method.

Then, let's add an implementation for this interface : 

public class AppRequestContext extends RequestContextBase<IAppRequestContext>
                               implements IAppRequestContext {

    @AssistedInject
    public AppRequestContext(@Assisted Object exchange,
                             RequestContextBaseDeps<IAppRequestContext> requestContextBaseDeps) {
        super(exchange, requestContextBaseDeps);
    }

    @Override
    public String translate(String sentence, Locale from, Locale to) {

        // Ok, it's more hardcoded than translated for now!
        return "Salut, monde!";
    }
}

Explanation :

  • 1-2 : Our implementation class extends the RequestContextBase class to keep all the functionalities of the default request context, but also implements our custom IAppRequestContext interface, where our new translate(...) method is declared.
  • 4-8 : The constructor is annotated with @AssistedInject because it will be used by a Guice assisted factory. Don't worry too much about this or about the parameters, they are simply required by the parent class's constructor.
  • 10-15 : A dummy implementation of our new method, translate(...).

Finally, we bind everything together by creating a custom Guice module, AppModule. This module is the one used by our App class to create the Guice context. 

public class AppModule extends SpincastDefaultGuiceModule {

    @Override
    protected void configure() {
        super.configure();
        bind(App.class).in(Scopes.SINGLETON);
    }

    @Override
    protected Class<? extends IRequestContext<?>> getRequestContextImplementationClass() {
        return AppRequestContext.class;
    }
    
}

Explanation :

  • 1 : Our custom module extends SpincastDefaultGuiceModule since we want to keep the default bindings and only tweak a few things.
  • 6 : In the overidden configure() method, we bind our App class itself! That way, Guice knows about it and is able to inject the dependencies it requires.
  • 9-12 : We override the getRequestContextImplementationClass() method to let Spincast know that it has to use our custom AppRequestContext request context type instead of the default one! Note that Spincast will automatically find the associated IAppRequestContext interface and will use it to parameterize the router and the other routing related components.

And that's it! If you start this application (using the main(...) method of the App class) and point your browser to http://localhost:44419, you'll see "Salut, monde!".

Extending the request context type may seem like a lot of code! But once in place, adding new functionalities is pretty easy. And you'll have a solid and flexible base to build your application.

That said, if it's too much, you can also start using Spincast with the provided default components and only switch to custom ones when you feel ready...

Note that if you use the Quick Start application as a start, the customization of the request context type has already been done for you.

{#========================================== Hello World (real life version) ==========================================#}

Hello World! (real life version)

Our second example was a good step forward. But in a real life application, your logic wouldn't all be inside a single App class! You would have controllers, services, respositories, etc.

Make sure you read the Bootstrapping your app section of the documentation for more ideas on how to structure a real life Spincast application.

{#========================================== Next steps ==========================================#}

Where to go from here?

If you haven't done so yet, try the Quick Start application. Not only it is a good way to learn how a Spincast application works, but it also makes a good starting point to build a real application. Open the project in your favorite IDE, add breakpoints and start debugging: this is probably the best way to really learn how Spincast works.

Finally, if you feel really adventurous, you could even Read The Freaking Manual!

{#========================================== Right sidebar ==========================================#} {# End right-sidebar #}
{# End row #}
{% endblock %}