Quick start

Quick start

Adding domino-rest to your GWT project is quite simple, just follow these steps to get started with using domino-rest :

1. Add the maven dependency

• GWT 2.8.2 Snapshot

<!-- Lib dependency-->
<dependency>
  <groupId>org.dominokit</groupId>
  <artifactId>domino-rest-gwt</artifactId>
  <version>1.0-alpha-gwt2.8.2-SNAPSHOT</version>
</dependency>

<!-- Annotation processor dependency-->
<dependency>
    <groupId>org.dominokit</groupId>
    <artifactId>domino-rest-apt</artifactId>
    <version>1.0-alpha-gwt2.8.2-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

• GWT 2.9.0 release

<!-- Lib dependency-->
<dependency>
  <groupId>org.dominokit</groupId>
  <artifactId>domino-rest-client</artifactId>
  <version>1.0.0-RC3</version>
</dependency>

<!-- Annotation processor dependency-->
<dependency>
    <groupId>org.dominokit</groupId>
    <artifactId>domino-rest-processor</artifactId>
    <version>1.0.0-RC3</version>
    <scope>provided</scope>
</dependency>

• GWT 2.9.0 Development snapshot

<!-- Lib dependency-->
<dependency>
  <groupId>org.dominokit</groupId>
  <artifactId>domino-rest-client</artifactId>
  <version>HEAD-SNAPSHOT</version>
</dependency>

<!-- Annotation processor dependency-->
<dependency>
    <groupId>org.dominokit</groupId>
    <artifactId>domino-rest-processor</artifactId>
    <version>HEAD-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

to use the snapshot version you will need to add the snapshot repositories to your maven setting.xml or to your project pom repositories section.

<repository>
   <id>sonatype-snapshots-repo</id>
   <url>https://oss.sonatype.org/content/repositories/snapshots</url>
   <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
      <checksumPolicy>fail</checksumPolicy>
   </snapshots>
</repository>

2. Add the GWT inherits directive

• GWT 2.8.2

<inherits name="org.dominokit.domino.rest.GwtRest"/>

• GWT 2.9.0

<inherits name="org.dominokit.rest.Rest"/>

When migrating from GWT 2.8.2 version to GWT 2.9.0 version domino-rest imports that starts with import org.dominokit.domino.* now changed to be import org.dominokit.* the part .domino is removed.

3. In your application entry point initialize domino-rest context :

DominoRestConfig.initDefaults();

4. Write a pojo

A POJO used in the service definition as a response or request needs to be annotated with @JSONMapper in order to generate the JSON mappers for it, we will see later how we can customize this.

@JSONMapper
public class Movie {

    @PathParam("name")
    private String name;
    private int rating;
    private String bio;
    private String releaseDate;

    // setters and getters
}

5. Write the service definition

To define a rest service create an interface and annotate it with @RequestFactory which will trigger the annotation processor when we compile to generate the rest client. Add as many methods annotated using JaxRs annotations, and the processor will create a request class and a factory method to execute that method and call the server.

@RequestFactory
public interface MoviesService {

    @Path("library/movies/:movieName")
    @GET
    Movie getMovieByName(@PathParam("movieName") String movieName);

    @Path("library/movies")
    @GET
    List<Movie> listMovies();

    @Path("library/movies/:name")
    @PUT
    void updateMovie(@BeanParam @RequestBody Movie movie);
}

6. Use the generated client

The generated client class will be named with the service interface name + "Factory", get the instance and call the service method :

MoviesServiceFactory.INSTANCE
    .getMovieByName("hulk")
    .onSuccess(movie -> {
        //do something on success
    })
    .onFailed(failedResponse -> {
        //do something on error
    })
    .send();

MoviesServiceFactory.INSTANCE
    .listMovies()
    .onSuccess(movies -> {
        //do something on success
    })
    .onFailed(failedResponse -> {
        //do something on error
    })
    .send();
    
MoviesServiceFactory.INSTANCE
    .updateMovie(movie)
    .onSuccess(aVoid -> {
        //do something on success
    })
    .onFailed(failedResponse -> {
        //do something on error
    })
    .send();