Class StaticFiles.Builder
- Enclosing class:
StaticFiles
StaticFiles instances.- Author:
- Mark Allen
-
Method Summary
Modifier and TypeMethodDescriptionaccessResolver(@Nullable StaticFiles.AccessResolver accessResolver) Sets the resolver used to decide whether resolved files are served, denied, or hidden.build()Builds the static-file helper.cacheControlResolver(@Nullable StaticFiles.CacheControlResolver cacheControlResolver) Sets the resolver used to produceCache-Controlvalues.entityTagResolver(@Nullable StaticFiles.EntityTagResolver entityTagResolver) Sets the resolver used to produceETagvalues.followSymlinks(@Nullable Boolean followSymlinks) Sets whether symbolic links are followed while resolving static-file paths.headersResolver(@Nullable StaticFiles.HeadersResolver headersResolver) Sets the resolver used to produce extra response headers.indexFileNames(@Nullable List<@NonNull String> indexFileNames) Sets the index file names to try when a request path resolves to a directory.lastModifiedResolver(@Nullable StaticFiles.LastModifiedResolver lastModifiedResolver) Sets the resolver used to produceLast-Modifiedvalues.mimeTypeResolver(@Nullable MimeTypeResolver mimeTypeResolver) Sets the resolver used to produceContent-Typevalues.rangeRequestsResolver(@Nullable StaticFiles.RangeRequestsResolver rangeRequestsResolver) Sets the resolver used to decide whether byte range requests are honored.trustedImmutableRoot(@Nullable Boolean trustedImmutableRoot) Declares that the root, its ancestors, links, and files are controlled exclusively by the application operator and remain unchanged while this helper or its responses are in use.
-
Method Details
-
trustedImmutableRoot
Declares that the root, its ancestors, links, and files are controlled exclusively by the application operator and remain unchanged while this helper or its responses are in use.This declaration is required on every platform. It does not set filesystem permissions or freeze files. Do not enable it for uploads, tenant-writable directories, or any tree that untrusted code can mutate. Public NIO checks cannot exclude all path-replacement races. Passing
falseornullwithdraws the declaration and makesbuild()fail closed. Deploy a new helper for a new immutable asset tree.- Parameters:
trustedImmutableRoot-trueto accept the immutable-root contract- Returns:
- this builder
-
indexFileNames
Sets the index file names to try when a request path resolves to a directory.Names are tried in list order. Each name must be a single file name, not a path; blank names,
.,.., path separators, control characters, Windows drive paths, and UNC-style paths are rejected when the builder is built.Each call replaces the complete previously configured list; it does not append. Passing
nullor an empty list clears the index file names.- Parameters:
indexFileNames- the replacement index file names, ornullto clear them- Returns:
- this builder
-
mimeTypeResolver
Sets the resolver used to produceContent-Typevalues.The configured resolver fully replaces the default resolver. Soklet's default resolver uses a curated deterministic set of common web-asset extensions, returns
Optional.empty()for unknown extensions, and does not callFiles.probeContentType(Path). Applications that need OS-level MIME database behavior can configure a resolver that callsFiles.probeContentType(...)directly.- Parameters:
mimeTypeResolver- the resolver to use, ornullto restore the default resolver- Returns:
- this builder
-
entityTagResolver
public @NonNull StaticFiles.Builder entityTagResolver(@Nullable StaticFiles.EntityTagResolver entityTagResolver) Sets the resolver used to produceETagvalues.Passing
nullrestores the default weak metadata-based resolver.- Parameters:
entityTagResolver- the resolver to use, ornullto restore the default resolver- Returns:
- this builder
-
accessResolver
public @NonNull StaticFiles.Builder accessResolver(@Nullable StaticFiles.AccessResolver accessResolver) Sets the resolver used to decide whether resolved files are served, denied, or hidden.The access resolver runs after path safety, index-file resolution, symlink policy, readability, regular-file checks, and attribute reads, but before MIME, validator, cache-control, extra-header, and range-request resolvers. It receives the resolved file path, not the original request path.
- Parameters:
accessResolver- the resolver to use, ornullto restore the allow-all default- Returns:
- this builder
-
lastModifiedResolver
public @NonNull StaticFiles.Builder lastModifiedResolver(@Nullable StaticFiles.LastModifiedResolver lastModifiedResolver) Sets the resolver used to produceLast-Modifiedvalues.Passing
nullrestores the default resolver, which uses the file attributes read for the response.- Parameters:
lastModifiedResolver- the resolver to use, ornullto restore the default resolver- Returns:
- this builder
-
cacheControlResolver
public @NonNull StaticFiles.Builder cacheControlResolver(@Nullable StaticFiles.CacheControlResolver cacheControlResolver) Sets the resolver used to produceCache-Controlvalues.Passing
nullrestores the disabled resolver, which omitsCache-Control.- Parameters:
cacheControlResolver- the resolver to use, ornullto omitCache-Control- Returns:
- this builder
-
headersResolver
public @NonNull StaticFiles.Builder headersResolver(@Nullable StaticFiles.HeadersResolver headersResolver) Sets the resolver used to produce extra response headers.Passing
nullrestores the disabled resolver, which emits no extra headers. Managed file headers cannot be supplied here; seeStaticFiles.HeadersResolverfor the controlled names and dedicated resolver alternatives.- Parameters:
headersResolver- the resolver to use, ornullto omit extra headers- Returns:
- this builder
-
rangeRequestsResolver
public @NonNull StaticFiles.Builder rangeRequestsResolver(@Nullable StaticFiles.RangeRequestsResolver rangeRequestsResolver) Sets the resolver used to decide whether byte range requests are honored.Passing
nullrestores the default resolver, which enables range requests.- Parameters:
rangeRequestsResolver- the resolver to use, ornullto enable range requests- Returns:
- this builder
-
followSymlinks
Sets whether symbolic links are followed while resolving static-file paths.Passing
nullrestores the default offalse. When disabled, any symbolic-link component under the static root causes the candidate path to be hidden. Enabling this option resolves links inside the configured root. Links that resolve outside the root are hidden. The required trusted immutable-root contract applies to links and their targets too; observed replacement links are rejected during delivery.- Parameters:
followSymlinks-trueto follow symlinks,falseto reject them, ornullfor the default- Returns:
- this builder
-
build
Builds the static-file helper.The configured root is validated as a directory when this method is called. With
followSymlinksenabled it is resolved to a real path; otherwise a symbolic-link root is rejected. The resolved root identity is captured without retaining an open directory handle. Both modes requiretrustedImmutableRoot(Boolean)to be explicitly set totrueand a provider with stable file identities. Rebuild the helper when intentionally switching deployment roots, after in-flight responses have completed. Pass the root'sPath.toRealPath(LinkOption...)value explicitly to use its resolved directory without enabling symlink traversal.- Returns:
- the configured static-file helper
-