org.apache.juneau.rest.BasicRestServlet Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.rest;
import static org.apache.juneau.http.HttpMethodName.*;
import static org.apache.juneau.jsonschema.JsonSchemaGenerator.*;
import org.apache.juneau.dto.swagger.*;
import org.apache.juneau.dto.swagger.ui.*;
import org.apache.juneau.html.*;
import org.apache.juneau.jso.*;
import org.apache.juneau.json.*;
import org.apache.juneau.plaintext.*;
import org.apache.juneau.rest.annotation.*;
import org.apache.juneau.soap.*;
import org.apache.juneau.uon.*;
import org.apache.juneau.urlencoding.*;
import org.apache.juneau.xml.*;
import org.apache.juneau.xmlschema.*;
/**
* Subclass of {@link RestServlet} with default serializers and parsers defined.
*
*
* Supports the following request Accept header values with the resulting response Content-Type:
*
*
* Accept
* Content-Type
* Serializer
*
*
* application/json
text/json
* application/json
* {@link JsonSerializer}
*
*
* application/json+simple
text/json+simple
* application/json
* {@link org.apache.juneau.json.SimpleJsonSerializer}
*
*
* application/json+schema
text/json+schema
* application/json
* {@link JsonSchemaSerializer}
*
*
* text/xml
* text/xml
* {@link XmlDocSerializer}
*
*
* text/xml+schema
* text/xml
* {@link XmlSchemaDocSerializer}
*
*
* text/html
* text/html
* {@link HtmlDocSerializer}
*
*
* text/html+stripped
* text/html
* {@link HtmlStrippedDocSerializer}
*
*
* text/uon
* text/uon
* {@link UonSerializer}
*
*
* application/x-www-form-urlencoded
* application/x-www-form-urlencoded
* {@link UrlEncodingSerializer}
*
*
* text/xml+soap
* text/xml
* {@link SoapXmlSerializer}
*
*
* text/plain
* text/plain
* {@link PlainTextSerializer}
*
*
*
* Supports the following request Content-Type header values:
*
*
*
* Content-Type
* Parser
*
*
* application/json
text/json
* {@link JsonParser}
*
*
* text/xml
application/xml
* {@link XmlParser}
*
*
* text/html
text/html+stripped
* {@link HtmlParser}
*
*
* text/uon
* {@link UonParser}
*
*
* application/x-www-form-urlencoded
* {@link UrlEncodingParser}
*
*
* text/plain
* {@link PlainTextParser}
*
*
*
*
* It should be noted that we do NOT add {@link JsoParser} to the list of parsers since this could cause security
* issues.
* Use caution when using this particular parser as it could inadvertently cause code execution security holes.
*
*
* The list of serializers and parsers can be appended to using the
* {@link RestResource#serializers() @RestResource(serializers)} and
* {@link RestResource#parsers() @RestResource(parsers)} annotations on subclasses.
*
*
* This subclass also provides a default OPTIONS page by implementing a {@link #getOptions(RestRequest)} that returns a
* POJO consisting of beans describing the class.
*
*
* The OPTIONS page can be modified or augmented by overriding this method and providing your own data.
*
*
Notes:
*
* -
* Provides a default HTML stylesheet by setting {@link HtmlDoc#stylesheet() @HtmlDoc(stylesheet)}
* to
"styles/juneau.css" .
* -
* Provides a default classpath entry "htdocs" by setting
* {@link RestResource#staticFiles() @RestResource(staticFiles)} to
{"htdocs:htdocs" ,"styles:styles" }.
* This allows files inside the [servletPackage].htdocs package to be served up under the URL
* /servletPath/htdocs.
*
*
* See Also:
*
* - {@doc juneau-rest-server.Instantiation.BasicRestServlet}
*
*/
@RestResource(
// Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter.
allowedMethodParams="OPTIONS",
// HTML-page specific settings.
htmldoc=@HtmlDoc(
// Basic page navigation links.
navlinks={
"up: request:/..",
"options: servlet:/?method=OPTIONS"
}
)
)
public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig {
private static final long serialVersionUID = 1L;
/**
* [OPTIONS /*] - Show resource options.
*
* @param req The HTTP request.
* @return A bean containing the contents for the OPTIONS page.
*/
@RestMethod(name=OPTIONS, path="/*",
summary="Swagger documentation",
description="Swagger documentation for this resource.",
htmldoc=@HtmlDoc(
// Override the nav links for the swagger page.
navlinks={
"back: servlet:/",
"json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
},
// Never show aside contents of page inherited from class.
aside="NONE"
),
// POJO swaps to apply to all serializers/parsers on this method.
pojoSwaps={
// Use the SwaggerUI swap when rendering Swagger beans.
// This is a per-media-type swap that only applies to text/html requests.
SwaggerUI.class
},
// Properties to apply to all serializers/parsers and REST-specific API objects on this method.
properties={
// Add descriptions to the following types when not specified:
@Property(name=JSONSCHEMA_addDescriptionsTo, value="bean,collection,array,map,enum"),
// Add x-example to the following types:
@Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"),
// Don't generate schema information on the Swagger bean itself or HTML beans.
@Property(name=JSONSCHEMA_ignoreTypes, value="Swagger,org.apache.juneau.dto.html5.*")
},
// Shortcut for boolean properties.
flags={
// Use $ref references for bean definitions to reduce duplication in Swagger.
JSONSCHEMA_useBeanDefs,
// When parsing generated beans, ignore unknown properties that may only exist as getters and not setters.
BEAN_ignoreUnknownBeanProperties
}
)
public Swagger getOptions(RestRequest req) {
// Localized Swagger for this resource is available through the RestRequest object.
return req.getSwagger();
}
}