Skip to content

Tag Archives: Spring

Creating Specification<> instances for Spring Data JPA with Spring MVC


One common requirement in web applications is to be able to filter a given set of data through request parameters. One way to do this is fetch everything from the server and filter it on the client. Me, i’m more of a server guy and i tend to do this inside a database.

Many projects of mine are developed with JPA based beans for the data model and recently i’ve come to really love Spring Data JPA. With the plain declaration of an interface extending a repository interface, you get everything you need to query your domain. Through in a second interface and you can execute JPA based criteria queries:

import entities.Projekt;
public interface ProjektRepository extends JpaRepository<Projekt, Long>, JpaSpecificationExecutor {    

My goal: Create controller methods for Spring MVC like so

@RequestMapping(value = "", method = GET)
public Page<Projekt> getProjekte(
    final @RequestParam(defaultValue = "0", required = false) int page,
    final @RequestParam(defaultValue = "10", required = false) int pageSize,	    
    final @RequestParam(required = false, defaultValue = "lieferjahr") String orderBy,
    final @RequestParam(required = false, defaultValue = "ASC") Direction orderByDirection,
    final @FilterDefinition(paths = FilteredPathsOnProjekt.class) Specification<Projekt> filter	    
) {
    return this.projektRepository.findAll(filter, new PageRequest(page, pageSize, new Sort(orderByDirection, orderBy)));

where the filter parameter is of type Specification and where i can define which fields are to be filtered in which way in a type-safe way that is checked on compile time like so:

public static class FilteredPathsOnProjekt<Projekt> extends FilteredPaths<Projekt> {
    public FilteredPathsOnProjekt() {	    
            .with((cb, p, value) ->"to_char", String.class, p, cb.literal("YYYY")), value + "%" ))
            .with((cb, p, value) ->"to_char", String.class, p, cb.literal("DD.MM.YYYY")), "%" + value + "%"))
            .with((cb, p, value) -><String>)p), "%" + value.toLowerCase() + "%"))
            .with((cb, p, value) -><String>)p), "%" + value.toLowerCase() + "%"))
            .with((cb, p, value) -><String>)p), "%" + value.toLowerCase() + "%"));		

I found this very inspiring post An alternative API for filtering data with Spring MVC & Spring Data JPA by Tomasz and here again, i big thank you.

My solution is similar, but uses the JPA Metamodel API that generates a metamodel from the annotated entity classes. In the above example, the entity is Projekt, the metamodel Projekt_ that lists all attributes that are mapped from the database.

Let’s start with the controller. Parameter filter is of type Specification and is annotated with @FilterDefinition:

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
public @interface FilterDefinition {
    Class<? extends FilteredPaths> paths();
    Class<? extends FilterSpecification> implementation() default FilterSpecification.class;

I need to wrap the paths i want to filter with a class because only are small list of types are allowed in annotations. The class looks like this:

import java.util.List;
import java.util.Map;
import javax.persistence.metamodel.SingularAttribute;
public abstract class FilteredPaths<T> {
    protected final FilteredPathsBuilder<T> builder = new FilteredPathsBuilder<>();
    public final Map<List<SingularAttribute<?, ?>>, PathOperation<T>> getValue() {
        return this.builder.getFilterablePaths();
    protected FilteredPathsBuilder<T> filter(SingularAttribute<?, ?>... path) {
        return builder.filter(path);

The core of this is the getValue method. It returns a map of lists of SingularAttributes (a list of them to do queries on sub elements) and a PathOperation. PathOperation is a functional interface:

import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.Path;
import javax.persistence.criteria.Predicate;
public interface PathOperation<T> {
    public Predicate buildPredicate(CriteriaBuilder cb, Path<?> path, String value);

that is used by my FilterSpecification to build the predicate:

import java.util.Map;
import java.util.function.Function;
import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Predicate;
import javax.persistence.criteria.Root;
import static;
public class FilterSpecification<T> implements Specification<T> {
    protected final Map<PathOperation, PathAndValue> filteredPaths;
    public FilterSpecification(Map<PathOperation, PathAndValue> filteredPaths) {
        this.filteredPaths = filteredPaths;
    public final Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuilder cb) {
        this.customizeQuery(root, query);
        return this.filteredPaths.entrySet().stream()
            .map(entry -> entry.getKey().buildPredicate(cb, entry.getValue().getPath(root), entry.getValue().getValue()))
                reducing(cb.conjunction(), Function.<Predicate>identity(), (p1, p2) -> cb.and(p1, p2))
    protected void customizeQuery(Root<T> root, final CriteriaQuery<?> query) {

As you see there’s one big difference to Tomasz solution: I don’t support OR’ing the filters, i’ve only support AND. I like the way i can use the Java 8 stream api and the reduction method to add them together very much.

How get’s this class instantiated? Here come’s the additional Spring MVC argument resolver:

import java.util.HashMap;
import java.util.Map;
import java.util.Optional;
import javax.persistence.metamodel.SingularAttribute;
import org.springframework.core.MethodParameter;
import org.springframework.web.context.request.NativeWebRequest;
public class FilteringSpecificationArgumentResolver implements HandlerMethodArgumentResolver {
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(FilterDefinition.class) && parameter.getParameterType() == Specification.class;
    public Object resolveArgument(
        MethodParameter parameter,
        ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest,
        WebDataBinderFactory binderFactory
    ) throws Exception {
        final FilterDefinition filterDefinition = parameter.getParameterAnnotation(FilterDefinition.class);	
        final FilteredPaths<?> paths = filterDefinition.paths().newInstance();
        final Map<PathOperation<?>, PathAndValue> filterValues = new HashMap<>();
        paths.getValue().entrySet().forEach(entry -> {
            final String param = entry.getKey().stream().map(SingularAttribute::getName).collect(Collectors.joining("."));
            final String paramValue = Optional.ofNullable(webRequest.getParameter(param)).orElse("");
            if (!paramValue.isEmpty()) {
                filterValues.put(entry.getValue(), new PathAndValue(entry.getKey(), paramValue));
        return filterDefinition.implementation().getConstructor(Map.class).newInstance(filterValues);

It supports controller arguments of type Specification annotated with @FilterDefinition. To resolver the argument it gets the annotation and then instantiates the class that holds the lists of paths that should be filtered. The lists actually contains the path and the filter operation. It’s iterated and each list of singular attributes is joined together with a “.”, so one attribute becomes “versorgungsart” and a nested becomes “” for example. It then checks the web requests if there are request params with those names. If so, the filter operation is added together with the path and the value for that path (from the request) to a new map (the operations are the key). This map than is passed to the implementation of the Specification.

What’s nice here: I don’t need to check if the attributes that are requested from the outside exists. As i start with the attributes of the entity from the start, there’s no chance i try to access one that doesn’t exists.

What’s missing is the pair type PathAndValue

import java.util.List;
import javax.persistence.criteria.Path;
import javax.persistence.criteria.Root;
import javax.persistence.metamodel.SingularAttribute;
public class PathAndValue {
    private final List<SingularAttribute<?, ?>> path;
    private final String value;
    public PathAndValue(List<SingularAttribute<?, ?>> path, String value) {
        this.path = path;
        this.value = value;
    public String getValue() {
        return value;
    public Path<?> getPath(final Root<?> root) {
        Path<?> rv = root;
        for (SingularAttribute attribute : path) {
            rv = rv.get(attribute);
        return rv;

that not only holds both the path (as a list of attributes) to be filtered and value to be filtered with, but also generates a complete JPA criteria path that is given to the PathOperation.

And last but not least is the little FilteredPathsBuilder that allows me to write the filter definition in a readable way and not obstructed with map and list operations as shown in FilteredPathsOnProjekt above:

import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javax.persistence.metamodel.SingularAttribute;
public class FilteredPathsBuilder<T> {
    private final Map<List<SingularAttribute<?, ?>>, PathOperation<T>> filterablePaths = new HashMap<>();
    private List<SingularAttribute<?, ?>> lastPath;
    private PathOperation<T> lastOp;
    public FilteredPathsBuilder<T> filter(SingularAttribute<?, ?>... path) {
        if(lastPath != null && lastOp != null) {
            filterablePaths.put(lastPath, lastOp);	    
        this.lastPath = Collections.unmodifiableList(Arrays.asList(path));
        this.lastOp = null;
        return this;
    public FilteredPathsBuilder<T> with(PathOperation<T> op) {
        this.lastOp = op;
        return this;
    public Map<List<SingularAttribute<?, ?>>, PathOperation<T>> getFilterablePaths() {
        if(lastPath != null && lastOp != null) {
            filterablePaths.put(lastPath, lastOp);	    
        this.lastPath = null;
        this.lastOp = null;
        return Collections.unmodifiableMap(filterablePaths);

As you can see in FilteredPathsOnProjekt above i have now a little DSL that i use to define which attribute of my entity should be filtered. Writing down the PathOperation as lambdas and using the generated MetaModel to specify the attributes i have not only filters that are checked on compile time but also have the the attributes definition only in one place. All solutions that require writing down lists of request parameters or fiddling with map parameters are too error prone and in the end, way too much work to write.

The above solution works fine with Spring 4.0.x and 4.1.x and certainly with Spring Boot. I’ve got tests for all of the code above and should anyone find this solution useful, i’m gonna prepare a standalone project with it.

Let me know, what you think.

Spring Boot as a backend for AngularJS


This is the fourth Post in my series Developing a web application with Spring Boot, AngularJS and Java 8.

I’m more a backend and database guy than a frontend developer, but i know how to write valid HTML and add some unobtrusive JavaScript to it, for example in my daily photo project. Daily Fratze is an “old-school” website for visitors and a more interactive site for users.

For my Biking Project and this series of blog posts i wanted to try out something new (for me) and i picked AngularJS to create a single page web application.

Most of the things i’ve done in AngularJS are pretty standard (i guess), but have a look at the sources yourself: bikings js.

Therefor i want to highlight just a few things that made Spring Boot play nicely with AngularJS:


I wanted as well as too work when entered in the address bar or followed through a link. To achieve this, i’m using AngularJS in HTML5 mode. Really, for this project i couldn’t care less about browser which don’t support this:

The whole html “application” lives in webapp/public/index.html which is served as a static resource by Spring Boot without any further server interaction.

To create “routes” for all URLs in app.js, i’ve created a super simple @Controller:

This forwards all mapped urls to the static resource without any further view resolving. Nice!


Spring Boot has excellent support for WebJars and automatically creates resolvers for them. Using web jars i can manage all dependencies for AngularJS and co. with Maven (yeah, i’m still using maven… ;) ):

and for example

And in index.html

Those placeholders work because i’ve enabled resource filtering in maven for selected resources in webapp. I know that there are a lot of JavaScript dependency managers out there, but this solution works very well for me. An option is to add wro4j to the mix.


I’m using plain old http basic auth. Yes, i do know that the password is transmitted in plain text but for this app and this purpose, i just don’t care. For your interest, here’s the Spring Security configuration for stateless http basic auth:

I’ve got to disable csrf protection because i don’t want to handle that in AngularJS and also, i’ve disable frame headers because the application acts as an oembed provider with frames.

I didn’t protect the whole app, but only backend methods with write access through annotations which is enabled via @EnableGlobalMethodSecurity and looks like:

Using @RestController from AngularJS

The above quoted method can easily be used from AngularJS:

“$” is a JSON object representing an instance NewBikeCmd. AngularJS maps this correctly as a @RequestBody, the thing is validated and everything else. Really nice.

Fancy things created with AngularJS

I’m not using AngularJS not long enough to rate this, but i really like the automatically refreshing about page which is created using through highcharts-ng and the nice OpenLayers integration for the tracks, written by myself: track-map-ng (OpenLayers), see an example here: Aachen – Domburg.


Rewriting this existing application from scratch (apart from the database model, that was fine), was real fun. Not only i could test and enjoy many new Java 8 features, but starting fresh, using well designed frameworks like Spring, Spring Boot and Spring Data JPA fixed many things for me i used to do wrong, sometimes because of some cargo cult i hand in mind, sometimes because i just didn’t get them right from the start.

Spring Boot together with Spring Data JPA are an excellent choice for me to write lightweight backends for JavaScript applications without loosing any functionality.

Look at some other projects of mine, i have no doubt that Boot is also a good choice for writing bigger applications, maybe with a more classical frontend, either JSP or Thymeleaf based.

Also: Java is not dead yet, in 2014 more far from than ever.

Thanks for reading so far.

Messaging and Websockets with Spring 4


This is the third Post in my series Developing a web application with Spring Boot, AngularJS and Java 8.

My old application had a J2ME(!) companion on my dump phone that send my location to the app, showing it on the page.

This was 2009… Before my iPhone time.

Planning a longer bike tour in 2014, i wanted this feature back but i have not the slightest ambition on writing an iPhone app anytime soon, so i asked around on twitter and Darko came up with OwnTracks which uses the MQ Telemetry Transport protocol for publishing (and subscribing to) location updates.

So what ingredients do we need to implement this in a standalone Java application? Actually, not many. I’ve added Apache Active MQ, Spring JMS and Messaging as well as Spring Websocket support for the frontend fun:

Spring Boot has a managed dependency for ActiveMQ but only 5.7 which has some bugs regarding the MQTT broker, therefor i use 5.9.

With those components given, it’s incredible easy to configure brokers for:

  • STOMP over WebSocket
  • Local (VM based) messaging
  • External messaging via MQTT

like this

In the simples case you would now add @EnableWebSocketMessageBroker to a configuration class and be done, but i wanted to use

  1. My own broker
  2. A username/password protected broker
  3. Also use @EnableScheduling

1. To use a custom broker, implement WebSocketMessageBrokerConfigurer (or extend AbstractWebSocketMessageBrokerConfigurer) in a configuration class and configure the relay

If you do this, be sure to add “org.projectreactor:reactor-tcp” to you dependencies, otherwise a weird ClassNotFoundException pops up…

While you’re at it, configure the thread pool size for in- and outbound channels in #configureClientInboundChannel and #configureClientOutboundChannel according to your needs.

2. See above, just use a simple Java based approach to configure the embedded broker.

3. Now this is fun… If you use some scheduled jobs in your application as i do, you’ll end up with the following exception: “More than one TaskScheduler and/or ScheduledExecutorService exist within the context”. Yeah, great… If you don’t configure a default scheduler, the ScheduledAnnotationBeanPostProcessor tries to find all beans of type TaskScheduler or ScheduledExecutorService… If it finds none, it uses the default, if it finds one, uses this, if it finds more, everything breaks… @EnableWebSocketMessageBroker creates 2 schedulers… So you need to configure your own:

I wish there is more to say, but the rest is standard… Putting together some listener that reacts on incoming locations, calls the Spring Data Repository and uses SimpMessagingTemplate to notify all subscribed STOMP clients. For details regarding WebSocket and STOMP have a look at the Spring reference. As i didn’t have any luck with the Atmosphere frameworks in 3 different applications since 2011, i’m really happy how the Spring solution turned out. Maybe she is still a little buggy, but i’m quite sure this will be fixed.

At the moment the location site runs on an uberspace behind a proxy, but STOMP together with SockJS handles this situation gracefully (and are actually dead simple to use):

It’s amazing what you can achieve with Java and Spring with little effort those days.

Using Java 8 .now()


This is the second Post in my series Developing a web application with Spring Boot, AngularJS and Java 8.

Java 8 has a major history. Many features should have been already included in Java 7 (i.e. Lambdas (anonymous functions for the elderly), modules and some stuff from project coin), which was released in 2011.

Now, in March 2014, Java 8 will be released (and i will be enjoying the release party in JavaLand) and it’s time to get some impression, what’s new and what’s doable.

Java 8 support in Spring 4

Spring 4 has already full support for Java 8:

Spring Framework 4.0 provides support for several Java 8 features. You can make use of lambda expressions and method references with Spring’s callback interfaces. There is first-class support for java.time (JSR-310), and several existing annotations have been retrofitted as @Repeatable. You can also use Java 8’s parameter name discovery (based on the -parameters compiler flag) as an alternative to compiling your code with debug information enabled.

Java 8 (as well as 6 and 7)

What is not available is Java 8 support in Eclipse based Springsource Tool Suite. I tried really hard to like JetBrains IntelliJ IDEA but it didn’t click at all. One example: I’m (still) a big Maven fan and adding a XML file for every dependency in a Maven project is a no-go for me. Also, on my 2012 iMac with 16GiB ram but HDD the product is way to slow.

So in the end i gave NetBeans IDE another try. I’m using 7.4 at the moment and i must say i really like it. Maven support is outstanding, didn’t have any problem with broken builds, plugins (JPA meta model, byte code enhancements) work as expected and the IDE feels very snappy.

I really like the CSS and JavaScript support as well. Autocomplete for CSS classes for example is a very handy feature.

And finally, NetBeans 7.4 has first class support for Lambdas and Java 8 features. There are many helpful hints to convert anonymous inner classes to Lambdas, for example.

Lambdas as configuration classes

The following represents one way to add filters to a Servlet 3 context using Spring Boots ServletContextInitializer:

public ServletContextInitializer servletContextInitializer() {
    return new ServletContextInitializer() {
	public void onStartup(ServletContext servletContext) throws ServletException {
	    final CharacterEncodingFilter characterEncodingFilter = new CharacterEncodingFilter();
	    servletContext.addFilter("characterEncodingFilter", characterEncodingFilter).addMappingForUrlPatterns(EnumSet.of(DispatcherType.REQUEST), false, "/*");

You have to create an inner class, clutter your code with the onStartup method and what you really want to is just to add stuff to the Servlet context:

public ServletContextInitializer servletContextInitializer() {
    return servletContext -> {
	final CharacterEncodingFilter characterEncodingFilter = new CharacterEncodingFilter();
	servletContext.addFilter("characterEncodingFilter", characterEncodingFilter).addMappingForUrlPatterns(EnumSet.of(DispatcherType.REQUEST), false, "/*");

The type of the lambda is determined by the return type of servletContextInitializer() and the rest is very simple to read: An instance of ServletContext is passed to the block and can be configured. Puritans would mind the braces, but i don’t. I like this syntax very much: Reduced to the stuff i want to do with little clutter as possible.

If Spring Boot was Java 8 only, the ServletContextInitializer interface should have been annotated with FunctionalInterface that has exactly one abstract method. The interface enforces that only one abstract method is present and the type is an interface type. Bear in mind, that any interface that meet this conditions, like the one above, are treated as functional as well.


I love Streams:

A sequence of elements supporting sequential and parallel aggregate operations. […] To perform a computation, stream operations are composed into a stream pipeline. A stream pipeline consists of a source (which might be an array, a collection, a generator function, an I/O channel, etc), zero or more intermediate operations (which transform a stream into another stream, such as filter(Predicate)), and a terminal operation (which produces a result or side-effect, such as count() or forEach(Consumer)). Streams are lazy; computation on the source data is only performed when the terminal operation is initiated, and source elements are consumed only as needed.

In my biking application i wanted to note my tachometer each month and add the current total milage and all computations should be done by the app. The old application was a Ruby app and this could be done in a one liner. A Java 8 stream allows nearly the same:

milages are the list of total milage at a given point in time. This method computes all monthly periods by:

  • Creating an IntStream from 1 (inclusive) to the size of milages (exclusive)
  • Map those ints to a LocalDate and a value by collecting them in a TreeMap.

In the “collect” call you see a Method Reference to the constructor of TreeMap as the 1st parameter and to the putAll method as the last parameter. This means:

“Collect them by creating a new TreeMap as the target, use the lambda given as 2nd parameter and merge them using putAll when ran in parallel.”

The given lambda just takes the generated int, get the milage at the given and previous index, compute the date and the differences and add it to the map parameter.

If you get your brain around those notions of collecting, mapping and reducing, the stuff actually becomes very easy to read.

The following is an example that includes filtering of stuff and resolving associations from the controller that creates the nice history graph here:

This creates a stream of all bikes than resolves all associations (I’m a database guy after all) to periods and creates a new stream from all periods, those are filtered by date and than collected in a TreeMap representing years and an array of values for each month per year.

There is also an example of the new Map#computeIfAbsent that creates a new value for a key not contained in the map which is handy in soooo many cases. The “generate” call in the same line is actually the creation of a new array containing 12 zeros:

IntStream.generate(() -> 23).limit(42).toArray()

just with a static import of #generate.

Also this statement includes an example that the stream operations may run in parallel and it’s sometimes not enough to use an simple Map#putAll as a combiner as in the example of the combiner in collect above. Here an existing array would have been overwritten when the operation runs in parallel so the addArray method must take care of this and is used for Map#merge.

Some say that Java 8 is pretty much recreating SQL with this kind of syntax and thinking, specifying what you want not how you want it. I – as stated above – like this.

I think this is just the tip of the things you can to with streams.

JSR 310 Date and Time API

FINALLY a build-in Date-Time API that doesn’t suck in pretty much every way and is not from Taligent.

Just let me start with an example of how broken the inheritance chain of java.util.Date and java.sql.Date is:

Date#toInstant: Converts this Date object to an Instant.

You see, a Date represents specific instant in time, with millisecond precision and can therefor be converted to a shiny new Instant.

As Hibernate doesn’t support JSR 310 yet, i wanted to use java.util.Date for my TemporalType.DATE’s to convert them to LocalDate like


The reason for Date instead of Calendar was Hibernate HHH-8617 discovered by me. I just wanted to do it right but was let down by the fact, that hibernate doesn’t return java.util.Date but java.sql.Date.

java.sql.Date represents only a date (yeah, the behavior is semantically correct), but there you have one of the bad designs in this area: Changing the behavior of the the class in a way that #toInstant of java.sql.Date throws an exception because it represents suddenly only a date is just horrible.

But enough of the old stuff. In the examples above you already see some new features of JSR 310, i.e. the query methods isBefore / isAfter.

Those classes are already supported in Spring 4 and can be used as controller method parameters together with a DateTimeFormat:

There are many other useful classes in java.time, be sure to have a look.

XML Parsing

Nothing that new here, but i’m doing Java for so long and although it seams that XML is an intrinsic part of the language there are is a plethora of solutions for XML parsing, for example JDOM, DOM4J, XOM and many more.

Java Architecture for XML Binding (JAXB) is part of Java since 1.6 but at least not used often enough by me.

To create a simple parser for MediaRSS it’s enough to write a few POJOs, annotate them a little, for example:

configure some namespaces

and you’re good to go:

JAXBContext rssContext = JAXBContext.newInstance(RSS.class);
final Unmarshaller unmarschaller = rssContext.createUnmarshaller();
RSS rss = (RSS) unmarschaller.unmarshal(inputStream);

Neat, i’d say.

You can also use the new java.time classes with little effort:


I had really much fun exploring Java 8’s new features and i’m somewhat sad that i cannot use them in current projects of mine that are not recreational projects.

What i didn’t touch was Nashorn, but maybe i’ll find a use case for that too in my demo application.

Having written a major application in Ruby using Ruby on Rails 2.x, doing maintenance for a medium sized Grails application and looking sometimes at Scale, i’d always go back to plain, old Java, hands down. Maybe the syntax is more verbose, maybe strict typing is old school, but all that gives you a kind of assurance that other languages are missing. There are a lot of IDEs to generate most of the boring stuff for you. Also, don’t forget that many developers, senior or junior, seems a bit overwhelmed the last years by the continuing growth in technologies (I’ve written about that in Old and tired?) and not everybody is as keen as the writer of this post to learn something new. With Java 8 you can have both: Old-fashioned code or a streamlined, modern code base.

Boot your application with Spring Boot


This is the first Post in my series Developing a web application with Spring Boot, AngularJS and Java 8.

Spring Boot makes it very easy to get you up and running with the Spring ecosystem without the need for XML configuration and the like. The nice thing about Boot is: It doesn’t add aspects and doesn’t generate code. Instead it uses several conditional beans to configure sensible defaults that disappear as soon as you add your own beans. This document helps a lot to discover the defaults and properties to customize everything you need: How Do I Do That With Spring Boot?.

So we want to create a simple MVC app with a hand full of (REST) controllers. Therefor i use the “spring-boot-starter-parent” as my parent pom:

and then use “spring-boot-starter-web” as the dependencies that include everything that is needed for Spring MVC to work:

Another goodie i wanted to use is Spring Boots ability to create executable jar files with an embedded web container, Tomcat 7 by default, so i need the spring-boot-maven-plugin as well:

Given my as the “start-class” (defined in the properties of my pom), i can run this application via “mvn spring-boot:run” or create an executable jar file with mvn package.

So what is this Application class? It looks like this:

You’ll see that it is a Spring @Configuration class that tells Spring Boot to enable automatic configuration (@EnableAutoConfiguration) as well as scheduling (@EnableScheduling) and finally tells Spring to look for more components in this and all child packages (@ComponentScan). The main method initializes an application context via a factory method inside SpringApplication. The configure method inherited from SpringBootServletInitializer does essentially the same but only when deployed as a war file. The one additional bean “home” just didn’t fit anywhere else, but you see a nice @Value annotation around the two parameters that reads “take the required value ‘biking2.home.longitude’ from the environment and used id as a parameter”. Methods annotated with @Bean are subject to dependency injection for their parameters, either beans or values. The values here are taken from at the root of the classpath.

With just a bunch of code you’ll have a fully configured application including scheduled jobs.

I want to keep track of my milage so i need some kind of persistence. I opted for H2 and added com.h2database:h2 as a dependency. Without any version number as a lot of possible dependencies are already versioned and managed by the parent pom. As i added org.springframework:orm and i could stop here. Spring Boot would automatically create a data source for me. I want some control so i added the following to the application properties:

This is also a nice example of using SpEL and nested properties inside property files managed by spring. The colon inside spring.datasource.username means “take the value of biking2.database-username if exists, otherwise use biking2″. Nice detail. Given this data source, i wanted a little more control over JPA, see For example, i wanted the Spring Data repository inside a given package (@EnableJpaRepositories(basePackages = “ac.simons.biking2.persistence.repositories”)) (otherwise they would have been initialized as well, but only in the default level), have some control over sql statements and adding the hibernateExceptionTranslator.

So, data source and repositories are ready? Nearly. I have an additional This properties file is only evaluated with profile test being active. I’m configuring a test in-memory db. This would happen automatically as well but with the added DB_CLOSE_DELAY=-1 parameter to the database url which means: “Keep the content of this db inside memory until the VM closes, not only until the last connection closes.” I had problems with my tests. The builder automatically adds schema.sql and data.sql and that fails if a new tests forks and the database is reused. I’m not sure wether it’s a problem with my configuration or with the Spring test runner.

So i’ve created a bunch of entities together with a repository if needed. The basic idea behind the bike -< milage entities is to record the milage of my trip recorder each month and to be done. All calculations happens inside the app.

JpaRepositories are just great. The following interface

will be instantiated at runtime and together with basic CRUD functionality, it maps two named queriers (“Bike.findActive” as #findActive(final @Param(“cutoffDate”) Calendar cutoffDate) and “Bike.getDateOfFirstRecord” as #getDateOfFirstRecord() both defined inside Bike and a dynamic query build by parsing “findByDecommissionedOnIsNull”.

So we have an application context, a data source including entities and repositories, we could throw in some services, but just keep it simple, i use the repository inside the following @RestController:

@RestControllers assume an implicit @ResponseBody at all methods annotated with @RequestMapping.

What do we see? First, an auto wired constructor. I opted for all dependency injection through constructors as i’m currently observing in another project when getter/setter injection get’s out of hands. People usually start to feel uncomfortable having a constructor more than 15 parameters (at least i hope). As an added benefits, most objects are immutable.

The repository is than used, depending on a request parameter, to retrieve a list of all bikes or of all active bikes and this list is returned. As jackson-core is on the class path, this list is automatically converted to a valid JSON representation. Given ” @RequestMapping(value = “/api/bikes”, method = GET)”, the method is exposed at the given endpoint.

Testing this method is an easy task. Just instantiate the controller with a mock repository, run your tests directly on the instance and be done. You can alternatively boot an application context or parts of a context to test methods with MockMvc, have a look at (More on that topic in a later post).

This method is actually used here for the list of bikes at the bottom of the page.

With a minimum effort, i’ve developed an API without nearly zero maintenance cost. I like this a lot.

Here is a short list of hints, that maybe help you:

Running behind a proxy

The app runs behind a proxy and needs to generate some links and therefore must know the proxy name.

Apart from seeing a Java 8 lambda, you’ll find a static Condition that checks the presence of a given property in the environment of the application context.

The following @Bean “embeddedServletContainerCustomizer” is only instantiated when the @Conditional matches and the property is present. The parameter proxyName uses this property name, the parameter proxyPort has a default of 80. The following just sets those two values on a TomcatEmbeddedServletContainerFactory.

Uploading files

To enable the Servlet 3.0 Multipart support, the Spring Boot Guides show here a bean of type MultipartConfigElement is enough. That’s true and works very well. But as many people just copy & paste code, the note the default configuration imposes no limits on the file size for an upload should really be a warning if you ever plan to run this in public. An authentication doesn’t protect you from big uploads. Those are send first, than the authentication is processed. So be sure the bean reads something like

This restricts uploads to 5Mb.

Multipart/form-data and UTF-8

To support UTF-8 in Multipart/form-data, add the following bean to your config:

The ServletContextInitializer is a special form of ServletContainerInitializer that works with Spring and Spring Boot. Here it’s used to add the CharacterEncodingFilter before all other filters. The before all other part is important, otherwise it doesn’t work for Multipart/form-data.

Customizing RequestMappingHandlerMapping

At the moment it is not possible to get hold of the default RequestMappingHandlerMapping and customize things like “useRegisteredSuffixPatternMatch” and the like. It’s not a conditional bean and adding your own will lead to double mappings.

So i’m using a classic beanPostProcessor to achieve this with Spring Boot 1.0.0.RC3:


At this point we have a working API, that can be used immediately in a JavaScript framework like Knockout.js or AngularJS.

Next post will be about Java 8 in the context of this application.

The whole source code at the point of writing this post is available at GitHub, the application is live right there