more info on null-safety

Author: Jonas Keßler

readme.md

@@ -4,17 +4,25 @@ This project covers several changes in spring-boot 2.0.0 which are worth knowing
 
 Currently this project contains changes from the latest released milestone 2.0.0M3.
 
-__Code structure__
+__Code structure__<br/>
 This repository contains two spring-boot-projects:
 - `spring-boot-2-demo` which shows the new features, see below.
 - `spring-boot-1-demo` which is meant to show the old behaviour
 
 # Features inherited from Spring Framework 5.0.0
 
-## @Nullable
-See package `de.acando.jk.bootdemo.newfeatures.nullable`.
+## @Nullable and @NonNullApi
 
-`@Nullable` annotation can be used in controller to define that e.g. a RequestParam is not required.
+> Intention of the spring developers was to "leverage [JSR 305](https://jcp.org/en/jsr/detail?id=305) (...) meta-annotations to specify explicitly
+null-safety of Spring Framework parameters and return values", compare this  [commit message](https://github.com/spring-projects/spring-framework/commit/87598f48e41d483745aba56cbf4e998c6f6d680c#diff-31f527c92f7d3887b2320e4a28e7be8a). <br/>
+> Another aim was to make the Spring-Framework null-safe for Kotlin. The annotations are also used for static code analysis, e.g. IntelliJ produces warnings when unsafe nullable usages are detected.
+
+Besides these points described above, the `@Nullable` annotation can be used to declare that a object can be null which means it is not required. Places where it can be used: 
+- On field injection
+- On controller injection
+- In controllers requestmapping methods to define that e.g. a RequestParam is not required.
+
+Example implementation see package `newfeaturesin2.nullable` in both projects.
 
 ## Candidate Component Index
 There is a new package `spring-context-indexer` which, if included as dependency, creates a index file `META-INF/spring.components` at build time. This file lists all candidate components (Spring Beans) as well as JPA candidates (Entities, Repositories).
@@ -26,13 +34,16 @@ Add following maven dependendy to active the new feature:
         <artifactId>spring-context-indexer</artifactId>
     </dependency>
 
+For more details for this new feature see the [commit message](https://github.com/snicoll/spring-framework/commit/dc160f6fd1f3623bf14b375c14a9b5065e660377) and the [JIRA Discussion](https://jira.spring.io/browse/SPR-11890).
+
 Simple hint for taking a look at the new mechanism via debugging in an IDE:
 - CAUTION: This is just for taking a look at the new mechanism, should be reverted if going back to developing! 
 - Run a build, then copy `META-INF/spring.components` from the jar file to `src/main/resources/META-INF/spring.components`
 - Breakpoints in 
   * `CandidateComponentsIndexLoader.loadIndex(..)` where the index file is loaded
   * `ClassPathScanningCandidateComponentProvider.findCandidateComponents(..)` where the index is used ix exists, otherwise class path is scanned
 
+To see that it works for JPA related candidates, checkout the branch `jpa` and run a build.
 
 
 ## Changed or removed properties
@@ -50,7 +61,10 @@ Simple hint for taking a look at the new mechanism via debugging in an IDE:
 Can be changed with property `management.context-path`.
 
 ## @ConfigurationProperties needs @Validated
-`@Valiadated` is now required, if there are any validation annotations in a `@ConfigurationProperties` class, which should be requested at startup.
+
+`@Validated` is now required, if there are any validation annotations in a `@ConfigurationProperties` class, which should be requested at startup.
+
+Example implementation: see package `newfeaturesin2.properties` in both projects. In v1.x the application fails starting, if the property `test.any` is not set. In v2.x it only fails if the `@Validated` annotation is used.
 
 ## New spring-boot-starter-json
 Includes dependencies `jackson-databind`, `jackson-datatype-jsr310` (necessary for convenient handling of java 8 data types) among others. The `spring-boot-starter-json` is in 2.0.0 included everywhere, where `jackson-databind` was used in 1.x. E.g. in the `spring-boot-starter-web`, so for my normal project setup there is no jackson dependency to be added explicitly anymore.

spring-boot-1-demo/src/main/java/de/acando/jk/boot1demo/newfeaturesin2/nullable/ServiceWithoutImplementation.java

@@ -0,0 +1,12 @@
+package de.acando.jk.boot1demo.newfeaturesin2.nullable;
+
+/**
+ *
+ * @author Jonas Keßler (jonas.kessler@acando.de)
+ */
+public interface ServiceWithoutImplementation {
+
+	public default String tellMeSomething() {
+		return "Spring is awesome";
+	}
+}

spring-boot-1-demo/src/main/java/de/acando/jk/boot1demo/newfeaturesin2/nullable/TestController.java

@@ -2,6 +2,7 @@
 
 import java.util.Optional;
 
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
@@ -16,21 +17,40 @@
 public class TestController {
 
 	/*
-	 * Nullable geht noch nicht in Spring < 5
+	 * Alternative solutions for field injection without @Nullable annotation:
+	 * - @Autowired(required = false) ServiceWithoutImplementation
+	 * - @Autowired Optional<ServiceWithoutImplementation>
 	 */
-	// @GetMapping()
-	// public String hello(@Nullable @RequestParam String name) {
-	// return "Hello " + name;
+	
+	// @Autowired(required = false)
+	// private ServiceWithoutImplementation service;
+
+	@Autowired
+	private Optional<ServiceWithoutImplementation> service;
+
+
+	/*
+	 * Alternative solution for constructor injection without @Nullable annotation
+	 */	
+	// private final Optional<ServiceWithoutImplementation> service;
+	// public TestController(Optional<ServiceWithoutImplementation> service) {
+	// this.service = service;
 	// }
 
+	
+	
 	/*
-	 * Alternative solutions:
-	 * - @RequestParam(required = false)
-	 * - Optional<String>
+	 * Nullable annotation not available Spring < 5
+	 * Alternative solutions here:
+	 * - @RequestParam(required = false) String
+	 * - @RequestParam Optional<String>
 	 */
 	@GetMapping
 	public String hello(@RequestParam Optional<String> name) {
-		return "Hello " + name.orElseGet(() -> "unknown");
+		return "Hello " + name.orElse("unknown")
+				+ " - "
+				+ service.orElse(new ServiceWithoutImplementation() {
+				}).tellMeSomething();
 	}
 
 

spring-boot-2-demo/src/main/java/de/acando/jk/bootdemo/newfeaturesin2/nullable/ServiceWithoutImplementation.java

@@ -0,0 +1,12 @@
+package de.acando.jk.bootdemo.newfeaturesin2.nullable;
+
+/**
+ *
+ * @author Jonas Keßler (jonas.kessler@acando.de)
+ */
+public interface ServiceWithoutImplementation {
+
+	public default String tellMeSomething() {
+		return "Spring is awesome";
+	}
+}

spring-boot-2-demo/src/main/java/de/acando/jk/bootdemo/newfeaturesin2/nullable/TestController.java

@@ -1,5 +1,7 @@
 package de.acando.jk.bootdemo.newfeaturesin2.nullable;
 
+import java.util.Optional;
+
 import org.springframework.lang.Nullable;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -10,9 +12,33 @@
 @RequestMapping("/test")
 public class TestController {
 
+	/*
+	 * @Nullable usage at field injection
+	 */
+	// @Nullable
+	// @Autowired
+	// private ServiceWithoutImplementation service;
+
+
+	/*
+	 * @Nullable usage in constructor injection
+	 *
+	 * FYI, since spring 4.3:
+	 *  ->  It is no longer necessary to specify the @Autowired annotation if the target bean only defines one constructor.
+	 *  compare https://docs.spring.io/spring/docs/current/spring-framework-reference/html/new-in-4.3.html
+	 */
+	private final ServiceWithoutImplementation service;
+	public TestController(@Nullable ServiceWithoutImplementation service) {
+		this.service = service;
+	}
+
 	@GetMapping()
 	public String hello(@Nullable @RequestParam String name) {
-		return "Hello " + name;
+		return "Hello " + Optional.ofNullable(name).orElse("unknown")
+				+ " - "
+				+ Optional.ofNullable(service)
+						.orElse(new ServiceWithoutImplementation() {
+				}).tellMeSomething();
 	}
 
 }