{#========================================== Docs : "Request Context" ==========================================#}

The Request Context

The Request Context is the object associated with the current request that Spincast passes to your matching Route Handlers. Its main purpose is to allow you to access information about the request, and to build the response to send.

Those functionalities are provided by simple methods, or by add-ons. What we call an "add-on" is an intermediate class containing a set of methods made available through the Request Context parameter. Here's an example of using the routing() add-on :

{% verbatim %}

public void myHandler(DefaultRequestContext context) {

    if(context.routing().isNotFoundRoute()) {
        //...
    }
}
{% endverbatim %}

This routing() add-on is available to any Route Handler, via its Request Context parameter, and provides a set of utility methods.

Here are some add-ons and some standalone methods available by default on a Request Context object : {% verbatim %}

public void myHandler(DefaultRequestContext context) {

    // Accesses the request information
    String name = context.request().getPathParam("name");

    // Sets the response
    context.response().sendPlainText("Hello world");

    // Gets information about the routing process and the current route
    boolean isNotFoundRoute = context.routing().isNotFoundRoute();

    // Gets/Sets request-scoped variables
    String someVariable = context.variables().getAsString("someVariable");

    // Direct access to the Json manager
    JsonObject jsonObj = context.json().create();

    // Direct access to the XML manager
    JsonObject jsonObj2 = context.xml().fromXml("<someObj></someObj>");

    // Direct access the Guice context
    SpincastUtils spincastUtils = context.guice().getInstance(SpincastUtils.class);

    // Direct access to the Templating Engine
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("name", "Stromgol");
    context.templating().evaluate("Hello {{name}}", params);
    
    // Gets the best Locale to use for the current request
    Locale localeToUse = context.getLocaleToUse();
    
    // Sends cache headers
    context.cacheHeaders().cache(3600);
    
    // ...
}
{% endverbatim %}

Again, the main job of the Request Context is to allow the Route Handlers to deal with the request and the response. But it's also an extensible object on which various functionalities can be added to help the Route Handlers do their job! Take the "templating()" add-on, for example:

{% verbatim %}

public void myRouteHandler(DefaultRequestContext context) {

    Map<String, Object> params = new HashMap<String, Object>();
    params.put("name", "Stromgol");
    String content = context.templating().evaluate("Hi {{name}}!", params);

    // Do something with the evaluated content...
}
{% endverbatim %}

The templating() add-on does not directly manipulate the request or the response. But it still provides a useful set of methods for the Route Handlers.

If you have experience with Guice, or with dependency injection in general, you may be thinking that we could simply inject a TemplatingEngine instance in the controller and access it that way :

{% verbatim %}

public class AppController {

    private final TemplatingEngine templatingEngine;

    @Inject
    public AppController(TemplatingEngine templatingEngine) {
        this.templatingEngine = templatingEngine;
    }

    protected TemplatingEngine getTemplatingEngine() {
        return this.templatingEngine;
    }

    public void myRouteHandler(DefaultRequestContext context) {

        Map<String, Object> params = new HashMap<String, Object>();
        params.put("name", "Stromgol");
        String content = getTemplatingEngine().evaluate("Hi {{name}}!", params);

        // Do something with the evaluated content...
    }
}
{% endverbatim %}

The two versions indeed lead to the exact same result. But, for functionalities that are often used inside Route Handlers, or for functionalities that should be request scoped, extending the Request Context can be very useful.

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 object? For example : 

public void myHandler(ICustomRequestContext context) {

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

There is some boilerplate code involved to get such custom Request Context type but, when it's in place, it's pretty easy to tweak and extend. In fact, we highly recommend that you use a custom Request Context as soon as possible in your application. That way, you will be able to easily add add-ons when you need them.

If you use the Quick Start as a start for your application, a custom Request Context type is already provided. But if you start from scratch, an upcoming section will show you how to extend the default Request Context type, by yourself.

{#========================================== Section "Request Context / default add-ons" ==========================================#}

The default add-ons

There are add-ons which are always available on a Request Context object, in any Spincast application. Let's have a quick look at them :

{#========================================== Section "Request Context / Extending the Request Context type" ==========================================#}

Extending the Request Context

Extending the Request Context is probably to most advanced thing to learn about Spincast. Once in place, a custom Request Context is quite easy to adjust and extend, but the required code to start may be somewhat challenging. This is why we recommend that you start your application with the Quick Start! This application already contains a custom Request Context type, so you don't have to write the bootstrapping code by yourself! But if you start from scratch or if you are curious about how a custom Request Context type is possible, keep reading.

First, let's quickly repeat why we could want to extend the default Request Context type... There may be a "translate(...)" method on some class and we frequently use it by our various Route Handlers. Let's say this is a method helping translate a sentence from one language to another.

Instead of injecting the class where this method is defined each time we need to use it, wouldn't it be nice if we would have access to it directly from a Request Context object? For example: 

public class AppController {

    public void myRouteHandler(AppRequestContext context) {
        String translated = context.translate("Hello World!", Locale.ENGLISH, Locale.FRENCH);
        // ...
    }
}

Since this method doesn't exist on the default RequestContext interface, we'll have to create a custom type and add the method to it. In the previous snippet, this custom type is called "AppRequestContext".

Let's create this custom Request Context type... 

public interface AppRequestContext extends RequestContext<AppRequestContext> {

    public void translate(String sentense, Locale from, Locale to);

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

Note that we extend RequestContext, which is the base interface for any Request Context, but we parameterize it using our custom type. This is required because the base interface needs to know about it.

Then, the implementation: 

public class AppRequestContextDefault extends RequestContextBase<AppRequestContext>
                                      implements AppRequestContext {

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

    @Override
    public String translate(String sentense, Locale from, Locale to) {
        
        // More hardcoded than translated here!
        return "Salut, monde!";
    }
}

Explanation :

Last, but not the least, we need to tell Spincast about our new custom Request Context type! This is done by using the requestContextImplementationClass(...) of the Bootstrapper : 

public static void main(String[] args) {

    Spincast.configure()
            .module(new AppModule())
            .requestContextImplementationClass(AppRequestContextDefault.class)
            .mainArgs(args)
            .init();
    //....
}

Note that it is the implementation, "AppRequestContextDefault", that we have to specify, not the interface! This is to simplify your job : Spincast will automatically find the associated interface and will use it to parameterize the required components.

And that's it! From now on, when you are using a routing related component, which has to be parameterized with the Request Context type, you use your new custom type. For example: 


Router<AppRequestContext, DefaultWebsocketContext> router = getRouter();

router.GET("/").save(context -> {
    String translated = context.translate("Hello World!", Locale.ENGLISH, Locale.FRENCH);
    // do something with the translated sentence...
});

Or, using an inline Route Handler: 


Router<AppRequestContext, DefaultWebsocketContext> router = getRouter();

router.GET("/").save(new Handler<AppRequestContext>() {

    @Override
    public void handle(AppRequestContext context) {
        String translated = context.translate("Hello World!", Locale.ENGLISH, Locale.FRENCH);
        // do something with the translated sentence...
    }
});

(You may have motice that the parameterized version of the Router doesn't simply contain a Request Context type, but also a Websocket context type. This is because this type can also be extended.)

This may seem like a lot of boilerplate code! But it has to be done only one time and, once in place, it's easy to add new methods and add-ons to your Request Context objects! Also, using a unparameterized version of those generic components, it's way nicer. Let's see how to creat those unparameterized versions...

Using unparameterized components

You can do for your custom types what we already did for the default ones : to create an unparameterized version for each of them. For example, here's how the provided DefaultRouter is defined : 

public interface DefaultRouter extends Router<DefaultRequestContext, DefaultWebsocketContext> {
    // nothing required
}

This interface has no other goal than to "hide" the parameterization, to be more visually appealing, more easy to use... Thanks to this definition, you can inject DefaultRouter instead of Router<DefaultRequestContext, DefaultWebsocketContext>, which is arguably nicer. Both types are interchangeable.

You can do the exact same thing with your custom Route Context type : 

public interface AppRouter extends Router<AppRequestContext, DefaultWebsocketContext> {
    // nothing required
}

Now, you can inject AppRouter instead of Router<AppRequestContext, DefaultWebsocketContext> when you need an instance of your custom router! Here again, it's a matter of taste... Noth types are interchangeable.

For more details, have a look at the Quick Start application. It implements exactly this.