3 Usage - Reference Documentation
Authors: David Estes
Version: 0.3.0
3 Usage
There are several tips and tricks to taking advantage of the Karman Storage API. This guide should get you started and is still a work in progress so expect more down the road.3.1 Providers
Karman provides a uniform interface in dealing with cloud stored files. It does this starting with the Provider class. The Provider class is the starting point and is responsible for storing any credentials needed to interface with your cloud provider as well as instantiating Directories. By default the core Karman plugin comes with a LocalStorageProvider implementation:import com.bertramlabs.plugins.karman.local.LocalStorageProviderdef provider = new LocalStorageProvider(basePath: '/path/to/store')
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()
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')
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
TheDirectory
abstract class provides more convenience methods for getting files or creating files within your cloud provider.We can start by simply listing all the files in our bucket/directory:provider['mybucket'].listFiles()
provider['mybucket'].listFiles(prefix: 'config/') //List only files in the config path
provider['mybucket'].getFile('test.txt')
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']
provider['mybucket']['test.txt'].text("Setting the text value").contentType("text/plain").save()
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']
3.3 Files
Working with files in the Karman plugin is fairly simple and most methods of theCloudFile
interface should be supported.
The CloudFile
tries to adhere to similar methods in the File
class to make it simpler to deal with. For example:def file = provider['mybucket']['test.txt']return file.text //or return file.getText('UTF-8') //or return file.bytes //or return file.inputStream
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()
file.delete()
getURL
:file.getURL() //or if private and need public file.getURL(1.hour) //retrive a url good for 1 hour