Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,237 @@
+//
***************************************************************************************************************************
+// * 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 org.apache.juneau.rest.*;
+
+/**
+ * Extended annotation for {@link RestResource#swagger()
@RestResource.swagger()}.
+ */
+public @interface ResourceSwagger {
+ /**
+ * Optional servlet terms-of-service for this API.
+ *
+ * <p>
+ * It is used to populate the Swagger terms-of-service field.
+ *
+ * <p>
+ * The default value pulls the description from the
<code>termsOfService</code> entry in the servlet resource bundle.
+ * (e.g. <js>"termsOfService = foo"</js> or
<js>"MyServlet.termsOfService = foo"</js>).
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/info/termsOfService</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getTermsOfService(RestRequest)}
+ * method.
+ */
+ String termsOfService() default "";
+
+ /**
+ * Optional contact information for the exposed API.
+ *
+ * <p>
+ * It is used to populate the Swagger contact field and to display on
HTML pages.
+ *
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * name: string,
+ * url: string,
+ * email: string
+ * }
+ * </p>
+ *
+ * <p>
+ * The default value pulls the description from the
<code>contact</code> entry in the servlet resource bundle.
+ * (e.g. <js>"contact = {name:'John
Smith',email:'[email protected]'}"</js> or
+ * <js>"MyServlet.contact = {name:'John
Smith',email:'[email protected]'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ * contact=<js>"{name:'John
Smith',email:'[email protected]'}"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/info/contact</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getContact(RestRequest)} method.
+ */
+ String contact() default "";
+
+ /**
+ * Optional license information for the exposed API.
+ *
+ * <p>
+ * It is used to populate the Swagger license field and to display on
HTML pages.
+ *
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * name: string,
+ * url: string
+ * }
+ * </p>
+ *
+ * <p>
+ * The default value pulls the description from the
<code>license</code> entry in the servlet resource bundle.
+ * (e.g. <js>"license = {name:'Apache
2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js> or
+ * <js>"MyServlet.license = {name:'Apache
2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ * license=<js>"{name:'Apache
2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/info/license</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getLicense(RestRequest)} method.
+ */
+ String license() default "";
+
+ /**
+ * Provides the version of the application API (not to be confused with
the specification version).
+ *
+ * <p>
+ * It is used to populate the Swagger version field and to display on
HTML pages.
+ *
+ * <p>
+ * The default value pulls the description from the
<code>version</code> entry in the servlet resource bundle.
+ * (e.g. <js>"version = 2.0"</js> or <js>"MyServlet.version =
2.0"</js>).
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/info/version</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getVersion(RestRequest)} method.
+ */
+ String version() default "";
+
+ /**
+ * Optional tagging information for the exposed API.
+ *
+ * <p>
+ * It is used to populate the Swagger tags field and to display on HTML
pages.
+ *
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * [
+ * {
+ * name: string,
+ * description: string,
+ * externalDocs: {
+ * description: string,
+ * url: string
+ * }
+ * }
+ * ]
+ * </p>
+ *
+ * <p>
+ * The default value pulls the description from the <code>tags</code>
entry in the servlet resource bundle.
+ * (e.g. <js>"tags = [{name:'Foo',description:'Foobar'}]"</js> or
+ * <js>"MyServlet.tags = [{name:'Foo',description:'Foobar'}]"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ *
tags=<js>"[{name:'Foo',description:'Foobar'}]"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/tags</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getTags(RestRequest)} method.
+ */
+ String tags() default "";
+
+ /**
+ * Optional external documentation information for the exposed API.
+ *
+ * <p>
+ * It is used to populate the Swagger external documentation field and
to display on HTML pages.
+ *
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * description: string,
+ * url: string
+ * }
+ * </p>
+ *
+ * <p>
+ * The default value pulls the description from the
<code>externalDocs</code> entry in the servlet resource bundle.
+ * (e.g. <js>"externalDocs = {url:'http://juneau.apache.org'}"</js> or
+ * <js>"MyServlet.externalDocs =
{url:'http://juneau.apache.org'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ *
externalDocs=<js>"{url:'http://juneau.apache.org'}"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * See {@link RestContext#getVarResolver()} for the list of supported
variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/tags</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getExternalDocs(RestRequest)}
+ * method.
+ */
+ String externalDocs() default "";
+}
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,102 @@
+//
***************************************************************************************************************************
+// * 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 org.apache.juneau.rest.*;
+
+/**
+ * Annotation used in conjunction with {@link MethodSwagger#responses()} to
identify possible responses by the method.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"*"</js>,
+ * swagger=@ResourceSwagger(
+ * responses={
+ *
<ja>@Response</ja>(value=200,description=<js>"Everything was great."</js>),
+ *
<ja>@Response</ja>(value=404,description=<js>"File was not found."</js>)
+ * <ja>@Response</ja>(500),
+ * }
+ * )
+ * )
+ * <jk>public void</jk> doAnything(RestRequest req, RestResponse res,
<ja>@Method</ja> String method) {
+ * ...
+ * }
+ * </p>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Response {
+
+ /**
+ * HTTP response code.
+ */
+ int value();
+
+ /**
+ * Optional description.
+ *
+ * <p>
+ * The default value pulls the description from the
<code>description</code> entry in the servlet resource bundle.
+ * (e.g. <js>"myMethod.res.[code].description = foo"</js> or
+ * <js>"MyServlet.myMethod.res.[code].description = foo"</js>).
+ *
+ * <p>
+ * This field can contain variables (e.g. "$L{my.localized.variable}").
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field
<code>/paths/{path}/{method}/responses/{code}/description</code>.
+ */
+ String description() default "";
+
+ /**
+ * A definition of the response structure.
+ *
+ * <p>
+ * It can be a primitive, an array or an object.
+ * If this field does not exist, it means no content is returned as
part of the response.
+ * As an extension to the <a class="doclink"
href="http://swagger.io/specification/#schemaObject";>Schema Object</a>,
+ * its root type value may also be <js>"file"</js>.
+ * This SHOULD be accompanied by a relevant produces mime-type.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"*"</js>,
+ * swagger=@MethodSwagger(
+ * responses={
+ *
<ja>@Response</ja>(value=200,schema=<js>"{type:'string',description:'A
serialized Person bean.'}"</js>),
+ * }
+ * )
+ * </p>
+ */
+ String schema() default "";
+
+ /**
+ * Optional response headers.
+ *
+ * <p>
+ * Response variables can also be defined in the servlet resource
bundle.
+ * (e.g. <js>"myMethod.res.[code].[category].[name] = foo"</js> or
+ * <js>"MyServlet.myMethod.res.[code].[category].[name] = foo"</js>).
+ */
+ Parameter[] headers() default {};
+}
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestHook.java
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestHook.java
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestHook.java
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,86 @@
+//
***************************************************************************************************************************
+// * 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.*;
+
+/**
+ * Identifies Java methods on a resource/servlet class that get invoked during
particular lifecycle events of
+ * the servlet or REST call.
+ *
+ * <p>
+ * For example, if you want to add an initialization method to your resource:
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> MyResource {
+ *
+ * <jc>// Our database.</jc>
+ * <jk>private</jk> Map<Integer,Object> <jf>myDatabase</jf>;
+ *
+ * <ja>@RestHook</ja>(<jsf>INIT</jsf>)
+ * <jk>public void</jk> initMyDatabase(RestConfig config)
<jk>throws</jk> Exception {
+ * <jf>myDatabase</jf> = <jk>new</jk>
LinkedHashMap<>();
+ * }
+ * }
+ * </p>
+ *
+ * <p>
+ * Or if you want to intercept REST calls:
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> MyResource {
+ *
+ * <jc>// Add a request attribute to all incoming requests.</jc>
+ * <ja>@RestHook</ja>(<jsf>PRE_CALL</jsf>)
+ * <jk>public void</jk> onPreCall(RestRequest req) {
+ * req.setAttribute(<js>"foo"</js>, <js>"bar"</js>);
+ * }
+ * }
+ * </p>
+ *
+ * <p>
+ * The hook events can be broken down into two categories:
+ * <ul class='spaced-list'>
+ * <li>Resource lifecycle events:
+ * <ul>
+ * <li>{@link HookEvent#INIT INIT} - Right before
initialization.
+ * <li>{@link HookEvent#POST_INIT POST_INIT} - Right after
initialization.
+ * <li>{@link HookEvent#POST_INIT_CHILD_FIRST
POST_INIT_CHILD_FIRST} - Right after initialization, but run child methods
first.
+ * <li>{@link HookEvent#DESTROY DESTROY} - Right before
servlet destroy.
+ * </ul>
+ * <li>REST call lifecycle events:
+ * <ul>
+ * <li>{@link HookEvent#START_CALL START_CALL} - At the
beginning of a REST call.
+ * <li>{@link HookEvent#PRE_CALL PRE_CALL} - Right before
the <ja>@RestMethod</ja> method is invoked.
+ * <li>{@link HookEvent#POST_CALL POST_CALL} - Right after
the <ja>@RestMethod</ja> method is invoked.
+ * <li>{@link HookEvent#END_CALL END_CALL} - At the end of
the REST call after the response has been flushed.
+ * </ul>
+ * </ul>
+ *
+ * <p>
+ * See the {@link HookEvent} class for information about individual event
types.
+ */
+@Documented
+@Target(METHOD)
+@Retention(RUNTIME)
+@Inherited
+public @interface RestHook {
+
+ /**
+ * The lifecycle event.
+ */
+ HookEvent value();
+}
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestHook.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,633 @@
+//
***************************************************************************************************************************
+// * 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 org.apache.juneau.*;
+import org.apache.juneau.encoders.*;
+import org.apache.juneau.parser.*;
+import org.apache.juneau.remoteable.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.serializer.*;
+
+/**
+ * Identifies a REST Java method on a {@link RestServlet} implementation class.
+ * <p>
+ * Refer to <a class='doclink'
href='../package-summary.html#TOC'>org.apache.juneau.rest</a> doc for
information on using this class.
+ */
+@Documented
+@Target(METHOD)
+@Retention(RUNTIME)
+@Inherited
+public @interface RestMethod {
+
+ /**
+ * REST method name.
+ *
+ * <p>
+ * Typically <js>"GET"</js>, <js>"PUT"</js>, <js>"POST"</js>,
<js>"DELETE"</js>, or <js>"OPTIONS"</js>.
+ *
+ * <p>
+ * Method names are case-insensitive (always folded to upper-case).
+ *
+ * <p>
+ * Besides the standard HTTP method names, the following can also be
specified:
+ * <ul class='spaced-list'>
+ * <li>
+ * <js>"*"</js>
+ * - Denotes any method.
+ * <br>Use this if you want to capture any HTTP methods in
a single Java method.
+ * <br>The {@link Method @Method} annotation and/or {@link
RestRequest#getMethod()} method can be used to
+ * distinguish the actual HTTP method name.
+ * <li>
+ * <js>""</js>
+ * - Auto-detect.
+ * <br>The method name is determined based on the Java
method name.
+ * <br>For example, if the method is
<code>doPost(...)</code>, then the method name is automatically detected
+ * as <js>"POST"</js>.
+ * <br>Otherwise, defaults to <js>"GET"</js>.
+ * <li>
+ * <js>"PROXY"</js>
+ * - Remote-proxy interface.
+ * <br>This denotes a Java method that returns an object
(usually an interface, often annotated with the
+ * {@link Remoteable @Remoteable} annotation) to be used
as a remote proxy using
+ * <code>RestClient.getRemoteableProxy(Class<T>
interfaceClass, String url)</code>.
+ * <br>This allows you to construct client-side interface
proxies using REST as a transport medium.
+ * <br>Conceptually, this is simply a fancy
<code>POST</code> against the url <js>"/{path}/{javaMethodName}"</js>
+ * where the arguments are marshalled from the client to
the server as an HTTP body containing an array of
+ * objects, passed to the method as arguments, and then
the resulting object is marshalled back to the client.
+ * <li>
+ * Anything else
+ * - Overloaded non-HTTP-standard names that are passed in
through a <code>&method=methodName</code> URL
+ * parameter.
+ * </ul>
+ */
+ String name() default "";
+
+ /**
+ * Optional path pattern for the specified method.
+ *
+ * <p>
+ * Appending <js>"/*"</js> to the end of the path pattern will make it
match any remainder too.
+ * <br>Not appending <js>"/*"</js> to the end of the pattern will cause
a 404 (Not found) error to occur if the exact
+ * pattern is not found.
+ *
+ * <p>
+ * The path can contain variables that get resolved to {@link Path
@Path} parameters:
+ * <p class='bcode'>
+ * <jc>// Example 1</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
+ *
+ * <jc>// Example 2</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/myurl/{0}/{1}/{2}/*"</js>)
+ * </p>
+ *
+ * <p>
+ * Refer to {@link Path @Path} on how path variables get resolved.
+ */
+ String path() default "/*";
+
+ /**
+ * URL path pattern priority.
+ *
+ * <p>
+ * To force path patterns to be checked before other path patterns, use
a higher priority number.
+ *
+ * <p>
+ * By default, it's <code>0</code>, which means it will use an internal
heuristic to determine a best match.
+ */
+ int priority() default 0;
+
+ /**
+ * Method guards.
+ *
+ * <p>
+ * Associates one or more {@link RestGuard RestGuards} with a method
call.
+ * These guards get called immediately before execution of the REST
method.
+ *
+ * <p>
+ * Typically, guards will be used for permissions checking on the user
making the request, but it can also be used
+ * for other purposes like pre-call validation of a request.
+ */
+ Class<? extends RestGuard>[] guards() default {};
+
+ /**
+ * Method response converters.
+ *
+ * <p>
+ * Associates one or more {@link RestConverter RestConverters} with a
method call.
+ * These converters get called immediately after execution of the REST
method in the same order specified in the
+ * annotation.
+ *
+ * <p>
+ * Can be used for performing post-processing on the response object
before serialization.
+ *
+ * <p>
+ * Default converters are available in the <a class='doclink'
+ *
href='../converters/package-summary.html#TOC'>org.apache.juneau.rest.converters</a>
package.
+ */
+ Class<? extends RestConverter>[] converters() default {};
+
+ /**
+ * Method matchers.
+ *
+ * <p>
+ * Associates one more more {@link RestMatcher RestMatchers} with this
method.
+ *
+ * <p>
+ * Matchers are used to allow multiple Java methods to handle requests
assigned to the same URL path pattern, but
+ * differing based on some request attribute, such as a specific header
value.
+ *
+ * <p>
+ * See {@link RestMatcher} for details.
+ */
+ Class<? extends RestMatcher>[] matchers() default {};
+
+ /**
+ * Overrides the list of serializers assigned at the method level.
+ *
+ * <p>
+ * Use this annotation when the list of serializers assigned to a
method differs from the list of serializers
+ * assigned at the servlet level.
+ *
+ * <p>
+ * To append to the list of serializers assigned at the servlet level,
use
+ * <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>.
+ *
+ * <p class='bcode'>
+ * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
+ *
+ * <ja>@RestMethod</ja>(
+ * name=<js>"GET"</js>,
+ * path=<js>"/foo"</js>,
+ * serializers=MySpecialSerializer.<jk>class</jk>,
+ * serializersInherit=<jsf>SERIALIZERS</jsf>
+ * )
+ * <jk>public</jk> Object doGetWithSpecialAcceptType() {
+ * <jc>// Handle request for special Accept
type</jc>
+ * }
+ * }
+ * </p>
+ */
+ Class<? extends Serializer>[] serializers() default {};
+
+ /**
+ * Used in conjunction with {@link #serializers()} to identify what
class-level settings are inherited by the method
+ * serializer group.
+ *
+ * <p>
+ * Possible values:
+ * <ul>
+ * <li>{@link Inherit#SERIALIZERS} - Inherit class-level
serializers.
+ * <li>{@link Inherit#PROPERTIES} - Inherit class-level properties.
+ * <li>{@link Inherit#TRANSFORMS} - Inherit class-level transforms.
+ * </ul>
+ *
+ * <p>
+ * For example, to inherit all serializers, properties, and transforms
from the servlet class:
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * path=<js>"/foo"</js>,
+ * serializers=MySpecialSerializer.<jk>class</jk>,
+ *
serializersInherit={<jsf>SERIALIZERS</jsf>,<jsf>PROPERTIES</jsf>,<jsf>TRANSFORMS</jsf>}
+ * )
+ * </p>
+ */
+ Inherit[] serializersInherit() default {};
+
+ /**
+ * Overrides the list of parsers assigned at the method level.
+ *
+ * <p>
+ * Use this annotation when the list of parsers assigned to a method
differs from the list of parsers assigned at
+ * the servlet level.
+ *
+ * <p>
+ * To append to the list of serializers assigned at the servlet level,
use
+ * <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>.
+ *
+ * <p class='bcode'>
+ * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
+ *
+ * <ja>@RestMethod</ja>(
+ * name=<js>"PUT"</js>,
+ * path=<js>"/foo"</js>,
+ * parsers=MySpecialParser.<jk>class</jk>,
+ * parsersInherit=<jsf>PARSERS</jsf>
+ * )
+ * <jk>public</jk> Object doGetWithSpecialAcceptType() {
+ * <jc>// Handle request for special Accept
type</jc>
+ * }
+ * }
+ * </p>
+ */
+ Class<? extends Parser>[] parsers() default {};
+
+ /**
+ * Used in conjunction with {@link #parsers()} to identify what
class-level settings are inherited by the method
+ * parser group.
+ *
+ * <p>
+ * Possible values:
+ * <ul>
+ * <li>{@link Inherit#PARSERS} - Inherit class-level parsers.
+ * <li>{@link Inherit#PROPERTIES} - Inherit class-level properties.
+ * <li>{@link Inherit#TRANSFORMS} - Inherit class-level transforms.
+ * </ul>
+ *
+ * <p>
+ * For example, to inherit all parsers, properties, and transforms from
the servlet class:
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * path=<js>"/foo"</js>,
+ * parsers=MySpecialParser.<jk>class</jk>,
+ *
parsersInherit={<jsf>PARSERS</jsf>,<jsf>PROPERTIES</jsf>,<jsf>TRANSFORMS</jsf>}
+ * )
+ * </p>
+ */
+ Inherit[] parsersInherit() default {};
+
+ /**
+ * Appends to the list of {@link Encoder encoders} specified on the
servlet.
+ *
+ * <p>
+ * Use this annotation when the list of encoders assigned to a method
differs from the list of encoders assigned at
+ * the servlet level.
+ *
+ * <p>
+ * These can be used to enable various kinds of compression (e.g.
<js>"gzip"</js>) on requests and responses.
+ *
+ * <p class='bcode'>
+ * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
+ *
+ * <ja>@RestMethod</ja>(
+ * name=<js>"PUT"</js>,
+ * path=<js>"/foo"</js>,
+ * encoders={GzipEncoder.<jk>class</jk>}
+ * )
+ * <jk>public</jk> Object doGetWithSpecialEncoding() {
+ * <jc>// Handle request with special encoding</jc>
+ * }
+ * }
+ * </p>
+ *
+ * <p>
+ * If you want to OVERRIDE the set of encoders specified by the
servlet, combine this annotation with
+ * <code><ja>@RestMethod</ja>(inheritEncoders=<jk>false</jk>)</code>.
+ */
+ Class<? extends Encoder>[] encoders() default {};
+
+ /**
+ * Specifies whether the method should inherit encoders from the
servlet.
+ */
+ boolean inheritEncoders() default true;
+
+ /**
+ * Same as {@link RestResource#properties()}, except defines property
values by default when this method is called.
+ *
+ * <p>
+ * This is equivalent to simply calling
<code>res.addProperties()</code> in the Java method, but is provided for
+ * convenience.
+ */
+ Property[] properties() default {};
+
+ /**
+ * Shortcut for setting {@link #properties()} of simple boolean types.
+ *
+ * <p>
+ * Setting a flag is equivalent to setting the same property to
<js>"true"</js>.
+ */
+ String[] flags() default {};
+
+ /**
+ * Appends the specified bean filters to all serializers and parsers
used by this method.
+ */
+ Class<?>[] beanFilters() default {};
+
+ /**
+ * Appends the specified POJO swaps to all serializers and parsers used
by this method.
+ */
+ Class<?>[] pojoSwaps() default {};
+
+ /**
+ * Shortcut for specifying the {@link
BeanContext#BEAN_includeProperties} property on all serializers.
+ *
+ * <p>
+ * The typical use case is when you're rendering summary and details
views of the same bean in a resource and
+ * you want to expose or hide specific properties depending on the
level of detail you want.
+ *
+ * <p>
+ * In the example below, our 'summary' view is a list of beans where we
only want to show the ID property,
+ * and our detail view is a single bean where we want to expose
different fields:
+ * <p class='bcode'>
+ * <jc>// Our bean</jc>
+ * <jk>public class</jk> MyBean {
+ *
+ * <jc>// Summary properties</jc>
+ * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>)
+ * <jk>public</jk> String <jf>id</jf>;
+ *
+ * <jc>// Detail properties</jc>
+ * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>;
+ * }
+ *
+ * <jc>// Only render "id" property.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/mybeans"</js>, bpi=<js>"MyBean: id"</js>)
+ * <jk>public</jk> List<MyBean> getBeanSummary();
+ *
+ * <jc>// Only render "a" and "b" properties.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/mybeans/{id}"</js>, bpi=<js>"MyBean: a,b"</js>)
+ * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id);
+ * </p>
+ *
+ * <p>
+ * The format of each value is: <js>"Key: comma-delimited-tokens"</js>.
+ * <br>Keys can be fully-qualified or short class names or <js>"*"</js>
to represent all classes.
+ * <br>Values are comma-delimited lists of bean property names.
+ * <br>Properties apply to specified class and all subclasses.
+ *
+ * <p>
+ * Semicolons can be used as an additional separator for multiple
values:
+ * <p class='bcode'>
+ * <jc>// Equivalent</jc>
+ * bpi={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>}
+ * bpi=<js>"Bean1: foo; Bean2: bar,baz"</js>
+ * </p>
+ */
+ String[] bpi() default {};
+
+ /**
+ * Shortcut for specifying the {@link
BeanContext#BEAN_excludeProperties} property on all serializers.
+ *
+ * <p>
+ * Same as {@link #bpi()} except you specify a list of bean property
names that you want to exclude from
+ * serialization.
+ *
+ * <p>
+ * In the example below, our 'summary' view is a list of beans where we
want to exclude some properties:
+ * <p class='bcode'>
+ * <jc>// Our bean</jc>
+ * <jk>public class</jk> MyBean {
+ *
+ * <jc>// Summary properties</jc>
+ * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>)
+ * <jk>public</jk> String <jf>id</jf>;
+ *
+ * <jc>// Detail properties</jc>
+ * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>;
+ * }
+ *
+ * <jc>// Don't show "a" and "b" properties.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/mybeans"</js>, bpx=<js>"MyBean: a,b"</js>)
+ * <jk>public</jk> List<MyBean> getBeanSummary();
+ *
+ * <jc>// Render all properties.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/mybeans/{id}"</js>)
+ * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id);
+ * </p>
+ *
+ * <p>
+ * The format of each value is: <js>"Key: comma-delimited-tokens"</js>.
+ * <br>Keys can be fully-qualified or short class names or <js>"*"</js>
to represent all classes.
+ * <br>Values are comma-delimited lists of bean property names.
+ * <br>Properties apply to specified class and all subclasses.
+ *
+ * <p>
+ * Semicolons can be used as an additional separator for multiple
values:
+ * <p class='bcode'>
+ * <jc>// Equivalent</jc>
+ * bpx={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>}
+ * bpx=<js>"Bean1: foo; Bean2: bar,baz"</js>
+ * </p>
+ */
+ String[] bpx() default {};
+
+ /**
+ * Specifies default values for request headers.
+ *
+ * <p>
+ * Strings are of the format <js>"Header-Name: header-value"</js>.
+ *
+ * <p>
+ * Affects values returned by {@link RestRequest#getHeader(String)}
when the header is not present on the request.
+ *
+ * <p>
+ * The most useful reason for this annotation is to provide a default
<code>Accept</code> header when one is not
+ * specified so that a particular default {@link Serializer} is picked.
+ *
+ * <p>
+ * Only one header value can be specified per entry (i.e. it's not a
delimited list of header entries).
+ *
+ * <p>
+ * Header values specified at the method level override header values
specified at the servlet level.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Assume "text/json" Accept value when Accept not
specified</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/*"</js>,
defaultRequestHeaders={<js>"Accept: text/json"</js>})
+ * <jk>public</jk> String doGet() {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * You can use either <js>':'</js> or <js>'='</js> as the key/value
delimiter.
+ * Key and value is trimmed of whitespace.
+ */
+ String[] defaultRequestHeaders() default {};
+
+ /**
+ * Specifies default values for query parameters.
+ *
+ * <p>
+ * Strings are of the format <js>"name=value"</js>.
+ *
+ * <p>
+ * Affects values returned by {@link RestRequest#getQuery(String)} when
the parameter is not present on the request.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/*"</js>,
defaultQuery={<js>"foo=bar"</js>})
+ * <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"foo"</js>)
String foo) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * You can use either <js>':'</js> or <js>'='</js> as the key/value
delimiter.
+ * Key and value is trimmed of whitespace.
+ */
+ String[] defaultQuery() default {};
+
+ /**
+ * Specifies default values for form-data parameters.
+ *
+ * <p>
+ * Strings are of the format <js>"name=value"</js>.
+ *
+ * <p>
+ * Affects values returned by {@link RestRequest#getFormData(String)}
when the parameter is not present on the
+ * request.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/*"</js>,
defaultFormData={<js>"foo=bar"</js>})
+ * <jk>public</jk> String doGet(<ja>@FormData</ja>(<js>"foo"</js>)
String foo) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * You can use either <js>':'</js> or <js>'='</js> as the key/value
delimiter.
+ * Key and value is trimmed of whitespace.
+ */
+ String[] defaultFormData() default {};
+
+ /**
+ * Optional summary for the exposed API.
+ *
+ * <p>
+ * This summary is used in the following locations:
+ * <ul class='spaced-list'>
+ * <li>
+ * The value returned by {@link
RestRequest#getMethodSummary()}.
+ * <li>
+ * The <js>"$R{methodSummary}"</js> variable.
+ * <li>
+ * The summary of the method in the Swagger page.
+ * </ul>
+ *
+ * <p>
+ * The default value pulls the description from the
<code>(className.?)[javaMethodName].summary</code> entry in the
+ * servlet resource bundle. (e.g. <js>"MyClass.myMethod.summary =
foo"</js> or <js>"myMethod.summary = foo"</js>).
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field
<code>/paths/{path}/{method}/summary</code>.
+ */
+ String summary() default "";
+
+ /**
+ * Optional description for the exposed API.
+ *
+ * <p>
+ * This description is used in the following locations:
+ * <ul class='spaced-list'>
+ * <li>
+ * The value returned by {@link
RestRequest#getMethodDescription()}.
+ * <li>
+ * The <js>"$R{methodDescription}"</js> variable.
+ * <li>
+ * The description of the method in the Swagger page.
+ * </ul>
+ *
+ * <p>
+ * The default value pulls the description from the
<code>(className.?)[javaMethodName].description</code> entry in
+ * the servlet resource bundle. (e.g. <js>"MyClass.myMethod.description
= foo"</js> or
+ * <js>"myMethod.description = foo"</js>).
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field
<code>/paths/{path}/{method}/description</code>.
+ */
+ String description() default "";
+
+ /**
+ * Specifies whether this method can be called based on the client
version.
+ *
+ * <p>
+ * The client version is identified via the HTTP request header
identified by
+ * {@link RestResource#clientVersionHeader()} which by default is
<js>"X-Client-Version"</js>.
+ *
+ * <p>
+ * This is a specialized kind of {@link RestMatcher} that allows you to
invoke different Java methods for the same
+ * method/path based on the client version.
+ *
+ * <p>
+ * The format of the client version range is similar to that of OSGi
versions.
+ *
+ * <p>
+ * In the following example, the Java methods are mapped to the same
HTTP method and URL <js>"/foobar"</js>.
+ * <p class='bcode'>
+ * <jc>// Call this method if X-Client-Version is at least 2.0.
+ * // Note that this also matches 2.0.1.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>)
+ * <jk>public</jk> Object method1() {
+ * ...
+ * }
+ *
+ * <jc>// Call this method if X-Client-Version is at least 1.1,
but less than 2.0.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>)
+ * <jk>public</jk> Object method2() {
+ * ...
+ * }
+ *
+ * <jc>// Call this method if X-Client-Version is less than
1.1.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>)
+ * <jk>public</jk> Object method3() {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * It's common to combine the client version with transforms that will
convert new POJOs into older POJOs for
+ * backwards compatibility.
+ * <p class='bcode'>
+ * <jc>// Call this method if X-Client-Version is at least
2.0.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>)
+ * <jk>public</jk> NewPojo newMethod() {
+ * ...
+ * }
+ *
+ * <jc>// Call this method if X-Client-Version is at least 1.1,
but less than 2.0.</jc>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>,
path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>,
transforms={NewToOldPojoSwap.<jk>class</jk>})
+ * <jk>public</jk> NewPojo oldMethod() {
+ * <jk>return</jk> newMethod()
+ * }
+ *
+ * <p>
+ * Note that in the previous example, we're returning the exact same
POJO, but using a transform to convert it into
+ * an older form.
+ * The old method could also just return back a completely different
object.
+ * The range can be any of the following:
+ * <ul>
+ * <li><js>"[0,1.0)"</js> = Less than 1.0. 1.0 and 1.0.0 does not
match.
+ * <li><js>"[0,1.0]"</js> = Less than or equal to 1.0. Note that
1.0.1 will match.
+ * <li><js>"1.0"</js> = At least 1.0. 1.0 and 2.0 will match.
+ * </ul>
+ */
+ String clientVersion() default "";
+
+ /**
+ * Provides swagger-specific metadata on this method.
+ */
+ MethodSwagger swagger() default @MethodSwagger;
+
+ /**
+ * Provides HTML-doc-specific metadata on this method.
+ *
+ * <p>
+ * Information provided here overrides information provided in the
servlet-level annotation.
+ */
+ HtmlDoc htmldoc() default @HtmlDoc;
+}
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,763 @@
+//
***************************************************************************************************************************
+// * 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.encoders.Encoder;
+import org.apache.juneau.ini.*;
+import org.apache.juneau.json.*;
+import org.apache.juneau.parser.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.serializer.*;
+import org.apache.juneau.transform.*;
+import org.apache.juneau.utils.*;
+import org.apache.juneau.xml.*;
+
+/**
+ * Used to denote that a class is a REST resource and to associate metadata on
it.
+ *
+ * <p>
+ * 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.
+ *
+ * Refer to <a class='doclink'
href='../package-summary.html#TOC'>org.apache.juneau.rest</a> doc for
information on
+ * using this class.
+ */
+@Documented
+@Target(TYPE)
+@Retention(RUNTIME)
+@Inherited
+public @interface RestResource {
+
+ /**
+ * Identifies the location of the resource bundle for this class.
+ *
+ * <p>
+ * This annotation is used to provide localized messages for the
following methods:
+ * <ul>
+ * <li>{@link RestRequest#getMessage(String, Object...)}
+ * <li>{@link RestContext#getMessages()}
+ * </ul>
+ *
+ * <p>
+ * Refer to the {@link MessageBundle} class for a description of the
message key formats used in the properties file.
+ *
+ * <p>
+ * The value can be a relative path like <js>"nls/Messages"</js>,
indicating to look for the resource bundle
+ * <js>"com.foo.sample.nls.Messages"</js> if the resource class is in
<js>"com.foo.sample"</js>, or it can be an
+ * absolute path, like <js>"com.foo.sample.nls.Messages"</js>
+ */
+ String messages() default "";
+
+ /**
+ * Class-level guards.
+ *
+ * <p>
+ * Associates one or more {@link RestGuard RestGuards} with all REST
methods defined in this class.
+ * These guards get called immediately before execution of any REST
method in this class.
+ *
+ * <p>
+ * Typically, guards will be used for permissions checking on the user
making the request, but it can also be used
+ * for other purposes like pre-call validation of a request.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addGuards(Class...)}/
+ * {@link RestConfig#addGuards(RestGuard...)} methods.
+ */
+ Class<? extends RestGuard>[] guards() default {};
+
+ /**
+ * Class-level converters.
+ *
+ * <p>
+ * Associates one or more {@link RestConverter converters} with a
resource class.
+ * These converters get called immediately after execution of the REST
method in the same order specified in the
+ * annotation.
+ *
+ * <p>
+ * Can be used for performing post-processing on the response object
before serialization.
+ *
+ * <p>
+ * Default converter implementations are provided in the <a
class='doclink'
+ *
href='../converters/package-summary.html#TOC'>org.apache.juneau.rest.converters</a>
package.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addConverters(Class...)}/
+ * {@link RestConfig#addConverters(RestConverter...)} methods.
+ */
+ Class<? extends RestConverter>[] converters() default {};
+
+ /**
+ * Class-level bean filters.
+ *
+ * <p>
+ * Shortcut to add bean filters to the bean contexts of the objects
returned by the following methods:
+ * <ul>
+ * <li>{@link RestContext#getBeanContext()}
+ * <li>{@link RestContext#getSerializers()}
+ * <li>{@link RestContext#getParsers()}
+ * </ul>
+ *
+ * <p>
+ * If the specified class is an instance of {@link BeanFilterBuilder},
then a filter built from that builder is added.
+ * Any other classes are wrapped in a {@link
InterfaceBeanFilterBuilder} to indicate that subclasses should be
+ * treated as the specified class type.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestConfig#addBeanFilters(Class...)} method.
+ */
+ Class<?>[] beanFilters() default {};
+
+ /**
+ * Class-level POJO swaps.
+ *
+ * <p>
+ * Shortcut to add POJO swaps to the bean contexts of the objects
returned by the following methods:
+ * <ul>
+ * <li>{@link RestContext#getBeanContext()}
+ * <li>{@link RestContext#getSerializers()}
+ * <li>{@link RestContext#getParsers()}
+ * </ul>
+ *
+ * <p>
+ * If the specified class is an instance of {@link PojoSwap}, then that
swap is added.
+ * Any other classes are wrapped in a {@link SurrogateSwap}.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestConfig#addPojoSwaps(Class...)} method.
+ */
+ Class<?>[] pojoSwaps() default {};
+
+ /**
+ * Class-level Java method parameter resolvers.
+ *
+ * <p>
+ * By default, the Juneau framework will automatically Java method
parameters of various types (e.g.
+ * <code>RestRequest</code>, <code>Accept</code>, <code>Reader</code>).
+ * This annotation allows you to provide your own resolvers for your
own class types that you want resolved.
+ *
+ * <p>
+ * For example, if you want to pass in instances of
<code>MySpecialObject</code> to your Java method, define
+ * the following resolver:
+ * <p class='bcode'>
+ * <jk>public class</jk> MyRestParam <jk>extends</jk> RestParam {
+ *
+ * <jc>// Must have no-arg constructor!</jc>
+ * <jk>public</jk> MyRestParam() {
+ * <jc>// First two parameters help with Swagger
doc generation.</jc>
+ * <jk>super</jk>(<jsf>QUERY</jsf>,
<js>"myparam"</js>, MySpecialObject.<jk>class</jk>);
+ * }
+ *
+ * <jc>// The method that creates our object.
+ * // In this case, we're taking in a query parameter and
converting it to our object.</jc>
+ * <jk>public</jk> Object resolve(RestRequest req,
RestResponse res) <jk>throws</jk> Exception {
+ * <jk>return new</jk>
MySpecialObject(req.getQuery().get(<js>"myparam"</js>));
+ * }
+ * }
+ * </p>
+ *
+ * <p>
+ * <b>Note:</b>{@link RestParam} classes must have no-arg constructors.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestConfig#addParamResolvers(Class...)} method.
+ */
+ Class<? extends RestParam>[] paramResolvers() default {};
+
+ /**
+ * Class-level properties.
+ *
+ * <p>
+ * Shortcut for specifying class-level properties on this servlet to
the objects returned by the following methods:
+ * <ul>
+ * <li>{@link RestContext#getBeanContext()}
+ * <li>{@link RestContext#getSerializers()}
+ * <li>{@link RestContext#getParsers()}
+ * </ul>
+ * <p>
+ * Any of the following property names can be specified:
+ * <ul>
+ * <li>{@link RestContext}
+ * <li>{@link BeanContext}
+ * <li>{@link SerializerContext}
+ * <li>{@link ParserContext}
+ * <li>{@link JsonSerializerContext}
+ * <li>{@link XmlSerializerContext}
+ * <li>{@link XmlParserContext}
+ * </ul>
+ *
+ * <p>
+ * Property values will be converted to the appropriate type.
+ *
+ * <p>
+ * In some cases, properties can be overridden at runtime through the
+ * {@link RestResponse#setProperty(String, Object)} method or through a
{@link Properties @Properties} annotated
+ * method parameter.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#setProperty(String, Object)}/
+ * {@link RestConfig#setProperties(java.util.Map)} methods.
+ */
+ Property[] properties() default {};
+
+ /**
+ * Shortcut for setting {@link #properties()} of simple boolean types.
+ *
+ * <p>
+ * Setting a flag is equivalent to setting the same property to
<js>"true"</js>.
+ */
+ String[] flags() default {};
+
+ /**
+ * Specifies a list of {@link Serializer} classes to add to the list of
serializers available for this servlet.
+ *
+ * <p>
+ * This annotation can only be used on {@link Serializer} classes that
have no-arg constructors.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addSerializers(Class...)}/
+ * {@link RestConfig#addSerializers(Serializer...)} methods.
+ */
+ Class<? extends Serializer>[] serializers() default {};
+
+ /**
+ * Specifies a list of {@link Parser} classes to add to the list of
parsers available for this servlet.
+ *
+ * <p>
+ * This annotation can only be used on {@link Parser} classes that have
no-arg constructors.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addParsers(Class...)}/
+ * {@link RestConfig#addParsers(Parser...)} methods.
+ */
+ Class<? extends Parser>[] parsers() default {};
+
+ /**
+ * 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.
+ *
+ * <p>
+ * See {@link ResponseHandler} for details.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addResponseHandlers(Class...)}/
+ * {@link RestConfig#addResponseHandlers(ResponseHandler...)} methods.
+ */
+ Class<? extends ResponseHandler>[] responseHandlers() default {};
+
+ /**
+ * Specifies a list of {@link Encoder} to associate with this servlet.
+ *
+ * <p>
+ * These can be used to enable various kinds of compression (e.g.
<js>"gzip"</js>) on requests and responses.
+ *
+ * <p>
+ * This annotation can only be used on {@link Encoder} classes that
have no-arg constructors.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Servlet with automated support for GZIP compression</jc>
+ * <ja>@RestResource</ja>(encoders={GzipEncoder.<jk>class</jk>})
+ * <jk>public</jk> MyRestServlet <jk>extends</jk> RestServlet {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addEncoders(Class...)}/
+ * {@link RestConfig#addEncoders(Encoder...)} methods.
+ */
+ Class<? extends Encoder>[] encoders() default {};
+
+ /**
+ * Specifies default values for request headers.
+ *
+ * <p>
+ * Strings are of the format <js>"Header-Name: header-value"</js>.
+ *
+ * <p>
+ * Affects values returned by {@link RestRequest#getHeader(String)}
when the header is not present on the request.
+ *
+ * <p>
+ * The most useful reason for this annotation is to provide a default
<code>Accept</code> header when one is not
+ * specified so that a particular default {@link Serializer} is picked.
+ *
+ * <p>
+ * Only one header value can be specified per entry (i.e. it's not a
delimited list of header entries).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Assume "text/json" Accept value when Accept not
specified</jc>
+ * <ja>@RestResource</ja>(defaultRequestHeaders={<js>"Accept:
text/json"</js>})
+ * <jk>public</jk> MyRestServlet <jk>extends</jk> RestServlet {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addDefaultRequestHeader(String, Object)}/
+ * {@link RestConfig#addDefaultRequestHeaders(String...)} methods.
+ */
+ String[] defaultRequestHeaders() default {};
+
+ /**
+ * Specifies default values for response headers.
+ *
+ * <p>
+ * Strings are of the format <js>"Header-Name: header-value"</js>.
+ *
+ * <p>
+ * This is equivalent to calling {@link RestResponse#setHeader(String,
String)} programmatically in each of the Java
+ * methods.
+ *
+ * <p>
+ * The header value will not be set if the header value has already
been specified (hence the 'default' in the name).
+ *
+ * <p>
+ * Only one header value can be specified per entry (i.e. it's not a
delimited list of header entries).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Add a version header attribute to all responses</jc>
+ * <ja>@RestResource</ja>(defaultResponseHeaders={<js>"X-Version:
1.0"</js>})
+ * <jk>public</jk> MyRestServlet <jk>extends</jk> RestServlet {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addDefaultResponseHeader(String, Object)}/
+ * {@link RestConfig#addDefaultResponseHeaders(String...)} methods.
+ */
+ String[] defaultResponseHeaders() default {};
+
+ /**
+ * Defines children of this resource.
+ *
+ * <p>
+ * A REST child resource is simply another servlet that is initialized
as part of the parent resource and has a
+ * servlet path directly under the parent servlet path.
+ * The main advantage to defining servlets as REST children is that you
do not need to define them in the
+ * <code>web.xml</code> file of the web application.
+ * This can cut down on the number of entries that show up in the
<code>web.xml</code> file if you are defining
+ * large numbers of servlets.
+ *
+ * <p>
+ * Child resources must specify a value for {@link #path()} that
identifies the subpath of the child resource
+ * relative to the parent path.
+ *
+ * <p>
+ * It should be noted that servlets can be nested arbitrarily deep
using this technique (i.e. children can also have
+ * children).
+ *
+ * <dl>
+ * <dt>Servlet initialization:</dt>
+ * <dd>
+ * <p>
+ * A child resource will be initialized
immediately after the parent servlet is initialized.
+ * The child resource receives the same servlet
config as the parent resource.
+ * This allows configuration information such as
servlet initialization parameters to filter to child
+ * resources.
+ * </p>
+ * </dd>
+ * <dt>Runtime behavior:</dt>
+ * <dd>
+ * <p>
+ * As a rule, methods defined on the
<code>HttpServletRequest</code> object will behave as if the child
+ * servlet were deployed as a top-level resource
under the child's servlet path.
+ * For example, the <code>getServletPath()</code>
and <code>getPathInfo()</code> methods on the
+ * <code>HttpServletRequest</code> object will
behave as if the child resource were deployed using the
+ * child's servlet path.
+ * Therefore, the runtime behavior should be
equivalent to deploying the child servlet in the
+ * <code>web.xml</code> file of the web
application.
+ * </p>
+ * </dd>
+ * </dl>
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#addChildResource(String, Object)}/
+ * {@link RestConfig#addChildResources(Class...)}/{@link
RestConfig#addChildResources(Object...)} methods.
+ */
+ Class<?>[] children() default {};
+
+ /**
+ * Identifies the URL subpath relative to the parent resource.
+ *
+ * <p>
+ * Typically, this annotation is only applicable to resources defined
as children through the {@link #children()}
+ * annotation.
+ * However, it may be used in other ways (e.g. defining paths for
top-level resources in microservices).
+ *
+ * <p>
+ * This annotation is ignored on top-level servlets (i.e. servlets
defined in <code>web.xml</code> files).
+ * Therefore, implementers can optionally specify a path value for
documentation purposes.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestConfig#setPath(String)} method.
+ */
+ String path() default "";
+
+ /**
+ * Optional site name.
+ *
+ * <p>
+ * The site name is intended to be a title that can be applied to the
entire site.
+ *
+ * <p>
+ * This value can be retrieved programmatically through the {@link
RestRequest#getSiteName()} method.
+ *
+ * <p>
+ * 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:
+ * <p class='bcode'>
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * header={
+ * <js>"<h1>$R{siteName}</h1>"</js>,
+ * <js>"<h2>$R{servletTitle}</h2>"</js>
+ * }
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getSiteName(RestRequest)} method.
+ */
+ String siteName() default "";
+
+ /**
+ * Optional servlet title.
+ *
+ * <p>
+ * It is used to populate the Swagger title field.
+ * This value can be retrieved programmatically through the {@link
RestRequest#getServletTitle()} method.
+ *
+ * <p>
+ * The default value pulls the label from the <code>label</code> entry
in the servlet resource bundle.
+ * (e.g. <js>"title = foo"</js> or <js>"MyServlet.title = foo"</js>).
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/info/title</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getTitle(RestRequest)} method.
+ */
+ String title() default "";
+
+ /**
+ * Optional servlet description.
+ *
+ * <p>
+ * It is used to populate the Swagger description field.
+ * This value can be retrieved programmatically through the {@link
RestRequest#getServletDescription()} method.
+ *
+ * <p>
+ * The default value pulls the description from the
<code>description</code> entry in the servlet resource bundle.
+ * (e.g. <js>"description = foo"</js> or <js>"MyServlet.description =
foo"</js>).
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/info/description</code>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestInfoProvider#getDescription(RestRequest)} method.
+ */
+ String description() default "";
+
+ /**
+ * Optional location of configuration file for this servlet.
+ *
+ * <p>
+ * The configuration file .
+ *
+ * <p>
+ * This field can contain variables (e.g.
<js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of
supported variables.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestConfig#setConfigFile(ConfigFile)} method.
+ */
+ String config() default "";
+
+ /**
+ * The favicon to use for HTML views.
+ *
+ * <p>
+ * The name is a path to an icon file located in either the classpath
or working directory.
+ * The resulting favicon becomes available in the servlet via the URL
<js>"[servlet-path]/favicon.ico"</js>.
+ *
+ * <p>
+ * If the file cannot be located, the request to
<js>"[servlet-path]/favicon.ico"</js> will return
+ * {@link HttpServletResponse#SC_NOT_FOUND}.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jk>package</jk> com.foo.mypackage;
+ *
+ * <ja>@RestResource</ja>(
+ * favicon=<js>"mydocs/myicon.ico"</js>
+ * )
+ * <jk>public class</jk> MyResource <jk>extends</jk>
RestServletDefault {
+ * }
+ * </p>
+ *
+ * <p>
+ * In this example, the servlet will attempt to find the
<code>myicon.ico</code> file in the following ordered
+ * locations:
+ * <ol>
+ * <li><code>com.foo.mypackage.mydocs</code> package.
+ * <li><code>org.apache.juneau.rest.mydocs</code> package (since
<code>RestServletDefault</code> is in
+ * <code>org.apache.juneau.rest</code>).
+ * <li><code>[working-dir]/mydocs</code> directory.
+ * </ol>
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#setFavIcon(Object)}/
+ * {@link RestConfig#setFavIcon(Class, String)} methods.
+ */
+ String favicon() default "";
+
+ /**
+ * Defines paths and locations of statically served files.
+ *
+ * <p>
+ * This is a JSON map of paths to packages/directories located on
either the classpath or working directory.
+ *
+ * <p>
+ * Mappings are cumulative from parent to child. Child resources can
override mappings made on parent resources.
+ *
+ * <p>
+ * If the file cannot be located, the request will return {@link
HttpServletResponse#SC_NOT_FOUND}.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jk>package</jk> com.foo.mypackage;
+ *
+ * <ja>@RestResource</ja>(
+ * path=<js>"/myresource"</js>,
+ * staticFiles=<js>"{htdocs:'docs'}"</js>
+ * )
+ * <jk>public class</jk> MyResource <jk>extends</jk>
RestServletDefault {
+ * }
+ * </p>
+ *
+ * <p>
+ * In this example, given a GET request to
<code>/myresource/htdocs/foobar.html</code>, the servlet will attempt to
+ * find the <code>foobar.html</code> file in the following ordered
locations:
+ * <ol>
+ * <li><code>com.foo.mypackage.docs</code> package.
+ * <li><code>org.apache.juneau.rest.docs</code> package (since
<code>RestServletDefault</code> is in
+ * <code>org.apache.juneau.rest</code>).
+ * <li><code>[working-dir]/docs</code> directory.
+ * </ol>
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestConfig#addStaticFiles(Class, String)} method.
+ */
+ String staticFiles() default "";
+
+ /**
+ * Specifies the HTTP header name used to identify the client version.
+ *
+ * <p>
+ * The client version is used to support backwards compatibility for
breaking REST interface changes.
+ * Used in conjunction with {@link RestMethod#clientVersion()}
annotation.
+ *
+ * <p>
+ * If not specified, uses <js>"X-Client-Version"</js>.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link
RestConfig#setClientVersionHeader(String)} method.
+ */
+ String clientVersionHeader() default "";
+
+ /**
+ * Specifies the resolver class to use for resolving child resources by
class name.
+ *
+ * <p>
+ * The default implementation simply instantiates the class using one
of the following constructors:
+ * <ul>
+ * <li><code><jk>public</jk> T(RestConfig)</code>
+ * <li><code><jk>public</jk> T()</code>
+ * </ul>
+ *
+ * <p>
+ * The former constructor can be used to get access to the {@link
RestConfig} object to get access to the config
+ * file and initialization information or make programmatic
modifications to the resource before full initialization.
+ *
+ * <p>
+ * Non-<code>RestServlet</code> classes can also add the following two
methods to get access to the
+ * {@link RestConfig} and {@link RestContext} objects:
+ * <ul>
+ * <li><code><jk>public void</jk> init(RestConfig);</code>
+ * <li><code><jk>public void</jk> init(RestContext);</code>
+ * </ul>
+ *
+ * <p>
+ * Subclasses can be used to provide customized resolution of REST
resource class instances.
+ *
+ * <p>
+ * If not specified on a child resource, the resource resolver is
inherited from the parent resource context.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link
RestConfig#setResourceResolver(Class)}/
+ * {@link RestConfig#setResourceResolver(RestResourceResolver)} methods.
+ * <br>The value (class or instance) can also be set via the servlet
context attribute
+ * * {@link RestContext#REST_resourceResolver}.
+ */
+ Class<? extends RestResourceResolver> resourceResolver() default
RestResourceResolverSimple.class;
+
+ /**
+ * Specifies the logger class to use for logging.
+ *
+ * <p>
+ * The default logger performs basic error logging to the Java logger.
+ * Subclasses can be used to customize logging behavior on the resource.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setLogger(Class)}/{@link
RestConfig#setLogger(RestLogger)} methods.
+ */
+ Class<? extends RestLogger> logger() default RestLogger.Normal.class;
+
+ /**
+ * Specifies the REST call handler class.
+ *
+ * <p>
+ * This class handles the basic lifecycle of an HTTP REST call.
+ * Subclasses can be used to customize how these HTTP calls are handled.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setCallHandler(Class)}/{@link
RestConfig#setCallHandler(RestCallHandler)} methods.
+ */
+ Class<? extends RestCallHandler> callHandler() default
RestCallHandler.class;
+
+ /**
+ * Specifies the class used to retrieve title/description/swagger
information about a resource.
+ *
+ * <p>
+ * Subclasses can be used to customize the documentation on a resource.
+ *
+ * <p>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setInfoProvider(Class)}/{@link
RestConfig#setInfoProvider(RestInfoProvider)} methods.
+ */
+ Class<? extends RestInfoProvider> infoProvider() default
RestInfoProvider.class;
+
+ /**
+ * Specifies the serializer listener class to use for listening for
non-fatal errors.
+ */
+ Class<? extends SerializerListener> serializerListener() default
SerializerListener.class;
+
+ /**
+ * Specifies the parser listener class to use for listening for
non-fatal errors.
+ */
+ Class<? extends ParserListener> parserListener() default
ParserListener.class;
+
+ /**
+ * Provides swagger-specific metadata on this resource.
+ *
+ * <p>
+ * Used to populate the auto-generated OPTIONS swagger documentation.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * path=<js>"/addressBook"</js>,
+ *
+ * <jc>// Swagger info.</jc>
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * contact=<js>"{name:'John
Smith',email:'[email protected]'}"</js>,
+ * license=<js>"{name:'Apache
2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>,
+ * version=<js>"2.0"</js>,
+ * termsOfService=<js>"You're on your own."</js>,
+ * tags=<js>"[{name:'Java',description:'Java
utility',externalDocs:{description:'Home
page',url:'http://juneau.apache.org'}}]"</js>,
+ * externalDocs=<js>"{description:'Home
page',url:'http://juneau.apache.org'}"</js>
+ * )
+ * )
+ * </p>
+ */
+ ResourceSwagger swagger() default @ResourceSwagger;
+
+ /**
+ * Provides HTML-doc-specific metadata on this method.
+ *
+ * <p>
+ * Used to customize the output from the HTML Doc serializer.
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * path=<js>"/addressBook"</js>,
+ *
+ * <jc>// 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.</jc>
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * <jc>// Widgets for $W variables.</jc>
+ * widgets={
+ * PoweredByJuneau.<jk>class</jk>,
+ * ContentTypeLinks.<jk>class</jk>
+ * }
+ * links={
+ * <js>"up: request:/.."</js>,
+ * <js>"options:
servlet:/?method=OPTIONS"</js>,
+ * <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java"</js>,
+ * },
+ * aside={
+ * <js>"<div
style='max-width:400px;min-width:200px'>"</js>,
+ * <js>" <p>Proof-of-concept
resource that shows off the capabilities of working with POJO
resources.</p>"</js>,
+ * <js>" <p>Provides examples of:
</p>"</js>,
+ * <js>" <ul>"</js>,
+ * <js>" <li>XML
and RDF namespaces"</js>,
+ * <js>"
<li>Swagger documentation"</js>,
+ * <js>"
<li>Widgets"</js>,
+ * <js>" </ul>"</js>,
+ * <js>" <p
style='text-weight:bold;text-decoration:underline;'>Available Content
Types</p>"</js>,
+ * <js>" $W{ContentTypeLinks}"</js>,
+ * <js>"</div>"</js>
+ * },
+ * footer=<js>"$W{PoweredByJuneau}"</js>
+ * )
+ * )
+ * </p>
+ */
+ HtmlDoc htmldoc() default @HtmlDoc;
+
+ /**
+ * Overrides the context path value for this resource and any child
resources.
+ *
+ * <p>
+ * This setting is useful if you want to use
<js>"context:/child/path"</js> URLs in child resource POJOs but
+ * the context path is not actually specified on the servlet container.
+ * The net effect is that the {@link RestRequest#getContextPath()} and
{@link RestRequest#getServletPath()} methods
+ * will return this value instead of the actual context path of the web
app.
+ */
+ String contextPath() default "";
+}
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/package.html
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/package.html
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/package.html
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,41 @@
+<!DOCTYPE HTML>
+<!--
+/***************************************************************************************************************************
+ * 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.
+ *
+
***************************************************************************************************************************/
+ -->
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <style type="text/css">
+ /* For viewing in Page Designer */
+ @IMPORT url("../../../../javadoc.css");
+
+ /* For viewing in REST interface */
+ @IMPORT url("../htdocs/javadoc.css");
+ body {
+ margin: 20px;
+ }
+ </style>
+ <script>
+ /* Replace all @code and @link tags. */
+ window.onload = function() {
+ document.body.innerHTML =
document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
+ document.body.innerHTML =
document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g,
'<code>$3</code>');
+ }
+ </script>
+</head>
+<body>
+<p>REST servlet annotations</p>
+</body>
+</html>
\ No newline at end of file
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/package.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,71 @@
+//
***************************************************************************************************************************
+// * 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.converters;
+
+import static javax.servlet.http.HttpServletResponse.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.json.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.transform.*;
+import org.apache.juneau.utils.*;
+
+/**
+ * Converter for enablement of {@link PojoIntrospector} support on response
objects returned by a
+ * <code>@RestMethod</code> method.
+ *
+ * <p>
+ * When enabled, public methods can be called on objects returned through the
{@link RestResponse#setOutput(Object)}
+ * method.
+ *
+ * <p>
+ * Note that opening up public methods for calling through a REST interface
can be dangerous, and should be done with
+ * caution.
+ *
+ * <p>
+ * Java methods are invoked by passing in the following URL parameters:
+ * <ul class='spaced-list'>
+ * <li>
+ * <code>&invokeMethod</code> - The Java method name,
optionally with arguments if necessary to
+ * differentiate between methods.
+ * <li>
+ * <code>&invokeArgs</code> - The arguments as a JSON array.
+ * </ul>
+ *
+ * <p>
+ * See {@link PojoIntrospector} for additional information on introspection of
POJO methods.
+ */
+public final class Introspectable implements RestConverter {
+
+ @Override /* RestConverter */
+ @SuppressWarnings({"unchecked", "rawtypes"})
+ public Object convert(RestRequest req, Object o, ClassMeta cm) throws
RestException {
+ String method = req.getQuery().getString("invokeMethod");
+ String args = req.getQuery().getString("invokeArgs");
+ if (method == null)
+ return o;
+ try {
+ BeanSession bs = req.getBeanSession();
+ PojoSwap swap = cm.getPojoSwap(bs);
+ if (swap != null)
+ o = swap.swap(bs, o);
+ return new PojoIntrospector(o,
JsonParser.DEFAULT).invokeMethod(method, args);
+ } catch (Exception e) {
+ e.printStackTrace();
+ return new RestException(SC_INTERNAL_SERVER_ERROR,
+ "Error occurred trying to invoke method: {0}",
+ e.getLocalizedMessage()
+ ).initCause(e);
+ }
+ }
+}
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
==============================================================================
---
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
(added)
+++
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
Fri Sep 8 23:25:34 2017
@@ -0,0 +1,71 @@
+//
***************************************************************************************************************************
+// * 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.converters;
+
+import org.apache.juneau.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.utils.*;
+
+/**
+ * Converter for enabling of {@link PojoQuery} support on response objects
returned by a <code>@RestMethod</code> method.
+ *
+ * <p>
+ * When enabled, objects in a POJO tree can be filtered using the
functionality described in the {@link PojoQuery}
+ * class.
+ *
+ * <p>
+ * The following HTTP request parameters are available for tabular data (e.g.
{@code Collections} of {@code Maps},
+ * arrays of beans, etc...):
+ * <ul class='spaced-list'>
+ * <li>
+ * <code>&s=</code> Search arguments.
+ * <br>Comma-delimited list of key/value pairs representing column
names and search tokens.
+ * <br>Example: <js>"&s=name=Bill*,birthDate>2000"</js>
+ * <li>
+ * <code>&v=</code> Visible columns.
+ * <br>Comma-delimited list of column names to display.
+ * <br>Example: <js>"&v=name,birthDate"</js>
+ * <li>
+ * <code>&o=</code> Sort commands.
+ * <br>Comma-delimited list of columns to sort by.
+ * <br>Column names can be suffixed with <js>'+'</js> or
<js>'-'</js> to indicate ascending or descending order.
+ * <br>The default is ascending order.
+ * <br>Example: <js>"&o=name,birthDate-"</js>
+ * <li>
+ * <code>&i=</code> Case-insensitive parameter.
+ * <br>Boolean flag for case-insensitive matching on the search
parameters.
+ * <li>
+ * <code>&p=</code> - Position parameter.
+ * <br>Only return rows starting at the specified index position
(zero-indexed).
+ * <br>Default is {@code 0}.
+ * <li>
+ * <code>&l=</code> Limit parameter.
+ * <br>Only return the specified number of rows.
+ * <br>Default is {@code 0} (meaning return all rows).
+ * </ul>
+ *
+ * <p>
+ * See {@link PojoQuery} for additional information on filtering POJO models.
+ */
+public final class Queryable implements RestConverter {
+
+ @Override /* RestConverter */
+ public Object convert(RestRequest req, Object o, ClassMeta<?> cm) {
+ if (o == null)
+ return null;
+ SearchArgs searchArgs = req.getQuery().getSearchArgs();
+ if (searchArgs == null)
+ return o;
+ return new PojoQuery(o,
req.getBeanSession()).filter(searchArgs);
+ }
+}
Propchange:
release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
