Merge pull request #13615 from thibaultfaure/articles/BAEL-6206-@contract-annotation

BAEL-6206 code for the JetBrains @Contract annotation article

jetbrains/README.md

@@ -0,0 +1,5 @@
+## Jetbrains
+
+This module contains articles about Jetbrains' libraries.
+
+### Relevant articles:

jetbrains/pom.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <artifactId>jetbrains</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <name>jetbrains</name>
+    <packaging>jar</packaging>
+    <url>http://maven.apache.org</url>
+
+    <parent>
+        <groupId>com.baeldung</groupId>
+        <artifactId>parent-java</artifactId>
+        <version>0.0.1-SNAPSHOT</version>
+        <relativePath>../parent-java</relativePath>
+    </parent>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-lang3</artifactId>
+            <version>${apache.commons.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.jetbrains</groupId>
+            <artifactId>annotations</artifactId>
+            <version>${jetbrains.annotations.version}</version>
+        </dependency>
+    </dependencies>
+
+    <properties>
+        <apache.commons.version>3.12.0</apache.commons.version>
+        <jetbrains.annotations.version>24.0.1</jetbrains.annotations.version>
+    </properties>
+
+</project>

jetbrains/src/main/java/com/baeldung/annotations/Demo.java

@@ -0,0 +1,112 @@
+package com.baeldung.annotations;
+
+import java.util.List;
+
+import org.apache.commons.lang3.StringUtils;
+import org.jetbrains.annotations.Contract;
+
+public class Demo {
+
+    @Contract("_ -> new")
+    Person fromName(String name) {
+        return new Person().withName(name);
+    }
+
+    @Contract(" -> fail")
+    void alwaysFail() {
+        throw new RuntimeException();
+    }
+
+    @Contract(" -> fail")
+    void doNothingWithWrongContract() {
+
+    }
+
+    @Contract("_, null -> null; null, _ -> param2; _, !null -> !null")
+    String concatenateOnlyIfSecondArgumentIsNotNull(String head, String tail) {
+        if (tail == null) {
+            return null;
+        }
+        if (head == null) {
+            return tail;
+        }
+        return head + tail;
+    }
+
+    void uselessNullCheck() {
+        String head = "1234";
+        String tail = "5678";
+        String concatenation = concatenateOnlyIfSecondArgumentIsNotNull(head, tail);
+        if (concatenation != null) {
+            System.out.println(concatenation);
+        }
+    }
+
+    void uselessNullCheckOnInferredAnnotation() {
+        if (StringUtils.isEmpty(null)) {
+            System.out.println("baeldung");
+        }
+    }
+
+    @Contract(pure = true)
+    String replace(String string, char oldChar, char newChar) {
+        return string.replace(oldChar, newChar);
+    }
+
+    @Contract(value = "true -> false; false -> true", pure = true)
+    boolean not(boolean input) {
+        return !input;
+    }
+
+    @Contract("true -> new")
+    void contractExpectsWrongParameterType(List<Integer> integers) {
+
+    }
+
+    @Contract("_, _ -> new")
+    void contractExpectsMoreParametersThanMethodHas(String s) {
+
+    }
+
+    @Contract("_ -> _; null -> !null")
+    String secondContractClauseNotReachable(String s) {
+        return "";
+    }
+
+    @Contract("_ -> true")
+    void contractExpectsWrongReturnType(String s) {
+
+    }
+
+    // NB: the following examples demonstrate how to use the mutates attribute of the annotation
+    // This attribute is currently experimental and could be changed or removed in the future
+    @Contract(mutates = "param")
+    void incrementArrayFirstElement(Integer[] integers) {
+        if (integers.length > 0) {
+            integers[0] = integers[0] + 1;
+        }
+    }
+
+    @Contract(pure = true, mutates = "param")
+    void impossibleToMutateParamInPureFunction(List<String> strings) {
+        if (strings != null) {
+            strings.forEach(System.out::println);
+        }
+    }
+
+    @Contract(mutates = "param3")
+    void impossibleToMutateThirdParamWhenMethodHasOnlyTwoParams(int a, int b) {
+
+    }
+
+    @Contract(mutates = "param")
+    void impossibleToMutableImmutableType(String s) {
+
+    }
+
+    @Contract(mutates = "this")
+    static void impossibleToMutateThisInStaticMethod() {
+
+    }
+
+}

jetbrains/src/main/java/com/baeldung/annotations/Person.java

@@ -0,0 +1,15 @@
+package com.baeldung.annotations;
+
+import org.jetbrains.annotations.Contract;
+
+public class Person {
+
+    String name;
+
+    @Contract("_ -> this")
+    Person withName(String name) {
+        this.name = name;
+        return this;
+    }
+
+}

pom.xml

@@ -352,6 +352,7 @@
                 <module>java-jdi</module>
                 <module>java-websocket</module>
 
+                <module>jetbrains</module>
                 <module>jhipster-5</module>
 
                 <module>jmh</module>
@@ -730,7 +731,7 @@
                 <module>spring-boot-modules/spring-boot-react</module>
                 <module>spring-ejb-modules/ejb-beans</module>
                 <module>vaadin</module>
-               <module>vavr-modules</module>
+                <module>vavr-modules</module>
             </modules>
 
         </profile>
@@ -934,7 +935,6 @@
                 <module>asm</module>
                 <module>atomikos</module>
                 <module>atomix</module>
-<!--            <module>axon</module>--><!-- JAVA-18408 -->
 
                 <module>bazel</module>
                 <module>code-generation</module>