Support and Documentation

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:

  1. Instantiate a StorageItem object with a particular configuration.

  2. Look up the configuration's static root path (for local storage) or container (for cloud storage).

  3. Create a dynamic path under the static path.

  4. 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.

Static and dynamic portions of StorageItem paths
Figure 96. 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" /> 1
<Environment name="dari/storage/myStorageName/class" type="java.lang.String" value="com.psddev.dari.util.LocalStorageItem" /> 2
<Environment name="dari/storage/myStorageName/baseUrl" type="java.lang.String" value="http://www.dari.com/huge-image-directory" /> 3
<Environment name="dari/storage/myStorageName/rootPath" type="java.lang.String" value="/home/dari/huge-image-directory" /> 4

1

Establishes this configuration as the default for all storage items.

2

Declares that the class used for storage items is LocalStorageItem.

3

Host portion of the file's URL appearing in the img tag when using configuration myStorageName.

4

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—

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" /> 1
<Environment name="dari/storage/myStorageName/class" type="java.lang.String" value="com.psddev.dari.aws.S3StorageItem" /> 2
<Environment name="dari/storage/myStorageName/baseUrl" type="java.lang.String" value="http://s3-us-east-amazonaws.com/" /> 3
<Environment name="dari/storage/myStorageName/access" type="java.lang.String" value="myusername" /> 4

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

1

Establishes this configuration as the default for all storage items.

2

Declares that the class used for storage items is S3StorageItem when using configuration myStorageName.

3

URL for logging on to and retrieving from the S3 server when using configuration myStorageName.

4

Username to log in to the S3 server when using configuration myStorageName.

5

Password to log in to the S3 server when using configuration myStorageName.

6

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

class

Class for processing files.

java.lang.String

provider

URL for the cloud service.

java.lang.String

identity

User name 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>

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

<!-- 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" /> 1
<Environment name="dari/storage/myStorageName/class" type="java.lang.String" value="com.psddev.dari.util.CloudStorageItem" /> 2
<Environment name="dari/storage/myStorageName/provider" type="java.lang.String" value="http://dari.cloudapp.net" /> 3
<Environment name="dari/storage/myStorageName/identity" type="java.lang.String" value="myusername" /> 4
<Environment name="dari/storage/myStorageName/credential" type="java.lang.String" value="mypassword" /> 5
<Environment name="dari/storage/myStorageName/region" type="java.lang.String" value="New_York" /> 6
<Environment name="dari/storage/myStorageName/container" type="java.lang.String" value="mycontainer" /> 7

1

Establishes this configuration as the default for all storage items.

2

Declares that the class used for storage items is CloudStorageItem.

3

URL for logging on to the cloud server when using configuration myStorageName.

4

Username to log in to and retrieving from the cloud server when using configuration myStorageName.

5

Password to log in to the cloud server when using configuration myStorageName.

6

Region containing the storage item. If you set value="", the region is considered null.

7

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/.