Interface IFileUploadService

All Known Implementing Classes:
AppGyroFileUploaderService
public interface IFileUploadService
The file upload service of one application session: mints reservations that authorize a client to POST file chunks over HTTPS, observes them, and owns the staged files until the App takes them.

Declared in core, implemented in the server, obtained from IAppSessionGyro.getFileUploadService(). The WebSocket authorizes and HTTPS carries the bytes: nothing in this interface ever carries file content.

Every reservation is bound to the application session that made it: it survives a client disconnecting or reconnecting, it does not survive the application session ending, and any client of the same application session may continue it with the per-file secrets.

Author:
Christopher Mindus

  • Method Details

    • isEnabled

      boolean isEnabled()
      Checks if uploads are enabled for new reservations. Transfers already in flight when uploads are disabled are allowed to finish.
      Returns:
      true if reserve(List, IFileUploadListener) would consider a request.

    • reserve

      default IUploadReservation reserve(List<UploadFileRequest> files, IFileUploadListener listener)
      Reserves a transfer of one or more files, with the automatic failure notice on. Quota, file count, size and type limits are checked here, never at write time; files are accepted in order until one no longer fits and the rest are refused individually.
      Parameters:
      files - The files the client declares, at least one.
      listener - A listener for this reservation only, or null; the service-level listeners see it as well.
      Returns:
      The reservation, accepted or refused; never null.
      Throws:
      NullPointerException - If files is null.
      IllegalArgumentException - If files is empty.

    • reserve

      default IUploadReservation reserve(List<UploadFileRequest> files, IFileUploadListener listener, boolean notices)
      Reserves a transfer of one or more files. Quota, file count, size and type limits are checked here, never at write time; files are accepted in order until one no longer fits and the rest are refused individually.
      Parameters:
      files - The files the client declares, at least one.
      listener - A listener for this reservation only, or null; the service-level listeners see it as well.
      notices - Whether a cancellation only the server knows about (idle, start, maxPause) is shown to the client as one message box listing the files; false when the App reports failures its own way.
      Returns:
      The reservation, accepted or refused; never null.
      Throws:
      NullPointerException - If files is null.
      IllegalArgumentException - If files is empty.

    • reserve

      IUploadReservation reserve(List<UploadFileRequest> files, IFileUploadListener listener, boolean notices, String types)
      Reserves a transfer of one or more files that must also be of the types the requester accepts. The request's types narrow $upload.types for this reservation only: a file is accepted when both permit it - at reservation on the declared type and name, and again at verification on the type the content was found to be, where a file that is not what it was declared as fails typeNotPermitted.
      Parameters:
      files - The files the client declares, at least one.
      listener - A listener for this reservation only, or null; the service-level listeners see it as well.
      notices - Whether a cancellation only the server knows about (idle, start, maxPause) is shown to the client as one message box listing the files; false when the App reports failures its own way.
      types - The types the requester accepts, in the syntax of the HTML accept attribute: comma-separated media types (image/png), families (image/*) and file name extensions (.pdf); null or empty for no types of its own.
      Returns:
      The reservation, accepted or refused; never null.
      Throws:
      NullPointerException - If files is null.
      IllegalArgumentException - If files is empty.

    • getReservation

      IUploadReservation getReservation(String reservationID)
      Gets a live reservation of this application session.
      Parameters:
      reservationID - The reservation ID.
      Returns:
      The reservation, or null if unknown, swept or not of this session.

    • getReservations

      List<? extends IUploadReservation> getReservations()
      Gets the live reservations of this application session.
      Returns:
      The reservations, never null.

    • addListener

      boolean addListener(IFileUploadListener listener)
      Adds a listener for every reservation of this application session.
      Parameters:
      listener - The listener.
      Returns:
      true if added, false if already present.
      Throws:
      NullPointerException - If the listener is null.

    • removeListener

      boolean removeListener(IFileUploadListener listener)
      Removes a listener.
      Parameters:
      listener - The listener.
      Returns:
      true if removed, false if not present.