Interface IUIFileUploadListener

public interface IUIFileUploadListener
Listener of a UIFileUpload component: asked whether a request of the client to upload files is allowed, and told what becomes of the files (design UPLOAD-UI-DESIGN.md edition 2, section 3.4; rulings UU-8 and UU-9).

Every method has an empty default, so a listener overrides only what it needs. Added with UIFileUpload.addListener(IUIFileUploadListener). The listener is called first, then the method tagged with OnUIUpload for the component, if any.

Threads. onUploadRequest(UIFileUpload, UploadRequest) is called on the client session's worker, while the client waits for its answer. Every other method is called on the application session's worker, as the upload service calls its listeners.

The listener hears a transfer only while its component lives. When the component is disposed of, its transfers continue and this listener hears nothing more of them; the listeners of the client session (IClientUploadAPI.addListener) and of the application session (IFileUploadService.addListener) hear the rest.

Author:
Christopher Mindus

  • Method Details

    • onUploadRequest

      default String onUploadRequest(UIFileUpload component, UploadRequest request)
      Asks whether a request of the client to upload files is allowed. Called after the component's own limits have passed and before anything is reserved. A refusal by any listener, or by the method tagged with @OnUIUpload, wins.
      Parameters:
      component - The component.
      request - The request: the files with their declared names, types and sizes.
      Returns:
      null to allow the request, or the reason the client is told, a short code such as denied.

    • onReserved

      default void onReserved(UIFileUpload component, IUploadReservation reservation)
      Called once when the request has been reserved with the upload service, accepted or refused; the client has been told.
      Parameters:
      component - The component.
      reservation - The reservation.

    • onFileStarted

      default void onFileStarted(UIFileUpload component, IUploadFile file)
      Called when the first chunk of a file has been accepted.
      Parameters:
      component - The component.
      file - The file.

    • onFileProgress

      default void onFileProgress(UIFileUpload component, IUploadFile file, long plainBytes, long plainTotal)
      Called as chunks arrive, at most once per second per file.
      Parameters:
      component - The component.
      file - The file.
      plainBytes - Uncompressed bytes acknowledged so far.
      plainTotal - The declared uncompressed size.

    • onFilePaused

      default void onFilePaused(UIFileUpload component, IUploadFile file, String reason)
      Called once when a file is paused, by the App or by the client.
      Parameters:
      component - The component.
      file - The file.
      reason - The reason whoever paused it gave, never null.

    • onFileResumed

      default void onFileResumed(UIFileUpload component, IUploadFile file)
      Called once when a paused file may receive chunks again.
      Parameters:
      component - The component.
      file - The file.

    • onFileCompleted

      default void onFileCompleted(UIFileUpload component, IUploadedFile file)
      Take the file or delete it here: a completed file the App neither takes (IUploadedFile.take()) nor deletes (IUploadedFile.delete()) stays the server's and is removed with its reservation at the next sweep.

      Called once when a file has been completely received and verified.

      Parameters:
      component - The component.
      file - The verified file.

    • onFileFailed

      default void onFileFailed(UIFileUpload component, IUploadFile file, String reason)
      Called once when a file failed verification or its transfer; the staged bytes are gone.
      Parameters:
      component - The component.
      file - The file.
      reason - The reason, e.g. typeMismatch, sizeMismatch, corrupt, overCap.

    • onFileCancelled

      default void onFileCancelled(UIFileUpload component, IUploadFile file, String reason)
      Called once when a file was cancelled by the client, the App, a timeout or disposal; the staged bytes are gone.
      Parameters:
      component - The component.
      file - The file.
      reason - The reason, e.g. cancelled, idle, start, maxPause.

    • onUploadFinished

      default void onUploadFinished(UIFileUpload component, IUploadReservation reservation)
      Called once when every file of a reservation is final: completed, failed or cancelled.
      Parameters:
      component - The component.
      reservation - The reservation.