Storage

Brightspot's StorageItem API provides a unified interface for uploading, retrieving, and managing files across multiple storage back ends. Whether you're storing files on the local filesystem, Amazon S3, Azure Blob Storage, or Google Cloud Storage, the API remains the same.

Key capabilities

• Unified API—A single StorageItem interface for all storage operations regardless of the back end.
• Multiple back ends—Built-in support for local filesystem, AWS S3, Azure Blob Storage, and Google Cloud Storage.
• Lifecycle hooks—Extensible before/after hooks for save and delete operations.
• CDN integration—Automatic file synchronization with content delivery networks, including multi-CDN hashing.
• Custom path generation—Pluggable path generators for controlling how uploaded files are named and organized.

Getting started

Installation

The core module provides the StorageItem interface and the local filesystem back end:

Requirements

Requires Brightspot 4.8 or later.

Maven

<dependency>
    <groupId>com.brightspot.storage</groupId>
    <artifactId>storage</artifactId>
    <version>__HIDDEN__</version>
</dependency>

Gradle

implementation 'com.brightspot.storage:storage:__HIDDEN__'

Gradle (Kotlin DSL)

implementation("com.brightspot.storage:storage:__HIDDEN__")

Add a back-end module based on your storage provider:

Provider	Artifact
AWS S3	com.brightspot.storage:aws
Azure Blob Storage	com.brightspot.storage:azure
Google Cloud Storage	com.brightspot.storage:gcp

Using StorageItem in content types

To store files in a Brightspot content type, declare a field of type StorageItem:

1
@Recordable.PreviewField("file")
2
public class GettingStarted extends Content {
3

4
    private String name;
5

6
    private StorageItem file;
7

8
    public String getName() {
9
        return name;
10
    }
11

12
    public void setName(String name) {
13
        this.name = name;
14
    }
15

16
    public StorageItem getFile() {
17
        return file;
18
    }
19

20
    public void setFile(StorageItem file) {
21
        this.file = file;
22
    }
23
}

When editors upload a file through the CMS, Brightspot automatically persists it to the configured storage back end and serializes the StorageItem reference in the database.

Programmatic usage

Create and save a file to the default storage:

1
public StorageItem uploadFile(String fileName, byte[] content, String contentType) throws IOException {
2
    StorageItem item = StorageItem.Static.create();
3

4
    item.setPath(fileName);
5
    item.setContentType(contentType);
6
    item.setData(new ByteArrayInputStream(content));
7
    item.save();
8

9
    return item;
10
}

Save to a specific named storage:

1
public StorageItem uploadToSpecificStorage(String storageName, String fileName, InputStream data)
2
    throws IOException {
3

4
    StorageItem item = StorageItem.Static.createIn(storageName);
5

6
    item.setPath(fileName);
7
    item.setData(data);
8
    item.save();
9

10
    return item;
11
}

Read data back from a storage item:

1
public byte[] downloadFile(StorageItem item) throws IOException {
2
    try (InputStream data = item.getData()) {
3
        return data.readAllBytes();
4
    }
5
}

Copy a file between storage back ends:

1
public StorageItem copyToStorage(StorageItem item, String targetStorage) throws IOException {
2
    return StorageItem.Static.copy(item, targetStorage);
3
}

How it works

The storage system is built around the StorageItem interface, with AbstractStorageItem providing shared functionality like base URL construction and CDN hashing. Each back-end module extends AbstractStorageItem with provider-specific logic.

1
StorageItem (interface)
2
  └── AbstractStorageItem (abstract)
3
        ├── LocalStorageItem
4
        ├── S3StorageItem
5
        ├── AzureBlobStorageItem
6
        └── GoogleCloudStorageItem

Storage back ends are configured via Dari settings under dari/storage/{name}, where {name} is an arbitrary identifier. The dari/defaultStorage setting determines which back end is used when no storage name is explicitly specified.

Who this documentation is for

• Storage back ends—For developers configuring a storage provider (local filesystem, S3, Azure, or GCS) for a Brightspot project.
• Extending—For developers implementing custom lifecycle hooks, path generators, CDN filters, or hashing strategies.