Merge pull request #1374 from Avalon-Lab/2.x

Provide Route attributes for MVC and Script API.

Author: jknack

docs/asciidoc/routing.adoc

@@ -61,6 +61,77 @@ A javadoc:Route[] consists of three part:
 The javadoc:Route.Handler[text="handler"] function always produces a result, which is send it back
 to the client.
 
+==== Route attributes
+
+Attributes let you annotate a route at application bootstrap time. It functions like static metadata available at runtime:
+.Java
+[source, java, role="primary"]
+----
+{
+  get("/foo", ctx -> "Foo")
+    .attribute("foo", "bar");
+}
+----
+An attribute consist of a name and value. Values can be any object.
+Attributes can be accessed at runtime in a request/response cycle. For example, a security module might check for a role attribute.
+.Java
+[source, java, role="primary"]
+----
+{
+  decorator(next -> ctx -> {
+    User user = ...;
+    String role = ctx.getRoute().attribute("Role"); 
+    
+    if (user.hasRole(role)) {
+        return next.apply(ctx);
+    }      
+    
+    throw new StatusCodeException(StatusCode.FORBIDDEN);                              
+  });
+}
+----
+
+In MVC routes you can set attributes via annotations:
+.Java
+[source, java, role="primary"]
+----
+@Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Role {
+  String value();
+}
+
+@Path("/path")
+public class AdminResource {
+
+  @Role("admin")
+  public Object doSomething() {
+    ...
+  }
+
+}
+
+{
+  decorator(next -> ctx -> {
+    System.out.println(ctx.getRoute().attribute("Role"))
+  });
+}
+----
+The previous example will print: admin.
+You can retrieve all the attributes of the route by calling `ctx.getRoute().getAttributes()`.
+
+Any runtime annotation is automatically added as route attributes following these rules:
+- If the annotation has a value method, then we use the annotation’s name as the attribute name.
+- Otherwise, we use the method name as the attribute name.
+
+.request attributes vs route attributes
+[NOTE]
+====
+Route attributes are created at bootstrap. They are global, and once set, they won’t change.
+On the other hand, request attributes are created in a request/response cycle.
+====
+
+
 === Path Pattern
 
 ==== Static

jooby/src/main/java/io/jooby/Route.java

@@ -11,14 +11,16 @@
 import javax.annotation.Nullable;
 import java.io.Serializable;
 import java.lang.reflect.Type;
-import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.Set;
 import java.util.HashSet;
-import java.util.List;
 import java.util.Map;
-import java.util.Set;
+import java.util.HashMap;
+import java.util.List;
+import java.util.ArrayList;
+import java.util.Arrays;
+
 
 /**
  * Route contains information about the HTTP method, path pattern, which content types consumes and
@@ -334,6 +336,8 @@ public interface Handler extends Serializable {
 
   private List<MediaType> consumes = EMPTY_LIST;
 
+  private Map<String, Object> attributes = EMPTY_MAP;
+
   private Set<String> supportedMethod;
 
   /**
@@ -618,6 +622,58 @@ public Route(@Nonnull String method, @Nonnull String pattern, @Nonnull Handler h
     return this;
   }
 
+  /**
+   * Attributes set to this route.
+   *
+   * @return Map of attributes set to the route.
+   */
+  public @Nonnull Map<String, Object> getAttributes() {
+    return attributes;
+  }
+
+  /**
+   * Retrieve value of this specific Attribute set to this route.
+   *
+   * @param name of the attribute to retrieve.
+   * @return value of the specific attribute.
+   */
+  public Object attribute(String name) {
+    return attributes.get(name);
+  }
+
+  /**
+   * Add one or more attributes applied to this route.
+   *
+   * @param attributes .
+   * @return This route.
+   */
+  public @Nonnull Route setAttributes(@Nonnull Map<String, Object> attributes) {
+    if (attributes.size() > 0) {
+      if (this.attributes == EMPTY_MAP) {
+        this.attributes = new HashMap<>();
+      }
+      this.attributes.putAll(attributes);
+    }
+    return this;
+  }
+
+  /**
+   * Add one or more attributes applied to this route.
+   *
+   * @param name attribute name
+   * @param value attribute value
+   * @return This route.
+   */
+  public @Nonnull Route attribute(@Nonnull String name, @Nonnull Object value) {
+    if (this.attributes == EMPTY_MAP) {
+      this.attributes = new HashMap<>();
+    }
+
+    this.attributes.put(name, value);
+
+    return this;
+  }
+
   /**
    * MessageDecoder for given media type.
    *

jooby/src/main/java/io/jooby/internal/RouterImpl.java

@@ -38,6 +38,7 @@
 import javax.annotation.Nonnull;
 import javax.inject.Provider;
 import java.io.FileNotFoundException;
+import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;
 import java.lang.reflect.Modifier;
 import java.nio.file.Path;
@@ -592,6 +593,11 @@ private void mvc(String prefix, Class type, Provider provider) {
       if (consumes.size() > 0) {
         route.setConsumes(consumes);
       }
+
+      Map<String, Object> attributes = model.getAttributes();
+      if (attributes.size() > 0) {
+        route.setAttributes(attributes);
+      }
     });
   }
 

jooby/src/main/java/io/jooby/internal/mvc/JaxrsAnnotationParser.java

@@ -44,7 +44,7 @@ public class JaxrsAnnotationParser extends MvcAnnotationParserBase {
   @Override protected MvcAnnotation create(Method method, Annotation annotation) {
     MvcAnnotation result = new MvcAnnotation(annotation.annotationType().getSimpleName(),
         path(method),
-        produces(method), consumes(method));
+        produces(method), consumes(method), attributes(method));
     result.setCookieParam(CookieParam.class);
     result.setHeaderParam(HeaderParam.class);
     result.setPathParam(PathParam.class);

jooby/src/main/java/io/jooby/internal/mvc/JoobyAnnotationParser.java

@@ -45,8 +45,8 @@ public class JoobyAnnotationParser extends MvcAnnotationParserBase {
 
   @Override protected MvcAnnotation create(Method method, Annotation annotation) {
     MvcAnnotation result = new MvcAnnotation(annotation.annotationType().getSimpleName(),
-        path(method, annotation),
-        produces(annotation), consumes(annotation));
+        path(method, annotation), produces(annotation),
+        consumes(annotation), attributes(method));
     result.setCookieParam(CookieParam.class);
     result.setHeaderParam(HeaderParam.class);
     result.setPathParam(PathParam.class);

jooby/src/main/java/io/jooby/internal/mvc/MvcAnnotation.java

@@ -12,6 +12,7 @@
 import java.lang.reflect.Parameter;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -24,6 +25,8 @@ public class MvcAnnotation {
 
   private List<MediaType> consumes;
 
+  private Map<String, Object> attributes;
+
   private Class<? extends Annotation> headerParam;
 
   private Class<? extends Annotation> cookieParam;
@@ -36,11 +39,12 @@ public class MvcAnnotation {
 
   private Class<? extends Annotation> flashParam;
 
-  public MvcAnnotation(String method, String[] path, String[] produces, String[] consumes) {
+  public MvcAnnotation(String method, String[] path, String[] produces, String[] consumes, Map<String, Object> attributes) {
     this.method = method;
     this.path = path;
     this.produces = types(produces);
     this.consumes = types(consumes);
+    this.attributes = attributes;
   }
 
   private List<MediaType> types(String[] values) {
@@ -68,6 +72,10 @@ public List<MediaType> getConsumes() {
     return consumes;
   }
 
+  public Map<String, Object> getAttributes() {
+    return attributes;
+  }
+
   public boolean isPathParam(Parameter parameter) {
     return parameter.getAnnotation(pathParam) != null;
   }
@@ -134,4 +142,5 @@ public String getName(Parameter parameter) {
       throw SneakyThrows.propagate(x);
     }
   }
+
 }

jooby/src/main/java/io/jooby/internal/mvc/MvcAnnotationParserBase.java

@@ -5,10 +5,16 @@
  */
 package io.jooby.internal.mvc;
 
+import io.jooby.SneakyThrows;
+
 import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
+import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 public abstract class MvcAnnotationParserBase implements MvcAnnotationParser {
 
@@ -50,4 +56,45 @@ protected String[] merge(String[] parent, String[] path) {
     }
     return result;
   }
+
+  protected Map<String, Object> attributes(Method method) {
+    Map<String, Object> attributes = new LinkedHashMap<>();
+
+    List<Annotation> specificAttributes = Stream.of(method.getDeclaredAnnotations())
+        .filter(annotation ->
+            !"io.jooby.annotations".equals(annotation.annotationType().getPackage().getName())
+                && !"javax.ws.rs".equals(annotation.annotationType().getPackage().getName()))
+        .collect(Collectors.toList());
+
+      specificAttributes.forEach(annotation -> attributes.putAll(extractAttributes(annotation)));
+
+      return attributes;
+  }
+
+  protected Map<String, Object> extractAttributes(Annotation annotation) {
+    Map<String, Object> annotationAttributes = new LinkedHashMap<>();
+
+    Method[] attributesMethod = annotation.annotationType().getDeclaredMethods();
+    for (Method attribute : attributesMethod) {
+      try {
+        Object value = attribute.invoke(annotation);
+        annotationAttributes.put(attributeName(attribute, annotation), value);
+      } catch (Exception x) {
+        throw SneakyThrows.propagate(x);
+      }
+    }
+
+    return annotationAttributes;
+  }
+
+  protected String attributeName(Method attr, Annotation annotation) {
+    String name = attr.getName();
+    String context = annotation.annotationType().getSimpleName();
+
+    if (name.equals("value")) {
+      return context;
+    }
+
+    return context + "." + name;
+  }
 }

tests/src/test/java/examples/MvcAttributes.java

@@ -0,0 +1,22 @@
+package examples;
+
+import io.jooby.annotations.GET;
+import io.jooby.annotations.Path;
+
+@Path("/attr")
+public class MvcAttributes {
+
+  @GET
+  @Path("/secured/subpath")
+  @Role(value = "Admin", level = "two")
+  public String subpath() {
+    return "Got it!!";
+  }
+
+  @GET
+  @Path("/secured/otherpath")
+  @Role("User")
+  public String otherpath() {
+    return "OK!";
+  }
+}

tests/src/test/java/examples/Role.java

@@ -0,0 +1,14 @@
+package examples;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface Role {
+  String value();
+
+  String level() default "one";
+}