3 Usage

3.1 Providers

import com.bertramlabs.plugins.karman.local.LocalStorageProvider
def provider = new LocalStorageProvider(basePath: '/path/to/store')

As can be seen above the LocalStorageProvider provides an interface to a storage path on your filesystem. The plugin is designed to be very extensible and more providers are in the works such as the karman-aws plugin which will provide the S3StorageProvider for interfacing with S3.

Getting Directories

A Provider provides an interface to get or create root directories on the cloud. Most cloud providers dont use full folder trees but rather files with names containing a '/'. In the case of the S3Provider, a Directory can be considered Synonymous with a Bucket.

There are several ways get interact with directories. For example to get a list of directories we simply do the following:

provider.getDirectories()

This will return an array of Directory compatible classes.

Another option is to simply ask for a reference to a directory or bucket directly. This can be done by simply doing:

provider.getDirectory('mybucket')

This will return a directory object wether it exists or not. You can test for existance via the exists() method or call mkdir() to create the directory (more on this later).

We also take advantage of some groovy magic to make for some nifty shorthand to get a directory:

provider['mybucket'] //equivalent to getDirectory

3.2 Directories

We can start by simply listing all the files in our bucket/directory:

provider['mybucket'].listFiles()

The above will return an array of CloudFile objects. The listFiles method will also accept a few optional paramenters (this can vary slightly between providers but a few are considered standard). One of which is the prefix option. It is important to note that the listFiles() method is a recursive scan and should list all files (wether nested or not). In cases where you may just want files within a subfolder you can do something like:

provider['mybucket'].listFiles(prefix: 'config/') //List only files in the config path

A Directory also supports several shortcuts for getting individual files:

provider['mybucket'].getFile('test.txt')

This will return a file object wether it exists or not. Use the exists() method on the CloudFile to determine existance. We also take advantage of some groovy magic, not only for getting references to CloudFiles but shorthand for uploading files.

provider['mybucket']['test.txt']

This returns a CloudFile object. We can do some chaining fun to quickly set the file contents:

provider['mybucket']['test.txt'].text("Setting the text value").contentType("text/plain").save()

We can even just set the value of this property directly to trigger an immediate upload:

provider['mybucket']['test.txt'] = "Setting the text value" //Uploaded
//Or upload a File
provider['mybucket']['test.txt'] = new File("path/to/file")
//Or transfer a file from one cloud provider to another
s3provider['mybucket']['test.txt'] = rackspace['mybucket']['test.txt']

These are nifty shorthands for getting to the point with your files. In many cases though you will need more fine grained control over your file contents, meta, and upload strategy. To do this we can use the CloudFile directly.

3.3 Files

def file = provider['mybucket']['test.txt']
return file.text
//or 
return file.getText('UTF-8')
//or
return file.bytes
//or
return file.inputStream

In the cloud, files typically have a lot more meta data tied to them. To deal with this we have methods for getContentType and setContentType. More complex meta data is still being worked on.

When setting content values of a CloudFile, the contents are not immediately persisted (except in the LocalStorage implementation). To save your changes make sure the save() method is called:

def file = provider['mybucket']['test.txt']
file.text = "Setting some value to this file"
file.save()

Files can be deleted as well:

file.delete()

Public Url can be fetched for a file via getURL:

file.getURL()
//or if private and need public
file.getURL(1.hour) //retrive a url good for 1 hour

NOTE: The above is not yet fully implemented , stay tuned!