Add incubating annotation to javadocs including max version informati…

…on. (#1565)

Add @Incubating along with the max version information "To be removed in a.b.c."

changelog/@unreleased/pr-1565.v2.yml

@@ -0,0 +1,5 @@
+type: improvement
+improvement:
+  description: Add incubating annotation and max version info to javadoc
+  links:
+  - https://github.com/palantir/conjure-java/pull/1565

conjure-java-core/src/main/java/com/palantir/conjure/java/services/ServiceGenerators.java

@@ -35,6 +35,8 @@ public static String getJavaDocWithRequestLine(EndpointDefinition endpointDef) {
     private static Optional<String> getJavaDocInternal(EndpointDefinition endpointDef, boolean includeRequestLine) {
         Optional<String> depr = endpointDef.getDeprecated().map(Javadoc::getDeprecatedJavadoc);
 
+        Optional<String> incDoc = Javadoc.getIncubatingJavadoc(endpointDef.getTags());
+
         Optional<String> docs = endpointDef.getDocs().map(Javadoc::render);
 
         Optional<String> requestLine = Optional.empty();
@@ -52,6 +54,7 @@ private static Optional<String> getJavaDocInternal(EndpointDefinition endpointDe
         requestLine.ifPresent(sb::append);
         params.ifPresent(sb::append);
         depr.ifPresent(sb::append);
+        incDoc.ifPresent(sb::append);
         return sb.length() > 0 ? Optional.of(sb.toString()) : Optional.empty();
     }
 

conjure-java-core/src/main/java/com/palantir/conjure/java/util/Javadoc.java

@@ -22,6 +22,9 @@
 import com.palantir.conjure.spec.HttpMethod;
 import com.palantir.conjure.spec.HttpPath;
 import java.util.Optional;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import org.apache.commons.lang3.StringUtils;
 import org.commonmark.node.Paragraph;
 import org.commonmark.parser.Parser;
@@ -90,5 +93,20 @@ public static String getDeprecatedJavadoc(Documentation deprecationDocs) {
         return "@deprecated " + render(deprecationDocs);
     }
 
+    public static Optional<String> getIncubatingJavadoc(Set<String> endppointTags) {
+        Optional<String> incubatingMaxVersion = Optional.empty();
+        if (endppointTags.contains("incubating")) {
+            Pattern maxVersionPattern = Pattern.compile(".*To be removed (in|after) \\d+\\.\\d+\\.(\\d+|x).*");
+            incubatingMaxVersion = endppointTags.stream()
+                    .filter(t -> {
+                        Matcher matcher = maxVersionPattern.matcher(t);
+                        return matcher.matches();
+                    })
+                    .findFirst()
+                    .map(t -> "@Incubating " + t);
+        }
+        return incubatingMaxVersion;
+    }
+
     private Javadoc() {}
 }

conjure-java-core/src/test/java/com/palantir/conjure/java/ServiceGeneratorTests.java

@@ -0,0 +1,60 @@
+/*
+ * (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.conjure.java;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.util.concurrent.MoreExecutors;
+import com.palantir.conjure.defs.Conjure;
+import com.palantir.conjure.java.services.JerseyServiceGenerator;
+import com.palantir.conjure.spec.ConjureDefinition;
+import java.io.File;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.api.parallel.Execution;
+import org.junit.jupiter.api.parallel.ExecutionMode;
+
+@Execution(ExecutionMode.CONCURRENT)
+public final class ServiceGeneratorTests extends TestBase {
+
+    @TempDir
+    public File folder;
+
+    private static String compiledFileContent(File srcDir, String clazz) throws IOException {
+        return new String(Files.readAllBytes(Paths.get(srcDir.getPath(), clazz)), StandardCharsets.UTF_8);
+    }
+
+    @Test
+    public void testConjureIncubatingJavadoc() throws IOException {
+        ConjureDefinition conjure =
+                Conjure.parse(ImmutableList.of(new File("src/test/resources/example-conjure-incubating.yml")));
+        File src = Files.createDirectory(folder.toPath().resolve("src")).toFile();
+        new GenerationCoordinator(
+                        MoreExecutors.directExecutor(), ImmutableSet.of(new JerseyServiceGenerator(Options.empty())))
+                .emit(conjure, src);
+
+        // Generated files contain imports
+        assertThat(compiledFileContent(src, "test/api/with/imports/IncubatingEndpoint.java"))
+                .contains("* @Incubating To be removed after 1.2.x.");
+    }
+}

conjure-java-core/src/test/resources/example-conjure-incubating.yml

@@ -0,0 +1,9 @@
+services:
+  IncubatingEndpoint:
+    name: Test Service
+    package: test.api.with.imports
+    base-path: /catalog
+    endpoints:
+      testIncubatingJavadoc:
+        http: GET /testIncubatingJavadoc
+        tags: ["To be removed after 1.2.x.", "incubating"]