/**
 *                                  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.spec;

import java.io.Serializable;
import java.lang.reflect.Method;
import java.util.List;
import java.util.Map;
import java.util.Optional;

/**
 * <h1>spec</h1>
 *
 * <p>
 * The spec module allows you to export your API/microservices outside an application.
 * </p>
 *
 * <p>
 * The goal of this module is to define a common way to write APIs and provide you API tools like
 * live doc and testing for <strong>FREE</strong>. By <strong>FREE</strong> we mean:
 * </p>
 *
 * <blockquote>
 * You aren't force to learn any other tool or annotated your code special annotations. All you
 * have to do is: **write your application** following a few/minor suggestions.
 * </blockquote>
 *
 * <p>
 * This module process, collect and compile <strong>routes</strong> from your application. It
 * extracts HTTP method/pattern, parameter, responses, types and doc.
 * </p>
 *
 * <p>
 * You will find here the basis and the necessary documentation to build and expose rich APIs for
 * free, but keep in mind this module isn't intended for direct usage. It is the basis for tools
 * like <a href="http://swagger.io/">Swagger</a> or <a href="http://raml.org">RAML</a>.
 * </p>
 *
 * <h1>api def</h1>
 *
 * <p>
 * The goal of this module is to define a common way to write APIs and provide you API tools like
 * live doc and testing for <strong>FREE</strong>. By <strong>FREE</strong> we mean:
 * </p>
 *
 * <blockquote>
 * You aren't force to learn any other tool or annotated your code special annotations. All you
 * have to do is: **write your application** following a few/minor suggestions.
 * </blockquote>
 *
 * Let's review how to build rich APIs using the <code>spec</code> module via <code>script</code> or
 * <code>mvc</code> programming model:
 *
 * <h2>script API</h2>
 * <pre>
 * {@code
 * {
 *   /{@literal *}{@literal *}
 *    {@literal *} Everything about your Pets.
 *    {@literal *}/
 *   use("/api/pets")
 *      /{@literal *}{@literal *}
 *       * List pets ordered by name.
 *       *
 *       * @param start Start offset, useful for paging. Default is <code>0</code>.
 * * @param max Max page size, useful for paging. Default is <code>200</code>.
 * * @return Pets ordered by name.
 * {@literal *}/
 * .get(req {@literal ->} {
 * int start = req.param("start").intValue(0);
 * int max = req.param("max").intValue(200);
 * DB db = req.require(DB.class);
 * List&lt;Pet&gt; pets = db.findAll(Pet.class, start, max);
 * return pets;
 * })
 * /{@literal *}{@literal *}
 * * Find pet by ID
 * *
 * * @param id Pet ID.
 * * @return Returns <code>200</code> with a single pet or <code>404</code>
 * {@literal *}/
 * .get("/:id",req {@literal ->} {
 * int id=req.param("id").intValue();
 * DB db=req.require(DB.class);
 * Pet pet = db.find(Pet.class,id);
 * return pet;
 * })
 * /{@literal *}{@literal *}
 * * Add a new pet to the store.
 * *
 * * @param body Pet object that needs to be added to the store.
 * * @return Returns a saved pet.
 * {@literal *}/
 * .post(req {@literal ->} {
 * Pet pet=req.body().to(Pet.class);
 * DB db=req.require(DB.class);
 * db.save(pet);
 * return pet;
 * })
 * /{@literal *}{@literal *}
 * * Update an existing pet.
 * *
 * * @param body Pet object that needs to be updated.
 * * @return Returns a saved pet.
 * {@literal *}/
 * .put(req {@literal ->} {
 * Pet pet=req.body().to(Pet.class);
 * DB db=req.require(DB.class);db.save(pet);
 * return pet;
 * })
 * /{@literal *}{@literal *}
 * * Deletes a pet by ID.
 * *
 * * @param id Pet ID.
 * * @return A <code>204</code>
 * {@literal *}/
 * .delete("/:id",req {@literal ->} {
 * int id=req.param("id").intValue();
 * DB db=req.require(DB.class);
 * db.delete(Pet.class,id);
 * return Results.noContent();
 * })
 * .produces("json")
 * .consumes("json");}
 * }</pre>
 *
 * <h2>MVC API</h2>
 *
 * <pre>
 * {@code
 * /{@literal *}{@literal *}
 *  * Everything about your Pets.
 *  {@literal *}/
 *  &#64;Path("/api/pets")
 *  &#64;Consumes("json")
 *  &#64;Produces("json")
 *  public class Pets {
 *
 *    private DB db;
 *
 *    &#64;Inject
 *    public Pets(final DB db) {
 *      this.db = db;
 *    }
 *
 *    /{@literal *}{@literal *}
 *     * List pets ordered by name.
 *     *
 *     * @param start Start offset, useful for paging. Default is <code>0</code>.
 * * @param max Max page size, useful for paging. Default is <code>200</code>.
 * * @return Pets ordered by name.
 * {@literal *}/
 * &#64;GET
 * public List&lt;Pet&gt; list(final Optional<Integer> start, final Optional<Integer> max) {
 * List&lt;Pet&gt; pets = db.findAll(Pet.class, start.orElse(0), max.orElse(200));
 * return pets;
 * }
 *
 * /{@literal *}{@literal *}
 * * Find pet by ID.
 * *
 * * @param id Pet ID.
 * * @return Returns a single pet
 * {@literal *}/
 * &#64;Path("/:id")
 * &#64;GET
 * public Pet get(final int id) {
 * Pet pet = db.find(Pet.class, id);
 * return pet;
 * }
 *
 * /{@literal *}{@literal *}
 * * Add a new pet to the store.
 * *
 * * @param pet Pet object that needs to be added to the store.
 * * @return Returns a saved pet.
 * {@literal *}/
 * &#64;POST
 * public Pet post(@Body final Pet pet) {
 * db.save(pet);
 * return pet;
 * }
 *
 * /{@literal *}{@literal *}
 * * Update an existing pet.
 * *
 * * @param body Pet object that needs to be updated.
 * * @return Returns a saved pet.
 * {@literal *}/
 * &#64;PUT
 * public Pet put(@Body final Pet pet) {
 * db.save(pet);
 * return pet;
 * }
 *
 * /{@literal *}{@literal *}
 * * Deletes a pet by ID.
 * *
 * * @param id Pet ID.
 * {@literal *}/
 * &#64;DELETE
 * public void delete(final int id) {
 * db.delete(Pet.class, id);
 * }
 * }
 * }
 * </pre>
 *
 * <p>
 * Previous examples are feature identical, but they were written in very different way. Still
 * they produces an output likes:
 * </p>
 *
 * <pre>
 * {@code
 * GET /api/pets
 *  summary: Everything about your Pets.
 *  doc: List pets ordered by name.
 *  consumes: [application/json]
 *  produces: [application/json]
 *  params:
 *    start:
 *      paramType: QUERY
 *      type: int
 *      value: 0
 *      doc: Start offset, useful for paging. Default is <code>0</code>.
 *    max:
 *      paramType: QUERY
 *      type: int
 *      value: 200
 *      doc: Max page size, useful for paging. Default is <code>200</code>.
 *  response:
 *    type: java.util.List<apps.model.Pet>
 *    doc: Pets ordered by name.
 * GET /api/pets/:id
 *  summary: Everything about your Pets.
 *  doc: Find pet by ID
 *  consumes: [application/json]
 *  produces: [application/json]
 *  params:
 *    id:
 *      paramType: PATH
 *      type: int
 *      doc: Pet ID.
 *  response:
 *    type: apps.model.Pet
 *    doc: Returns <code>200</code> with a single pet or <code>404</code>
 * POST /api/pets
 *  summary: Everything about your Pets.
 *  doc: Add a new pet to the store.
 *  consumes: [application/json]
 *  produces: [application/json]
 *  params:
 *    body:
 *      paramType: BODY
 *      type: apps.model.Pet
 *      doc: Pet object that needs to be added to the store.
 *  response:
 *    type: apps.model.Pet
 *    doc: Returns a saved pet.
 * PUT /api/pets
 *  summary: Everything about your Pets.
 *  doc: Update an existing pet.
 *  consumes: [application/json]
 *  produces: [application/json]
 *  params:
 *    body:
 *      paramType: BODY
 *      type: apps.model.Pet
 *      doc: Pet object that needs to be updated.
 *  response:
 *    type: apps.model.Pet
 *    doc: Returns a saved pet.
 * DELETE /api/pets/:id
 *  summary: Everything about your Pets.
 *  doc: Deletes a pet by ID.
 *  consumes: [application/json]
 *  produces: [application/json]
 *  params:
 *    id:
 *      paramType: PATH
 *      type: int
 *      doc: Pet ID.
 *  response:
 *    type: void
 *    doc: A <code>204</code>
 * }</pre>
 *
 * <p>
 * <strong>NOTE</strong>: We use <code>text</code> for simplicity and easy read, but keep in mind
 * the output
 * is compiled in binary format.
 * </p>
 *
 *
 * <h2>how it works?</h2>
 *
 * <p>
 * The spec module scan and parse the source code: <code>*.java</code> and produces a list of
 * {@link RouteSpec}.
 * </p>
 * <p>
 * There is a <code>jooby:spec</code> maven plugin for that collects and compiles {@link RouteSpec}
 * at build time, useful for production environments where the source code isn't available.
 * </p>
 *
 * <h3>Why do we parse the source code?</h3>
 *
 * <p>
 * It is required for getting information from <code>script routes</code>. We don't need that for
 * <code>mvc routes</code> because all the information is available via <code>Reflection</code> and
 * {@link Method}.
 * </p>
 *
 * <p>
 * But also, you can write clean and useful JavaDoc in your source code that later are added to the
 * API information.
 * </p>
 *
 * <h3>Why don't parse byte-code with ASM?</h3>
 * <p>
 * Good question, the main reason is that we lost generic type information and we aren't able to
 * tell if the route response is for example a list of pets.
 * </p>
 *
 * <h2>script rules</h2>
 * <p>
 * Have a look at the previous examples again? Do you see anything special? No, right?
 * </p>
 * <p>
 * Well there are some minor things you need to keep in mind for getting or collecting route
 * metadata from <code>script</code> routes:
 * </p>
 *
 * <h3>params</h3>
 * <p>
 * Params need to be in one sentence/statement, like:
 *
 * </p>
 *
 * <pre>
 * req {@literal ->} {
 *   int id = req.param("id").intValue();
 * }
 * </pre>
 *
 * not like:
 *
 * <pre>
 * req {@literal ->} {
 *   Mutant p = req.param("id");
 *   int id = p.intValue();
 * }
 * </pre>
 *
 * <h3>response type (a.k.a return type)</h3>
 *
 * <p>
 * There should be <strong>ONLY one</strong> return statement and return type needs to be declared
 * as variable, like:
 * </p>
 *
 * <pre>
 * req {@literal ->} {
 *   ...
 *   Pet pet = db.find(id); // variable pet
 *   ...
 *   return pet;
 * }
 * </pre>
 *
 * not like:
 *
 * <pre>
 * req {@literal ->} {
 *   ...
 *   return db.find(id); // we aren't able to tell what type returns db.find
 * }
 * </pre>
 *
 * or
 *
 * <pre>
 * req {@literal ->} {
 *   ...
 *   if (...) {
 *     return ...;
 *   } else {
 *     return ...;
 *   }
 * }
 * </pre>
 *
 * <p>
 * There is a workaround if these rules doesn't make sense to you and/or the algorithm fails to
 * resolve the correct type. Please checkout next section.
 * </p>
 *
 * <h2>API doc</h2>
 * <p>
 * If you take a few minutes and write good quality doc the prize will be huge!
 * </p>
 * <p>
 * The tool takes the doc and export it as part of your API!!
 * </p>
 * <p>
 * Here is an example on how to document script routes:
 * </p>
 *
 * <pre>
 *   /{@literal *}{@literal *}
 *    * Everything about your Pets.
 *    {@literal *}/
 *   use("/api/pets")
 *      /{@literal *}{@literal *}
 *       * List pets ordered by name.
 *       *
 *       * @param start Start offset, useful for paging. Default is <code>0</code>.
 * * @param max Max page size, useful for paging. Default is <code>200</code>.
 * * @return Pets ordered by name.
 * {@literal *}/
 * .get(req {@literal ->} {
 * int start = req.param("start").intValue(0);
 * int max = req.param("max").intValue(200);
 * DB db = req.require(DB.class);
 * List&lt;Pet&gt; pets = db.findAll(Pet.class, start, max);
 * return pets;
 * });
 * </pre>
 *
 * The spec for <code>/api/pets</code> will have the following doc:
 *
 * <pre>
 *   params:
 *     start:
 *       paramType: QUERY
 *       type: int
 *       value: 0
 *       doc: Start offset, useful for paging. Default is <code>0</code>.
 * max:
 * paramType: QUERY
 * type: int
 * value: 200
 * doc: Max page size, useful for paging. Default is <code>200</code>.
 * response:
 * type: java.util.List&lt;apps.model.Pet&gt;
 * doc: Pets ordered by name.
 * </pre>
 *
 * <h3>response</h3>
 *
 * <p>
 * With JavaDoc, you can control the default type returned by the route and/or the status codes.
 * For example:
 * </p>
 *
 * <pre>
 *
 *   /{@literal *}{@literal *}
 *    * Find pet by ID.
 *    *
 *    * @param id Pet ID.
 *    * @return Returns a {&#64;link Pet} with <code>200</code> status or <code>404</code>
 * {@literal *}/
 * get(req {@literal ->} {
 * DB db = req.require(DB.class);
 * return db.find(Pet.class, id);
 * });
 * </pre>
 *
 * <p>
 * Here you tell the tool that this route produces a <code>Pet</code>, response looks like:
 * </p>
 *
 * <pre>
 * response:
 *   type: apps.model.Pet
 *    statusCodes:
 *      200: Success
 *      404: Not Found
 *    doc: Returns <code>200</code> with a single pet or <code>404</code>
 * </pre>
 *
 * <p>
 * You can override the default message of the status code with:
 * </p>
 *
 * <pre>
 * &#64;return Returns a <code>{&#64;link Pet}</code> with <code>200 = Success</code> status or
 * <code>404 = Missing</code>
 * </pre>
 *
 * <p>
 * Finally, you can specify the response type via JavaDoc type references:
 * <code>{&#64;link Pet}</code>. This is useful when the tool isn't able to detect the type for
 * you and/or you aren't able to follow the return rules described before.
 * </p>
 *
 * @author edgar
 * @see RouteProcessor
 * @since 0.15.0
 */
@Deprecated
public interface RouteSpec extends Serializable {

  /**
   * @return Top level doc (a.k.a summary).
   */
  Optional<String> summary();

  /**
   * @return Route name.
   */
  Optional<String> name();

  /**
   * @return Route method.
   */
  String method();

  /**
   * @return Route pattern.
   */
  String pattern();

  /**
   * @return Route doc.
   */
  Optional<String> doc();

  /**
   * @return List all the types this route can consumes, defaults is: {@code * / *}.
   */
  List<String> consumes();

  /**
   * @return List all the types this route can produces, defaults is: {@code * / *}.
   */
  List<String> produces();

  /**
   * @return List of params or empty list.
   */
  List<RouteParam> params();

  /**
   * @return Route response.
   */
  RouteResponse response();

  /**
   * Additional route attributes.
   *
   * @return Route attributes.
   */
  Map<String, Object> attributes();
}
