Interface IClientUploadAPI

All Known Implementing Classes:
ClientSessionUploadChannel
public interface IClientUploadAPI
The file upload API of one client session: where a client's request to upload files is allowed or refused, and where its reservations are observed (design UPLOAD-UI-DESIGN.md edition 2, section 2; rulings UD-3 to UD-7; built by CC-UPLOAD-U1).

Obtained from IClientSessionGyro.getFileUploadAPI(). Declared in core, implemented by the server on the upload channel the client created. The client session is the one object that knows both sides: the application session's IFileUploadService, which holds the limits and the staged files, and the client that will send the bytes.

A reservation answers a client's request and nothing else (UD-5). The client declares its files - name, type and size each - in an UploadRequest, which only the channel's decoder can build. Whoever receives the request decides: reserve(UploadRequest, IFileUploadListener) reserves the files against the service's limits and tells the client, refuse(UploadRequest, String) tells the client no. Either way the client gets ONE answer carrying its sequence number. The returned reservation's IUploadReservation.getPath() is the path the client posts to, relative, which the client resolves against the server it is connected to; the per-file secrets travel to the client on the channel only.

Three levels of listener hear a reservation (UD-7), every one on the application session's worker: the listener given to reserve(UploadRequest, IFileUploadListener) hears that reservation only, the listeners added here hear every reservation of this client session, and the listeners of IFileUploadService.addListener(IFileUploadListener) hear every reservation of the application session. An object registered at two levels hears each event twice.

The lifetime is the client session's. A reservation belongs to the application session and continues when this client session ends; from then on the listeners of the first two levels hear nothing more of it, and the service's listeners hear the rest.

Author:
Christopher Mindus

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    addListener(IFileUploadListener listener)
    Adds a listener for every reservation made through this client session from now on.
    List<? extends IUploadReservation>
    getReservations()
    Gets the live reservations made through this client session.
    boolean
    isDirectReserve()
    Checks if the direct route is allowed.
    boolean
    isEnabled()
    Checks if this client session can upload now: the client created the upload channel (its page loaded the upload transport), the server has the upload service, and uploads are allowed ($upload.allow).
    void
    refuse(UploadRequest request, String reason)
    Refuses a client's request: answers the client ONE RESERVED, refused, carrying the request's sequence number and the reason.
    boolean
    removeListener(IFileUploadListener listener)
    Removes a listener from this client session: as a listener added with addListener(IFileUploadListener), and as the listener of every reservation it was given to in reserve(UploadRequest, IFileUploadListener).
    IUploadReservation
    reserve(UploadRequest request, IFileUploadListener listener)
    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.
    void
    setDirectReserve(boolean allowed)
    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.

  • Method Details

    • isEnabled

      boolean isEnabled()
      Checks if this client session can upload now: the client created the upload channel (its page loaded the upload transport), the server has the upload service, and uploads are allowed ($upload.allow).
      Returns:
      true if reserve(UploadRequest, IFileUploadListener) would consider a request; false answers every request refused disabled.

    • reserve

      IUploadReservation reserve(UploadRequest request, IFileUploadListener listener)
      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.
      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 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.
      Throws:
      NullPointerException - If the request is null.
      IllegalStateException - If the request has already been answered.

    • refuse

      void refuse(UploadRequest request, String reason)
      Refuses a client's request: answers the client ONE RESERVED, refused, carrying the request's sequence number and the reason. Nothing is reserved.
      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.
      Throws:
      NullPointerException - If the request is null.
      IllegalStateException - If the request has already been answered.

    • addListener

      boolean addListener(IFileUploadListener listener)
      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.

      Parameters:
      listener - The listener.
      Returns:
      true if added, false if already present or this client session cannot upload.
      Throws:
      NullPointerException - If the listener is null.

    • removeListener

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

    • getReservations

      List<? extends IUploadReservation> getReservations()
      Gets the live reservations made through this client session.
      Returns:
      The reservations, never null; a snapshot.

    • setDirectReserve

      void setDirectReserve(boolean allowed)
      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.
      Parameters:
      allowed - true to reserve direct requests, false to refuse them.

    • isDirectReserve

      boolean isDirectReserve()
      Checks if the direct route is allowed.
      Returns:
      true if a direct RESERVE is reserved, false (the default) if refused.