You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2018/04/24 01:24:12 UTC
[juneau] branch master updated: New RestResources class.
This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new f1346d5 New RestResources class.
f1346d5 is described below
commit f1346d51b007e03a40031dad7d795e1dd4e7e028
Author: JamesBognar <ja...@apache.org>
AuthorDate: Mon Apr 23 21:23:54 2018 -0400
New RestResources class.
---
.../examples/rest/DockerRegistryResource.java | 8 +-
.../examples/rest/MethodExampleResource.java | 16 ++--
.../examples/rest/PredefinedLabelsResource.java | 10 +--
.../examples/rest/petstore/PetStoreResource.java | 22 ++---
.../microservice/resources/DebugResource.java | 8 +-
.../juneau/rest/annotation/ResponseStatus.java | 96 ++++++++++++++++++++++
.../apache/juneau/rest/annotation/Responses.java | 12 ++-
.../apache/juneau/rest/annotation/RestMethod.java | 1 -
.../rest/helper/ChildResourceDescriptions.java | 2 +-
.../ResourceDescriptions.java} | 33 ++++----
10 files changed, 155 insertions(+), 53 deletions(-)
diff --git a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DockerRegistryResource.java b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DockerRegistryResource.java
index 90f8627..bd0a13b 100644
--- a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DockerRegistryResource.java
+++ b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DockerRegistryResource.java
@@ -75,10 +75,10 @@ public class DockerRegistryResource extends BasicRestServlet {
/** [GET /] - Show child resources. */
@RestMethod(name=GET, path="/")
- public ResourceDescription[] getChildren(RestRequest req) {
- return new ResourceDescription[] {
- new ResourceDescription("search", "Search Registry")
- };
+ public ResourceDescriptions getChildren(RestRequest req) {
+ return new ResourceDescriptions()
+ .append("search", "Search Registry")
+ ;
}
/**
diff --git a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/MethodExampleResource.java b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/MethodExampleResource.java
index 376e924..60fa7af 100644
--- a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/MethodExampleResource.java
+++ b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/MethodExampleResource.java
@@ -57,21 +57,21 @@ public class MethodExampleResource extends BasicRestServlet {
/** Example GET request that redirects to our example method */
@RestMethod(name=GET, path="/", summary="Top-level page")
- public ResourceDescription[] doExample() throws Exception {
- return new ResourceDescription[] {
- new ResourceDescription(
+ public ResourceDescriptions doExample() throws Exception {
+ return new ResourceDescriptions()
+ .append(
"example1/foo/123/"+SAMPLE_UUID+"/path-remainder?q1=456&q2=bar",
"Example 1 - Annotated method attributes."
- ),
- new ResourceDescription(
+ )
+ .append(
"example2/foo/123/"+SAMPLE_UUID+"/path-remainder?q1=456&q2=bar",
"Example 2 - Low-level RestRequest/RestResponse objects."
- ),
- new ResourceDescription(
+ )
+ .append(
"example3/foo/123/"+SAMPLE_UUID+"/path-remainder?q1=456&q2=bar",
"Example 3 - Intermediate-level APIs."
)
- };
+ ;
}
@RestMethod(
diff --git a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/PredefinedLabelsResource.java b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/PredefinedLabelsResource.java
index 630a978..829777c 100644
--- a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/PredefinedLabelsResource.java
+++ b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/PredefinedLabelsResource.java
@@ -53,11 +53,11 @@ public class PredefinedLabelsResource extends BasicRestServlet {
private static final long serialVersionUID = 1L;
@RestMethod(name=GET, path="/")
- public ResourceDescription[] getChildMethods() throws Exception {
- return new ResourceDescription[] {
- new ResourceDescription("beanDescription", "BeanDescription"),
- new ResourceDescription("htmlLinks", "HtmlLink")
- };
+ public ResourceDescriptions getChildMethods() throws Exception {
+ return new ResourceDescriptions()
+ .append("beanDescription", "BeanDescription")
+ .append("htmlLinks", "HtmlLink")
+ ;
}
@RestMethod(name=GET, path="/beanDescription")
diff --git a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
index 0c0773d..7aafeec 100644
--- a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
+++ b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
@@ -96,12 +96,12 @@ public class PetStoreResource extends BasicRestServletJena {
path="/",
summary="Navigation page"
)
- public ResourceDescription[] getTopPage() {
- return new ResourceDescription[] {
- new ResourceDescription("pet", "All pets in the store"),
- new ResourceDescription("store", "Orders and inventory"),
- new ResourceDescription("user", "Petstore users")
- };
+ public ResourceDescriptions getTopPage() {
+ return new ResourceDescriptions()
+ .append("pet", "All pets in the store")
+ .append("store", "Orders and inventory")
+ .append("user", "Petstore users")
+ ;
}
//-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
@@ -367,11 +367,11 @@ public class PetStoreResource extends BasicRestServletJena {
tags="store"
)
)
- public ResourceDescription[] getTopStorePage() {
- return new ResourceDescription[] {
- new ResourceDescription("store/order", "Petstore orders"),
- new ResourceDescription("store/inventory", "Petstore inventory")
- };
+ public ResourceDescriptions getTopStorePage() {
+ return new ResourceDescriptions()
+ .append("store/order", "Petstore orders")
+ .append("store/inventory", "Petstore inventory")
+ ;
}
@RestMethod(
diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DebugResource.java b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DebugResource.java
index c41ba77..7628582 100644
--- a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DebugResource.java
+++ b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DebugResource.java
@@ -49,10 +49,10 @@ public class DebugResource extends BasicRestServlet {
* @throws Exception
*/
@RestMethod(name=GET, path="/", description="Show contents of config file.")
- public ResourceDescription[] getChildren() throws Exception {
- return new ResourceDescription[] {
- new ResourceDescription("jetty/dump", "Jetty thread dump")
- };
+ public ResourceDescriptions getChildren() throws Exception {
+ return new ResourceDescriptions()
+ .append("jetty/dump", "Jetty thread dump")
+ ;
}
/**
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
index 6413740..b97ff9f 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
@@ -17,8 +17,81 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
+import org.apache.juneau.utils.*;
+
/**
* Annotation that can be applied to parameters and types to denote them as an HTTP response status.
+ *
+ * <p>
+ * This can only be applied to parameters and subclasses of the {@link Value} class with an {@link Integer} type.
+ * <br>The {@link Value} object is mean to be a place-holder for the set value.
+ *
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ * <jk>public void</jk> login(String username, String password,
+ * <ja>@ResponseStatus</ja>(code=401, description=<js>"Invalid user/pw"</js>) Value<Integer> status) {
+ * <jk>if</jk> (! isValid(username, password))
+ * status.set(401);
+ * }
+ * </p>
+ *
+ * <p>
+ * The {@link Responses @Responses} annotation can be used to represent multiple possible response types.
+ *
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ * <jk>public void</jk> login(String username, String password,
+ * <ja>@ResponseStatuses</ja>{
+ * <ja>@ResponseStatus</ja>(200)
+ * <ja>@ResponseStatus</ja>(code=401, description=<js>"Invalid user/pw"</js>)
+ * }
+ * Value<Integer> status) {
+ *
+ * <jk>if</jk> (! isValid(username, password))
+ * status.set(401);
+ * <jk>else</jk>
+ * status.set(200);
+ * }
+ * </p>
+ *
+ * <p>
+ * The other option is to apply this annotation to a subclass of {@link Value} which often leads to a cleaner
+ * REST method:
+ *
+ * <p class='bcode'>
+ * <ja>@ResponseStatuses</ja>{
+ * <ja>@ResponseStatus</ja>(200)
+ * <ja>@ResponseStatus</ja>(code=401, description=<js>"Invalid user/pw"</js>)
+ * }
+ * <jk>public class</jk> LoginStatus <jk>extends</jk> Value<Integer> {}
+ *
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ * <jk>public void</jk> login(String username, String password, LoginStatus status) {
+ * <jk>if</jk> (! isValid(username, password))
+ * status.set(401);
+ * <jk>else</jk>
+ * status.set(200);
+ * }
+ * </p>
+ *
+ * <p>
+ * The attributes on this annotation are used to populate the generated Swagger for the method.
+ * <br>In this case, the Swagger is populated with the following:
+ *
+ * <p class='bcode'>
+ * <js>'/user/login'</js>: {
+ * get: {
+ * responses: {
+ * 200: {
+ * description: <js>'OK'</js>
+ * },
+ * 401: {
+ * description: <js>'Invalid user/pw'</js>
+ * }
+ * }
+ * }
+ * }
+ * </p>
*/
@Documented
@Target({PARAMETER,TYPE})
@@ -31,7 +104,30 @@ public @interface ResponseStatus {
*/
int code() default 0;
+ /**
+ * A synonym to {@link #code()}.
+ *
+ * <p>
+ * Useful if you only want to specify a code only.
+ *
+ * <p class='bcode'>
+ * <ja>@ResponseStatus</ja>(200)
+ * </p>
+ */
int value() default 0;
+ /**
+ * Defines the swagger value <code>/paths/{path}/{method}/responses/{status-code}/description</code>.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format of the value is plain-text.
+ * <br>Multiple lines are concatenated with newlines.
+ * <li>
+ * Supports <a class="doclink" href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time and request-time variables</a>
+ * (e.g. <js>"$L{my.localized.variable}"</js>).
+ * </ul>
+ */
String[] description() default {};
}
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Responses.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Responses.java
index b8c7870..32056c4 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Responses.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Responses.java
@@ -17,11 +17,21 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
+/**
+ * Used to associate multiple {@link Response @Response} annotations to the same parameter or class.
+ *
+ * <p>
+ * Since Juneau currently prereq's Java 1.7, we cannot take advantage of annotation duplication support in Java 8.
+ * <br>This annotation overcomes that limitation.
+ */
@Documented
-@Target({TYPE})
+@Target({PARAMETER,TYPE})
@Retention(RUNTIME)
@Inherited
public @interface Responses {
+ /**
+ * Specifies one or more {@link Response @Response} annotations to apply to the same parameter or class.
+ */
Response[] value() default {};
}
\ No newline at end of file
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
index cae82b4..cc0f1ed 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
@@ -737,7 +737,6 @@ public @interface RestMethod {
String[] consumes() default {};
/**
- /**
* Provides swagger-specific metadata on this method.
*
* <p>
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/ChildResourceDescriptions.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/ChildResourceDescriptions.java
index d20e3ae..82261f3 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/ChildResourceDescriptions.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/ChildResourceDescriptions.java
@@ -27,7 +27,7 @@ import org.apache.juneau.rest.*;
* <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.PredefinedLabelBeans">Overview > juneau-rest-server > Predefined Label Beans</a>
* </ul>
*/
-public class ChildResourceDescriptions extends LinkedList<ResourceDescription> {
+public class ChildResourceDescriptions extends ResourceDescriptions {
private static final long serialVersionUID = 1L;
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/ResourceDescriptions.java
similarity index 72%
copy from juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
copy to juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/ResourceDescriptions.java
index 6413740..16aa52e 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/ResourceDescriptions.java
@@ -10,28 +10,25 @@
// * "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 org.apache.juneau.rest.annotation;
+package org.apache.juneau.rest.helper;
-import static java.lang.annotation.ElementType.*;
-import static java.lang.annotation.RetentionPolicy.*;
-
-import java.lang.annotation.*;
+import java.util.*;
/**
- * Annotation that can be applied to parameters and types to denote them as an HTTP response status.
+ * A list of {@link ResourceDescription} objects.
*/
-@Documented
-@Target({PARAMETER,TYPE})
-@Retention(RUNTIME)
-@Inherited
-public @interface ResponseStatus {
-
+public class ResourceDescriptions extends ArrayList<ResourceDescription> {
+ private static final long serialVersionUID = 1L;
+
/**
- * The HTTP status of the response.
+ * Adds a new {@link ResourceDescription} to this list.
+ *
+ * @param name The name of the child resource.
+ * @param description The description of the child resource.
+ * @return This object (for method chaining).
*/
- int code() default 0;
-
- int value() default 0;
-
- String[] description() default {};
+ public ResourceDescriptions append(String name, String description) {
+ super.add(new ResourceDescription(name, description));
+ return this;
+ }
}
--
To stop receiving notification emails like this one, please contact
jamesbognar@apache.org.