net.snowflake.client.jdbc.cloud.storage

## Class SnowflakeS3Client

- java.lang.Object
- - net.snowflake.client.jdbc.cloud.storage.SnowflakeS3Client

All Implemented Interfaces:
  SnowflakeStorageClient

    public class SnowflakeS3Client
    extends Object
    implements SnowflakeStorageClient

Wrapper around AmazonS3Client.

Author:
  ffunke

### Constructor Summary

Constructors
Constructor and Description
`SnowflakeS3Client(Map stageCredentials, com.amazonaws.ClientConfiguration clientConfig, net.snowflake.common.core.RemoteStoreFileEncryptionMaterial encMat, String stageRegion)`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addDigestMetadata(StorageObjectMetadata meta, String digest)` Adds digest metadata to the StorageObjectMetadata object
`void` `addEncryptionMetadata(StorageObjectMetadata meta, MatDesc matDesc, byte[] ivData, byte[] encKeK, long contentLength)` Adds encryption metadata to the StorageObjectMetadata object
`void` `download(SFSession connection, String command, String localLocation, String destFileName, int parallelism, String remoteStorageLocation, String stageFilePath, String stageRegion)` Download a file from S3.
`String` `getDigestMetadata(StorageObjectMetadata meta)` Gets digest metadata to the StorageObjectMetadata object
`int` `getEncryptionKeySize()`
`String` `getMatdescKey()` Returns the material descriptor key
`int` `getMaxRetries()`
`StorageObjectMetadata` `getObjectMetadata(String remoteStorageLocation, String prefix)` Returns the metadata properties for a remote storage object
`int` `getRetryBackoffMaxExponent()` Returns the max exponent for multiplying backoff with the power of 2, the value of 4 will give us 16secs as the max number of time to sleep before retry
`int` `getRetryBackoffMin()`
`void` `handleStorageException(Exception ex, int retryCount, String operation, SFSession connection, String command)` Handles exceptions thrown by the remote storage provider
`boolean` `isEncrypting()`
`StorageObjectSummaryCollection` `listObjects(String remoteStorageLocation, String prefix)` For a set of remote storage objects under a remote location and a given prefix/path returns their properties wrapped in ObjectSummary objects
`void` `renew(Map stageCredentials)` Renew the S3 client with fresh AWS credentials/access token
`void` `shutdown()` shuts down the client
`void` `upload(SFSession connection, String command, int parallelism, boolean uploadFromStream, String remoteStorageLocation, File srcFile, String destFileName, InputStream inputStream, FileBackedOutputStream fileBackedOutputStream, StorageObjectMetadata meta, String stageRegion)` Upload a file (-stream) to S3.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### SnowflakeS3Client

    public SnowflakeS3Client(Map stageCredentials,
                             com.amazonaws.ClientConfiguration clientConfig,
                             net.snowflake.common.core.RemoteStoreFileEncryptionMaterial encMat,
                             String stageRegion)
                      throws SnowflakeSQLException

Throws:
  `SnowflakeSQLException`

### Method Detail

#### getMaxRetries

    public int getMaxRetries()

Specified by:
  `getMaxRetries` in interface `SnowflakeStorageClient`
Returns:
  Returns the Max number of retry attempts

#### getRetryBackoffMaxExponent

    public int getRetryBackoffMaxExponent()

Description copied from interface: `SnowflakeStorageClient`
Returns the max exponent for multiplying backoff with the power of 2, the value of 4 will give us 16secs as the max number of time to sleep before retry

Specified by:
  `getRetryBackoffMaxExponent` in interface `SnowflakeStorageClient`
Returns:
  Returns the exponent

#### getRetryBackoffMin

    public int getRetryBackoffMin()

Specified by:
  `getRetryBackoffMin` in interface `SnowflakeStorageClient`
Returns:
  Returns the min number of milliseconds to sleep before retry

#### isEncrypting

    public boolean isEncrypting()

Specified by:
  `isEncrypting` in interface `SnowflakeStorageClient`
Returns:
  Returns true if encryption is enabled

#### getEncryptionKeySize

    public int getEncryptionKeySize()

Specified by:
  `getEncryptionKeySize` in interface `SnowflakeStorageClient`
Returns:
  Returns the size of the encryption key

#### renew

    public void renew(Map stageCredentials)
               throws SnowflakeSQLException

Renew the S3 client with fresh AWS credentials/access token

Specified by:
  `renew` in interface `SnowflakeStorageClient`
Parameters:
  `stageCredentials` - a Map of new AWS credential properties, to refresh the client with (as returned by GS)
Throws:
  `SnowflakeSQLException` - if any error occurs

#### shutdown

    public void shutdown()

Description copied from interface: `SnowflakeStorageClient`
shuts down the client

Specified by:
  `shutdown` in interface `SnowflakeStorageClient`

#### listObjects

    public StorageObjectSummaryCollection listObjects(String remoteStorageLocation,
                                                      String prefix)
                                               throws StorageProviderException

Description copied from interface: `SnowflakeStorageClient`
For a set of remote storage objects under a remote location and a given prefix/path returns their properties wrapped in ObjectSummary objects

Specified by:
  `listObjects` in interface `SnowflakeStorageClient`
Parameters:
  `remoteStorageLocation` - location, i.e. bucket for S3
  `prefix` - the prefix to list
Returns:
  a collection of storage summary objects
Throws:
  `StorageProviderException` - cloud storage provider error

#### getObjectMetadata

    public StorageObjectMetadata getObjectMetadata(String remoteStorageLocation,
                                                   String prefix)
                                            throws StorageProviderException

Description copied from interface: `SnowflakeStorageClient`
Returns the metadata properties for a remote storage object

Specified by:
  `getObjectMetadata` in interface `SnowflakeStorageClient`
Parameters:
  `remoteStorageLocation` - location, i.e. bucket for S3
  `prefix` - the prefix/path of the object to retrieve
Returns:
  storage metadata object
Throws:
  `StorageProviderException` - cloud storage provider error

#### download

    public void download(SFSession connection,
                         String command,
                         String localLocation,
                         String destFileName,
                         int parallelism,
                         String remoteStorageLocation,
                         String stageFilePath,
                         String stageRegion)
                  throws SnowflakeSQLException

Download a file from S3.

Specified by:
  `download` in interface `SnowflakeStorageClient`
Parameters:
  `connection` - connection object
  `command` - command to download file
  `localLocation` - local file path
  `destFileName` - destination file name
  `parallelism` - number of threads for parallel downloading
  `remoteStorageLocation` - s3 bucket name
  `stageFilePath` - stage file path
  `stageRegion` - region name where the stage persists
Throws:
  `SnowflakeSQLException` - if download failed without an exception
  `SnowflakeSQLException` - if failed to decrypt downloaded file
  `SnowflakeSQLException` - if file metadata is incomplete

#### upload

    public void upload(SFSession connection,
                       String command,
                       int parallelism,
                       boolean uploadFromStream,
                       String remoteStorageLocation,
                       File srcFile,
                       String destFileName,
                       InputStream inputStream,
                       FileBackedOutputStream fileBackedOutputStream,
                       StorageObjectMetadata meta,
                       String stageRegion)
                throws SnowflakeSQLException

Upload a file (-stream) to S3.

Specified by:
  `upload` in interface `SnowflakeStorageClient`
Parameters:
  `connection` - connection object
  `command` - upload command
  `parallelism` - number of threads do parallel uploading
  `uploadFromStream` - true if upload source is stream
  `remoteStorageLocation` - s3 bucket name
  `srcFile` - source file if not uploading from a stream
  `destFileName` - file name on s3 after upload
  `inputStream` - stream used for uploading if fileBackedOutputStream is null
  `fileBackedOutputStream` - stream used for uploading if not null
  `meta` - object meta data
  `stageRegion` - region name where the stage persists
Throws:
  `SnowflakeSQLException` - if upload failed even after retry

#### handleStorageException

    public void handleStorageException(Exception ex,
                                       int retryCount,
                                       String operation,
                                       SFSession connection,
                                       String command)
                                throws SnowflakeSQLException

Description copied from interface: `SnowflakeStorageClient`
Handles exceptions thrown by the remote storage provider

Specified by:
  `handleStorageException` in interface `SnowflakeStorageClient`
Parameters:
  `ex` - the exception to handle
  `retryCount` - current number of retries, incremented by the caller before each call
  `operation` - string that indicates the function/operation that was taking place, when the exception was raised, for example "upload"
  `connection` - the current SFSession object used by the client
  `command` - the command attempted at the time of the exception
Throws:
  `SnowflakeSQLException` - exceptions that were not handled, or retried past what the retry policy allows, are propagated

#### getMatdescKey

    public String getMatdescKey()

Returns the material descriptor key

Specified by:
  `getMatdescKey` in interface `SnowflakeStorageClient`
Returns:
  the material descriptor key

#### addEncryptionMetadata

    public void addEncryptionMetadata(StorageObjectMetadata meta,
                                      MatDesc matDesc,
                                      byte[] ivData,
                                      byte[] encKeK,
                                      long contentLength)

Adds encryption metadata to the StorageObjectMetadata object

Specified by:
  `addEncryptionMetadata` in interface `SnowflakeStorageClient`
Parameters:
  `meta` - the storage metadata object to add the encyption info to
  `matDesc` - the material decriptor
  `ivData` - the initialization vector
  `encKeK` - the key encryption key
  `contentLength` - the length of the encrypted content

#### addDigestMetadata

    public void addDigestMetadata(StorageObjectMetadata meta,
                                  String digest)

Adds digest metadata to the StorageObjectMetadata object

Specified by:
  `addDigestMetadata` in interface `SnowflakeStorageClient`
Parameters:
  `meta` - the storage metadata object to add the digest to
  `digest` - the digest metadata to add

#### getDigestMetadata

    public String getDigestMetadata(StorageObjectMetadata meta)

Gets digest metadata to the StorageObjectMetadata object

Specified by:
  `getDigestMetadata` in interface `SnowflakeStorageClient`
Parameters:
  `meta` - the metadata object to extract the digest metadata from
Returns:
  the digest metadata value