001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.rest.annotation;
014
015import static java.lang.annotation.ElementType.*;
016import static java.lang.annotation.RetentionPolicy.*;
017
018import java.lang.annotation.*;
019import java.nio.charset.*;
020
021import org.apache.juneau.*;
022import org.apache.juneau.annotation.*;
023import org.apache.juneau.rest.*;
024import org.apache.juneau.rest.converter.*;
025import org.apache.juneau.rest.guard.*;
026import org.apache.juneau.rest.httppart.*;
027import org.apache.juneau.rest.matcher.*;
028import org.apache.juneau.rest.servlet.*;
029import org.apache.juneau.rest.swagger.*;
030import org.apache.juneau.serializer.*;
031import org.apache.juneau.dto.swagger.*;
032import org.apache.juneau.encoders.*;
033import org.apache.juneau.parser.*;
034
035/**
036 * Identifies a REST PUT operation Java method on a {@link RestServlet} implementation class.
037 *
038 * <p>
039 * This is a specialized subtype of <c><ja>{@link RestOp @RestOp}(method=<jsf>PUT</jsf>)</c>.
040 *
041 * <h5 class='section'>See Also:</h5><ul>
042 *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.RestOpAnnotatedMethods">@RestOp-Annotated Methods</a>
043
044 * </ul>
045 */
046@Target(METHOD)
047@Retention(RUNTIME)
048@Inherited
049@ContextApply(RestPutAnnotation.RestOpContextApply.class)
050@AnnotationGroup(RestOp.class)
051public @interface RestPut {
052
053   /**
054    * Specifies whether this method can be called based on the client version.
055    *
056    * <p>
057    * The client version is identified via the HTTP request header identified by
058    * {@link Rest#clientVersionHeader() @Rest(clientVersionHeader)} which by default is <js>"Client-Version"</js>.
059    *
060    * <p>
061    * This is a specialized kind of {@link RestMatcher} that allows you to invoke different Java methods for the same
062    * method/path based on the client version.
063    *
064    * <p>
065    * The format of the client version range is similar to that of OSGi versions.
066    *
067    * <p>
068    * In the following example, the Java methods are mapped to the same HTTP method and URL <js>"/foobar"</js>.
069    * <p class='bjava'>
070    *    <jc>// Call this method if Client-Version is at least 2.0.
071    *    // Note that this also matches 2.0.1.</jc>
072    *    <ja>@RestPut</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>)
073    *    <jk>public</jk> Object method1()  {...}
074    *
075    *    <jc>// Call this method if Client-Version is at least 1.1, but less than 2.0.</jc>
076    *    <ja>@RestPut</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>)
077    *    <jk>public</jk> Object method2()  {...}
078    *
079    *    <jc>// Call this method if Client-Version is less than 1.1.</jc>
080    *    <ja>@RestPut</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>)
081    *    <jk>public</jk> Object method3()  {...}
082    * </p>
083    *
084    * <p>
085    * It's common to combine the client version with transforms that will convert new POJOs into older POJOs for
086    * backwards compatibility.
087    * <p class='bjava'>
088    *    <jc>// Call this method if Client-Version is at least 2.0.</jc>
089    *    <ja>@RestPut</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>)
090    *    <jk>public</jk> NewPojo newMethod()  {...}
091    *
092    *    <jc>// Call this method if X-Client-Version is at least 1.1, but less than 2.0.</jc>
093    *    <ja>@RestPut</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>)
094    *    <ja>@BeanConfig</ja>(swaps=NewToOldSwap.<jk>class</jk>)
095    *    <jk>public</jk> NewPojo oldMethod() {
096    *       <jk>return</jk> newMethod();
097    *    }
098    *
099    * <p>
100    * Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into
101    * an older form.
102    * The old method could also just return back a completely different object.
103    * The range can be any of the following:
104    * <ul>
105    *    <li><js>"[0,1.0)"</js> = Less than 1.0.  1.0 and 1.0.0 does not match.
106    *    <li><js>"[0,1.0]"</js> = Less than or equal to 1.0.  Note that 1.0.1 will match.
107    *    <li><js>"1.0"</js> = At least 1.0.  1.0 and 2.0 will match.
108    * </ul>
109    *
110    * <h5 class='section'>See Also:</h5><ul>
111    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#clientVersionHeader(String)}
112    * </ul>
113    *
114    * @return The annotation value.
115    */
116   String clientVersion() default "";
117
118   /**
119    * Supported content media types.
120    *
121    * <p>
122    * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource.
123    *
124    * <h5 class='section'>Notes:</h5><ul>
125    *    <li class='note'>
126    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
127    *       (e.g. <js>"$S{mySystemProperty}"</js>).
128    * </ul>
129    *
130    * <h5 class='section'>See Also:</h5><ul>
131    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#consumes(MediaType...)}
132    * </ul>
133    *
134    * @return The annotation value.
135    */
136   String[] consumes() default {};
137
138   /**
139    * Class-level response converters.
140    *
141    * <p>
142    * Associates one or more {@link RestConverter converters} with this method.
143    *
144    * <h5 class='section'>See Also:</h5><ul>
145    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#converters()} - Registering converters with REST resources.
146    * </ul>
147    *
148    * @return The annotation value.
149    */
150   Class<? extends RestConverter>[] converters() default {};
151
152   /**
153    * Enable debug mode.
154    *
155    * <p>
156    * Enables the following:
157    * <ul class='spaced-list'>
158    *    <li>
159    *       HTTP request/response bodies are cached in memory for logging purposes.
160    *    <li>
161    *       Request/response messages are automatically logged.
162    * </ul>
163    *
164    * <ul class='values'>
165    *    <li><js>"true"</js> - Debug is enabled for all requests.
166    *    <li><js>"false"</js> - Debug is disabled for all requests.
167    *    <li><js>"conditional"</js> - Debug is enabled only for requests that have a <c class='snippet'>Debug: true</c> header.
168    *    <li><js>""</js> (or anything else) - Debug mode is inherited from class.
169    * </ul>
170    *
171    * <h5 class='section'>Notes:</h5><ul>
172    *    <li class='note'>
173    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
174    *       (e.g. <js>"$L{my.localized.variable}"</js>).
175    * </ul>
176    *
177    * <h5 class='section'>See Also:</h5><ul>
178    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#debugEnablement()}
179    * </ul>
180    *
181    * @return The annotation value.
182    */
183   String debug() default "";
184
185   /**
186    * Default <c>Accept</c> header.
187    *
188    * <p>
189    * The default value for the <c>Accept</c> header if not specified on a request.
190    *
191    * <p>
192    * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header.
193    *
194    * @return The annotation value.
195    */
196   String defaultAccept() default "";
197
198   /**
199    * Default character encoding.
200    *
201    * <p>
202    * The default character encoding for the request and response if not specified on the request.
203    *
204    * <h5 class='section'>Notes:</h5><ul>
205    *    <li class='note'>
206    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
207    *       (e.g. <js>"$S{mySystemProperty}"</js>).
208    * </ul>
209    *
210    * <h5 class='section'>See Also:</h5><ul>
211    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultCharset(Charset)}
212    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#defaultCharset(Charset)}
213    *    <li class='ja'>{@link Rest#defaultCharset}
214    * </ul>
215    *
216    * @return The annotation value.
217    */
218   String defaultCharset() default "";
219
220   /**
221    * Default <c>Content-Type</c> header.
222    *
223    * <p>
224    * The default value for the <c>Content-Type</c> header if not specified on a request.
225    *
226    * <p>
227    * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header.
228    *
229    * @return The annotation value.
230    */
231   String defaultContentType() default "";
232
233   /**
234    * Specifies default values for form-data parameters.
235    *
236    * <p>
237    * Strings are of the format <js>"name=value"</js>.
238    *
239    * <p>
240    * Affects values returned by {@link RestRequest#getFormParam(String)} when the parameter is not present on the
241    * request.
242    *
243    * <h5 class='section'>Example:</h5>
244    * <p class='bjava'>
245    *    <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultRequestFormData={<js>"foo=bar"</js>})
246    *    <jk>public</jk> String doPut(<ja>@FormData</ja>(<js>"foo"</js>) String <jv>foo</jv>)  {...}
247    * </p>
248    *
249    * <h5 class='section'>Notes:</h5><ul>
250    *    <li class='note'>
251    *       You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter.
252    *    <li class='note'>
253    *       Key and value is trimmed of whitespace.
254    *    <li class='note'>
255    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
256    *       (e.g. <js>"$S{mySystemProperty}"</js>).
257    * </ul>
258    *
259    * @return The annotation value.
260    */
261   String[] defaultRequestFormData() default {};
262
263   /**
264    * Specifies default values for query parameters.
265    *
266    * <p>
267    * Strings are of the format <js>"name=value"</js>.
268    *
269    * <p>
270    * Affects values returned by {@link RestRequest#getQueryParam(String)} when the parameter is not present on the request.
271    *
272    * <h5 class='section'>Example:</h5>
273    * <p class='bjava'>
274    *    <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultRequestQueryData={<js>"foo=bar"</js>})
275    *    <jk>public</jk> String doPut(<ja>@Query</ja>(<js>"foo"</js>) String <jv>foo</jv>)  {...}
276    * </p>
277    *
278    * <h5 class='section'>Notes:</h5><ul>
279    *    <li class='note'>
280    *       You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter.
281    *    <li class='note'>
282    *       Key and value is trimmed of whitespace.
283    *    <li class='note'>
284    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
285    *       (e.g. <js>"$S{mySystemProperty}"</js>).
286    * </ul>
287    *
288    * @return The annotation value.
289    */
290   String[] defaultRequestQueryData() default {};
291
292   /**
293    * Default request attributes.
294    *
295    * <p>
296    * Specifies default values for request attributes if they're not already set on the request.
297    *
298    * <p>
299    * Affects values returned by the following methods:
300    *    <ul>
301    *       <li class='jm'>{@link RestRequest#getAttribute(String)}.
302    *       <li class='jm'>{@link RestRequest#getAttributes()}.
303    *    </ul>
304    *
305    * <h5 class='section'>Example:</h5>
306    * <p class='bjava'>
307    *    <jc>// Defined via annotation resolving to a config file setting with default value.</jc>
308    *    <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: $C{REST/myAttributeValue}"</js>})
309    *    <jk>public class</jk> MyResource {
310    *
311    *       <jc>// Override at the method level.</jc>
312    *       <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>})
313    *       <jk>public</jk> Object myMethod() {...}
314    *    }
315    * </p>
316    *
317    * </ul>
318    * <h5 class='section'>Notes:</h5><ul>
319    *    <li class='note'>
320    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
321    *       (e.g. <js>"$L{my.localized.variable}"</js>).
322    * </ul>
323    *
324    * <h5 class='section'>See Also:</h5><ul>
325    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestAttributes(NamedAttribute...)}
326    *    <li class='ja'>{@link Rest#defaultRequestAttributes()}
327    * </ul>
328    *
329    * @return The annotation value.
330    */
331   String[] defaultRequestAttributes() default {};
332
333   /**
334    * Default request headers.
335    *
336    * <p>
337    * Specifies default values for request headers if they're not passed in through the request.
338    *
339    * <h5 class='section'>Example:</h5>
340    * <p class='bjava'>
341    *    <jc>// Assume "text/json" Accept value when Accept not specified</jc>
342    *    <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>})
343    *    <jk>public</jk> String doPut()  {...}
344    * </p>
345    *
346    * <h5 class='section'>Notes:</h5><ul>
347    *    <li class='note'>
348    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
349    *       (e.g. <js>"$S{mySystemProperty}"</js>).
350    * </ul>
351    *
352    * <h5 class='section'>See Also:</h5><ul>
353    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestHeaders(org.apache.http.Header...)}
354    * </ul>
355    *
356    * @return The annotation value.
357    */
358   String[] defaultRequestHeaders() default {};
359
360   /**
361    * Default response headers.
362    *
363    * <p>
364    * Specifies default values for response headers if they're not overwritten during the request.
365    *
366    * <h5 class='section'>Example:</h5>
367    * <p class='bjava'>
368    *    <jc>// Assume "text/json" Accept value when Accept not specified</jc>
369    *    <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultResponseHeaders={<js>"Content-Type: text/json"</js>})
370    *    <jk>public</jk> String doPut()  {...}
371    * </p>
372    *
373    * <h5 class='section'>Notes:</h5><ul>
374    *    <li class='note'>
375    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
376    *       (e.g. <js>"$S{mySystemProperty}"</js>).
377    * </ul>
378    *
379    * <h5 class='section'>See Also:</h5><ul>
380    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultResponseHeaders(org.apache.http.Header...)}
381    * </ul>
382    *
383    * @return The annotation value.
384    */
385   String[] defaultResponseHeaders() default {};
386
387   /**
388    * Optional description for the exposed API.
389    *
390    * <p>
391    * This description is used in the following locations:
392    * <ul class='spaced-list'>
393    *    <li>
394    *       The value returned by {@link Operation#getDescription()} in the auto-generated swagger.
395    *    <li>
396    *       The <js>"$RS{operationDescription}"</js> variable.
397    *    <li>
398    *       The description of the method in the Swagger page.
399    * </ul>
400    *
401    * <h5 class='section'>Notes:</h5><ul>
402    *    <li class='note'>
403    *       Corresponds to the swagger field <c>/paths/{path}/{method}/description</c>.
404    *    <li class='note'>
405    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
406    *       (e.g. <js>"$L{my.localized.variable}"</js>).
407    * </ul>
408    *
409    * @return The annotation value.
410    */
411   String[] description() default {};
412
413   /**
414    * Specifies the compression encoders for this method.
415    *
416    * <p>
417    * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses.
418    *
419    * <p>
420    * This value overrides encoders specified at the class level using {@link Rest#encoders()}.
421    * The {@link org.apache.juneau.encoders.EncoderSet.Inherit} class can be used to include values from the parent class.
422    *
423    * <h5 class='section'>Example:</h5>
424    * <p class='bjava'>
425    *    <jc>// Define a REST resource that handles GZIP compression.</jc>
426    *    <ja>@Rest</ja>(
427    *       encoders={
428    *          GzipEncoder.<jk>class</jk>
429    *       }
430    *    )
431    *    <jk>public class</jk> MyResource {
432    *
433    *       <jc>// Define a REST method that can also use a custom encoder.</jc>
434    *       <ja>@RestPut</ja>(
435    *          encoders={
436    *             EncoderSet.Inherit.<jk>class</jk>, MyEncoder.<jk>class</jk>
437    *          }
438    *       )
439    *       <jk>public void</jk> doPut(MyBean <jv>bean</jv>) {
440    *          ...
441    *       }
442    *    }
443    * </p>
444    *
445    * <p>
446    * The programmatic equivalent to this annotation is:
447    * <p class='bjava'>
448    *    RestOpContext.Builder <jv>builder</jv> = RestOpContext.<jsm>create</jsm>(<jv>method</jv>,<jv>restContext</jv>);
449    *    <jv>builder</jv>.getEncoders().set(<jv>classes</jv>);
450    * </p>
451    *
452    * <h5 class='section'>See Also:</h5><ul>
453    *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Encoders">Encoders</a>
454    * </ul>
455    *
456    * @return The annotation value.
457    */
458   Class<? extends Encoder>[] encoders() default {};
459
460   /**
461    * Method-level guards.
462    *
463    * <p>
464    * Associates one or more {@link RestGuard RestGuards} with this method.
465    *
466    * <h5 class='section'>See Also:</h5><ul>
467    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#guards()}
468    * </ul>
469    *
470    * @return The annotation value.
471    */
472   Class<? extends RestGuard>[] guards() default {};
473
474   /**
475    * Method matchers.
476    *
477    * <p>
478    * Associates one more more {@link RestMatcher RestMatchers} with this method.
479    *
480    * <p>
481    * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but
482    * differing based on some request attribute, such as a specific header value.
483    *
484    * <h5 class='section'>See Also:</h5><ul>
485    *    <li class='jac'>{@link RestMatcher}
486    * </ul>
487    *
488    * @return The annotation value.
489    */
490   Class<? extends RestMatcher>[] matchers() default {};
491
492   /**
493    * The maximum allowed input size (in bytes) on HTTP requests.
494    *
495    * <p>
496    * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting
497    * in out-of-memory errors which could affect system stability.
498    *
499    * <h5 class='section'>Example:</h5>
500    * <p class='bjava'>
501    *    <ja>@RestPut</ja>(
502    *       maxInput=<js>"100M"</js>
503    *    )
504    * </p>
505    *
506    * <h5 class='section'>Notes:</h5><ul>
507    *    <li class='note'>
508    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
509    *       (e.g. <js>"$S{mySystemProperty}"</js>).
510    * </ul>
511    *
512    * <h5 class='section'>See Also:</h5><ul>
513    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#maxInput(String)}
514    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#maxInput(String)}
515    *    <li class='ja'>{@link Rest#maxInput}
516    * </ul>
517    *
518    * @return The annotation value.
519    */
520   String maxInput() default "";
521
522   /**
523    * Dynamically apply this annotation to the specified methods.
524    *
525    * <h5 class='section'>See Also:</h5><ul>
526    *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
527    * </ul>
528    *
529    * @return The annotation value.
530    */
531   String[] on() default {};
532
533   /**
534    * Specifies the parsers for converting HTTP request bodies into POJOs for this method.
535    *
536    * <p>
537    * Parsers are used to convert the content of HTTP requests into POJOs.
538    * <br>Any of the Juneau framework parsers can be used in this setting.
539    * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method
540    * using a best-match algorithm:
541    * <ul class='javatree'>
542    *    <li class='jm'>{@link Parser#getMediaTypes()}
543    * </ul>
544    *
545    * <p>
546    * This value overrides parsers specified at the class level using {@link Rest#parsers()}.
547    * The {@link org.apache.juneau.parser.ParserSet.Inherit} class can be used to include values from the parent class.
548    *
549    * <h5 class='section'>Example:</h5>
550    * <p class='bjava'>
551    *    <jc>// Define a REST resource that can consume JSON and HTML.</jc>
552    *    <ja>@Rest</ja>(
553    *       parsers={
554    *          JsonParser.<jk>class</jk>,
555    *          HtmlParser.<jk>class</jk>
556    *       }
557    *    )
558    *    <jk>public class</jk> MyResource {
559    *
560    *       <jc>// Define a REST method that can also consume XML.</jc>
561    *       <ja>@RestPut</ja>(
562    *          parsers={
563    *             ParserSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk>
564    *          }
565    *       )
566    *       <jk>public void</jk> doPut(MyBean <jv>bean</jv>) {
567    *          ...
568    *       }
569    *    }
570    * </p>
571    *
572    * <p>
573    * The programmatic equivalent to this annotation is:
574    * <p class='bjava'>
575    *    RestOpContext.Builder <jv>builder</jv> = RestOpContext.<jsm>create</jsm>(<jv>method</jv>,<jv>restContext</jv>);
576    *    <jv>builder</jv>.getParsers().set(<jv>classes</jv>);
577    * </p>
578    *
579    * <h5 class='section'>See Also:</h5><ul>
580    *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Marshalling">Marshalling</a>
581    * </ul>
582    *
583    * @return The annotation value.
584    */
585   Class<?>[] parsers() default {};
586
587   /**
588    * Optional path pattern for the specified method.
589    *
590    * <p>
591    * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too.
592    * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact
593    * pattern is not found.
594    *
595    * <p>
596    * The path can contain variables that get resolved to {@link org.apache.juneau.http.annotation.Path @Path} parameters.
597    *
598    * <h5 class='figure'>Examples:</h5>
599    * <p class='bjava'>
600    *    <ja>@RestPut</ja>(path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
601    * </p>
602    * <p class='bjava'>
603    *    <ja>@RestPut</ja>(path=<js>"/myurl/{0}/{1}/{2}/*"</js>)
604    * </p>
605    *
606    * <p>
607    * If you do not specify a path name, then the path name is inferred from the Java method name.
608    *
609    * <h5 class='figure'>Example:</h5>
610    * <p class='bjava'>
611    *    <jc>// Path is assumed to be "/foo".</jc>
612    *    <ja>@RestPut</ja>
613    *    <jk>public void</jk> foo() {...}
614    * </p>
615    *
616    * <p>
617    * Note that you can also use {@link #value()} to specify the path.
618    *
619    * <h5 class='section'>See Also:</h5><ul>
620    *    <li class='ja'>{@link org.apache.juneau.http.annotation.Path}
621    * </ul>
622    *
623    * @return The annotation value.
624    */
625   String[] path() default {};
626
627   /**
628    * Supported accept media types.
629    *
630    * <p>
631    * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource.
632    *
633    * <h5 class='section'>Notes:</h5><ul>
634    *    <li class='note'>
635    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
636    *       (e.g. <js>"$S{mySystemProperty}"</js>).
637    * </ul>
638    *
639    * <h5 class='section'>See Also:</h5><ul>
640    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#produces(MediaType...)}
641    * </ul>
642    *
643    * @return The annotation value.
644    */
645   String[] produces() default {};
646
647   /**
648    * Role guard.
649    *
650    * <p>
651    * An expression defining if a user with the specified roles are allowed to access this method.
652    *
653    * <h5 class='section'>Example:</h5>
654    * <p class='bjava'>
655    *    <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {
656    *
657    *       <ja>@RestPut</ja>(
658    *          path=<js>"/foo"</js>,
659    *          roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; ROLE_SPECIAL)"</js>
660    *       )
661    *       <jk>public</jk> Object doPut() {
662    *       }
663    *    }
664    * </p>
665    *
666    * <h5 class='section'>Notes:</h5><ul>
667    *    <li class='note'>
668    *       Supports any of the following expression constructs:
669    *       <ul>
670    *          <li><js>"foo"</js> - Single arguments.
671    *          <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments.
672    *          <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax.
673    *          <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax.
674    *          <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>.
675    *          <li><js>"fo* &amp; *oo"</js> - Multiple AND'ed arguments, ampersand syntax.
676    *          <li><js>"fo* &amp;&amp; *oo"</js> - Multiple AND'ed arguments, Java-AND syntax.
677    *          <li><js>"fo* || (*oo || bar)"</js> - Parenthesis.
678    *       </ul>
679    *    <li class='note'>
680    *       AND operations take precedence over OR operations (as expected).
681    *    <li class='note'>
682    *       Whitespace is ignored.
683    *    <li class='note'>
684    *       <jk>null</jk> or empty expressions always match as <jk>false</jk>.
685    *    <li class='note'>
686    *       If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()} or {@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)}.
687    *    <li class='note'>
688    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
689    *       (e.g. <js>"$L{my.localized.variable}"</js>).
690    *    <li class='note'>
691    *       When defined on parent/child classes and methods, ALL guards within the hierarchy must pass.
692    * </ul>
693    *
694    * <h5 class='section'>See Also:</h5><ul>
695    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#roleGuard(String)}
696    * </ul>
697    *
698    * @return The annotation value.
699    */
700   String roleGuard() default "";
701
702   /**
703    * Declared roles.
704    *
705    * <p>
706    * A comma-delimited list of all possible user roles.
707    *
708    * <p>
709    * Used in conjunction with {@link #roleGuard()} is used with patterns.
710    *
711    * <h5 class='section'>Example:</h5>
712    * <p class='bjava'>
713    *    <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {
714    *
715    *       <ja>@RestPut</ja>(
716    *          path=<js>"/foo"</js>,
717    *          rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>,
718    *          roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; ROLE_SPECIAL)"</js>
719    *       )
720    *       <jk>public</jk> Object doPut() {
721    *       }
722    *    }
723    * </p>
724    *
725    * <h5 class='section'>See Also:</h5><ul>
726    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)}
727    * </ul>
728    *
729    * @return The annotation value.
730    */
731   String rolesDeclared() default "";
732
733   /**
734    * Specifies the serializers for marshalling POJOs into response bodies for this method.
735    *
736    * <p>
737    * Serializer are used to convert POJOs to HTTP response bodies.
738    * <br>Any of the Juneau framework serializers can be used in this setting.
739    * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method
740    * using a best-match algorithm:
741    * <ul class='javatree'>
742    *    <li class='jm'>{@link Serializer#getMediaTypeRanges()}
743    * </ul>
744    *
745    * <p>
746    * This value overrides serializers specified at the class level using {@link Rest#serializers()}.
747    * The {@link org.apache.juneau.serializer.SerializerSet.Inherit} class can be used to include values from the parent class.
748    *
749    * <h5 class='section'>Example:</h5>
750    * <p class='bjava'>
751    *    <jc>// Define a REST resource that can produce JSON and HTML.</jc>
752    *    <ja>@Rest</ja>(
753    *       serializers={
754    *          JsonParser.<jk>class</jk>,
755    *          HtmlParser.<jk>class</jk>
756    *       }
757    *    )
758    *    <jk>public class</jk> MyResource {
759    *
760    *       <jc>// Define a REST method that can also produce XML.</jc>
761    *       <ja>@RestPut</ja>(
762    *          parsers={
763    *             SerializerSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk>
764    *          }
765    *       )
766    *       <jk>public</jk> MyBean doPut() {
767    *          ...
768    *       }
769    *    }
770    * </p>
771    *
772    * <p>
773    * The programmatic equivalent to this annotation is:
774    * <p class='bjava'>
775    *    RestOpContext.Builder <jv>builder</jv> = RestOpContext.<jsm>create</jsm>(<jv>method</jv>,<jv>restContext</jv>);
776    *    <jv>builder</jv>.getSerializers().set(<jv>classes</jv>);
777    * </p>
778    *
779    * <h5 class='section'>See Also:</h5><ul>
780    *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Marshalling">Marshalling</a>
781    * </ul>
782    *
783    * @return The annotation value.
784    */
785   Class<? extends Serializer>[] serializers() default {};
786
787   /**
788    * Optional summary for the exposed API.
789    *
790    * <p>
791    * This summary is used in the following locations:
792    * <ul class='spaced-list'>
793    *    <li>
794    *       The value returned by {@link Operation#getSummary()} in the auto-generated swagger.
795    *    <li>
796    *       The <js>"$RS{operationSummary}"</js> variable.
797    *    <li>
798    *       The summary of the method in the Swagger page.
799    * </ul>
800    *
801    * <h5 class='section'>Notes:</h5><ul>
802    *    <li class='note'>
803    *       Corresponds to the swagger field <c>/paths/{path}/{method}/summary</c>.
804    *    <li class='note'>
805    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
806    *       (e.g. <js>"$L{my.localized.variable}"</js>).
807    * </ul>
808    *
809    * @return The annotation value.
810    */
811   String summary() default "";
812
813   /**
814    * Provides swagger-specific metadata on this method.
815    *
816    * <p>
817    * Used to populate the auto-generated OPTIONS swagger documentation.
818    *
819    * <p>
820    * The format of this annotation is JSON when all individual parts are concatenated.
821    * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional.
822    *
823    * <h5 class='section'>Example:</h5>
824    * <p class='bjava'>
825    *    <ja>@RestPut</ja>(
826    *       path=<js>"/{propertyName}"</js>,
827    *
828    *       <jc>// Swagger info.</jc>
829    *       swagger={
830    *          <js>"parameters:["</js>,
831    *             <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>,
832    *             <js>"{in:'body',description:'The new system property value.'}"</js>,
833    *          <js>"],"</js>,
834    *          <js>"responses:{"</js>,
835    *             <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>,
836    *             <js>"403: {description:'User is not an admin.'}"</js>,
837    *          <js>"}"</js>
838    *       }
839    *    )
840    * </p>
841    *
842    * <h5 class='section'>Notes:</h5><ul>
843    *    <li class='note'>
844    *       The format is <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a>.
845    *       <br>Multiple lines are concatenated with newlines.
846    *    <li class='note'>
847    *       The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional.
848    *    <li class='note'>
849    *       These values are superimposed on top of any Swagger JSON file present for the resource in the classpath.
850    *    <li class='note'>
851    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
852    *       (e.g. <js>"$L{my.localized.variable}"</js>).
853    * </ul>
854    *
855    * <h5 class='section'>See Also:</h5><ul>
856    *    <li class='ja'>{@link OpSwagger}
857    *    <li class='jc'>{@link SwaggerProvider}
858    * </ul>
859    *
860    * @return The annotation value.
861    */
862   OpSwagger swagger() default @OpSwagger;
863
864   /**
865    * REST method path.
866    *
867    * <p>
868    * Can be used to provide a shortened form for the {@link #path()} value.
869    *
870    * <p>
871    * The following examples are considered equivalent.
872    * <p class='bjava'>
873    *    <jc>// Normal form</jc>
874    *    <ja>@RestPut</ja>(path=<js>"/{propertyName}"</js>)
875    *
876    *    <jc>// Shortened form</jc>
877    *    <ja>@RestPut</ja>(<js>"/{propertyName}"</js>)
878    * </p>
879    *
880    * @return The annotation value.
881    */
882   String value() default "";
883}