Dolphin Platform: A Sneak Peek of the controller API

Today I want to add the next sneak peek of the Dolphin Platform, a new open source project on that Michael Heinrich and I are currently working at Canoo. Yesterday I blogged about the [general concept of the platform]({{ site.baseurl }}{% post_url 2015-10-04-dolphin-platform-a-sneak-peek %} ). Today I want to show server side controllers can be defined by using the Dolphin Platform.

The Controller API

As already said the controller are defined on the server. If you already used JSF you might know this concept. But don’t be afraid, I won’t compare Dolphin Platform with JSF ;)

Each controller must be annotated with the @DolphinController annotation and therefore the most simple controller might look like this:

@DolphinController
public class MyController {
}

Even if this class don’t make that much sense we created a complete runnable Dolphin Platform server application here. Once this is deployed the underlying platform (currently JavaEE or Spring) will automatically find your container and manage its lifecycle. This is done by the architecture of Dolphin Platform that provides a public API and specific bootstrap implementations for JavaEE and Spring. As a developer you will always code against the public API and only need to add the needed bootrap module as a dependency to your server application.

This means that the shown controller will work in any Spring or JavaEE 7 environment.

Since the controllers managed by the container you automatically get all the benefits that comes with it. This means that you can use @Inject or @PostContruct annotations, for example:

@DolphinController
public class MyController {

  @Inject
  private PersistenceService myService;
  
  @PostConstruct
  public void init() {
    myService.loadData();
  }

}

Next to this Dolphin Platform provides addition features for the controller API. Any method that is annotated by @DolphinAction can be called from the client view to trigger some actions on user interaction, for example.

@DolphinController
public class MyController {

  @Inject
  private PersistenceService myService;
  
  @DolphinAction
  public void load() {
    myService.loadData();
  }
  
  @DolphinAction
  public void save() {
    myService.saveData();
  }

}

By doing so it’s very easy to handle the business logic that will be triggered by a user action. Since the methods are defined on the server you benefit of security and transaction support, for example.

Next to the actions a main concept of the Dolphin Platform is the presentation model (or view model). Each view-controller-pair can define it’s own model that can simply be injected in the controller by using the @DolphinModel annotation. We will see later how such a model can be defined. When injecting a model to the controller its lifecycle is bound to the lifecycle of the controller and will be automatically managed by the underlying platform.

@DolphinController
public class MyController {

  @Inject
  private PersistenceService myService;
  
  @DolphinModel
  private MyModel model;
  
  @DolphinAction
  public void refresh() {
    model.setData(myService.loadData());
  }
  
}

By doing so the model instance will automatically be created when a new controller instance will be created. If the controller will be destroyed by the container the model will be destroyed, too. In addition the model will automatically be synchronized between the server controller and the view on the client side. How the model can be accessed and handled on the client will part of a future post.

I think the biggest benefit in the shown concept is the perfect integration in a web container like it is provided by Spring or JavaEE. All your controller (and model) instances will be managed by the container and it’s no problem to inject a spring service in your controller, for example. By doing so you can use an API like Spring data and fill your view model directly with data from your persistence.

In the next preview I will show how a view model can be defined by using Dolphin Platform and how you can simply observe any view model on the server and client.