Upload and Download / Blob Adapters
Overview

Large files are frequently stored in databases as BLOB fields (binary large objects). Code On Time offers out-of-the-box support for upload and download of content directly to BLOB table columns. However, common practice is to store the binary content outside of the database. There are numerous advantages to this approach:

File System

The most common method to store external files is in the file system. The files can be saved on the same hard drive of the host machine, or on an external Network-Attached Storage (NAS) device. While these devices are simple to configure, they still will require maintenance to ensure redundancy and performance.

Azure Storage

Microsoft Azure Storage cloud platform is a high-redundancy and availability solution that stores all data in data centers managed by Microsoft. It offers geo redundant storage, affinity groups, and logging. Each storage account can open multiple “containers” that are accessed via HTTP requests using unique container keys. Containers may be declared as “public” if necessary.

Amazon S3

Amazon Simple Storage Service (Amazon S3) is another popular cloud solution that offers features similar to Microsoft Azure Storage. It offers data redundancy and high availability, enabling rapid scaling of application infrastructure. Each account can create multiple buckets to store data, which are accessed via HTTP requests using one or more “Secret Access Keys”.

Configuring an Upload/Download Adapter

Declare virtual BLOB fields by entering a few parameters in the BLOB Adapter Configuration of a data controller. The web application framework will perform REST requests to a specified storage system, making it possible to use any combination of adapters in a single application without creating dependencies on third-party libraries.

A physical table column storing the file name is required for each virtual BLOB field definition. It allows the application framework  to determine existence of binary content.

Optional utility table columns Length and Content Type may be specified. The matching data controller fields will enable the application framework to communicate the file type and size to the client browser.

The table below shows configuration parameters that may be used to set up an adapter.

Parameter Description Storage System
Access-Key-ID The Access Key ID of the specified Secret Access Key required to form secure requests to Amazon S3. S3
Account Name of the Azure Storage Account. Azure
Bucket The bucket that stores the binary content. S3
Container The container that stores the binary content. Azure
Content-Type-Field The name of the data controller field that stores the file content type (data type String). Optional
Field The name of the virtual BLOB field. Required
File-Name-Field The name of the field that stores the file name (data type String). Required
Key The key used to authenticate Azure Storage requests. Azure
Length-Field The name of the data controller field that stores the file length (data type Int). Optional
Path-Template The path to the binary content in the storage system. May include references to data controller field names and special names. Required
Storage-System The type of storage system that holds the binary content. Supported values are “File”, “Azure”, and “S3”. Required
Secret-Access-Key The Secret Access Key used in conjunction with Access Key ID to form secure requests to Amazon S3. S3

Configuring Path Template

The path template can reference data controller field names in curly brackets ({}). The following example references the data controller fields ProductID and PictureFileName. This path template will work with Azure and S3 storage systems.

Path-Template: Products/{ProductID}-{PictureFileName}

The file system path template must resolve as a physical path in the file system.

Path-Template: C:\Northwind\Customers\{CustomerID}-{PhotoFileName}

You can also specify a path relative to the application root when using file system storage.

Path-Template: ~\App_Data\Customers\{CustomerID}-{PhotoFileName}

Special names $Extension and $FileNameWithoutExtension can also be used in the path template with any storage system.

Path-Template: Products/{$FileNameWithoutExtension}-{ProductID}.{$Extension}

Most hosted storage systems (Azure, S3, Google Drive) are only supporting a limited set of characters in the path. The application framework will automatically replace non-alphanumeric characters with dash (-) when evaluating path templates.