org.jooby.Router Maven / Gradle / Ivy
/**
* Apache License
* Version 2.0, January 2004
* http://www.apache.org/licenses/
*
* TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
*
* 1. Definitions.
*
* "License" shall mean the terms and conditions for use, reproduction,
* and distribution as defined by Sections 1 through 9 of this document.
*
* "Licensor" shall mean the copyright owner or entity authorized by
* the copyright owner that is granting the License.
*
* "Legal Entity" shall mean the union of the acting entity and all
* other entities that control, are controlled by, or are under common
* control with that entity. For the purposes of this definition,
* "control" means (i) the power, direct or indirect, to cause the
* direction or management of such entity, whether by contract or
* otherwise, or (ii) ownership of fifty percent (50%) or more of the
* outstanding shares, or (iii) beneficial ownership of such entity.
*
* "You" (or "Your") shall mean an individual or Legal Entity
* exercising permissions granted by this License.
*
* "Source" form shall mean the preferred form for making modifications,
* including but not limited to software source code, documentation
* source, and configuration files.
*
* "Object" form shall mean any form resulting from mechanical
* transformation or translation of a Source form, including but
* not limited to compiled object code, generated documentation,
* and conversions to other media types.
*
* "Work" shall mean the work of authorship, whether in Source or
* Object form, made available under the License, as indicated by a
* copyright notice that is included in or attached to the work
* (an example is provided in the Appendix below).
*
* "Derivative Works" shall mean any work, whether in Source or Object
* form, that is based on (or derived from) the Work and for which the
* editorial revisions, annotations, elaborations, or other modifications
* represent, as a whole, an original work of authorship. For the purposes
* of this License, Derivative Works shall not include works that remain
* separable from, or merely link (or bind by name) to the interfaces of,
* the Work and Derivative Works thereof.
*
* "Contribution" shall mean any work of authorship, including
* the original version of the Work and any modifications or additions
* to that Work or Derivative Works thereof, that is intentionally
* submitted to Licensor for inclusion in the Work by the copyright owner
* or by an individual or Legal Entity authorized to submit on behalf of
* the copyright owner. For the purposes of this definition, "submitted"
* means any form of electronic, verbal, or written communication sent
* to the Licensor or its representatives, including but not limited to
* communication on electronic mailing lists, source code control systems,
* and issue tracking systems that are managed by, or on behalf of, the
* Licensor for the purpose of discussing and improving the Work, but
* excluding communication that is conspicuously marked or otherwise
* designated in writing by the copyright owner as "Not a Contribution."
*
* "Contributor" shall mean Licensor and any individual or Legal Entity
* on behalf of whom a Contribution has been received by Licensor and
* subsequently incorporated within the Work.
*
* 2. Grant of Copyright License. Subject to the terms and conditions of
* this License, each Contributor hereby grants to You a perpetual,
* worldwide, non-exclusive, no-charge, royalty-free, irrevocable
* copyright license to reproduce, prepare Derivative Works of,
* publicly display, publicly perform, sublicense, and distribute the
* Work and such Derivative Works in Source or Object form.
*
* 3. Grant of Patent License. Subject to the terms and conditions of
* this License, each Contributor hereby grants to You a perpetual,
* worldwide, non-exclusive, no-charge, royalty-free, irrevocable
* (except as stated in this section) patent license to make, have made,
* use, offer to sell, sell, import, and otherwise transfer the Work,
* where such license applies only to those patent claims licensable
* by such Contributor that are necessarily infringed by their
* Contribution(s) alone or by combination of their Contribution(s)
* with the Work to which such Contribution(s) was submitted. If You
* institute patent litigation against any entity (including a
* cross-claim or counterclaim in a lawsuit) alleging that the Work
* or a Contribution incorporated within the Work constitutes direct
* or contributory patent infringement, then any patent licenses
* granted to You under this License for that Work shall terminate
* as of the date such litigation is filed.
*
* 4. Redistribution. You may reproduce and distribute copies of the
* Work or Derivative Works thereof in any medium, with or without
* modifications, and in Source or Object form, provided that You
* meet the following conditions:
*
* (a) You must give any other recipients of the Work or
* Derivative Works a copy of this License; and
*
* (b) You must cause any modified files to carry prominent notices
* stating that You changed the files; and
*
* (c) You must retain, in the Source form of any Derivative Works
* that You distribute, all copyright, patent, trademark, and
* attribution notices from the Source form of the Work,
* excluding those notices that do not pertain to any part of
* the Derivative Works; and
*
* (d) If the Work includes a "NOTICE" text file as part of its
* distribution, then any Derivative Works that You distribute must
* include a readable copy of the attribution notices contained
* within such NOTICE file, excluding those notices that do not
* pertain to any part of the Derivative Works, in at least one
* of the following places: within a NOTICE text file distributed
* as part of the Derivative Works; within the Source form or
* documentation, if provided along with the Derivative Works; or,
* within a display generated by the Derivative Works, if and
* wherever such third-party notices normally appear. The contents
* of the NOTICE file are for informational purposes only and
* do not modify the License. You may add Your own attribution
* notices within Derivative Works that You distribute, alongside
* or as an addendum to the NOTICE text from the Work, provided
* that such additional attribution notices cannot be construed
* as modifying the License.
*
* You may add Your own copyright statement to Your modifications and
* may provide additional or different license terms and conditions
* for use, reproduction, or distribution of Your modifications, or
* for any such Derivative Works as a whole, provided Your use,
* reproduction, and distribution of the Work otherwise complies with
* the conditions stated in this License.
*
* 5. Submission of Contributions. Unless You explicitly state otherwise,
* any Contribution intentionally submitted for inclusion in the Work
* by You to the Licensor shall be under the terms and conditions of
* this License, without any additional terms or conditions.
* Notwithstanding the above, nothing herein shall supersede or modify
* the terms of any separate license agreement you may have executed
* with Licensor regarding such Contributions.
*
* 6. Trademarks. This License does not grant permission to use the trade
* names, trademarks, service marks, or product names of the Licensor,
* except as required for reasonable and customary use in describing the
* origin of the Work and reproducing the content of the NOTICE file.
*
* 7. Disclaimer of Warranty. Unless required by applicable law or
* agreed to in writing, Licensor provides the Work (and each
* Contributor provides its Contributions) on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
* implied, including, without limitation, any warranties or conditions
* of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
* PARTICULAR PURPOSE. You are solely responsible for determining the
* appropriateness of using or redistributing the Work and assume any
* risks associated with Your exercise of permissions under this License.
*
* 8. Limitation of Liability. In no event and under no legal theory,
* whether in tort (including negligence), contract, or otherwise,
* unless required by applicable law (such as deliberate and grossly
* negligent acts) or agreed to in writing, shall any Contributor be
* liable to You for damages, including any direct, indirect, special,
* incidental, or consequential damages of any character arising as a
* result of this License or out of the use or inability to use the
* Work (including but not limited to damages for loss of goodwill,
* work stoppage, computer failure or malfunction, or any and all
* other commercial damages or losses), even if such Contributor
* has been advised of the possibility of such damages.
*
* 9. Accepting Warranty or Additional Liability. While redistributing
* the Work or Derivative Works thereof, You may choose to offer,
* and charge a fee for, acceptance of support, warranty, indemnity,
* or other liability obligations and/or rights consistent with this
* License. However, in accepting such obligations, You may act only
* on Your own behalf and on Your sole responsibility, not on behalf
* of any other Contributor, and only if You agree to indemnify,
* defend, and hold each Contributor harmless for any liability
* incurred by, or claims asserted against, such Contributor by reason
* of your accepting any such warranty or additional liability.
*
* END OF TERMS AND CONDITIONS
*
* APPENDIX: How to apply the Apache License to your work.
*
* To apply the Apache License to your work, attach the following
* boilerplate notice, with the fields enclosed by brackets "{}"
* replaced with your own identifying information. (Don't include
* the brackets!) The text should be enclosed in the appropriate
* comment syntax for the file format. We also recommend that a
* file or class name and description of purpose be included on the
* same "printed page" as the copyright notice for easier
* identification within third-party archives.
*
* Copyright 2014 Edgar Espina
*
* 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.
*/
package org.jooby;
import org.jooby.Route.Mapper;
import org.jooby.funzy.Try;
import org.jooby.handlers.AssetHandler;
import javax.annotation.Nonnull;
import java.net.URLDecoder;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.Executor;
import java.util.function.Predicate;
/**
* Route DSL. Constructs and creates several flavors of jooby routes.
*
* @author edgar
* @since 0.16.0
*/
public interface Router {
/**
* Decode a path by delegating to {@link URLDecoder#decode(String, String)}.
*
* @param path Path to decoded.
* @return Decode a path by delegating to {@link URLDecoder#decode(String, String)}.
*/
static String decode(String path) {
return Try.apply(() -> URLDecoder.decode(path, "UTF-8")).get();
}
/**
* Import content from provide application (routes, parsers/renderers, start/stop callbacks, ...
* etc.).
*
* @param app Routes provider.
* @return This router.
*/
@Nonnull
Router use(final Jooby app);
/**
* Group one or more routes under a common path.
*
* {@code
* {
* path("/api/pets", () -> {
*
* });
* }
* }
*
* @param path Common path.
* @param action Router action.
* @return This router.
*/
Route.Collection path(String path, Runnable action);
/**
* Import content from provide application (routes, parsers/renderers, start/stop callbacks, ...
* etc.). Routes will be mounted at the provided path.
*
* @param path Path to mount the given app.
* @param app Routes provider.
* @return This router.
*/
@Nonnull
Router use(final String path, final Jooby app);
/**
* Define one or more routes under the same namespace:
*
*
* {
* use("/pets")
* .get("/:id", req {@literal ->} db.get(req.param("id").value()))
* .get(() {@literal ->} db.values());
* }
*
*
* @param pattern Global pattern to use.
* @return A route namespace.
* @deprecated Replaced by {@link #path(String, Runnable)}.
*/
@Nonnull
@Deprecated
Route.Group use(String pattern);
/**
* Append a new filter that matches any method under the given path.
*
* @param path A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition use(String path, Route.Filter filter);
/**
* Append a new filter that matches the given method and path.
*
* @param method A HTTP method.
* @param path A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition use(String method, String path, Route.Filter filter);
/**
* Append a new route handler that matches the given method and path. Like
* {@link #use(String, String, org.jooby.Route.Filter)} but you don't have to explicitly call
* {@link Route.Chain#next(Request, Response)}.
*
* @param method A HTTP method.
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition use(String method, String path, Route.Handler handler);
/**
* Append a new route handler that matches any method under the given path. Like
* {@link #use(String, org.jooby.Route.Filter)} but you don't have to explicitly call
* {@link Route.Chain#next(Request, Response)}.
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition use(String path, Route.Handler handler);
/**
* Append a new route handler that matches any method under the given path.
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition use(String path, Route.OneArgHandler handler);
/**
* Append a route that matches the HTTP GET method:
*
*
* get((req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition get(Route.Handler handler) {
return get("/", handler);
}
/**
* Append a route that matches the HTTP GET method:
*
*
* get("/", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition get(String path, Route.Handler handler);
/**
* Append two routes that matches the HTTP GET method on the same handler:
*
*
* get("/model", "/mode/:id", (req, rsp) {@literal ->} {
* rsp.send(req.param("id").toOptional(String.class));
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, Route.Handler handler);
/**
* Append three routes that matches the HTTP GET method on the same handler:
*
*
* get("/p1", "/p2", "/p3", (req, rsp) {@literal ->} {
* rsp.send(req.path());
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, String path3, Route.Handler handler);
/**
* Append route that matches the HTTP GET method:
*
*
* get(req {@literal ->} {
* return "hello";
* });
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition get(Route.OneArgHandler handler) {
return get("/", handler);
}
/**
* Append route that matches the HTTP GET method:
*
*
* get("/", req {@literal ->} {
* return "hello";
* });
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition get(String path, Route.OneArgHandler handler);
/**
* Append three routes that matches the HTTP GET method on the same handler:
*
*
* get("/model", "/model/:id", req {@literal ->} {
* return req.param("id").toOptional(String.class);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, Route.OneArgHandler handler);
/**
* Append three routes that matches the HTTP GET method on the same handler:
*
*
* get("/p1", "/p2", "/p3", req {@literal ->} {
* return req.path();
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, String path3, Route.OneArgHandler handler);
/**
* Append route that matches HTTP GET method:
*
*
* get(() {@literal ->}
* "hello"
* );
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition get(Route.ZeroArgHandler handler) {
return get("/", handler);
}
/**
* Append route that matches HTTP GET method:
*
*
* get("/", () {@literal ->}
* "hello"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition get(String path, Route.ZeroArgHandler handler);
/**
* Append three routes that matches the HTTP GET method on the same handler:
*
*
* get("/p1", "/p2", () {@literal ->} {
* return "OK";
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, Route.ZeroArgHandler handler);
/**
* Append three routes that matches HTTP GET method on the same handler:
*
*
* get("/p1", "/p2", "/p3", () {@literal ->} {
* return "OK";
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, String path3, Route.ZeroArgHandler handler);
/**
* Append a filter that matches HTTP GET method:
*
*
* get("/", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition get(String path, Route.Filter filter);
/**
* Append three routes that matches the HTTP GET method on the same handler:
*
*
* get("/model", "/model/:id", (req, rsp, chain) {@literal ->} {
* req.param("id").toOptional(String.class);
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, Route.Filter filter);
/**
* Append three routes that supports HTTP GET method on the same handler:
*
*
* get("/p1", "/p2", "/p3", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection get(String path1, String path2, String path3, Route.Filter filter);
/**
* Append a route that supports HTTP POST method:
*
*
* post((req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition post(Route.Handler handler) {
return post("/", handler);
}
/**
* Append a route that supports HTTP POST method:
*
*
* post("/", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition post(String path, Route.Handler handler);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2", (req, rsp) {@literal ->} {
* rsp.send(req.path());
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, Route.Handler handler);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2", "/p3", (req, rsp) {@literal ->} {
* rsp.send(req.path());
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, String path3, Route.Handler handler);
/**
* Append route that supports HTTP POST method:
*
*
* post(req {@literal ->}
* "hello"
* );
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition post(Route.OneArgHandler handler) {
return post("/", handler);
}
/**
* Append route that supports HTTP POST method:
*
*
* post("/", req {@literal ->}
* "hello"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition post(String path, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2", req {@literal ->} {
* return req.path();
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2", "/p3", req {@literal ->} {
* return req.path();
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, String path3, Route.OneArgHandler handler);
/**
* Append route that supports HTTP POST method:
*
*
* post(() {@literal ->}
* "hello"
* );
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition post(Route.ZeroArgHandler handler) {
return post("/", handler);
}
/**
* Append route that supports HTTP POST method:
*
*
* post("/", () {@literal ->}
* "hello"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition post(String path, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2", {@literal ->} {
* return "OK";
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2", "/p3", () {@literal ->} {
* return "OK";
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, String path3, Route.ZeroArgHandler handler);
/**
* Append a route that supports HTTP POST method:
*
*
* post("/", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition post(String path, Route.Filter filter);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2",(req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, Route.Filter filter);
/**
* Append three routes that supports HTTP POST method on the same handler:
*
*
* post("/p1", "/p2", "/p3", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection post(String path1, String path2, String path3, Route.Filter filter);
/**
* Append a route that supports HTTP HEAD method:
*
*
* post("/", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition head(String path, Route.Handler handler);
/**
* Append route that supports HTTP HEAD method:
*
*
* head("/", req {@literal ->}
* "hello"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition head(String path, Route.OneArgHandler handler);
/**
* Append route that supports HTTP HEAD method:
*
*
* head("/", () {@literal ->}
* "hello"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition head(String path, Route.ZeroArgHandler handler);
/**
* Append a route that supports HTTP HEAD method:
*
*
* post("/", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition head(String path, Route.Filter filter);
/**
* Append a new route that automatically handles HEAD request from existing GET routes.
*
*
* {
* head();
* }
*
*
* @return A new route definition.
*/
@Nonnull
Route.Definition head();
/**
* Append a route that supports HTTP OPTIONS method:
*
*
* options("/", (req, rsp) {@literal ->} {
* rsp.header("Allow", "GET, POST");
* });
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition options(String path, Route.Handler handler);
/**
* Append route that supports HTTP OPTIONS method:
*
*
* options("/", req {@literal ->}
* return Results.with(200).header("Allow", "GET, POST")
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition options(String path, Route.OneArgHandler handler);
/**
* Append route that supports HTTP OPTIONS method:
*
*
* options("/", () {@literal ->}
* return Results.with(200).header("Allow", "GET, POST")
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition options(String path, Route.ZeroArgHandler handler);
/**
* Append a route that supports HTTP OPTIONS method:
*
*
* options("/", (req, rsp, chain) {@literal ->} {
* rsp.header("Allow", "GET, POST");
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A callback to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition options(String path, Route.Filter filter);
/**
* Append a new route that automatically handles OPTIONS requests.
*
*
* get("/", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
* post("/", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
* options("/");
*
*
* OPTIONS / produces a response with a Allow header set to: GET, POST.
*
* @return A new route definition.
*/
@Nonnull
Route.Definition options();
/**
* Append route that supports HTTP PUT method:
*
*
* put((req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param handler A route to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition put(Route.Handler handler) {
return put("/", handler);
}
/**
* Append route that supports HTTP PUT method:
*
*
* put("/", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param path A path pattern.
* @param handler A route to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition put(String path, Route.Handler handler);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", (req, rsp) {@literal ->} {
* rsp.send(req.path());
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, Route.Handler handler);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", "/p3", (req, rsp) {@literal ->} {
* rsp.send(req.path());
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, String path3, Route.Handler handler);
/**
* Append route that supports HTTP PUT method:
*
*
* put(req {@literal ->}
* return Results.accepted();
* );
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition put(Route.OneArgHandler handler) {
return put("/", handler);
}
/**
* Append route that supports HTTP PUT method:
*
*
* put("/", req {@literal ->}
* return Results.accepted();
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition put(String path, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", req {@literal ->} {
* return req.path();
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", "/p3", req {@literal ->} {
* return req.path();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, String path3, Route.OneArgHandler handler);
/**
* Append route that supports HTTP PUT method:
*
*
* put(() {@literal ->} {
* return Results.accepted()
* });
*
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition put(Route.ZeroArgHandler handler) {
return put("/", handler);
}
/**
* Append route that supports HTTP PUT method:
*
*
* put("/", () {@literal ->} {
* return Results.accepted()
* });
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition put(String path, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", req {@literal ->} {
* return req.path();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", "/p3", req {@literal ->} {
* return req.path();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, String path3, Route.ZeroArgHandler handler);
/**
* Append route that supports HTTP PUT method:
*
*
* put("/", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A callback to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition put(String path, Route.Filter filter);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, Route.Filter filter);
/**
* Append three routes that supports HTTP PUT method on the same handler:
*
*
* put("/p1", "/p2", "/p3", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection put(String path1, String path2, String path3, Route.Filter filter);
/**
* Append route that supports HTTP PATCH method:
*
*
* patch((req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param handler A route to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition patch(Route.Handler handler) {
return patch("/", handler);
}
/**
* Append route that supports HTTP PATCH method:
*
*
* patch("/", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param path A path pattern.
* @param handler A route to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition patch(String path, Route.Handler handler);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection patch(String path1, String path2, Route.Handler handler);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", "/p3", (req, rsp) {@literal ->} {
* rsp.send(something);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
Route.Collection patch(String path1, String path2, String path3, Route.Handler handler);
/**
* Append route that supports HTTP PATCH method:
*
*
* patch(req {@literal ->}
* Results.ok()
* );
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition patch(Route.OneArgHandler handler) {
return patch("/", handler);
}
/**
* Append route that supports HTTP PATCH method:
*
*
* patch("/", req {@literal ->}
* Results.ok()
* );
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition patch(String path, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", req {@literal ->} {
* return req.path();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection patch(String path1, String path2, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", "/p3", req {@literal ->} {
* return req.path();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection patch(String path1, String path2, String path3, Route.OneArgHandler handler);
/**
* Append route that supports HTTP PATCH method:
*
*
* patch(() {@literal ->} {
* return Results.ok();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition patch(Route.ZeroArgHandler handler) {
return patch("/", handler);
}
/**
* Append route that supports HTTP PATCH method:
*
*
* patch("/", () {@literal ->} {
* return Results.ok();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition patch(String path, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", () {@literal ->} {
* return Results.ok();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection patch(String path1, String path2, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", "/p3", () {@literal ->} {
* return Results.ok();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection patch(String path1, String path2, String path3, Route.ZeroArgHandler handler);
/**
* Append route that supports HTTP PATCH method:
*
*
* patch("/", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A callback to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition patch(String path, Route.Filter filter);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection patch(String path1, String path2, Route.Filter filter);
/**
* Append three routes that supports HTTP PATCH method on the same handler:
*
*
* patch("/p1", "/p2", "/p3", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection patch(String path1, String path2, String path3, Route.Filter filter);
/**
* Append a route that supports HTTP DELETE method:
*
*
* delete((req, rsp) {@literal ->} {
* rsp.status(204);
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition delete(Route.Handler handler) {
return delete("/", handler);
}
/**
* Append a route that supports HTTP DELETE method:
*
*
* delete("/", (req, rsp) {@literal ->} {
* rsp.status(204);
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition delete(String path, Route.Handler handler);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", (req, rsp) {@literal ->} {
* rsp.status(204);
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, Route.Handler handler);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", "/p3", (req, rsp) {@literal ->} {
* rsp.status(204);
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, String path3, Route.Handler handler);
/**
* Append route that supports HTTP DELETE method:
*
*
* delete(req {@literal ->}
* return Results.noContent();
* );
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition delete(Route.OneArgHandler handler) {
return delete("/", handler);
}
/**
* Append route that supports HTTP DELETE method:
*
*
* delete("/", req {@literal ->}
* return Results.noContent();
* );
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition delete(String path, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", req {@literal ->} {
* return Results.noContent();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, Route.OneArgHandler handler);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", "/p3",req {@literal ->} {
* return Results.noContent();
* });
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, String path3, Route.OneArgHandler handler);
/**
* Append route that supports HTTP DELETE method:
*
*
* delete(() {@literal ->}
* return Results.noContent();
* );
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
default Route.Definition delete(Route.ZeroArgHandler handler) {
return delete("/", handler);
}
/**
* Append route that supports HTTP DELETE method:
*
*
* delete("/", () {@literal ->}
* return Results.noContent();
* );
*
*
* This is a singleton route so make sure you don't share or use global variables.
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition delete(String path, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", () {@literal ->} {
* return Results.noContent();
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, Route.ZeroArgHandler handler);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", "/p3", req {@literal ->} {
* return Results.noContent();
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, String path3, Route.ZeroArgHandler handler);
/**
* Append a route that supports HTTP DELETE method:
*
*
* delete("/", (req, rsp, chain) {@literal ->} {
* rsp.status(304);
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A callback to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition delete(String path, Route.Filter filter);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", (req, rsp, chain) {@literal ->} {
* rsp.status(304);
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, Route.Filter filter);
/**
* Append three routes that supports HTTP DELETE method on the same handler:
*
*
* delete("/p1", "/p2", "/p3", (req, rsp, chain) {@literal ->} {
* rsp.status(304);
* chain.next(req, rsp);
* });
*
*
* @param path1 A path pattern.
* @param path2 A path pattern.
* @param path3 A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Collection delete(String path1, String path2, String path3, Route.Filter filter);
/**
* Append a route that supports HTTP TRACE method:
*
*
* trace("/", (req, rsp) {@literal ->} {
* rsp.send(...);
* });
*
*
* @param path A path pattern.
* @param handler A callback to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition trace(String path, Route.Handler handler);
/**
* Append route that supports HTTP TRACE method:
*
*
* trace("/", req {@literal ->}
* "trace"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition trace(String path, Route.OneArgHandler handler);
/**
* Append route that supports HTTP TRACE method:
*
*
* trace("/", () {@literal ->}
* "trace"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition trace(String path, Route.ZeroArgHandler handler);
/**
* Append a route that supports HTTP TRACE method:
*
*
* trace("/", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A callback to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition trace(String path, Route.Filter filter);
/**
* Append a default trace implementation under the given path. Default trace response, looks
* like:
*
*
* TRACE /path
* header1: value
* header2: value
*
*
* @return A new route definition.
*/
@Nonnull
Route.Definition trace();
/**
* Append a route that supports HTTP CONNECT method:
*
*
* connect("/", (req, rsp) {@literal ->} {
* });
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition connect(String path, Route.Handler handler);
/**
* Append route that supports HTTP CONNECT method:
*
*
* connect("/", req {@literal ->}
* "hello"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition connect(String path, Route.OneArgHandler handler);
/**
* Append route that supports HTTP CONNECT method:
*
*
* connect("/", () {@literal ->}
* "connected"
* );
*
*
* @param path A path pattern.
* @param handler A handler to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition connect(String path, Route.ZeroArgHandler handler);
/**
* Append a route that supports HTTP CONNECT method:
*
*
* connect("/", (req, rsp, chain) {@literal ->} {
* chain.next(req, rsp);
* });
*
*
* @param path A path pattern.
* @param filter A filter to execute.
* @return A new route definition.
*/
@Nonnull
Route.Definition connect(String path, Route.Filter filter);
/**
* Static files handler.
*
*
* assets("/assets/**");
*
*
* Resources are served from root of classpath, for example GET /assets/file.js will
* be resolve as classpath resource at the same location.
*
* The {@link AssetHandler} one step forward and add support for serving files from a CDN out of
* the box. All you have to do is to define a assets.cdn property:
*
*
* assets.cdn = "http://d7471vfo50fqt.cloudfront.net"
*
*
* A GET to /assets/js/index.js will be redirected to:
* http://d7471vfo50fqt.cloudfront.net/assets/js/index.js.
*
* You can turn on/off ETag and Last-Modified headers too using
* assets.etag and assets.lastModified. These two properties are enabled
* by default.
*
* @param path The path to publish.
* @return A new route definition.
*/
@Nonnull
default Route.AssetDefinition assets(final String path) {
return assets(path, "/");
}
/**
* Static files handler on external location.
*
*
* assets("/assets/**", Paths.get("/www"));
*
*
* For example GET /assets/file.js will be resolve as /www/file.js on
* server file system.
*
*
* The {@link AssetHandler} one step forward and add support for serving files from a CDN out of
* the box. All you have to do is to define a assets.cdn property:
*
*
* assets.cdn = "http://d7471vfo50fqt.cloudfront.net"
*
*
* A GET to /assets/js/index.js will be redirected to:
* http://d7471vfo50fqt.cloudfront.net/assets/js/index.js.
*
* You can turn on/off ETag and Last-Modified headers too using
* assets.etag and assets.lastModified. These two properties are enabled
* by default.
*
* @param path The path to publish.
* @param basedir Base directory.
* @return A new route definition.
*/
@Nonnull
Route.AssetDefinition assets(final String path, Path basedir);
/**
* Static files handler. Like {@link #assets(String)} but let you specify a different classpath
* location.
*
*
* Basic example
*
*
*
* assets("/js/**", "/");
*
*
* A request for: /js/jquery.js will be translated to: /lib/jquery.js.
*
*
* Webjars example:
*
*
*
* assets("/js/**", "/resources/webjars/{0}");
*
*
* A request for: /js/jquery/2.1.3/jquery.js will be translated to:
* /resources/webjars/jquery/2.1.3/jquery.js.
* The {0} represent the ** capturing group.
*
*
* Another webjars example:
*
*
*
* assets("/js/*-*.js", "/resources/webjars/{0}/{1}/{0}.js");
*
*
*
* A request for: /js/jquery-2.1.3.js will be translated to:
* /resources/webjars/jquery/2.1.3/jquery.js.
*
*
* @param path The path to publish.
* @param location A resource location.
* @return A new route definition.
*/
@Nonnull
Route.AssetDefinition assets(String path, String location);
/**
* Send static files, like {@link #assets(String)} but let you specify a custom
* {@link AssetHandler}.
*
* @param path The path to publish.
* @param handler Asset handler.
* @return A new route definition.
*/
@Nonnull
Route.AssetDefinition assets(String path, AssetHandler handler);
/**
*
* Append MVC routes from a controller like class:
*
*
*
* use(MyRoute.class);
*
*
* Where MyRoute.java is:
*
*
* {@literal @}Path("/")
* public class MyRoute {
*
* {@literal @}GET
* public String hello() {
* return "Hello Jooby";
* }
* }
*
*
* Programming model is quite similar to JAX-RS/Jersey with some minor differences and/or
* simplifications.
*
*
*
* To learn more about Mvc Routes, please check {@link org.jooby.mvc.Path},
* {@link org.jooby.mvc.Produces} {@link org.jooby.mvc.Consumes}.
*
*
* @param routeClass A route(s) class.
* @return This router.
*/
@Nonnull
Route.Collection use(Class routeClass);
/**
*
* Append MVC routes from a controller like class:
*
*
*
* use("/pets", MyRoute.class);
*
*
* Where MyRoute.java is:
*
*
* {@literal @}Path("/")
* public class MyRoute {
*
* {@literal @}GET
* public String hello() {
* return "Hello Jooby";
* }
* }
*
*
* Programming model is quite similar to JAX-RS/Jersey with some minor differences and/or
* simplifications.
*
*
*
* To learn more about Mvc Routes, please check {@link org.jooby.mvc.Path},
* {@link org.jooby.mvc.Produces} {@link org.jooby.mvc.Consumes}.
*
*
* @param path Path to mount the route.
* @param routeClass A route(s) class.
* @return This router.
*/
@Nonnull
Route.Collection use(String path, Class routeClass);
/**
* before
*
* Allows for customized handler execution chains. It will be invoked before the actual handler.
*
* {@code
* {
* before((req, rsp) -> {
* // your code goes here
* });
* }
* }
*
* You are allowed to modify the request and response objects.
*
* Please note that the before handler is just syntax sugar for {@link Route.Filter}.
* For example, the before handler was implemented as:
*
* {@code
* {
* use("*", "*", (req, rsp, chain) -> {
* before(req, rsp);
* // your code goes here
* chain.next(req, rsp);
* });
* }
* }
*
* A before handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* before((req, rsp) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* // your code goes here
* return ...;
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param handler Before handler.
* @return A new route definition.
*/
@Nonnull
default Route.Definition before(final Route.Before handler) {
return before("*", handler);
}
/**
* before
*
* Allows for customized handler execution chains. It will be invoked before the actual handler.
*
* {@code
* {
* before((req, rsp) -> {
* // your code goes here
* });
* }
* }
*
* You are allowed to modify the request and response objects.
*
* Please note that the before handler is just syntax sugar for {@link Route.Filter}.
* For example, the before handler was implemented as:
*
* {@code
* {
* use("*", "*", (req, rsp, chain) -> {
* before(req, rsp);
* // your code goes here
* chain.next(req, rsp);
* });
* }
* }
*
* A before handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* before((req, rsp) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* // your code goes here
* return ...;
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param handler Before handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection before(final Route.Before handler, Route.Before... next) {
return before("*", handler, next);
}
/**
* before
*
* Allows for customized handler execution chains. It will be invoked before the actual handler.
*
* {@code
* {
* before("*", (req, rsp) -> {
* // your code goes here
* });
* }
* }
*
* You are allowed to modify the request and response objects.
*
* Please note that the before handler is just syntax sugar for {@link Route.Filter}.
* For example, the before handler was implemented as:
*
* {@code
* {
* use("*", (req, rsp, chain) -> {
* before(req, rsp);
* chain.next(req, rsp);
* });
* }
* }
*
* A before handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* before("/path", (req, rsp) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* // your code goes here
* return ...;
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param pattern Pattern to intercept.
* @param handler Before handler.
* @return A new route definition.
*/
@Nonnull
default Route.Definition before(final String pattern, final Route.Before handler) {
return before("*", pattern, handler);
}
/**
* before
*
* Allows for customized handler execution chains. It will be invoked before the actual handler.
*
* {@code
* {
* before("*", (req, rsp) -> {
* // your code goes here
* });
* }
* }
*
* You are allowed to modify the request and response objects.
*
* Please note that the before handler is just syntax sugar for {@link Route.Filter}.
* For example, the before handler was implemented as:
*
* {@code
* {
* use("*", (req, rsp, chain) -> {
* before(req, rsp);
* chain.next(req, rsp);
* });
* }
* }
*
* A before handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* before("/path", (req, rsp) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* // your code goes here
* return ...;
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param pattern Pattern to intercept.
* @param handler Before handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection before(String pattern, Route.Before handler, Route.Before... next) {
return before("*", pattern, handler, next);
}
/**
* before
*
* Allows for customized handler execution chains. It will be invoked before the actual handler.
*
* {@code
* {
* before("GET", "*", (req, rsp) -> {
* // your code goes here
* });
* }
* }
*
* You are allowed to modify the request and response objects.
*
* Please note that the before handler is just syntax sugar for {@link Route.Filter}.
* For example, the before handler was implemented as:
*
* {@code
* {
* use("GET", "*", (req, rsp, chain) -> {
* before(req, rsp);
* chain.next(req, rsp);
* });
* }
* }
*
* A before handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* before("GET", "/path", (req, rsp) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* // your code goes here
* return ...;
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param method HTTP method to intercept.
* @param pattern Pattern to intercept.
* @param handler Before handler.
* @return A new route definition.
*/
@Nonnull
Route.Definition before(String method, String pattern, Route.Before handler);
/**
* before
*
* Allows for customized handler execution chains. It will be invoked before the actual handler.
*
* {@code
* {
* before("GET", "*", (req, rsp) -> {
* // your code goes here
* });
* }
* }
*
* You are allowed to modify the request and response objects.
*
* Please note that the before handler is just syntax sugar for {@link Route.Filter}.
* For example, the before handler was implemented as:
*
* {@code
* {
* use("GET", "*", (req, rsp, chain) -> {
* before(req, rsp);
* chain.next(req, rsp);
* });
* }
* }
*
* A before handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* before("GET", "/path", (req, rsp) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* // your code goes here
* return ...;
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param method HTTP method to intercept.
* @param pattern Pattern to intercept.
* @param handler Before handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection before(String method, String pattern, Route.Before handler, Route.Before... next) {
List routes = new ArrayList<>();
routes.add(before(method, pattern, handler));
Arrays.asList(next).stream()
.map(h -> before(method, pattern, h))
.forEach(routes::add);
return new Route.Collection(routes.toArray(new Route.Definition[routes.size()]));
}
/**
* after
*
* Allows for customized response before sending it. It will be invoked at the time a response
* need
* to be send.
*
* {@code
* {
* after((req, rsp, result) -> {
* // your code goes here
* return result;
* });
* }
* }
*
* You are allowed to modify the request, response and result objects. The handler returns a
* {@link Result} which can be the same or an entirely new {@link Result}.
*
* A after handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* after((req, rsp, result) -> {
* // your code goes here
* return result;
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param handler After handler.
* @return A new route definition.
*/
@Nonnull
default Route.Definition after(Route.After handler) {
return after("*", handler);
}
/**
* after
*
* Allows for customized response before sending it. It will be invoked at the time a response
* need
* to be send.
*
* {@code
* {
* after((req, rsp, result) -> {
* // your code goes here
* return result;
* });
* }
* }
*
* You are allowed to modify the request, response and result objects. The handler returns a
* {@link Result} which can be the same or an entirely new {@link Result}.
*
* A after handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* after((req, rsp, result) -> {
* // your code goes here
* return result;
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param handler After handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection after(Route.After handler, Route.After... next) {
return after("*", handler, next);
}
/**
* after
*
* Allows for customized response before sending it. It will be invoked at the time a response
* need to be send.
*
* {@code
* {
* after("*", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
* }
* }
*
* You are allowed to modify the request, response and result objects. The handler returns a
* {@link Result} which can be the same or an entirely new {@link Result}.
*
* A after handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* after("/path", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param pattern Pattern to intercept.
* @param handler After handler.
* @return A new route definition.
*/
@Nonnull
default Route.Definition after(final String pattern, final Route.After handler) {
return after("*", pattern, handler);
}
/**
* after
*
* Allows for customized response before sending it. It will be invoked at the time a response
* need to be send.
*
* {@code
* {
* after("*", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
* }
* }
*
* You are allowed to modify the request, response and result objects. The handler returns a
* {@link Result} which can be the same or an entirely new {@link Result}.
*
* A after handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* after("/path", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param pattern Pattern to intercept.
* @param handler After handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection after(String pattern, Route.After handler, Route.After... next) {
return after("*", pattern, handler, next);
}
/**
* after
*
* Allows for customized response before sending it. It will be invoked at the time a response
* need to be send.
*
* {@code
* {
* after("GET", "*", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
* }
* }
*
* You are allowed to modify the request, response and result objects. The handler returns a
* {@link Result} which can be the same or an entirely new {@link Result}.
*
* A after handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* after("GET", "/path", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param method HTTP method to intercept.
* @param pattern Pattern to intercept.
* @param handler After handler.
* @return A new route definition.
*/
@Nonnull
Route.Definition after(String method, String pattern, Route.After handler);
/**
* after
*
* Allows for customized response before sending it. It will be invoked at the time a response
* need to be send.
*
* {@code
* {
* after("GET", "*", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
* }
* }
*
* You are allowed to modify the request, response and result objects. The handler returns a
* {@link Result} which can be the same or an entirely new {@link Result}.
*
* A after handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* after("GET", "/path", (req, rsp, result) -> {
* // your code goes here
* return result;
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* @param method HTTP method to intercept.
* @param pattern Pattern to intercept.
* @param handler After handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection after(String method, String pattern, Route.After handler, Route.After... next) {
List routes = new ArrayList<>();
routes.add(after(method, pattern, handler));
Arrays.asList(next).stream()
.map(h -> after(method, pattern, handler))
.forEach(routes::add);
return new Route.Collection(routes.toArray(new Route.Definition[routes.size()]));
}
/**
* complete
*
* Allows for log and cleanup a request. It will be invoked after we send a response.
*
* {@code
* {
* complete((req, rsp, cause) -> {
* // your code goes here
* });
* }
* }
*
* You are NOT allowed to modify the request and response objects. The cause is an
* {@link Optional} with a {@link Throwable} useful to identify problems.
*
* The goal of the after handler is to probably cleanup request object and log
* responses.
*
* A complete handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* complete((req, rsp, cause) -> {
* // your code goes here
* });
*
* get(req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* example
*
* Suppose you have a transactional resource, like a database connection. The next example shows
* you how to implement a simple and effective transaction-per-request pattern:
*
*
* {@code
* {
* // start transaction
* before((req, rsp) -> {
* DataSource ds = req.require(DataSource.class);
* Connection connection = ds.getConnection();
* Transaction trx = connection.getTransaction();
* trx.begin();
* req.set("connection", connection);
* return true;
* });
*
* // commit/rollback transaction
* complete((req, rsp, cause) -> {
* // unbind connection from request
* try(Connection connection = req.unset("connection").get()) {
* Transaction trx = connection.getTransaction();
* if (cause.ifPresent()) {
* trx.rollback();
* } else {
* trx.commit();
* }
* }
* });
*
* // your transactional routes goes here
* get("/api/something", req -> {
* Connection connection = req.get("connection");
* // work with connection
* });
* }
* }
*
* @param handler Complete handler.
* @return A new route definition.
*/
@Nonnull
default Route.Definition complete(final Route.Complete handler) {
return complete("*", handler);
}
/**
* complete
*
* Allows for log and cleanup a request. It will be invoked after we send a response.
*
* {@code
* {
* complete((req, rsp, cause) -> {
* // your code goes here
* });
* }
* }
*
* You are NOT allowed to modify the request and response objects. The cause is an
* {@link Optional} with a {@link Throwable} useful to identify problems.
*
* The goal of the after handler is to probably cleanup request object and log
* responses.
*
* A complete handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* complete((req, rsp, cause) -> {
* // your code goes here
* });
*
* get(req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* example
*
* Suppose you have a transactional resource, like a database connection. The next example shows
* you how to implement a simple and effective transaction-per-request pattern:
*
*
* {@code
* {
* // start transaction
* before((req, rsp) -> {
* DataSource ds = req.require(DataSource.class);
* Connection connection = ds.getConnection();
* Transaction trx = connection.getTransaction();
* trx.begin();
* req.set("connection", connection);
* return true;
* });
*
* // commit/rollback transaction
* complete((req, rsp, cause) -> {
* // unbind connection from request
* try(Connection connection = req.unset("connection").get()) {
* Transaction trx = connection.getTransaction();
* if (cause.ifPresent()) {
* trx.rollback();
* } else {
* trx.commit();
* }
* }
* });
*
* // your transactional routes goes here
* get("/api/something", req -> {
* Connection connection = req.get("connection");
* // work with connection
* });
* }
* }
*
* @param handler Complete handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection complete(final Route.Complete handler, Route.Complete... next) {
return complete("*", handler, next);
}
/**
* complete
*
* Allows for log and cleanup a request. It will be invoked after we send a response.
*
* {@code
* {
* complete("*", (req, rsp, cause) -> {
* // your code goes here
* });
* }
* }
*
* You are NOT allowed to modify the request and response objects. The cause is an
* {@link Optional} with a {@link Throwable} useful to identify problems.
*
* The goal of the complete handler is to probably cleanup request object and log
* responses.
*
* A complete handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* complete("/path", (req, rsp, cause) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* example
*
* Suppose you have a transactional resource, like a database connection. The next example shows
* you how to implement a simple and effective transaction-per-request pattern:
*
*
* {@code
* {
* // start transaction
* before("/api/*", (req, rsp) -> {
* DataSource ds = req.require(DataSource.class);
* Connection connection = ds.getConnection();
* Transaction trx = connection.getTransaction();
* trx.begin();
* req.set("connection", connection);
* return true;
* });
*
* // commit/rollback transaction
* complete("/api/*", (req, rsp, cause) -> {
* // unbind connection from request
* try(Connection connection = req.unset("connection").get()) {
* Transaction trx = connection.getTransaction();
* if (cause.ifPresent()) {
* trx.rollback();
* } else {
* trx.commit();
* }
* }
* });
*
* // your transactional routes goes here
* get("/api/something", req -> {
* Connection connection = req.get("connection");
* // work with connection
* });
* }
* }
*
* @param pattern Pattern to intercept.
* @param handler Complete handler.
* @return A new route definition.
*/
@Nonnull
default Route.Definition complete(final String pattern, final Route.Complete handler) {
return complete("*", pattern, handler);
}
/**
* complete
*
* Allows for log and cleanup a request. It will be invoked after we send a response.
*
* {@code
* {
* complete("*", (req, rsp, cause) -> {
* // your code goes here
* });
* }
* }
*
* You are NOT allowed to modify the request and response objects. The cause is an
* {@link Optional} with a {@link Throwable} useful to identify problems.
*
* The goal of the complete handler is to probably cleanup request object and log
* responses.
*
* A complete handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* complete("/path", (req, rsp, cause) -> {
* // your code goes here
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* example
*
* Suppose you have a transactional resource, like a database connection. The next example shows
* you how to implement a simple and effective transaction-per-request pattern:
*
*
* {@code
* {
* // start transaction
* before("/api/*", (req, rsp) -> {
* DataSource ds = req.require(DataSource.class);
* Connection connection = ds.getConnection();
* Transaction trx = connection.getTransaction();
* trx.begin();
* req.set("connection", connection);
* return true;
* });
*
* // commit/rollback transaction
* complete("/api/*", (req, rsp, cause) -> {
* // unbind connection from request
* try(Connection connection = req.unset("connection").get()) {
* Transaction trx = connection.getTransaction();
* if (cause.ifPresent()) {
* trx.rollback();
* } else {
* trx.commit();
* }
* }
* });
*
* // your transactional routes goes here
* get("/api/something", req -> {
* Connection connection = req.get("connection");
* // work with connection
* });
* }
* }
*
* @param pattern Pattern to intercept.
* @param handler Complete handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection complete(String pattern, Route.Complete handler, Route.Complete... next) {
return complete("*", pattern, handler, next);
}
/**
* complete
*
* Allows for log and cleanup a request. It will be invoked after we send a response.
*
* {@code
* {
* complete("*", "*", (req, rsp, cause) -> {
* // your code goes here
* });
* }
* }
*
* You are NOT allowed to modify the request and response objects. The cause is an
* {@link Optional} with a {@link Throwable} useful to identify problems.
*
* The goal of the complete handler is to probably cleanup request object and log
* responses.
*
* A complete handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* complete("*", "/path", (req, rsp, cause) -> {
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* example
*
* Suppose you have a transactional resource, like a database connection. The next example shows
* you how to implement a simple and effective transaction-per-request pattern:
*
*
* {@code
* {
* // start transaction
* before((req, rsp) -> {
* DataSource ds = req.require(DataSource.class);
* Connection connection = ds.getConnection();
* Transaction trx = connection.getTransaction();
* trx.begin();
* req.set("connection", connection);
* return true;
* });
*
* // commit/rollback transaction
* complete((req, rsp, cause) -> {
* // unbind connection from request
* try(Connection connection = req.unset("connection")) {
* Transaction trx = connection.getTransaction();
* if (cause.ifPresent()) {
* trx.rollback();
* } else {
* trx.commit();
* }
* }
* });
*
* // your transactional routes goes here
* get("/my-trx-route", req -> {
* Connection connection = req.get("connection");
* // work with connection
* });
* }
* }
*
* @param method HTTP method to intercept.
* @param pattern Pattern to intercept.
* @param handler Complete handler.
* @return A new route definition.
*/
@Nonnull
Route.Definition complete(String method, String pattern, Route.Complete handler);
/**
* complete
*
* Allows for log and cleanup a request. It will be invoked after we send a response.
*
* {@code
* {
* complete("*", "*", (req, rsp, cause) -> {
* // your code goes here
* });
* }
* }
*
* You are NOT allowed to modify the request and response objects. The cause is an
* {@link Optional} with a {@link Throwable} useful to identify problems.
*
* The goal of the complete handler is to probably cleanup request object and log
* responses.
*
* A complete handler must to be registered before the actual handler you want to
* intercept.
*
* {@code
* {
* complete("*", "/path", (req, rsp, cause) -> {
* });
*
* get("/path", req -> {
* return "hello";
* });
* }
* }
*
* If you reverse the order then it won't work.
*
*
* Remember: routes are executed in the order they are defined and the pipeline
* is executed as long you don't generate a response.
*
*
* example
*
* Suppose you have a transactional resource, like a database connection. The next example shows
* you how to implement a simple and effective transaction-per-request pattern:
*
*
* {@code
* {
* // start transaction
* before((req, rsp) -> {
* DataSource ds = req.require(DataSource.class);
* Connection connection = ds.getConnection();
* Transaction trx = connection.getTransaction();
* trx.begin();
* req.set("connection", connection);
* return true;
* });
*
* // commit/rollback transaction
* complete((req, rsp, cause) -> {
* // unbind connection from request
* try(Connection connection = req.unset("connection")) {
* Transaction trx = connection.getTransaction();
* if (cause.ifPresent()) {
* trx.rollback();
* } else {
* trx.commit();
* }
* }
* });
*
* // your transactional routes goes here
* get("/my-trx-route", req -> {
* Connection connection = req.get("connection");
* // work with connection
* });
* }
* }
*
* @param method HTTP method to intercept.
* @param pattern Pattern to intercept.
* @param handler Complete handler.
* @param next Next handler.
* @return A new route definition.
*/
@Nonnull
default Route.Collection complete(String method, String pattern, Route.Complete handler, Route.Complete... next) {
List routes = new ArrayList<>();
routes.add(complete(method, pattern, handler));
Arrays.asList(next).stream()
.map(h -> complete(method, pattern, handler))
.forEach(routes::add);
return new Route.Collection(routes.toArray(new Route.Definition[routes.size()]));
}
/**
* Append a new WebSocket handler under the given path.
*
*
* ws("/ws", (socket) {@literal ->} {
* // connected
* socket.onMessage(message {@literal ->} {
* System.out.println(message);
* });
* socket.send("Connected"):
* });
*
*
* @param path A path pattern.
* @param handler A connect callback.
* @return A new WebSocket definition.
*/
@Nonnull
default WebSocket.Definition ws(final String path, final WebSocket.OnOpen1 handler) {
return ws(path, (WebSocket.OnOpen) handler);
}
/**
* Append a new WebSocket handler under the given path.
*
*
* ws("/ws", (req, socket) {@literal ->} {
* // connected
* socket.onMessage(message {@literal ->} {
* System.out.println(message);
* });
* socket.send("Connected"):
* });
*
*
* @param path A path pattern.
* @param handler A connect callback.
* @return A new WebSocket definition.
*/
@Nonnull
WebSocket.Definition ws(String path, WebSocket.OnOpen handler);
/**
* Append a new WebSocket handler under the given path.
*
*
* ws(MyHandler.class);
*
*
* @param handler A message callback.
* @param Message type.
* @return A new WebSocket definition.
*/
@Nonnull
default WebSocket.Definition ws(final Class> handler) {
return ws("", handler);
}
/**
* Append a new WebSocket handler under the given path.
*
*
* ws("/ws", MyHandler.class);
*
*
* @param path A path pattern.
* @param handler A message callback.
* @param Message type.
* @return A new WebSocket definition.
*/
@Nonnull
WebSocket.Definition ws(String path, Class> handler);
/**
* Add a server-sent event handler.
*
* {@code
* {
* sse("/path",(req, sse) -> {
* // 1. connected
* sse.send("data"); // 2. send/push data
* });
* }
* }
*
* @param path Event path.
* @param handler Callback. It might executed in a different thread (web server choice).
* @return A route definition.
*/
@Nonnull
Route.Definition sse(String path, Sse.Handler handler);
/**
* Add a server-sent event handler.
*
* {@code
* {
* sse("/path", sse -> {
* // 1. connected
* sse.send("data"); // 2. send/push data
* });
* }
* }
*
* @param path Event path.
* @param handler Callback. It might executed in a different thread (web server choice).
* @return A route definition.
*/
@Nonnull
Route.Definition sse(String path, Sse.Handler1 handler);
/**
* Apply common configuration and attributes to a group of routes:
*
* {@code
* {
* with(() -> {
* get("/foo", ...);
*
* get("/bar", ...);
*
* get("/etc", ...);
*
* ...
* }).attr("v1", "k1")
* .excludes("/public/**");
* }
* }
*
* All the routes wrapped by with will have a v1 attribute and will
* excludes/ignores a /public request.
*
* @param callback Route callback.
* @return A route collection.
*/
@Nonnull
Route.Collection with(Runnable callback);
/**
* Apply the mapper to all the functional routes.
*
* {@code
* {
* mapper((Integer v) -> v * 2);
*
* mapper(v -> Integer.parseInt(v.toString()));
*
* get("/four", () -> "2");
* }
* }
*
* A call to /four outputs 4. Mapper are applied in reverse order.
*
* @param mapper Route mapper to append.
* @return This instance.
*/
@Nonnull
Router map(final Mapper mapper);
/**
* Setup a route error handler. Default error handler {@link Err.DefHandler} does content
* negotation and this method allow to override/complement default handler.
*
* This is a catch all error handler.
*
* html
*
* If a request has an Accept: text/html header. Then, the default err handler will
* ask to a {@link View.Engine} to render the err view.
*
* The default model has these attributes:
*
* message: exception string
* stacktrace: exception stack-trace as an array of string
* status: status code, like 400
* reason: status code reason, like BAD REQUEST
*
*
* Here is a simply public/err.html error page:
*
*
* <html>
* <body>
* {{ "{{status" }}}}:{{ "{{reason" }}}}
* </body>
* </html>
*
*
* HTTP status code will be set too.
*
* @param err A route error handler.
* @return This router.
*/
@Nonnull
Router err(Err.Handler err);
/**
* Setup a custom error handler.The error handler will be executed if the current exception is an
* instance of given type type.
*
* All headers are reset while generating the error response.
*
* @param type Exception type. The error handler will be executed if the current exception is an
* instance of this type.
* @param handler A route error handler.
* @return This router.
*/
@Nonnull
default Router err(final Class type, final Err.Handler handler) {
return err((req, rsp, x) -> {
if (type.isInstance(x) || type.isInstance(x.getCause())) {
handler.handle(req, rsp, x);
}
});
}
/**
* Setup a route error handler. The error handler will be executed if current status code matches
* the one provided.
*
* All headers are reset while generating the error response.
*
* @param statusCode The status code to match.
* @param handler A route error handler.
* @return This router.
*/
@Nonnull
default Router err(final int statusCode, final Err.Handler handler) {
return err((req, rsp, x) -> {
if (statusCode == x.statusCode()) {
handler.handle(req, rsp, x);
}
});
}
/**
* Setup a route error handler. The error handler will be executed if current status code matches
* the one provided.
*
* All headers are reset while generating the error response.
*
* @param code The status code to match.
* @param handler A route error handler.
* @return This router.
*/
@Nonnull
default Router err(final Status code, final Err.Handler handler) {
return err((req, rsp, x) -> {
if (code.value() == x.statusCode()) {
handler.handle(req, rsp, x);
}
});
}
/**
* Setup a route error handler. The error handler will be executed if current status code matches
* the one provided.
*
* All headers are reset while generating the error response.
*
* @param predicate Apply the error handler if the predicate evaluates to true.
* @param handler A route error handler.
* @return This router.
*/
@Nonnull
default Router err(final Predicate predicate, final Err.Handler handler) {
return err((req, rsp, err) -> {
if (predicate.test(Status.valueOf(err.statusCode()))) {
handler.handle(req, rsp, err);
}
});
}
/**
* Produces a deferred response, useful for async request processing. By default a
* {@link Deferred} results run in the current thread.
*
* This is intentional because application code (your code) always run in a worker thread. There
* is a thread pool of 100 worker threads, defined by the property:
* server.threads.Max.
*
* That's why a {@link Deferred} result runs in the current thread (no need to use a new thread),
* unless you want to apply a different thread model and or use a reactive/async library.
*
* As a final thought you might want to reduce the number of worker thread if you are going to a
* build a full reactive/async application.
*
* usage
*
*
* {
* get("/async", promise(deferred {@literal ->} {
* try {
* deferred.resolve(...); // success value
* } catch (Exception ex) {
* deferred.reject(ex); // error value
* }
* }));
* }
*
*
*
* This method is useful for integrating reactive/async libraries. Here is an example on how to
* use RxJava:
*
*
* {@code
* {
* get("/rx", promise(deferred -> {
* Observable.create(s -> {
* s.onNext(...);
* s.onCompleted();
* }).subscribeOn(Schedulers.computation())
* .subscribe(deferred::resolve, deferred::reject);
* }));
* }
* }
*
*
* This is just an example because there is a Rx module.
*
*
*
* Checkout the {@link #deferred(org.jooby.Route.ZeroArgHandler)} methods to see how to use a
* plain {@link Executor}.
*
*
* @param initializer Deferred initializer.
* @return A new deferred handler.
* @see Deferred
*/
@Nonnull
Route.OneArgHandler promise(Deferred.Initializer initializer);
/**
* Produces a deferred response, useful for async request processing. Like
* {@link #promise(org.jooby.Deferred.Initializer)} but allow you to specify an {@link Executor}
* to use. See {@link Jooby#executor(Executor)} and {@link Jooby#executor(String, Executor)}.
*
* usage
*
*
* {
* executor("forkjoin", new ForkJoinPool());
*
* get("/async", promise("forkjoin", deferred {@literal ->} {
* try {
* deferred.resolve(...); // success value
* } catch (Exception ex) {
* deferred.reject(ex); // error value
* }
* }));
* }
*
*
*
* Checkout the {@link #deferred(org.jooby.Route.ZeroArgHandler)} methods to see how to use a
* plain {@link Executor}.
*
*
* @param executor Executor to run the deferred.
* @param initializer Deferred initializer.
* @return A new deferred handler.
* @see Deferred
*/
@Nonnull
Route.OneArgHandler promise(String executor, Deferred.Initializer initializer);
/**
* Produces a deferred response, useful for async request processing. Like
* {@link #promise(org.jooby.Deferred.Initializer)} but give you access to {@link Request}.
*
* usage
*
*
* {
* ExecutorService executor = ...;
*
* get("/async", promise((req, deferred) {@literal ->} {
* executor.execute(() {@literal ->} {
* try {
* deferred.resolve(req.param("param").value()); // success value
* } catch (Exception ex) {
* deferred.reject(ex); // error value
* }
* });
* }));
* }
*
*
* @param initializer Deferred initializer.
* @return A new deferred handler.
* @see Deferred
*/
@Nonnull
Route.OneArgHandler promise(Deferred.Initializer0 initializer);
/**
* Produces a deferred response, useful for async request processing. Like
* {@link #promise(String, org.jooby.Deferred.Initializer)} but give you access to
* {@link Request}.
*
* usage
*
*
* {
* get("/async", promise("myexec", (req, deferred) {@literal ->} {
* // resolve a success value
* deferred.resolve(req.param("param").value());
* }));
* }
*
*
* @param executor Executor to run the deferred.
* @param initializer Deferred initializer.
* @return A new deferred handler.
* @see Deferred
*/
@Nonnull
Route.OneArgHandler promise(String executor, Deferred.Initializer0 initializer);
/**
* Functional version of {@link #promise(org.jooby.Deferred.Initializer)}. To use ideally with one
* or more {@link Executor}:
*
* {@code
* {
* executor("cached", Executors.newCachedExecutor());
*
* get("/fork", deferred("cached", req -> {
* return req.param("value").value();
* }));
* }
* }
*
* This handler automatically {@link Deferred#resolve(Object)} or
* {@link Deferred#reject(Throwable)} a route handler response.
*
* @param executor Executor to run the deferred.
* @param handler Application block.
* @return A new deferred handler.
*/
@Nonnull
default Route.ZeroArgHandler deferred(final String executor, final Route.OneArgHandler handler) {
return () -> Deferred.deferred(executor, handler);
}
/**
* Functional version of {@link #promise(org.jooby.Deferred.Initializer)}.
*
* Using the default executor (current thread):
*
* {@code
* {
* get("/fork", deferred(req -> {
* return req.param("value").value();
* }));
* }
* }
*
* Using a custom executor:
*
* {@code
* {
* executor(new ForkJoinPool());
*
* get("/fork", deferred(req -> {
* return req.param("value").value();
* }));
* }
* }
*
* This handler automatically {@link Deferred#resolve(Object)} or
* {@link Deferred#reject(Throwable)} a route handler response.
*
* @param handler Application block.
* @return A new deferred handler.
*/
@Nonnull
default Route.ZeroArgHandler deferred(final Route.OneArgHandler handler) {
return () -> Deferred.deferred(handler);
}
/**
* Functional version of {@link #promise(org.jooby.Deferred.Initializer)}. To use ideally with one
* or more {@link Executor}:
*
* {@code
* {
* executor("cached", Executors.newCachedExecutor());
*
* get("/fork", deferred("cached", () -> {
* return "OK";
* }));
* }
* }
*
* This handler automatically {@link Deferred#resolve(Object)} or
* {@link Deferred#reject(Throwable)} a route handler response.
*
* @param executor Executor to run the deferred.
* @param handler Application block.
* @return A new deferred handler.
*/
@Nonnull
default Route.ZeroArgHandler deferred(final String executor, final Route.ZeroArgHandler handler) {
return () -> Deferred.deferred(executor, handler);
}
/**
* Functional version of {@link #promise(org.jooby.Deferred.Initializer)}.
*
* Using the default executor (current thread):
*
* {@code
* {
* get("/fork", deferred(() -> {
* return req.param("value").value();
* }));
* }
* }
*
* Using a custom executor:
*
* {@code
* {
* executor(new ForkJoinPool());
*
* get("/fork", deferred(() -> {
* return req.param("value").value();
* }));
* }
* }
*
* This handler automatically {@link Deferred#resolve(Object)} or
* {@link Deferred#reject(Throwable)} a route handler response.
*
* @param handler Application block.
* @return A new deferred handler.
*/
@Nonnull
default Route.ZeroArgHandler deferred(final Route.ZeroArgHandler handler) {
return () -> Deferred.deferred(handler);
}
}