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// @formatter:off
073@HtmlDocConfig(
074   // Basic page navigation links.
075   navlinks={
076      "up: request:/..",
077      "api: servlet:/api",
078      "stats: servlet:/stats"
079   }
080)
081@JsonSchemaConfig(
082   // Add descriptions to the following types when not specified:
083   addDescriptionsTo="bean,collection,array,map,enum",
084   // Add example to the following types:
085   addExamplesTo="bean,collection,array,map",
086   // Don't generate schema information on the Swagger bean itself or HTML beans.
087   ignoreTypes="Swagger,org.apache.juneau.bean.html5.*",
088   // Use $ref references for bean definitions to reduce duplication in Swagger.
089   useBeanDefs="true"
090)
091public interface BasicRestOperations {
092
093   /**
094    * [* /error] - Error occurred.
095    */
096   @RestOp(
097      method=ANY,
098      path="/error",
099      summary="Error occurred",
100      description={
101         "An error occurred during handling of the request.  ",
102         "Servlet chains will often automatically redirect to '/error' when any sort of error condition occurs ",
103         "(such as failed authentication) and will set appropriate response parameters ",
104         "(such as an WWW-Authenticate response header)."
105      }
106   ) void error();
107
108   /**
109    * [GET favicon.ico] - Retrieve favorites icon image.
110    *
111    * @return A bean containing the contents for the OPTIONS page.
112    */
113   @RestGet(
114      path="favicon.ico",
115      summary="Favorites icon.",
116      description="Favorites icon."
117   ) HttpResource getFavIcon();
118
119   /**
120    * [GET /htdocs/*] - Retrieve static file.
121    *
122    * @param path The path to retrieve.
123    * @param locale The locale of the HTTP request.
124    * @return An HTTP resource representing the static file.
125    */
126   @RestGet(
127      path="/htdocs/*",
128      summary="Static files",
129      description="Static file retrieval."
130   ) HttpResource getHtdoc(@Path String path, Locale locale);
131
132   /**
133    * [GET /stats] - Timing statistics.
134    *
135    * <p>
136    * Timing statistics for method invocations on this resource.
137    *
138    * @param req The HTTP request.
139    * @return A collection of timing statistics for each annotated method on this resource.
140    */
141   @RestGet(
142      path="/stats",
143      summary="Timing statistics",
144      description="Timing statistics for method invocations on this resource."
145   )
146   @HtmlDocConfig(
147      // Should override config annotations defined on class.
148      rank=10,
149      // Override the nav links for the swagger page.
150      navlinks = { "back: servlet:/", "json: servlet:/stats?Accept=text/json&plainText=true" },
151      // Never show aside contents of page inherited from class.
152      aside="NONE"
153   )
154   RestContextStats getStats(RestRequest req);
155
156   /**
157    * [GET /api] - Show resource options.
158    *
159    * @param req The HTTP request.
160    * @return A bean containing the contents for the OPTIONS page.
161    */
162   @RestGet(
163      path="/api/*",
164      summary="Swagger documentation",
165      description="Swagger documentation for this resource."
166   )
167   @HtmlDocConfig(
168      // Should override config annotations defined on class.
169      rank=10,
170      // Override the nav links for the swagger page.
171      navlinks={
172         "back: servlet:/",
173         "json: servlet:/?Accept=text/json&plainText=true"
174      },
175      // Never show aside contents of page inherited from class.
176      aside="NONE"
177   )
178   @BeanConfig(
179      // POJO swaps to apply to all serializers/parsers on this method.
180      swaps={
181         // Use the SwaggerUI swap when rendering Swagger beans.
182         // This is a per-media-type swap that only applies to text/html requests.
183         SwaggerUI.class
184      }
185   )
186   Swagger getSwagger(RestRequest req);
187}