initial import

Signed-off-by: Rüdiger zu Dohna <snackbox@sinntr.eu>

proposals/problem-details/README.asciidoc

@@ -0,0 +1,48 @@
+//
+// Copyright (c) 2019 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// 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.
+//
+
+= Problem Details
+
+//The specification is here
+//TODO provide link the the spec html
+
+== About
+
+The proposed standard https://tools.ietf.org/html/rfc7807[RFC-7807] specifies an http response message entity (body) to convey the machine- and human-readable details about a problem with a request. In order to apply this standard to the Java world, exceptions on the server side have to be mapped to such a problem details; and/or problem detail responses have to trigger an exception on the client side containing the information provided in the message.
+
+The MicroProfile Problem Detail specification defines that compliant implementations:
+
+* Map exceptions thrown while processing an http request to valid problem detail documents.
+* What defaults to use for the various specified fields.
+* Consider the annotations defined in the API to override those details or add extension fields.
+* On the client side map problem detail http message entities back to appropriate standard or a (compatible) custom exceptions containing the fields and extensions.
+
+
+== Building
+
+Just enter `mvn` at the command line and maven will generate the following artifacts:
+
+API::
+A jar containing the api annotations, etc. in `/api/target`
+
+Specification::
+A PDF and HTML version of the specification document in `/spec/target/generated-docs/`
+
+TCK::
+A artifacts to test an implementation in `/tck/target`

proposals/problem-details/api/pom.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright (c) 2019 Contributors to the Eclipse Foundation
+  ~
+  ~ 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.
+  -->
+<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/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.microprofile.sandbox</groupId>
+        <artifactId>problem-details-parent</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <relativePath>..</relativePath>
+    </parent>
+
+    <artifactId>problem-details-api</artifactId>
+    <name>MicroProfile Problem Details :: API</name>
+    <description>Problem Details for MicroProfile :: API</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>javax.ws.rs</groupId>
+            <artifactId>javax.ws.rs-api</artifactId>
+            <version>2.1.1</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+</project>

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Constants.java

@@ -0,0 +1,31 @@
+package org.eclipse.microprofile.problemdetails;
+
+import javax.ws.rs.core.MediaType;
+
+public class Constants {
+    /**
+     * The JSON formatted details body of a failing http request.
+     *
+     * @see <a href="https://tools.ietf.org/html/rfc7807">RFC-7807</a>
+     */
+    public static final String PROBLEM_DETAIL_JSON = "application/problem+json";
+    /**
+     * The JSON formatted details body of a failing http request.
+     *
+     * @see <a href="https://tools.ietf.org/html/rfc7807">RFC-7807</a>
+     */
+    public static final MediaType PROBLEM_DETAIL_JSON_TYPE = MediaType.valueOf(PROBLEM_DETAIL_JSON);
+
+    /**
+     * The XML formatted details body of a failing http request.
+     *
+     * @see <a href="https://tools.ietf.org/html/rfc7807">RFC-7807</a>
+     */
+    public static final String PROBLEM_DETAIL_XML = "application/problem+xml";
+    /**
+     * The XML formatted details body of a failing http request.
+     *
+     * @see <a href="https://tools.ietf.org/html/rfc7807">RFC-7807</a>
+     */
+    public static final MediaType PROBLEM_DETAIL_XML_TYPE = MediaType.valueOf(PROBLEM_DETAIL_XML);
+}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Detail.java

@@ -0,0 +1,19 @@
+package org.eclipse.microprofile.problemdetails;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * The annotated methods or fields are used to build the <code>detail</code>
+ * field of the problem detail. Multiple details are joined to a single string
+ * delimited by `. `: a period and a space character.
+ * <p>
+ * Defaults to the message of the exception.
+ */
+@Retention(RUNTIME)
+@Target({METHOD, FIELD})
+public @interface Detail {}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Extension.java

@@ -0,0 +1,20 @@
+package org.eclipse.microprofile.problemdetails;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * The annotated methods or fields are used to build additional properties of the problem detail.
+ */
+@Retention(RUNTIME)
+@Target({METHOD, FIELD})
+public @interface Extension {
+    /**
+     * Defaults to the field/method name
+     */
+    String value() default "";
+}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Instance.java

@@ -0,0 +1,20 @@
+package org.eclipse.microprofile.problemdetails;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * The annotated method or field is used for the <code>instance</code> field of the problem detail.
+ * The behavior is undefined, if there are multiple fields/methods.
+ * Note that this value should be different for every occurrence.
+ * <p>
+ * By default, an <code>URN</code> with <code>urn:uuid:</code> and a random {@link java.util.UUID}
+ * is generated.
+ */
+@Retention(RUNTIME)
+@Target({METHOD, FIELD})
+public @interface Instance {}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/LogLevel.java

@@ -0,0 +1,10 @@
+package org.eclipse.microprofile.problemdetails;
+
+public enum LogLevel {
+    /**
+     * <code>DEBUG</code> for <code>4xx</code> and <code>ERROR</code> for <code>5xx</code> and anything else.
+     */
+    AUTO,
+
+    ERROR, WARNING, INFO, DEBUG, OFF
+}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Logging.java

@@ -0,0 +1,30 @@
+package org.eclipse.microprofile.problemdetails;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.PACKAGE;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static org.eclipse.microprofile.problemdetails.LogLevel.AUTO;
+
+/**
+ * Defines how problem details should be logged.
+ * <p>
+ * Can be applied to the package level, so all exceptions in the package are configured by default.
+ */
+@Retention(RUNTIME)
+@Target({TYPE, PACKAGE})
+public @interface Logging {
+
+    /**
+     * The category to log to. Defaults to the fully qualified class name of the exception.
+     */
+    String to() default "";
+
+    /**
+     * The level to log at. Defaults to <code>AUTO</code>, i.e. <code>DEBUG</code> for <code>4xx</code>
+     * and <code>ERROR</code> for <code>5xx</code>.
+     */
+    LogLevel at() default AUTO;
+}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Status.java

@@ -0,0 +1,19 @@
+package org.eclipse.microprofile.problemdetails;
+
+import javax.ws.rs.core.Response;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Defines the http status code to be used for the annotated exception.
+ * This will also be included as the <code>status</code> field of the
+ * problem detail.
+ */
+@Retention(RUNTIME)
+@Target(TYPE)
+public @interface Status {
+    Response.Status value();
+}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Title.java

@@ -0,0 +1,18 @@
+package org.eclipse.microprofile.problemdetails;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Defines the title string to be used for the annotated exception.
+ * The default is derived from the simple class name by splitting the
+ * camel case name into words.
+ */
+@Retention(RUNTIME)
+@Target(TYPE)
+public @interface Title {
+    String value();
+}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/Type.java

@@ -0,0 +1,17 @@
+package org.eclipse.microprofile.problemdetails;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Defines the type url to be used for the annotated exception.
+ * The default is a URN <code>urn:problem-type:[simple-class-name-with-dashes]</code>
+ */
+@Retention(RUNTIME)
+@Target(TYPE)
+public @interface Type {
+    String value();
+}

proposals/problem-details/api/src/main/java/org/eclipse/microprofile/problemdetails/package-info.java

@@ -0,0 +1,43 @@
+/*
+ *******************************************************************************
+ * Copyright (c) 2019 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.
+ *******************************************************************************/
+
+/**
+ * Annotations to override the default values for RFC-7807 problem detail fields, for example:
+ * <pre>
+ *{@literal @}Type("https://example.com/probs/out-of-credit")
+ *{@literal @}Title("You do not have enough credit.")
+ *{@literal @}Status(FORBIDDEN)
+ * public class OutOfCreditException extends RuntimeException {
+ *    {@literal @}Instance private URI instance;
+ *    {@literal @}Extension private int balance;
+ *     private int cost;
+ *    {@literal @}Extension private List<URI> accounts;
+ *
+ *    {@literal @}Detail public String getDetail() {
+ *         return "Your current balance is " + balance + ", but that costs " + cost + ".";
+ *     }
+ *
+ *     // ... constructors & getters
+ * }
+ * </pre>
+ *
+ * @since 1.0
+ */
+package org.eclipse.microprofile.problemdetails;