Package fr.gouv.vitam.storage.driver

# Interface Connection

All Superinterfaces:
  `AutoCloseable`

All Known Implementing Classes:
  `AbstractConnection`, `ConnectionImpl`, `FakeDriverImpl.FakeConnectionImpl`

public interface Connection extends AutoCloseable
Represents a connection to the distant storage offer service that is provided by the driver when calling the connect method:

`myDriver.connect(serviceUrl, parameters);`

The connection implementation is driver dependent but MUST hold enough informations/parameters/configurations to be able to contact the distant offer service without the need to give additional connection related parameters on further request done with this connection. In some cases it may be considered as a "session". Note: Connection extends `AutoCloseable` so the connection implementation MUST provide a close() method which responsibility is to cleanly close and remove.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `StorageBulkPutResult`
  `bulkPutObjects(StorageBulkPutRequest request)`
  Bulk put object files into the storage offer.
  `Map<String,AccessRequestStatus>`
  `checkAccessRequestStatuses(List<String> accessRequestIds, int tenant, boolean adminCrossTenantAccessRequestAllowed)`
  Check access request statuses of asynchronous offer.
  `boolean`
  `checkObjectAvailability(StorageCheckObjectAvailabilityRequest request)`
  Check immediate availability of objects from asynchronous storage offer.
  `void`
  `close()`
  Override AutoCloseable implementation to specify the exception
  `String`
  `createAccessRequest(StorageAccessRequestCreationRequest request)`
  Create an access request for retrieving objects from asynchronous storage offer.
  `StorageBulkMetadataResult`
  `getBulkMetadata(StorageGetBulkMetadataRequest request)`
  Bulk get metadata of objects
  `StorageMetadataResult`
  `getMetadatas(StorageGetMetadataRequest request)`
  Get metadata of object
  `StorageGetResult`
  `getObject(StorageObjectRequest request)`
  Retrieve an object from the storage offer based on criterias defined in request argument.
  `RequestResponse<OfferLog>`
  `getOfferLogs(StorageOfferLogRequest request)`
  Get a listing of offer logs on a container type
  `StorageCapacityResult`
  `getStorageCapacity(Integer tenantId)`
  Retrieve the remaining storage capacity available on the distant offer.
  `jakarta.ws.rs.core.Response`
  `launchOfferLogCompaction(VitamContext vitamContext)`
  launch Offer Log Compaction
  `CloseableIterator<ObjectEntry>`
  `listObjects(StorageListRequest request)`
  List object on a container type
  `boolean`
  `objectExistsInOffer(StorageObjectRequest request)`
  Check if an object is present in the offer
  `StoragePutResult`
  `putObject(StoragePutRequest request)`
  Put the object file into the storage offer based on criteria defined in request argument and underlying connection parameters.
  `void`
  `removeAccessRequest(String accessRequestId, int tenant, boolean adminCrossTenantAccessRequestAllowed)`
  Removes (cancel / delete) and access request for an asynchronous offer.
  `StorageRemoveResult`
  `removeObject(StorageRemoveRequest request)`
  Delete an object on the distant storage offer.

- ## Method Details

  - ### getStorageCapacity

    StorageCapacityResult getStorageCapacity(Integer tenantId) throws StorageDriverPreconditionFailedException, StorageDriverNotFoundException, StorageDriverException
    Retrieve the remaining storage capacity available on the distant offer. Return values MUST in bytes
    Parameters:
      `tenantId` - the tenant id needed to get storage capacity
    Returns:
      the usable and used space in bytes and a remind of the given tenantId
    Throws:
      `StorageDriverPreconditionFailedException` - if a bad request is encountered
      `StorageDriverNotFoundException` - if container is not found
      `StorageDriverException` - if any problem occurs during request

  - ### getObject

    StorageGetResult getObject(StorageObjectRequest request) throws StorageDriverException
    Retrieve an object from the storage offer based on criterias defined in request argument.
    Parameters:
      `request` - the request to send. It contains informations needed to retrieve a given object.
    Returns:
      a result that may contains metadatas as well as the binary file
    Throws:
      `StorageDriverException` - if any problem occurs during request
      `IllegalArgumentException` - if request is wrong

  - ### createAccessRequest

    String createAccessRequest(StorageAccessRequestCreationRequest request) throws StorageDriverException
    Create an access request for retrieving objects from asynchronous storage offer.
    Parameters:
      `request` - the request to send. It contains information needed to prepare a given object.
    Returns:
      an AccessRequestId that can be used to check the status of the AccessRequest, and to remove it
    Throws:
      `StorageDriverException` - if any problem occurs during request
      `IllegalArgumentException` - if request is wrong

  - ### checkAccessRequestStatuses

    Map<String,AccessRequestStatus> checkAccessRequestStatuses(List<String> accessRequestIds, int tenant, boolean adminCrossTenantAccessRequestAllowed) throws StorageDriverException
    Check access request statuses of asynchronous offer.
    Parameters:
      `accessRequestIds` - the accessRequestIds whose status is to be checked
      `tenant` - the tenant Id
      `adminCrossTenantAccessRequestAllowed` - when `true`, access to access requests of other tenants is allowed from Admin tenant
    Returns:
      a Map of `AccessRequestStatus` by access request Id
    Throws:
      `StorageDriverException` - if any problem occurs during request

  - ### removeAccessRequest

    void removeAccessRequest(String accessRequestId, int tenant, boolean adminCrossTenantAccessRequestAllowed) throws StorageDriverException
    Removes (cancel / delete) and access request for an asynchronous offer. Does nothing is access request id does not exist (idempotency)
    Parameters:
      `accessRequestId` - the accessRequestId to remove
      `tenant` - the tenant Id
      `adminCrossTenantAccessRequestAllowed` - when `true`, removing access requests of other tenants is allowed from Admin tenant
    Throws:
      `StorageDriverException` - if any problem occurs during request

  - ### checkObjectAvailability

    boolean checkObjectAvailability(StorageCheckObjectAvailabilityRequest request) throws StorageDriverException
    Check immediate availability of objects from asynchronous storage offer.
    Parameters:
      `request` - the request to send. It contains information needed to check object availability.
    Returns:
      `true` if ALL objects are available, otherwise `false`.
    Throws:
      `StorageDriverException` - if any problem occurs during request
      `IllegalArgumentException` - if request is wrong

  - ### putObject

    StoragePutResult putObject(StoragePutRequest request) throws StorageDriverException
    Put the object file into the storage offer based on criteria defined in request argument and underlying connection parameters.
    Parameters:
      `request` - the request to send. It may contain information needed to store the file.
    Returns:
      a result that may contain metadata or statistics about the object put operation.
    Throws:
      `StorageDriverException` - if any problem occurs during request

  - ### bulkPutObjects

    StorageBulkPutResult bulkPutObjects(StorageBulkPutRequest request) throws StorageDriverException
    Bulk put object files into the storage offer.
    Throws:
      `StorageDriverException` - if any problem occurs during request

  - ### removeObject

    StorageRemoveResult removeObject(StorageRemoveRequest request) throws StorageDriverException
    Delete an object on the distant storage offer.
    Parameters:
      `request` - the request to send, it contains information needed to delete an object on the distant store
    Returns:
      a result that may contains metadatas or statistics about the object removal operation.
    Throws:
      `StorageDriverException` - if any problem occurs during request

  - ### objectExistsInOffer

    boolean objectExistsInOffer(StorageObjectRequest request) throws StorageDriverException
    Check if an object is present in the offer
    Parameters:
      `request` - the request to send. It contains informations needed to retrieve a given object.
    Returns:
      true if exists, else false
    Throws:
      `StorageDriverException` - if any problem occurs during request

  - ### getMetadatas

    StorageMetadataResult getMetadatas(StorageGetMetadataRequest request) throws StorageDriverException
    Get metadata of object
    Parameters:
      `request` -
    Returns:
      a result that may contain information about the storage metadata
    Throws:
      `StorageDriverException`

  - ### getBulkMetadata

    StorageBulkMetadataResult getBulkMetadata(StorageGetBulkMetadataRequest request) throws StorageDriverException, InvalidParseOperationException
    Bulk get metadata of objects
    Parameters:
      `request` -
    Returns:
      a result that may contain information about the storage metadata
    Throws:
      `StorageDriverException`
      `InvalidParseOperationException`

  - ### listObjects

    CloseableIterator<ObjectEntry> listObjects(StorageListRequest request) throws StorageDriverException, StorageDriverNotFoundException
    List object on a container type
    Parameters:
      `request` - the request contains data needed to list container type
    Returns:
      an iterator with each object metadata
    Throws:
      `StorageDriverException`
      `StorageDriverNotFoundException`

  - ### getOfferLogs

    RequestResponse<OfferLog> getOfferLogs(StorageOfferLogRequest request) throws StorageDriverException
    Get a listing of offer logs on a container type
    Parameters:
      `request` - the request contains data needed to retrieve the listing of the container
    Returns:
      the listing of last objects save according to the request
    Throws:
      `StorageDriverException` - to be thrown in case of any driver exception

  - ### launchOfferLogCompaction

    jakarta.ws.rs.core.Response launchOfferLogCompaction(VitamContext vitamContext) throws StorageDriverException
    launch Offer Log Compaction
    Returns:
      RequestResponse
    Throws:
      `StorageDriverException` - to be thrown in case of any driver exception

  - ### close

    void close() throws StorageDriverException
    Override AutoCloseable implementation to specify the exception
    Specified by:
      `close` in interface `AutoCloseable`
    Throws:
      `StorageDriverException` - to be thrown in case of any driver exception