001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.rest.server; 018 019import org.apache.juneau.marshall.encoders.*; 020import org.apache.juneau.marshall.httppart.*; 021import org.apache.juneau.marshall.serializer.*; 022import org.apache.juneau.rest.server.arg.*; 023import org.apache.juneau.rest.server.converter.*; 024import org.apache.juneau.rest.server.guard.*; 025import org.apache.juneau.rest.server.openapi.*; 026import org.apache.juneau.rest.server.processor.*; 027import org.apache.juneau.rest.server.staticfile.*; 028import org.apache.juneau.rest.server.swagger.*; 029 030/** 031 * Public, fluent, self-typed configuration surface for programmatically configuring a {@code @Rest} resource, 032 * child resource, or mixin instead of (or in addition to) the {@link Rest @Rest} annotation. 033 * 034 * <p> 035 * This is the user-facing builder surface introduced for programmatic resource/mixin configuration (e.g. 036 * instantiating a configured resource bean in a Spring {@code @Bean} method). Builder-supplied values take 037 * <b>precedence</b> over {@link Rest @Rest} annotation values — they slot in as the highest-priority 038 * (rung 1) contributor of the runtime-override resolution chain documented on 039 * {@link RestContext#getPaths()}, generalized to every {@code @Rest} member. 040 * 041 * <p class='bjava'> 042 * <jc>// Configure a resource programmatically; builder values win over the class's @Rest annotation.</jc> 043 * MyRest <jv>r</jv> = MyRest.<jsm>builder</jsm>().path(<js>"/foo"</js>).allowedHeaderParams(<js>"foo"</js>).build(); 044 * </p> 045 * 046 * <h5 class='section'>Self type (CRTP):</h5> 047 * 048 * <p> 049 * The {@code SELF} type parameter is the concrete builder type, so every fluent setter returns the most-derived 050 * builder type and bespoke setters added by a builder subclass chain with true covariant returns. This mirrors 051 * the project-wide {@code SELF}/{@code self()} self-type convention. 052 * 053 * <h5 class='section'>See Also:</h5><ul> 054 * <li class='jc'>{@link AbstractRestBuilder} 055 * <li class='jc'>{@link org.apache.juneau.rest.server.servlet.RestServlet.Builder} 056 * <li class='jc'>{@link org.apache.juneau.rest.server.servlet.RestResource.Builder} 057 * <li class='jc'>{@link org.apache.juneau.rest.server.servlet.RestMixin.Builder} 058 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestAnnotatedClasses">@Rest-Annotated Class</a> 059 * </ul> 060 * 061 * @param <SELF> The concrete builder type (self type). 062 * @since 10.0.0 063 */ 064@SuppressWarnings({ 065 "java:S119", // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name. 066 "unchecked" // Generic varargs parameter; no heap pollution from this declaration. 067}) 068public interface RestBuilder<SELF extends RestBuilder<SELF>> { 069 070 //----------------------------------------------------------------------------------------------------------------- 071 // Identity & mounting 072 //----------------------------------------------------------------------------------------------------------------- 073 074 /** 075 * Specifies the {@link Rest#path() path} for this resource. 076 * 077 * @param value The new value for this property. 078 * @return This object. 079 */ 080 SELF path(String value); 081 082 /** 083 * Specifies the {@link Rest#paths() top-level mount paths} for this resource. 084 * 085 * @param value The new value for this property. 086 * @return This object. 087 */ 088 SELF paths(String... value); 089 090 /** 091 * Specifies the {@link Rest#children() child resources} for this resource. 092 * 093 * @param value The new value for this property. 094 * @return This object. 095 */ 096 SELF children(Class<?>... value); 097 098 /** 099 * Specifies the {@link Rest#mixins() mixins} for this resource. 100 * 101 * @param value The new value for this property. 102 * @return This object. 103 */ 104 SELF mixins(Class<?>... value); 105 106 /** 107 * Specifies the {@link Rest#mixinDefs() mixinDefs} (rich, host-overriding mixin definitions) for this resource. 108 * 109 * @param value The new value for this property. 110 * @return This object. 111 */ 112 SELF mixinDefs(Mixin... value); 113 114 /** 115 * Specifies the {@link Rest#uriAuthority() uriAuthority} for this resource. 116 * 117 * @param value The new value for this property. 118 * @return This object. 119 */ 120 SELF uriAuthority(String value); 121 122 /** 123 * Specifies the {@link Rest#uriContext() uriContext} for this resource. 124 * 125 * @param value The new value for this property. 126 * @return This object. 127 */ 128 SELF uriContext(String value); 129 130 /** 131 * Specifies the {@link Rest#uriRelativity() uriRelativity} for this resource. 132 * 133 * @param value The new value for this property. 134 * @return This object. 135 */ 136 SELF uriRelativity(String value); 137 138 /** 139 * Specifies the {@link Rest#uriResolution() uriResolution} for this resource. 140 * 141 * @param value The new value for this property. 142 * @return This object. 143 */ 144 SELF uriResolution(String value); 145 146 //----------------------------------------------------------------------------------------------------------------- 147 // Marshalling 148 //----------------------------------------------------------------------------------------------------------------- 149 150 /** 151 * Specifies the {@link Rest#serializers() serializers} for this resource. 152 * 153 * @param value The new value for this property. 154 * @return This object. 155 */ 156 SELF serializers(Class<? extends Serializer>... value); 157 158 /** 159 * Specifies the {@link Rest#parsers() parsers} for this resource. 160 * 161 * @param value The new value for this property. 162 * @return This object. 163 */ 164 SELF parsers(Class<?>... value); 165 166 /** 167 * Specifies the {@link Rest#encoders() encoders} for this resource. 168 * 169 * @param value The new value for this property. 170 * @return This object. 171 */ 172 SELF encoders(Class<? extends Encoder>... value); 173 174 /** 175 * Specifies the {@link Rest#partSerializer() partSerializer} for this resource. 176 * 177 * @param value The new value for this property. 178 * @return This object. 179 */ 180 SELF partSerializer(Class<? extends HttpPartSerializer> value); 181 182 /** 183 * Specifies the {@link Rest#partParser() partParser} for this resource. 184 * 185 * @param value The new value for this property. 186 * @return This object. 187 */ 188 SELF partParser(Class<? extends HttpPartParser> value); 189 190 /** 191 * Specifies the {@link Rest#consumes() consumes} media types for this resource. 192 * 193 * @param value The new value for this property. 194 * @return This object. 195 */ 196 SELF consumes(String... value); 197 198 /** 199 * Specifies the {@link Rest#produces() produces} media types for this resource. 200 * 201 * @param value The new value for this property. 202 * @return This object. 203 */ 204 SELF produces(String... value); 205 206 /** 207 * Specifies the {@link Rest#responseProcessors() responseProcessors} for this resource. 208 * 209 * @param value The new value for this property. 210 * @return This object. 211 */ 212 SELF responseProcessors(Class<? extends ResponseProcessor>... value); 213 214 /** 215 * Specifies the {@link Rest#allowedSerializerOptions() allowedSerializerOptions} for this resource. 216 * 217 * @param value The new value for this property. 218 * @return This object. 219 */ 220 SELF allowedSerializerOptions(String... value); 221 222 /** 223 * Specifies the {@link Rest#allowedParserOptions() allowedParserOptions} for this resource. 224 * 225 * @param value The new value for this property. 226 * @return This object. 227 */ 228 SELF allowedParserOptions(String... value); 229 230 //----------------------------------------------------------------------------------------------------------------- 231 // Request behavior / params 232 //----------------------------------------------------------------------------------------------------------------- 233 234 /** 235 * Specifies the {@link Rest#allowedHeaderParams() allowedHeaderParams} for this resource. 236 * 237 * @param value The new value for this property. 238 * @return This object. 239 */ 240 SELF allowedHeaderParams(String value); 241 242 /** 243 * Specifies the {@link Rest#allowedMethodHeaders() allowedMethodHeaders} for this resource. 244 * 245 * @param value The new value for this property. 246 * @return This object. 247 */ 248 SELF allowedMethodHeaders(String value); 249 250 /** 251 * Specifies the {@link Rest#allowedMethodParams() allowedMethodParams} for this resource. 252 * 253 * @param value The new value for this property. 254 * @return This object. 255 */ 256 SELF allowedMethodParams(String value); 257 258 /** 259 * Specifies the {@link Rest#clientVersionHeader() clientVersionHeader} for this resource. 260 * 261 * @param value The new value for this property. 262 * @return This object. 263 */ 264 SELF clientVersionHeader(String value); 265 266 /** 267 * Specifies the {@link Rest#defaultAccept() defaultAccept} for this resource. 268 * 269 * @param value The new value for this property. 270 * @return This object. 271 */ 272 SELF defaultAccept(String value); 273 274 /** 275 * Specifies the {@link Rest#defaultContentType() defaultContentType} for this resource. 276 * 277 * @param value The new value for this property. 278 * @return This object. 279 */ 280 SELF defaultContentType(String value); 281 282 /** 283 * Specifies the {@link Rest#defaultCharset() defaultCharset} for this resource. 284 * 285 * @param value The new value for this property. 286 * @return This object. 287 */ 288 SELF defaultCharset(String value); 289 290 /** 291 * Specifies the {@link Rest#defaultRequestAttributes() defaultRequestAttributes} for this resource. 292 * 293 * @param value The new value for this property. 294 * @return This object. 295 */ 296 SELF defaultRequestAttributes(String... value); 297 298 /** 299 * Specifies the {@link Rest#defaultRequestHeaders() defaultRequestHeaders} for this resource. 300 * 301 * @param value The new value for this property. 302 * @return This object. 303 */ 304 SELF defaultRequestHeaders(String... value); 305 306 /** 307 * Specifies the {@link Rest#defaultResponseHeaders() defaultResponseHeaders} for this resource. 308 * 309 * @param value The new value for this property. 310 * @return This object. 311 */ 312 SELF defaultResponseHeaders(String... value); 313 314 /** 315 * Specifies the {@link Rest#disableContentParam() disableContentParam} flag for this resource. 316 * 317 * @param value The new value for this property. 318 * @return This object. 319 */ 320 SELF disableContentParam(String value); 321 322 /** 323 * Specifies the {@link Rest#maxInput() maxInput} for this resource. 324 * 325 * @param value The new value for this property. 326 * @return This object. 327 */ 328 SELF maxInput(String value); 329 330 /** 331 * Specifies the {@link Rest#restOpArgs() restOpArgs} for this resource. 332 * 333 * @param value The new value for this property. 334 * @return This object. 335 */ 336 SELF restOpArgs(Class<? extends RestOpArg>... value); 337 338 //----------------------------------------------------------------------------------------------------------------- 339 // Security 340 //----------------------------------------------------------------------------------------------------------------- 341 342 /** 343 * Specifies the {@link Rest#guards() guards} for this resource. 344 * 345 * @param value The new value for this property. 346 * @return This object. 347 */ 348 SELF guards(Class<? extends RestGuard>... value); 349 350 /** 351 * Specifies the {@link Rest#roleGuard() roleGuard} for this resource. 352 * 353 * @param value The new value for this property. 354 * @return This object. 355 */ 356 SELF roleGuard(String value); 357 358 /** 359 * Specifies the {@link Rest#rolesDeclared() rolesDeclared} for this resource. 360 * 361 * @param value The new value for this property. 362 * @return This object. 363 */ 364 SELF rolesDeclared(String value); 365 366 /** 367 * Specifies the {@link Rest#converters() converters} for this resource. 368 * 369 * @param value The new value for this property. 370 * @return This object. 371 */ 372 SELF converters(Class<? extends RestConverter>... value); 373 374 //----------------------------------------------------------------------------------------------------------------- 375 // Lifecycle / perf 376 //----------------------------------------------------------------------------------------------------------------- 377 378 /** 379 * Specifies the {@link Rest#eagerInit() eagerInit} flag for this resource. 380 * 381 * @param value The new value for this property. 382 * @return This object. 383 */ 384 SELF eagerInit(String value); 385 386 /** 387 * Specifies the {@link Rest#lazyChildren() lazyChildren} flag for this resource. 388 * 389 * @param value The new value for this property. 390 * @return This object. 391 */ 392 SELF lazyChildren(String value); 393 394 /** 395 * Specifies the {@link Rest#virtualThreads() virtualThreads} flag for this resource. 396 * 397 * @param value The new value for this property. 398 * @return This object. 399 */ 400 SELF virtualThreads(String value); 401 402 /** 403 * Specifies the {@link Rest#asyncTimeoutMillis() asyncTimeoutMillis} for this resource. 404 * 405 * @param value The new value for this property. 406 * @return This object. 407 */ 408 SELF asyncTimeoutMillis(String value); 409 410 /** 411 * Specifies the {@link Rest#asyncCompletionExecutor() asyncCompletionExecutor} bean name for this resource. 412 * 413 * @param value The new value for this property. 414 * @return This object. 415 */ 416 SELF asyncCompletionExecutor(String value); 417 418 //----------------------------------------------------------------------------------------------------------------- 419 // Observability / logging / errors 420 //----------------------------------------------------------------------------------------------------------------- 421 422 /** 423 * Specifies the {@link Rest#observability() observability} flag for this resource. 424 * 425 * @param value The new value for this property. 426 * @return This object. 427 */ 428 SELF observability(String value); 429 430 /** 431 * Specifies the {@link Rest#renderResponseStackTraces() renderResponseStackTraces} flag for this resource. 432 * 433 * @param value The new value for this property. 434 * @return This object. 435 */ 436 SELF renderResponseStackTraces(String value); 437 438 /** 439 * Specifies the {@link Rest#problemDetails() problemDetails} flag for this resource. 440 * 441 * @param value The new value for this property. 442 * @return This object. 443 */ 444 SELF problemDetails(String value); 445 446 /** 447 * Specifies the {@link Rest#debugMarshalling() debugMarshalling} flag for this resource. 448 * 449 * @param value The new value for this property. 450 * @return This object. 451 */ 452 SELF debugMarshalling(String value); 453 454 //----------------------------------------------------------------------------------------------------------------- 455 // Docs / metadata / i18n / static files 456 //----------------------------------------------------------------------------------------------------------------- 457 458 /** 459 * Specifies the {@link Rest#title() title} for this resource. 460 * 461 * @param value The new value for this property. 462 * @return This object. 463 */ 464 SELF title(String... value); 465 466 /** 467 * Specifies the {@link Rest#description() description} for this resource. 468 * 469 * @param value The new value for this property. 470 * @return This object. 471 */ 472 SELF description(String... value); 473 474 /** 475 * Specifies the {@link Rest#siteName() siteName} for this resource. 476 * 477 * @param value The new value for this property. 478 * @return This object. 479 */ 480 SELF siteName(String value); 481 482 /** 483 * Specifies the {@link Rest#swaggerProvider() swaggerProvider} for this resource. 484 * 485 * @param value The new value for this property. 486 * @return This object. 487 */ 488 SELF swaggerProvider(Class<? extends SwaggerProvider> value); 489 490 /** 491 * Specifies the {@link Rest#openApiProvider() openApiProvider} for this resource. 492 * 493 * @param value The new value for this property. 494 * @return This object. 495 */ 496 SELF openApiProvider(Class<? extends OpenApiProvider> value); 497 498 /** 499 * Specifies the {@link Rest#messages() messages} bundle location for this resource. 500 * 501 * @param value The new value for this property. 502 * @return This object. 503 */ 504 SELF messages(String value); 505 506 /** 507 * Specifies the {@link Rest#config() config} location for this resource. 508 * 509 * @param value The new value for this property. 510 * @return This object. 511 */ 512 SELF config(String value); 513 514 /** 515 * Specifies the {@link Rest#staticFiles() staticFiles} for this resource. 516 * 517 * @param value The new value for this property. 518 * @return This object. 519 */ 520 SELF staticFiles(Class<? extends StaticFiles> value); 521 522 /** 523 * Specifies the {@link Rest#noInherit() noInherit} property names for this resource. 524 * 525 * @param value The new value for this property. 526 * @return This object. 527 */ 528 SELF noInherit(String... value); 529 530 //----------------------------------------------------------------------------------------------------------------- 531 // Programmatic-only knob (no @Rest member) 532 //----------------------------------------------------------------------------------------------------------------- 533 534 /** 535 * Specifies whether MDC async propagation is enabled for this resource. 536 * 537 * <p> 538 * This is a <b>programmatic-only</b> knob — it has no {@link Rest @Rest} annotation member (its default is 539 * env-driven). Setting it here overrides the {@code RestContext.mdcAsyncPropagation} env-driven default. 540 * 541 * @param value The new value for this property. 542 * @return This object. 543 */ 544 SELF mdcAsyncPropagation(boolean value); 545 546 //----------------------------------------------------------------------------------------------------------------- 547 // Forward-compat escape hatch 548 //----------------------------------------------------------------------------------------------------------------- 549 550 /** 551 * Generic forward-compatible override setter, keyed by the {@code @Rest} property name (e.g. 552 * {@code "allowContentParam"}, {@code "defaultRequestHeaders"}). 553 * 554 * <p> 555 * Use this escape hatch for members not yet exposed as a dedicated fluent method. Keys reuse the existing 556 * {@code @Rest} member names. 557 * 558 * @param key The {@code @Rest} property name. Must not be <jk>null</jk>. 559 * @param value The override value. 560 * @return This object. 561 */ 562 SELF set(String key, Object value); 563}