Class: S33r::S3Object

Inherits:
Client
  • Object
show all
Defined in:
lib/s33r/s3_obj.rb

Instance Attribute Summary collapse

Attributes inherited from Client

#access, #canned_acl, #created_with_options, #expires, #secret, #subdomain, #use_ssl

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Client

#bucket_exists?, #bucket_names, #buckets, #change_log_target_status, #create_bucket, #delete_bucket, #get_acl, #get_bucket, init, #list_bucket, #listing, #logging, #logs_off, #logs_to, #make_private, #make_public, #public?, #put, #put_file, #request_defaults, #set_acl, #set_options, #settings, #url

Constructor Details

#initialize(key, value = nil, options = {}) ⇒ S3Object

options can include:

  • :bucket => Bucket: Bucket this object is attached to.

  • :metadata => Hash: metadata to use in building the object.

  • :amz_meta => Hash: metadata specific to Amazon.



19
20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/s33r/s3_obj.rb', line 19

def initialize(key, value=nil, options={})
  @key = key
  
  @value = value
  @content_type = 'text/plain'
  @render_as_attachment = false
  @amz_meta = options[:amz_meta] || {}
  
  set_bucket(options[:bucket])
  
  metadata = options[:metadata] || {}
  set_properties(metadata) unless metadata.empty?
end

Instance Attribute Details

#amz_meta ⇒ Object Also known as: meta

Metadata to set with x-amz-meta- style headers. Note that the bit after x-amz-meta- is stored for each key, rather than the full key.



12
13
14
 
# File 'lib/s33r/s3_obj.rb', line 12

def amz_meta
  @amz_meta
end

#bucket ⇒ Object (readonly)

Name of bucket this object is attached to.



8
9
10
 
# File 'lib/s33r/s3_obj.rb', line 8

def bucket
  @bucket
end

#content_type ⇒ Object

Returns the value of attribute content_type.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def content_type
  @content_type
end

#etag ⇒ Object

Returns the value of attribute etag.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def etag
  @etag
end

#key ⇒ Object

Returns the value of attribute key.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def key
  @key
end

#last_modified ⇒ Object

Returns the value of attribute last_modified.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def last_modified
  @last_modified
end

#owner ⇒ Object

Returns the value of attribute owner.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def owner
  @owner
end

#render_as_attachment ⇒ Object

Returns the value of attribute render_as_attachment.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def render_as_attachment
  @render_as_attachment
end

#size ⇒ Object

Returns the value of attribute size.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def size
  @size
end

#storage_class ⇒ Object

Returns the value of attribute storage_class.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def storage_class
  @storage_class
end

#value ⇒ Object

Returns the value of attribute value.



4
5
6
 
# File 'lib/s33r/s3_obj.rb', line 4

def value
  @value
end

Class Method Details

.from_file(filename, options = {}) ⇒ Object

To create an object which reads the content in from a file; you can then save the object to its associated bucket (if you like).



63
64
65
66
67
68
69
70
71
 
# File 'lib/s33r/s3_obj.rb', line 63

def self.from_file(filename, options={})
  mime_type = guess_mime_type(filename)
  content_type = mime_type.simplified
  value = File.open(filename).read
  key = options[:key] || filename
  
  options.merge!(:metadata => {:content_type => content_type})
  self.new(key, value, options)
end

.from_response(key, resp, options = {}) ⇒ Object

Create a new instance from a HTTP response. This is useful if you do a GET for a resource key and want to convert the response into an object; NB the response doesn’t necessarily contain all the metadata you might want - you need to do a HEAD for that.

key is the key for the resource (not part of the response). resp is a Net::HTTPResponse instance to parse. options is passed through to the constructor (see initialize).

Note that if the resp returns nil, a blank object is created.



131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/s33r/s3_obj.rb', line 131

def self.from_response(key, resp, options={})
  result = self.parse_response(resp)
  if result
    metadata, amz_meta, value = result
    options.merge!(:metadata => metadata, :amz_meta => amz_meta)
  else
    value = nil
  end
  
  self.new(key, value, options)
end

.from_text(key, text, options = {}) ⇒ Object

Create a new instance from a string.



74
75
76
77
78
79
 
# File 'lib/s33r/s3_obj.rb', line 74

def self.from_text(key, text, options={})
  content_type = 'text/plain'
  
  options.merge!(:metadata => {:content_type => content_type})
  self.new(key, text, options)
end

.from_xml_node(doc, options = {}) ⇒ Object

Create a new instance from an XML document; N.B. this instance will have no value associated with it (yet). Call the load method to populate it.

options is passed to the constructor.



94
95
96
97
98
99
 
# File 'lib/s33r/s3_obj.rb', line 94

def self.from_xml_node(doc, options={})
  metadata = self.parse_xml_node(doc)
  
  options.merge!(:metadata => metadata)
  self.new(metadata[:key], nil, options)
end

.from_xml_string(xml_str, options = {}) ⇒ Object

Set properties of the object from an XML string.

xml_str should be a string representing a full XML document, containing a <Contents> element as its root element.



85
86
87
 
# File 'lib/s33r/s3_obj.rb', line 85

def self.from_xml_string(xml_str, options={})
  self.from_xml_node(XML.get_xml_doc(xml_str))
end

.parse_response(resp) ⇒ Object

Parse the response returned by GET on a resource key within a bucket.

resp is a Net::HTTPResponse instance.

Returns an array [metadata, response.body]; or nil if the object doesn’t exist.



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/s33r/s3_obj.rb', line 150

def self.parse_response(resp)
  resp_headers = resp.to_hash
  
  # If there's no etag, there's no content in the resource.
  if resp_headers['etag']
    metadata = {}
    metadata[:last_modified] = resp_headers['last-modified'][0]
    metadata[:etag] = resp_headers['etag'][0]
    metadata[:size] = resp_headers['content-length'][0]
    metadata[:content_type] = resp_headers['content-type'][0]
    
    content_disposition = resp_headers['content-disposition']
    if content_disposition
      content_disposition = content_disposition[0]
      if /^attachment/ =~ content_disposition
        metadata[:render_as_attachment] = true
      end
    end
    
    # x-amz-meta- response headers.
    interesting_header = Regexp.new(METADATA_PREFIX)
    new_amz_meta = {}
    resp.each_header do |key, value|
      new_amz_meta[key.gsub(interesting_header, '')] = value if interesting_header =~ key
    end
  
    # The actual content of the S3 object.
    value = resp.body
  
    [metadata, new_amz_meta, value]
  else
    nil
  end
end

.parse_xml_node(doc) ⇒ Object

Get properties of the object from an XML document, e.g. as returned in a bucket listing.

doc: XML::Document instance to parse to get properties for this object.

Returns the metadata relating to the object, as stored on S3.



106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/s33r/s3_obj.rb', line 106

def self.parse_xml_node(doc)
  metadata = {}
  metadata[:key] = doc.xget('Key')
  metadata[:last_modified] = doc.xget('LastModified')
  metadata[:etag] = doc.xget('ETag')
  metadata[:size] = doc.xget('Size')
  
  # Build representation of the owner.
  user_xml_doc = doc.find('Owner').to_a.first
  metadata[:owner] = S3ACL::CanonicalUser.from_xml(user_xml_doc)
  
  metadata
end

Instance Method Details

#[](key) ⇒ Object

Get metadata on the object.



191
192
193
 
# File 'lib/s33r/s3_obj.rb', line 191

def [](key)
  amz_meta[key]
end

#[]=(key, value) ⇒ Object

Set metadata on the object.



186
187
188
 
# File 'lib/s33r/s3_obj.rb', line 186

def []=(key, value)
  amz_meta[key] = value
end

#set_bucket(bucket_instance) ⇒ Object Also known as: bucket=

Set a bucket instance as the default bucket for this object.



34
35
36
37
38
39
40
 
# File 'lib/s33r/s3_obj.rb', line 34

def set_bucket(bucket_instance)
  if bucket_instance
    @bucket = bucket_instance
    set_options(@bucket.settings)
    extend(InBucket)
  end
end

#set_properties(metadata) ⇒ Object

Set the properties of the object from some metadata name-value pairs.

metadata is a hash of properties and their values, used to set the corresponding properties on the object.



47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/s33r/s3_obj.rb', line 47

def set_properties(metadata)
  # required properties
  @etag = metadata[:etag].gsub("\"", "") if metadata[:etag]
  @last_modified = Time.parse(metadata[:last_modified]) if metadata[:last_modified]
  @size = metadata[:size].to_i if metadata[:size]
  @render_as_attachment = metadata[:render_as_attachment] || false

  # only set if creating object from XML (not available otherwise)
  @owner ||= metadata[:owner]
  
  # only set if creating object from HTTP response
  @content_type = metadata[:content_type] if metadata[:content_type]
end