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