Bootstrap Code

Hook in the Bootstrap Process

GWTP aims to make the initial configuration of new projects as simple as possible. However, you may need to execute some code in a context usually handled by GWTP. There are a couple options available that should cover most needs.

1. Bootstrapper: Use a Bootstrapper if you need to execute code after GWTP and GIN are initialized, but before the default place is shown.

2. Pre-Bootstrapper: Use a Pre-Bootstrapper if you need to execute code before GWTP is initialized.

3. GIN module registration: You can register GIN modules directly in your .gwt.xml file. A common use case is to split your application into independent modules.

4. Ginjector Extensions: Register Ginjector extensions if you need to generate code that uses the Ginjector, which is itself generated by GWTP.

5. Custom Entry Point: If none of the preceding options fit your needs, you can use your own Entry Point the old fashioned way.

Bootstrapper {bootstrapper}

A Bootstrapper is executed code after GWTP and GIN are initialized, but before the default place is shown. You can only execute one Bootstrapper in your application. The Bootstrapper is also responsible for revealing the first place. If you forget to reveal a place in your Bootstrapper, your app will not open at all.. Since the Bootstrapper is loaded after GIN's initialization, you can use dependency injection.

A common use case for Bootstrappers is to check if a user is already logged in. If he is, the home page is displayed and if he is not, the login page is displayed.

To create a Bootstrapper, create a new class and implement Bootstrapper:

public class MyBootstrapper implements Bootstrapper {
    private final PlaceManager placeManager;
    private final SecurityDelegate securityDelegate;

    @Inject
    public MyBootstrapper(
            SecurityDelegate securityDelegate,
            PlaceManager placeManager) {
        this.securityDelegate = securityDelegate;
        this.placeManager = placeManager;
    }

    @Override
    public void onBootstrap() {
        securityDelegate.initialize();

        if(securityDelegate.isUserLoggedIn()) {
            placeManager.revealCurrentPlace();
        } else {
            placeManager.revealPlace(new PlaceRequest.Builder()
                    .nameToken(NameTokens.LOGIN)
                    .build());
        }
    }
}

Once you have a custom Bootstrapper, you need to register it in in your GWT module:

<set-configuration-property name="gwtp.bootstrapper"
        value="com.mydomain.myproject.client.MyBootstrapper"/>

Pre-Bootstrapper {pre-bootstrapper}

A Pre-Bootstrapper allows you to hook into GWTP's bootstrapping process right before anything is initialized. This is particularly useful if you need something done before GWTP starts up. It is very rarely necessary to use a Pre-Bootstrapper, as such the use of a Bootstrapper is advised. It is not possible to use GIN to inject code in a Pre-Bootstrapper. There are cases where it is not enough like when setting up an UncaughtExceptionHandler for gwt-log.

To create a Pre-Bootstrapper, create a new class and implement PreBootstrapper:

public class MyPreBootstrapper implements PreBootstrapper {
    @Override
    public void onPreBootstrap() {
        GWT.setUncaughtExceptionHandler(new UncaughtExceptionHandler() {
            @Override
            public void onUncaughtException(Throwable e) {
                Window.alert("There was a problem loading your application");
            }
        });
    }
}

Once you have a custom Pre-Bootstrapper, you need to register it in in your GWT module:

<set-configuration-property name="gwtp.prebootstrapper"
        value="com.mydomain.myproject.client.MyPreBootstrapper"/>

GIN module registration {gin-modules}

You can register GIN modules directly in your .gwt.xml file. A common use case is to split your application into independent modules. You then have one or many application using all or a subset of the available modules.

Gin Modules are registered in your GWT module by adding the following line:

<extend-configuration-property name="gin.ginjector.modules"
        value="com.mydomain.myproject.client.MyModule"/>

Ginjector Extensions {ginjector-extensions}

Ginjector extensions are useful if you need to add custom code to the Ginjector generated by GWTP. One of the very rare use-cases is when you write code-generators and their output needs access to code registered through GIN.

Ginjector Extensions should be interfaces and the methods should return a valid type. See GIN's documentation for more details. Once it is created, register it in your GWT module like so:

<extend-configuration-property name="gin.ginjector.extensions"
        value="com.mydomain.myproject.client.MyGinjectorExtension"/>

Custom Entry Point {custom-entrypoint}

If none of the previous options fit your needs, you can use your own Entry Point the old fashioned way. If you need your own Entry Point, please raise an issue on GitHub: we will gladly see what can be improved in GWTP's bootstrap process to cover your use-case.

In your GWT module, you need to inherit MVP (as opposed to MvpWithEntryPoint) and specify your own Entry Point:

<inherits name='com.gwtplatform.mvp.Mvp'/>
<entry-point class='tld.domain.project.client.MyApplicationEntryPoint'/>

Then, create your custom EntryPoint:

public class MyEntryPoint implements EntryPoint {
    private static final ApplicationController CONTROLLER =
            GWT.create(ApplicationController.class);

    @Override
    public void onModuleLoad() {
        controller.init();
    }
}

Note: The ApplicationController is what manages GWTP's bootstrap. So even if you have a custom Entry Point, all other options explained in this guide are still usable.