Service root

Service root

• Global service root

By default domino-rest assumes that the rest points are deployed to the same host and port of the running application, so if the application is running on localhost at port 8080 then all services will be mapped to :

http://localhost:8080/service/{path to service}

we can change the default service root globally for all services using the DominoRestConfig class :

DominoRestConfig
   .getInstance()
   .setDefaultServiceRoot("http://127.0.0.1:9090/");

after changing the service root all service will be mapped to the new service root .e.g: http://127.0.0.1:9090/{path to service}

• Service root for a single service

We can change the service root for any service while keeping other services mapped to the default service root using the @ServiceFactory annotation by setting the serviceRoot attribute

@RequestFactory(serviceRoot = "http://localhost:7070/library/")
public interface MoviesService {

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

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

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

with this we can make the movies service for example map to port 7070 while keep other services map to default port 8080

• Dynamic service root mapping

Instead of fixed service mapping for each service, or using one global service mapping for all service domino-rest allows mapping each service to a different root based on some matching conditions. for example we want all services that has a path starts with movies to map to http://localhost:7070/library/ while all services with paths starts with books map to http://localhost:9090 and so on. this is also very useful when the service roots are not fixed and could be defined as system properties or coming from some sort of configuration.

in order to define a dynamic service root we use the DominoRestConfig class

DominoRestConfig.getInstance()
    .addDynamicServiceRoot(DynamicServiceRoot
            .pathMatcher(path -> path.startsWith("movies"))
            .serviceRoot(() -> "http://localhost:7070/library/")
    )
    .addDynamicServiceRoot(DynamicServiceRoot
            .pathMatcher(path -> path.startsWith("books"))
            .serviceRoot(() -> "http://localhost:9090")
    );

Any service that isn't matched with of the defined matchers will be mapped to the default service root.

We can also use dynamic service roots to remove the host and port mapping from the service definition while keeping using a custom service root for that interface, in this case we use the @Path annotation on service level :

for example instead of defining the movies service like this :

@RequestFactory(serviceRoot = "http://localhost:7070/")
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);
}

We can define it like this

@RequestFactory
@Path("library/")
public interface MoviesService {

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

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

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

then we define a service root like this :

DominoRestConfig.getInstance()
    .addDynamicServiceRoot(DynamicServiceRoot
            .pathMatcher(path -> path.startsWith("library"))
            .serviceRoot(() -> "http://localhost:7070/library/")
    )

notice now how we dont have the host and port hard-coded in the service definition, and how we have a shorter path mapping in the service methods.

this will map for example the getMovieByname method to http://localhost:7070/library/movies/hulk.