/**

* 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;

import static com.google.common.base.Preconditions.checkArgument;

import static java.util.Objects.requireNonNull;

import java.lang.reflect.Method;

import java.util.ArrayList;

import java.util.Arrays;

import java.util.Collections;

import java.util.List;

import java.util.Map;

import java.util.Optional;

import org.jooby.internal.AssetProxy;

import org.jooby.internal.RouteImpl;

import org.jooby.internal.RouteMatcher;

import org.jooby.internal.RoutePattern;

import org.jooby.util.Collectors;

import com.google.common.base.Strings;

import com.google.common.collect.ImmutableList;

import com.google.common.collect.Lists;

/**

* Routes are a key concept in Jooby. Routes are executed in the same order they are defined

* (even for Mvc Routes).

*

* <h1>Handlers</h1>

* <p>

* There are two types of handlers: {@link Route.Handler} and {@link Route.Filter}. They behave very

* similar, except that a {@link Route.Filter} can decide if the next route handler can be executed

* or not. For example:

* </p>

*

* <pre>

* get("/filter", (req, rsp, chain) {@literal ->} {

* if (someCondition) {

* chain.next(req, rsp);

* } else {

* // respond, throw err, etc...

* }

* });

* </pre>

*

* While a {@link Route.Handler} always execute the next handler:

*

* <pre>

* get("/path", (req, rsp) {@literal ->} {

* rsp.send("handler");

* });

*

* // filter version

* get("/path", (req, rsp, chain) {@literal ->} {

* rsp.send("handler");

* chain.next(req, rsp);

* });

* </pre>

*

* <h1>Path Patterns</h1>

* <p>

* Jooby supports Ant-style path patterns:

* </p>

* <p>

* Some examples:

* </p>

* <ul>

* <li>{@code com/t?st.html} - matches {@code com/test.html} but also {@code com/tast.jsp} or

* {@code com/txst.html}</li>

* <li>{@code com/*.html} - matches all {@code .html} files in the {@code com} directory</li>

* <li><code>com/{@literal **}/test.html</code> - matches all {@code test.html} files underneath the

* {@code com} path</li>

* <li>{@code **}/{@code *} - matches any path at any level.</li>

* <li>{@code *} - matches any path at any level, shorthand for {@code **}/{@code *}.</li>

* </ul>

*

* <h2>Variables</h2>

* <p>

* Jooby supports path parameters too:

* </p>

* <p>

* Some examples:

* </p>

* <ul>

* <li><code> /user/{id}</code> - /user/* and give you access to the <code>id</code> var.</li>

* <li><code> /user/:id</code> - /user/* and give you access to the <code>id</code> var.</li>

* <li><code> /user/{id:\\d+}</code> - /user/[digits] and give you access to the numeric

* <code>id</code> var.</li>

* </ul>

*

* <h1>Routes</h1>

* <p>

* Routes are executed in the order they are defined, for example:

* </p>

*

* <pre>

* get("/", (req, rsp) {@literal ->} {

* log.info("first"); // start here and go to second

* });

*

* get("/", (req, rsp) {@literal ->} {

* log.info("second"); // execute after first and go to final

* });

*

* get("/", (req, rsp) {@literal ->} {

* rsp.send("final"); // done!

* });

* </pre>

*

* Please note first and second routes are converted to a filter, so previous example is the same

* as:

*

* <pre>

* get("/", (req, rsp, chain) {@literal ->} {

* log.info("first"); // start here and go to second

* chain.next(req, rsp);

* });

*

* get("/", (req, rsp, chain) {@literal ->} {

* log.info("second"); // execute after first and go to final

* chain.next(req, rsp);

* });

*

* get("/", (req, rsp) {@literal ->} {

* rsp.send("final"); // done!

* });

* </pre>

*

* <h2>Inline route</h2>

* <p>

* An inline route can be defined using Lambda expressions, like:

* </p>

*

* <pre>

* get("/", (request, response) {@literal ->} {

* response.send("Hello Jooby");

* });

* </pre>

*

* Due to the use of lambdas a route is a singleton and you should NOT use global variables.

* For example this is a bad practice:

*

* <pre>

* List{@literal <}String{@literal >} names = new ArrayList{@literal <>}(); // names produces side effects

* get("/", (req, rsp) {@literal ->} {

* names.add(req.param("name").value();

* // response will be different between calls.

* rsp.send(names);

* });

* </pre>

*

* <h2>Mvc Route</h2>

* <p>

* A Mvc Route use annotations to define routes:

* </p>

*

* <pre>

* {

* use(MyRoute.class);

* }

* </pre>

*

* MyRoute.java:

* <pre>

* {@literal @}Path("/")

* public class MyRoute {

*

* {@literal @}GET

* public String hello() {

* return "Hello Jooby";

* }

* }

* </pre>

* <p>

* Programming model is quite similar to JAX-RS/Jersey with some minor differences and/or

* simplifications.

* </p>

*

* <p>

* To learn more about Mvc Routes, please check {@link org.jooby.mvc.Path},

* {@link org.jooby.mvc.Produces} {@link org.jooby.mvc.Consumes}.

* </p>

*

* @author edgar

* @since 0.1.0

*/

public interface Route {

class Group {

/** List of definitions. */

private List<Route.Definition> routes = new ArrayList<>();

private String rootPattern;

private String prefix;

public Group(final String pattern, final String prefix) {

requireNonNull(pattern, "Pattern is required.");

this.rootPattern = pattern;

this.prefix = prefix;

}

public Group(final String pattern) {

this(pattern, null);

}

public List<Route.Definition> routes() {

return routes;

}

// ********************************************************************************************

// ALL

// ********************************************************************************************

public Group all(final String pattern, final Route.Filter filter) {

newRoute("*", pattern, filter);

return this;

}

public Group all(final String pattern, final Route.Handler handler) {

newRoute("*", pattern, handler);

return this;

}

public Group all(final String pattern, final Route.OneArgHandler handler) {

newRoute("*", pattern, handler);

return this;

}

public Group all(final String pattern, final Route.ZeroArgHandler handler) {

newRoute("*", pattern, handler);

return this;

}

public Group all(final Route.Filter filter) {

newRoute("*", "", filter);

return this;

}

public Group all(final Route.Handler handler) {

newRoute("*", "", handler);

return this;

}

public Group all(final Route.OneArgHandler handler) {

newRoute("*", "", handler);

return this;

}

public Group all(final Route.ZeroArgHandler handler) {

newRoute("*", "", handler);

return this;

}

// ********************************************************************************************

// GET

// ********************************************************************************************

public Group get(final String pattern, final Route.Filter filter) {

newRoute("GET", pattern, filter);

return this;

}

public Group get(final String pattern, final Route.Handler handler) {

newRoute("GET", pattern, handler);

return this;

}

public Group get(final String pattern, final Route.OneArgHandler handler) {

newRoute("GET", pattern, handler);

return this;

}

public Group get(final String pattern, final Route.ZeroArgHandler handler) {

newRoute("GET", pattern, handler);

return this;

}

public Group get(final Route.Filter filter) {

newRoute("GET", "", filter);

return this;

}

public Group get(final Route.Handler handler) {

newRoute("GET", "", handler);

return this;

}

public Group get(final Route.OneArgHandler handler) {

newRoute("GET", "", handler);

return this;

}

public Group get(final Route.ZeroArgHandler handler) {

newRoute("GET", "", handler);

return this;

}

// ********************************************************************************************

// POST

// ********************************************************************************************

public Group post(final String pattern, final Route.Filter filter) {

newRoute("POST", pattern, filter);

return this;

}

public Group post(final String pattern, final Route.Handler handler) {

newRoute("POST", pattern, handler);

return this;

}

public Group post(final String pattern, final Route.OneArgHandler handler) {

newRoute("POST", pattern, handler);

return this;

}

public Group post(final String pattern, final Route.ZeroArgHandler handler) {

newRoute("POST", pattern, handler);

return this;

}

public Group post(final Route.Filter filter) {

newRoute("POST", "", filter);

return this;

}

public Group post(final Route.Handler handler) {

newRoute("POST", "", handler);

return this;

}

public Group post(final Route.OneArgHandler handler) {

newRoute("POST", "", handler);

return this;

}

public Group post(final Route.ZeroArgHandler handler) {

newRoute("POST", "", handler);

return this;

}

// ********************************************************************************************

// PUT

// ********************************************************************************************

public Group put(final String pattern, final Route.Filter filter) {

newRoute("PUT", pattern, filter);

return this;

}

public Group put(final String pattern, final Route.Handler handler) {

newRoute("PUT", pattern, handler);

return this;

}

public Group put(final String pattern, final Route.OneArgHandler handler) {

newRoute("PUT", pattern, handler);

return this;

}

public Group put(final String pattern, final Route.ZeroArgHandler handler) {

newRoute("PUT", pattern, handler);

return this;

}

public Group put(final Route.Filter filter) {

newRoute("PUT", "", filter);

return this;

}

public Group put(final Route.Handler handler) {

newRoute("PUT", "", handler);

return this;

}

public Group put(final Route.OneArgHandler handler) {

newRoute("PUT", "", handler);

return this;

}

public Group put(final Route.ZeroArgHandler handler) {

newRoute("PUT", "", handler);

return this;

}

// ********************************************************************************************

// DELETE

// ********************************************************************************************

public Group delete(final String pattern, final Route.Filter filter) {

newRoute("DELETE", pattern, filter);

return this;

}

public Group delete(final String pattern, final Route.Handler handler) {

newRoute("DELETE", pattern, handler);

return this;

}

public Group delete(final String pattern, final Route.OneArgHandler handler) {

newRoute("DELETE", pattern, handler);

return this;

}

public Group delete(final String pattern, final Route.ZeroArgHandler handler) {

newRoute("DELETE", pattern, handler);

return this;

}

public Group delete(final Route.Filter filter) {

newRoute("DELETE", "", filter);

return this;

}

public Group delete(final Route.Handler handler) {

newRoute("DELETE", "", handler);

return this;

}

public Group delete(final Route.OneArgHandler handler) {

newRoute("DELETE", "", handler);

return this;

}

public Group delete(final Route.ZeroArgHandler handler) {

newRoute("DELETE", "", handler);

return this;

}

// ********************************************************************************************

// PATCH

// ********************************************************************************************

public Group patch(final String pattern, final Route.Filter filter) {

newRoute("PATCH", pattern, filter);

return this;

}

public Group patch(final String pattern, final Route.Handler handler) {

newRoute("PATCH", pattern, handler);

return this;

}

public Group patch(final String pattern, final Route.OneArgHandler handler) {

newRoute("PATCH", pattern, handler);

return this;

}

public Group patch(final String pattern, final Route.ZeroArgHandler handler) {

newRoute("PATCH", pattern, handler);

return this;

}

public Group patch(final Route.Filter filter) {

newRoute("PATCH", "", filter);

return this;

}

public Group patch(final Route.Handler handler) {

newRoute("PATCH", "", handler);

return this;

}

public Group patch(final Route.OneArgHandler handler) {

newRoute("PATCH", "", handler);

return this;

}

public Group patch(final Route.ZeroArgHandler handler) {

newRoute("PATCH", "", handler);

return this;

}

/**

* Set the route name to the whole collection.

*

* @param name Name to use/set.

* @return This instance.

*/

public Group name(final String name) {

for (Definition definition : routes) {

if (prefix != null) {

definition.name(prefix + "/" + name);

} else {

definition.name(name);

}

}

return this;

}

/**

* Set what a route can consumes.

*

* @param types Media types.

* @return This instance.

*/

public Group consumes(final MediaType... types) {

for (Definition definition : routes) {

definition.consumes(types);

}

return this;

}

/**

* Set what a route can consumes.

*

* @param types Media types.

* @return This instance.

*/

public Group consumes(final String... types) {

for (Definition definition : routes) {

definition.consumes(types);

}

return this;

}

/**

* Set what a route can produces.

*

* @param types Media types.

* @return This instance.

*/

public Group produces(final MediaType... types) {

for (Definition definition : routes) {

definition.produces(types);

}

return this;

}

/**

* Set what a route can produces.

*

* @param types Media types.

* @return This instance.

*/

public Group produces(final String... types) {

for (Definition definition : routes) {

definition.produces(types);

}

return this;

}

private void newRoute(final String method, final String pattern,

final Route.Filter filter) {

newRoute(new Route.Definition(method, this.rootPattern + pattern, filter));

}

private void newRoute(final String method, final String pattern,

final Route.Handler filter) {

newRoute(new Route.Definition(method, this.rootPattern + pattern, filter));

}

private void newRoute(final String method, final String pattern,

final Route.OneArgHandler filter) {

newRoute(new Route.Definition(method, this.rootPattern + pattern, filter));

}

private void newRoute(final String method, final String pattern,

final Route.ZeroArgHandler filter) {

newRoute(new Route.Definition(method, this.rootPattern + pattern, filter));

}

private void newRoute(final Route.Definition route) {

if (prefix != null) {

route.name(prefix);

}

routes.add(route);

}

};

/**

* Collection of {@link Route.Definition} useful for registering/setting route options at once.

*

* @author edgar

* @since 0.5.0

*/

class Collection {

/** List of definitions. */

private Route.Definition[] definitions;

/**

* Creates a new collection of route definitions.

*

* @param definitions Collection of route definitions.

*/

public Collection(final Route.Definition[] definitions) {

this.definitions = requireNonNull(definitions, "Route definitions are required.");

}

/**

* Set the route name to the whole collection.

*

* @param name Name to use/set.

* @return This instance.

*/

public Collection name(final String name) {

for (Definition definition : definitions) {

definition.name(name);

}

return this;

}

/**

* Set what a route can consumes.

*

* @param types Media types.

* @return This instance.

*/

public Collection consumes(final MediaType... types) {

for (Definition definition : definitions) {

definition.consumes(types);

}

return this;

}

/**

* Set what a route can consumes.

*

* @param types Media types.

* @return This instance.

*/

public Collection consumes(final String... types) {

for (Definition definition : definitions) {

definition.consumes(types);

}

return this;

}

/**

* Set what a route can produces.

*

* @param types Media types.

* @return This instance.

*/

public Collection produces(final MediaType... types) {

for (Definition definition : definitions) {

definition.produces(types);

}

return this;

}

/**

* Set what a route can produces.

*

* @param types Media types.

* @return This instance.

*/

public Collection produces(final String... types) {

for (Definition definition : definitions) {

definition.produces(types);

}

return this;

}

}

/**

* DSL for customize routes.

*

* <h1>Defining a new route</h1>

* <p>

* It's pretty straight forward:

* </p>

*

* <pre>

* public class MyApp extends Jooby {

* {

* get("/", (req, rsp) {@literal ->} rsp.send("GET"));

*

* post("/", (req, rsp) {@literal ->} rsp.send("POST"));

*

* put("/", (req, rsp) {@literal ->} rsp.send("PUT"));

*

* delete("/", (req, rsp) {@literal ->} rsp.status(Response.Status.NO_CONTENT));

* }

* }

* </pre>

*

* <h1>Setting what a route can consumes</h1>

*

* <pre>

* public class MyApp extends Jooby {

* {

* post("/", (req, resp) {@literal ->} resp.send("POST"))

* .consumes(MediaType.json);

* }

* }

* </pre>

*

* <h1>Setting what a route can produces</h1>

*

* <pre>

* public class MyApp extends Jooby {

* {

* post("/", (req, resp) {@literal ->} resp.send("POST"))

* .produces(MediaType.json);

* }

* }

* </pre>

*

* <h1>Adding a name</h1>

*

* <pre>

* public class MyApp extends Jooby {

* {

* post("/", (req, resp) {@literal ->} resp.send("POST"))

* .name("My Root");

* }

* }

* </pre>

*

* @author edgar

* @since 0.1.0

*/

class Definition {

/**

* Route's name.

*/

private String name = "/anonymous";

/**

* A route pattern.

*/

private RoutePattern compiledPattern;

/**

* The target route.

*/

private Filter filter;

/**

* Defines the media types that the methods of a resource class or can accept. Default is:

* {@code *}/{@code *}.

*/

private List<MediaType> consumes = MediaType.ALL;

/**

* Defines the media types that the methods of a resource class or can produces. Default is:

* {@code *}/{@code *}.

*/

private List<MediaType> produces = MediaType.ALL;

/**

* A HTTP verb or <code>*</code>.

*/

private String method;

/**

* A path pattern.

*/

private String pattern;

private List<RoutePattern> excludes = Collections.emptyList();

/**

* Creates a new route definition.

*

* @param verb A HTTP verb or <code>*</code>.

* @param pattern A path pattern.

* @param handler A route handler.

*/

public Definition(final String verb, final String pattern,

final Route.Handler handler) {

this(verb, pattern, (Route.Filter) handler);

}

/**

* Creates a new route definition.

*

* @param verb A HTTP verb or <code>*</code>.

* @param pattern A path pattern.

* @param handler A route handler.

*/

public Definition(final String verb, final String pattern,

final Route.OneArgHandler handler) {

this(verb, pattern, (Route.Filter) handler);

}

/**

* Creates a new route definition.

*

* @param verb A HTTP verb or <code>*</code>.

* @param pattern A path pattern.

* @param handler A route handler.

*/

public Definition(final String verb, final String pattern,

final Route.ZeroArgHandler handler) {

this(verb, pattern, (Route.Filter) handler);

}

/**

* Creates a new route definition.

*

* @param method A HTTP verb or <code>*</code>.

* @param pattern A path pattern.

* @param filter A callback to execute.

*/

public Definition(final String method, final String pattern,

final Filter filter) {

requireNonNull(pattern, "A route path is required.");

requireNonNull(filter, "A filter is required.");

this.method = method.toUpperCase();

this.compiledPattern = new RoutePattern(method, pattern);

// normalized pattern

this.pattern = compiledPattern.pattern();

this.filter = filter;

}

/**

* <h1>Path Patterns</h1>

* <p>

* Jooby supports Ant-style path patterns:

* </p>

* <p>

* Some examples:

* </p>

* <ul>

* <li>{@code com/t?st.html} - matches {@code com/test.html} but also {@code com/tast.jsp} or

* {@code com/txst.html}</li>

* <li>{@code com/*.html} - matches all {@code .html} files in the {@code com} directory</li>

* <li><code>com/{@literal **}/test.html</code> - matches all {@code test.html} files underneath

* the {@code com} path</li>

* <li>{@code **}/{@code *} - matches any path at any level.</li>

* <li>{@code *} - matches any path at any level, shorthand for {@code **}/{@code *}.</li>

* </ul>

*

* <h2>Variables</h2>

* <p>

* Jooby supports path parameters too:

* </p>

* <p>

* Some examples:

* </p>

* <ul>

* <li><code> /user/{id}</code> - /user/* and give you access to the <code>id</code> var.</li>

* <li><code> /user/:id</code> - /user/* and give you access to the <code>id</code> var.</li>

* <li><code> /user/{id:\\d+}</code> - /user/[digits] and give you access to the numeric

* <code>id</code> var.</li>

* </ul>

*

* @return A path pattern.

*/

public String pattern() {

return pattern;

}

/**

* @return List of path variables (if any).

*/

public List<String> vars() {

return compiledPattern.vars();

}

/**

* Test if the route matches the given verb, path, content type and accept header.

*

* @param verb A HTTP verb.

* @param path Current HTTP path.

* @param contentType The <code>Content-Type</code> header.

* @param accept The <code>Accept</code> header.

* @return A route or an empty optional.

*/

public Optional<Route> matches(final String verb,

final String path, final MediaType contentType,

final List<MediaType> accept) {

String fpath = verb.toUpperCase() + path;

if (excludes(fpath)) {

return Optional.empty();

}

RouteMatcher matcher = compiledPattern.matcher(fpath);

if (matcher.matches()) {

List<MediaType> result = MediaType.matcher(accept).filter(this.produces);

if (result.size() > 0 && canConsume(contentType)) {

// keep accept when */*

List<MediaType> produces = result.size() == 1 && result.get(0).name().equals("*/*")

? accept : this.produces;

return Optional.of(asRoute(verb, matcher, produces));

}

}

return Optional.empty();

}

/**

* @return HTTP method or <code>*</code>.

*/

public String method() {

return method;

}

/**

* @return Handler behind this route.

*/

public Route.Filter filter() {

return filter;

}

/**

* Route's name, helpful for debugging but also to implement dynamic and advanced routing. See

* {@link Route.Chain#next(String, Request, Response)}

*

* @return Route name. Default is: <code>anonymous</code>.

*/

public String name() {

return name;

}

/**

* Set the route name. Route's name, helpful for debugging but also to implement dynamic and

* advanced routing. See {@link Route.Chain#next(String, Request, Response)}

*

*

* @param name A route's name.

* @return This definition.

*/

public Definition name(final String name) {

checkArgument(!Strings.isNullOrEmpty(name), "A route's name is required.");

this.name = RoutePattern.normalize(name);

return this;

}

/**

* Test if the route definition can consume a media type.

*

* @param type A media type to test.

* @return True, if the route can consume the given media type.

*/

public boolean canConsume(final MediaType type) {

return MediaType.matcher(Arrays.asList(type)).matches(consumes);

}

/**

* Test if the route definition can consume a media type.

*

* @param type A media type to test.

* @return True, if the route can consume the given media type.

*/

public boolean canConsume(final String type) {

return MediaType.matcher(MediaType.valueOf(type)).matches(consumes);

}

/**

* Test if the route definition can consume a media type.

*

* @param types A media types to test.

* @return True, if the route can produces the given media type.

*/

public boolean canProduce(final List<MediaType> types) {

return MediaType.matcher(types).matches(produces);

}

/**

* Test if the route definition can consume a media type.

*

* @param types A media types to test.

* @return True, if the route can produces the given media type.

*/

public boolean canProduce(final MediaType... types) {

return canProduce(Arrays.asList(types));

}

/**

* Test if the route definition can consume a media type.

*

* @param types A media types to test.

* @return True, if the route can produces the given media type.

*/

public boolean canProduce(final String... types) {

return canProduce(MediaType.valueOf(types));

}

/**

* Set the media types the route can consume.

*

* @param consumes The media types to test for.

* @return This route definition.

*/

public Definition consumes(final MediaType... consumes) {

return consumes(Arrays.asList(consumes));

}

/**

* Set the media types the route can consume.

*

* @param consumes The media types to test for.