Package org.yamcs.filetransfer

Interface FileTransferService

All Superinterfaces:
FileListingService, com.google.common.util.concurrent.Service, YamcsService
All Known Implementing Classes:
CfdpService
public interface FileTransferService extends YamcsService, FileListingService
The file transfer service defines an interface for implementing file transfers.

The service provides file transfer operations between named "entities".

The entity term is borrowed from CFDP (CCSDS File Delivery Protocol) and it can mean anything for a particular implementation. For example it could mean a host in a traditional TCP/IP network.

Each file transfer is identified by a unique 64 bit identifier.

  • Method Details

    • getLocalEntities

      List<EntityInfo> getLocalEntities()
      Get the list of configured local entities. These contain the {@code source) used in the {@link #startUpload(String, Bucket, String, String, String, TransferOptions)} call. <p> Can return an empty list if there is only one unnamed entity. @return

    • getRemoteEntities

      List<EntityInfo> getRemoteEntities()
      Get the list of configured remote entity. These contain the destination used in the startUpload(String, Bucket, String, String, String, TransferOptions) call.

      Can return an empty list if there is only one unnamed remote entity.

      Returns:

    • getCapabilities

      FileTransferCapabilities getCapabilities()
      Get the capabilities supported by this service.

      The capabilities are used by the yamcs-web to enable/disable some options.

      Returns:

    • getFileTransferOptions

      default List<FileTransferOption> getFileTransferOptions()
      Get configured options for the file transfers
      Returns:

    • startUpload

      FileTransfer startUpload(String sourceEntity, Bucket bucket, String objectName, String destinationEntity, String destinationPath, TransferOptions options) throws IOException
      Start a file upload.
      Parameters:
      sourceEntity - the source (local) entity. Can be null if the service supports only one unnamed source entity.
      bucket - the bucket containing the object to be transferred.
      objectName - the object name to be transferred.
      destinationEntity - the destination (remote) entity. Can be null if the service supports only one unnamed destination entity.
      destinationPath - the path on the destination where the file will be uploaded. Depending on the implementation this can be the path of a directory in which case the objectName will be used as a destination file name or can be the name of a (non-existent) file which will then be used as the destination file. if the destinationPath is null, then the objectName will be used as the name at the destination.
      options - transfer options.
      Returns:
      Throws:
      IOException - if there was a problem retrieving the object from the bucket.
      InvalidRequestException - thrown if the request is invalid; possible reasons:
      • object does not exist in the bucket
      • the source or destination entities are not valid
      • the transfer options are invalid
      • other service specific error.

    • startDownload

      FileTransfer startDownload(String sourceEntity, String sourcePath, String destinationEntity, Bucket bucket, String objectName, TransferOptions options) throws IOException, InvalidRequestException
      Start a file download.
      Parameters:
      sourceEntity - the source (remote) entity. Can be null if the service supports only one unnamed source entity.
      sourcePath - the path on the source representing the file to be transferred.
      destinationEntity - the destination (local) entity. Can be null if the service supports only one unnamed destination entity.
      bucket - the bucket where the file will be stored.
      objectName - the object name where the file will be stored.
      options - transfer options.
      Returns:
      Throws:
      IOException - if there was a problem retrieving the object from the bucket.
      InvalidRequestException - thrown if the request is invalid; possible reasons:
      • the source or destination entities are not valid
      • the transfer options are invalid
      • download operation not supported or cannot be triggered by this call (most systems will have a telecommand to trigger a download)
      • other service specific error.

    • getTransfers

      List<FileTransfer> getTransfers()
      Get the list of ongoing or past transfers.
      Returns:
      the list of transfers

    • getFileTransfer

      FileTransfer getFileTransfer(long id)
      Get the file transfer with the given identifier.
      Parameters:
      id -
      Returns:

    • pause

      void pause(FileTransfer transfer)
      Pause the file transfer.

      If the transfer is already paused, this operation has no effect.

      Parameters:
      transfer - the transfer to be paused.
      Throws:
      UnsupportedOperationException - if the pause operation is not supported.

    • resume

      void resume(FileTransfer transfer)
      Resume the file transfer.

      If the transfer is not paused, this call has no effect.

      Parameters:
      transfer - the transfer to be resumed.
      Throws:
      UnsupportedOperationException - if the resume operation is not supported.

    • cancel

      void cancel(FileTransfer transfer)
      Cancel the file transfer.
      Parameters:
      transfer -
      Throws:
      UnsupportedOperationException - if the cancel operation is not supported.

    • registerTransferMonitor

      void registerTransferMonitor(TransferMonitor listener)
      Register a monitor to be called each time a file transfer is started or changes state.
      Parameters:
      listener -

    • unregisterTransferMonitor

      void unregisterTransferMonitor(TransferMonitor listener)
      Unregister the monitor. If the monitor was not registered, this call has no effect.
      Parameters:
      listener -

    • init

      default void init(String yamcsInstance, String serviceName, YConfiguration config) throws InitException
      Description copied from interface: YamcsService
      Initialize this service. This is called before the service is started. All operations should finish fast.
      Specified by:
      init in interface FileListingService
      Specified by:
      init in interface YamcsService
      Parameters:
      yamcsInstance - The yamcs instance, or null if this is a global service.
      serviceName - The service name.
      config - The configured arguments for this service. If YamcsService.getSpec() is implemented then this contains the arguments after being validated (including any defaults).
      Throws:
      InitException - When something goes wrong during the execution of this method.