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; 014 015import org.apache.juneau.dto.swagger.*; 016import org.apache.juneau.html.*; 017import org.apache.juneau.html.annotation.*; 018import org.apache.juneau.jso.*; 019import org.apache.juneau.json.*; 020import org.apache.juneau.plaintext.*; 021import org.apache.juneau.rest.annotation.*; 022import org.apache.juneau.rest.config.*; 023import org.apache.juneau.soap.*; 024import org.apache.juneau.uon.*; 025import org.apache.juneau.urlencoding.*; 026import org.apache.juneau.xml.*; 027 028/** 029 * Subclass of {@link RestServlet} with default serializers and parsers defined. 030 * 031 * <p> 032 * Supports the following request <c>Accept</c> header values with the resulting response <c>Content-Type</c>: 033 * <table class='styled'> 034 * <tr> 035 * <th>Accept</th> 036 * <th>Content-Type</th> 037 * <th>Serializer</th> 038 * </tr> 039 * <tr> 040 * <td class='code'>application/json<br>text/json</td> 041 * <td class='code'>application/json</td> 042 * <td>{@link JsonSerializer}</td> 043 * </tr> 044 * <tr> 045 * <td class='code'>application/json+simple<br>text/json+simple</td> 046 * <td class='code'>application/json</td> 047 * <td>{@link org.apache.juneau.json.SimpleJsonSerializer}</td> 048 * </tr> 049 * <tr> 050 * <td class='code'>application/json+schema<br>text/json+schema</td> 051 * <td class='code'>application/json</td> 052 * <td>{@link JsonSchemaSerializer}</td> 053 * </tr> 054 * <tr> 055 * <td class='code'>text/xml</td> 056 * <td class='code'>text/xml</td> 057 * <td>{@link XmlDocSerializer}</td> 058 * </tr> 059 * <tr> 060 * <td class='code'>text/html</td> 061 * <td class='code'>text/html</td> 062 * <td>{@link HtmlDocSerializer}</td> 063 * </tr> 064 * <tr> 065 * <td class='code'>text/html+stripped</td> 066 * <td class='code'>text/html</td> 067 * <td>{@link HtmlStrippedDocSerializer}</td> 068 * </tr> 069 * <tr> 070 * <td class='code'>text/uon</td> 071 * <td class='code'>text/uon</td> 072 * <td>{@link UonSerializer}</td> 073 * </tr> 074 * <tr> 075 * <td class='code'>application/x-www-form-urlencoded</td> 076 * <td class='code'>application/x-www-form-urlencoded</td> 077 * <td>{@link UrlEncodingSerializer}</td> 078 * </tr> 079 * <tr> 080 * <td class='code'>text/xml+soap</td> 081 * <td class='code'>text/xml</td> 082 * <td>{@link SoapXmlSerializer}</td> 083 * </tr> 084 * <tr> 085 * <td class='code'>text/plain</td> 086 * <td class='code'>text/plain</td> 087 * <td>{@link PlainTextSerializer}</td> 088 * </tr> 089 * </table> 090 * <p> 091 * Supports the following request <c>Content-Type</c> header values: 092 * </p> 093 * <table class='styled'> 094 * <tr> 095 * <th>Content-Type</th> 096 * <th>Parser</th> 097 * </tr> 098 * <tr> 099 * <td class='code'>application/json<br>text/json</td> 100 * <td>{@link JsonParser}</td> 101 * </tr> 102 * <tr> 103 * <td class='code'>text/xml<br>application/xml</td> 104 * <td>{@link XmlParser}</td> 105 * </tr> 106 * <tr> 107 * <td class='code'>text/html<br>text/html+stripped</td> 108 * <td>{@link HtmlParser}</td> 109 * </tr> 110 * <tr> 111 * <td class='code'>text/uon</td> 112 * <td>{@link UonParser}</td> 113 * </tr> 114 * <tr> 115 * <td class='code'>application/x-www-form-urlencoded</td> 116 * <td>{@link UrlEncodingParser}</td> 117 * </tr> 118 * <tr> 119 * <td class='code'>text/plain</td> 120 * <td>{@link PlainTextParser}</td> 121 * </tr> 122 * </table> 123 * 124 * <p> 125 * It should be noted that we do NOT add {@link JsoParser} to the list of parsers since this could cause security 126 * issues. 127 * Use caution when using this particular parser as it could inadvertently cause code execution security holes. 128 * 129 * <p> 130 * The list of serializers and parsers can be appended to using the 131 * {@link Rest#serializers() @Rest(serializers)} and 132 * {@link Rest#parsers() @Rest(parsers)} annotations on subclasses. 133 * 134 * <p> 135 * This subclass also provides a default OPTIONS page by implementing a {@link #getOptions(RestRequest)} that returns a 136 * POJO consisting of beans describing the class. 137 * 138 * <p> 139 * The OPTIONS page can be modified or augmented by overriding this method and providing your own data. 140 * 141 * <ul class='notes'> 142 * <li> 143 * Provides a default HTML stylesheet by setting {@link HtmlDocConfig#stylesheet() HtmlDocConfig(stylesheet)} 144 * to <js>"styles/juneau.css"</js>. 145 * <li> 146 * Provides a default classpath entry "htdocs" by setting 147 * {@link Rest#staticFiles() @Rest(staticFiles)} to <code>{<js>"htdocs:htdocs"</js>,<js>"styles:styles"</js>}</code>. 148 * This allows files inside the <c>[servletPackage].htdocs</c> package to be served up under the URL 149 * <c>/servletPath/htdocs</c>. 150 * </ul> 151 * 152 * <ul class='seealso'> 153 * <li class='link'>{@doc BasicRestServlet} 154 * </ul> 155 */ 156@Rest( 157 // Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter. 158 allowedMethodParams="OPTIONS" 159) 160@HtmlDocConfig( 161 // Basic page navigation links. 162 navlinks={ 163 "up: request:/..", 164 "options: servlet:/?method=OPTIONS", 165 "stats: servlet:/stats" 166 } 167) 168public abstract class BasicRestServlet extends RestServlet implements BasicUniversalRest, BasicRestMethods { 169 private static final long serialVersionUID = 1L; 170 171 /** 172 * [OPTIONS /*] - Show resource options. 173 * 174 * @param req The HTTP request. 175 * @return A bean containing the contents for the OPTIONS page. 176 */ 177 @Override /* BasicRestConfig */ 178 public Swagger getOptions(RestRequest req) { 179 // Localized Swagger for this resource is available through the RestRequest object. 180 return req.getSwagger(); 181 } 182 183 /** 184 * [GET /options] - Show resource options. 185 * 186 * @param req The HTTP request. 187 * @return A bean containing the contents for the OPTIONS page. 188 */ 189 @Override /* BasicRestConfig */ 190 public Swagger getOptions2(RestRequest req) { 191 // Localized Swagger for this resource is available through the RestRequest object. 192 return req.getSwagger(); 193 } 194 195 /** 196 * [* /error] - Error occurred. 197 * 198 * <p> 199 * Servlet chains will often automatically redirect to <js>"/error"</js> when any sort of error condition occurs 200 * (such as failed authentication) and will set appropriate response parameters (such as an <c>WWW-Authenticate</c> 201 * response header). 202 * 203 * <p> 204 * These responses should be left as-is without any additional processing. 205 */ 206 @Override /* BasicRestConfig */ 207 public void error() {} 208 209 /** 210 * [GET /stats] - Timing statistics. 211 * 212 * <p> 213 * Timing statistics for method invocations on this resource. 214 * 215 * @return A collection of timing statistics for each annotated method on this resource. 216 */ 217 @Override /* BasicRestConfig */ 218 public RestContextStats getStats(RestRequest req) { 219 return req.getContext().getStats(); 220 } 221}