Class AppGyroFileUploaderService

java.lang.Object
com.iizix.server.gyro.AppGyroFileUploaderService
All Implemented Interfaces:
IFileUploadService, FileUploadRegistry.IEvents
public final class AppGyroFileUploaderService extends Object implements IFileUploadService, FileUploadRegistry.IEvents
The file upload service of one application session: mints reservations through the server-global registry, routes the registry's events to the session's listeners on the session's worker thread, verifies completed files, and cancels everything when the session is disposed of.

The WebSocket authorizes and HTTPS carries the bytes: this class never sees file content except in the verification pass, which decodes a completed part on a server executor thread, never on a servlet thread and never on the session's worker.

Created lazily by AppSessionGyro.getFileUploadService() and disposed of in AppSessionGyro.dispose() beside the session's file provider: when disposed of, all transfers are cancelled and removed.

Two things reach the client from here (rulings of 2026-09-24). The App's pause and resume of a file are pushed to every registered IUploadClientChannel (row 12), the client side of which is the JS transport order's; the client's own pause notices come in through onClientPauseNotice(String, int, boolean, String). And a cancellation only the server knows about (idle, start, maxPause) is shown as ONE message box per reservation listing its files (row 25), through the session context's message-box queue (row 21: kept for the next client, dropped with the session), unless the App switched it off for the reservation (row 20).

Author:
Christopher Mindus

  • Constructor Details

    • AppGyroFileUploaderService

      public AppGyroFileUploaderService(IUploadSessionContext context, FileUploadRegistry registry, UploadStagingStore store, Executor verifier, BooleanSupplier mounted)
      Constructor.
      Parameters:
      context - The session context.
      registry - The server-global registry.
      store - The staging store.
      verifier - The executor for the verification pass.
      mounted - Whether the chunk route is mounted (FileUploadModule.isRouteAvailable() in production): a reservation is refused disabled while it is not.

  • Method Details

    • getSessionUUID

      public String getSessionUUID()
      Gets the application session UUID this service serves.
      Returns:
      The UUID string.

    • isEnabled

      public boolean isEnabled()
      Checks if uploads are enabled for new reservations: the live $upload.allow setting AND the chunk route mounted. The mount gate is read once, at server ready, so the setting turned on at run time (or a registerServlet that failed at start) must not hand out reservations whose chunks have no route: they are refused disabled until a restart mounts it. Turned off at run time, the mounted route keeps serving transfers in flight and new reservations are refused here.
      Specified by:
      isEnabled in interface IFileUploadService
      Returns:
      true if reserve(List, IFileUploadListener, boolean, String) would consider a request.

    • reserve

      public IUploadReservation reserve(List<UploadFileRequest> files, IFileUploadListener listener, boolean notices, String types)
      Description copied from interface: IFileUploadService
      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.
      Specified by:
      reserve in interface IFileUploadService
      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.

    • getReservation

      public IUploadReservation getReservation(String reservationID)
      Description copied from interface: IFileUploadService
      Gets a live reservation of this application session.
      Specified by:
      getReservation in interface IFileUploadService
      Parameters:
      reservationID - The reservation ID.
      Returns:
      The reservation, or null if unknown, swept or not of this session.

    • getReservations

      public List<? extends IUploadReservation> getReservations()
      Description copied from interface: IFileUploadService
      Gets the live reservations of this application session.
      Specified by:
      getReservations in interface IFileUploadService
      Returns:
      The reservations, never null.

    • addListener

      public boolean addListener(IFileUploadListener listener)
      Description copied from interface: IFileUploadService
      Adds a listener for every reservation of this application session.
      Specified by:
      addListener in interface IFileUploadService
      Parameters:
      listener - The listener.
      Returns:
      true if added, false if already present.

    • removeListener

      public boolean removeListener(IFileUploadListener listener)
      Description copied from interface: IFileUploadService
      Removes a listener.
      Specified by:
      removeListener in interface IFileUploadService
      Parameters:
      listener - The listener.
      Returns:
      true if removed, false if not present.

    • onFileComplete

      public void onFileComplete(UploadReservation r, UploadFileEntry f)
      Called by the servlet after the last chunk of a file has been recorded: runs the verification pass on the executor and reports the outcome to the listeners.
      Parameters:
      r - The reservation.
      f - The complete file.

    • addClientChannel

      public boolean addClientChannel(IUploadClientChannel channel)
      Registers a client's channel: the App's pauses and resumes are pushed to it from now on, and every file the App holds paused right now is told to it at once, so a reconnecting client learns what it must not send.
      Parameters:
      channel - The channel.
      Returns:
      true if added, false if already registered.
      Throws:
      NullPointerException - If the channel is null.

    • removeClientChannel

      public boolean removeClientChannel(IUploadClientChannel channel)
      Removes a client's channel (its client session is disposed of).
      Parameters:
      channel - The channel.
      Returns:
      true if removed, false if not registered.

    • onClientPauseNotice

      public void onClientPauseNotice(String reservationID, int fileIndex, boolean paused, String reason)
      The client's pause notice for a file of this session (its page hidden, its network gone, or back again): the listener hears it and the idle timeout is suspended while paused. A notice for an unknown reservation or file is ignored; a chunk arriving on a client-paused file is that client's resume, so a late resume notice is harmless.
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index, or -1 for every file.
      paused - true for a pause, false for a resume.
      reason - The client's reason, null or empty for paused.

    • onFileCancelled

      public void onFileCancelled(UploadReservation r, UploadFileEntry f, String reason)
      --- FileUploadRegistry.IEvents (routed here by the module for this session) ---
      Specified by:
      onFileCancelled in interface FileUploadRegistry.IEvents
      Parameters:
      r - The reservation.
      f - The file.
      reason - The reason.

    • onFilePaused

      public void onFilePaused(UploadReservation r, UploadFileEntry f, String reason, boolean byApp)
      Description copied from interface: FileUploadRegistry.IEvents
      A file entered UploadState.PAUSED.
      Specified by:
      onFilePaused in interface FileUploadRegistry.IEvents
      Parameters:
      r - The reservation.
      f - The file.
      reason - The reason given by whoever paused it.
      byApp - true if the App paused it, false if the client did.

    • onFileResumed

      public void onFileResumed(UploadReservation r, UploadFileEntry f, boolean byApp)
      Description copied from interface: FileUploadRegistry.IEvents
      A file left UploadState.PAUSED: every party that held it has resumed it.
      Specified by:
      onFileResumed in interface FileUploadRegistry.IEvents
      Parameters:
      r - The reservation.
      f - The file.
      byApp - true if the App's resume freed it, false if the client's did.

    • onAppReleased

      public void onAppReleased(UploadReservation r, UploadFileEntry f)
      Description copied from interface: FileUploadRegistry.IEvents
      The App resumed a file it held, but the client still holds it: the file stays paused and no FileUploadRegistry.IEvents.onFileResumed(UploadReservation, UploadFileEntry, boolean) is given, yet the client must learn the App no longer holds it.
      Specified by:
      onAppReleased in interface FileUploadRegistry.IEvents
      Parameters:
      r - The reservation.
      f - The file.

    • onFileFailed

      public void onFileFailed(UploadReservation r, UploadFileEntry f, String reason)
      Description copied from interface: FileUploadRegistry.IEvents
      A file failed; its bytes are gone.
      Specified by:
      onFileFailed in interface FileUploadRegistry.IEvents
      Parameters:
      r - The reservation.
      f - The file.
      reason - The reason.

    • onReservationClosed

      public void onReservationClosed(UploadReservation r)
      Description copied from interface: FileUploadRegistry.IEvents
      Every file of the reservation is final.
      Specified by:
      onReservationClosed in interface FileUploadRegistry.IEvents
      Parameters:
      r - The reservation.

    • onFileProgress

      public void onFileProgress(UploadReservation r, UploadFileEntry f)
      Reports a chunk's progress; called by the servlet at most once per second per file.
      Parameters:
      r - The reservation.
      f - The file.

    • onFileStarted

      public void onFileStarted(UploadReservation r, UploadFileEntry f)
      Reports the first accepted chunk of a file.
      Parameters:
      r - The reservation.
      f - The file.

    • dispose

      public void dispose()
      Disposes of the service: every transfer of the session is cancelled and removed, the listeners are cleared. Called from AppSessionGyro.dispose(), after the worker is gone, so nothing is posted.

    • isDisposed

      public boolean isDisposed()
      Checks if disposed of.
      Returns:
      true if disposed.