class Atmos::Store

Public Class Methods

new(options = {}) click to toggle source

Create and validate a connection to an Atmos server. This API supports both the object interface and the namespace interface. Proxy support has been tested against squid 2.7.STABLE9 on ubuntu 10.10.

If you have used Atmos Online this example will look familiar:

store = Atmos::Store.new(:url    => 'https://accesspoint.atmosonline.com'
                         :uid    => 'ab9090e754b549eeb460a468abdf7fc2/A797558526171ea693ce'
                         :secret => 'pEauABL07ujkF2hJN7r6wA9/HPs='
                        )

Required:

  • :url - the url to the Atmos server the Store object will

    represent (e.g. \https://accesspoint.atmosonline.com)
  • :uid - a string, “<tenant id>/<username>”

    ("Full Token ID" in Atmos Online)
  • :secret - a string, the secret key associated with the user

    (shared secret for a token in Atmos Online)

– Optional:

  • :proxy - url to proxy of the form

    scheme://[user[:password]@]host:port
# File lib/atmos/store.rb, line 31
def initialize(options = {})
  valid   = [:url,:secret,:uid,:tag,:version,:proxy,:unsupported].freeze
  invalid = options.keys - valid
  raise Atmos::Exceptions::ArgumentException,
  "Unrecognized options: #{invalid.inspect}" if (!invalid.empty?)
  Atmos::LOG.info("Store.initialize: options: #{options.inspect}")

  raise Atmos::Exceptions::ArgumentException,
  "The kind of XML parser you would like to use has not been set yet." if (Atmos::Parser::parser.nil?)         

  @uri    = URI.parse(options[:url])
  @secret = options[:secret]
  @uid    = options[:uid]
  @tag    = options[:tag]
  
  if (@uid =~ /^([^\/]+)\/([^\/]+)$/)
    @tenant = $1
    @user = $2
  else
    @tenant = nil
    @user = @uid
  end
 
 
  proxyopts = [nil]
  if !options[:proxy].nil?

    proxyurl = URI.parse(options[:proxy])

    if (!proxyurl.kind_of?(URI::HTTP) &&
        !proxyurl.kind_of?(URI::HTTPS))

      msg = "Please check the proxy URL scheme.  "
      msg += "It's not being recognized as an http or https url.  "
      msg +=  "You do have to include the http(s):// part."
      raise Atmos::Exceptions::ArgumentException, msg
    end
    
    Atmos::LOG.warn("using proxy: #{options[:proxy]}")
    proxyopts = [proxyurl.host, proxyurl.port]

    if (proxyurl.userinfo =~ /([^:]+):([^:])/)
      proxyopts.push([$1, $2])
    elsif (!proxyurl.userinfo.nil?)
      proxyopts.push(proxyurl.userinfo)
    end
    Atmos::LOG.info("proxy options: #{proxyopts.inspect}")
  end


  @http = Net::HTTP.Proxy(*proxyopts).new(@uri.host, @uri.port)
  if @uri.scheme == 'https'
     @http.use_ssl = true
     @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
  end
  Atmos::LOG.debug("http class: #{@http.inspect}")

  @request = Atmos::Request.new(:store => self, :default_tag => @tag)
  res = @request.do(:get_service_info)
                                           
  if (res.http_response.kind_of?(Net::HTTPMovedPermanently))
     rurl = (res['location'].nil?) ? res.body.match(/<a href=\"([^>]+)\">/i)[1] : res['location']
     raise ArgumentException, "The Atmos URL is redirecting.  Please supply the correct URL. (#{@uri.to_s} => #{rurl})"
  end
  
  @server_version = Atmos::Parser::response_get_string(res.http_response, '//xmlns:Atmos')            

  if ((!SUPPORTED_VERSIONS.include?(@server_version)) &&
      (options[:unsupported] != true))
    msg ="This library does not support Atmos version #{@server_version}.  "
    msg +=  "Supported versions: #{SUPPORTED_VERSIONS.inspect}.  "
    msg += "To silence this, pass :unsupported => true when instantiating."

    raise Atmos::Exceptions::NotImplementedException, msg
  end


  if (!options[:version].nil? && !options[:version].eql?(@server_version))
    raise Atmos::Exceptions::ArgumentException, 
    "Atmos server version and version you were expecting do not match." 
  end
end

Public Instance Methods

create(options = {}) click to toggle source

Create an Atmos object. This can be done with no arguments, or with any of the listed optional arguments. Checksums are not yet supported.

If no data is passed, a 0 length object is created. If no ACLs are passed, the default access control is applied. If no mime type is passed, the default is 'binary/octet-stream'.

Optional:

  • :user_acl - hash of username/permissions (:none, :read, :write, :full) pairs

  • :group_acl - hash of groupname/permissions (:none, :read, :write, :full) pairs

  • :metadata - hash of string pairs

  • :listable_metadata - hash of string pairs

  • :mimetype - defaults to application/octet-stream

  • :data - a String or an IO stream

  • :length - a number (requires :data)

  • :namespace - name for namespace interface instead of object interface

# File lib/atmos/store.rb, line 134
def create(options = {})    
   Atmos::Object.new(self, :create, options)
end
each_object_with_listable_tag(tag) { |object(self, :get, :id => idxml)| ... } click to toggle source

Iterate through objects that are indexed by a particular tag. Tag can't be nil, and must be a ruby String. Note that as the objects are instantiated, ACLs and Metadata will be retrieved, and object data will not.

Note that there may not be any objects associated with a listable tag even though that tag shows up when listing all listable tags.

# File lib/atmos/store.rb, line 199
def each_object_with_listable_tag(tag)
   raise Atmos::Exceptions::ArgumentException, "The 'tag' parameter cannot be nil." if (tag.nil?)
   raise Atmos::Exceptions::ArgumentException, "Only one tag is allowed at a time." if (!tag.kind_of?(String))

   response = @request.do(:list_objects, 'x-emc-include-meta' => 0, 'x-emc-tags' => tag)

   Atmos::Parser::response_get_array(response, '//xmlns:ObjectID').each do |idxml|
      yield Atmos::Object.new(self, :get, :id => idxml)
   end
end
get(options) click to toggle source

Retrieve an Atmos object given an id.

When the object is retrieved, the ACL and Metadata information is loaded from the server.

The blob data is not loaded until accessed, so it can be progressively downloaded.

Mutually exclusive, one required:

  • :id - the id of the object to retrieve

  • :namespace - the namespace key of the object to retrieve

# File lib/atmos/store.rb, line 149
def get(options)
          
   # can't both be set, can't both be empty
   if (!options[:id].nil? && !options[:namespace].nil?)
      raise Atmos::Exceptions::ArgumentException, "One of :id, :namespace is required, but not both."
   elsif (options[:id].nil? && options[:namespace].nil?)
      raise Atmos::Exceptions::ArgumentException, "One of :id, :namespace is required."
   end
   
   Atmos::Object.new(self, :get, options)
end
server_version() click to toggle source

Returns the version of the Atmos server authenticated to, as a string.

# File lib/atmos/store.rb, line 214
def server_version
   @server_version
end