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; 014 015import static org.apache.juneau.internal.StringUtils.*; 016import static org.apache.juneau.parser.Parser.*; 017import static org.apache.juneau.rest.RestContext.*; 018import static org.apache.juneau.rest.HttpRuntimeException.*; 019import static org.apache.juneau.serializer.Serializer.*; 020import static org.apache.juneau.internal.CollectionUtils.*; 021 022import java.nio.charset.*; 023import java.util.*; 024 025import javax.servlet.*; 026 027import org.apache.juneau.*; 028import org.apache.juneau.config.*; 029import org.apache.juneau.config.vars.*; 030import org.apache.juneau.encoders.*; 031import org.apache.juneau.html.*; 032import org.apache.juneau.http.*; 033import org.apache.juneau.http.exception.*; 034import org.apache.juneau.httppart.*; 035import org.apache.juneau.oapi.*; 036import org.apache.juneau.parser.*; 037import org.apache.juneau.reflect.*; 038import org.apache.juneau.rest.annotation.*; 039import org.apache.juneau.rest.reshandlers.*; 040import org.apache.juneau.rest.util.RestUtils; 041import org.apache.juneau.rest.vars.*; 042import org.apache.juneau.rest.widget.*; 043import org.apache.juneau.serializer.*; 044import org.apache.juneau.svl.*; 045import org.apache.juneau.svl.vars.*; 046import org.apache.juneau.utils.*; 047 048/** 049 * Defines the initial configuration of a <c>RestServlet</c> or <c>@RestResource</c> annotated object. 050 * 051 * <p> 052 * An extension of the {@link ServletConfig} object used during servlet initialization. 053 * 054 * <p> 055 * Provides access to the following initialized resources: 056 * <ul> 057 * <li>{@link #getConfig()} - The external configuration for this resource. 058 * <li>{@link #getProperties()} - The modifiable configuration properties for this resource. 059 * <li>{@link #getVarResolverBuilder()} - The variable resolver for this resource. 060 * </ul> 061 * 062 * <p> 063 * Methods are provided for overriding or augmenting the information provided by the <ja>@RestResource</ja> annotation. 064 * In general, most information provided in the <ja>@RestResource</ja> annotation can be specified programmatically 065 * through calls on this object. 066 * 067 * <p> 068 * To interact with this object, simply pass it in as a constructor argument or in an INIT hook. 069 * <p class='bcode w800'> 070 * <jc>// Option #1 - Pass in through constructor.</jc> 071 * <jk>public</jk> MyResource(RestContextBuilder builder) { 072 * builder 073 * .pojoSwaps(TemporalCalendarSwap.IsoLocalDateTime.<jk>class</jk>) 074 * .set(<jsf>PARSER_debug</jsf>, <jk>true</jk>); 075 * } 076 * 077 * <jc>// Option #2 - Use an INIT hook.</jc> 078 * <ja>@RestHook</ja>(<jsf>INIT</jsf>) 079 * <jk>public void</jk> init(RestContextBuilder builder) <jk>throws</jk> Exception { 080 * builder 081 * .pojoSwaps(TemporalCalendarSwap.IsoLocalDateTime.<jk>class</jk>) 082 * .set(<jsf>PARSER_debug</jsf>, <jk>true</jk>); 083 * } 084 * </p> 085 * 086 * <ul class='seealso'> 087 * <li class='link'>{@doc juneau-rest-server.RestContext} 088 * </ul> 089 */ 090public class RestContextBuilder extends BeanContextBuilder implements ServletConfig { 091 092 final ServletConfig inner; 093 094 Class<?> resourceClass; 095 Object resource; 096 ServletContext servletContext; 097 RestContext parentContext; 098 099 //----------------------------------------------------------------------------------------------------------------- 100 // The following fields are meant to be modifiable. 101 // They should not be declared final. 102 // Read-only snapshots of these will be made in RestServletContext. 103 //----------------------------------------------------------------------------------------------------------------- 104 105 RestContextProperties properties; 106 Config config; 107 VarResolverBuilder varResolverBuilder; 108 109 @SuppressWarnings("deprecation") 110 RestContextBuilder(ServletConfig servletConfig, Class<?> resourceClass, RestContext parentContext) throws ServletException { 111 this.inner = servletConfig; 112 this.resourceClass = resourceClass; 113 this.parentContext = parentContext; 114 this.properties = new RestContextProperties(); 115 116 ClassInfo rci = ClassInfo.of(resourceClass); 117 118 // Default values. 119 logger(BasicRestLogger.class); 120 partSerializer(OpenApiSerializer.class); 121 partParser(OpenApiParser.class); 122 staticFileResponseHeader("Cache-Control", "max-age=86400, public"); 123 encoders(IdentityEncoder.INSTANCE); 124 responseHandlers( 125 ReaderHandler.class, 126 InputStreamHandler.class, 127 DefaultHandler.class 128 ); 129 130 try { 131 132 varResolverBuilder = new VarResolverBuilder() 133 .defaultVars() 134 .vars(ConfigVar.class) 135 .vars(FileVar.class) 136 .contextObject("crm", new ClasspathResourceManager(resourceClass)); 137 138 VarResolver vr = varResolverBuilder.build(); 139 140 List<AnnotationInfo<RestResource>> restResourceAnnotationsParentFirst = rci.getAnnotationInfosParentFirst(RestResource.class); 141 142 // Find our config file. It's the last non-empty @RestResource(config). 143 String configPath = ""; 144 for (AnnotationInfo<RestResource> r : restResourceAnnotationsParentFirst) 145 if (! r.getAnnotation().config().isEmpty()) 146 configPath = r.getAnnotation().config(); 147 String cf = vr.resolve(configPath); 148 149 if ("SYSTEM_DEFAULT".equals(cf)) 150 this.config = Config.getSystemDefault(); 151 152 if (this.config == null) { 153 ConfigBuilder cb = Config.create().varResolver(vr); 154 if (! cf.isEmpty()) 155 cb.name(cf); 156 this.config = cb.build(); 157 } 158 159 // Add our config file to the variable resolver. 160 varResolverBuilder.contextObject(ConfigVar.SESSION_config, config); 161 vr = varResolverBuilder.build(); 162 163 // Add the servlet init parameters to our properties. 164 if (servletConfig != null) { 165 for (Enumeration<String> ep = servletConfig.getInitParameterNames(); ep.hasMoreElements();) { 166 String p = ep.nextElement(); 167 String initParam = servletConfig.getInitParameter(p); 168 set(vr.resolve(p), vr.resolve(initParam)); 169 } 170 } 171 172 applyAnnotations(rci.getAnnotationListParentFirst(ConfigAnnotationFilter.INSTANCE), vr.createSession()); 173 174 // Load stuff from parent-to-child order. 175 // This allows child settings to overwrite parent settings. 176 for (AnnotationInfo<RestResource> e : restResourceAnnotationsParentFirst) { 177 178 RestResource r = e.getAnnotation(); 179 for (Property p : r.properties()) 180 set(vr.resolve(p.name()), vr.resolve(p.value())); 181 for (String p : r.flags()) 182 set(p, true); 183 } 184 185 } catch (Exception e) { 186 throw new ServletException(e); 187 } 188 } 189 190 @Override /* BeanContextBuilder */ 191 public RestContext build() { 192 try { 193 return new RestContext(this); 194 } catch (Exception e) { 195 throw toHttpException(e, InternalServerError.class); 196 } 197 } 198 199 /* 200 * Calls all @RestHook(INIT) methods on the specified resource object. 201 */ 202 RestContextBuilder init(Object resource) throws ServletException { 203 this.resource = resource; 204 ClassInfo rci = ClassInfo.of(resourceClass); 205 206 Map<String,MethodInfo> map = new LinkedHashMap<>(); 207 for (MethodInfo m : rci.getAllMethodsParentFirst()) { 208 if (m.hasAnnotation(RestHook.class) && m.getAnnotation(RestHook.class).value() == HookEvent.INIT) { 209 m.setAccessible(); 210 String sig = m.getSignature(); 211 if (! map.containsKey(sig)) 212 map.put(sig, m); 213 } 214 } 215 for (MethodInfo m : map.values()) { 216 assertArgsOnlyOfType(m, RestContextBuilder.class, ServletConfig.class); 217 Class<?>[] pt = m.getRawParamTypes(); 218 Object[] args = new Object[pt.length]; 219 for (int i = 0; i < args.length; i++) { 220 if (pt[i] == RestContextBuilder.class) 221 args[i] = this; 222 else 223 args[i] = this.inner; 224 } 225 try { 226 m.invoke(resource, args); 227 } catch (Exception e) { 228 throw new RestServletException("Exception thrown from @RestHook(INIT) method {0}.", m).initCause(e); 229 } 230 } 231 return this; 232 } 233 234 private static void assertArgsOnlyOfType(MethodInfo m, Class<?>...args) { 235 if (! m.argsOnlyOfType(args)) 236 throw new FormattedIllegalArgumentException("Invalid arguments passed to method {0}. Only arguments of type {1} are allowed.", m, args); 237 } 238 239 RestContextBuilder servletContext(ServletContext servletContext) { 240 this.servletContext = servletContext; 241 return this; 242 } 243 244 /** 245 * Adds the specified {@link Var} classes to this config. 246 * 247 * <p> 248 * These variables affect the variable resolver returned by {@link RestRequest#getVarResolverSession()} which is 249 * used to resolve string variables of the form <js>"$X{...}"</js>. 250 * 251 * <p> 252 * See {@link RestContext#getVarResolver()} for a list of predefined variables. 253 * 254 * @param vars The {@link Var} classes to add to this config. 255 * @return This object (for method chaining). 256 */ 257 public RestContextBuilder vars(Class<?>...vars) { 258 this.varResolverBuilder.vars(vars); 259 return this; 260 } 261 262 /** 263 * Adds a var context object to this config. 264 * 265 * <p> 266 * Var context objects are read-only objects associated with the variable resolver for vars that require external 267 * information. 268 * 269 * <p> 270 * For example, the {@link ConfigVar} needs access to this resource's {@link Config} through the 271 * {@link ConfigVar#SESSION_config} object that can be specified as either a session object (temporary) or 272 * context object (permanent). 273 * In this case, we call the following code to add it to the context map: 274 * <p class='bcode w800'> 275 * config.addVarContextObject(<jsf>SESSION_config</jsf>, configFile); 276 * </p> 277 * 278 * @param name The context object key (i.e. the name that the Var class looks for). 279 * @param object The context object. 280 * @return This object (for method chaining). 281 */ 282 public RestContextBuilder varContextObject(String name, Object object) { 283 this.varResolverBuilder.contextObject(name, object); 284 return this; 285 } 286 287 /** 288 * Overwrites the default config file with a custom config file. 289 * 290 * <p> 291 * By default, the config file is determined using the {@link RestResource#config() @RestResource(config)} 292 * annotation. 293 * This method allows you to programmatically override it with your own custom config file. 294 * 295 * @param config The new config file. 296 * @return This object (for method chaining). 297 */ 298 public RestContextBuilder config(Config config) { 299 this.config = config; 300 return this; 301 } 302 303 /** 304 * Creates a new {@link PropertyStore} object initialized with the properties defined in this config. 305 * 306 * @return A new property store. 307 */ 308 protected PropertyStoreBuilder createPropertyStore() { 309 return PropertyStore.create().add(properties); 310 } 311 312 313 //---------------------------------------------------------------------------------------------------- 314 // Methods that give access to the config file, var resolver, and properties. 315 //---------------------------------------------------------------------------------------------------- 316 317 /** 318 * Returns the external configuration file for this resource. 319 * 320 * <p> 321 * The configuration file location is determined via the {@link RestResource#config() @RestResource(config)} 322 * annotation on the resource. 323 * 324 * <p> 325 * The config file can be programmatically overridden by adding the following method to your resource: 326 * <p class='bcode w800'> 327 * <jk>public</jk> Config createConfig(ServletConfig servletConfig) <jk>throws</jk> ServletException; 328 * </p> 329 * 330 * <p> 331 * If a config file is not set up, then an empty config file will be returned that is not backed by any file. 332 * 333 * @return The external config file for this resource. Never <jk>null</jk>. 334 */ 335 public Config getConfig() { 336 return config; 337 } 338 339 /** 340 * Returns the configuration properties for this resource. 341 * 342 * <p> 343 * The configuration properties are determined via the {@link RestResource#properties() @RestResource(properties)} annotation on the resource. 344 * 345 * <p> 346 * The configuration properties can be augmented programmatically by adding the following method to your resource: 347 * <p class='bcode w800'> 348 * <jk>public</jk> RestContextProperties createProperties(ServletConfig servletConfig) <jk>throws</jk> ServletException; 349 * </p> 350 * 351 * <p> 352 * These properties can be modified during servlet initialization. 353 * However, any modifications made after {@link RestServlet#init(ServletConfig)} has been called will have no effect. 354 * 355 * @return The configuration properties for this resource. Never <jk>null</jk>. 356 */ 357 public RestContextProperties getProperties() { 358 return properties; 359 } 360 361 /** 362 * Creates the variable resolver for this resource. 363 * 364 * <p> 365 * The variable resolver returned by this method can resolve the following variables: 366 * <ul> 367 * <li>{@link SystemPropertiesVar} 368 * <li>{@link EnvVariablesVar} 369 * <li>{@link ConfigVar} 370 * <li>{@link IfVar} 371 * <li>{@link SwitchVar} 372 * </ul> 373 * 374 * <p> 375 * Note that the variables supported here are only a subset of those returned by 376 * {@link RestRequest#getVarResolverSession()}. 377 * 378 * @return The variable resolver for this resource. Never <jk>null</jk>. 379 */ 380 public VarResolverBuilder getVarResolverBuilder() { 381 return varResolverBuilder; 382 } 383 384 /** 385 * Returns the REST path defined on this builder. 386 * 387 * @return The REST path defined on this builder. 388 */ 389 public String getPath() { 390 Object p = peek(REST_path); 391 return p == null ? "_" : p.toString(); 392 } 393 394 //---------------------------------------------------------------------------------------------------- 395 // Properties 396 //---------------------------------------------------------------------------------------------------- 397 398 /** 399 * Configuration property: Allow body URL parameter. 400 * 401 * <p> 402 * When enabled, the HTTP body content on PUT and POST requests can be passed in as text using the <js>"body"</js> 403 * URL parameter. 404 * <br> 405 * For example: 406 * <p class='bcode w800'> 407 * ?body=(name='John%20Smith',age=45) 408 * </p> 409 * 410 * <ul class='seealso'> 411 * <li class='jf'>{@link RestContext#REST_allowBodyParam} 412 * </ul> 413 * 414 * @param value 415 * The new value for this setting. 416 * <br>The default is <jk>true</jk>. 417 * @return This object (for method chaining). 418 */ 419 public RestContextBuilder allowBodyParam(boolean value) { 420 return set(REST_allowBodyParam, value); 421 } 422 423 /** 424 * Configuration property: Allowed header URL parameters. 425 * 426 * <p> 427 * When specified, allows headers such as <js>"Accept"</js> and <js>"Content-Type"</js> to be passed in as URL query 428 * parameters. 429 * <br> 430 * For example: 431 * <p class='bcode w800'> 432 * ?Accept=text/json&Content-Type=text/json 433 * </p> 434 * 435 * <ul class='seealso'> 436 * <li class='jf'>{@link RestContext#REST_allowedHeaderParams} 437 * </ul> 438 * 439 * @param value 440 * The new value for this setting. 441 * <br>The default is <jk>true</jk>. 442 * @return This object (for method chaining). 443 */ 444 public RestContextBuilder allowedHeaderParams(String value) { 445 return set(REST_allowedHeaderParams, value); 446 } 447 448 /** 449 * Configuration property: Allowed method headers. 450 * 451 * <p> 452 * A comma-delimited list of HTTP method names that are allowed to be passed as values in an <c>X-Method</c> HTTP header 453 * to override the real HTTP method name. 454 * <p> 455 * Allows you to override the actual HTTP method with a simulated method. 456 * <br>For example, if an HTTP Client API doesn't support <c>PATCH</c> but does support <c>POST</c> (because 457 * <c>PATCH</c> is not part of the original HTTP spec), you can add a <c>X-Method: PATCH</c> header on a normal 458 * <c>HTTP POST /foo</c> request call which will make the HTTP call look like a <c>PATCH</c> request in any of the REST APIs. 459 * 460 * <ul class='seealso'> 461 * <li class='jf'>{@link RestContext#REST_allowedMethodHeaders} 462 * </ul> 463 * 464 * @param value 465 * The new value for this setting. 466 * <br>The default is <jk>true</jk>. 467 * @return This object (for method chaining). 468 */ 469 public RestContextBuilder allowedMethodHeaders(String value) { 470 return set(REST_allowedMethodHeaders, value); 471 } 472 473 /** 474 * Configuration property: Allowed method parameters. 475 * 476 * <p> 477 * When specified, the HTTP method can be overridden by passing in a <js>"method"</js> URL parameter on a regular 478 * GET request. 479 * <br> 480 * For example: 481 * <p class='bcode w800'> 482 * ?method=OPTIONS 483 * </p> 484 * 485 * <ul class='seealso'> 486 * <li class='jf'>{@link RestContext#REST_allowedMethodParams} 487 * </ul> 488 * 489 * @param value 490 * The new value for this setting. 491 * <br>The default is <code>[<js>"HEAD"</js>,<js>"OPTIONS"</js>]</code>. 492 * <br>Individual values can also be comma-delimited lists. 493 * @return This object (for method chaining). 494 */ 495 public RestContextBuilder allowedMethodParams(String value) { 496 return set(REST_allowedMethodParams, value); 497 } 498 499 /** 500 * Configuration property: Allow header URL parameters. 501 * 502 * <p> 503 * When enabled, headers such as <js>"Accept"</js> and <js>"Content-Type"</js> to be passed in as URL query 504 * parameters. 505 * <br> 506 * For example: 507 * <p class='bcode w800'> 508 * ?Accept=text/json&Content-Type=text/json 509 * </p> 510 * 511 * <ul class='seealso'> 512 * <li class='jf'>{@link RestContext#REST_allowHeaderParams} 513 * </ul> 514 * 515 * @param value 516 * The new value for this setting. 517 * <br>The default is <jk>true</jk>. 518 * @return This object (for method chaining). 519 * @deprecated Use {@link #allowedHeaderParams(String)} 520 */ 521 @Deprecated 522 public RestContextBuilder allowHeaderParams(boolean value) { 523 return set(REST_allowedHeaderParams, value ? "*" : null); 524 } 525 526 /** 527 * Configuration property: REST call handler. 528 * 529 * <p> 530 * This class handles the basic lifecycle of an HTTP REST call. 531 * <br>Subclasses can be used to customize how these HTTP calls are handled. 532 * 533 * <ul class='seealso'> 534 * <li class='jf'>{@link RestContext#REST_callHandler} 535 * </ul> 536 * 537 * @param value 538 * The new value for this setting. 539 * <br>The default is {@link BasicRestCallHandler}. 540 * @return This object (for method chaining). 541 */ 542 public RestContextBuilder callHandler(Class<? extends RestCallHandler> value) { 543 return set(REST_callHandler, value); 544 } 545 546 /** 547 * Configuration property: REST call handler. 548 * 549 * <p> 550 * Same as {@link #callHandler(Class)} except input is a pre-constructed instance. 551 * 552 * <ul class='seealso'> 553 * <li class='jf'>{@link RestContext#REST_callHandler} 554 * </ul> 555 * 556 * @param value 557 * The new value for this setting. 558 * <br>The default is {@link BasicRestCallHandler}. 559 * @return This object (for method chaining). 560 */ 561 public RestContextBuilder callHandler(RestCallHandler value) { 562 return set(REST_callHandler, value); 563 } 564 565 /** 566 * Configuration property: REST call logger. 567 * 568 * <p> 569 * Specifies the logger to use for logging of HTTP requests and responses. 570 * 571 * <ul class='seealso'> 572 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 573 * <li class='jf'>{@link RestContext#REST_callLogger} 574 * </ul> 575 * 576 * @param value 577 * The new value for this setting. 578 * <br>The default is {@link BasicRestCallLogger}. 579 * @return This object (for method chaining). 580 */ 581 public RestContextBuilder callLogger(Class<? extends RestCallLogger> value) { 582 return set(REST_callLogger, value); 583 } 584 585 /** 586 * Configuration property: REST call logger. 587 * 588 * <p> 589 * Specifies the logger to use for logging of HTTP requests and responses. 590 * 591 * <ul class='seealso'> 592 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 593 * <li class='jf'>{@link RestContext#REST_callLogger} 594 * </ul> 595 * 596 * @param value 597 * The new value for this setting. 598 * <br>The default is {@link BasicRestCallLogger}. 599 * @return This object (for method chaining). 600 */ 601 public RestContextBuilder callLogger(RestCallLogger value) { 602 return set(REST_callLogger, value); 603 } 604 605 /** 606 * Configuration property: REST call logging rules. 607 * 608 * <p> 609 * Specifies rules on how to handle logging of HTTP requests/responses. 610 * 611 * <ul class='seealso'> 612 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 613 * <li class='jf'>{@link RestContext#REST_callLoggerConfig} 614 * </ul> 615 * 616 * @param value 617 * The new value for this setting. 618 * <br>The default is {@link RestCallLoggerConfig#DEFAULT}. 619 * @return This object (for method chaining). 620 */ 621 public RestContextBuilder callLoggerConfig(RestCallLoggerConfig value) { 622 return set(REST_callLoggerConfig, value); 623 } 624 625 /** 626 * Configuration property: Children. 627 * 628 * <p> 629 * Defines children of this resource. 630 * 631 * <p> 632 * A REST child resource is simply another servlet that is initialized as part of the parent resource and has a 633 * servlet path directly under the parent servlet path. 634 * 635 * <ul class='seealso'> 636 * <li class='jf'>{@link RestContext#REST_children} 637 * </ul> 638 * 639 * @param values The values to add to this setting. 640 * @return This object (for method chaining). 641 */ 642 public RestContextBuilder children(Class<?>...values) { 643 return addTo(REST_children, values); 644 } 645 646 /** 647 * Configuration property: Children. 648 * 649 * <p> 650 * Same as {@link #children(Class...)} except input is pre-constructed instances. 651 * 652 * <ul class='seealso'> 653 * <li class='jf'>{@link RestContext#REST_children} 654 * </ul> 655 * 656 * @param values The values to add to this setting. 657 * @return This object (for method chaining). 658 */ 659 public RestContextBuilder children(Object...values) { 660 return addTo(REST_children, values); 661 } 662 663 /** 664 * Configuration property: Children. 665 * 666 * <p> 667 * Shortcut for adding a single child to this resource. 668 * 669 * <p> 670 * This can be used for resources that don't have a {@link RestResource#path() @RestResource(path)} annotation. 671 * 672 * <ul class='seealso'> 673 * <li class='jf'>{@link RestContext#REST_children} 674 * </ul> 675 * 676 * @param path The child path relative to the parent resource URI. 677 * @param child The child to add to this resource. 678 * @return This object (for method chaining). 679 */ 680 public RestContextBuilder child(String path, Object child) { 681 return addTo(REST_children, new RestChild(path, child)); 682 } 683 684 /** 685 * Configuration property: Classpath resource finder. 686 * 687 * <p> 688 * Used to retrieve localized files from the classpath. 689 * 690 * <ul class='seealso'> 691 * <li class='jf'>{@link RestContext#REST_classpathResourceFinder} 692 * </ul> 693 * 694 * @param value 695 * The new value for this setting. 696 * <br>The default is {@link ClasspathResourceFinderBasic}. 697 * @return This object (for method chaining). 698 */ 699 public RestContextBuilder classpathResourceFinder(Class<? extends ClasspathResourceFinder> value) { 700 return set(REST_classpathResourceFinder, value); 701 } 702 703 /** 704 * Configuration property: Classpath resource finder. 705 * 706 * <p> 707 * Same as {@link #classpathResourceFinder(ClasspathResourceFinder)} except input is a pre-constructed instance. 708 * 709 * <ul class='seealso'> 710 * <li class='jf'>{@link RestContext#REST_classpathResourceFinder} 711 * </ul> 712 * 713 * @param value 714 * The new value for this setting. 715 * <br>The default is {@link ClasspathResourceFinderBasic}. 716 * @return This object (for method chaining). 717 */ 718 public RestContextBuilder classpathResourceFinder(ClasspathResourceFinder value) { 719 return set(REST_classpathResourceFinder, value); 720 } 721 722 /** 723 * Configuration property: Client version header. 724 * 725 * <p> 726 * Specifies the name of the header used to denote the client version on HTTP requests. 727 * 728 * <p> 729 * The client version is used to support backwards compatibility for breaking REST interface changes. 730 * <br>Used in conjunction with {@link RestMethod#clientVersion() @RestMethod(clientVersion)} annotation. 731 * 732 * <ul class='seealso'> 733 * <li class='jf'>{@link RestContext#REST_clientVersionHeader} 734 * </ul> 735 * 736 * @param value 737 * The new value for this setting. 738 * <br>The default is <js>"X-Client-Version"</js>. 739 * @return This object (for method chaining). 740 */ 741 public RestContextBuilder clientVersionHeader(String value) { 742 return set(REST_clientVersionHeader, value); 743 } 744 745 /** 746 * Configuration property: Class-level response converters. 747 * 748 * <p> 749 * Associates one or more {@link RestConverter converters} with a resource class. 750 * 751 * <ul class='seealso'> 752 * <li class='jf'>{@link RestContext#REST_converters} 753 * </ul> 754 * 755 * @param values The values to add to this setting. 756 * @return This object (for method chaining). 757 */ 758 public RestContextBuilder converters(Class<?>...values) { 759 return addTo(REST_converters, values); 760 } 761 762 /** 763 * Configuration property: Response converters. 764 * 765 * <p> 766 * Same as {@link #converters(Class...)} except input is pre-constructed instances. 767 * 768 * <ul class='seealso'> 769 * <li class='jf'>{@link RestContext#REST_converters} 770 * </ul> 771 * 772 * @param values The values to add to this setting. 773 * @return This object (for method chaining). 774 */ 775 public RestContextBuilder converters(RestConverter...values) { 776 return addTo(REST_converters, values); 777 } 778 779 /** 780 * Configuration property: Debug mode. 781 * 782 * Enables the following: 783 * <ul class='spaced-list'> 784 * <li> 785 * HTTP request/response bodies are cached in memory for logging purposes. 786 * <li> 787 * Request/response messages are automatically logged. 788 * </ul> 789 * 790 * <ul class='seealso'> 791 * <li class='jf'>{@link RestContext#REST_debug} 792 * <li class='jf'>{@link BeanContext#BEAN_debug} 793 * </ul> 794 * 795 * @param value The new value for this setting. 796 * @return This object (for method chaining). 797 */ 798 @Override 799 public RestContextBuilder debug(boolean value) { 800 super.debug(value); 801 return debug(Enablement.TRUE); 802 } 803 804 /** 805 * Configuration property: Debug mode. 806 * 807 * <p> 808 * Enables the following: 809 * <ul class='spaced-list'> 810 * <li> 811 * HTTP request/response bodies are cached in memory for logging purposes. 812 * </ul> 813 * 814 * @param value The new value for this setting. 815 * @return This object (for method chaining). 816 */ 817 public RestContextBuilder debug(Enablement value) { 818 return set(REST_debug, value); 819 } 820 821 /** 822 * Configuration property: Default character encoding. 823 * 824 * <p> 825 * The default character encoding for the request and response if not specified on the request. 826 * 827 * <ul class='seealso'> 828 * <li class='jf'>{@link RestContext#REST_defaultCharset} 829 * </ul> 830 * 831 * @param value 832 * The new value for this setting. 833 * <br>The default is <js>"utf-8"</js>. 834 * @return This object (for method chaining). 835 */ 836 public RestContextBuilder defaultCharset(String value) { 837 return set(REST_defaultCharset, value); 838 } 839 840 /** 841 * Configuration property: Default character encoding. 842 * 843 * <p> 844 * Same as {@link #defaultCharset(Charset)} but takes in an instance of {@link Charset}. 845 * 846 * <ul class='seealso'> 847 * <li class='jf'>{@link RestContext#REST_defaultCharset} 848 * </ul> 849 * 850 * @param value 851 * The new value for this setting. 852 * <br>The default is <js>"utf-8"</js>. 853 * @return This object (for method chaining). 854 */ 855 public RestContextBuilder defaultCharset(Charset value) { 856 return set(REST_defaultCharset, value); 857 } 858 859 /** 860 * Configuration property: Default request attributes. 861 * 862 * <p> 863 * Specifies default values for request attributes if they're not already set on the request. 864 * 865 * <ul class='seealso'> 866 * <li class='jf'>{@link RestContext#REST_attrs} 867 * </ul> 868 * 869 * @param values The attributes in the format <js>"Name: value"</js>. 870 * @return This object (for method chaining). 871 * @throws RestServletException If malformed header is found. 872 */ 873 public RestContextBuilder attrs(String...values) throws RestServletException { 874 for (String v : values) { 875 String[] p = RestUtils.parseKeyValuePair(v); 876 if (p == null) 877 throw new RestServletException("Invalid default request attribute specified: ''{0}''. Must be in the format: ''Name: value''", v); 878 defaultRequestHeader(p[0], p[1]); 879 } 880 return this; 881 } 882 883 /** 884 * Configuration property: Default request headers. 885 * 886 * <p> 887 * Specifies default values for request headers if they're not passed in through the request. 888 * 889 * <ul class='seealso'> 890 * <li class='jf'>{@link RestContext#REST_defaultRequestHeaders} 891 * </ul> 892 * 893 * @param headers The headers in the format <js>"Header-Name: header-value"</js>. 894 * @return This object (for method chaining). 895 * @throws RestServletException If malformed header is found. 896 */ 897 public RestContextBuilder defaultRequestHeaders(String...headers) throws RestServletException { 898 for (String header : headers) { 899 String[] h = RestUtils.parseHeader(header); 900 if (h == null) 901 throw new RestServletException("Invalid default request header specified: ''{0}''. Must be in the format: ''Header-Name: header-value''", header); 902 defaultRequestHeader(h[0], h[1]); 903 } 904 return this; 905 } 906 907 /** 908 * Specifies a default <c>Accept</c> header value if not specified on a request. 909 * 910 * @param value 911 * The default value of the <c>Accept</c> header. 912 * <br>Ignored if <jk>null</jk> or empty. 913 * @return This object (for method chaining). 914 */ 915 public RestContextBuilder defaultAccept(String value) { 916 if (isNotEmpty(value)) 917 defaultRequestHeader("Accept", value); 918 return this; 919 } 920 921 /** 922 * Specifies a default <c>Content-Type</c> header value if not specified on a request. 923 * 924 * @param value 925 * The default value of the <c>Content-Type</c> header. 926 * <br>Ignored if <jk>null</jk> or empty. 927 * @return This object (for method chaining). 928 */ 929 public RestContextBuilder defaultContentType(String value) { 930 if (isNotEmpty(value)) 931 defaultRequestHeader("Content-Type", value); 932 return this; 933 } 934 935 /** 936 * Configuration property: Default request attribute. 937 * 938 * <p> 939 * Same as {@link #attrs(String...)} but adds a single attribute name/value pair. 940 * 941 * <ul class='seealso'> 942 * <li class='jf'>{@link RestContext#REST_attrs} 943 * </ul> 944 * 945 * @param name The HTTP header name. 946 * @param value The HTTP header value. 947 * @return This object (for method chaining). 948 */ 949 public RestContextBuilder attr(String name, Object value) { 950 return addTo(REST_attrs, name, value); 951 } 952 953 /** 954 * Configuration property: Default request headers. 955 * 956 * <p> 957 * Same as {@link #defaultRequestHeaders(String...)} but adds a single header name/value pair. 958 * 959 * <ul class='seealso'> 960 * <li class='jf'>{@link RestContext#REST_defaultRequestHeaders} 961 * </ul> 962 * 963 * @param name The HTTP header name. 964 * @param value The HTTP header value. 965 * @return This object (for method chaining). 966 */ 967 public RestContextBuilder defaultRequestHeader(String name, Object value) { 968 return addTo(REST_defaultRequestHeaders, name, value); 969 } 970 971 /** 972 * Configuration property: Default response headers. 973 * 974 * <p> 975 * Specifies default values for response headers if they're not set after the Java REST method is called. 976 * 977 * <ul class='seealso'> 978 * <li class='jf'>{@link RestContext#REST_defaultResponseHeaders} 979 * </ul> 980 * 981 * @param headers The headers in the format <js>"Header-Name: header-value"</js>. 982 * @return This object (for method chaining). 983 * @throws RestServletException If malformed header is found. 984 */ 985 public RestContextBuilder defaultResponseHeaders(String...headers) throws RestServletException { 986 for (String header : headers) { 987 String[] h = RestUtils.parseHeader(header); 988 if (h == null) 989 throw new RestServletException("Invalid default response header specified: ''{0}''. Must be in the format: ''Header-Name: header-value''", header); 990 defaultResponseHeader(h[0], h[1]); 991 } 992 return this; 993 } 994 995 /** 996 * Configuration property: Default response headers. 997 * 998 * <p> 999 * Same as {@link #defaultResponseHeaders(String...)} but adds a single header name/value pair. 1000 * 1001 * <ul class='seealso'> 1002 * <li class='jf'>{@link RestContext#REST_defaultResponseHeaders} 1003 * </ul> 1004 * 1005 * @param name The HTTP header name. 1006 * @param value The HTTP header value. 1007 * @return This object (for method chaining). 1008 */ 1009 public RestContextBuilder defaultResponseHeader(String name, Object value) { 1010 return addTo(REST_defaultResponseHeaders, name, value); 1011 } 1012 1013 /** 1014 * Configuration property: Compression encoders. 1015 * 1016 * <p> 1017 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 1018 * 1019 * <ul class='seealso'> 1020 * <li class='jf'>{@link RestContext#REST_encoders} 1021 * </ul> 1022 * 1023 * @param values The values to add to this setting. 1024 * @return This object (for method chaining). 1025 */ 1026 public RestContextBuilder encoders(Class<?>...values) { 1027 return addTo(REST_encoders, values); 1028 } 1029 1030 /** 1031 * Configuration property: Compression encoders. 1032 * 1033 * <p> 1034 * Same as {@link #encoders(Class...)} except input a pre-constructed instances. 1035 * 1036 * <ul class='seealso'> 1037 * <li class='jf'>{@link RestContext#REST_encoders} 1038 * </ul> 1039 * 1040 * @param values The values to add to this setting. 1041 * @return This object (for method chaining). 1042 */ 1043 public RestContextBuilder encoders(Encoder...values) { 1044 return addTo(REST_encoders, values); 1045 } 1046 1047 /** 1048 * Configuration property: Class-level guards. 1049 * 1050 * <p> 1051 * Associates one or more {@link RestGuard RestGuards} with all REST methods defined in this class. 1052 * 1053 * <ul class='seealso'> 1054 * <li class='jf'>{@link RestContext#REST_guards} 1055 * </ul> 1056 * 1057 * @param values The values to add to this setting. 1058 * @return This object (for method chaining). 1059 */ 1060 public RestContextBuilder guards(Class<?>...values) { 1061 return addTo(REST_guards, values); 1062 } 1063 1064 /** 1065 * Configuration property: Class-level guards. 1066 * 1067 * <p> 1068 * Same as {@link #guards(Class...)} except input is pre-constructed instances. 1069 * 1070 * <ul class='seealso'> 1071 * <li class='jf'>{@link RestContext#REST_guards} 1072 * </ul> 1073 * 1074 * @param values The values to add to this setting. 1075 * @return This object (for method chaining). 1076 */ 1077 public RestContextBuilder guards(RestGuard...values) { 1078 return addTo(REST_guards, values); 1079 } 1080 1081 /** 1082 * Configuration property: REST info provider. 1083 * 1084 * <p> 1085 * Class used to retrieve title/description/swagger information about a resource. 1086 * 1087 * <ul class='seealso'> 1088 * <li class='jf'>{@link RestContext#REST_infoProvider} 1089 * </ul> 1090 * 1091 * @param value 1092 * The new value for this setting. 1093 * <br>The default is {@link BasicRestInfoProvider}. 1094 * @return This object (for method chaining). 1095 */ 1096 public RestContextBuilder infoProvider(Class<? extends RestInfoProvider> value) { 1097 return set(REST_infoProvider, value); 1098 } 1099 1100 /** 1101 * Configuration property: REST info provider. 1102 * 1103 * <p> 1104 * Same as {@link #infoProvider(Class)} except input is a pre-constructed instance. 1105 * 1106 * <ul class='seealso'> 1107 * <li class='jf'>{@link RestContext#REST_infoProvider} 1108 * </ul> 1109 * 1110 * @param value 1111 * The new value for this setting. 1112 * <br>The default is {@link BasicRestInfoProvider}. 1113 * @return This object (for method chaining). 1114 */ 1115 public RestContextBuilder infoProvider(RestInfoProvider value) { 1116 return set(REST_infoProvider, value); 1117 } 1118 1119 /** 1120 * Configuration property: REST logger. 1121 * 1122 * <p> 1123 * Specifies the logger to use for logging. 1124 * 1125 * <ul class='seealso'> 1126 * <li class='jf'>{@link RestContext#REST_logger} 1127 * </ul> 1128 * 1129 * @param value 1130 * The new value for this setting. 1131 * <br>The default is {@link BasicRestCallLogger}. 1132 * <br>Can be <jk>null</jk> to disable logging. 1133 * @return This object (for method chaining). 1134 * @deprecated Use {@link #callLogger(Class)} 1135 */ 1136 @Deprecated 1137 public RestContextBuilder logger(Class<? extends RestLogger> value) { 1138 return set(REST_logger, value); 1139 } 1140 1141 /** 1142 * Configuration property: REST logger. 1143 * 1144 * <p> 1145 * Same as {@link #logger(Class)} except input is a pre-constructed instance. 1146 * 1147 * <ul class='seealso'> 1148 * <li class='jf'>{@link RestContext#REST_logger} 1149 * </ul> 1150 * 1151 * @param value 1152 * The new value for this setting. 1153 * <br>The default is {@link BasicRestLogger}. 1154 * <br>Can be <jk>null</jk> to disable logging. 1155 * @return This object (for method chaining). 1156 * @deprecated Use {@link #callLogger(RestCallLogger)} 1157 */ 1158 @Deprecated 1159 public RestContextBuilder logger(RestLogger value) { 1160 return set(REST_logger, value); 1161 } 1162 1163 /** 1164 * Configuration property: The maximum allowed input size (in bytes) on HTTP requests. 1165 * 1166 * <p> 1167 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 1168 * in out-of-memory errors which could affect system stability. 1169 * 1170 * <ul class='seealso'> 1171 * <li class='jf'>{@link RestContext#REST_maxInput} 1172 * </ul> 1173 * 1174 * @param value 1175 * The new value for this setting. 1176 * <br>The default is <js>"100M"</js>. 1177 * @return This object (for method chaining). 1178 */ 1179 public RestContextBuilder maxInput(String value) { 1180 return set(REST_maxInput, value); 1181 } 1182 1183 /** 1184 * Configuration property: Messages. 1185 * 1186 * <p> 1187 * Identifies the location of the resource bundle for this class. 1188 * 1189 * <ul class='seealso'> 1190 * <li class='jf'>{@link RestContext#REST_messages} 1191 * </ul> 1192 * 1193 * @param values The values to add to this setting. 1194 * @return This object (for method chaining). 1195 */ 1196 public RestContextBuilder messages(MessageBundleLocation...values) { 1197 return addTo(REST_messages, values); 1198 } 1199 1200 /** 1201 * Configuration property: Messages. 1202 * 1203 * <p> 1204 * Same as {@link #messages(MessageBundleLocation...)} except allows you to pass in the base class and bundle 1205 * path separately. 1206 * 1207 * <ul class='seealso'> 1208 * <li class='jf'>{@link RestContext#REST_messages} 1209 * </ul> 1210 * 1211 * @param baseClass 1212 * The base class that the bundle path is relative to. 1213 * <br>If <jk>null</jk>, assumed to be the resource class itself. 1214 * @param bundlePath The bundle path relative to the base class. 1215 * @return This object (for method chaining). 1216 */ 1217 public RestContextBuilder messages(Class<?> baseClass, String bundlePath) { 1218 return addTo(REST_messages, new MessageBundleLocation(baseClass, bundlePath)); 1219 } 1220 1221 /** 1222 * Configuration property: Messages. 1223 * 1224 * <p> 1225 * Same as {@link #messages(Class,String)} except assumes the base class is the resource class itself. 1226 * 1227 * <ul class='seealso'> 1228 * <li class='jf'>{@link RestContext#REST_messages} 1229 * </ul> 1230 * 1231 * @param bundlePath The bundle path relative to the base class. 1232 * @return This object (for method chaining). 1233 */ 1234 public RestContextBuilder messages(String bundlePath) { 1235 return addTo(REST_messages, new MessageBundleLocation(null, bundlePath)); 1236 } 1237 1238 /** 1239 * Configuration property: MIME types. 1240 * 1241 * <p> 1242 * Defines MIME-type file type mappings. 1243 * 1244 * <ul class='seealso'> 1245 * <li class='jf'>{@link RestContext#REST_mimeTypes} 1246 * </ul> 1247 * 1248 * @param values The values to add to this setting. 1249 * @return This object (for method chaining). 1250 */ 1251 public RestContextBuilder mimeTypes(String...values) { 1252 return addTo(REST_mimeTypes, values); 1253 } 1254 1255 /** 1256 * Configuration property: Java method parameter resolvers. 1257 * 1258 * <p> 1259 * By default, the Juneau framework will automatically Java method parameters of various types (e.g. 1260 * <c>RestRequest</c>, <c>Accept</c>, <c>Reader</c>). 1261 * This annotation allows you to provide your own resolvers for your own class types that you want resolved. 1262 * 1263 * <ul class='seealso'> 1264 * <li class='jf'>{@link RestContext#REST_paramResolvers} 1265 * </ul> 1266 * 1267 * @param values The values to add to this setting. 1268 * @return This object (for method chaining). 1269 */ 1270 @SuppressWarnings("unchecked") 1271 public RestContextBuilder paramResolvers(Class<? extends RestMethodParam>...values) { 1272 return addTo(REST_paramResolvers, values); 1273 } 1274 1275 /** 1276 * Configuration property: Java method parameter resolvers. 1277 * 1278 * <p> 1279 * Same as {@link #paramResolvers(Class...)} except input is pre-constructed instances. 1280 * 1281 * <ul class='seealso'> 1282 * <li class='jf'>{@link RestContext#REST_paramResolvers} 1283 * </ul> 1284 * 1285 * @param values The values to add to this setting. 1286 * @return This object (for method chaining). 1287 */ 1288 public RestContextBuilder paramResolvers(RestMethodParam...values) { 1289 return addTo(REST_paramResolvers, values); 1290 } 1291 1292 /** 1293 * Configuration property: Parser listener. 1294 * 1295 * <p> 1296 * Specifies the parser listener class to use for listening to non-fatal parsing errors. 1297 * 1298 * <ul class='seealso'> 1299 * <li class='jf'>{@link Parser#PARSER_listener} 1300 * </ul> 1301 * 1302 * @param value The new value for this setting. 1303 * @return This object (for method chaining). 1304 */ 1305 public RestContextBuilder parserListener(Class<? extends ParserListener> value) { 1306 if (value != ParserListener.Null.class) 1307 set(PARSER_listener, value); 1308 return this; 1309 } 1310 1311 /** 1312 * Configuration property: Parsers. 1313 * 1314 * <p> 1315 * Adds class-level parsers to this resource. 1316 * 1317 * <ul class='seealso'> 1318 * <li class='jf'>{@link RestContext#REST_parsers} 1319 * </ul> 1320 * 1321 * @param values The values to add to this setting. 1322 * @return This object (for method chaining). 1323 */ 1324 public RestContextBuilder parsers(Class<?>...values) { 1325 return addTo(REST_parsers, values); 1326 } 1327 1328 /** 1329 * Configuration property: Parsers. 1330 * 1331 * <p> 1332 * Same as {@link #parsers(Class...)} except input is pre-constructed instances. 1333 * 1334 * <p> 1335 * Parser instances are considered set-in-stone and do NOT inherit properties and transforms defined on the 1336 * resource class or method. 1337 * 1338 * <ul class='seealso'> 1339 * <li class='jf'>{@link RestContext#REST_parsers} 1340 * </ul> 1341 * 1342 * @param values The values to add to this setting. 1343 * @return This object (for method chaining). 1344 */ 1345 public RestContextBuilder parsers(Object...values) { 1346 return addTo(REST_parsers, values); 1347 } 1348 1349 /** 1350 * Configuration property: Parsers. 1351 * 1352 * <p> 1353 * Same as {@link #parsers(Class...)} except allows you to overwrite the previous value. 1354 * 1355 * <ul class='seealso'> 1356 * <li class='jf'>{@link RestContext#REST_parsers} 1357 * </ul> 1358 * 1359 * @param values The values to add to this setting. 1360 * @return This object (for method chaining). 1361 */ 1362 public RestContextBuilder parsersReplace(Object...values) { 1363 return set(REST_parsers, values); 1364 } 1365 1366 /** 1367 * Configuration property: HTTP part parser. 1368 * 1369 * <p> 1370 * Specifies the {@link HttpPartParser} to use for parsing headers, query/form parameters, and URI parts. 1371 * 1372 * <ul class='seealso'> 1373 * <li class='jf'>{@link RestContext#REST_partParser} 1374 * </ul> 1375 * 1376 * @param value 1377 * The new value for this setting. 1378 * <br>The default is {@link OpenApiParser}. 1379 * @return This object (for method chaining). 1380 */ 1381 public RestContextBuilder partParser(Class<? extends HttpPartParser> value) { 1382 if (value != HttpPartParser.Null.class) 1383 set(REST_partParser, value); 1384 return this; 1385 } 1386 1387 /** 1388 * Configuration property: HTTP part parser. 1389 * 1390 * <p> 1391 * Same as {@link #partParser(Class)} except input is a pre-constructed instance. 1392 * 1393 * <ul class='seealso'> 1394 * <li class='jf'>{@link RestContext#REST_partParser} 1395 * </ul> 1396 * 1397 * @param value 1398 * The new value for this setting. 1399 * <br>The default is {@link OpenApiParser}. 1400 * @return This object (for method chaining). 1401 */ 1402 public RestContextBuilder partParser(HttpPartParser value) { 1403 return set(REST_partParser, value); 1404 } 1405 1406 /** 1407 * Configuration property: HTTP part serializer. 1408 * 1409 * <p> 1410 * Specifies the {@link HttpPartSerializer} to use for serializing headers, query/form parameters, and URI parts. 1411 * 1412 * <ul class='seealso'> 1413 * <li class='jf'>{@link RestContext#REST_partSerializer} 1414 * </ul> 1415 * 1416 * @param value 1417 * The new value for this setting. 1418 * <br>The default is {@link OpenApiSerializer}. 1419 * @return This object (for method chaining). 1420 */ 1421 public RestContextBuilder partSerializer(Class<? extends HttpPartSerializer> value) { 1422 if (value != HttpPartSerializer.Null.class) 1423 set(REST_partSerializer, value); 1424 return this; 1425 } 1426 1427 /** 1428 * Configuration property: HTTP part serializer. 1429 * 1430 * <p> 1431 * Same as {@link #partSerializer(Class)} except input is a pre-constructed instance. 1432 * 1433 * <ul class='seealso'> 1434 * <li class='jf'>{@link RestContext#REST_partSerializer} 1435 * </ul> 1436 * 1437 * @param value 1438 * The new value for this setting. 1439 * <br>The default is {@link OpenApiSerializer}. 1440 * @return This object (for method chaining). 1441 */ 1442 public RestContextBuilder partSerializer(HttpPartSerializer value) { 1443 return set(REST_partSerializer, value); 1444 } 1445 1446 /** 1447 * Configuration property: Resource path. 1448 * 1449 * <p> 1450 * Identifies the URL subpath relative to the parent resource. 1451 * 1452 * <ul class='seealso'> 1453 * <li class='jf'>{@link RestContext#REST_path} 1454 * </ul> 1455 * 1456 * @param value The new value for this setting. 1457 * @return This object (for method chaining). 1458 */ 1459 public RestContextBuilder path(String value) { 1460 if (startsWith(value, '/')) 1461 value = value.substring(1); 1462 set(REST_path, value); 1463 return this; 1464 } 1465 1466 /** 1467 * Configuration property: Render response stack traces in responses. 1468 * 1469 * <p> 1470 * Render stack traces in HTTP response bodies when errors occur. 1471 * 1472 * <ul class='seealso'> 1473 * <li class='jf'>{@link RestContext#REST_renderResponseStackTraces} 1474 * </ul> 1475 * 1476 * @param value 1477 * The new value for this setting. 1478 * <br>The default is <jk>false</jk>. 1479 * @return This object (for method chaining). 1480 */ 1481 public RestContextBuilder renderResponseStackTraces(boolean value) { 1482 return set(REST_renderResponseStackTraces, value); 1483 } 1484 1485 /** 1486 * Configuration property: Render response stack traces in responses. 1487 * 1488 * <p> 1489 * Shortcut for calling <code>renderResponseStackTraces(<jk>true</jk>)</code>. 1490 * 1491 * <ul class='seealso'> 1492 * <li class='jf'>{@link RestContext#REST_renderResponseStackTraces} 1493 * </ul> 1494 * 1495 * @return This object (for method chaining). 1496 */ 1497 public RestContextBuilder renderResponseStackTraces() { 1498 return set(REST_renderResponseStackTraces, true); 1499 } 1500 1501 /** 1502 * REST resource resolver. 1503 * 1504 * <p> 1505 * The resolver used for resolving child resources. 1506 * 1507 * <p> 1508 * Can be used to provide customized resolution of REST resource class instances (e.g. resources retrieve from Spring). 1509 * 1510 * <ul class='seealso'> 1511 * <li class='jf'>{@link RestContext#REST_resourceResolver} 1512 * </ul> 1513 * 1514 * @param value 1515 * The new value for this setting. 1516 * <br>The default is {@link BasicRestResourceResolver}. 1517 * @return This object (for method chaining). 1518 */ 1519 public RestContextBuilder resourceResolver(Class<? extends RestResourceResolver> value) { 1520 return set(REST_resourceResolver, value); 1521 } 1522 1523 /** 1524 * REST resource resolver. 1525 * 1526 * <p> 1527 * Same as {@link #resourceResolver(Class)} except input is a pre-constructed instance. 1528 * 1529 * <ul class='seealso'> 1530 * <li class='jf'>{@link RestContext#REST_resourceResolver} 1531 * </ul> 1532 * 1533 * @param value 1534 * The new value for this setting. 1535 * <br>The default is {@link BasicRestResourceResolver}. 1536 * @return This object (for method chaining). 1537 */ 1538 public RestContextBuilder resourceResolver(RestResourceResolver value) { 1539 return set(REST_resourceResolver, value); 1540 } 1541 1542 /** 1543 * Configuration property: Response handlers. 1544 * 1545 * <p> 1546 * Specifies a list of {@link ResponseHandler} classes that know how to convert POJOs returned by REST methods or 1547 * set via {@link RestResponse#setOutput(Object)} into appropriate HTTP responses. 1548 * 1549 * <ul class='seealso'> 1550 * <li class='jf'>{@link RestContext#REST_responseHandlers} 1551 * </ul> 1552 * 1553 * @param values The values to add to this setting. 1554 * @return This object (for method chaining). 1555 */ 1556 public RestContextBuilder responseHandlers(Class<?>...values) { 1557 return addTo(REST_responseHandlers, values); 1558 } 1559 1560 /** 1561 * Configuration property: Response handlers. 1562 * 1563 * <p> 1564 * Same as {@link #responseHandlers(Class...)} except input is pre-constructed instances. 1565 * 1566 * <ul class='seealso'> 1567 * <li class='jf'>{@link RestContext#REST_responseHandlers} 1568 * </ul> 1569 * 1570 * @param values The values to add to this setting. 1571 * @return This object (for method chaining). 1572 */ 1573 public RestContextBuilder responseHandlers(ResponseHandler...values) { 1574 return addTo(REST_responseHandlers, values); 1575 } 1576 1577 /** 1578 * Configuration property: Declared roles. 1579 * 1580 * <p> 1581 * A comma-delimited list of all possible user roles. 1582 * 1583 * <p> 1584 * Used in conjunction with {@link RestContextBuilder#roleGuard(String)} is used with patterns. 1585 * 1586 * <h5 class='section'>Example:</h5> 1587 * <p class='bcode w800'> 1588 * <ja>@RestResource</ja>( 1589 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 1590 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1591 * ) 1592 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { 1593 * ... 1594 * } 1595 * </p> 1596 * 1597 * <ul class='seealso'> 1598 * <li class='jf'>{@link RestContext#REST_rolesDeclared} 1599 * </ul> 1600 * @param values The values to add to this setting. 1601 * @return This object (for method chaining). 1602 */ 1603 public RestContextBuilder rolesDeclared(String...values) { 1604 return addTo(REST_rolesDeclared, values); 1605 } 1606 1607 /** 1608 * Configuration property: Role guard. 1609 * 1610 * <p> 1611 * An expression defining if a user with the specified roles are allowed to access methods on this class. 1612 * 1613 * <h5 class='section'>Example:</h5> 1614 * <p class='bcode w800'> 1615 * <ja>@RestResource</ja>( 1616 * path=<js>"/foo"</js>, 1617 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1618 * ) 1619 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { 1620 * ... 1621 * } 1622 * </p> 1623 * 1624 * <ul class='notes'> 1625 * <li> 1626 * Supports any of the following expression constructs: 1627 * <ul> 1628 * <li><js>"foo"</js> - Single arguments. 1629 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 1630 * <li><js>"foo | bar | bqz"</js> - Multiple OR'ed arguments, pipe syntax. 1631 * <li><js>"foo || bar || bqz"</js> - Multiple OR'ed arguments, Java-OR syntax. 1632 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 1633 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 1634 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 1635 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 1636 * </ul> 1637 * <li> 1638 * AND operations take precedence over OR operations (as expected). 1639 * <li> 1640 * Whitespace is ignored. 1641 * <li> 1642 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 1643 * <li> 1644 * If patterns are used, you must specify the list of declared roles using {@link RestResource#rolesDeclared()} or {@link RestContext#REST_rolesDeclared}. 1645 * <li> 1646 * Supports {@doc DefaultRestSvlVariables} 1647 * (e.g. <js>"$L{my.localized.variable}"</js>). 1648 * </ul> 1649 * 1650 * @param value The values to add to this setting. 1651 * @return This object (for method chaining). 1652 */ 1653 public RestContextBuilder roleGuard(String value) { 1654 return addTo(REST_roleGuard, value); 1655 } 1656 1657 /** 1658 * Configuration property: Serializer listener. 1659 * 1660 * <p> 1661 * Specifies the serializer listener class to use for listening to non-fatal serialization errors. 1662 * 1663 * <ul class='seealso'> 1664 * <li class='jf'>{@link Serializer#SERIALIZER_listener} 1665 * </ul> 1666 * 1667 * @param value The new value for this setting. 1668 * @return This object (for method chaining). 1669 */ 1670 public RestContextBuilder serializerListener(Class<? extends SerializerListener> value) { 1671 if (value != SerializerListener.Null.class) 1672 set(SERIALIZER_listener, value); 1673 return this; 1674 } 1675 1676 /** 1677 * Configuration property: Serializers. 1678 * 1679 * <p> 1680 * Adds class-level serializers to this resource. 1681 * 1682 * <ul class='seealso'> 1683 * <li class='jf'>{@link RestContext#REST_serializers} 1684 * </ul> 1685 * 1686 * @param values The values to add to this setting. 1687 * @return This object (for method chaining). 1688 */ 1689 public RestContextBuilder serializers(Class<?>...values) { 1690 return addTo(REST_serializers, values); 1691 } 1692 1693 /** 1694 * Configuration property: Serializers. 1695 * 1696 * <p> 1697 * Same as {@link #serializers(Class[])} but replaces any existing values. 1698 * 1699 * <ul class='seealso'> 1700 * <li class='jf'>{@link RestContext#REST_serializers} 1701 * </ul> 1702 * 1703 * @param values The values to set on this setting. 1704 * @return This object (for method chaining). 1705 */ 1706 public RestContextBuilder serializersReplace(Class<?>...values) { 1707 return set(REST_serializers, values); 1708 } 1709 1710 /** 1711 * Configuration property: Serializers. 1712 * 1713 * <p> 1714 * Same as {@link #serializers(Class...)} except input is pre-constructed instances. 1715 * 1716 * <p> 1717 * Serializer instances are considered set-in-stone and do NOT inherit properties and transforms defined on the 1718 * resource class or method. 1719 * 1720 * <ul class='seealso'> 1721 * <li class='jf'>{@link RestContext#REST_serializers} 1722 * </ul> 1723 * 1724 * @param values The values to add to this setting. 1725 * @return This object (for method chaining). 1726 */ 1727 public RestContextBuilder serializers(Object...values) { 1728 return addTo(REST_serializers, values); 1729 } 1730 1731 /** 1732 * Configuration property: Serializers. 1733 * 1734 * <p> 1735 * Same as {@link #serializers(Class...)} except allows you to overwrite the previous value. 1736 * 1737 * <ul class='seealso'> 1738 * <li class='jf'>{@link RestContext#REST_serializers} 1739 * </ul> 1740 * 1741 * @param values The values to add to this setting. 1742 * @return This object (for method chaining). 1743 */ 1744 public RestContextBuilder serializersReplace(Object...values) { 1745 return set(REST_serializers, values); 1746 } 1747 1748 /** 1749 * Configuration property: Static file response headers. 1750 * 1751 * <p> 1752 * Used to customize the headers on responses returned for statically-served files. 1753 * 1754 * <ul class='seealso'> 1755 * <li class='jf'>{@link RestContext#REST_staticFileResponseHeaders} 1756 * </ul> 1757 * 1758 * @param headers 1759 * The headers to add to this list. 1760 * <br>The default is <code>{<js>'Cache-Control'</js>: <js>'max-age=86400, public</js>}</code>. 1761 * @return This object (for method chaining). 1762 */ 1763 public RestContextBuilder staticFileResponseHeaders(Map<String,String> headers) { 1764 return addTo(REST_staticFileResponseHeaders, headers); 1765 } 1766 1767 /** 1768 * Configuration property: Static file response headers. 1769 * 1770 * <p> 1771 * Same as {@link #staticFileResponseHeaders(Map)} but replaces any previous values. 1772 * 1773 * <ul class='seealso'> 1774 * <li class='jf'>{@link RestContext#REST_staticFileResponseHeaders} 1775 * </ul> 1776 * 1777 * @param headers 1778 * The headers to set on this list. 1779 * <br>The default is <code>{<js>'Cache-Control'</js>: <js>'max-age=86400, public</js>}</code>. 1780 * @return This object (for method chaining). 1781 */ 1782 public RestContextBuilder staticFileResponseHeadersReplace(Map<String,String> headers) { 1783 return set(REST_staticFileResponseHeaders, headers); 1784 } 1785 1786 /** 1787 * Configuration property: Static file response headers. 1788 * 1789 * <p> 1790 * Same as {@link #staticFileResponseHeaders(Map)} with append=<jk>true</jk> except headers are strings 1791 * composed of key/value pairs. 1792 * 1793 * <ul class='seealso'> 1794 * <li class='jf'>{@link RestContext#REST_staticFileResponseHeaders} 1795 * </ul> 1796 * 1797 * @param headers The headers in the format <js>"Header-Name: header-value"</js>. 1798 * @return This object (for method chaining). 1799 * @throws RestServletException If malformed header is found. 1800 */ 1801 public RestContextBuilder staticFileResponseHeaders(String...headers) throws RestServletException { 1802 for (String header : headers) { 1803 String[] h = RestUtils.parseHeader(header); 1804 if (h == null) 1805 throw new RestServletException("Invalid static file response header specified: ''{0}''. Must be in the format: ''Header-Name: header-value''", header); 1806 staticFileResponseHeader(h[0], h[1]); 1807 } 1808 return this; 1809 } 1810 1811 /** 1812 * Configuration property: Static file response headers. 1813 * 1814 * <p> 1815 * Same as {@link #staticFileResponseHeaders(String...)} except header is broken into name/value pair. 1816 * 1817 * <ul class='seealso'> 1818 * <li class='jf'>{@link RestContext#REST_staticFileResponseHeaders} 1819 * </ul> 1820 * 1821 * @param name The HTTP header name. 1822 * @param value The HTTP header value. 1823 * @return This object (for method chaining). 1824 */ 1825 public RestContextBuilder staticFileResponseHeader(String name, String value) { 1826 return addTo(REST_staticFileResponseHeaders, name, value); 1827 } 1828 1829 /** 1830 * Configuration property: Static file mappings. 1831 * 1832 * <p> 1833 * Used to define paths and locations of statically-served files such as images or HTML documents. 1834 * 1835 * <ul class='seealso'> 1836 * <li class='jf'>{@link RestContext#REST_staticFiles} 1837 * </ul> 1838 * 1839 * @param values The values to append to this setting. 1840 * @return This object (for method chaining). 1841 */ 1842 public RestContextBuilder staticFiles(StaticFileMapping...values) { 1843 return addTo(REST_staticFiles, values); 1844 } 1845 1846 /** 1847 * Configuration property: Static file mappings. 1848 * 1849 * <p> 1850 * Same as {@link #staticFiles(StaticFileMapping...)} except input is in the form of a mapping string. 1851 * 1852 * <p> 1853 * Mapping string must be one of these formats: 1854 * <ul> 1855 * <li><js>"path:location"</js> (e.g. <js>"foodocs:docs/foo"</js>) 1856 * <li><js>"path:location:headers-json"</js> (e.g. <js>"foodocs:docs/foo:{'Cache-Control':'max-age=86400, public'}"</js>) 1857 * </ul> 1858 * 1859 * <ul class='seealso'> 1860 * <li class='jf'>{@link RestContext#REST_staticFiles} 1861 * </ul> 1862 * 1863 * @param mappingString The static file mapping string. 1864 * @throws ParseException If mapping string is malformed. 1865 * @return This object (for method chaining). 1866 */ 1867 public RestContextBuilder staticFiles(String mappingString) throws ParseException{ 1868 for (StaticFileMapping sfm : reverseIterable(StaticFileMapping.parse(resourceClass, mappingString))) 1869 staticFiles(sfm); 1870 return this; 1871 } 1872 1873 /** 1874 * Configuration property: Static file mappings. 1875 * 1876 * <p> 1877 * Same as {@link #staticFiles(String)} except overrides the base class for retrieving the resource. 1878 * 1879 * <p> 1880 * Mapping string must be one of these formats: 1881 * <ul> 1882 * <li><js>"path:location"</js> (e.g. <js>"foodocs:docs/foo"</js>) 1883 * <li><js>"path:location:headers-json"</js> (e.g. <js>"foodocs:docs/foo:{'Cache-Control':'max-age=86400, public'}"</js>) 1884 * </ul> 1885 * 1886 * <ul class='seealso'> 1887 * <li class='jf'>{@link RestContext#REST_staticFiles} 1888 * </ul> 1889 * 1890 * @param baseClass 1891 * Overrides the default class to use for retrieving the classpath resource. 1892 * <br>If <jk>null<jk>, uses the REST resource class. 1893 * @param mappingString The static file mapping string. 1894 * @return This object (for method chaining). 1895 * @throws ParseException If mapping string is malformed. 1896 */ 1897 public RestContextBuilder staticFiles(Class<?> baseClass, String mappingString) throws ParseException { 1898 for (StaticFileMapping sfm : reverseIterable(StaticFileMapping.parse(baseClass, mappingString))) 1899 staticFiles(sfm); 1900 return this; 1901 } 1902 1903 /** 1904 * Configuration property: Static file mappings. 1905 * 1906 * <p> 1907 * Same as {@link #staticFiles(String)} except path and location are already split values. 1908 * 1909 * <ul class='seealso'> 1910 * <li class='jf'>{@link RestContext#REST_staticFiles} 1911 * </ul> 1912 * 1913 * @param path 1914 * The mapped URI path. 1915 * <br>Leading and trailing slashes are trimmed. 1916 * @param location 1917 * The location relative to the resource class. 1918 * <br>Leading and trailing slashes are trimmed. 1919 * @return This object (for method chaining). 1920 */ 1921 public RestContextBuilder staticFiles(String path, String location) { 1922 return staticFiles(new StaticFileMapping(resourceClass, path, location, null)); 1923 } 1924 1925 /** 1926 * Configuration property: Static file mappings. 1927 * 1928 * <p> 1929 * Same as {@link #staticFiles(String,String)} except overrides the base class for retrieving the resource. 1930 * 1931 * <ul class='seealso'> 1932 * <li class='jf'>{@link RestContext#REST_staticFiles} 1933 * </ul> 1934 * 1935 * @param baseClass 1936 * Overrides the default class to use for retrieving the classpath resource. 1937 * <br>If <jk>null<jk>, uses the REST resource class. 1938 * @param path 1939 * The mapped URI path. 1940 * <br>Leading and trailing slashes are trimmed. 1941 * @param location 1942 * The location relative to the resource class. 1943 * <br>Leading and trailing slashes are trimmed. 1944 * @return This object (for method chaining). 1945 */ 1946 public RestContextBuilder staticFiles(Class<?> baseClass, String path, String location) { 1947 return staticFiles(new StaticFileMapping(baseClass, path, location, null)); 1948 } 1949 1950 /** 1951 * Configuration property: Supported accept media types. 1952 * 1953 * <p> 1954 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 1955 * 1956 * <ul class='seealso'> 1957 * <li class='jf'>{@link RestContext#REST_produces} 1958 * </ul> 1959 * 1960 * @param values The values to add to this setting. 1961 * @return This object (for method chaining). 1962 */ 1963 public RestContextBuilder produces(String...values) { 1964 return addTo(REST_produces, values); 1965 } 1966 1967 /** 1968 * Configuration property: Supported accept media types. 1969 * 1970 * <p> 1971 * Same as {@link #produces(String...)} but replaces any previous values. 1972 * 1973 * <ul class='seealso'> 1974 * <li class='jf'>{@link RestContext#REST_produces} 1975 * </ul> 1976 * 1977 * @param values The values to set on this setting. 1978 * @return This object (for method chaining). 1979 */ 1980 public RestContextBuilder producesReplace(String...values) { 1981 return set(REST_produces, values); 1982 } 1983 1984 /** 1985 * Configuration property: Supported accept media types. 1986 * 1987 * <p> 1988 * Same as {@link #produces(String...)} except input is {@link MediaType} instances. 1989 * 1990 * <ul class='seealso'> 1991 * <li class='jf'>{@link RestContext#REST_produces} 1992 * </ul> 1993 * 1994 * @param values The values to add to this setting. 1995 * @return This object (for method chaining). 1996 */ 1997 public RestContextBuilder produces(MediaType...values) { 1998 return addTo(REST_produces, values); 1999 } 2000 2001 /** 2002 * Configuration property: Supported accept media types. 2003 * 2004 * <p> 2005 * Same as {@link #produces(MediaType...)} but replaces any previous values. 2006 * 2007 * <ul class='seealso'> 2008 * <li class='jf'>{@link RestContext#REST_produces} 2009 * </ul> 2010 * 2011 * @param values The values to set on this setting. 2012 * @return This object (for method chaining). 2013 */ 2014 public RestContextBuilder producesReplace(MediaType...values) { 2015 return set(REST_produces, values); 2016 } 2017 2018 /** 2019 * Configuration property: Supported content media types. 2020 * 2021 * <p> 2022 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 2023 * 2024 * <ul class='seealso'> 2025 * <li class='jf'>{@link RestContext#REST_consumes} 2026 * </ul> 2027 * 2028 * @param values The values to add to this setting. 2029 * @return This object (for method chaining). 2030 */ 2031 public RestContextBuilder consumes(String...values) { 2032 return addTo(REST_consumes, values); 2033 } 2034 2035 /** 2036 * Configuration property: Supported content media types. 2037 * 2038 * <p> 2039 * Same as {@link #consumes(String...)} but replaces any existing values. 2040 * 2041 * <ul class='seealso'> 2042 * <li class='jf'>{@link RestContext#REST_consumes} 2043 * </ul> 2044 * 2045 * @param values The values to set on this setting. 2046 * @return This object (for method chaining). 2047 */ 2048 public RestContextBuilder consumesReplace(String...values) { 2049 return set(REST_consumes, values); 2050 } 2051 2052 /** 2053 * Configuration property: Supported content media types. 2054 * 2055 * <p> 2056 * Same as {@link #consumes(String...)} except input is {@link MediaType} instances. 2057 * 2058 * <ul class='seealso'> 2059 * <li class='jf'>{@link RestContext#REST_consumes} 2060 * </ul> 2061 * 2062 * @param values The values to add to this setting. 2063 * @return This object (for method chaining). 2064 */ 2065 public RestContextBuilder consumes(MediaType...values) { 2066 return addTo(REST_consumes, values); 2067 } 2068 2069 /** 2070 * Configuration property: Supported content media types. 2071 * 2072 * <p> 2073 * Same as {@link #consumes(MediaType...)} except replaces any existing values. 2074 * 2075 * <ul class='seealso'> 2076 * <li class='jf'>{@link RestContext#REST_consumes} 2077 * </ul> 2078 * 2079 * @param values The values to set on this setting. 2080 * @return This object (for method chaining). 2081 */ 2082 public RestContextBuilder consumesReplace(MediaType...values) { 2083 return set(REST_consumes, values); 2084 } 2085 2086 /** 2087 * Configuration property: Properties. 2088 * 2089 * <p> 2090 * Shortcut to add properties to the bean contexts of all serializers and parsers on all methods in the class. 2091 * 2092 * <p> 2093 * Any of the properties defined on {@link RestContext} or any of the serializers and parsers can be specified. 2094 * 2095 * <p> 2096 * Property values will be converted to the appropriate type. 2097 * 2098 * <ul class='seealso'> 2099 * <li class='jm'>{@link RestContext#REST_properties} 2100 * </ul> 2101 * 2102 * @param values The values to set on this setting. 2103 * @return This object (for method chaining). 2104 */ 2105 public RestContextBuilder properties(Map<String,Object> values) { 2106 return addTo(REST_properties, values); 2107 } 2108 2109 /** 2110 * Configuration property: Properties. 2111 * 2112 * <p> 2113 * Shortcut to add properties to the bean contexts of all serializers and parsers on all methods in the class. 2114 * 2115 * <p> 2116 * Any of the properties defined on {@link RestContext} or any of the serializers and parsers can be specified. 2117 * 2118 * <p> 2119 * Property values will be converted to the appropriate type. 2120 * 2121 * <ul class='seealso'> 2122 * <li class='jm'>{@link RestContext#REST_properties} 2123 * </ul> 2124 * 2125 * @param name The key to add to the properties. 2126 * @param value The value to add to the properties. 2127 * @return This object (for method chaining). 2128 */ 2129 public RestContextBuilder property(String name, Object value) { 2130 return addTo(REST_properties, name, value); 2131 } 2132 2133 /** 2134 * Configuration property: Resource authority path. 2135 * 2136 * <p> 2137 * Overrides the authority path value for this resource and any child resources. 2138 * 2139 * <p> 2140 * This setting is useful if you want to resolve relative URIs to absolute paths and want to explicitly specify the hostname/port. 2141 * 2142 * <ul class='seealso'> 2143 * <li class='jf'>{@link RestContext#REST_uriAuthority} 2144 * </ul> 2145 * 2146 * @param value The new value for this setting. 2147 * @return This object (for method chaining). 2148 */ 2149 public RestContextBuilder uriAuthority(String value) { 2150 if (! value.isEmpty()) 2151 set(REST_uriAuthority, value); 2152 return this; 2153 } 2154 2155 /** 2156 * Configuration property: Resource context path. 2157 * 2158 * <p> 2159 * Overrides the context path value for this resource and any child resources. 2160 * 2161 * <p> 2162 * This setting is useful if you want to use <js>"context:/child/path"</js> URLs in child resource POJOs but 2163 * the context path is not actually specified on the servlet container. 2164 * 2165 * <ul class='seealso'> 2166 * <li class='jf'>{@link RestContext#REST_uriContext} 2167 * </ul> 2168 * 2169 * @param value The new value for this setting. 2170 * @return This object (for method chaining). 2171 */ 2172 public RestContextBuilder uriContext(String value) { 2173 if (! value.isEmpty()) 2174 set(REST_uriContext, value); 2175 return this; 2176 } 2177 2178 /** 2179 * Configuration property: URI resolution relativity. 2180 * 2181 * <p> 2182 * Specifies how relative URIs should be interpreted by serializers. 2183 * 2184 * <p> 2185 * See {@link UriResolution} for possible values. 2186 * 2187 * <ul class='seealso'> 2188 * <li class='jf'>{@link RestContext#REST_uriRelativity} 2189 * </ul> 2190 * 2191 * @param value The new value for this setting. 2192 * @return This object (for method chaining). 2193 */ 2194 public RestContextBuilder uriRelativity(String value) { 2195 if (! value.isEmpty()) 2196 set(REST_uriRelativity, value); 2197 return this; 2198 } 2199 2200 /** 2201 * Configuration property: URI resolution. 2202 * 2203 * <p> 2204 * Specifies how relative URIs should be interpreted by serializers. 2205 * 2206 * <p> 2207 * See {@link UriResolution} for possible values. 2208 * 2209 * <ul class='seealso'> 2210 * <li class='jf'>{@link RestContext#REST_uriResolution} 2211 * </ul> 2212 * 2213 * @param value The new value for this setting. 2214 * @return This object (for method chaining). 2215 */ 2216 public RestContextBuilder uriResolution(String value) { 2217 if (! value.isEmpty()) 2218 set(REST_uriResolution, value); 2219 return this; 2220 } 2221 2222 /** 2223 * Configuration property: Use classpath resource caching. 2224 * 2225 * <p> 2226 * When enabled, resources retrieved via {@link RestContext#getClasspathResource(String, Locale)} (and related 2227 * methods) will be cached in memory to speed subsequent lookups. 2228 * 2229 * <ul class='seealso'> 2230 * <li class='jf'>{@link RestContext#REST_useClasspathResourceCaching} 2231 * </ul> 2232 * 2233 * @param value 2234 * The new value for this setting. 2235 * <br>The default is <jk>true</jk>. 2236 * @return This object (for method chaining). 2237 */ 2238 public RestContextBuilder useClasspathResourceCaching(boolean value) { 2239 return set(REST_useClasspathResourceCaching, value); 2240 } 2241 2242 /** 2243 * Configuration property: Use stack trace hashes. 2244 * 2245 * <p> 2246 * When enabled, the number of times an exception has occurred will be determined based on stack trace hashsums, 2247 * made available through the {@link RestException#getOccurrence()} method. 2248 * 2249 * <ul class='seealso'> 2250 * <li class='jf'>{@link RestContext#REST_useStackTraceHashes} 2251 * </ul> 2252 * 2253 * @param value 2254 * The new value for this setting. 2255 * <br>The default is <jk>true</jk>. 2256 * @return This object (for method chaining). 2257 * @deprecated Use {@link #callLoggerConfig(RestCallLoggerConfig)} 2258 */ 2259 @Deprecated 2260 public RestContextBuilder useStackTraceHashes(boolean value) { 2261 return set(REST_useStackTraceHashes, value); 2262 } 2263 2264 /** 2265 * Configuration property: HTML Widgets. 2266 * 2267 * <p> 2268 * Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly 2269 * generate arbitrary replacement text. 2270 * 2271 * <ul class='seealso'> 2272 * <li class='jf'>{@link RestContext#REST_widgets} 2273 * </ul> 2274 * 2275 * @param values The values to add to this setting. 2276 * @return This object (for method chaining). 2277 * 2278 * @deprecated Use {@link HtmlDocSerializerBuilder#widgets(Class[])} 2279 */ 2280 @SuppressWarnings("unchecked") 2281 @Deprecated 2282 public RestContextBuilder widgets(Class<? extends Widget>...values) { 2283 return addTo(REST_widgets, values); 2284 } 2285 2286 /** 2287 * Configuration property: HTML Widgets. 2288 * 2289 * <p> 2290 * Same as {@link #widgets(Class...)} but replaces any previous values. 2291 * 2292 * <ul class='seealso'> 2293 * <li class='jf'>{@link RestContext#REST_widgets} 2294 * </ul> 2295 * 2296 * @param values The values to set on this setting. 2297 * @return This object (for method chaining). 2298 * 2299 * @deprecated Use {@link HtmlDocSerializerBuilder#widgetsReplace(Class[])} 2300 */ 2301 @SuppressWarnings("unchecked") 2302 @Deprecated 2303 public RestContextBuilder widgetsReplace(Class<? extends Widget>...values) { 2304 return set(REST_widgets, values); 2305 } 2306 2307 /** 2308 * Configuration property: HTML Widgets. 2309 * 2310 * <p> 2311 * Same as {@link #widgets(Class...)} except input is pre-constructed instances. 2312 * 2313 * <ul class='seealso'> 2314 * <li class='jf'>{@link RestContext#REST_widgets} 2315 * </ul> 2316 * 2317 * @param values The values to add to this setting. 2318 * @return This object (for method chaining). 2319 * 2320 * @deprecated Use {@link HtmlDocSerializerBuilder#widgets(HtmlWidget[])} 2321 */ 2322 @Deprecated 2323 public RestContextBuilder widgets(Widget...values) { 2324 return addTo(REST_widgets, values); 2325 } 2326 2327 /** 2328 * Configuration property: HTML Widgets. 2329 * 2330 * <p> 2331 * Same as {@link #widgets(Widget...)} except allows you to overwrite the previous value. 2332 * 2333 * <ul class='seealso'> 2334 * <li class='jf'>{@link RestContext#REST_widgets} 2335 * </ul> 2336 * 2337 * @param values The values to add to this setting. 2338 * @return This object (for method chaining). 2339 * 2340 * @deprecated Use {@link HtmlDocSerializerBuilder#widgetsReplace(HtmlWidget[])} 2341 */ 2342 @Deprecated 2343 public RestContextBuilder widgetsReplace(Widget...values) { 2344 return set(REST_widgets, values); 2345 } 2346 2347 @Override /* BeanContextBuilder */ 2348 public RestContextBuilder beanClassVisibility(Visibility value) { 2349 super.beanClassVisibility(value); 2350 return this; 2351 } 2352 2353 @Override /* BeanContextBuilder */ 2354 public RestContextBuilder beanConstructorVisibility(Visibility value) { 2355 super.beanConstructorVisibility(value); 2356 return this; 2357 } 2358 2359 @Override /* BeanContextBuilder */ 2360 public RestContextBuilder beanDictionary(Class<?>...values) { 2361 super.beanDictionary(values); 2362 return this; 2363 } 2364 2365 @Override /* BeanContextBuilder */ 2366 public RestContextBuilder beanDictionary(Object...values) { 2367 super.beanDictionary(values); 2368 return this; 2369 } 2370 2371 @Override /* BeanContextBuilder */ 2372 public RestContextBuilder beanDictionaryReplace(Class<?>...values) { 2373 super.beanDictionaryReplace(values); 2374 return this; 2375 } 2376 2377 @Override /* BeanContextBuilder */ 2378 public RestContextBuilder beanDictionaryReplace(Object...values) { 2379 super.beanDictionaryReplace(values); 2380 return this; 2381 } 2382 2383 @Override /* BeanContextBuilder */ 2384 public RestContextBuilder beanDictionaryRemove(Class<?>...values) { 2385 super.beanDictionaryRemove(values); 2386 return this; 2387 } 2388 2389 @Override /* BeanContextBuilder */ 2390 public RestContextBuilder beanDictionaryRemove(Object...values) { 2391 super.beanDictionaryRemove(values); 2392 return this; 2393 } 2394 2395 @Override /* BeanContextBuilder */ 2396 public RestContextBuilder beanFieldVisibility(Visibility value) { 2397 super.beanFieldVisibility(value); 2398 return this; 2399 } 2400 2401 @Override /* BeanContextBuilder */ 2402 public RestContextBuilder beanFilters(Class<?>...values) { 2403 super.beanFilters(values); 2404 return this; 2405 } 2406 2407 @Override /* BeanContextBuilder */ 2408 public RestContextBuilder beanFilters(Object...values) { 2409 super.beanFilters(values); 2410 return this; 2411 } 2412 2413 @Override /* BeanContextBuilder */ 2414 public RestContextBuilder beanFiltersReplace(Class<?>...values) { 2415 super.beanFiltersReplace(values); 2416 return this; 2417 } 2418 2419 @Override /* BeanContextBuilder */ 2420 public RestContextBuilder beanFiltersReplace(Object...values) { 2421 super.beanFiltersReplace(values); 2422 return this; 2423 } 2424 2425 @Override /* BeanContextBuilder */ 2426 public RestContextBuilder beanFiltersRemove(Class<?>...values) { 2427 super.beanFiltersRemove(values); 2428 return this; 2429 } 2430 2431 @Override /* BeanContextBuilder */ 2432 public RestContextBuilder beanFiltersRemove(Object...values) { 2433 super.beanFiltersRemove(values); 2434 return this; 2435 } 2436 2437 @Override /* BeanContextBuilder */ 2438 public RestContextBuilder beanMapPutReturnsOldValue(boolean value) { 2439 super.beanMapPutReturnsOldValue(value); 2440 return this; 2441 } 2442 2443 @Override /* BeanContextBuilder */ 2444 public RestContextBuilder beanMapPutReturnsOldValue() { 2445 super.beanMapPutReturnsOldValue(); 2446 return this; 2447 } 2448 2449 @Override /* BeanContextBuilder */ 2450 public RestContextBuilder beanMethodVisibility(Visibility value) { 2451 super.beanMethodVisibility(value); 2452 return this; 2453 } 2454 2455 @Override /* BeanContextBuilder */ 2456 public RestContextBuilder beansRequireDefaultConstructor(boolean value) { 2457 super.beansRequireDefaultConstructor(value); 2458 return this; 2459 } 2460 2461 @Override /* BeanContextBuilder */ 2462 public RestContextBuilder beansRequireDefaultConstructor() { 2463 super.beansRequireDefaultConstructor(); 2464 return this; 2465 } 2466 2467 @Override /* BeanContextBuilder */ 2468 public RestContextBuilder beansRequireSerializable(boolean value) { 2469 super.beansRequireSerializable(value); 2470 return this; 2471 } 2472 2473 @Override /* BeanContextBuilder */ 2474 public RestContextBuilder beansRequireSerializable() { 2475 super.beansRequireSerializable(); 2476 return this; 2477 } 2478 2479 @Override /* BeanContextBuilder */ 2480 public RestContextBuilder beansRequireSettersForGetters(boolean value) { 2481 super.beansRequireSettersForGetters(value); 2482 return this; 2483 } 2484 2485 @Override /* BeanContextBuilder */ 2486 public RestContextBuilder beansRequireSettersForGetters() { 2487 super.beansRequireSettersForGetters(); 2488 return this; 2489 } 2490 2491 @Override /* BeanContextBuilder */ 2492 public RestContextBuilder beansRequireSomeProperties(boolean value) { 2493 super.beansRequireSomeProperties(value); 2494 return this; 2495 } 2496 2497 @Override /* BeanContextBuilder */ 2498 public RestContextBuilder beanTypePropertyName(String value) { 2499 super.beanTypePropertyName(value); 2500 return this; 2501 } 2502 2503 @Override /* BeanContextBuilder */ 2504 public RestContextBuilder debug() { 2505 debug(Enablement.TRUE); 2506 super.debug(); 2507 return this; 2508 } 2509 2510 @Override /* BeanContextBuilder */ 2511 public <T> RestContextBuilder example(Class<T> c, T o) { 2512 super.example(c, o); 2513 return this; 2514 } 2515 2516 @Override /* BeanContextBuilder */ 2517 public <T> RestContextBuilder exampleJson(Class<T> c, String value) { 2518 super.exampleJson(c, value); 2519 return this; 2520 } 2521 2522 @Override /* BeanContextBuilder */ 2523 public RestContextBuilder ignoreInvocationExceptionsOnGetters(boolean value) { 2524 super.ignoreInvocationExceptionsOnGetters(value); 2525 return this; 2526 } 2527 2528 @Override /* BeanContextBuilder */ 2529 public RestContextBuilder ignoreInvocationExceptionsOnGetters() { 2530 super.ignoreInvocationExceptionsOnGetters(); 2531 return this; 2532 } 2533 2534 @Override /* BeanContextBuilder */ 2535 public RestContextBuilder ignoreInvocationExceptionsOnSetters(boolean value) { 2536 super.ignoreInvocationExceptionsOnSetters(value); 2537 return this; 2538 } 2539 2540 @Override /* BeanContextBuilder */ 2541 public RestContextBuilder ignoreInvocationExceptionsOnSetters() { 2542 super.ignoreInvocationExceptionsOnSetters(); 2543 return this; 2544 } 2545 2546 @Override /* BeanContextBuilder */ 2547 public RestContextBuilder ignorePropertiesWithoutSetters(boolean value) { 2548 super.ignorePropertiesWithoutSetters(value); 2549 return this; 2550 } 2551 2552 @Override /* BeanContextBuilder */ 2553 public RestContextBuilder ignoreUnknownBeanProperties(boolean value) { 2554 super.ignoreUnknownBeanProperties(value); 2555 return this; 2556 } 2557 2558 @Override /* BeanContextBuilder */ 2559 public RestContextBuilder ignoreUnknownBeanProperties() { 2560 super.ignoreUnknownBeanProperties(); 2561 return this; 2562 } 2563 2564 @Override /* BeanContextBuilder */ 2565 public RestContextBuilder ignoreUnknownNullBeanProperties(boolean value) { 2566 super.ignoreUnknownNullBeanProperties(value); 2567 return this; 2568 } 2569 2570 @Override /* BeanContextBuilder */ 2571 public RestContextBuilder implClass(Class<?> interfaceClass, Class<?> implClass) { 2572 super.implClass(interfaceClass, implClass); 2573 return this; 2574 } 2575 2576 @Override /* BeanContextBuilder */ 2577 public RestContextBuilder implClasses(Map<String,Class<?>> values) { 2578 super.implClasses(values); 2579 return this; 2580 } 2581 2582 @Override /* BeanContextBuilder */ 2583 public RestContextBuilder locale(Locale value) { 2584 super.locale(value); 2585 return this; 2586 } 2587 2588 @Override /* BeanContextBuilder */ 2589 public RestContextBuilder mediaType(MediaType value) { 2590 super.mediaType(value); 2591 return this; 2592 } 2593 2594 @Override /* BeanContextBuilder */ 2595 public RestContextBuilder notBeanClasses(Class<?>...values) { 2596 super.notBeanClasses(values); 2597 return this; 2598 } 2599 2600 @Override /* BeanContextBuilder */ 2601 public RestContextBuilder notBeanClasses(Object...values) { 2602 super.notBeanClasses(values); 2603 return this; 2604 } 2605 2606 @Override /* BeanContextBuilder */ 2607 public RestContextBuilder notBeanClassesReplace(Class<?>...values) { 2608 super.notBeanClassesReplace(values); 2609 return this; 2610 } 2611 2612 @Override /* BeanContextBuilder */ 2613 public RestContextBuilder notBeanClassesReplace(Object...values) { 2614 super.notBeanClassesReplace(values); 2615 return this; 2616 } 2617 2618 @Override /* BeanContextBuilder */ 2619 public RestContextBuilder notBeanClassesRemove(Class<?>...values) { 2620 super.notBeanClassesRemove(values); 2621 return this; 2622 } 2623 2624 @Override /* BeanContextBuilder */ 2625 public RestContextBuilder notBeanClassesRemove(Object...values) { 2626 super.notBeanClassesRemove(values); 2627 return this; 2628 } 2629 2630 @Override /* BeanContextBuilder */ 2631 public RestContextBuilder notBeanPackages(Object...values) { 2632 super.notBeanPackages(values); 2633 return this; 2634 } 2635 2636 @Override /* BeanContextBuilder */ 2637 public RestContextBuilder notBeanPackages(String...values) { 2638 super.notBeanPackages(values); 2639 return this; 2640 } 2641 2642 @Override /* BeanContextBuilder */ 2643 public RestContextBuilder notBeanPackagesReplace(String...values) { 2644 super.notBeanPackagesReplace(values); 2645 return this; 2646 } 2647 2648 @Override /* BeanContextBuilder */ 2649 public RestContextBuilder notBeanPackagesReplace(Object...values) { 2650 super.notBeanPackagesReplace(values); 2651 return this; 2652 } 2653 2654 @Override /* BeanContextBuilder */ 2655 public RestContextBuilder notBeanPackagesRemove(String...values) { 2656 super.notBeanPackagesRemove(values); 2657 return this; 2658 } 2659 2660 @Override /* BeanContextBuilder */ 2661 public RestContextBuilder notBeanPackagesRemove(Object...values) { 2662 super.notBeanPackagesRemove(values); 2663 return this; 2664 } 2665 2666 @Override /* BeanContextBuilder */ 2667 public RestContextBuilder pojoSwaps(Class<?>...values) { 2668 super.pojoSwaps(values); 2669 return this; 2670 } 2671 2672 @Override /* BeanContextBuilder */ 2673 public RestContextBuilder pojoSwaps(Object...values) { 2674 super.pojoSwaps(values); 2675 return this; 2676 } 2677 2678 @Override /* BeanContextBuilder */ 2679 public RestContextBuilder pojoSwapsReplace(Class<?>...values) { 2680 super.pojoSwapsReplace(values); 2681 return this; 2682 } 2683 2684 @Override /* BeanContextBuilder */ 2685 public RestContextBuilder pojoSwapsReplace(Object...values) { 2686 super.pojoSwapsReplace(values); 2687 return this; 2688 } 2689 2690 @Override /* BeanContextBuilder */ 2691 public RestContextBuilder pojoSwapsRemove(Class<?>...values) { 2692 super.pojoSwapsRemove(values); 2693 return this; 2694 } 2695 2696 @Override /* BeanContextBuilder */ 2697 public RestContextBuilder pojoSwapsRemove(Object...values) { 2698 super.pojoSwapsRemove(values); 2699 return this; 2700 } 2701 2702 @Override /* BeanContextBuilder */ 2703 public RestContextBuilder sortProperties(boolean value) { 2704 super.sortProperties(value); 2705 return this; 2706 } 2707 2708 @Override /* BeanContextBuilder */ 2709 public RestContextBuilder sortProperties() { 2710 super.sortProperties(); 2711 return this; 2712 } 2713 2714 @Override /* BeanContextBuilder */ 2715 public RestContextBuilder timeZone(TimeZone value) { 2716 super.timeZone(value); 2717 return this; 2718 } 2719 2720 @Override /* BeanContextBuilder */ 2721 public RestContextBuilder useEnumNames(boolean value) { 2722 super.useEnumNames(value); 2723 return this; 2724 } 2725 2726 @Override /* BeanContextBuilder */ 2727 public RestContextBuilder useEnumNames() { 2728 super.useEnumNames(); 2729 return this; 2730 } 2731 2732 @Override /* BeanContextBuilder */ 2733 public RestContextBuilder useInterfaceProxies(boolean value) { 2734 super.useInterfaceProxies(value); 2735 return this; 2736 } 2737 2738 @Override /* BeanContextBuilder */ 2739 public RestContextBuilder useJavaBeanIntrospector(boolean value) { 2740 super.useJavaBeanIntrospector(value); 2741 return this; 2742 } 2743 2744 @Override /* BeanContextBuilder */ 2745 public RestContextBuilder useJavaBeanIntrospector() { 2746 super.useJavaBeanIntrospector(); 2747 return this; 2748 } 2749 2750 @Override /* ContextBuilder */ 2751 public RestContextBuilder set(String name, Object value) { 2752 super.set(name, value); 2753 this.properties.put(name, value); 2754 addTo(REST_properties, name, value); 2755 return this; 2756 } 2757 2758 @Override /* ContextBuilder */ 2759 public RestContextBuilder set(Map<String,Object> properties) { 2760 super.set(properties); 2761 this.properties.clear(); 2762 this.properties.putAll(properties); 2763 addTo(REST_properties, properties); 2764 return this; 2765 } 2766 2767 @Override /* ContextBuilder */ 2768 public RestContextBuilder add(Map<String,Object> properties) { 2769 super.add(properties); 2770 return this; 2771 } 2772 2773 @Override /* ContextBuilder */ 2774 public RestContextBuilder addTo(String name, Object value) { 2775 super.addTo(name, value); 2776 return this; 2777 } 2778 2779 @Override /* ContextBuilder */ 2780 public RestContextBuilder addTo(String name, String key, Object value) { 2781 super.addTo(name, key, value); 2782 return this; 2783 } 2784 2785 @Override /* ContextBuilder */ 2786 public RestContextBuilder removeFrom(String name, Object value) { 2787 super.removeFrom(name, value); 2788 return this; 2789 } 2790 2791 @Override /* ContextBuilder */ 2792 public RestContextBuilder apply(PropertyStore copyFrom) { 2793 super.apply(copyFrom); 2794 return this; 2795 } 2796 2797 @Override /* ContextBuilder */ 2798 public RestContextBuilder applyAnnotations(AnnotationList al, VarResolverSession vrs) { 2799 super.applyAnnotations(al, vrs); 2800 return this; 2801 } 2802 2803 @Override /* ContextBuilder */ 2804 public RestContextBuilder applyAnnotations(Class<?> fromClass) { 2805 super.applyAnnotations(fromClass); 2806 return this; 2807 } 2808 2809 @Override /* ContextBuilder */ 2810 public RestContextBuilder applyAnnotations(java.lang.reflect.Method fromMethod) { 2811 super.applyAnnotations(fromMethod); 2812 return this; 2813 } 2814 2815 //---------------------------------------------------------------------------------------------------- 2816 // Methods inherited from ServletConfig 2817 //---------------------------------------------------------------------------------------------------- 2818 2819 @Override /* ServletConfig */ 2820 public String getInitParameter(String name) { 2821 return inner.getInitParameter(name); 2822 } 2823 2824 @Override /* ServletConfig */ 2825 public Enumeration<String> getInitParameterNames() { 2826 return inner.getInitParameterNames(); 2827 } 2828 2829 @Override /* ServletConfig */ 2830 public ServletContext getServletContext() { 2831 return inner.getServletContext(); 2832 } 2833 2834 @Override /* ServletConfig */ 2835 public String getServletName() { 2836 return inner.getServletName(); 2837 } 2838}