001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.servlet;
018
019import static org.apache.juneau.http.HttpMethod.*;
020
021import java.util.*;
022
023import org.apache.juneau.annotation.*;
024import org.apache.juneau.bean.swagger.Swagger;
025import org.apache.juneau.bean.swagger.ui.*;
026import org.apache.juneau.html.annotation.*;
027import org.apache.juneau.http.annotation.*;
028import org.apache.juneau.http.resource.*;
029import org.apache.juneau.jsonschema.annotation.*;
030import org.apache.juneau.rest.*;
031import org.apache.juneau.rest.annotation.*;
032import org.apache.juneau.rest.stats.*;
033
034/**
035 * Basic REST operation methods.
036 *
037 * <p>
038 *    Defines 5 special use REST operation endpoints:
039 * </p>
040 *
041 * <p class='bjava'>
042 *    <ja>@RestGet</ja>(path=<js>"/api/*"</js></js>)
043 *    <jk>public</jk> {@link Swagger} {@link #getSwagger(RestRequest) getSwagger}({@link RestRequest} <jv>req</jv>);
044 *
045 *    <ja>@RestGet</ja>(path=<js>"/htdocs/*"</js>)
046 *    <jk>public</jk> {@link HttpResource} {@link #getHtdoc(String,Locale) getHtdoc}(<ja>@Path</ja> String <jv>path</jv>, Locale <jv>locale</jv>);
047 *
048 *    <ja>@RestGet</ja>(path=<js>"favicon.ico"</js>)
049 *    <jk>public</jk> {@link HttpResource} {@link #getFavIcon() getFavIcon}();
050 *
051 *    <ja>@RestGet</ja>(path=<js>"/stats"</js>)
052 *    <jk>public</jk> {@link RestContextStats} {@link #getStats(RestRequest) getStats}({@link RestRequest} <jv>req</jv>);
053 *
054 *    <ja>@RestOp</ja>(method=<jsf>ANY</jsf>, path=<js>"/error"</js>)
055 *    <jk>public void</jk> {@link #error() error}();
056 * </p>
057 *
058 * <p>
059 *    Implementations provided by the following classes:
060 * </p>
061 * <ul class='javatreec'>
062 *    <li class='jac'>{@link BasicRestServlet}
063 *    <li class='jac'>{@link BasicRestServletGroup}
064 *    <li class='jac'>{@link BasicRestObject}
065 *    <li class='jac'>{@link BasicRestObjectGroup}
066 * </ul>
067 *
068 * <h5 class='section'>See Also:</h5><ul>
069 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestAnnotatedClassBasics">@Rest-Annotated Class Basics</a>
070 * </ul>
071 */
072@HtmlDocConfig(
073   // Basic page navigation links.
074   navlinks={
075      "up: request:/..",
076      "api: servlet:/api",
077      "stats: servlet:/stats"
078   }
079)
080@JsonSchemaConfig(
081   // Add descriptions to the following types when not specified:
082   addDescriptionsTo="bean,collection,array,map,enum",
083   // Add example to the following types:
084   addExamplesTo="bean,collection,array,map",
085   // Don't generate schema information on the Swagger bean itself or HTML beans.
086   ignoreTypes="Swagger,org.apache.juneau.bean.html5.*",
087   // Use $ref references for bean definitions to reduce duplication in Swagger.
088   useBeanDefs="true"
089)
090public interface BasicRestOperations {
091
092   /**
093    * [GET /api] - Show resource options.
094    *
095    * @param req The HTTP request.
096    * @return A bean containing the contents for the OPTIONS page.
097    */
098   @RestGet(
099      path="/api/*",
100      summary="Swagger documentation",
101      description="Swagger documentation for this resource."
102   )
103   @HtmlDocConfig(
104      // Should override config annotations defined on class.
105      rank=10,
106      // Override the nav links for the swagger page.
107      navlinks={
108         "back: servlet:/",
109         "json: servlet:/?Accept=text/json&plainText=true"
110      },
111      // Never show aside contents of page inherited from class.
112      aside="NONE"
113   )
114   @BeanConfig(
115      // POJO swaps to apply to all serializers/parsers on this method.
116      swaps={
117         // Use the SwaggerUI swap when rendering Swagger beans.
118         // This is a per-media-type swap that only applies to text/html requests.
119         SwaggerUI.class
120      }
121   ) Swagger getSwagger(RestRequest req);
122
123   /**
124    * [GET /htdocs/*] - Retrieve static file.
125    *
126    * @param path The path to retrieve.
127    * @param locale The locale of the HTTP request.
128    * @return An HTTP resource representing the static file.
129    */
130   @RestGet(
131      path="/htdocs/*",
132      summary="Static files",
133      description="Static file retrieval."
134   ) HttpResource getHtdoc(@Path String path, Locale locale);
135
136   /**
137    * [GET favicon.ico] - Retrieve favorites icon image.
138    *
139    * @return A bean containing the contents for the OPTIONS page.
140    */
141   @RestGet(
142      path="favicon.ico",
143      summary="Favorites icon.",
144      description="Favorites icon."
145   ) HttpResource getFavIcon();
146
147   /**
148    * [* /error] - Error occurred.
149    */
150   @RestOp(
151      method=ANY,
152      path="/error",
153      summary="Error occurred",
154      description={
155         "An error occurred during handling of the request.  ",
156         "Servlet chains will often automatically redirect to '/error' when any sort of error condition occurs ",
157         "(such as failed authentication) and will set appropriate response parameters ",
158         "(such as an WWW-Authenticate response header)."
159      }
160   ) void error();
161
162   /**
163    * [GET /stats] - Timing statistics.
164    *
165    * <p>
166    * Timing statistics for method invocations on this resource.
167    *
168    * @param req The HTTP request.
169    * @return A collection of timing statistics for each annotated method on this resource.
170    */
171   @RestGet(
172      path="/stats",
173      summary="Timing statistics",
174      description="Timing statistics for method invocations on this resource."
175   )
176   @HtmlDocConfig(
177      // Should override config annotations defined on class.
178      rank=10,
179      // Override the nav links for the swagger page.
180      navlinks={
181         "back: servlet:/",
182         "json: servlet:/stats?Accept=text/json&plainText=true"
183      },
184      // Never show aside contents of page inherited from class.
185      aside="NONE"
186   ) RestContextStats getStats(RestRequest req);
187}