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 static org.apache.juneau.http.HttpMethodName.*; 016import static org.apache.juneau.jsonschema.JsonSchemaGenerator.*; 017 018import org.apache.juneau.dto.swagger.*; 019import org.apache.juneau.dto.swagger.ui.*; 020import org.apache.juneau.html.*; 021import org.apache.juneau.jso.*; 022import org.apache.juneau.json.*; 023import org.apache.juneau.plaintext.*; 024import org.apache.juneau.rest.annotation.*; 025import org.apache.juneau.soap.*; 026import org.apache.juneau.uon.*; 027import org.apache.juneau.urlencoding.*; 028import org.apache.juneau.xml.*; 029 030/** 031 * Subclass of {@link RestServlet} with default serializers and parsers defined. 032 * 033 * <p> 034 * Supports the following request <code>Accept</code> header values with the resulting response <code>Content-Type</code>: 035 * <table class='styled'> 036 * <tr> 037 * <th>Accept</th> 038 * <th>Content-Type</th> 039 * <th>Serializer</th> 040 * </tr> 041 * <tr> 042 * <td class='code'>application/json<br>text/json</td> 043 * <td class='code'>application/json</td> 044 * <td>{@link JsonSerializer}</td> 045 * </tr> 046 * <tr> 047 * <td class='code'>application/json+simple<br>text/json+simple</td> 048 * <td class='code'>application/json</td> 049 * <td>{@link org.apache.juneau.json.SimpleJsonSerializer}</td> 050 * </tr> 051 * <tr> 052 * <td class='code'>application/json+schema<br>text/json+schema</td> 053 * <td class='code'>application/json</td> 054 * <td>{@link JsonSchemaSerializer}</td> 055 * </tr> 056 * <tr> 057 * <td class='code'>text/xml</td> 058 * <td class='code'>text/xml</td> 059 * <td>{@link XmlDocSerializer}</td> 060 * </tr> 061 * <tr> 062 * <td class='code'>text/xml+schema</td> 063 * <td class='code'>text/xml</td> 064 * <td>{@link org.apache.juneau.xmlschema.XmlSchemaDocSerializer}</td> 065 * </tr> 066 * <tr> 067 * <td class='code'>text/html</td> 068 * <td class='code'>text/html</td> 069 * <td>{@link HtmlDocSerializer}</td> 070 * </tr> 071 * <tr> 072 * <td class='code'>text/html+stripped</td> 073 * <td class='code'>text/html</td> 074 * <td>{@link HtmlStrippedDocSerializer}</td> 075 * </tr> 076 * <tr> 077 * <td class='code'>text/uon</td> 078 * <td class='code'>text/uon</td> 079 * <td>{@link UonSerializer}</td> 080 * </tr> 081 * <tr> 082 * <td class='code'>application/x-www-form-urlencoded</td> 083 * <td class='code'>application/x-www-form-urlencoded</td> 084 * <td>{@link UrlEncodingSerializer}</td> 085 * </tr> 086 * <tr> 087 * <td class='code'>text/xml+soap</td> 088 * <td class='code'>text/xml</td> 089 * <td>{@link SoapXmlSerializer}</td> 090 * </tr> 091 * <tr> 092 * <td class='code'>text/plain</td> 093 * <td class='code'>text/plain</td> 094 * <td>{@link PlainTextSerializer}</td> 095 * </tr> 096 * </table> 097 * <p> 098 * Supports the following request <code>Content-Type</code> header values: 099 * </p> 100 * <table class='styled'> 101 * <tr> 102 * <th>Content-Type</th> 103 * <th>Parser</th> 104 * </tr> 105 * <tr> 106 * <td class='code'>application/json<br>text/json</td> 107 * <td>{@link JsonParser}</td> 108 * </tr> 109 * <tr> 110 * <td class='code'>text/xml<br>application/xml</td> 111 * <td>{@link XmlParser}</td> 112 * </tr> 113 * <tr> 114 * <td class='code'>text/html<br>text/html+stripped</td> 115 * <td>{@link HtmlParser}</td> 116 * </tr> 117 * <tr> 118 * <td class='code'>text/uon</td> 119 * <td>{@link UonParser}</td> 120 * </tr> 121 * <tr> 122 * <td class='code'>application/x-www-form-urlencoded</td> 123 * <td>{@link UrlEncodingParser}</td> 124 * </tr> 125 * <tr> 126 * <td class='code'>text/plain</td> 127 * <td>{@link PlainTextParser}</td> 128 * </tr> 129 * </table> 130 * 131 * <p> 132 * It should be noted that we do NOT add {@link JsoParser} to the list of parsers since this could cause security 133 * issues. 134 * Use caution when using this particular parser as it could inadvertently cause code execution security holes. 135 * 136 * <p> 137 * The list of serializers and parsers can be appended to using the 138 * {@link RestResource#serializers() @RestResource(serializers)} and 139 * {@link RestResource#parsers() @RestResource(parsers)} annotations on subclasses. 140 * 141 * <p> 142 * This subclass also provides a default OPTIONS page by implementing a {@link #getOptions(RestRequest)} that returns a 143 * POJO consisting of beans describing the class. 144 * 145 * <p> 146 * The OPTIONS page can be modified or augmented by overriding this method and providing your own data. 147 * 148 * <h5 class='section'>Notes:</h5> 149 * <ul class='spaced-list'> 150 * <li> 151 * Provides a default HTML stylesheet by setting {@link HtmlDoc#stylesheet() @HtmlDoc(stylesheet)} 152 * to <js>"styles/juneau.css"</js>. 153 * <li> 154 * Provides a default classpath entry "htdocs" by setting 155 * {@link RestResource#staticFiles() @RestResource(staticFiles)} to <code>{<js>"htdocs:htdocs"</js>,<js>"styles:styles"</js>}</code>. 156 * This allows files inside the <code>[servletPackage].htdocs</code> package to be served up under the URL 157 * <code>/servletPath/htdocs</code>. 158 * </ul> 159 * 160 * <h5 class='section'>See Also:</h5> 161 * <ul> 162 * <li class='link'>{@doc juneau-rest-server.Instantiation.BasicRestServlet} 163 * </ul> 164 */ 165@RestResource( 166 167 // Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter. 168 allowedMethodParams="OPTIONS", 169 170 // HTML-page specific settings. 171 htmldoc=@HtmlDoc( 172 // Basic page navigation links. 173 navlinks={ 174 "up: request:/..", 175 "options: servlet:/?method=OPTIONS" 176 } 177 ) 178) 179public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig { 180 private static final long serialVersionUID = 1L; 181 182 /** 183 * [OPTIONS /*] - Show resource options. 184 * 185 * @param req The HTTP request. 186 * @return A bean containing the contents for the OPTIONS page. 187 */ 188 @RestMethod(name=OPTIONS, path="/*", 189 190 summary="Swagger documentation", 191 description="Swagger documentation for this resource.", 192 193 htmldoc=@HtmlDoc( 194 // Override the nav links for the swagger page. 195 navlinks={ 196 "back: servlet:/", 197 "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true" 198 }, 199 // Never show aside contents of page inherited from class. 200 aside="NONE" 201 ), 202 203 // POJO swaps to apply to all serializers/parsers on this method. 204 pojoSwaps={ 205 // Use the SwaggerUI swap when rendering Swagger beans. 206 // This is a per-media-type swap that only applies to text/html requests. 207 SwaggerUI.class 208 }, 209 210 // Properties to apply to all serializers/parsers and REST-specific API objects on this method. 211 properties={ 212 // Add descriptions to the following types when not specified: 213 @Property(name=JSONSCHEMA_addDescriptionsTo, value="bean,collection,array,map,enum"), 214 215 // Add x-example to the following types: 216 @Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"), 217 218 // Don't generate schema information on the Swagger bean itself or HTML beans. 219 @Property(name=JSONSCHEMA_ignoreTypes, value="Swagger,org.apache.juneau.dto.html5.*") 220 }, 221 222 // Shortcut for boolean properties. 223 flags={ 224 // Use $ref references for bean definitions to reduce duplication in Swagger. 225 JSONSCHEMA_useBeanDefs, 226 227 // When parsing generated beans, ignore unknown properties that may only exist as getters and not setters. 228 BEAN_ignoreUnknownBeanProperties 229 } 230 ) 231 public Swagger getOptions(RestRequest req) { 232 // Localized Swagger for this resource is available through the RestRequest object. 233 return req.getSwagger(); 234 } 235}