Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 1AF2A200CEC for ; Tue, 11 Jul 2017 03:33:46 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 1962F164C8A; Tue, 11 Jul 2017 01:33:46 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id C4199164C96 for ; Tue, 11 Jul 2017 03:33:43 +0200 (CEST) Received: (qmail 39264 invoked by uid 500); 11 Jul 2017 01:33:43 -0000 Mailing-List: contact commits-help@juneau.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@juneau.incubator.apache.org Delivered-To: mailing list commits@juneau.incubator.apache.org Received: (qmail 39255 invoked by uid 99); 11 Jul 2017 01:33:42 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 11 Jul 2017 01:33:42 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 55F871948A7 for ; Tue, 11 Jul 2017 01:33:42 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -5.022 X-Spam-Level: X-Spam-Status: No, score=-5.022 tagged_above=-999 required=6.31 tests=[RCVD_IN_DNSWL_HI=-5, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-0.001, SPF_PASS=-0.001] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id CB8H7HSg-55M for ; Tue, 11 Jul 2017 01:33:31 +0000 (UTC) Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with SMTP id 4E6F16261C for ; Tue, 11 Jul 2017 01:33:26 +0000 (UTC) Received: (qmail 38964 invoked by uid 99); 11 Jul 2017 01:33:26 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 11 Jul 2017 01:33:26 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 4CD01E961F; Tue, 11 Jul 2017 01:33:25 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: jamesbognar@apache.org To: commits@juneau.incubator.apache.org Date: Tue, 11 Jul 2017 01:33:29 -0000 Message-Id: In-Reply-To: <366103f89d774546a3e5581bda6a2249@git.apache.org> References: <366103f89d774546a3e5581bda6a2249@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [05/30] incubator-juneau-website git commit: Update javadocs archived-at: Tue, 11 Jul 2017 01:33:46 -0000 http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/9b48e212/content/site/apidocs/src-html/org/apache/juneau/rest/annotation/RestMethod.html ---------------------------------------------------------------------- diff --git a/content/site/apidocs/src-html/org/apache/juneau/rest/annotation/RestMethod.html b/content/site/apidocs/src-html/org/apache/juneau/rest/annotation/RestMethod.html index 1de5e03..1a83b92 100644 --- a/content/site/apidocs/src-html/org/apache/juneau/rest/annotation/RestMethod.html +++ b/content/site/apidocs/src-html/org/apache/juneau/rest/annotation/RestMethod.html @@ -30,486 +30,486 @@ 022import org.apache.juneau.parser.*; 023import org.apache.juneau.remoteable.*; 024import org.apache.juneau.rest.*; -025import org.apache.juneau.rest.widget.*; -026import org.apache.juneau.serializer.*; -027 -028/** -029 * Identifies a REST Java method on a {@link RestServlet} implementation class. -030 * <p> -031 * Refer to <a class='doclink' href='../package-summary.html#TOC'>org.apache.juneau.rest</a> doc for information on using this class. -032 */ -033@Documented -034@Target(METHOD) -035@Retention(RUNTIME) -036@Inherited -037public @interface RestMethod { -038 -039 /** -040 * REST method name. -041 * -042 * <p> -043 * Typically <js>"GET"</js>, <js>"PUT"</js>, <js>"POST"</js>, <js>"DELETE"</js>, or <js>"OPTIONS"</js>. -044 * -045 * <p> -046 * Method names are case-insensitive (always folded to upper-case). -047 * -048 * <p> -049 * Besides the standard HTTP method names, the following can also be specified: -050 * <ul class='spaced-list'> -051 * <li> -052 * <js>"*"</js> -053 * - Denotes any method. -054 * <br>Use this if you want to capture any HTTP methods in a single Java method. -055 * <br>The {@link Method @Method} annotation and/or {@link RestRequest#getMethod()} method can be used to -056 * distinguish the actual HTTP method name. -057 * <li> -058 * <js>""</js> -059 * - Auto-detect. -060 * <br>The method name is determined based on the Java method name. -061 * <br>For example, if the method is <code>doPost(...)</code>, then the method name is automatically detected -062 * as <js>"POST"</js>. -063 * <br>Otherwise, defaults to <js>"GET"</js>. -064 * <li> -065 * <js>"PROXY"</js> -066 * - Remote-proxy interface. -067 * <br>This denotes a Java method that returns an object (usually an interface, often annotated with the -068 * {@link Remoteable @Remoteable} annotation) to be used as a remote proxy using -069 * <code>RestClient.getRemoteableProxy(Class&lt;T&gt; interfaceClass, String url)</code>. -070 * <br>This allows you to construct client-side interface proxies using REST as a transport medium. -071 * <br>Conceptually, this is simply a fancy <code>POST</code> against the url <js>"/{path}/{javaMethodName}"</js> -072 * where the arguments are marshalled from the client to the server as an HTTP body containing an array of -073 * objects, passed to the method as arguments, and then the resulting object is marshalled back to the client. -074 * <li> -075 * Anything else -076 * - Overloaded non-HTTP-standard names that are passed in through a <code>&amp;method=methodName</code> URL -077 * parameter. -078 * </ul> -079 */ -080 String name() default ""; -081 -082 /** -083 * Optional path pattern for the specified method. -084 * -085 * <p> -086 * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too. -087 * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact -088 * pattern is not found. -089 * -090 * <p> -091 * The path can contain variables that get resolved to {@link Path @Path} parameters: -092 * <p class='bcode'> -093 * <jc>// Example 1</jc> -094 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>) -095 * -096 * <jc>// Example 2</jc> -097 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{0}/{1}/{2}/*"</js>) -098 * </p> -099 * -100 * <p> -101 * Refer to {@link Path @Path} on how path variables get resolved. -102 */ -103 String path() default "/*"; -104 -105 /** -106 * URL path pattern priority. -107 * -108 * <p> -109 * To force path patterns to be checked before other path patterns, use a higher priority number. -110 * -111 * <p> -112 * By default, it's <code>0</code>, which means it will use an internal heuristic to determine a best match. -113 */ -114 int priority() default 0; -115 -116 /** -117 * Method guards. -118 * -119 * <p> -120 * Associates one or more {@link RestGuard RestGuards} with a method call. -121 * These guards get called immediately before execution of the REST method. -122 * -123 * <p> -124 * Typically, guards will be used for permissions checking on the user making the request, but it can also be used -125 * for other purposes like pre-call validation of a request. -126 */ -127 Class<? extends RestGuard>[] guards() default {}; -128 -129 /** -130 * Method response converters. -131 * -132 * <p> -133 * Associates one or more {@link RestConverter RestConverters} with a method call. -134 * These converters get called immediately after execution of the REST method in the same order specified in the -135 * annotation. -136 * -137 * <p> -138 * Can be used for performing post-processing on the response object before serialization. -139 * -140 * <p> -141 * Default converters are available in the <a class='doclink' -142 * href='../converters/package-summary.html#TOC'>org.apache.juneau.rest.converters</a> package. -143 */ -144 Class<? extends RestConverter>[] converters() default {}; -145 -146 /** -147 * Method matchers. -148 * -149 * <p> -150 * Associates one more more {@link RestMatcher RestMatchers} with this method. -151 * -152 * <p> -153 * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but -154 * differing based on some request attribute, such as a specific header value. -155 * -156 * <p> -157 * See {@link RestMatcher} for details. -158 */ -159 Class<? extends RestMatcher>[] matchers() default {}; -160 -161 /** -162 * Overrides the list of serializers assigned at the method level. -163 * -164 * <p> -165 * Use this annotation when the list of serializers assigned to a method differs from the list of serializers -166 * assigned at the servlet level. -167 * -168 * <p> -169 * To append to the list of serializers assigned at the servlet level, use -170 * <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>. -171 * -172 * <p class='bcode'> -173 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { -174 * -175 * <ja>@RestMethod</ja>( -176 * name=<js>"GET"</js>, -177 * path=<js>"/foo"</js>, -178 * serializers=MySpecialSerializer.<jk>class</jk>, -179 * serializersInherit=<jsf>SERIALIZERS</jsf> -180 * ) -181 * <jk>public</jk> Object doGetWithSpecialAcceptType() { -182 * <jc>// Handle request for special Accept type</jc> -183 * } -184 * } -185 * </p> -186 */ -187 Class<? extends Serializer>[] serializers() default {}; -188 -189 /** -190 * Used in conjunction with {@link #serializers()} to identify what class-level settings are inherited by the method -191 * serializer group. -192 * -193 * <p> -194 * Possible values: -195 * <ul> -196 * <li>{@link Inherit#SERIALIZERS} - Inherit class-level serializers. -197 * <li>{@link Inherit#PROPERTIES} - Inherit class-level properties. -198 * <li>{@link Inherit#TRANSFORMS} - Inherit class-level transforms. -199 * </ul> -200 * -201 * <p> -202 * For example, to inherit all serializers, properties, and transforms from the servlet class: -203 * <p class='bcode'> -204 * <ja>@RestMethod</ja>( -205 * path=<js>"/foo"</js>, -206 * serializers=MySpecialSerializer.<jk>class</jk>, -207 * serializersInherit={<jsf>SERIALIZERS</jsf>,<jsf>PROPERTIES</jsf>,<jsf>TRANSFORMS</jsf>} -208 * ) -209 * </p> -210 */ -211 Inherit[] serializersInherit() default {}; -212 -213 /** -214 * Overrides the list of parsers assigned at the method level. -215 * -216 * <p> -217 * Use this annotation when the list of parsers assigned to a method differs from the list of parsers assigned at -218 * the servlet level. -219 * -220 * <p> -221 * To append to the list of serializers assigned at the servlet level, use -222 * <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>. -223 * -224 * <p class='bcode'> -225 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { -226 * -227 * <ja>@RestMethod</ja>( -228 * name=<js>"PUT"</js>, -229 * path=<js>"/foo"</js>, -230 * parsers=MySpecialParser.<jk>class</jk>, -231 * parsersInherit=<jsf>PARSERS</jsf> -232 * ) -233 * <jk>public</jk> Object doGetWithSpecialAcceptType() { -234 * <jc>// Handle request for special Accept type</jc> -235 * } -236 * } -237 * </p> -238 */ -239 Class<? extends Parser>[] parsers() default {}; -240 -241 /** -242 * Used in conjunction with {@link #parsers()} to identify what class-level settings are inherited by the method -243 * parser group. -244 * -245 * <p> -246 * Possible values: -247 * <ul> -248 * <li>{@link Inherit#PARSERS} - Inherit class-level parsers. -249 * <li>{@link Inherit#PROPERTIES} - Inherit class-level properties. -250 * <li>{@link Inherit#TRANSFORMS} - Inherit class-level transforms. -251 * </ul> -252 * -253 * <p> -254 * For example, to inherit all parsers, properties, and transforms from the servlet class: -255 * <p class='bcode'> -256 * <ja>@RestMethod</ja>( -257 * path=<js>"/foo"</js>, -258 * parsers=MySpecialParser.<jk>class</jk>, -259 * parsersInherit={<jsf>PARSERS</jsf>,<jsf>PROPERTIES</jsf>,<jsf>TRANSFORMS</jsf>} -260 * ) -261 * </p> -262 */ -263 Inherit[] parsersInherit() default {}; -264 -265 /** -266 * Appends to the list of {@link Encoder encoders} specified on the servlet. -267 * -268 * <p> -269 * Use this annotation when the list of encoders assigned to a method differs from the list of encoders assigned at -270 * the servlet level. -271 * -272 * <p> -273 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. -274 * -275 * <p class='bcode'> -276 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { -277 * -278 * <ja>@RestMethod</ja>( -279 * name=<js>"PUT"</js>, -280 * path=<js>"/foo"</js>, -281 * encoders={GzipEncoder.<jk>class</jk>} -282 * ) -283 * <jk>public</jk> Object doGetWithSpecialEncoding() { -284 * <jc>// Handle request with special encoding</jc> -285 * } -286 * } -287 * </p> -288 * -289 * <p> -290 * If you want to OVERRIDE the set of encoders specified by the servlet, combine this annotation with -291 * <code><ja>@RestMethod</ja>(inheritEncoders=<jk>false</jk>)</code>. -292 */ -293 Class<? extends Encoder>[] encoders() default {}; -294 -295 /** -296 * Specifies whether the method should inherit encoders from the servlet. -297 */ -298 boolean inheritEncoders() default true; -299 -300 /** -301 * Same as {@link RestResource#properties()}, except defines property values by default when this method is called. -302 * -303 * <p> -304 * This is equivalent to simply calling <code>res.addProperties()</code> in the Java method, but is provided for -305 * convenience. -306 */ -307 Property[] properties() default {}; -308 -309 /** -310 * Shortcut for setting {@link #properties()} of simple boolean types. -311 * -312 * <p> -313 * Setting a flag is equivalent to setting the same property to <js>"true"</js>. -314 */ -315 String[] flags() default {}; -316 -317 /** -318 * Appends the specified bean filters to all serializers and parsers used by this method. -319 */ -320 Class<?>[] beanFilters() default {}; -321 -322 /** -323 * Appends the specified POJO swaps to all serializers and parsers used by this method. -324 */ -325 Class<?>[] pojoSwaps() default {}; -326 -327 /** -328 * Shortcut for specifying the {@link BeanContext#BEAN_includeProperties} property on all serializers. -329 * -330 * <p> -331 * The typical use case is when you're rendering summary and details views of the same bean in a resource and -332 * you want to expose or hide specific properties depending on the level of detail you want. -333 * -334 * <p> -335 * In the example below, our 'summary' view is a list of beans where we only want to show the ID property, -336 * and our detail view is a single bean where we want to expose different fields: -337 * <p class='bcode'> -338 * <jc>// Our bean</jc> -339 * <jk>public class</jk> MyBean { -340 * -341 * <jc>// Summary properties</jc> -342 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) -343 * <jk>public</jk> String <jf>id</jf>; -344 * -345 * <jc>// Detail properties</jc> -346 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; -347 * } -348 * -349 * <jc>// Only render "id" property.</jc> -350 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans"</js>, bpIncludes=<js>"{MyBean:'id'}"</js>) -351 * <jk>public</jk> List&lt;MyBean&gt; getBeanSummary(); -352 * -353 * <jc>// Only render "a" and "b" properties.</jc> -354 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans/{id}"</js>, bpIncludes=<js>"{MyBean:'a,b'}"</js>) -355 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id); -356 * </p> -357 * -358 * <p> -359 * The format of this value is a lax JSON object. -360 * <br>Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. -361 * <br>Values are comma-delimited lists of bean property names. -362 * <br>Properties apply to specified class and all subclasses. -363 */ -364 String bpIncludes() default ""; -365 -366 /** -367 * Shortcut for specifying the {@link BeanContext#BEAN_excludeProperties} property on all serializers. -368 * -369 * <p> -370 * Same as {@link #bpIncludes()} except you specify a list of bean property names that you want to exclude from -371 * serialization. -372 * -373 * <p> -374 * In the example below, our 'summary' view is a list of beans where we want to exclude some properties: -375 * <p class='bcode'> -376 * <jc>// Our bean</jc> -377 * <jk>public class</jk> MyBean { -378 * -379 * <jc>// Summary properties</jc> -380 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) -381 * <jk>public</jk> String <jf>id</jf>; -382 * -383 * <jc>// Detail properties</jc> -384 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; -385 * } -386 * -387 * <jc>// Don't show "a" and "b" properties.</jc> -388 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans"</js>, bpExcludes=<js>"{MyBean:'a,b'}"</js>) -389 * <jk>public</jk> List&lt;MyBean&gt; getBeanSummary(); -390 * -391 * <jc>// Render all properties.</jc> -392 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans/{id}"</js>) -393 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id); -394 * </p> -395 * -396 * <p> -397 * The format of this value is a lax JSON object. -398 * <br>Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. -399 * <br>Values are comma-delimited lists of bean property names. -400 * <br>Properties apply to specified class and all subclasses. -401 */ -402 String bpExcludes() default ""; -403 -404 /** -405 * Specifies default values for request headers. -406 * -407 * <p> -408 * Strings are of the format <js>"Header-Name: header-value"</js>. -409 * -410 * <p> -411 * Affects values returned by {@link RestRequest#getHeader(String)} when the header is not present on the request. -412 * -413 * <p> -414 * The most useful reason for this annotation is to provide a default <code>Accept</code> header when one is not -415 * specified so that a particular default {@link Serializer} is picked. -416 * -417 * <p> -418 * Only one header value can be specified per entry (i.e. it's not a delimited list of header entries). -419 * -420 * <p> -421 * Header values specified at the method level override header values specified at the servlet level. -422 * -423 * <h5 class='section'>Example:</h5> -424 * <p class='bcode'> -425 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> -426 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>}) -427 * <jk>public</jk> String doGet() { -428 * ... -429 * } -430 * </p> -431 * -432 * <p> -433 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. -434 * Key and value is trimmed of whitespace. -435 */ -436 String[] defaultRequestHeaders() default {}; -437 -438 /** -439 * Specifies default values for query parameters. -440 * -441 * <p> -442 * Strings are of the format <js>"name=value"</js>. -443 * -444 * <p> -445 * Affects values returned by {@link RestRequest#getQuery(String)} when the parameter is not present on the request. -446 * -447 * <h5 class='section'>Example:</h5> -448 * <p class='bcode'> -449 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/*"</js>, defaultQuery={<js>"foo=bar"</js>}) -450 * <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"foo"</js>) String foo) { -451 * ... -452 * } -453 * </p> -454 * -455 * <p> -456 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. -457 * Key and value is trimmed of whitespace. -458 */ -459 String[] defaultQuery() default {}; -460 -461 /** -462 * Specifies default values for form-data parameters. -463 * -464 * <p> -465 * Strings are of the format <js>"name=value"</js>. -466 * -467 * <p> -468 * Affects values returned by {@link RestRequest#getFormData(String)} when the parameter is not present on the -469 * request. -470 * -471 * <h5 class='section'>Example:</h5> -472 * <p class='bcode'> -473 * <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/*"</js>, defaultFormData={<js>"foo=bar"</js>}) -474 * <jk>public</jk> String doGet(<ja>@FormData</ja>(<js>"foo"</js>) String foo) { -475 * ... -476 * } -477 * </p> -478 * -479 * <p> -480 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. -481 * Key and value is trimmed of whitespace. -482 */ -483 String[] defaultFormData() default {}; -484 -485 /** -486 * Optional summary for the exposed API. -487 * -488 * <p> -489 * This summary is used in the following locations: -490 * <ul class='spaced-list'> -491 * <li> -492 * The value returned by {@link RestRequest#getMethodSummary()}. -493 * <li> -494 * The <js>"$R{methodSummary}"</js> variable. -495 * <li> -496 * The summary of the method in the Swagger page. -497 * </ul> -498 * -499 * <p> -500 * The default value pulls the description from the <code>(className.?)[javaMethodName].summary</code> entry in the -501 * servlet resource bundle. (e.g. <js>"MyClass.myMethod.summary = foo"</js> or <js>"myMethod.summary = foo"</js>). -502 * -503 * <p> -504 * This field value can contain variables (e.g. "$L{my.localized.variable}"). +025import org.apache.juneau.serializer.*; +026 +027/** +028 * Identifies a REST Java method on a {@link RestServlet} implementation class. +029 * <p> +030 * Refer to <a class='doclink' href='../package-summary.html#TOC'>org.apache.juneau.rest</a> doc for information on using this class. +031 */ +032@Documented +033@Target(METHOD) +034@Retention(RUNTIME) +035@Inherited +036public @interface RestMethod { +037 +038 /** +039 * REST method name. +040 * +041 * <p> +042 * Typically <js>"GET"</js>, <js>"PUT"</js>, <js>"POST"</js>, <js>"DELETE"</js>, or <js>"OPTIONS"</js>. +043 * +044 * <p> +045 * Method names are case-insensitive (always folded to upper-case). +046 * +047 * <p> +048 * Besides the standard HTTP method names, the following can also be specified: +049 * <ul class='spaced-list'> +050 * <li> +051 * <js>"*"</js> +052 * - Denotes any method. +053 * <br>Use this if you want to capture any HTTP methods in a single Java method. +054 * <br>The {@link Method @Method} annotation and/or {@link RestRequest#getMethod()} method can be used to +055 * distinguish the actual HTTP method name. +056 * <li> +057 * <js>""</js> +058 * - Auto-detect. +059 * <br>The method name is determined based on the Java method name. +060 * <br>For example, if the method is <code>doPost(...)</code>, then the method name is automatically detected +061 * as <js>"POST"</js>. +062 * <br>Otherwise, defaults to <js>"GET"</js>. +063 * <li> +064 * <js>"PROXY"</js> +065 * - Remote-proxy interface. +066 * <br>This denotes a Java method that returns an object (usually an interface, often annotated with the +067 * {@link Remoteable @Remoteable} annotation) to be used as a remote proxy using +068 * <code>RestClient.getRemoteableProxy(Class&lt;T&gt; interfaceClass, String url)</code>. +069 * <br>This allows you to construct client-side interface proxies using REST as a transport medium. +070 * <br>Conceptually, this is simply a fancy <code>POST</code> against the url <js>"/{path}/{javaMethodName}"</js> +071 * where the arguments are marshalled from the client to the server as an HTTP body containing an array of +072 * objects, passed to the method as arguments, and then the resulting object is marshalled back to the client. +073 * <li> +074 * Anything else +075 * - Overloaded non-HTTP-standard names that are passed in through a <code>&amp;method=methodName</code> URL +076 * parameter. +077 * </ul> +078 */ +079 String name() default ""; +080 +081 /** +082 * Optional path pattern for the specified method. +083 * +084 * <p> +085 * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too. +086 * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact +087 * pattern is not found. +088 * +089 * <p> +090 * The path can contain variables that get resolved to {@link Path @Path} parameters: +091 * <p class='bcode'> +092 * <jc>// Example 1</jc> +093 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>) +094 * +095 * <jc>// Example 2</jc> +096 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{0}/{1}/{2}/*"</js>) +097 * </p> +098 * +099 * <p> +100 * Refer to {@link Path @Path} on how path variables get resolved. +101 */ +102 String path() default "/*"; +103 +104 /** +105 * URL path pattern priority. +106 * +107 * <p> +108 * To force path patterns to be checked before other path patterns, use a higher priority number. +109 * +110 * <p> +111 * By default, it's <code>0</code>, which means it will use an internal heuristic to determine a best match. +112 */ +113 int priority() default 0; +114 +115 /** +116 * Method guards. +117 * +118 * <p> +119 * Associates one or more {@link RestGuard RestGuards} with a method call. +120 * These guards get called immediately before execution of the REST method. +121 * +122 * <p> +123 * Typically, guards will be used for permissions checking on the user making the request, but it can also be used +124 * for other purposes like pre-call validation of a request. +125 */ +126 Class<? extends RestGuard>[] guards() default {}; +127 +128 /** +129 * Method response converters. +130 * +131 * <p> +132 * Associates one or more {@link RestConverter RestConverters} with a method call. +133 * These converters get called immediately after execution of the REST method in the same order specified in the +134 * annotation. +135 * +136 * <p> +137 * Can be used for performing post-processing on the response object before serialization. +138 * +139 * <p> +140 * Default converters are available in the <a class='doclink' +141 * href='../converters/package-summary.html#TOC'>org.apache.juneau.rest.converters</a> package. +142 */ +143 Class<? extends RestConverter>[] converters() default {}; +144 +145 /** +146 * Method matchers. +147 * +148 * <p> +149 * Associates one more more {@link RestMatcher RestMatchers} with this method. +150 * +151 * <p> +152 * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but +153 * differing based on some request attribute, such as a specific header value. +154 * +155 * <p> +156 * See {@link RestMatcher} for details. +157 */ +158 Class<? extends RestMatcher>[] matchers() default {}; +159 +160 /** +161 * Overrides the list of serializers assigned at the method level. +162 * +163 * <p> +164 * Use this annotation when the list of serializers assigned to a method differs from the list of serializers +165 * assigned at the servlet level. +166 * +167 * <p> +168 * To append to the list of serializers assigned at the servlet level, use +169 * <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>. +170 * +171 * <p class='bcode'> +172 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { +173 * +174 * <ja>@RestMethod</ja>( +175 * name=<js>"GET"</js>, +176 * path=<js>"/foo"</js>, +177 * serializers=MySpecialSerializer.<jk>class</jk>, +178 * serializersInherit=<jsf>SERIALIZERS</jsf> +179 * ) +180 * <jk>public</jk> Object doGetWithSpecialAcceptType() { +181 * <jc>// Handle request for special Accept type</jc> +182 * } +183 * } +184 * </p> +185 */ +186 Class<? extends Serializer>[] serializers() default {}; +187 +188 /** +189 * Used in conjunction with {@link #serializers()} to identify what class-level settings are inherited by the method +190 * serializer group. +191 * +192 * <p> +193 * Possible values: +194 * <ul> +195 * <li>{@link Inherit#SERIALIZERS} - Inherit class-level serializers. +196 * <li>{@link Inherit#PROPERTIES} - Inherit class-level properties. +197 * <li>{@link Inherit#TRANSFORMS} - Inherit class-level transforms. +198 * </ul> +199 * +200 * <p> +201 * For example, to inherit all serializers, properties, and transforms from the servlet class: +202 * <p class='bcode'> +203 * <ja>@RestMethod</ja>( +204 * path=<js>"/foo"</js>, +205 * serializers=MySpecialSerializer.<jk>class</jk>, +206 * serializersInherit={<jsf>SERIALIZERS</jsf>,<jsf>PROPERTIES</jsf>,<jsf>TRANSFORMS</jsf>} +207 * ) +208 * </p> +209 */ +210 Inherit[] serializersInherit() default {}; +211 +212 /** +213 * Overrides the list of parsers assigned at the method level. +214 * +215 * <p> +216 * Use this annotation when the list of parsers assigned to a method differs from the list of parsers assigned at +217 * the servlet level. +218 * +219 * <p> +220 * To append to the list of serializers assigned at the servlet level, use +221 * <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>. +222 * +223 * <p class='bcode'> +224 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { +225 * +226 * <ja>@RestMethod</ja>( +227 * name=<js>"PUT"</js>, +228 * path=<js>"/foo"</js>, +229 * parsers=MySpecialParser.<jk>class</jk>, +230 * parsersInherit=<jsf>PARSERS</jsf> +231 * ) +232 * <jk>public</jk> Object doGetWithSpecialAcceptType() { +233 * <jc>// Handle request for special Accept type</jc> +234 * } +235 * } +236 * </p> +237 */ +238 Class<? extends Parser>[] parsers() default {}; +239 +240 /** +241 * Used in conjunction with {@link #parsers()} to identify what class-level settings are inherited by the method +242 * parser group. +243 * +244 * <p> +245 * Possible values: +246 * <ul> +247 * <li>{@link Inherit#PARSERS} - Inherit class-level parsers. +248 * <li>{@link Inherit#PROPERTIES} - Inherit class-level properties. +249 * <li>{@link Inherit#TRANSFORMS} - Inherit class-level transforms. +250 * </ul> +251 * +252 * <p> +253 * For example, to inherit all parsers, properties, and transforms from the servlet class: +254 * <p class='bcode'> +255 * <ja>@RestMethod</ja>( +256 * path=<js>"/foo"</js>, +257 * parsers=MySpecialParser.<jk>class</jk>, +258 * parsersInherit={<jsf>PARSERS</jsf>,<jsf>PROPERTIES</jsf>,<jsf>TRANSFORMS</jsf>} +259 * ) +260 * </p> +261 */ +262 Inherit[] parsersInherit() default {}; +263 +264 /** +265 * Appends to the list of {@link Encoder encoders} specified on the servlet. +266 * +267 * <p> +268 * Use this annotation when the list of encoders assigned to a method differs from the list of encoders assigned at +269 * the servlet level. +270 * +271 * <p> +272 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. +273 * +274 * <p class='bcode'> +275 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { +276 * +277 * <ja>@RestMethod</ja>( +278 * name=<js>"PUT"</js>, +279 * path=<js>"/foo"</js>, +280 * encoders={GzipEncoder.<jk>class</jk>} +281 * ) +282 * <jk>public</jk> Object doGetWithSpecialEncoding() { +283 * <jc>// Handle request with special encoding</jc> +284 * } +285 * } +286 * </p> +287 * +288 * <p> +289 * If you want to OVERRIDE the set of encoders specified by the servlet, combine this annotation with +290 * <code><ja>@RestMethod</ja>(inheritEncoders=<jk>false</jk>)</code>. +291 */ +292 Class<? extends Encoder>[] encoders() default {}; +293 +294 /** +295 * Specifies whether the method should inherit encoders from the servlet. +296 */ +297 boolean inheritEncoders() default true; +298 +299 /** +300 * Same as {@link RestResource#properties()}, except defines property values by default when this method is called. +301 * +302 * <p> +303 * This is equivalent to simply calling <code>res.addProperties()</code> in the Java method, but is provided for +304 * convenience. +305 */ +306 Property[] properties() default {}; +307 +308 /** +309 * Shortcut for setting {@link #properties()} of simple boolean types. +310 * +311 * <p> +312 * Setting a flag is equivalent to setting the same property to <js>"true"</js>. +313 */ +314 String[] flags() default {}; +315 +316 /** +317 * Appends the specified bean filters to all serializers and parsers used by this method. +318 */ +319 Class<?>[] beanFilters() default {}; +320 +321 /** +322 * Appends the specified POJO swaps to all serializers and parsers used by this method. +323 */ +324 Class<?>[] pojoSwaps() default {}; +325 +326 /** +327 * Shortcut for specifying the {@link BeanContext#BEAN_includeProperties} property on all serializers. +328 * +329 * <p> +330 * The typical use case is when you're rendering summary and details views of the same bean in a resource and +331 * you want to expose or hide specific properties depending on the level of detail you want. +332 * +333 * <p> +334 * In the example below, our 'summary' view is a list of beans where we only want to show the ID property, +335 * and our detail view is a single bean where we want to expose different fields: +336 * <p class='bcode'> +337 * <jc>// Our bean</jc> +338 * <jk>public class</jk> MyBean { +339 * +340 * <jc>// Summary properties</jc> +341 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) +342 * <jk>public</jk> String <jf>id</jf>; +343 * +344 * <jc>// Detail properties</jc> +345 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; +346 * } +347 * +348 * <jc>// Only render "id" property.</jc> +349 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans"</js>, bpIncludes=<js>"{MyBean:'id'}"</js>) +350 * <jk>public</jk> List&lt;MyBean&gt; getBeanSummary(); +351 * +352 * <jc>// Only render "a" and "b" properties.</jc> +353 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans/{id}"</js>, bpIncludes=<js>"{MyBean:'a,b'}"</js>) +354 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id); +355 * </p> +356 * +357 * <p> +358 * The format of this value is a lax JSON object. +359 * <br>Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. +360 * <br>Values are comma-delimited lists of bean property names. +361 * <br>Properties apply to specified class and all subclasses. +362 */ +363 String bpIncludes() default ""; +364 +365 /** +366 * Shortcut for specifying the {@link BeanContext#BEAN_excludeProperties} property on all serializers. +367 * +368 * <p> +369 * Same as {@link #bpIncludes()} except you specify a list of bean property names that you want to exclude from +370 * serialization. +371 * +372 * <p> +373 * In the example below, our 'summary' view is a list of beans where we want to exclude some properties: +374 * <p class='bcode'> +375 * <jc>// Our bean</jc> +376 * <jk>public class</jk> MyBean { +377 * +378 * <jc>// Summary properties</jc> +379 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) +380 * <jk>public</jk> String <jf>id</jf>; +381 * +382 * <jc>// Detail properties</jc> +383 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; +384 * } +385 * +386 * <jc>// Don't show "a" and "b" properties.</jc> +387 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans"</js>, bpExcludes=<js>"{MyBean:'a,b'}"</js>) +388 * <jk>public</jk> List&lt;MyBean&gt; getBeanSummary(); +389 * +390 * <jc>// Render all properties.</jc> +391 * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/mybeans/{id}"</js>) +392 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id); +393 * </p> +394 * +395 * <p> +396 * The format of this value is a lax JSON object. +397 * <br>Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. +398 * <br>Values are com