org.apache.juneau.rest.annotation.RestResource 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.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import javax.servlet.http.*;
import org.apache.juneau.*;
import org.apache.juneau.config.*;
import org.apache.juneau.encoders.*;
import org.apache.juneau.httppart.*;
import org.apache.juneau.parser.*;
import org.apache.juneau.rest.*;
import org.apache.juneau.serializer.*;
import org.apache.juneau.utils.*;
/**
* Used to denote that a class is a REST resource and to associate metadata on it.
*
*
* Usually used on a subclass of {@link RestServlet}, but can be used to annotate any class that you want to expose as
* a REST resource.
*
*
See Also:
*
* - {@doc juneau-rest-server.RestResource}
*
*/
@Documented
@Target(TYPE)
@Retention(RUNTIME)
@Inherited
public @interface RestResource {
/**
* Allow body URL parameter.
*
*
* When enabled, the HTTP body content on PUT and POST requests can be passed in as text using the "body"
* URL parameter.
*
* For example:
*
* ?body=(name='John%20Smith',age=45)
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_allowBodyParam}
*
*/
String allowBodyParam() default "";
/**
* Allowed method parameters.
*
*
* When specified, the HTTP method can be overridden by passing in a "method" URL parameter on a regular
* GET request.
*
* For example:
*
* ?method=OPTIONS
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_allowedMethodParams}
*
*/
String allowedMethodParams() default "";
/**
* Allow header URL parameters.
*
*
* When enabled, headers such as "Accept" and "Content-Type" to be passed in as URL query
* parameters.
*
* For example:
*
* ?Accept=text/json&Content-Type=text/json
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_allowHeaderParams}
*
*/
String allowHeaderParams() default "";
/**
* Class-level bean filters.
*
*
* Shortcut to add bean filters to the bean contexts of the objects returned by the following methods:
*
* - {@link RestContext#getBeanContext()}
*
- {@link RestContext#getSerializers()}
*
- {@link RestContext#getParsers()}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_beanFilters}
*
*/
Class[] beanFilters() default {};
/**
* REST call handler.
*
*
* This class handles the basic lifecycle of an HTTP REST call.
*
*
See Also:
*
* - {@link RestContext#REST_callHandler}
*
*/
Class callHandler() default RestCallHandler.Null.class;
/**
* REST children.
*
*
* Defines children of this resource.
*
*
See Also:
*
* - {@link RestContext#REST_children}
*
*/
Class[] children() default {};
/**
* Classpath resource finder.
*
*
* Used to retrieve localized files from the classpath.
*
*
See Also:
*
* - {@link RestContext#REST_classpathResourceFinder}
*
*/
Class classpathResourceFinder() default ClasspathResourceFinder.Null.class;
/**
* Client version header.
*
*
* Specifies the name of the header used to denote the client version on HTTP requests.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_clientVersionHeader}
*
*/
String clientVersionHeader() default "";
/**
* Optional location of configuration file for this servlet.
*
*
* The configuration file .
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContextBuilder#config(Config)}
*
*/
String config() default "";
/**
* Class-level response converters.
*
*
* Associates one or more {@link RestConverter converters} with a resource class.
*
*
See Also:
*
* - {@link RestContext#REST_converters}
*
*/
Class[] converters() default {};
/**
* Default Accept header.
*
*
* The default value for the Accept header if not specified on a request.
*
*
* This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String defaultAccept() default "";
/**
* Default character encoding.
*
*
* The default character encoding for the request and response if not specified on the request.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_defaultCharset}
*
*/
String defaultCharset() default "";
/**
* Default Content-Type header.
*
*
* The default value for the Content-Type header if not specified on a request.
*
*
* This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String defaultContentType() default "";
/**
* Default request headers.
*
*
* Specifies default values for request headers if they're not passed in through the request.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_defaultRequestHeaders}
*
*/
String[] defaultRequestHeaders() default {};
/**
* Default response headers.
*
*
* Specifies default values for response headers if they're not set after the Java REST method is called.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_defaultResponseHeaders}
*
*/
String[] defaultResponseHeaders() default {};
/**
* Optional servlet description.
*
*
* It is used to populate the Swagger description field.
*
This value can be retrieved programmatically through the {@link RestRequest#getResourceDescription()} method.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* The format is plain-text.
*
Multiple lines are concatenated with newlines.
*
*
* See Also:
*
* - {@link RestInfoProvider#getDescription(RestRequest)}
*
*/
String[] description() default {};
/**
* Compression encoders.
*
*
* These can be used to enable various kinds of compression (e.g. "gzip" ) on requests and responses.
*
*
See Also:
*
* - {@link RestContext#REST_encoders}
*
*/
Class[] encoders() default {};
/**
* Shortcut for setting {@link #properties()} of simple boolean types.
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Setting a flag is equivalent to setting the same property to
"true" .
*
*/
String[] flags() default {};
/**
* Class-level guards.
*
*
* Associates one or more {@link RestGuard RestGuards} with all REST methods defined in this class.
*
*
See Also:
*
* - {@link RestContext#REST_guards}
*
*/
Class[] guards() default {};
/**
* Provides HTML-doc-specific metadata on this method.
*
*
* Used to customize the output from the HTML Doc serializer.
*
* @RestResource (
* path="/addressBook" ,
*
* // Links on the HTML rendition page.
* // "request:/..." URIs are relative to the request URI.
* // "servlet:/..." URIs are relative to the servlet URI.
* // "$C{...}" variables are pulled from the config file.
* htmldoc=@HtmlDoc (
* // Widgets for $W variables.
* widgets={
* PoweredByJuneau.class ,
* ContentTypeLinks.class
* }
* navlinks={
* "up: request:/.." ,
* "options: servlet:/?method=OPTIONS" ,
* "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java" ,
* },
* aside={
* "<div style='max-width:400px;min-width:200px'>" ,
* " <p>Proof-of-concept resource that shows off the capabilities of working with POJO resources.</p>" ,
* " <p>Provides examples of: </p>" ,
* " <ul>" ,
* " <li>XML and RDF namespaces" ,
* " <li>Swagger documentation" ,
* " <li>Widgets" ,
* " </ul>" ,
* " <p style='text-weight:bold;text-decoration:underline;'>Available Content Types</p>" ,
* " $W{ContentTypeLinks}" ,
* "</div>"
* },
* footer="$W{PoweredByJuneau}"
* )
* )
*
*
* See Also:
*
* - {@doc juneau-rest-server.HtmlDocAnnotation}
*
*/
HtmlDoc htmldoc() default @HtmlDoc;
/**
* Configuration property: REST info provider.
*
*
* Class used to retrieve title/description/swagger information about a resource.
*
*
See Also:
*
* - {@link RestContext#REST_infoProvider}
*
*/
Class infoProvider() default RestInfoProvider.Null.class;
/**
* REST logger.
*
*
* Specifies the logger to use for logging.
*
*
See Also:
*
* - {@link RestContext#REST_logger}
*
*/
Class logger() default RestLogger.Null.class;
/**
* The maximum allowed input size (in bytes) on HTTP requests.
*
*
* Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting
* in out-of-memory errors which could affect system stability.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_maxInput}
*
*/
String maxInput() default "";
/**
* Messages.
*
* Identifies the location of the resource bundle for this class.
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_messages}
*
*/
String messages() default "";
/**
* Configuration property: MIME types.
*
*
* Defines MIME-type file type mappings.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_mimeTypes}
*
*/
String[] mimeTypes() default {};
/**
* Java method parameter resolvers.
*
*
* By default, the Juneau framework will automatically Java method parameters of various types (e.g.
* RestRequest, Accept, Reader).
*
This setting allows you to provide your own resolvers for your own class types that you want resolved.
*
*
See Also:
*
* - {@link RestContext#REST_paramResolvers}
*
*/
Class[] paramResolvers() default {};
/**
* Parser listener.
*
*
* Specifies the parser listener class to use for listening to non-fatal parsing errors.
*
*
See Also:
*
* - {@link Parser#PARSER_listener}
*
*/
Class parserListener() default ParserListener.Null.class;
/**
* Parsers.
*
*
* If no value is specified, the parsers are inherited from parent class.
*
Otherwise, this value overrides the parsers defined on the parent class.
*
*
* Use {@link Inherit} to inherit parsers defined on the parent class.
*
*
* Use {@link None} to suppress inheriting parsers defined on the parent class.
*
*
See Also:
*
* - {@link RestContext#REST_parsers}
*
*/
Class[] parsers() default {};
/**
* HTTP part parser.
*
*
* Specifies the {@link HttpPartParser} to use for parsing headers, query/form parameters, and URI parts.
*
*
See Also:
*
* - {@link RestContext#REST_partParser}
*
*/
Class partParser() default HttpPartParser.Null.class;
/**
* HTTP part serializer.
*
*
* Specifies the {@link HttpPartSerializer} to use for serializing headers, query/form parameters, and URI parts.
*
*
See Also:
*
* - {@link RestContext#REST_partSerializer}
*
*/
Class partSerializer() default HttpPartSerializer.Null.class;
/**
* Resource path.
*
*
* Identifies the URL subpath relative to the parent resource.
*
*
See Also:
*
* - {@link RestContext#REST_path}
*
*/
String path() default "";
/**
* Class-level POJO swaps.
*
*
* Shortcut to add POJO swaps to the bean contexts of the objects returned by the following methods:
*
* - {@link RestContext#getBeanContext()}
*
- {@link RestContext#getSerializers()}
*
- {@link RestContext#getParsers()}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_pojoSwaps}
*
*/
Class[] pojoSwaps() default {};
/**
* Class-level properties.
*
*
* Shortcut for specifying class-level properties on this servlet to the objects returned by the following methods:
*
* - {@link RestContext#getBeanContext()}
*
- {@link RestContext#getSerializers()}
*
- {@link RestContext#getParsers()}
*
*
*
* Any of the properties defined on {@link RestContext} or any of the serializers and parsers can be specified.
*
*
* Property values will be converted to the appropriate type.
*
*
* In some cases, properties can be overridden at runtime through the
* {@link RestResponse#prop(String, Object)} method or through an {@link RequestProperties}
* method parameter.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContextBuilder#set(String,Object)}
*
- {@link RestContextBuilder#set(java.util.Map)}
*
*/
Property[] properties() default {};
/**
* Render response stack traces in responses.
*
*
* Render stack traces in HTTP response bodies when errors occur.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_renderResponseStackTraces}
*
*/
String renderResponseStackTraces() default "";
/**
* REST resource resolver.
*
*
* The resolver used for resolving child resources.
*
*
See Also:
*
* - {@link RestContext#REST_resourceResolver}
*
*/
Class resourceResolver() default RestResourceResolver.Null.class;
/**
* Response handlers.
*
*
* Specifies a list of {@link ResponseHandler} classes that know how to convert POJOs returned by REST methods or
* set via {@link RestResponse#setOutput(Object)} into appropriate HTTP responses.
*
*
See Also:
*
* - {@link RestContext#REST_responseHandlers}
*
*/
Class[] responseHandlers() default {};
/**
* Serializer listener.
*
*
* Specifies the serializer listener class to use for listening to non-fatal serialization errors.
*
*
See Also:
*
* - {@link Serializer#SERIALIZER_listener}
*
*/
Class serializerListener() default SerializerListener.Null.class;
/**
* Serializers.
*
*
* If no value is specified, the serializers are inherited from parent class.
*
Otherwise, this value overrides the serializers defined on the parent class.
*
*
* Use {@link Inherit} to inherit serializers defined on the parent class.
*
*
* Use {@link None} to suppress inheriting serializers defined on the parent class.
*
*
See Also:
*
* - {@link RestContext#REST_serializers}
*
*/
Class[] serializers() default {};
/**
* Optional site name.
*
*
* The site name is intended to be a title that can be applied to the entire site.
*
*
* This value can be retrieved programmatically through the {@link RestRequest#getSiteName()} method.
*
*
* One possible use is if you want to add the same title to the top of all pages by defining a header on a
* common parent class like so:
*
* htmldoc=@HtmlDoc (
* header={
* "<h1>$R{siteName}</h1>" ,
* "<h2>$R{resourceTitle}</h2>"
* }
* )
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestInfoProvider#getSiteName(RestRequest)}
*
*/
String siteName() default "";
/**
* Static file response headers.
*
*
* Used to customize the headers on responses returned for statically-served files.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_staticFileResponseHeaders}
*
*/
String[] staticFileResponseHeaders() default {};
/**
* Static file mappings.
*
*
* Used to define paths and locations of statically-served files such as images or HTML documents.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_staticFiles}
*
*/
String[] staticFiles() default {};
/**
* Supported accept media types.
*
*
* Overrides the media types inferred from the serializers that identify what media types can be produced by the resource.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_produces}
*
*/
String[] produces() default {};
/**
* Supported content media types.
*
*
* Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_consumes}
*
*/
String[] consumes() default {};
/**
* Provides swagger-specific metadata on this resource.
*
*
* Used to populate the auto-generated OPTIONS swagger documentation.
*
*
Example:
*
* @RestResource (
* path="/addressBook" ,
*
* // Swagger info.
* swagger=@ResourceSwagger({
* "contact:{name:'John Smith',email:'[email protected]'}," ,
* "license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}," ,
* "version:'2.0', ,
* "termsOfService:'You are on your own.'," ,
* "tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]," ,
* "externalDocs:{description:'Home page',url:'http://juneau.apache.org'}"
* })
* )
*
*
* See Also:
*
* - {@link ResourceSwagger}
*
- {@link RestInfoProvider#getSwagger(RestRequest)}
*
*/
ResourceSwagger swagger() default @ResourceSwagger;
/**
* Optional servlet title.
*
*
* It is used to populate the Swagger title field.
*
This value can be retrieved programmatically through the {@link RestRequest#getResourceTitle()} method.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Corresponds to the swagger field
/info/title.
*
*
* See Also:
*
* - {@link RestInfoProvider#getTitle(RestRequest)}
*
*/
String[] title() default {};
/**
* Resource authority path.
*
*
* Overrides the authority path value for this resource and any child resources.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_uriAuthority}
*
*/
String uriAuthority() default "";
/**
* Resource context path.
*
*
* Overrides the context path value for this resource and any child resources.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_uriContext}
*
*/
String uriContext() default "";
/**
* URI-resolution relativity.
*
*
* Specifies how relative URIs should be interpreted by serializers.
*
*
* See {@link UriResolution} for possible values.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_uriRelativity}
*
*/
String uriRelativity() default "";
/**
* URI-resolution.
*
*
* Specifies how relative URIs should be interpreted by serializers.
*
*
* See {@link UriResolution} for possible values.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_uriResolution}
*
*/
String uriResolution() default "";
/**
* Configuration property: Use classpath resource caching.
*
*
* When enabled, resources retrieved via {@link RestRequest#getClasspathReaderResource(String, boolean)} (and related
* methods) will be cached in memory to speed subsequent lookups.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_useClasspathResourceCaching}
*
*/
String useClasspathResourceCaching() default "";
/**
* Use stack trace hashes.
*
*
* When enabled, the number of times an exception has occurred will be determined based on stack trace hashsums,
* made available through the {@link RestException#getOccurrence()} method.
*
*
Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_useStackTraceHashes}
*
*/
String useStackTraceHashes() default "";
/**
* Enable debug mode.
*
*
* Enables the following:
*
* - A message and stack trace is printed to STDERR when {@link BasicRestCallHandler#handleError(HttpServletRequest, HttpServletResponse, Throwable)} is called.
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@link RestContext#REST_debug}
*
*/
String debug() default "";
}