Flash messages

A Flash message is a message that is displayed to the user only once. It is most of the time used to display a confirmation message to the user when a form is submitted and the page redirected.

A good practice on a website is indeed to redirect the user to a new page when a form has been POSTed and is valid : that way, even if the user refreshes the resulting page, the form won't be resubmitted. But this pattern leads to a question : how to display a confirmation message on the page the user is redirected to? Flash messages are the answer to this question.

(All the Forms & Validation demos use Flash messages to display a confirmation message when the Form is submitted and is valid... Try them!)

A Flash message is most of the time used to display a confirmation (success) message to the user, but it, in fact, supports three "levels" :

Success
Warning
Error

A Flash message can also have some variables associated with it (in the form of an JsonObject), and those variables can be used when the Flash message is retrieved.

You can specify a Flash message :

By using the .response().redirect(...) method in a Route Handler

public void myHandler(AppRequestContext context) {
    context.response().redirect("/some-url/",
                                FlashMessageLevel.SUCCESS,
                                "The form has been processed successfully.");
}

By throwing a RedirectException

public void myHandler(AppRequestContext context) {
    throw new RedirectException("/some-url/",
                                FlashMessageLevel.SUCCESS,
                                "The form has been processed successfully.");
}

Of course, it doesn't make sense to specify a Flash message when redirecting the user to an external website!

Flash messages, when retrieved, are automatically added as a global variable for the Templating Engine. It is, in fact, converted to an Alert message.

How are Flash messages actually implemented? If Spincast has validated that the user supports cookies, it uses one to store the "id" of the Flash message and to retrieve it on the page the user is redirected to. If cookies are disabled, or if their support has not been validated yet, the "id" of the Flash messageis added as a queryString parameter to the URL of the page the user is redirected to.

Alert messages

{% if alertDemoMsg is not empty | default(false) %}

✔ {{alertDemoMsg}}

{% endif %}

An Alert message is a message that has a Success, Warning or Error level and that is displayed to the user, usually at the top of the page or of a section. It aims to inform the user about the result of an action, for example.

There are multiple ways to display an Alert message on a website. The Spincast website uses Toastr.js when javascript is enabled , and a plain <div> when javascript is disabled ( Try it!)

An Alert message is simply some text and a level associated with it, both added as a templating variable. You can easily implement your own way to pass such messages to be displayed to the user, but Spincast suggests a convention and some utilities :

The Alert messages are provided to the Templating Engine as a variable associated with the "spincast.alerts" key.

There is a dedicated "addAlert(...)" method on the response() add-on to easily add one from a Route handler :

public void myHandler(AppRequestContext context) {
    context.response().addAlert(AlertLevel.ERROR, 
                                "Your submission is not valid!");
}

Note that Flash messages will be automatically converted to Alert messages when it's time to render a template! This means that as long as you add code to display Alert messages in your interface, Flash messages will also be displayed properly.

Using a SSL certificate (HTTPS)

It is recommended that you serve your application over HTTPS and not HTTP, which is not secure. To achieve that, you need to install a SSL certificate.

If you download the Quick Start application, you will find two files explaining the required procedure :

/varia/ssl_certificate_howto/self-signed.txt
Shows how to use a self-signed certificate, for development purpose.
/varia/ssl_certificate_howto/lets-encrypt.txt
Shows how to use a Let's Encrypt certificate. Let's Encrypt is a provider of free, but totally valid, SSL certificates. Instructions in this file will probably work for certificates obtained from other providers, but we haven't tested it yet.

Spincast Utilities

Spincast provides some generic utilities, accessible via the SpincastUtils interface :

void zipDirectory(File directoryToZip, File targetZipFile, boolean includeDirItself)
Zips a directory.
@param targetZipFile the target .zip file. If the parent directories don't exist, tries to create them.
@param If true, the directory itself will be included in the zip file, otherwise only its content will be.
void zipExtract(File zipFile, File targetDir)
Extracts a .zip file to the specified directory.
@param targetDir The target directory. If it doesn't exist, tried to create it (and its parents, if required).
String getMimeTypeFromMultipleSources(String responseContentTypeHeader, String resourcePath, String requestPath)
Gets the mime type using multiple sources of information.
@param contentTypeHeader an already existing Content-Type header on the response. Can be null.
@param resourcePath the path (absolute or relative) to the target resource. Can be null.
@param requestPath the path of the current request. Can be null.
@return the mime type or null if it can't be decided.
String getMimeTypeFromPath(String path)
Gets the mime type from a path, using its extension.
@return the mime type or null if it can't be decided.
String getMimeTypeFromExtension(String extension)
Gets the mime type from the extension.
@return the mime type or null if it can't be decided.
Locale getLocaleBestMatchFromAcceptLanguageHeader(String acceptLanguageHeader)
Gets the best Locale to use given a "Accept-Language" HTTP header.
@return the best Locale to use or null if the given header can't be parsed.
boolean isContentTypeToSkipGziping(String contentType)
Should the specified Content-Type be gzipped?
File getAppJarDirectory()
Returns the working directory: the directory in which the executable .jar is located.
@return the working directory or null if the application is running inside an IDE.
String getSpincastCurrentVersion()
Gets the current Spincast version.
String getCacheBusterCode()
The cache buster to use.
This should probably change each time the application is restarted or at least redeployed.

It should also be in such a format that it's possible to remove it from a given text.

This must be kept in sync with removeCacheBusterCode!
String removeCacheBusterCodes(String text)
Removes the cache buster code occurences from the given text.
Note that this won't simply remove the current cache busting code, it will remove any valid cache busting code... This is what we want since we don't want a client sending a request containing an old cache busting code to break!

This must be kept in sync with getCacheBusterCode!
String readClasspathFile(String path)

Reads a file on the classpath and returns it as a String.

Paths are always considered from the root at the classpath. You can start the path with a "/" or not, it makes no difference.

Uses UTF-8 by default.

@return the content of the file or null if not found.

@MainArgs

The init(...) method of the Bootstrapper allows you to bind the arguments received in your main(...) method. For example :


public static void main(String[] args) {

    Spincast.configure()
            .module(new AppModule())
            .init(args);
    //....
}

By doing so, those arguments will be available for injection, using the @MainArgs annotation :

public class AppConfig extends SpincastConfig implements AppConfig {

    private final String[] mainArgs;

    @Inject
    public AppConfig(@MainArgs String[] mainArgs) {
        this.mainArgs = mainArgs;
    }

    protected String[] getMainArgs() {
        return this.mainArgs;
    }

    @Override
    public int getHttpServerPort() {

        int port = super.getHttpServerPort();
        if(getMainArgs().length > 0) {
            port = Integer.parseInt(getMainArgs()[0]);
        }
        return port;
    }
}

Using an `init()` method

This is more about standard Guice development than about Spincast, but we feel it's a useful thing to know.

Guice doesn't provide support for a @PostConstruct annotation out of the box. And since it is often seen as a bad practice to do too much work directly in a constructor, what we want is an init() method to be called once the object it fully constructed, and do the initialization work there.

The trick is that Guice calls any @Inject annotated methods once the object is created, so let's use this to our advantage :

public class UserService implements UserService {

    private final SpincastConfig spincastConfig;

    @Inject
    public UserService(SpincastConfig spincastConfig) {
        this.spincastConfig = spincastConfig;
    }

    @Inject
    protected void init() {
        doSomeValidation();
        doSomeInitialization();
    }

    //...
}

Explanation :

5-8 : The constructor's job is only to receive the dependencies.
10-14 : An init() method is also annotated with @Inject. This method will be called once the object is fully constructed. This is a good place to do some initialization work!

What we recommend is constructor injection + one (and only one) @Inject annotated method. The problem with multiple @Inject annotated methods (other than constructors) is that it's hard to know in which order they will be called.

Finally, if the init() method must be called as soon as the application starts, make sure you bind the object using asEagerSingleton()!