Interface IUploadReservation

All Known Implementing Classes:
UploadReservation
public interface IUploadReservation
One authorized transfer of one or more files, minted by IFileUploadService.reserve(List, IFileUploadListener) and bound to the application session that made it.

The reservation ID is opaque and loggable and is part of the upload URL. The per-file secrets are bearer credentials: they travel only in the X-iizi-upload header and are never logged; a caller that reads them through getSecret(int) must hand them only to the client the reservation was made for.

Author:
Christopher Mindus

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancel(int fileIndex, String reason)
    Cancels one file or the whole reservation.
    int
    getChunkSize()
    Gets the chunk size the client must use, in bytes.
    List<? extends IUploadFile>
    getFiles()
    Gets the files, accepted or refused, in the order they were requested; a file's index in this list is its IUploadFile.getFileIndex().
    String
    getID()
    Gets the reservation ID: 16 random bytes as 32 lower-case hex characters.
    int
    getIdleTimeout()
    Gets the idle timeout in force, in seconds.
    int
    getMaxFiles()
    Gets the maximum file count per reservation in force.
    int
    getMaxPause()
    Gets the maximum pause time in force, in seconds: how long the reservation may stay paused (by the App or the client) before it is cancelled with reason maxPause.
    String
    getPath()
    Gets the relative upload path, ending with '/'.
    String
    getPermittedTypes()
    Gets the permitted media types in force, as configured, empty for any.
    String
    getRefusalReason()
    Gets the reason the whole reservation was refused.
    long
    getRemainingBytes()
    Gets the remaining allowance after this reservation, i.e.
    String
    getSecret(int fileIndex)
    Gets the per-file secret.
    boolean
    isAccepted()
    Checks if the reservation as a whole was accepted.
    boolean
    isCancelled()
    Checks if the reservation was cancelled as a whole.
    boolean
    isClosed()
    Checks if every file has reached a terminal state or been verified, i.e.
    boolean
    isNoticeEnabled()
    Checks if the App wants the automatic failure notice for this reservation: a cancellation only the server knows about (idle, start, maxPause) is then shown to the client as one message box listing the files.
    boolean
    isPaused()
    Checks if the reservation is paused as a whole: no file is receiving chunks and at least one is UploadState.PAUSED.
    void
    pause(int fileIndex, String reason)
    Pauses one file or every receiving file: the client is told to stop sending and a chunk sent anyway is refused as paused, never as a failure.
    void
    resume(int fileIndex)
    Resumes one file or every file the App paused: the client is told it may send again.

  • Method Details

    • getID

      String getID()
      Gets the reservation ID: 16 random bytes as 32 lower-case hex characters.
      Returns:
      The ID.

    • getPath

      String getPath()
      Gets the relative upload path, ending with '/'. The client resolves it against the origin it already uses for its WebSocket; the server never composes a scheme, host or port.
      Returns:
      The path, e.g. /iizi-upload/.

    • isAccepted

      boolean isAccepted()
      Checks if the reservation as a whole was accepted. A refused reservation has no accepted files and getRefusalReason() says why.
      Returns:
      true if accepted.

    • getRefusalReason

      String getRefusalReason()
      Gets the reason the whole reservation was refused.
      Returns:
      The reason, or null if accepted.

    • getFiles

      List<? extends IUploadFile> getFiles()
      Gets the files, accepted or refused, in the order they were requested; a file's index in this list is its IUploadFile.getFileIndex().
      Returns:
      The files, never null.

    • getSecret

      String getSecret(int fileIndex)
      Gets the per-file secret. Never log it.
      Parameters:
      fileIndex - The file index.
      Returns:
      The secret as base64url without padding, or null if the file was refused.
      Throws:
      IndexOutOfBoundsException - For an invalid index.

    • getChunkSize

      int getChunkSize()
      Gets the chunk size the client must use, in bytes.
      Returns:
      The chunk size.

    • getRemainingBytes

      long getRemainingBytes()
      Gets the remaining allowance after this reservation, i.e. the most a further reservation of the same session could declare, in bytes.
      Returns:
      The remaining bytes, or Long.MAX_VALUE if unlimited.

    • getMaxFiles

      int getMaxFiles()
      Gets the maximum file count per reservation in force.
      Returns:
      The count.

    • getPermittedTypes

      String getPermittedTypes()
      Gets the permitted media types in force, as configured, empty for any.
      Returns:
      The comma-separated list.

    • getIdleTimeout

      int getIdleTimeout()
      Gets the idle timeout in force, in seconds.
      Returns:
      The seconds after which an idle reservation is cancelled.

    • getMaxPause

      int getMaxPause()
      Gets the maximum pause time in force, in seconds: how long the reservation may stay paused (by the App or the client) before it is cancelled with reason maxPause. The idle timeout does not run while paused.
      Returns:
      The seconds.

    • isNoticeEnabled

      boolean isNoticeEnabled()
      Checks if the App wants the automatic failure notice for this reservation: a cancellation only the server knows about (idle, start, maxPause) is then shown to the client as one message box listing the files. On by default.
      Returns:
      true if the notice is shown, false if the App reports failures its own way.

    • isClosed

      boolean isClosed()
      Checks if every file has reached a terminal state or been verified, i.e. no further byte is expected.
      Returns:
      true if closed.

    • isCancelled

      boolean isCancelled()
      Checks if the reservation was cancelled as a whole.
      Returns:
      true if cancelled.

    • isPaused

      boolean isPaused()
      Checks if the reservation is paused as a whole: no file is receiving chunks and at least one is UploadState.PAUSED. The idle timeout is suspended and the maximum pause time runs.
      Returns:
      true if paused as a whole.

    • pause

      void pause(int fileIndex, String reason)
      Pauses one file or every receiving file: the client is told to stop sending and a chunk sent anyway is refused as paused, never as a failure. The listener sees IFileUploadListener.onFilePaused(IUploadReservation, IUploadFile, String). A file that is complete, verified or terminal is left alone; a file the client has already paused is additionally held by the App.
      Parameters:
      fileIndex - The file index, or -1 for every file.
      reason - The reason, reported to the listener and the client; null or empty means paused.

    • resume

      void resume(int fileIndex)
      Resumes one file or every file the App paused: the client is told it may send again. A file the client has also paused stays paused until the client resumes it.
      Parameters:
      fileIndex - The file index, or -1 for every file.

    • cancel

      void cancel(int fileIndex, String reason)
      Cancels one file or the whole reservation. Cancel means cancel: the staged bytes are deleted immediately and the quota is released.
      Parameters:
      fileIndex - The file index, or -1 for the whole reservation.
      reason - The reason, recorded on the file(s) and reported to the listener.