ruby-atmos-pure

= Atmos

This gem is a Ruby library for EMC's Atmos (http://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 => ,

: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