aws-sdk 1.0.0

data/lib/aws/s3/multipart_upload_collection.rb

@@ -0,0 +1,78 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+require 'aws/s3/prefix_and_delimiter_collection'
+require 'aws/s3/multipart_upload'
+require 'aws/s3/s3_object'
+
+module AWS
+  class S3
+
+    # Represents the uploads in progress for a bucket.
+    #
+    # @example Finding uploads by prefix
+    #  bucket.multipart_uploads.with_prefix("photos/").
+    #    map { |upload| upload.object.key }
+    #  # => ["photos/1.jpg", "photos/2.jpg", ...]
+    #
+    # @example Browsing with a tree interface
+    #  bucket.multipart_uploads.with_prefix("photos").as_tree.
+    #    children.select(&:branch?).map(&:prefix)
+    #  # => ["photos/2010", "photos/2011", ...]
+    #
+    # @see Tree
+    class MultipartUploadCollection
+
+      include Enumerable
+      include Model
+      include PrefixAndDelimiterCollection
+
+      # @return [Bucket] The bucket in which the uploads are taking
+      #   place.
+      attr_reader :bucket
+
+      # @private
+      def initialize(bucket, opts = {})
+        @bucket = bucket
+        super
+      end
+
+      protected
+      def each_member_in_page(page, &block)
+        super
+        page.uploads.each do |u|
+          object = S3Object.new(bucket, u.key)
+          upload = MultipartUpload.new(object, u.upload_id)
+          yield(upload)
+        end
+      end
+
+      protected
+      def list_request(options)
+        client.list_multipart_uploads(options)
+      end
+
+      protected
+      def limit_param; :max_uploads; end
+
+      protected
+      def pagination_markers; super + [:upload_id_marker]; end
+
+      protected
+      def page_size(resp); super + resp.uploads.size; end
+
+    end
+
+  end
+end

data/lib/aws/s3/object_collection.rb

@@ -0,0 +1,159 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+require 'aws/s3/s3_object'
+require 'aws/s3/prefix_and_delimiter_collection'
+
+module AWS
+  class S3
+
+    # Represents a collection of S3 objects.
+    #
+    # == Getting an S3Object by Key
+    #
+    # If you know the key of the object you want, you can reference it this way:
+    #
+    #   # this will not make any requests against S3
+    #   object = bucket.objects['foo.jpg']
+    #   object.key #=> 'foo.jpg'
+    # 
+    # == Finding objects with a Prefix
+    #
+    # Given a bucket with the following keys:
+    #
+    #   photos/sunset.jpg
+    #   photos/sunrise.jpg
+    #   photos/winter.jpg
+    #   videos/comedy.mpg
+    #   videos/dancing.mpg
+    #
+    # You can list objects that share a prefix:
+    #
+    #   bucket.objects.with_prefix('videos').collect(&:key)
+    #   #=> ['videos/comedy.mpg', 'videos/dancing.mpg']
+    #   
+    # == Exploring Objects with a Tree Interface
+    #
+    # Given a bucket with the following keys:
+    #
+    #   README.txt
+    #   videos/wedding.mpg
+    #   videos/family_reunion.mpg
+    #   photos/2010/house.jpg
+    #   photos/2011/fall/leaves.jpg
+    #   photos/2011/summer/vacation.jpg
+    #   photos/2011/summer/family.jpg
+    #
+    #   tree = bucket.objects.with_prefix.prefix('photos').as_tree
+    #
+    #   directories = tree.children.select(&:branch?).collect(&:prefix)
+    #   #=> ['photos/2010', 'photos/2011']
+    #
+    class ObjectCollection
+
+      include Model
+      include Enumerable
+      include PrefixAndDelimiterCollection
+
+      # @param [Bucket] The S3 bucket this object collection belongs to.
+      def initialize(bucket, options = {})
+        @bucket = bucket
+        super
+      end
+
+      # @return [Bucket] The bucket this collection belongs to.
+      attr_reader :bucket
+
+      # Writes a new object to S3.
+      #
+      # The first param is the key you want to write this object to.
+      # All other params/options are documented in {S3Object#write}.
+      #
+      # @see S3Object#write
+      #
+      # @param [String] key Where in S3 to write the object.
+      # @return [S3Object]
+      def create key, *args
+        self[key].write(*args)
+      end
+
+      # Returns an S3Object given its name.  For example:
+      #
+      # @example
+      #   
+      #   object = bucket.objects['file.txt']
+      #   object.class #=> S3Object
+      #
+      # @param [String] key The object key.
+      # @return [S3Object]
+      def [] key
+        S3Object.new(bucket, key.to_s)
+      end
+
+      # (see PrefixedCollection#with_prefix)
+      def with_prefix prefix, mode = :replace
+        super(prefix, mode)
+      end
+
+      # Iterates the collection, yielding instances of S3Object.
+      #
+      # Use break or raise an exception to terminate the enumeration.
+      #
+      # @param [Hash] options
+      # @option options [Integer] :limit (nil) The maximum number of 
+      #   objects to yield.
+      # @option options [Integer] :batch_size (1000) The number of objects to
+      #   fetch each request to S3.  Maximum is 1000 keys at time. 
+      # @return [nil]
+      def each options = {}, &block
+        super
+      end
+
+      # @private
+      protected
+      def each_member_in_page(page, &block)
+        super
+        page.contents.each do |content|
+          yield(S3Object.new(bucket, content.key))
+        end
+      end
+
+      # @private
+      protected
+      def list_request(options)
+        client.list_objects(options)
+      end
+
+      # @private
+      protected
+      def limit_param
+        :max_keys
+      end
+
+      # @private
+      protected
+      def page_size resp
+        super + resp.contents.size
+      end
+
+      # @private
+      protected
+      def next_markers page
+        { :marker => (last = page.contents.last and last.key) }
+      end
+
+    end
+
+  end
+end

data/lib/aws/s3/object_metadata.rb

@@ -0,0 +1,67 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+
+module AWS
+  class S3
+
+    # Returns an object that represents the metadata for an S3 object.
+    class ObjectMetadata
+
+      include Model
+
+      # @param [S3Object]
+      # @param [Hash] options
+      # @option options [String] :version_id A specific version of the object
+      #   to get metadata for
+      def initialize(object, options = {})
+        @object = object
+        @version_id = options[:version_id]
+        super
+      end
+
+      # @return [S3Object]
+      attr_reader :object
+
+      # Returns the value for the given name stored in the S3Objects
+      # metadata:
+      #
+      #   bucket.objects['myobject'].metadata['purpose']
+      #   # returns nil if the given metadata key has not been set
+      #
+      # @return [String,nil] Returns the metadata for the given name.
+      def [] name
+        to_h[name.to_s]
+      end
+
+      # Proxies the method to {#[]}.
+      # @return (see #[])
+      def method_missing name
+        self[name]
+      end
+
+      # @return [Hash] Returns the user-generated metadata stored with 
+      #   this S3 Object.
+      def to_h
+        options = {}
+        options[:bucket_name] = object.bucket.name
+        options[:key] = object.key
+        options[:version_id] = @version_id if @version_id
+        client.head_object(options).meta
+      end
+
+    end
+
+  end
+end

data/lib/aws/s3/object_upload_collection.rb

@@ -0,0 +1,83 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+require 'aws/s3/paginated_collection'
+require 'aws/s3/multipart_upload'
+require 'aws/s3/multipart_upload_collection'
+require 'aws/s3/s3_object'
+
+module AWS
+  class S3
+
+    # Represents uploads in progress for a single object.
+    #
+    # @example Cancel all uploads for an object
+    #  object.multipart_uploads.each(&:abort)
+    #
+    # @example Get an upload by ID
+    #  object.multipart_uploads[id]
+    class ObjectUploadCollection
+
+      include Enumerable
+      include Model
+
+      # @return [S3Object] The object to which the uploads belong.
+      attr_reader :object
+
+      # @private
+      def initialize(object, opts = {})
+        @all_uploads =
+          MultipartUploadCollection.new(object.bucket).
+          with_prefix(object.key)
+        @object = object
+        super
+      end
+
+      # Creates a new multipart upload.  It is usually more
+      # convenient to use {S3Object#multipart_upload}.
+      def create(options = {})
+        options[:storage_class] = :reduced_redundancy if
+          options.delete(:reduced_redundancy)
+        initiate_opts = {
+          :bucket_name => object.bucket.name,
+          :key => object.key
+        }.merge(options)
+        id = client.initiate_multipart_upload(initiate_opts).upload_id
+        MultipartUpload.new(object, id)
+      end
+
+      # Iterates the uploads in the collection.
+      #
+      # @yieldparam [MultipartUpload] upload An upload in the
+      #   collection.
+      # @return [nil]
+      def each(options = {}, &block)
+        @all_uploads.each(options) do |upload|
+          yield(upload) if upload.object.key == @object.key
+        end
+        nil
+      end
+
+      # @return [MultipartUpload] An object representing the upload
+      #   with the given ID.
+      #
+      # @param [String] id The ID of an upload to get.
+      def [] id
+        MultipartUpload.new(object, id)
+      end
+
+    end
+
+  end
+end

data/lib/aws/s3/object_version.rb

@@ -0,0 +1,141 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/model'
+require 'aws/errors'
+
+module AWS
+  class S3
+
+    # Represents a single version of an S3Object.
+    #
+    # When you enable versioning on a S3 bucket, writing to an object 
+    # will create an object version instead of replacing the existing 
+    # object.
+    class ObjectVersion
+
+      include Model
+
+      # @param [S3Object] object The object this is a version of.
+      # @param [String] version_id The unique id for this version.
+      # @param [Hash] options
+      # @option options [Boolean] :delete_marker Is this version a
+      #   delete marker?
+      def initialize(object, version_id, options = {})
+        @object = object
+        @version_id = version_id
+        @delete_marker = options[:delete_marker]
+        super
+      end
+
+      # @return [S3Object] the object this is a version of.
+      attr_reader :object
+
+      def bucket
+        object.bucket
+      end
+
+      # @return [String] The unique version identifier.
+      attr_reader :version_id
+
+      # @return (see S3Object#key)
+      def key
+        object.key
+      end
+
+      # @see S3Object#head
+      # @return (see S3Object#head)
+      def head
+        object.head(:version_id => @version_id)
+      end
+
+      # @see S3Object#etag
+      # @return (see S3Object#etag)
+      def etag
+        head.etag
+      end
+
+      # @return (see S3Object#content_length)
+      def content_length
+        head.content_length
+      end
+
+      # @note (see S3Object#content_type)
+      # @see S3Object#content_type
+      # @return (see S3Object#content_type)
+      def content_type
+        head.content_type
+      end
+
+      # @see S3Object#metadata
+      # @return (see S3Object#metadata)
+      def metadata
+        object.metadata(:version_id => @version_id)
+      end
+
+      # Reads the data from this object version.
+      # @see S3Object#read
+      # @options (see S3Object#read)
+      # @return (see S3Object#read)
+      def read options = {}, &block
+        object.read(options.merge(:version_id => @version_id), &block)
+      end
+
+      # Deletes this object version from S3.
+      # @return (see S3Object#delete)
+      def delete
+        object.delete(:version_id => @version_id)
+      end
+
+      # @return [Boolean] Returns this if this is the latest version of
+      #   the object, false if the object has been written to since
+      #   this version was created.
+      def latest?
+        object.versions.latest.version_id == self.version_id
+      end
+
+      # If you delete an object in a versioned bucket, a delete marker
+      # is created.  
+      # @return [Boolean] Returns true if this version is a delete marker.
+      def delete_marker?
+        if @delete_marker.nil?
+          begin
+            # S3 responds with a 405 (method not allowed) when you try
+            # to HEAD an s3 object version that is a delete marker
+            metadata['foo'] 
+            @delete_marker = false
+          rescue Errors::MethodNotAllowed => error
+            @delete_marker = true
+          end
+        end
+        @delete_marker
+      end
+
+      # @return [Boolean] Returns true if the other object version has
+      #   the same s3 object key and version id.
+      def ==(other)
+        other.kind_of?(ObjectVersion) and
+          other.object == object and
+          other.version_id == version_id
+      end
+
+      alias_method :eql?, :==
+
+      # @private
+      def inspect
+        "<#{self.class}:#{object.bucket.name}:#{object.key}:#{version_id}>"
+      end
+
+    end
+  end
+end