10.2.4

Edit

File storage

ODF 2 can work with Amazon S3-compatible file storages. Under the hood, it uses AWS Java SDK, though with a more convenient high-level API.

Low-level API

All interactions with the S3 storage are via the com.amazonaws.services.s3.AmazonS3 class that is part of AWS Java SDK. The ODF 2 context contains a preconfigured AmazonS3 instance to inject into any task or service. You can use S3Moduleor aggregate default modules ControlTowerServicesModule to get access to those services. The module is called from the generated Bot Task code where the platform service wrappers are provided as injectables. Among other useful services, the module provides AmazonS3 that can be used as an API for file storage operations.

The high-level API also uses this instance. The Web-Harvest context reads all configurations. Therefore, this instance is always ready to work with the S3 storage configured in Control Tower.

note

By default, S3 credentials are taken from the IA Cloud instance. When running a task from IDE, provide the credentials manually—in a test code or IDE properties if you use Studio.

To customize the AmazonS3 configuration, you can inject an instance of AmazonS3ClientBuilder preconfigured from the Web-Harvest context. When calling .build(), it produces an instance of AmazonS3 identical to the one that can be injected. Thus, use the builder to deliver a customized AmazonS3 instance.

For more details, refer to the source code of com.workfusion.odf2.service.s3.S3Module, specifically the amazonS3() and amazonS3ClientBuilder() methods.

High-level API

You can avoid using the low-level API for most standard cases. Instead, you can inject an instance of com.workfusion.odf2.service.s3.S3Service. The API provided by this class hides the complexity of underlying AmazonS3 and provides methods for common cases.

S3Service is quite small. It contains two public methods:

  • getBucket() is used to get an API object that represents a specific S3 bucket.
  • parseUrl() is used to process a string with the S3 URL extracting relevant parts from it.
final S3Bucket myBucket = s3Service.getBucket("my-bucket");

The com.workfusion.odf2.core.webharvest.service.s3.S3Bucket instance is used to upload and download files to and from the corresponding bucket.

Download binary content from S3

final S3Bucket myBucket = s3Service.getBucket("my-bucket");
final byte[] fileContent = myBucket.get(documentUrl);

Upload binary content to S3

final S3Bucket myBucket = s3Service.getBucket("my-bucket");
final byte[] fileContent = "some content".getBytes(StandardCharsets.UTF_8);
myBucket.put(fileContent, "/some/file-name.txt");

When using this method, you can guess the MIME type of an uploaded file from its filename.

Upload binary content to S3 with additional options

An overloaded version of put() allows you to specify additional options and properties for the file upload.

final S3Bucket myBucket = s3Service.getBucket("my-bucket");
final byte[] fileContent = "some content".getBytes(StandardCharsets.UTF_8);
myBucket.put(fileContent, "/some/file.name", 
    Optional.of(CannedAccessControlList.PublicRead), // The access control list for uploaded file can be specified here
    Optional.of("text/plain"),                       // The MIME type can be explicitly specified here
    Optional.of("inline"),                           // The Content-Disposition HTTP header for the file can be specified here (see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
    Optional.of(Duration.ofHours(6)));               // If this parameter is specified, presigned URL with specified expiration time is generated for the file.
← OCRSecrets Vault →