001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.rest.server; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023 024import org.apache.juneau.bean.swagger.*; 025import org.apache.juneau.commons.*; 026import org.apache.juneau.marshall.encoders.*; 027import org.apache.juneau.rest.server.guard.*; 028import org.apache.juneau.rest.server.matcher.*; 029import org.apache.juneau.rest.server.servlet.*; 030import org.apache.juneau.rest.server.swagger.*; 031 032/** 033 * Identifies a REST DELETE operation Java method on a {@link RestServlet} implementation class. 034 * 035 * <p> 036 * This is a specialized subtype of <c><ja>{@link RestOp @RestOp}(method=<jsf>DELETE</jsf>)</c>. 037 * 038 * <h5 class='section'>See Also:</h5><ul> 039 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestOpAnnotatedMethods">@RestOp-Annotated Method</a> 040 041 * </ul> 042 */ 043@Target(METHOD) 044@Retention(RUNTIME) 045@Inherited 046@AnnotationGroup(RestOp.class) 047public @interface RestDelete { 048 049 /** 050 * Specifies whether this method can be called based on the client version. 051 * 052 * <p> 053 * The client version is identified via the HTTP request header identified by 054 * {@link Rest#clientVersionHeader() @Rest(clientVersionHeader)} which by default is <js>"Client-Version"</js>. 055 * 056 * <p> 057 * This is a specialized kind of {@link RestMatcher} that allows you to invoke different Java methods for the same 058 * method/path based on the client version. 059 * 060 * <p> 061 * The format of the client version range is similar to that of OSGi versions. 062 * 063 * <p> 064 * In the following example, the Java methods are mapped to the same HTTP method and URL <js>"/foobar"</js>. 065 * <p class='bjava'> 066 * <jc>// Call this method if Client-Version is at least 2.0. 067 * // Note that this also matches 2.0.1.</jc> 068 * <ja>@RestDelete</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 069 * <jk>public</jk> Object method1() {...} 070 * 071 * <jc>// Call this method if Client-Version is at least 1.1, but less than 2.0.</jc> 072 * <ja>@RestDelete</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 073 * <jk>public</jk> Object method2() {...} 074 * 075 * <jc>// Call this method if Client-Version is less than 1.1.</jc> 076 * <ja>@RestDelete</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>) 077 * <jk>public</jk> Object method3() {...} 078 * </p> 079 * 080 * <p> 081 * It's common to combine the client version with transforms that will convert new POJOs into older POJOs for 082 * backwards compatibility. 083 * <p class='bjava'> 084 * <jc>// Call this method if Client-Version is at least 2.0.</jc> 085 * <ja>@RestDelete</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 086 * <jk>public void</jk> newMethod() {...} 087 * 088 * <jc>// Call this method if Client-Version is at least 1.1, but less than 2.0.</jc> 089 * <ja>@RestDelete</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>}) 090 * <jk>public void</jk> oldMethod() {...} 091 * </p> 092 * 093 * <p> 094 * Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into 095 * an older form. 096 * The old method could also just return back a completely different object. 097 * The range can be any of the following: 098 * <ul> 099 * <li><js>"[0,1.0)"</js> = Less than 1.0. 1.0 and 1.0.0 does not match. 100 * <li><js>"[0,1.0]"</js> = Less than or equal to 1.0. Note that 1.0.1 will match. 101 * <li><js>"1.0"</js> = At least 1.0. 1.0 and 2.0 will match. 102 * </ul> 103 * 104 * 105 * @return The annotation value. 106 */ 107 String clientVersion() default ""; 108 109 /** 110 * Default <c>Accept</c> header. 111 * 112 * <p> 113 * The default value for the <c>Accept</c> header if not specified on a request. 114 * 115 * <p> 116 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 117 * 118 * @return The annotation value. 119 */ 120 String defaultAccept() default ""; 121 122 /** 123 * Default character encoding. 124 * 125 * <p> 126 * The default character encoding for the request and response if not specified on the request. 127 * 128 * <h5 class='section'>Notes:</h5><ul> 129 * <li class='note'> 130 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 131 * (e.g. <js>"$S{mySystemProperty}"</js>). 132 * </ul> 133 * 134 * <h5 class='section'>See Also:</h5><ul> 135 * <li class='ja'>{@link Rest#defaultCharset} 136 * </ul> 137 * 138 * @return The annotation value. 139 */ 140 String defaultCharset() default ""; 141 142 /** 143 * Default request attributes. 144 * 145 * <p> 146 * Specifies default values for request attributes if they're not already set on the request. 147 * 148 * <p> 149 * Affects values returned by the following methods: 150 * <ul> 151 * <li class='jm'>{@link RestRequest#getAttribute(String)}. 152 * <li class='jm'>{@link RestRequest#getAttributes()}. 153 * </ul> 154 * 155 * <h5 class='section'>Example:</h5> 156 * <p class='bjava'> 157 * <jc>// Defined via annotation resolving to a config file setting with default value.</jc> 158 * <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: $C{REST/myAttributeValue}"</js>}) 159 * <jk>public class</jk> MyResource { 160 * 161 * <jc>// Override at the method level.</jc> 162 * <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>}) 163 * <jk>public</jk> Object myMethod() {...} 164 * } 165 * </p> 166 * 167 * </ul> 168 * <h5 class='section'>Notes:</h5><ul> 169 * <li class='note'> 170 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 171 * (e.g. <js>"$L{my.localized.variable}"</js>). 172 * </ul> 173 * 174 * <h5 class='section'>See Also:</h5><ul> * <li class='ja'>{@link Rest#defaultRequestAttributes()} 175 * </ul> 176 * 177 * @return The annotation value. 178 */ 179 String[] defaultRequestAttributes() default {}; 180 181 /** 182 * Default request headers. 183 * 184 * <p> 185 * Specifies default values for request headers if they're not passed in through the request. 186 * 187 * <h5 class='section'>Example:</h5> 188 * <p class='bjava'> 189 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 190 * <ja>@RestDelete</ja>(path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>}) 191 * <jk>public</jk> String doDelete() {...} 192 * </p> 193 * 194 * <h5 class='section'>Notes:</h5><ul> 195 * <li class='note'> 196 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 197 * (e.g. <js>"$S{mySystemProperty}"</js>). 198 * </ul> 199 * 200 * 201 * @return The annotation value. 202 */ 203 String[] defaultRequestHeaders() default {}; 204 205 /** 206 * Specifies default values for query parameters. 207 * 208 * <p> 209 * Strings are of the format <js>"name=value"</js>. 210 * 211 * <p> 212 * Affects values returned by {@link RestRequest#getQueryParam(String)} when the parameter is not present on the request. 213 * 214 * <h5 class='section'>Example:</h5> 215 * <p class='bjava'> 216 * <ja>@RestDelete</ja>(path=<js>"/*"</js>, defaultRequestQueryData={<js>"foo=bar"</js>}) 217 * <jk>public</jk> String doDelete(<ja>@Query</ja>(<js>"foo"</js>) String <jv>foo</jv>) {...} 218 * </p> 219 * 220 * <h5 class='section'>Notes:</h5><ul> 221 * <li class='note'> 222 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 223 * <li class='note'> 224 * Key and value is trimmed of whitespace. 225 * <li class='note'> 226 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 227 * (e.g. <js>"$S{mySystemProperty}"</js>). 228 * </ul> 229 * 230 * @return The annotation value. 231 */ 232 String[] defaultRequestQueryData() default {}; 233 234 /** 235 * Default response headers. 236 * 237 * <p> 238 * Specifies default values for response headers if they're not overwritten during the request. 239 * 240 * <h5 class='section'>Example:</h5> 241 * <p class='bjava'> 242 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 243 * <ja>@RestDelete</ja>(path=<js>"/*"</js>, defaultResponseHeaders={<js>"Content-Type: text/json"</js>}) 244 * <jk>public</jk> String doDelete() {...} 245 * </p> 246 * 247 * <h5 class='section'>Notes:</h5><ul> 248 * <li class='note'> 249 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 250 * (e.g. <js>"$S{mySystemProperty}"</js>). 251 * </ul> 252 * 253 * 254 * @return The annotation value. 255 */ 256 String[] defaultResponseHeaders() default {}; 257 258 /** 259 * Optional description for the exposed API. 260 * 261 * <p> 262 * This description is used in the following locations: 263 * <ul class='spaced-list'> 264 * <li> 265 * The value returned by {@link Operation#getDescription()} in the auto-generated swagger. 266 * <li> 267 * The <js>"$RS{operationDescription}"</js> variable. 268 * <li> 269 * The description of the method in the Swagger page. 270 * </ul> 271 * 272 * <h5 class='section'>Notes:</h5><ul> 273 * <li class='note'> 274 * Corresponds to the swagger field <c>/paths/{path}/{method}/description</c>. 275 * <li class='note'> 276 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 277 * (e.g. <js>"$L{my.localized.variable}"</js>). 278 * </ul> 279 * 280 * @return The annotation value. 281 */ 282 String[] description() default {}; 283 284 /** 285 * Specifies the compression encoders for this method. 286 * 287 * <p> 288 * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 289 * 290 * <p> 291 * This value overrides encoders specified at the class level using {@link Rest#encoders()}. 292 * The {@link org.apache.juneau.marshall.encoders.EncoderSet.Inherit EncoderSet.Inherit} class can be used to include values from the parent class. 293 * 294 * <h5 class='section'>Example:</h5> 295 * <p class='bjava'> 296 * <jc>// Define a REST resource that handles GZIP compression.</jc> 297 * <ja>@Rest</ja>( 298 * encoders={ 299 * GzipEncoder.<jk>class</jk> 300 * } 301 * ) 302 * <jk>public class</jk> MyResource { 303 * 304 * <jc>// Define a REST method that can also use a custom encoder.</jc> 305 * <ja>@RestDelete</ja>( 306 * encoders={ 307 * EncoderSet.Inherit.<jk>class</jk>, MyEncoder.<jk>class</jk> 308 * } 309 * ) 310 * <jk>public</jk> String doDelete() { 311 * ... 312 * } 313 * } 314 * </p> 315 * 316 * <p> 317 * For programmatic equivalents, contribute a {@link EncoderSet} bean via 318 * {@link org.apache.juneau.commons.inject.Bean @Bean(name="encoders")} (use methodScope to scope to specific operation methods). 319 * 320 * <h5 class='section'>See Also:</h5><ul> 321 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerEncoders">Encoders in REST servers</a> 322 * </ul> 323 * 324 * @return The annotation value. 325 */ 326 Class<? extends Encoder>[] encoders() default {}; 327 328 /** 329 * Method-level guards. 330 * 331 * <p> 332 * Associates one or more {@link RestGuard RestGuards} with this method. 333 * 334 * 335 * @return The annotation value. 336 */ 337 Class<? extends RestGuard>[] guards() default {}; 338 339 /** 340 * Method matchers. 341 * 342 * <p> 343 * Associates one more more {@link RestMatcher RestMatchers} with this method. 344 * 345 * <p> 346 * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but 347 * differing based on some request attribute, such as a specific header value. 348 * 349 * <h5 class='section'>See Also:</h5><ul> 350 * <li class='jac'>{@link RestMatcher} 351 * </ul> 352 * 353 * @return The annotation value. 354 */ 355 Class<? extends RestMatcher>[] matchers() default {}; 356 357 /** 358 * Optional path pattern for the specified method. 359 * 360 * <p> 361 * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too. 362 * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact 363 * pattern is not found. 364 * 365 * <p> 366 * The path can contain variables that get resolved to {@link org.apache.juneau.http.Path @Path} parameters. 367 * 368 * <h5 class='figure'>Examples:</h5> 369 * <p class='bjava'> 370 * <ja>@RestDelete</ja>(path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>) 371 * </p> 372 * <p class='bjava'> 373 * <ja>@RestDelete</ja>(path=<js>"/myurl/{0}/{1}/{2}/*"</js>) 374 * </p> 375 * 376 * <p> 377 * Note that you can also use {@link #value()} to specify the path. 378 * 379 * <h5 class='section'>See Also:</h5><ul> 380 * <li class='ja'>{@link org.apache.juneau.http.Path} 381 * </ul> 382 * 383 * @return The annotation value. 384 */ 385 String[] path() default {}; 386 387 /** 388 * Per-operation override for {@link Rest#problemDetails() @Rest(problemDetails)}. 389 * 390 * <p> 391 * When set on a {@code @RestDelete} method, this value takes precedence over the resource-level 392 * {@code @Rest(problemDetails)} attribute for this operation. Tri-state semantics: 393 * 394 * <ul class='values'> 395 * <li><js>"true"</js> — enable problem-details responses for this operation. 396 * <li><js>"false"</js> — disable problem-details responses for this operation (overrides an 397 * opted-in resource). 398 * <li><js>""</js> (default) — inherit from {@link Rest#problemDetails()}. 399 * </ul> 400 * 401 * <h5 class='section'>Notes:</h5><ul> 402 * <li class='note'> 403 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 404 * (e.g. <js>"$L{my.localized.variable}"</js>). 405 * </ul> 406 * 407 * <h5 class='section'>See Also:</h5><ul> 408 * <li class='ja'>{@link Rest#problemDetails()} 409 * </ul> 410 * 411 * @return The annotation value. 412 */ 413 String problemDetails() default ""; 414 415 /** 416 * Per-operation override for {@link Rest#debugMarshalling() @Rest(debugMarshalling)}. 417 * 418 * <p> 419 * When set on a {@code @RestDelete} method, this value takes precedence over the resource-level 420 * {@code @Rest(debugMarshalling)} attribute for this operation. Tri-state semantics: 421 * 422 * <ul class='values'> 423 * <li><js>"true"</js> — enable marshalling debug for this operation. 424 * <li><js>"false"</js> — disable marshalling debug for this operation (overrides an opted-in resource). 425 * <li><js>""</js> (default) — inherit from {@link Rest#debugMarshalling()}. 426 * </ul> 427 * 428 * <h5 class='section'>See Also:</h5><ul> 429 * <li class='ja'>{@link Rest#debugMarshalling()} 430 * </ul> 431 * 432 * @return The annotation value. 433 */ 434 String debugMarshalling() default ""; 435 436 /** 437 * Per-operation observability opt-in / opt-out control. 438 * 439 * <p> 440 * Overrides the resource-level {@link Rest#observability()} setting for this specific operation. 441 * 442 * <ul class='values'> 443 * <li><js>"true"</js> — strict opt-in; requires a wired observability backend. 444 * <li><js>"false"</js> — explicit opt-out; short-circuits the observability block. 445 * <li><js>""</js> (default) — inherits the resource-level setting. 446 * </ul> 447 * 448 * <h5 class='section'>See Also:</h5><ul> 449 * <li class='ja'>{@link RestOp#observability()} 450 * </ul> 451 * 452 * @return The annotation value. 453 * @since 10.0.0 454 */ 455 String observability() default ""; 456 457 /** 458 * Per-operation override for {@link Rest#asyncCompletionExecutor() @Rest(asyncCompletionExecutor)}. 459 * 460 * <p> 461 * Names the {@link java.util.concurrent.Executor} bean used to route completion callbacks for this 462 * specific operation through a dedicated thread pool. Empty string (default) inherits from 463 * {@link Rest#asyncCompletionExecutor()}. 464 * 465 * <h5 class='section'>See Also:</h5><ul> 466 * <li class='ja'>{@link RestOp#asyncCompletionExecutor()} 467 * <li class='ja'>{@link Rest#asyncCompletionExecutor()} 468 * </ul> 469 * 470 * @return The annotation value. 471 * @since 10.0.0 472 */ 473 String asyncCompletionExecutor() default ""; 474 475 /** 476 * Per-operation metric name override. Empty string (default) uses the recorder's own name derivation. 477 * 478 * <h5 class='section'>See Also:</h5><ul> 479 * <li class='ja'>{@link RestOp#metricName()} 480 * </ul> 481 * 482 * @return The annotation value. 483 * @since 10.0.0 484 */ 485 String metricName() default ""; 486 487 /** 488 * Per-operation metric tags. Format: comma-separated {@code key=value} pairs. 489 * Empty string (default) means no additional tags. 490 * 491 * <h5 class='section'>See Also:</h5><ul> 492 * <li class='ja'>{@link RestOp#metricTags()} 493 * </ul> 494 * 495 * @return The annotation value. 496 * @since 10.0.0 497 */ 498 String metricTags() default ""; 499 500 /** 501 * Allowed serializer session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 502 * 503 * <p> 504 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Serializer-Options"</js> 505 * header or <js>"juneauSerializerOptions"</js> query parameter. 506 * Merged on top of resource-level {@link Rest#allowedSerializerOptions()} values. 507 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 508 * 509 * <h5 class='section'>See Also:</h5><ul> 510 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 511 * </ul> 512 * 513 * @return The annotation value. 514 */ 515 String[] allowedSerializerOptions() default {}; 516 517 /** 518 * Allowed parser session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 519 * 520 * <p> 521 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Parser-Options"</js> 522 * header or <js>"juneauParserOptions"</js> query parameter. 523 * Merged on top of resource-level {@link Rest#allowedParserOptions()} values. 524 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 525 * 526 * <h5 class='section'>See Also:</h5><ul> 527 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 528 * </ul> 529 * 530 * @return The annotation value. 531 */ 532 String[] allowedParserOptions() default {}; 533 534 /** 535 * Property names for which less-derived contributions are NOT inherited. 536 * 537 * <p> 538 * Accepted values: {@code "allowedSerializerOptions"}, {@code "allowedParserOptions"}, 539 * {@code "problemDetails"}, {@code "debugMarshalling"}. 540 * Prevents the named property from inheriting values from the enclosing {@code @Rest} annotation. 541 * The {@code noInherit} attribute itself is never inherited. 542 * 543 * <h5 class='section'>See Also:</h5><ul> 544 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions">Session Options via HTTP</a> 545 * </ul> 546 * 547 * @return The annotation value. 548 */ 549 String[] noInherit() default {}; 550 551 /** 552 * Role guard. 553 * 554 * <p> 555 * An expression defining if a user with the specified roles are allowed to access this method. 556 * 557 * <h5 class='section'>Example:</h5> 558 * <p class='bjava'> 559 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 560 * 561 * <ja>@RestDelete</ja>( 562 * path=<js>"/foo"</js>, 563 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 564 * ) 565 * <jk>public</jk> Object doDelete() { 566 * } 567 * } 568 * </p> 569 * 570 * <h5 class='section'>Notes:</h5><ul> 571 * <li class='note'> 572 * Supports any of the following expression constructs: 573 * <ul> 574 * <li><js>"foo"</js> - Single arguments. 575 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 576 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 577 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 578 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 579 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 580 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 581 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 582 * </ul> 583 * <li class='note'> 584 * AND operations take precedence over OR operations (as expected). 585 * <li class='note'> 586 * Whitespace is ignored. 587 * <li class='note'> 588 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 589 * <li class='note'> 590 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()}. 591 * <li class='note'> 592 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 593 * (e.g. <js>"$L{my.localized.variable}"</js>). 594 * <li class='note'> 595 * When defined on parent/child classes and methods, ALL guards within the hierarchy must pass. 596 * </ul> 597 * 598 * 599 * @return The annotation value. 600 */ 601 String roleGuard() default ""; 602 603 /** 604 * Declared roles. 605 * 606 * <p> 607 * A comma-delimited list of all possible user roles. 608 * 609 * <p> 610 * Used in conjunction with {@link #roleGuard()} is used with patterns. 611 * 612 * <h5 class='section'>Example:</h5> 613 * <p class='bjava'> 614 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 615 * 616 * <ja>@RestDelete</ja>( 617 * path=<js>"/foo"</js>, 618 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 619 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 620 * ) 621 * <jk>public</jk> Object doDelete() { 622 * } 623 * } 624 * </p> 625 * 626 * 627 * @return The annotation value. 628 */ 629 String rolesDeclared() default ""; 630 631 /** 632 * Optional summary for the exposed API. 633 * 634 * <p> 635 * This summary is used in the following locations: 636 * <ul class='spaced-list'> 637 * <li> 638 * The value returned by {@link Operation#getSummary()} in the auto-generated swagger. 639 * <li> 640 * The <js>"$RS{operationSummary}"</js> variable. 641 * <li> 642 * The summary of the method in the Swagger page. 643 * </ul> 644 * 645 * <h5 class='section'>Notes:</h5><ul> 646 * <li class='note'> 647 * Corresponds to the swagger field <c>/paths/{path}/{method}/summary</c>. 648 * <li class='note'> 649 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 650 * (e.g. <js>"$L{my.localized.variable}"</js>). 651 * </ul> 652 * 653 * @return The annotation value. 654 */ 655 String summary() default ""; 656 657 /** 658 * Provides swagger-specific metadata on this method. 659 * 660 * <p> 661 * Used to populate the auto-generated OPTIONS swagger documentation. 662 * 663 * <p> 664 * The format of this annotation is JSON when all individual parts are concatenated. 665 * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 666 * 667 * <h5 class='section'>Example:</h5> 668 * <p class='bjava'> 669 * <ja>@RestDelete</ja>( 670 * path=<js>"/{propertyName}"</js>, 671 * 672 * <jc>// Swagger info.</jc> 673 * swagger={ 674 * <js>"parameters:["</js>, 675 * <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>, 676 * <js>"{in:'body',description:'The new system property value.'}"</js>, 677 * <js>"],"</js>, 678 * <js>"responses:{"</js>, 679 * <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>, 680 * <js>"403: {description:'User is not an admin.'}"</js>, 681 * <js>"}"</js> 682 * } 683 * ) 684 * </p> 685 * 686 * <h5 class='section'>Notes:</h5><ul> 687 * <li class='note'> 688 * The format is <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>. 689 * <br>Multiple lines are concatenated with newlines. 690 * <li class='note'> 691 * The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 692 * <li class='note'> 693 * These values are superimposed on top of any Swagger JSON file present for the resource in the classpath. 694 * <li class='note'> 695 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 696 * (e.g. <js>"$L{my.localized.variable}"</js>). 697 * </ul> 698 * 699 * <h5 class='section'>See Also:</h5><ul> 700 * <li class='ja'>{@link OpSwagger} 701 * <li class='jc'>{@link SwaggerProvider} 702 * </ul> 703 * 704 * @return The annotation value. 705 */ 706 OpSwagger swagger() default @OpSwagger; 707 708 /** 709 * REST method path. 710 * 711 * <p> 712 * Can be used to provide a shortened form for the {@link #path()} value. 713 * 714 * <p> 715 * The following examples are considered equivalent. 716 * <p class='bjava'> 717 * <jc>// Normal form</jc> 718 * <ja>@RestDelete</ja>(path=<js>"/{propertyName}"</js>) 719 * 720 * <jc>// Shortened form</jc> 721 * <ja>@RestDelete</ja>(<js>"/{propertyName}"</js>) 722 * </p> 723 * 724 * @return The annotation value. 725 */ 726 String value() default ""; 727}