2. Installing Spring Data REST

2. Installing Spring Data REST
Prev		Next

2.1 Introduction

Spring Data REST is itself a Spring MVC application and is designed in such a way that it should integrate with your existing Spring MVC applications with very little effort. An existing (or future) layer of services can run alongside Spring Data REST with only minor considerations.

To install Spring Data REST alongside your application, simply add the required dependencies, include the stock @Configuration class (or subclass it and perform any required manual configuration), and map some URLs to be managed by Spring Data REST.

2.2 Adding Spring Data REST to a Gradle project

To add Spring Data REST to a Gradle-based project, add the spring-data-rest-webmvc artifact to your compile-time dependencies:

dependencies {
  ... other project dependencies
  compile "org.springframework.data:spring-data-rest-webmvc:1.1.0.M1"
}

2.3 Adding Spring Data REST to a Maven project

To add Spring Data REST to a Maven-based project, add the spring-data-rest-webmvc artifact to your compile-time dependencies:

<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-rest-webmvc</artifactId>
  <version>1.1.0.M1</version>
</dependency>

2.4 Configuring Spring Data REST

To install Spring Data REST alongside your existing Spring MVC application, you need to include the appropriate MVC configuration. Spring Data REST configuration is defined in a class called RepositoryRestMvcConfiguration. You can either import this class into your existing configuration using an @Import annotation or you can subclass it and override any of the configureXXX methods to add your own configuration to that of Spring Data REST.

In the following example, we'll subclass the standard RepositoryRestMvcConfiguration and add some ResourceMapping configurations for the Person domain object to alter how the JSON will look and how the links to related entities will be handled.

@Configuration
public class MyWebConfiguration extends RepositoryRestMvcConfiguration {

  @Override protected void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
    config.addResourceMappingForDomainType(Person.class)
          .addResourceMappingFor("lastName")
          .setPath("surname"); // Change 'lastName' to 'surname' in the JSON
    config.addResourceMappingForDomainType(Person.class)
          .addResourceMappingFor("siblings")
          .setRel("siblings")
          .setPath("siblings"); // Pointless in this example,
                                // but shows how to change 'rel' and 'path' values.
  }

}

There are numerous methods on the RepositoryRestConfiguration object to allow you to configure various aspects of Spring Data REST. Please read the javadoc for that class to get detailed descriptions of the various settings you can control.

2.4.1 Adding custom converters

It may be necessary to add a custom converter to Spring Data REST. You might need to turn a query parameter into a complex object, for instance. In that case, you'll want to override the configureConversionService method and add your own converters. To convert a query parameter to a complex object, for instance, you would want to register a converter for String[] to MyPojo.

  @Bean public MyPojoConverter myPojoConverter() {
    return new MyPojoConverter();
  }

  @Override protected void configureConversionService(ConfigurableConversionService conversionService) {
    conversionService.addConverter(String[].class, myPojoConverter());
  }

2.5 Adding Spring Data REST to Spring MVC

Since Spring Data REST is simply a Spring MVC application, you only need to include the REST configuration into the configuration for the DispatcherServlet. If using a Servlet 3.0 WebApplicationInitializer (the preferred configuration for Spring Data REST applications), you would add your subclassed configuration from above into the configuration for the DispatcherServlet. The following configuration class is from the example project and includes datasource configuration for three different datastores and domain models, which will all be exported by Spring Data REST.

public class RestExporterWebInitializer implements WebApplicationInitializer {

  @Override public void onStartup(ServletContext servletContext) throws ServletException {
    AnnotationConfigWebApplicationContext rootCtx = new AnnotationConfigWebApplicationContext();
    rootCtx.register(
        JpaRepositoryConfig.class, // Include JPA entities, Repositories
        MongoDbRepositoryConfig.class, // Include MongoDB document entities, Repositories
        GemfireRepositoryConfig.class // Inlucde Gemfire entities, Repositories
    );
    servletContext.addListener(new ContextLoaderListener(rootCtx));

    AnnotationConfigWebApplicationContext webCtx = new AnnotationConfigWebApplicationContext();
    webCtx.register(MyWebConfiguration.class);

    DispatcherServlet dispatcherServlet = new DispatcherServlet(webCtx);
    ServletRegistration.Dynamic reg = servletContext.addServlet("rest-exporter", dispatcherServlet);
    reg.setLoadOnStartup(1);
    reg.addMapping("/*");
  }

}

The equivalent of the above in a standard web.xml will also work identically to this configuration if you are still in a servlet 2.5 environment.

When you deploy this application to your servlet container, you should be able to see what repositories are exported by accessing the root of the application. You can use curl or, more easily, the rest-shell:

$ rest-shell

 ___ ___  __ _____  __  _  _     _ _  __
| _ \ __/' _/_   _/' _/| || |   / / | \ \
| v / _|`._`. | | `._`.| >< |  / / /   > >
|_|_\___|___/ |_| |___/|_||_| |_/_/   /_/
1.2.1.RELEASE

Welcome to the REST shell. For assistance hit TAB or type "help".
http://localhost:8080:> list
rel         href
==========================================
people      http://localhost:8080/people
profile     http://localhost:8080/profile
customer    http://localhost:8080/customer
order       http://localhost:8080/order
product     http://localhost:8080/product

Prev		Next
1. Introduction	Home	3. Domain Object Representations