Merge pull request #59 from zalando/feature/api-guardian

Annotated public API with @API

jackson-datatype-problem/pom.xml

@@ -26,6 +26,11 @@
     </properties>
 
     <dependencies>
+        <dependency>
+            <groupId>org.apiguardian</groupId>
+            <artifactId>apiguardian-api</artifactId>
+            <version>1.0.0</version>
+        </dependency>
         <dependency>
             <groupId>com.google.code.findbugs</groupId>
             <artifactId>jsr305</artifactId>

jackson-datatype-problem/src/main/java/org/zalando/problem/ProblemModule.java

@@ -4,10 +4,14 @@
 import com.fasterxml.jackson.core.util.VersionUtil;
 import com.fasterxml.jackson.databind.Module;
 import com.fasterxml.jackson.databind.module.SimpleModule;
+import org.apiguardian.api.API;
 
 import java.util.HashMap;
 import java.util.Map;
 
+import static org.apiguardian.api.API.Status.STABLE;
+
+@API(status = STABLE)
 public final class ProblemModule extends Module {
 
     private final boolean stackTraces;

problem/pom.xml

@@ -22,6 +22,11 @@
     </scm>
 
     <dependencies>
+        <dependency>
+            <groupId>org.apiguardian</groupId>
+            <artifactId>apiguardian-api</artifactId>
+            <version>1.0.0</version>
+        </dependency>
         <dependency>
             <groupId>com.google.code.findbugs</groupId>
             <artifactId>jsr305</artifactId>

problem/src/main/java/org/zalando/problem/AbstractThrowableProblem.java

@@ -2,6 +2,7 @@
 
 import com.google.gag.annotation.remark.Hack;
 import com.google.gag.annotation.remark.OhNoYouDidnt;
+import org.apiguardian.api.API;
 
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
@@ -11,6 +12,10 @@
 import java.util.Map;
 import java.util.Optional;
 
+import static org.apiguardian.api.API.Status.INTERNAL;
+import static org.apiguardian.api.API.Status.STABLE;
+
+@API(status = STABLE)
 @Immutable // TODO kind of a lie until we remove set(String, Object)
 public abstract class AbstractThrowableProblem extends ThrowableProblem {
 
@@ -118,6 +123,7 @@ public Map<String, Object> getParameters() {
      * @param value the custom value
      * @see <a href="https://github.com/FasterXML/jackson-databind/issues/562">Jackson Issue 562</a>
      */
+    @API(status = INTERNAL)
     @Hack
     @OhNoYouDidnt
     void set(final String key, final Object value) {

problem/src/main/java/org/zalando/problem/DefaultProblem.java

@@ -1,9 +1,14 @@
 package org.zalando.problem;
 
+import org.apiguardian.api.API;
+
 import javax.annotation.Nullable;
 import java.net.URI;
 import java.util.Map;
 
+import static org.apiguardian.api.API.Status.STABLE;
+
+@API(status = STABLE)
 public final class DefaultProblem extends AbstractThrowableProblem {
 
     // TODO needed for jackson

problem/src/main/java/org/zalando/problem/Exceptional.java

@@ -1,5 +1,9 @@
 package org.zalando.problem;
 
+import org.apiguardian.api.API;
+
+import static org.apiguardian.api.API.Status.STABLE;
+
 /**
  * An extension of the {@link Problem} interface for problems that extend {@link Exception}. Since {@link Exception}
  * is a concrete type any class can only extend one exception type. {@link ThrowableProblem} is one choice, but we
@@ -14,6 +18,7 @@
  * @see Problem
  * @see ThrowableProblem
  */
+@API(status = STABLE)
 public interface Exceptional extends Problem {
 
     Exceptional getCause();

problem/src/main/java/org/zalando/problem/Problem.java

@@ -1,5 +1,7 @@
 package org.zalando.problem;
 
+import org.apiguardian.api.API;
+
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 import java.net.URI;
@@ -9,10 +11,12 @@
 import java.util.stream.Stream;
 
 import static java.util.stream.Collectors.joining;
+import static org.apiguardian.api.API.Status.STABLE;
 
 /**
  * @see <a href="https://tools.ietf.org/html/rfc7807">RFC 7807: Problem Details for HTTP APIs</a>
  */
+@API(status = STABLE)
 @Immutable
 public interface Problem {
 

problem/src/main/java/org/zalando/problem/ProblemBuilder.java

@@ -1,5 +1,7 @@
 package org.zalando.problem;
 
+import org.apiguardian.api.API;
+
 import javax.annotation.Nullable;
 import java.net.URI;
 import java.util.Arrays;
@@ -8,6 +10,9 @@
 import java.util.Map;
 import java.util.Set;
 
+import static org.apiguardian.api.API.Status.STABLE;
+
+@API(status = STABLE)
 public final class ProblemBuilder {
 
     private static final Set<String> RESERVED_PROPERTIES = new HashSet<>(Arrays.asList(

problem/src/main/java/org/zalando/problem/Status.java

@@ -1,13 +1,17 @@
 package org.zalando.problem;
 
-import javax.annotation.Nullable;
+import org.apiguardian.api.API;
+
+import static org.apiguardian.api.API.Status.MAINTAINED;
+import static org.apiguardian.api.API.Status.STABLE;
 
 /**
  * Commonly used status codes defined by HTTP, see
  * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10">HTTP/1.1 documentation</a>
  * for the complete list. Additional status codes can be added by applications
  * by creating an implementation of StatusType.
  */
+@API(status = MAINTAINED)
 public enum Status implements StatusType {
 
     /**

problem/src/main/java/org/zalando/problem/StatusType.java

@@ -1,9 +1,14 @@
 package org.zalando.problem;
 
 
+import org.apiguardian.api.API;
+
+import static org.apiguardian.api.API.Status.STABLE;
+
 /**
  * Base interface for statuses.
  */
+@API(status = STABLE)
 public interface StatusType {
 
     /**

problem/src/main/java/org/zalando/problem/ThrowableProblem.java

@@ -1,5 +1,7 @@
 package org.zalando.problem;
 
+import org.apiguardian.api.API;
+
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 import java.util.Collection;
@@ -8,8 +10,10 @@
 
 import static java.util.Arrays.asList;
 import static java.util.stream.Collectors.joining;
+import static org.apiguardian.api.API.Status.STABLE;
 import static org.zalando.problem.spi.StackTraceProcessor.COMPOUND;
 
+@API(status = STABLE)
 @Immutable
 public abstract class ThrowableProblem extends RuntimeException implements Problem, Exceptional {