Version française disponible

IT projects nowadays are mostly based on a microservice oriented architecture, it is not surprising that the different microservices are developed and maintained by different teams.

Each service provides an API (private or public) that allows the communication with the outside world while guaranteeing its data integrity. Multiple nested calls between microservices make it possible to do more complex processing. It is very important to have an up-to-date documentation for each of your APIs. Who has never heard a developer say to another “This doc has not been updated for months, look at the code directly!”.

Swagger UI complies with this assertion. Simply annotate your code and the framework will semi-automatically generate all your API documentation. I use ‘semi-automatic’ because Swagger cannot guess the business side of your documentation, so you have to write it yourself in a similar way that you are writing Javadoc.

The documentation generated by Swagger is updated at the same time as the code is. For instance, if you add a new parameter to a method that is exposed, it will be automatically taken into account and documented with the appropriate annotations. The documentation is much more than a static HTML file, it allows to act as an HTTP client (there is no need to have Postman installed for example) to test the various methods exposed by the API.

You can take a look at the official sample application (Petstore) and see by yourself the various supported features, for example OAuth2.0 authentication is supported.

Example with Swagger (Petstore)

If you use Spring MVC in your application, the SpringFox project (Swagger wrapper) makes Swagger integration very simple. In less than an hour, you should be able to generate your API documentation. Then you can add optional annotations to make it even more complete.

By adopting Swagger on all your microservices, it is a good bet that the communication between your different teams will improve. You will have a unique entry point and you can forget that dusty wiki page that was updated once in a while… Wishing you good documentation!

 Version française disponible

Juergen Hoeller, the co-founder of the Spring framework was doing a presentation last week at QCon London.

QCon London 2016 - Spring Framework 5 - Preview & Roadmap

Some history background first, the Spring framework has been created in 2002 with a first release in 2004 (yes, it was 12 years ago!), quite a long time for a framework which is still widely used and under development. The adoption and the number of projects within Spring has never stopped growing since. At the beginning, Spring was created to manage POJOs in a lightweight container by using dependency injection (following the Inversion of Control or IoC principle), Spring was an alternative to heavy JEE containers such as GlassFish or WebSphere.

Spring has now become a set of projects that are available to fulfill many requirements when building an application. Spring is like a set of Lego bricks, you can pick and assemble these compatible sub-projects to build something bigger.

• Imagine you want to use a database, you can use Spring Data
• You need to secure your application, just use Spring Security
• You want to be able to login to your application through social networks, Spring Social is here for you
• And so on

You can take a look at the full list of Spring projects.

Spring 4.3

Before jumping to Spring 5, Juergen talked about Spring 4. When I write this post, the current version is 4.2.5. A release candidate (RC) of Spring 4.3 will be available in March 2016 followed by a General availability (GA) one in May 2016. This version will include a couple of handy changes:

• In Spring Framework core:
  The @autowired annotation used to inject a dependency will be implicit so will become optional
• In Spring MVC (part of the core):
  The declaration of a MVC controller is refined. Before, value was the attribute name:

  @RequestMapping(value = '/mypath', method = RequestMethod.POST)
  

  After, we use a more meaningful name path:

  @RequestMapping(path = '/mypath', method = RequestMethod.POST)
  

  There are even new annotation shortcuts to avoid specifying the HTTP method attribute. And even the attribute name is optional, so it becomes very simple.

  @PostMapping('/mypath')
  

  And the equivalent for a GET

  @GetMapping('/mypath')
  

Spring 5.0 announced

Then, Juergen announced that Spring 5.0 will be available sometime in 2017 and compatible with JDK 8 and 9. On the roadmap, the GA should be available in March 2017 (at the same time the JDK 9 will be released). In case JDK 9 release is delayed, Spring 5.0 will be probably delayed too.

What are the major updates in Spring 5?

There are 3 key infrastructure themes:

• JDK 9 and Jigsaw modules
• Servlet 4.0 and HTTP/2
• Reactive architecture

JDK 9 and use of Jigsaw

In short, Jigsaw brings modularity to the JDK. The JDK is split up into modules and you can pick up only the ones you need to make your application works.

The JDK will come with a set of modules, but you can also define your owns. To define a module, you need to create a module-info.java file:

module my.app.db {
  requires java.sql;
  requires spring.jdbc;
}

Inside a module, you specify the modules you need with the keyword requires. Modules are managing transitive dependencies, a bit like Maven. If I use the module my.app.db above, I will be able to access any classes coming from the java.sql module. The main benefit is that it makes your application more modular relying on a subset of modules instead of a full JDK.

All the jars for Spring 5 will come with Jigsaw metadata out of the box, the module name will follow the Maven Central jar naming to avoid confusion (spring-context, spring-jdbc, spring-webmvc…). It will be very easy to build your applications by specifying the Spring modules you need.

HTTP/2

HTTP/1.1 is an old protocol (1999) and has some limitations. In the front-end world, we are using some workarounds, but it is not ideal. For example, to avoid overloading the server with multiple requests when a page contains a lot of images, we use CSS sprites (i.e. combine these images into one single file that we then split on the client side via CSS). With HTTP/2, the protocol is faster as it allows concurrency requests and removes the “head-of-line blocking”. There are other benefits that you can read on the HTTP/2 Frequently Asked Questions page.

As Juergen stated, “We need to embrace HTTP/2 in the Java land as well!”

To achieve that, Spring 5 will use the latest version of the Servlet library, Servlet 4.0 that:

• Enforces support for HTTP/2 in servlet containers
• Gives API features for Stream priorization and push resources

Reactive programming

Another big announcement was the creation of a new Spring project called Spring Reactive. It will be a Spring MVC-like endpoint based on a reactive foundation.

• Reuses Spring MVC programming model style
• But accepting and returning reactive streams (e.g. Mono – 1 element, Flux – list of elements)

Spring Reactive will be based on Project Reactor, a set of foundational libraries for building reactive cloud-ready applications on the JVM. This new project is not stand-alone and will be included in the Spring Framework core at some point.

Juergen reminds us that “Reactive is coming”:

• No blocking thread involved
• Reactive datastore drivers become available (PostgreSQL, Mongo, Couchbase…)
• Reactive HTTP client (Netty, Jetty, OkHttp…)

Note for myself and maybe for you as well, it is important to read some materials on Reactive and get familiar with the concepts, it will probably spread in the following years.

Last but not least, Spring 5 will use all the latest features introduced with Java 8:

• Lambdas, method reference, default methods in interfaces
• Ability to expose JDK 8 API types in core interfaces and classes: java.util.Optional, java.util.function, java.util.stream

As a matter of fact, Spring 5 will require Java 8. If your project is still using an older version, you will have to use Spring 4.X. The good news is that Spring 4 will have an extended support until 2020, so you will still have some time to migrate!

Slides of the presentation are available on the QCon website.