Class UploadChannelProps

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.upload.UploadChannelProps
All Implemented Interfaces:
EventListener, IGProp<GProp<?>[]>, IPropCnr, Cloneable
public class UploadChannelProps extends PropCnr
The file upload channel of one client session: the container under $env that carries the upload calls between the client's FileUploader and the server's upload service (FILE-UPLOAD-DESIGN.md section 1.2, amended 2026-09-25: ruling row 10 of 2026-09-24 moved the JS sender from the component to the client session; built by CC-UPLOAD-A step A1).

Created by the client, as PushChannelProps is: iz/EnvProps.js adds it to $env when iz/upload/UploadChannelProps.js is loaded, which the application, Design Viewer and Designer pages do and the VSViewer does not, so that its absence means "this session cannot upload". The server never predefines it, so EnvProps.onRemoteRootCreated() never makes it private. of(EnvProps) finds it. The server side of the channel - the link to the application session's upload service - is a UploadChannelProps.IHandler installed by com.iizix.server when the client session is created; without one, a reservation is refused disabled.

Calls are remote events, the ids of the design's section 1.2, repeated as literals with a comment in iz/upload/UploadChannelProps.js. Client to server: REMOTE_RESERVE (1), REMOTE_CANCEL (3) and REMOTE_STATE (7). Server to client: REMOTE_RESERVED (2), REMOTE_FILE_DONE (4), REMOTE_FILE_FAILED (5), REMOTE_CANCELLED (6), REMOTE_PAUSED (8) and REMOTE_RESUMED (9). Every switch is on getLocalID(): a remote event's getEventID() is always GEvent.REMOTE. A reservation request carries the client's sequence number P_SEQ and is answered by a RESERVED carrying it back.

A request is an UploadRequest (CC-UPLOAD-U1): decodeRequest(PropCnr) builds it from the parameters of a client's remote event - this channel's RESERVE, or the request event of a component, whose payload is the same - and nothing else can build one. encodeReserve(int, List, boolean, String) is the encoder, the counterpart of the client's. A RESERVE sent directly on this channel is reserved only when the App opened the direct route (IClientUploadAPI.setDirectReserve); otherwise it is answered refused REASON_DENIED.

Threads. A client event arrives on the client session's worker and the handler is called there, at once. The send methods may be called on any thread - the App's worker for a listener callback, a timer's for a cancellation - since the flush to the client is posted to the session's worker by the property chain, as for every change under the root.

Author:
Christopher Mindus

  • Field Details

  • Constructor Details

    • UploadChannelProps

      public UploadChannelProps()
      Creates the channel without a name.

    • UploadChannelProps

      public UploadChannelProps(Atom atom)
      Creates the channel with a name.
      Parameters:
      atom - The atom name, normally ATOM.

  • Method Details

    • clone

      public UploadChannelProps clone()
      Clones the channel: the handler is not cloned.
      Overrides:
      clone in class PropCnr

    • shouldSerializeToXML

      protected boolean shouldSerializeToXML(int programType)
      The channel is never written to XML.
      Overrides:
      shouldSerializeToXML in class GProp<GProp<?>[]>
      Parameters:
      programType - From PropFactory.getProgramType().
      Returns:
      false.

    • of

      public static UploadChannelProps of(EnvProps env)
      Finds the channel of a session.
      Parameters:
      env - The session's environment properties, or null.
      Returns:
      The channel the client created under $env, or null when the session has none: a VSViewer session, or a client built before A1.

    • setHandler

      public void setHandler(UploadChannelProps.IHandler handler)
      Installs the server side of the channel, or removes it.
      Parameters:
      handler - The handler, or null for none.

    • getHandler

      public UploadChannelProps.IHandler getHandler()
      Gets the installed server side.
      Returns:
      The handler, or null for none.

    • sendReserved

      public boolean sendReserved(int seq, IUploadReservation reservation)
      Answers a reservation request: REMOTE_RESERVED built from the reservation the service minted, accepted or refused.
      Parameters:
      seq - The client's sequence number.
      reservation - The reservation.
      Returns:
      true when sent, false when the channel is disposed of.
      Throws:
      NullPointerException - If the reservation is null.

    • sendFileDone

      public boolean sendFileDone(String reservationID, int fileIndex, String verifiedType, long size)
      Tells the client a file is verified and the App has it: REMOTE_FILE_DONE.
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index.
      verifiedType - The verified type, or null or empty for none.
      size - The size as measured, in bytes.
      Returns:
      true when sent, false when the channel is disposed of.

    • sendFileFailed

      public boolean sendFileFailed(String reservationID, int fileIndex, String reason)
      Tells the client a file failed: REMOTE_FILE_FAILED.
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index.
      reason - The reason, never null.
      Returns:
      true when sent, false when the channel is disposed of.

    • sendCancelled

      public boolean sendCancelled(String reservationID, int fileIndex, String reason)
      Tells the client a file was cancelled by the server side: REMOTE_CANCELLED.
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index.
      reason - The reason, never null.
      Returns:
      true when sent, false when the channel is disposed of.

    • sendPaused

      public boolean sendPaused(String reservationID, int fileIndex, String reason)
      Tells the client the App paused a file: REMOTE_PAUSED.
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index.
      reason - The App's reason, never null.
      Returns:
      true when sent, false when the channel is disposed of.

    • sendResumed

      public boolean sendResumed(String reservationID, int fileIndex)
      Tells the client the App no longer holds a file: REMOTE_RESUMED.
      Parameters:
      reservationID - The reservation ID.
      fileIndex - The file index.
      Returns:
      true when sent, false when the channel is disposed of.

    • onRemoteEvent

      public void onRemoteEvent(RemoteEvent event)
      Called when a remote property event should be processed by this property: the client's reservation request, cancel and state notice are decoded and handed to the installed UploadChannelProps.IHandler. Switches on getLocalID(), never on getEventID().

      A reservation request with no handler installed is answered refused REASON_DISABLED; one the channel cannot read is answered refused REASON_PROTOCOL and logged, so the client never waits for an answer that will not come.

      Specified by:
      onRemoteEvent in interface IGProp<GProp<?>[]>
      Overrides:
      onRemoteEvent in class GProp<GProp<?>[]>
      Parameters:
      event - The remote event.

    • decodeRequest

      public static UploadRequest decodeRequest(PropCnr params)
      Decodes a direct reservation request; see decodeRequest(PropCnr,GProp).
      Parameters:
      params - The parameters of the client's remote event.
      Returns:
      The request, with no source, not yet answered.
      Throws:
      IllegalArgumentException - If the request is malformed.

    • decodeRequest

      public static UploadRequest decodeRequest(PropCnr params, GProp<?> source)
      Decodes a client's reservation request from the parameters of its remote event: this channel's REMOTE_RESERVE, or the request event of a component, whose payload the client builds with the same encoder. This is the only way to an UploadRequest.
      Parameters:
      params - The parameters of the client's remote event.
      source - The property the event came in on - the requesting component - or null for a direct RESERVE on the channel.
      Returns:
      The request, not yet answered.
      Throws:
      IllegalArgumentException - If the request is malformed: no parameters, no file, a missing file container, a file the service would not take as declared (an empty name, a negative size, an unknown compression), or types longer than MAX_TYPES_LENGTH.

    • encodeReserve

      public static PropCnr encodeReserve(int seq, List<UploadFileRequest> files, boolean notices, String types)
      Encodes a reservation request as the client does: the counterpart of the client's UploadChannelProps.encodeReserve in iz/upload/UploadChannelProps.js, member for member, so that what one side writes the other reads. decodeRequest(PropCnr) reads the result back.
      Parameters:
      seq - The sequence number.
      files - The files, in order.
      notices - The automatic failure notice switch.
      types - The types the requester accepts, null or empty for none: the member is then left out, as the client leaves it out.
      Returns:
      The parameters of a REMOTE_RESERVE.
      Throws:
      NullPointerException - If the files are null.

    • sendRefused

      public boolean sendRefused(int seq, String reason)
      Answers a reservation request refused as a whole, without a reservation: the handler's answer when the service could not be asked at all.
      Parameters:
      seq - The client's sequence number.
      reason - The refusal reason, e.g. REASON_ERROR.
      Returns:
      true when sent, false when the channel is disposed of.

    • onPropDispose

      protected void onPropDispose()
      Called when the channel is disposed of, with its root: the server side is removed.
      Overrides:
      onPropDispose in class PropCnr