Class: Atmos::Store

Inherits:
Object
  • Object
show all
Defined in:
lib/atmos/store.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Store

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

Raises:



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# 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

Instance Attribute Details

#http ⇒ Object (readonly)

:nodoc:



4
5
6
 
# File 'lib/atmos/store.rb', line 4

def http
  @http
end

#proxy ⇒ Object (readonly)

:nodoc:



4
5
6
 
# File 'lib/atmos/store.rb', line 4

def proxy
  @proxy
end

#secret ⇒ Object (readonly)

:nodoc:



4
5
6
 
# File 'lib/atmos/store.rb', line 4

def secret
  @secret
end

#tenant ⇒ Object (readonly)

:nodoc:



4
5
6
 
# File 'lib/atmos/store.rb', line 4

def tenant
  @tenant
end

#uid ⇒ Object (readonly)

:nodoc:



4
5
6
 
# File 'lib/atmos/store.rb', line 4

def uid
  @uid
end

#uri ⇒ Object (readonly)

:nodoc:



4
5
6
 
# File 'lib/atmos/store.rb', line 4

def uri
  @uri
end

#user ⇒ Object (readonly)

:nodoc:



4
5
6
 
# File 'lib/atmos/store.rb', line 4

def user
  @user
end

Instance Method Details

#create(options = {}) ⇒ Object

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



134
135
136
 
# File 'lib/atmos/store.rb', line 134

def create(options = {})    
   Atmos::Object.new(self, :create, options)
end

#each_listable_tag(tag = nil) ⇒ Object

Tags are the key part of key/value metadata pairs.

Metadata that has been created as listable can be retrieved based on the tag. This method iterates through all listable tags in Atmos.

Tags can be hierarchical: foo/bar/baz. And each level anc have multiple tags under it. So to list all tags under the “foo” tag pass “foo” as the argument. To list all tags under “foo/bar”, pass “foo/bar” as the argument.



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/atmos/store.rb', line 174

def each_listable_tag(tag = nil) #:nodoc:
   token = ""
   headers = {}
   headers['x-emc-tags'] = tag if (!tag.nil?)
   
   while (!token.nil?)
      response = @request.do(:listable_tags, headers)
      response.each('x-emc-listable-tags') do |tag|
         yield tag
      end
      
      token = response['x-emc-token']
      headers['x-emc-token'] = token if (!token.nil?)
   end
end

#each_object_with_listable_tag(tag) ⇒ Object

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.

Raises:



199
200
201
202
203
204
205
206
207
208
 
# 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, idxml)
   end
end

#get(options) ⇒ Object

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



149
150
151
152
153
154
155
156
157
158
159
 
# 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 ⇒ Object

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



214
215
216
 
# File 'lib/atmos/store.rb', line 214

def server_version
   @server_version
end