Atmos

This gem is a Ruby library for EMC's Atmos (www.emc.com/atmos) REST API.

Logging is done via the Log4r package. The name of the logger is the string atmos, and the log level is set to Log4r::FATAL by default.

Getting started

You'll need this gem and a URL to your Atmos installation.

You'll also need your Atmos authentication credentials.

Basics

XML Parser

The very first thing is that you have to pick your XML parser. There are two options: nokogiri for performance or rexml for only pure ruby requirements. Setting the parser does the require, so make sure you have the gem you want to use installed. This gem doesn't require either, since it doesn't know which you plan to use.

Atmos::Parser::parser = Atmos::Parser::NOKOGIRI
Atmos::Parser::parser = Atmos::Parser::REXML

Datastore

The Atmos installation you will be connecting to is your datastore. You can see more detailed information at Atmos::Store.

store = Atmos::Store.new(:url    => "https://mgmt.atmosonline.com", 
                         :uid    => <your identifier>, 
                         :secret => <your secret>)

From your store, you can create and retrieve objects. Note that objects are always retrieved without their data, so a progressive download can be done.

obj = store.get(id)
newobj = store.create(options)

Now that you have a store, you can iterate through all listable tags, object ids by listable tag, and objects by listable tag. Remember that when an Atmos::Object is instantiated, it loads all ACLs and Metadata.

store.each_listable_tag { |tag| }

store.each_object_id_by_tag(tag) do |id|
end

store.each_object_by_tag(tag) do |obj|
end

Objects

See Atmos::Object for more detailed info on the object API.

Creating Objects

At the very simplest, you can create an object with nothing. The mimetype will default to binary/octet-stream. The object will be created with no data, no metadata, with permissions set for only the creator to access.

obj = store.create()

You can also create an object with (any combination of) more information up front. (See Atmos::Store.create for more detailed info on object creation options.)

obj = store.create(
                     :user_acl          => {'janet' => :full, 'xavier' => :read},
                     :group_acl         => {'other' => :read},
                     :metadata          => {'key' => 'value', 'another_key' => nil},
                     :listable_metadata => {'lkey' => 'lvalue', 'another_lkey' => nil},
                     :mimetype          => "video/quicktime",
                     :data              => open("local/video_file.qt")
                    )
Reading Objects

You can get the data for an object all at once, which means it all gets read into memory all at once:

@data = @obj.data

Or progressively download it by passing a block to read:

@file = open('mydata', 'w')
@obj.read do |chunk|
    @file.write chunk
end
Object Metadata

An object has system and user metadata. User metadata can be modified, system metadata cannot. User metadata is further divided into listable and non-listable metadata. Listable metadata means the object is indexed on the key value of the metadata key/value pair (also known as a tag), and can be retrieved via the tag.

Set or change user metadata, listable or non-listable, keys and values must be Strings:

@obj.metadata[newkey] = "newvalue"

(See Atmos::Metadata for more detailed info.)

Object ACL

There are two ACLs on an object: user_acl and group_acl. User and group names are ruby Strings, while the values are one of the following symbols: :none, :read, :write ,:full. They are accessed as Hashes on the object. All normal Hash functions will work.

When permissions are set to :none the pair disappears from the hash.

@obj.user_acl['user'] = :full
@obj.group_acl['other'] = :none

(See Atmos::ACL for more detailed info.)

Other Object Functionality
@obj.exists?
@obj.delete