ruby-atmos-pure 1.0.3

data/COPYING

@@ -0,0 +1,8 @@
+# Copyright (c) 2011 EMC Corporation
+# All Rights Reserved
+# 
+# This software contains the intellectual property of EMC Corporation
+# or is licensed to EMC Corporation from third parties.  Use of this 
+# software and the intellectual property contained therein is expressly
+# limited to the terms and conditions of the License Agreement under which 
+# it is provided by or on behalf of EMC.

data/README

@@ -0,0 +1,129 @@
+#
+# = Atmos
+#
+# This gem is a Ruby library for EMC's Atmos (http://www.emc.com/atmos) REST API.
+#
+# Logging is done via the <tt>Log4r</tt> package.  The name of the logger is the string +atmos+,
+# and the log level is set to <tt>Log4r::FATAL</tt> 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:
+# <tt>nokogiri</tt> for performance or <tt>rexml</tt> 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 <tt>Atmos::Store</tt>.
+# 
+#    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 <tt>Atmos::Object</tt> 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 <tt>binary/octet-stream</tt>.  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 <tt>Atmos::Store.create</tt> 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 <tt>read</tt>:
+#
+#  @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 
+# <tt>tag</tt>), 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 <tt>Atmos::Metadata</tt> for more detailed info.)
+#
+#
+# ===== Object ACL
+#
+# There are two ACLs on an object: <tt>user_acl</tt> and <tt>group_acl</tt>.
+# User and group names are ruby Strings, while the values are one of the
+# following symbols: <tt>:none</tt>, <tt>:read</tt>, <tt>:write</tt> ,<tt>:full</tt>.
+# They are accessed as Hashes on the object.  All normal Hash functions will work.
+#
+# When permissions are set to <tt>:none</tt> the pair disappears from the hash.
+#
+#  @obj.user_acl['user'] = :full
+#  @obj.group_acl['other'] = :none
+#
+# (See <tt>Atmos::ACL</tt> for more detailed info.)
+#
+#
+# ===== Other Object Functionality
+#
+#  @obj.exists?
+#  @obj.delete
+# 
+

data/Rakefile

@@ -0,0 +1,103 @@
+require 'rubygems'
+
+require 'rake'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'rake/gempackagetask'
+require 'test/unit'
+
+require File.dirname(__FILE__) + '/lib/atmos'
+
+task :default => :test
+
+
+desc "run tests"
+Rake::TestTask.new do |t|
+   libdir  = File.expand_path('lib')
+   testdir = File.expand_path('test')
+   
+   t.libs = [libdir, testdir]
+   #t.pattern = 'test/lib/test_*.rb'
+   t.verbose = true
+   #t.warning = true
+end
+
+
+Rake::RDocTask.new do |rdoc|  
+   rdoc.rdoc_dir = 'doc'  
+   rdoc.title    = "EMC Atmos' REST API gem - ruby-atmos"  
+   rdoc.options << '--line-numbers' << '--inline-source' << '--main=README'
+   rdoc.rdoc_files.include('README')
+   rdoc.rdoc_files.include('lib/*.rb')
+   rdoc.rdoc_files.include('lib/atmos/*.rb')  
+end
+
+
+spec = Gem::Specification.new do |s|
+   s.platform          = Gem::Platform::RUBY
+   s.name              = 'ruby-atmos'
+   s.version           = Gem::Version.new(Atmos::VERSION)
+   s.summary           = "Client library for EMC's Atmos REST API"
+   s.description       = "Ruby OO library to access an EMC Atmos server as a blobstore."
+   s.email             = 'fleur.dragan@emc.com'
+   s.author            = 'Fleur Dragan'
+   s.has_rdoc          = true
+   s.extra_rdoc_files  = %w(README COPYING)
+   s.homepage          = 'http://www.emc.com/atmos'
+    #s.rubyforge_project = 'atmos'
+   s.files             = FileList['Rakefile', 'lib/atmos.rb', 'lib/*/*.rb']
+   s.test_files        = Dir['test/**/*']
+   s.require_path      = 'lib'
+   s.add_dependency('log4r',     '>=1.1.9')
+   s.add_dependency('ruby-hmac', '>=0.4.0')
+
+   s.rdoc_options  = ['--title', "EMC Atmos' REST API gem - ruby-atmos",
+                       '--main',  'README',
+                       '--line-numbers', '--inline-source']
+end
+
+#
+# DRY: set up gemspecs for both versions of gems
+#
+nokogiri_spec = spec.clone
+nokogiri_spec.name = 'ruby-atmos'
+nokogiri_spec.add_dependency('nokogiri',  '>=1.4.4')
+nokogiri_spec.description = "Ruby OO library to access an EMC Atmos server with nokogiri as XML parser."
+nokogiri_spec.rubyforge_project = nokogiri_spec.name
+
+rexml_spec = spec.clone
+rexml_spec.name = 'ruby-atmos-pure'
+rexml_spec.files += FileList['lib/atmos/*/rexml.rb']
+rexml_spec.description = "Ruby OO library to access an EMC Atmos server with rexml as XML parser."
+rexml_spec.rubyforge_project = rexml_spec.name
+
+
+#
+# creating the actual package tasks for the two gems
+#
+Rake::GemPackageTask.new(nokogiri_spec) { |pkg| }
+Rake::GemPackageTask.new(rexml_spec) { |pkg| }
+
+desc 'install, require both gems'
+task :install do
+       sh "sudo gem i pkg/#{rexml_spec.name}-#{rexml_spec.version}.gem"
+       sh "ruby test/require_test.rb"
+       sh "sudo gem i pkg/#{nokogiri_spec.name}-#{nokogiri_spec.version}.gem"
+       sh "ruby test/require_test.rb"
+end
+  
+desc 'uninstall both gems'
+task :uninstall do
+    sh "sudo gem uninstall #{nokogiri_spec.name} -x"
+    sh "sudo gem uninstall nokogiri -x"
+    sh "sudo gem uninstall #{rexml_spec.name} -x"
+end
+  
+desc 'reinstall both gems'
+task :reinstall => [:uninstall, :install]
+
+desc 'push to rubygems.org'
+task :push => [:install] do
+   sh "gem push pkg/#{rexml_spec.name}-#{rexml_spec.version}.gem"
+   sh "gem push pkg/#{nokogiri_spec.name}-#{nokogiri_spec.version}.gem"
+end

data/lib/atmos.rb

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'log4r'
+require 'uri'
+require 'net/http'
+require 'net/https'
+require 'time'
+require 'base64'
+require 'hmac-sha1'
+
+
+Log4r::Logger.new('atmos')
+Log4r::Logger.get('atmos').add(Log4r::StderrOutputter.new 'console')
+Log4r::Logger.get('atmos').level = Log4r::FATAL
+#Log4r::Logger.get('atmos').level = Log4r::WARN
+#Log4r::Logger.get('atmos').level = Log4r::INFO
+#Log4r::Logger.get('atmos').level = Log4r::DEBUG
+
+
+$:.unshift(File.dirname(__FILE__))
+require 'atmos/parser'
+require 'atmos/version'
+require 'atmos/util'
+require 'atmos/exceptions'
+require 'atmos/request'
+require 'atmos/response'
+require 'atmos/rest'
+require 'atmos/store'
+require 'atmos/attributes'
+require 'atmos/object'
+
+#
+# This sets the default, but it can still be overridden by setting the parser elsewhere.
+#
+Atmos::Parser::parser = (File.exists?(File.join(File.dirname(__FILE__), 'atmos/parser/rexml.rb'))) ? Atmos::Parser::REXML : Atmos::Parser::NOKOGIRI
+Atmos::LOG.warn("parser: #{Atmos::Parser::parser}")

data/lib/atmos/attributes.rb

@@ -0,0 +1,545 @@
+module Atmos
+   
+   #
+   # == AttributeHashBase
+   #
+   # Base class for ACL and Metadata objects.  Contains utility methods common to both,
+   # as well as implementations of standard ruby Hash functions to make both ACL and
+   # Metadata objects appear as hashes while interacting with Atmos at the same time.
+   #
+   #
+   class AttributeHashBase < Hash # :nodoc:
+      attr_reader :last_reload_at
+      
+      @obj              = nil
+      @header           = nil
+      @last_reload_at   = nil
+      @set_action       = nil
+      @reload_action    = nil
+      @delete_action    = nil
+      
+      
+      def delete_with_atmos(key)
+         delete_without_atmos(key)
+      end
+      alias :delete_without_atmos :delete
+      alias :delete :delete_with_atmos
+
+
+      def clear_with_atmos
+         clear_without_atmos
+      end
+      alias :clear_without_atmos :clear
+      alias :clear :clear_with_atmos
+
+
+      def replace_with_atmos(h)
+         validate_input_hash(h)
+         replace_without_atmos(h)
+      end
+      alias :replace_without_atmos :replace
+      alias :replace :replace_with_atmos
+      
+      
+      def merge_with_atmos(h)
+         validate_input_hash(h)
+         merge_without_atmos(h)
+      end
+      alias :merge_without_atmos :merge
+      alias :merge :merge_with_atmos
+
+      
+      def merge_with_atmos!(h)
+         validate_input_hash(h)
+         
+         input = h.clone
+         input.each do |k,v|
+            input[k] = xlate_value_from_object_to_header(v)
+         end
+         
+         response = @obj.request.do(@set_action, :id => @obj.aoid, @header => Atmos::Util.hash2header(input))
+         reload(@reload_action, @obj.aoid)
+      end
+      alias :merge_without_atmos! :merge!
+      alias :merge! :merge_with_atmos!
+      alias :update :merge!
+
+
+      def default_with_atmos=
+         raise Atmos::Exceptions::NotImplementedExceptions, "Not implemented for Atmos Object properties."
+      end
+      alias :default_without_atmos= :default=
+      alias :default= :default_with_atmos=
+      
+      
+      #
+      # Same as self[key] = value
+      #
+      def store(key, value)
+         self[key] = value
+      end
+      
+
+      #
+      # This method is used internally to generate REST requests to the Atmos server.
+      #
+      # Each ACL or Metadata object knows what HTTP header it is representing
+      # in the Atmos REST API we're wrapping.  This method returns that.
+      #
+      def header_name
+         return @header
+      end
+      
+      
+      #
+      # This method is used internally to generate REST requests to the Atmos server.
+      #
+      # Returns data as a String in the form of a valid HTTP header Atmos will
+      # recognize.
+      #
+      def header_value
+         Atmos::Util.hash2header(self)
+      end
+      
+      
+      #
+      # This method is used internally to generate REST requests to the Atmos server.
+      #
+      def to_header
+         "#{self.header_name}: #{self.header_value}"
+      end
+      
+      def to_canonicalized_header
+         self.to_header.squeeze
+      end
+         
+         
+      protected
+         def validate_input_hash(h)
+            true
+         end
+         
+         def xlate_value_from_header_to_object(value)
+            value
+         end
+
+         def reload(action, aoid, options = {})
+            response = @obj.request.do(action, options.merge({:id => aoid}))
+            Atmos::LOG.debug("AttributeHashBase.reload: type: #{@type}; header: #{@header}; value: #{response[@header]}")
+            newval = Atmos::Util.header2hash(response[@header])
+            Atmos::LOG.debug("AttributeHashBase.reload: newval: #{newval.inspect}")
+            if (!newval.nil?)
+               newval.each do |key,val|
+                  newval[key] = xlate_value_from_header_to_object(val)
+               end
+               Atmos::LOG.debug("AttributeHashBase.reload: newval: #{newval.inspect}")
+               replace_without_atmos(newval)
+            end
+            Atmos::LOG.debug("AttributeHashBase.reload: self: #{self.inspect}")
+
+            @last_reload_at = Time.now()
+         end
+
+   end
+   
+   
+   # == Access Control Lists (ACLs)
+   #
+   # There are two hashes for access control, available as properties on the object: +user_acl+ and +group_acl+.  
+   # The keys are the Atmos usernames and the values are one of :+none+, :+read+, :+write+, :+full+.  The ACLs
+   # behave like normal Hash objects.  All operations are executed against the Atmos server immediately.
+   #
+   # === Defaults
+   # By default, when you create an object, the user you gave as a parameter when instantiating Atmos::Store
+   # has full permissions on the object  The default group is +other+.  So:
+   #
+   #    puts obj.user_acl.inspect => {user => :full}
+   #    puts obj.group_acl.inspect => {other => :none}
+   #
+   #
+   # === Adding 
+   # Adding permissions for a new user is as easy as adding another hash element:
+   #
+   #    obj.user_acl[newuser] = :read
+   #
+   #    puts obj.user_acl.inspect => {user => :full, newuser => :read}
+   #
+   #
+   # === Modifying
+   # User and group permissions can be modified by modifying the appropriate key value.
+   # Keep in mind that you CAN be dumb and give up access to your own objects,
+   # even if there is no other user that has access to them.
+   #
+   #    obj.user_acl[newuser] = :full
+   #    puts obj.user_acl.inspect => {user => :full, newuser => :full}
+   #
+   #    obj.group_acl['other'] = :full
+   #    puts obj.group_acl.inspect => {other => :full}
+   #
+   #
+   # === Deleting
+   # Remove any permissions for a given user or group, you can either modify existing permissions
+   # to :+none+, or you can delete the user/group name from the appropriate hash.  When you do either,
+   # the name disappears entirely from the hash.
+   #
+   #    obj.user_acl.delete(newuser)
+   #    puts obj.user_acl.inspect => {user => :full}
+   #
+   #    obj.user_acl[newuser] = :none
+   #    puts obj.user_acl.inspect => {user => :full}
+   #
+   #
+   class ACL < AttributeHashBase
+      USER  = 1
+      GROUP = 2
+      
+      #
+      # This constructor is only meant for internal use.  To get ACLs on an object:
+      #
+      #    obj.user_acl => Hash
+      #    obj.group_acl => Hash
+      #
+      def initialize(obj, type)
+         raise Atmos::Exceptions::ArgumentException, "The 'obj' parameter cannot be nil." if (obj.nil?)
+         raise Atmos::Exceptions::ArgumentException, "The 'obj' parameter must have an id." if (obj.aoid.nil?)
+         raise Atmos::Exceptions::ArgumentException, "The 'type' parameter must be Atmos::ACL::USER or Atmos::ACL::GROUP." if (![USER, GROUP].include?(type))
+         
+         super()
+         
+         @obj = obj
+         @type = type
+         
+         @header = (@type == USER) ? 'x-emc-useracl' : 'x-emc-groupacl'
+         @delete_action = @set_action = (@type == USER) ? :set_user_acl : :set_group_acl
+         @reload_action = :list_acl
+         
+         reload(@reload_action, @obj.aoid)
+      end
+      
+      
+      #
+      # Adds or modifies permissions for a user or group.  
+      # The change is made on the Atmos server immediately.
+      # Valid values are :+none+, :+read+, :+write+, :+full+.
+      #
+      def []=(key,value)
+         validate_value(value)
+         response = @obj.request.do(@set_action, :id => @obj.aoid, @header => "#{key}=#{xlate_value_from_object_to_header(value)}")
+         reload(@reload_action, @obj.aoid)
+      end
+      
+
+      #
+      # Returns +true+ if this ACL object is representing user ACLs.
+      #
+      def user?
+         @type == USER
+      end
+      
+      #
+      # Returns +true+ if this ACL object is representing group ACLs.
+      #
+      def group?
+         @type == GROUP
+      end
+      
+      
+      #
+      # Removes permissions for specified user/group name.  Update is made on the Atmos server immediately.
+      #
+      def delete(key)
+         response = @obj.request.do(@set_action, :id => @obj.aoid, @header => "#{key}=#{xlate_value_from_object_to_header(:none)}")
+         self.delete_without_atmos(key)
+         reload(@reload_action, @obj.aoid)         
+      end
+
+      #
+      # Removes all permissions for all groups, or for all users except the one used to instantiate
+      # the Atmos::Store connection.
+      #
+      def clear
+         # do a reload to make absolutely sure ACL is up to date
+         reload(@reload_action, @obj.aoid)
+         
+         values = {}
+         self.each do |k,v|
+            values[k] = xlate_value_from_object_to_header(:none)
+         end
+         values.delete(@obj.user)
+         
+         response = @obj.request.do(@set_action, :id => @obj.aoid, @header => Atmos::Util.hash2header(values))
+         reload(@reload_action, @obj.aoid)         
+      end
+ 
+       
+      private
+         def validate_input_hash(h)
+            msg = nil
+            bad_keys = []
+            bad_values = []
+            good_values = [:none, :read, :write, :full]
+            
+            h.each do |k,v|
+               bad_keys.push(k) if (k.nil? || !k.kind_of?(String))
+               bad_values.push(v) if (v.nil? || !good_values.include?(v))
+            end
+            
+            msg = "The input has was bad: " if (!bad_keys.empty? || !bad_values.empty?)
+            msg += "bad keys: #{bad_keys.inspect} " if (!bad_keys.empty?)
+            msg += "bad values: #{bad_values.inspect}" if (!bad_values.empty?)
+            
+            raise Atmos::Exceptions::ArgumentException, msg if (!msg.nil?)
+         end
+
+         def validate_value(value)
+            if (![:none, :read, :write, :full].include?(value))
+               raise Atmos::Exceptions::ArgumentException, "Valid permissions values are :none, :read, :write, :full"
+            end
+         end
+         
+         def xlate_value_from_header_to_object(value)
+            case value
+            when 'NONE'
+               :none
+            when 'READ'
+               :read
+            when 'WRITE'
+               :write
+            when 'FULL_CONTROL'
+               :full
+            else
+               raise Atmos::Exceptions::InternalLibraryException, "Permissions type not recognized: #{value}"
+            end
+         end
+         
+         def xlate_value_from_object_to_header(value)
+            case value
+            when :none
+               'NONE'
+            when :read
+               'READ'
+            when :write
+               'WRITE'
+            when :full
+               'FULL_CONTROL'
+            end
+         end
+   end
+
+
+   # == Metadata
+   # In all cases, +metadata+ refers to key/value pairs, and is represented 
+   # as a ruby Hash attached to an Atmos::Object object.
+   #
+   # === Standard Metadata
+   # In Atmos, +metadata+ with no modifier (e.g. +listable+ or +system+) 
+   # refers to metadata on an object that is not indexed.  In other words,
+   # objects cannot be referenced by the metadata information.  The only
+   # way to get this metadata information is to already have the object
+   # the metadata is attached to.
+   #
+   # ==== Defaults
+   # By default, when you create an object, there is no metadata.  So:
+   #
+   #    obj.metadata => {}
+   #
+   # ==== Adding 
+   # Add metadata in key/value pairs as you would to a hash.  Keys and 
+   # values must be ruby Strings.
+   #
+   #    obj.metadata[key] = value
+   #    obj.metadata.store(key, value)
+   #    obj.metadata.merge!({key => value})
+   #
+   # ==== Modifying
+   # Modify metadata as you would a hash.  Keys and values must be ruby 
+   # Strings.
+   #
+   #    obj.metadata[pre-existing-key] = new-value
+   #    obj.metadata.store(pre-existing-key, new-value)
+   #    obj.metadata.merge!({pre-existing-key => new-value})   
+   #
+   # ==== Deleting
+   # Delete metadata as you would a hash.  Keys must be ruby 
+   # Strings.
+   #
+   #    obj.metadata.delete(key)
+   #    obj.metadata.clear
+   #
+   # === Listable Metadata
+   # Listable metadata means atmos indexes the object by the key in the
+   # key/value metadata pair.  The keys of listable metadata are also known
+   # as listable tags.  Currently, an Atmos server can handle about 10k listable
+   # tags easily, so use judiciously with very large datasets.
+   #
+   # ==== Defaults
+   # By default, when you create an object, there is no listable metadata.  So:
+   #
+   #    obj.listable_metadata => {}
+   #
+   # ==== Adding 
+   # Add metadata in key/value pairs as you would to a hash.  Keys and 
+   # values must be ruby Strings.
+   #
+   #    obj.listable_metadata[key] = value
+   #    obj.listable_metadata.store(key, value)
+   #    obj.listable_metadata.merge!({key => value})
+   #
+   # ==== Modifying
+   # Modify metadata as you would a hash.  Keys and values must be ruby 
+   # Strings.
+   #
+   #    obj.listable_metadata[pre-existing-key] = new-value
+   #    obj.listable_metadata.store(pre-existing-key, new-value)
+   #    obj.listable_metadata.merge!({pre-existing-key => new-value})   
+   #
+   # ==== Deleting
+   # Delete metadata as you would a hash.  Keys must be ruby 
+   # Strings.
+   #
+   #    obj.listable_metadata.delete(key)
+   #    obj.listable_metadata.clear
+   #
+   # === System Metadata
+   # System metadata is a standard group of information maintained by Atmos for each object,
+   # such as +atime+, +mtime+, +type+, +policyname+.
+   #
+   # System metadata is not modifiable.
+   #
+   class Metadata < AttributeHashBase
+      LISTABLE     = 1
+      NON_LISTABLE = 2
+      SYSTEM       = 3
+
+
+      #
+      # This constructor is only meant for internal use.  To get the metadata on an object:
+      #
+      #    obj.metadata => Hash
+      #    obj.listable_metadata => Hash
+      #    obj.system_metadata => Hash
+      #
+      def initialize(obj, type)
+         raise Atmos::Exceptions::ArgumentException, "The 'obj' parameter cannot be nil." if (obj.nil?)
+         raise Atmos::Exceptions::ArgumentException, "The 'obj' parameter must have an id." if (obj.aoid.nil?)
+         raise Atmos::Exceptions::ArgumentException, "The 'type' parameter must be one of Atmos::Metadata::LISTABLE Atmos::Metadata::NON_LISTABLE Atmos::Metadata::SYSTEM." if (![SYSTEM, LISTABLE, NON_LISTABLE].include?(type))
+
+         super()
+         
+         @obj = obj
+         @type = type
+         
+         @header = (@type == LISTABLE) ? 'x-emc-listable-meta' : 'x-emc-meta'
+         @reload_action = (@type == SYSTEM) ? :list_system_metadata : :list_metadata
+         @set_action = (@type == LISTABLE) ? :set_listable_metadata : :set_metadata
+
+         reload(@reload_action, @obj.aoid)
+      end
+      
+      
+      #
+      # Adds the specified metadata to the object unless the object is representing system metadata.
+      #
+      # System metadata cannot be modified, so an Atmos::Exceptions::NotImplementedException 
+      # is thrown.
+      #
+      # The change is made on the Atmos server immediately.
+      # 
+      def []=(key,value)
+         raise Atmos::Exceptions::NotImplementedException, "System metadata cannot be modified." if (@type == SYSTEM)
+         raise Atmos::Exceptions::ArgumentException, "The 'value' parameter must be of type String'." if (!value.nil? && !value.kind_of?(String))
+         response = @obj.request.do(@set_action, :id => @obj.aoid, @header => "#{key}=#{value}")
+         reload(@reload_action, @obj.aoid)
+      end
+      
+      
+      #
+      # Deletes all metadata from the object unless the object is representing system metadata.
+      #
+      # System metadata cannot be modified, so an Atmos::Exceptions::NotImplementedException 
+      # is thrown.
+      #
+      # The change is made on the Atmos server immediately.
+      # 
+      def clear
+         raise Atmos::Exceptions::NotImplementedException, "System metadata cannot be modified." if (@type == SYSTEM)
+         reload(@reload_action, @obj.aoid)         
+         response = @obj.request.do(:delete_metadata, :id => @obj.aoid, 'x-emc-tags' => self.keys.join(','))
+         self.clear_without_atmos
+         reload(@reload_action, @obj.aoid)         
+      end
+      
+      
+      #
+      # Deletes the specified metadata from the object unless the 
+      # object is representing system metadata.  System metadata cannot
+      # be modified, so an <tt>Atmos::Exceptions::NotImplementedException</tt>
+      # is thrown.
+      #
+      # The deleted is executed on the Atmos server immediately.
+      # 
+      # Required:
+      #   *<tt>key</tt> - 
+      def delete(key)
+         raise Atmos::Exceptions::NotImplementedException, "System metadata cannot be modified." if (@type == SYSTEM)
+         response = @obj.request.do(:delete_metadata, :id => @obj.aoid, 'x-emc-tags' => key)
+         self.delete_without_atmos(key)
+         reload(@reload_action, @obj.aoid)         
+      end
+      
+      
+      #
+      # Returns +true+ if this Metadata object is representing listable metadata.
+      #
+      def listable?
+         @type == LISTABLE
+      end
+      
+      
+      #
+      # Returns +true+ if this Metadata object is representing non-listable metadata.
+      #
+      def non_listable?
+         @type == NON_LISTABLE
+      end
+      
+      
+      #
+      # Returns +true+ if this Metadata object is representing system metadata.
+      #
+      def system?
+         @type == SYSTEM
+      end
+      
+      
+      private
+         #
+         # This method is defined to override AttributeHashBase.validate_input_hash,
+         # which simply returns true.  This allows the base class to contain the
+         # method definitions for several standard Hash functions, yet allows the
+         # validation to be specialized for each subclass.
+         #
+         # Required:
+         # *<tt>h</tt> - the hash to validate
+         #
+         def validate_input_hash(h)
+            msg         = nil
+            bad_keys    = []
+            bad_values  = []
+            good_values = [:none, :read, :write, :full]
+            
+            h.each do |k,v|
+               bad_keys.push(k)   if (k.nil? || !k.kind_of?(String))
+               bad_values.push(v) if (v.nil? || !good_values.include?(v))
+            end
+            
+            msg = "The input has was bad: " if (!bad_keys.empty? || !bad_values.empty?)
+            msg += "bad keys: #{bad_keys.inspect} " if (!bad_keys.empty?)
+            msg += "bad values: #{bad_values.inspect}" if (!bad_values.empty?)
+            
+            raise Atmos::Exceptions::ArgumentException, msg if (!msg.nil?)
+         end
+
+   end
+   
+end