Package com.vaadin.flow.server.streams

Class TransferProgressAwareHandler<T,R extends TransferProgressAwareHandler>

java.lang.Object
com.vaadin.flow.server.streams.TransferProgressAwareHandler<T,R>
Type Parameters:
T - type of transfer event, e.g. DownloadHandler
R - type of the subclass implementing this abstract class, needed for revealing a proper type when you chain the methods
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AbstractDownloadHandler, AbstractFileUploadHandler, InMemoryUploadHandler
public abstract class TransferProgressAwareHandler<T,R extends TransferProgressAwareHandler> extends Object implements Serializable
Abstract class for common methods used in pre-made transfer progress handlers.
See Also:

  • Constructor Details

    • TransferProgressAwareHandler

      public TransferProgressAwareHandler()

  • Method Details

    • getTransferContext

      protected abstract TransferContext getTransferContext(T transferEvent)
      This method is used to get the transfer context from the transfer events (e.g. DownloadEvent).
      Parameters:
      transferEvent - the transfer event
      Returns:
      the transfer context

    • addTransferProgressListener

      protected Registration addTransferProgressListener(TransferProgressListener listener)
      Adds a listener to be notified of data transfer progress events, such as:

      The calls of the given listener's methods are wrapped by the UI.access(Command) to send UI changes defined here asynchronously when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Custom download/upload handler implementations can change this method to be public or use it in handler's constructor.

      Parameters:
      listener - progress listener to be added to this handler
      Returns:
      a Registration object that can be used to remove the added listener

    • whenStart

      public R whenStart(SerializableRunnable startHandler)
      Adds a listener to be notified when the transfer starts.

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Parameters:
      startHandler - the handler to be called when the transfer starts
      Returns:
      this instance for method chaining

    • whenStart

      public R whenStart(SerializableConsumer<TransferContext> startHandler)
      Adds a listener to be notified when the transfer starts that receives the transfer context as input.

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Parameters:
      startHandler - the handler to be called when the transfer starts
      Returns:
      this instance for method chaining

    • onProgress

      public R onProgress(SerializableTriConsumer<TransferContext,Long,Long> progressHandler, long progressIntervalInBytes)
      Adds a listener to be notified of transfer progress with giving the transfer context object and with the given interval.

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Parameters:
      progressHandler - the handler to be called with the transfer context, current and total bytes
      progressIntervalInBytes - the interval in bytes for reporting progress
      Returns:
      this instance for method chaining

    • onProgress

      public R onProgress(SerializableTriConsumer<TransferContext,Long,Long> progressHandler)
      Adds a listener to be notified of transfer progress with giving the transfer context object and with the default progress interval.

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Parameters:
      progressHandler - the handler to be called with the transfer context, current and total bytes
      Returns:
      this instance for method chaining

    • onProgress

      public R onProgress(SerializableBiConsumer<Long,Long> progressHandler, long progressIntervalInBytes)
      Adds a listener to be notified of transfer progress with the given interval.

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Parameters:
      progressHandler - the handler to be called with the current and total bytes
      progressIntervalInBytes - the interval in bytes for reporting progress
      Returns:
      this instance for method chaining

    • onProgress

      public R onProgress(SerializableBiConsumer<Long,Long> progressHandler)
      Adds a listener to be notified of transfer progress with a default interval.

      The first long parameter is the current number of bytes transferred, and the second is the total number of bytes.

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      The default progress report internal is 65536 bytes. To change it, use onProgress(SerializableBiConsumer, long).

      Parameters:
      progressHandler - the handler to be called with the current and total bytes
      Returns:
      this instance for method chaining

    • whenComplete

      public R whenComplete(SerializableConsumer<Boolean> completeOrTerminateHandler)
      Adds a listener to be notified when the transfer is completed successfully or with an error.

      Gives a Boolean indicating whether the transfer was completed successfully (true) or not (false).

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Parameters:
      completeOrTerminateHandler - the handler to be called when the transfer is completed
      Returns:
      this instance for method chaining

    • whenComplete

      public R whenComplete(SerializableBiConsumer<TransferContext,Boolean> completeOrTerminateHandler)
      Adds a listener to be notified when the transfer is completed successfully or with an error with the transfer context object given as an input.

      Gives a Boolean indicating whether the transfer was completed successfully (true) or not (false) and transfer context to obtain more meta-data.

      The call of the given callback is wrapped by the UI.access(Command) to send UI changes defined here when the download or upload request is being handled. This needs Push to be enabled in the application to properly send the UI changes to client.

      Parameters:
      completeOrTerminateHandler - the handler to be called when the transfer is completed
      Returns:
      this instance for method chaining

    • getListeners

      protected List<TransferProgressListener> getListeners()
      Get the listeners that are registered to this handler.

      For the custom data transfer implementation, one may need to notify listeners manually. This method can be used like getListeners().forEach(listener -> listener.onStart(getTransferContext(event))).

      The listeners are kept in order of registration.

      Returns:
      a list of listeners that are registered to this handler

    • notifyError

      protected void notifyError(T transferEvent, IOException ioe)
      Notifies all registered listeners about an error that occurred during a data transfer operation.

      Custom download/upload handler implementations can use this method to notify listeners in the catch block, e.g.: 

       try () {
     // handler download/upload request
 } catch (IOException ioe) {
     // process the error
     notifyError(event, ioe);
     throw ioe;
 }
      Parameters:
      transferEvent - the meta-data associated with the operation where the error occurred
      ioe - the exception that describes the error