Package com.vaadin.flow.server.streams

Interface UploadValidator

All Superinterfaces:

Serializable

public interface UploadValidator
extends Serializable

Validates an upload synchronously while it is being received, allowing it to be refused before it is stored.

A validator has three lifecycle phases, each invoked on the request thread by the pre-made upload handlers (InMemoryUploadHandler, FileUploadHandler, TemporaryFileUploadHandler):

• validateMetadata(UploadEvent) once, before any data is read, for checks based only on metadata such as file name, content type or declared size;
• validateHeader(UploadEvent, ByteBuffer) once, over the first headerSize() bytes of the upload, for checks on the leading content such as file-signature ("magic byte") or MIME sniffing;
• validateComplete(UploadEvent, UploadContent) once, after the whole upload has been received, for whole-content checks such as antivirus scanning.

Calling UploadEvent.reject(String) from any phase aborts the upload: no further data is read, the success callback is not invoked and any partially stored data is cleaned up. Prefer reject(...) over throwing: in a multipart upload a rejection lets the remaining files be processed (HTTP 207), whereas a thrown exception aborts the whole request.

Validators run synchronously and not wrapped in UI.access(com.vaadin.flow.server.Command); they must only inspect the upload and decide whether to reject it, not perform UI updates. Use a TransferProgressListener for UI updates.

For single-phase checks, prefer the fluent handler methods (AbstractUploadHandler.validateMetadata(UploadMetadataCallback) and friends) with a lambda. Implement this interface directly to combine multiple phases in one validator.

Since:

25.3

See Also:

• AbstractUploadHandler.withValidator(UploadValidator)
• UploadEvent.reject(String)

Method Summary

Modifier and Type	Method	Description
default int	headerSize()	The number of leading bytes to make available to validateHeader(UploadEvent, ByteBuffer).
default void	validateComplete(UploadEvent event, UploadContent content)	Validates the fully received upload, before it is delivered to the success callback.
default void	validateHeader(UploadEvent event, ByteBuffer header)	Validates the header (leading bytes) of the upload, before the rest is read.
default void	validateMetadata(UploadEvent event)	Validates the upload metadata before any data is read.

Method Details

validateMetadata

default void validateMetadata(UploadEvent event)
                       throws IOException

Validates the upload metadata before any data is read.

Invoked once, before the first byte is read, so it can refuse an upload (for example by declared size or file name) without reading its body.

Parameters:

event - the current upload

Throws:

IOException - if validation fails; treated as a transfer error

validateHeader

default void validateHeader(UploadEvent event,
 ByteBuffer header)
                     throws IOException

Validates the header (leading bytes) of the upload, before the rest is read.

Invoked once, only when headerSize() is greater than zero, with a read-only view of the first headerSize() bytes of the upload (or fewer, including an empty buffer, if the upload is smaller). Rejecting here aborts the upload after only those leading bytes have been read. The buffer is only valid for the duration of the call and must not be retained.

Overriding this method without also overriding headerSize() to return a positive value has no effect: it is never invoked.

Parameters:

event - the current upload

header - a read-only view of the leading bytes of the upload

Throws:

IOException - if validation fails; treated as a transfer error

validateComplete

default void validateComplete(UploadEvent event,
 UploadContent content)
                       throws IOException

Validates the fully received upload, before it is delivered to the success callback.

Invoked once, after the whole upload has been received. Because the entire body has already been read by this point, this phase cannot abort reading early, so it is not a size-limiting mechanism. Note that validateMetadata(com.vaadin.flow.server.streams.UploadEvent) can only inspect the client-declared size (UploadEvent.getFileSize()), which is untrusted for XHR uploads, and UploadHandler.getFileSizeMax() bounds multipart uploads only — XHR upload size is not enforced by the framework.

The transfer's TransferProgressListener.onComplete(com.vaadin.flow.server.streams.TransferContext, long) has already fired by the time this runs (it signals that all bytes were received, not that the upload was accepted); rejecting or failing here is reported to progress listeners as TransferProgressListener.onError(com.vaadin.flow.server.streams.TransferContext, java.io.IOException).

Parameters:

event - the current upload

content - handle to the received content, only valid for the duration of the call

Throws:

IOException - if validation fails; treated as a transfer error

headerSize

default int headerSize()

The number of leading bytes to make available to validateHeader(UploadEvent, ByteBuffer). Defaults to 0, meaning the header phase is skipped for this validator; override to a positive value to receive the header.

Must return a stable value: it is queried more than once per upload. The framework buffers this many bytes in memory per upload, so keep it modest.

Returns:

the header size in bytes, 0 to skip the header phase