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.

../../_images/storage-item-path-components.svg

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 Storage Item 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 files’ 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.

1
2
3
4
5
6
<!-- 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" />

In the previous snippet—

  • Line 3 establishes this configuration as the default for all storage items.
  • Line 4 declares that the class used for storage items is LocalStorageItem.
  • Line 5 specifies the host portion of the file’s URL appearing in the img tag.
  • Line 6 specifies the static portion of the path where Dari saves the files on the local file system.

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.

1
2
3
4
5
6
7
8
<!-- 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" />

In the previous snippet—

  • Line 3 establishes this configuration as the default for all storage items.
  • Line 4 declares that the class used for storage items is S3StorageItem.
  • Line 5 specifies the URL for logging on to and retrieving from the S3 server.
  • Line 6 specifies the username to log in to the S3 server.
  • Line 7 specifies the password to log in to the S3 server.
  • Line 8 specifies the bucket on the S3 server where Dari stores files.

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.

1
2
3
4
5
6
7
8
9
<!-- 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" />

In the previous snippet—

  • Line 3 establishes this configuration as the default for all storage items.
  • Line 4 declares that the class used for storage items is CloudStorageItem.
  • Line 5 specifies the URL for logging on to the cloud server.
  • Line 6 specifies the username to log in to and retrieving from the cloud server.
  • Line 7 specifies the password to log in to the cloud server.
  • Line 8 specifies the region containing the storage item. If you set value="", the region is considered null.
  • Line 9 specifies 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:

Creating StorageItems

StorageItem Lifecycle