Configuring StorageItem

You configure StorageItem on the Tomcat server for two scenarios: local storage and cloud-based storage. You can have multiple configurations for a single Brightspot instance. For example, you can have two configurations for local storage (saving files directly to the file system), one configuration for Amazon cloud storage, and three configurations for generic cloud-based storage—all in the same Dari project.

As a best practice, use local storage for local or non-production environments, and use cloud-based storage for production environments. Cloud-based storage reduces the number of hits to your own web server.

Dari’s default configuration is to create a path that is unique for each uploaded file using the following steps:

Instantiate a StorageItem object with a particular configuration.
Look up the configuration’s static root path (for local storage) or container (for cloud storage).
Create a dynamic path under the static path.
Save the file under the combined static/dynamic path.

The following illustration provides examples of path names for an uploaded file in cloud-based and local storage scenarios.

Configuring StorageItem.svg — **Static and dynamic portions of StorageItem paths**

In the previous illustration, the dynamic path xx/yy/zz/ changes for each file you upload. The default format for the dynamic path is xx/xx/xxxxxxxxxxxxxxxxxxxxxxxxxxxx/, based on a random Java UUID. This prevents files with the same name from overwriting each other. For example, if you configured your static root path as /home/user/image-directory/, and if you use the default dynamic path generator, then when you upload the file dragon-slayer.png Dari saves the file as /home/user/image-directory/33/c7/f340bec94c21b7e88687c4f78fa4/dragon-slayer.png.

(You can design your own class that generates dynamic paths; for details, see Customizing storage path generation.)

The following sections provide examples of configuring local and cloud-based storage.

Setting the default StorageItem configuration

You can configure more than one scheme for storage items and set one of them as a default. In the Tomcat file context.xml, add the following line.

<Environment name="dari/defaultStorage" type="java.lang.String" value="myStorageName" />

where value is one of the storage item configuration keys appearing in context.xml.

Configuring StorageItem for local storage

In a local storage scenario, the server saves the file in its own local directory or on another server mounted to a local directory. The following table lists the keys you need to configure in context.xml to enable local storage.

Key	Description	Type
class	Class for processing files.	java.lang.String
baseURL	Base portion of the file's URL including hostname. Do not terminate with forward slash.	java.lang.String
rootPath	Static portion of the path where Dari saves files. Do not terminate with forward slash. Must exist on the server.	java.lang.String

The following snippet is an example of a configuration for local storage.

<!-- Local Storage -->
<!-- Following line sets default configuration for all storage items. Comment out as necessary. -->
<Environment name="dari/defaultStorage" type="java.lang.String" value="myStorageName" /> 
<Environment name="dari/storage/myStorageName/class" type="java.lang.String" value="com.psddev.dari.util.LocalStorageItem" /> 
<Environment name="dari/storage/myStorageName/baseUrl" type="java.lang.String" value="http://www.dari.com/huge-image-directory" /> 
<Environment name="dari/storage/myStorageName/rootPath" type="java.lang.String" value="/home/dari/huge-image-directory" />

Establishes this configuration as the default for all storage items.
Declares that the class used for storage items is LocalStorageItem.
Host portion of the file’s URL appearing in the img tag when using configuration myStorageName.
Static portion of the path where Dari saves the files on the local file system when using configuration myStorageName.

Configuring StorageItem for Amazon Simple Storage Service

In an Amazon Simple Storage Service (S3) scenario, the server saves and retrieves the file from an Amazon S3 bucket. This configuration also has internal optimizations that make saves and retrievals faster than using the generic cloud storage configuration for Amazon S3.

The following table lists the keys you need to configure in context.xml to enable Amazon S3 storage.

Key	Description	Type
class	Class for processing files.	java.lang.String
baseURL	Amazon S3 host name. Must end with a forward slash.	java.lang.String
access	Access key ID for using Amazon S3 APIs.	java.lang.String
secret	Secret access key for using Amazon S3 APIs.	java.lang.String
bucket	Bucket for storing files.	java.lang.String

Additional resources—

Managing Access Keys for Your AWS Account explains how to create access key IDs and secret access keys for your Amazon S3 account.
Step 1: Create your first S3 bucket explains how to create a bucket for your Amazon S3 account.

The following snippet is an example of a configuration for Amazon S3 storage.

<!-- Amazon S3 Storage -->
<!-- Following line sets default configuration for all storage items. Comment out as necessary. -->
<Environment name="dari/defaultStorage" type="java.lang.String" value="myStorageName" /> 
<Environment name="dari/storage/myStorageName/class" type="java.lang.String" value="com.psddev.dari.aws.S3StorageItem" /> 
<Environment name="dari/storage/myStorageName/baseUrl" type="java.lang.String" value="http://s3-us-east-amazonaws.com/" /> 
<Environment name="dari/storage/myStorageName/access" type="java.lang.String" value="myusername" /> 

<Environment name="dari/storage/myStorageName/secret" type="java.lang.String" value="mypassword" /> 
<Environment name="dari/storage/myStorageName/bucket" type="java.lang.String" value="mystoragebucket" />

Establishes this configuration as the default for all storage items.
Declares that the class used for storage items is S3StorageItem when using configuration myStorageName.
URL for logging in to and retrieving from the S3 server when using configuration myStorageName.
Username to log in to the S3 server when using configuration myStorageName.
Password to log in to the S3 server when using configuration myStorageName.
Bucket on the S3 server where Dari stores files when using configuration myStorageName.

Referring to the previous snippet, at runtime Dari creates the static portion of the path for saving and retrieving a file as http://s3-us-east-amazonaws.com/mystoragebucket/.

Configuring StorageItem for Cloud Storage

In a cloud storage scenario, the server saves and retrieves the file from a cloud service. This configuration is available for any cloud provider supported by jclouds.

Note

If you are hosting files on Amazon S3 servers, use the configuration described in Configuring StorageItem for Amazon Simple Storage Service.

The following table lists the keys you need to configure in context.xml to enable cloud storage. Depending on your cloud provider, you may not need to configure all of the keys.

Key	Description	Type
Learn class	Class for processing files.	java.lang.String
provider	URL for the cloud service.	java.lang.String
identity	Username for logging in to cloud storage.	java.lang.String
credential	Password for logging in to cloud storage.	java.lang.String
container	Container where your files are stored.	java.lang.String
region	Geographical region or other scope containing a container.	java.lang.String

To use this class, Dari must be able to access the jclouds library. If you use Maven, add the following dependency to pom.xml:

<dependency>
    <groupId>org.jclouds</groupId>
    <artifactId>jclouds-all</artifactId>
    <version>1.6.0</version>
</dependency>

<!-- Cloud Storage -->
<!-- Following line sets default configuration for all storage items. Comment out as necessary. -->
<Environment name="dari/defaultStorage" type="java.lang.String" value="myStorageName" /> 
<Environment name="dari/storage/myStorageName/class" type="java.lang.String" value="com.psddev.dari.util.CloudStorageItem" /> 
<Environment name="dari/storage/myStorageName/provider" type="java.lang.String" value="http://dari.cloudapp.net" /> 
<Environment name="dari/storage/myStorageName/identity" type="java.lang.String" value="myusername" /> 
<Environment name="dari/storage/myStorageName/credential" type="java.lang.String" value="mypassword" /> 
<Environment name="dari/storage/myStorageName/region" type="java.lang.String" value="New_York" /> 
<Environment name="dari/storage/myStorageName/container" type="java.lang.String" value="mycontainer" />

Establishes this configuration as the default for all storage items.
Declares that the class used for storage items is CloudStorageItem.
URL for logging on to the cloud server when using configuration myStorageName.
Username to log in to and retrieving from the cloud server when using configuration myStorageName.
Password to log in to the cloud server when using configuration myStorageName.
Region containing the storage item. If you set value="", the region is considered null.
Container containing the storage item.

Referring to the previous snippet, at runtime Dari creates the static portion of the path for saving and retrieving a file as http://dari.cloudapp.net/New_York/mycontainer/.

See also:

Previous Topic

StorageItem life cycle

Next Topic

Querying