org.apache.juneau.rest.annotation

Annotation Type RestResource

@Documented
 @Target(value=TYPE)
 @Retention(value=RUNTIME)
 @Inherited
public @interface RestResource

Used to denote that a class is a REST resource and to associate metadata on it.

Usually used on a subclass of RestServlet, but can be used to annotate any class that you want to expose as a REST resource.

See Also:

• Overview > juneau-rest-server > @RestResource

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	allowBodyParam Allow body URL parameter.
String	allowedMethodParams Allowed method parameters.
String	allowHeaderParams Allow header URL parameters.
Class<?>[]	beanFilters Class-level bean filters.
Class<? extends RestCallHandler>	callHandler REST call handler.
Class<?>[]	children Children.
Class<? extends ClasspathResourceFinder>	classpathResourceFinder Classpath resource finder.
String	clientVersionHeader Client version header.
String	config Optional location of configuration file for this servlet.
String[]	consumes Supported content media types.
String	contextPath Resource context path.
Class<? extends RestConverter>[]	converters Class-level response converters.
String	defaultCharset Default character encoding.
String[]	defaultRequestHeaders Default request headers.
String[]	defaultResponseHeaders Default response headers.
String	description Optional servlet description.
Class<? extends Encoder>[]	encoders Compression encoders.
String[]	flags Shortcut for setting properties() of simple boolean types.
Class<? extends RestGuard>[]	guards Class-level guards.
HtmlDoc	htmldoc Provides HTML-doc-specific metadata on this method.
Class<? extends RestInfoProvider>	infoProvider Configuration property: REST info provider.
Class<? extends RestLogger>	logger REST logger.
String	maxInput The maximum allowed input size (in bytes) on HTTP requests.
String	messages Messages.
String[]	mimeTypes Configuration property: MIME types.
Class<? extends RestParam>[]	paramResolvers Java method parameter resolvers.
Class<? extends ParserListener>	parserListener Parser listener.
Class<? extends Parser>[]	parsers Parsers.
Class<? extends HttpPartParser>	partParser HTTP part parser.
Class<? extends HttpPartSerializer>	partSerializer HTTP part serializer.
String	path Resource path.
Class<?>[]	pojoSwaps Class-level POJO swaps.
String[]	produces Supported accept media types.
Property[]	properties Class-level properties.
String	renderResponseStackTraces Render response stack traces in responses.
Class<? extends RestResourceResolver>	resourceResolver REST resource resolver.
Class<? extends ResponseHandler>[]	responseHandlers Response handlers.
Class<? extends SerializerListener>	serializerListener Serializer listener.
Class<? extends Serializer>[]	serializers Serializers.
String	siteName Optional site name.
String[]	staticFileResponseHeaders Static file response headers.
String[]	staticFiles Static file mappings.
String[]	swagger Provides swagger-specific metadata on this resource.
String	title Optional servlet title.
String	useClasspathResourceCaching Configuration property: Use classpath resource caching.
String	useStackTraceHashes Use stack trace hashes.

Element Detail

allowBodyParam

public abstract String allowBodyParam

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 initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_allowBodyParam

Default:

""

allowedMethodParams

public abstract String allowedMethodParams

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 initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_allowedMethodParams

Default:

""

allowHeaderParams

public abstract String allowHeaderParams

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 initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_allowHeaderParams

Default:

""

beanFilters

public abstract Class<?>[] beanFilters

Class-level bean filters.

Shortcut to add bean filters to the bean contexts of the objects returned by the following methods:

• RestContext.getBeanContext()
• RestContext.getSerializers()
• RestContext.getParsers()

See Also:

• BeanContext.BEAN_beanFilters

Default:

{}

callHandler

public abstract Class<? extends RestCallHandler> callHandler

REST call handler.

This class handles the basic lifecycle of an HTTP REST call.

See Also:

• RestContext.REST_callHandler

Default:

org.apache.juneau.rest.RestCallHandler.Null.class

children

public abstract Class<?>[] children

Children.

Defines children of this resource.

See Also:

• RestContext.REST_children

Default:

{}

classpathResourceFinder

public abstract Class<? extends ClasspathResourceFinder> classpathResourceFinder

Classpath resource finder.

Used to retrieve localized files from the classpath.

See Also:

• RestContext.REST_classpathResourceFinder

Default:

org.apache.juneau.utils.ClasspathResourceFinder.Null.class

clientVersionHeader

public abstract String clientVersionHeader

Client version header.

Specifies the name of the header used to denote the client version on HTTP requests.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_clientVersionHeader

Default:

""

config

public abstract String config

Optional location of configuration file for this servlet.

The configuration file .

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContextBuilder.config(Config)

Default:

""

contextPath

public abstract String contextPath

Resource context path.

Overrides the context path value for this resource and any child resources.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_contextPath

Default:

""

converters

public abstract Class<? extends RestConverter>[] converters

Class-level response converters.

Associates one or more converters with a resource class.

See Also:

• RestContext.REST_converters

Default:

{}

defaultCharset

public abstract String defaultCharset

Default character encoding.

The default character encoding for the request and response if not specified on the request.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_defaultCharset

Default:

""

defaultRequestHeaders

public abstract String[] defaultRequestHeaders

Default request headers.

Specifies default values for request headers if they're not passed in through the request.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_defaultRequestHeaders

Default:

{}

defaultResponseHeaders

public abstract String[] defaultResponseHeaders

Default response headers.

Specifies default values for response headers if they're not set after the Java REST method is called.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_defaultResponseHeaders

Default:

{}

description

public abstract String description

Optional servlet description.

It is used to populate the Swagger description field.
This value can be retrieved programmatically through the RestRequest.getResourceDescription() method.

Notes:

• Supports initialization-time and request-time variables (e.g. "$L{my.localized.variable}").
• Corresponds to the swagger field /info/description.

See Also:

• RestInfoProvider.getDescription(RestRequest)

Default:

""

encoders

public abstract Class<? extends Encoder>[] encoders

Compression encoders.

These can be used to enable various kinds of compression (e.g. "gzip") on requests and responses.

See Also:

• RestContext.REST_encoders

Default:

{}

flags

public abstract String[] flags

Shortcut for setting properties() of simple boolean types.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").
• Setting a flag is equivalent to setting the same property to "true".

Default:

{}

guards

public abstract Class<? extends RestGuard>[] guards

Class-level guards.

Associates one or more RestGuards with all REST methods defined in this class.

See Also:

• RestContext.REST_guards

Default:

{}

htmldoc

public abstract HtmlDoc htmldoc

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:

• Overview > juneau-rest-server > @HtmlDoc

Default:

@org.apache.juneau.rest.annotation.HtmlDoc

infoProvider

public abstract Class<? extends RestInfoProvider> infoProvider

Configuration property: REST info provider.

Class used to retrieve title/description/swagger information about a resource.

See Also:

• RestContext.REST_infoProvider

Default:

org.apache.juneau.rest.RestInfoProvider.Null.class

logger

public abstract Class<? extends RestLogger> logger

REST logger.

Specifies the logger to use for logging.

See Also:

• RestContext.REST_logger

Default:

org.apache.juneau.rest.RestLogger.Null.class

maxInput

public abstract String maxInput

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 initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_maxInput

Default:

""

messages

public abstract String messages

Messages. Identifies the location of the resource bundle for this class.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_messages

Default:

""

mimeTypes

public abstract String[] mimeTypes

Configuration property: MIME types.

Defines MIME-type file type mappings.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_mimeTypes

Default:

{}

paramResolvers

public abstract Class<? extends RestParam>[] paramResolvers

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:

• RestContext.REST_paramResolvers

Default:

{}

parserListener

public abstract Class<? extends ParserListener> parserListener

Parser listener.

Specifies the parser listener class to use for listening to non-fatal parsing errors.

See Also:

• Parser.PARSER_listener

Default:

org.apache.juneau.parser.ParserListener.Null.class

parsers

public abstract Class<? extends Parser>[] parsers

Parsers.

Adds class-level parsers to this resource.

See Also:

• RestContext.REST_parsers

Default:

{}

partParser

public abstract Class<? extends HttpPartParser> partParser

HTTP part parser.

Specifies the HttpPartParser to use for parsing headers, query/form parameters, and URI parts.

See Also:

• RestContext.REST_partParser

Default:

org.apache.juneau.httppart.UonPartParser.class

partSerializer

public abstract Class<? extends HttpPartSerializer> partSerializer

HTTP part serializer.

Specifies the HttpPartSerializer to use for serializing headers, query/form parameters, and URI parts.

See Also:

• RestContext.REST_partSerializer

Default:

org.apache.juneau.httppart.SimpleUonPartSerializer.class

path

public abstract String path

Resource path.

Identifies the URL subpath relative to the parent resource.

See Also:

• RestContext.REST_path

Default:

""

pojoSwaps

public abstract Class<?>[] pojoSwaps

Class-level POJO swaps.

Shortcut to add POJO swaps to the bean contexts of the objects returned by the following methods:

• RestContext.getBeanContext()
• RestContext.getSerializers()
• RestContext.getParsers()

See Also:

• BeanContext.BEAN_pojoSwaps

Default:

{}

properties

public abstract Property[] properties

Class-level properties.

Shortcut for specifying class-level properties on this servlet to the objects returned by the following methods:

• RestContext.getBeanContext()
• RestContext.getSerializers()
• RestContext.getParsers()

Any of the properties defined on 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 RestResponse.prop(String, Object) method or through an RequestProperties method parameter.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContextBuilder.set(String,Object)
• RestContextBuilder.set(java.util.Map)

Default:

{}

renderResponseStackTraces

public abstract String renderResponseStackTraces

Render response stack traces in responses.

Render stack traces in HTTP response bodies when errors occur.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_renderResponseStackTraces

Default:

""

resourceResolver

public abstract Class<? extends RestResourceResolver> resourceResolver

REST resource resolver.

The resolver used for resolving child resources.

See Also:

• RestContext.REST_resourceResolver

Default:

org.apache.juneau.rest.RestResourceResolver.Null.class

responseHandlers

public abstract Class<? extends ResponseHandler>[] responseHandlers

Response handlers.

Specifies a list of ResponseHandler classes that know how to convert POJOs returned by REST methods or set via RestResponse.setOutput(Object) into appropriate HTTP responses.

See Also:

• RestContext.REST_responseHandlers

Default:

{}

serializerListener

public abstract Class<? extends SerializerListener> serializerListener

Serializer listener.

Specifies the serializer listener class to use for listening to non-fatal serialization errors.

See Also:

• Serializer.SERIALIZER_listener

Default:

org.apache.juneau.serializer.SerializerListener.Null.class

serializers

public abstract Class<? extends Serializer>[] serializers

Serializers.

Adds class-level serializers to this resource.

See Also:

• RestContext.REST_serializers

Default:

{}

siteName

public abstract String siteName

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 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 initialization-time and request-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestInfoProvider.getSiteName(RestRequest)

Default:

""

staticFileResponseHeaders

public abstract String[] staticFileResponseHeaders

Static file response headers.

Used to customize the headers on responses returned for statically-served files.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_staticFileResponseHeaders

Default:

{}

staticFiles

public abstract String[] staticFiles

Static file mappings.

Used to define paths and locations of statically-served files such as images or HTML documents.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_staticFiles

Default:

{}

produces

public abstract String[] produces

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 initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_produces

Default:

{}

consumes

public abstract String[] consumes

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 initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_consumes

Default:

{}

swagger

public abstract String[] swagger

Provides swagger-specific metadata on this resource.

Used to populate the auto-generated OPTIONS swagger documentation.

The format of this annotation is JSON when all individual parts are concatenated.
The starting and ending '{'/'}' characters around the entire value are optional.

Example:

@RestResource( path="/addressBook", // Swagger info. swagger={ "contact:{name:'John Smith',email:'john@smith.com'},", "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:

• RestInfoProvider.getSwagger(RestRequest)

Default:

{}

title

public abstract String title

Optional servlet title.

It is used to populate the Swagger title field.
This value can be retrieved programmatically through the RestRequest.getResourceTitle() method.

Notes:

• Supports initialization-time and request-time variables (e.g. "$L{my.localized.variable}").
• Corresponds to the swagger field /info/title.

See Also:

• RestInfoProvider.getTitle(RestRequest)

Default:

""

useClasspathResourceCaching

public abstract String useClasspathResourceCaching

Configuration property: Use classpath resource caching.

When enabled, resources retrieved via RestRequest.getClasspathReaderResource(String, boolean) (and related methods) will be cached in memory to speed subsequent lookups.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_useClasspathResourceCaching

Default:

""

useStackTraceHashes

public abstract String useStackTraceHashes

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 RestException.getOccurrence() method.

Notes:

• Supports initialization-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestContext.REST_useStackTraceHashes

Default:

""