better doc for route props and mapper

Author: jknack

coverage-report/src/test/java/org/jooby/issues/Issue349.java

@@ -39,6 +39,13 @@ public void ignored() {
         .get("/a", () -> "a")
         .map(v -> "//" + v);
 
+    with(() -> {
+
+      get("/double", () -> 2);
+
+      get("/str", req -> "str");
+    }).map((final Integer v) -> v * 2);
+
   }
 
   @Test
@@ -63,7 +70,14 @@ public void mapper() throws Exception {
 
     request().get("/mvc/void")
         .expect(204);
-
   }
 
+  @Test
+  public void applyIntMapper() throws Exception {
+    request().get("/double")
+        .expect("4");
+
+    request().get("/str")
+        .expect("str");
+  }
 }

jooby/src/main/java/org/jooby/Route.java

@@ -214,7 +214,74 @@
  */
 public interface Route {
 
+  /**
+   * The map operator converts a route output to something else
+   *
+   * <pre>{@code
+   * {
+   *   // we got bar.. not foo
+   *   get("/foo", () -> "foo")
+   *       .map(value -> "bar");
+   *
+   *   // we got foo.. not bar
+   *   get("/bar", () -> "bar")
+   *       .map(value -> "foo");
+   * }
+   * }</pre>
+   *
+   * If you want to apply a single map to several routes:
+   *
+   * <pre>{@code
+   * {
+   *    with(() -> {
+   *      get("/foo", () -> "foo");
+   *
+   *      get("/bar", () -> "bar");
+   *
+   *    }).map(v -> "foo or bar");
+   * }
+   * }</pre>
+   *
+   * You can apply a {@link Mapper} to specific return type:
+   *
+   * <pre>{@code
+   * {
+   *    with(() -> {
+   *      get("/str", () -> "str");
+   *
+   *      get("/int", () -> 1);
+   *
+   *    }).map(String v -> "{" + v + "}");
+   * }
+   * }</pre>
+   *
+   * A call to <code>/str</code> produces <code>{str}</code>, while <code>/int</code> just
+   * <code>1</code>.
+   *
+   * <strong>NOTE</strong>: You can apply the map operator to routes that produces an output.
+   *
+   * For example, the map operator will be silently ignored here:
+   *
+   * <pre>{@code
+   * {
+   *    get("/", (req, rsp) -> {
+   *      rsp.send(...);
+   *    }).map(v -> ..);
+   * }
+   * }</pre>
+   *
+   * @author edgar
+   * @param <T> Type to map.
+   */
   interface Mapper<T> {
+
+    /**
+     * Map the type to something else.
+     *
+     * @param value Value to map.
+     * @return Mapped value.
+     * @throws Throwable If mapping fails.
+     */
     Object map(T value) throws Throwable;
   }
 

jooby/src/main/java/org/jooby/internal/MappedHandler.java

@@ -1,3 +1,21 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.jooby.internal;
 
 import static javaslang.API.Case;

md/route-attrs.md

@@ -1,6 +1,14 @@
-## attributes
+## properties
 
-It is possible to add metadata to routes via ```.attr(String, String)```:
+Routes have a few properties that let you extend basic functionality in one way or another including:
+
+* attributes
+* with, map and excludes operators
+* consumes/produces types.
+
+### attributes
+
+Attributes let you annotated a route at application bootstrap time. It is like static metadata available at runtime:
 
 ```java
 {
@@ -9,7 +17,9 @@ It is possible to add metadata to routes via ```.attr(String, String)```:
 }
 ```
 
-You can add as many attributes as you need. They can be accessed later and use it in one way or another. For example, a security module might looks for ```role``` attribute, a sitemap generator might like for ```priority``` attribute, etc...
+An attribute consist of a name and value. Allowed values are ```primitives```, ```String```, ```enum```, ```class``` or an ```array``` of previous types.
+
+Attributes can be accessed at runtime in a request/response cycle. For example, a security module might check for ```role``` attribute, a sitemap generator might check for ```priority``` attribute, etc...
 
 ```java
 {
@@ -25,7 +35,17 @@ You can add as many attributes as you need. They can be accessed later and use i
 }
 ```
 
-In MVC routes we use ```annotations``` to define route attributes:
+In MVC routes you can set attributes for all the web methods:
+
+```java
+{
+   use(Controller.class)
+     .attr("foo", "bar");
+}
+```
+
+
+Or via ```annotations```:
 
 ```java
 @Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
@@ -65,9 +85,81 @@ Any runtime annotations are automatically added as route attributes. Following t
 >
 > While, request attributes are created in a request/response cycle.
 
+### with operator
+
+The with operator set attributes, consumes and produces types, exclusions, etc.. to one or more routes:
+
+```java
+{
+  with(() -> {
+
+    get("/admin/1", ...);
+
+    get("/admin/2", ...);
+
+  }).attr("role", "admin");
+}
+```
+
+### map operator
+
+The map operator converts a route output to something else
+
+```java
+{
+  // we got bar.. not foo
+  get("/foo", () -> "foo")
+    .map(value -> "bar");
+
+  // we got foo.. not bar
+  get("/bar", () -> "bar")
+    .map(value -> "foo");
+}
+```
+
+If you want to apply a single map to several routes:
+
+```java
+{
+  with(() -> {
+    get("/foo", () -> "foo");
+
+    get("/bar", () -> "bar");
+
+  }).map(v -> "foo or bar");
+}
+```
+
+You can apply a [Mapper]({{defdocs}}/Route.Mapper.html) to specific types:
+
+```java
+{
+  with(() -> {
+    get("/str", () -> "str");
+
+    get("/int", () -> 1);
+
+  }).map(String v -> "{" + v + "}");
+}
+```
+
+A call to ```/str``` produces ```{str}```, while ```/int``` just ```1```.
+
+> **NOTE**: You can apply the map operator to routes that produces an output.
+
+For example, the map operator will be silently ignored here:
+
+```java
+{
+  get("/", (req, rsp) -> {
+    rsp.send(...);
+  });
+}
+```
+
 ### excludes
 
-The excludes attribute skip/ignore a route path match:
+The excludes operator skip/ignore a route path match:
 
 ```java
 {
@@ -77,18 +169,27 @@ The excludes attribute skip/ignore a route path match:
 }
 ```
 
-### with
+### consumes
 
-The with operator help to set common attributes, consumes and produces types, exclusions, etc.. to one or more routes:
+The consumes operator indicates the expected input the route can handle. It is used will accepting requests.
 
 ```java
 {
-  with(() -> {
+  post("/", req -> {
+    MyObject json = req.body().to(MyObject.class);
 
-    get("/admin/1", ...);
+  }).consumes("json");
+}
+```
 
-    get("/admin/2", ...);
+### produces
 
-  }).attr("role", "admin");
+The produces operator indicates the expected output the route can produces.
+
+```java
+{
+  get("/", req -> {
+    return new MyObject();
+  }).produces("json");
 }
 ```