Class ClientSessionUploadChannel

java.lang.Object
com.iizix.server.upload.ClientSessionUploadChannel
All Implemented Interfaces:
IClientUploadAPI, UploadChannelProps.IHandler, IUploadClientChannel
public final class ClientSessionUploadChannel extends Object implements IClientUploadAPI, UploadChannelProps.IHandler, IUploadClientChannel
The server side of one client session's upload channel, and the file upload API of that client session (IClientUploadAPI, obtained from IClientSessionGyro.getFileUploadAPI()): links the UploadChannelProps the client created under $env to the application session's AppGyroFileUploaderService (CC-UPLOAD-A step A1, FILE-UPLOAD-DESIGN.md section 1.2 amended 2026-09-25; the API and the gate by CC-UPLOAD-U1, UPLOAD-UI-DESIGN.md edition 2 section 2).

Four roles in one object, each a translation and nothing more:

  • the IClientUploadAPI: a client's UploadRequest is reserved with the service, or refused, and answered down the channel with ONE RESERVED carrying the client's sequence number;
  • the channel's UploadChannelProps.IHandler: the client's direct reservation request, cancel and pause notice. A direct request is refused denied unless the App opened the direct route with setDirectReserve(boolean) (ruling UD-6): nothing but the limits would otherwise stand between any script of the page and the server's disk;
  • the service's IUploadClientChannel: the App's pause and resume of a file become remote events 8 and 9 (ruling row 12 of 2026-09-24);
  • per reservation, the one listener the service calls: completion, failure and cancellation become remote events 4, 5 and 6, so "done" to the client means "the App has it" (design section 1.3), and every event is passed on to the listener given with the reservation (a component) and to the listeners of this client session (UD-7).

A reservation belongs to the application session (design Q1.5) and outlives this client session: after dispose() its events are no longer sent anywhere from here - no client is listening, and the listeners of this client session are gone with it - while the transfer itself continues under whichever client holds the secrets, heard by the service's listeners.

A client session that cannot upload still has this object: without a channel (the VSViewer, a client from before the upload transport) or without a service (the upload module is not initialized), isEnabled() is false and every request is refused disabled.

Installed by ClientSessionGyro when the client session is created, through install(ClientSessionGyro), and disposed of with it.

Author:
Christopher Mindus

  • Constructor Details

    • ClientSessionUploadChannel

      public ClientSessionUploadChannel(UploadChannelProps channel, AppGyroFileUploaderService service)
      Constructor: installs this object as the channel's handler and registers it with the service, which replays every file the App holds paused.
      Parameters:
      channel - The channel the client created, or null when it created none.
      service - The application session's upload service, or null when the server has none.

  • Method Details

    • install

      public static ClientSessionUploadChannel install(ClientSessionGyro gyro)
      Installs the server side of the upload channel of a client session.
      Parameters:
      gyro - The client session gyro, its environment already received from the client.
      Returns:
      The link, never null. It is not enabled when the client created no channel under $env or the server has no upload service (the module is not initialized): every reservation is then refused disabled.

    • getChannel

      public UploadChannelProps getChannel()
      Gets the channel.
      Returns:
      The channel, or null when the client created none.

    • dispose

      public void dispose()
      Disposes of the link: the service stops pushing to it, the channel has no handler, the listeners of this client session are dropped, and no further event of this client's reservations is sent or passed on.

    • isDisposed

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

    • isEnabled

      public boolean isEnabled()
      --- IClientUploadAPI: allowing or refusing a client's request ---
      Specified by:
      isEnabled in interface IClientUploadAPI
      Returns:
      true if IClientUploadAPI.reserve(UploadRequest, IFileUploadListener) would consider a request; false answers every request refused disabled.

    • reserve

      public IUploadReservation reserve(UploadRequest request, IFileUploadListener listener)
      Description copied from interface: IClientUploadAPI
      Reserves the files of a client's request: the declared sizes against the quotas, the declared types against $upload.types and the request's own types, the count against the maximum; answers the client on the channel with ONE RESERVED carrying the request's sequence number, accepted or refused; and returns the reservation.
      Specified by:
      reserve in interface IClientUploadAPI
      Parameters:
      request - The client's request, not yet answered.
      listener - A listener for this reservation only, or null. It is called beside the listeners of this client session, on the application session's worker, and hears nothing more once this client session has ended or the listener has been removed with IClientUploadAPI.removeListener(IFileUploadListener).
      Returns:
      The reservation, accepted or refused; never null. A reservation refused as a whole holds nothing and its files are all UploadState.REFUSED.

    • refuse

      public void refuse(UploadRequest request, String reason)
      Description copied from interface: IClientUploadAPI
      Refuses a client's request: answers the client ONE RESERVED, refused, carrying the request's sequence number and the reason. Nothing is reserved.
      Specified by:
      refuse in interface IClientUploadAPI
      Parameters:
      request - The client's request, not yet answered.
      reason - The reason the client is told, a short code such as denied; null or empty for denied.

    • addListener

      public boolean addListener(IFileUploadListener listener)
      Description copied from interface: IClientUploadAPI
      Adds a listener for every reservation made through this client session from now on.

      An object that is also the listener of a reservation, or a listener of the application session's service, hears each event once per level.

      Specified by:
      addListener in interface IClientUploadAPI
      Parameters:
      listener - The listener.
      Returns:
      true if added, false if already present or this client session cannot upload.

    • removeListener

      public boolean removeListener(IFileUploadListener listener)
      Description copied from interface: IClientUploadAPI
      Removes a listener from this client session: as a listener added with IClientUploadAPI.addListener(IFileUploadListener), and as the listener of every reservation it was given to in IClientUploadAPI.reserve(UploadRequest, IFileUploadListener). A component that is disposed of removes itself this way; its transfers continue.
      Specified by:
      removeListener in interface IClientUploadAPI
      Parameters:
      listener - The listener.
      Returns:
      true if it was removed from at least one place, false if it was nowhere.

    • getReservations

      public List<? extends IUploadReservation> getReservations()
      Description copied from interface: IClientUploadAPI
      Gets the live reservations made through this client session.
      Specified by:
      getReservations in interface IClientUploadAPI
      Returns:
      The reservations, never null; a snapshot.

    • setDirectReserve

      public void setDirectReserve(boolean allowed)
      Description copied from interface: IClientUploadAPI
      Allows or forbids the direct route: a RESERVE sent on the upload channel by the client's own script, with no component and no App code in between. Forbidden by default (UD-6): such a request is then refused denied, since nothing has allowed it. An App whose own client code uploads through the session's uploader opts in here, and so accepts every request the limits permit.
      Specified by:
      setDirectReserve in interface IClientUploadAPI
      Parameters:
      allowed - true to reserve direct requests, false to refuse them.

    • isDirectReserve

      public boolean isDirectReserve()
      Description copied from interface: IClientUploadAPI
      Checks if the direct route is allowed.
      Specified by:
      isDirectReserve in interface IClientUploadAPI
      Returns:
      true if a direct RESERVE is reserved, false (the default) if refused.

    • onReserve

      public void onReserve(UploadChannelProps channel, UploadRequest request)
      The client's direct reservation request: refused disabled when this client session cannot upload, reserved when the App opened the direct route, refused denied otherwise (UD-6).
      Specified by:
      onReserve in interface UploadChannelProps.IHandler
      Parameters:
      channel - The channel the request came in on.
      request - The request, decoded and not yet answered; its source is null.

    • onCancel

      public void onCancel(String reservationID, int fileIndex, String reason)
      Description copied from interface: UploadChannelProps.IHandler
      The client cancels a file or a reservation.
      Specified by:
      onCancel in interface UploadChannelProps.IHandler
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index, or -1 for the whole reservation.
      reason - The reason, never null.

    • onState

      public void onState(String reservationID, int fileIndex, boolean paused, String reason)
      Description copied from interface: UploadChannelProps.IHandler
      The client's own pause or resume notice (rows 11 and 13).
      Specified by:
      onState in interface UploadChannelProps.IHandler
      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 reason of a pause, empty for a resume.

    • onFilePaused

      public void onFilePaused(String reservationID, int fileIndex, String reason)
      --- IUploadClientChannel: the App's pause and resume ---
      Specified by:
      onFilePaused in interface IUploadClientChannel
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index.
      reason - The reason the App gave, never null.

    • onFileResumed

      public void onFileResumed(String reservationID, int fileIndex)
      Description copied from interface: IUploadClientChannel
      The App resumed a file: the client may send its chunks again, starting at the acknowledged offset it already knows or learns with a status query.
      Specified by:
      onFileResumed in interface IUploadClientChannel
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index.