s3_acl.rb in s33r-0.5

- old
+ new

@@ -13,23 +13,23 @@
     # An S3 ACL document, incorporating one or more Grants
     # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingACL.html).
     # 
     # Represents both retrieved ACL XML or can be built up 
     # using objects and converted to XML.
-    # NB the ACLDoc is oblivious to the resource it is going 
+    # NB the Policy is oblivious to the resource it is going 
     # to be applied to.
-    class ACLDoc
+    class Policy
       # List of grants to be applied.
       attr_accessor :grants, :owner
       
       # +owner+: S33r::S3ACL::CanonicalUser instance
       def initialize(owner, grants=[])
         @grants = grants
         @owner = owner
       end
       
-      # Create an ACLDoc instance from a raw Access Control Policy XML document.
+      # Create an Policy instance from a raw Access Control Policy XML document.
       # 
       # +acl_xml+ is a raw Access Control Policy XML string (NOT libxml Document or Node).
       # 
       # Returns nil if the ACL XML is nil.
       def self.from_xml(acl_xml)
@@ -48,11 +48,11 @@
           permission = g.xget('Permission')
           
           grants << Grant.new(grantee, permission)
         end
         
-        ACLDoc.new(owner, grants)
+        Policy.new(owner, grants)
       end
       
       # Generate AccessControlPolicy XML document.
       def to_xml
         xml_str = ""
@@ -79,16 +79,14 @@
       # Add a grant to the ACL document.
       # 
       # Returns true if grant was added;
       # false otherwise (grant already exists).
       def add_grant(grant)
-        if @grants.include?(grant)
-          return false
-        else
+        unless @grants.include?(grant)
           @grants << grant
-          return true
         end
+        self
       end
       
       # Remove a grant from the ACL document. Note that if you
       # set a grant for an AmazonCustomer, you want be able to remove it by
       # specifying the same grant. This is because grants set by AmazonCustomer 
@@ -98,10 +96,11 @@
       # 
       # Returns true if grant was removed;
       # false if it wasn't in the document.
       def remove_grant(grant)
         @grants.delete_if { |g| grant == g }
+        self
       end
       
       # Does the ACL contain a grant for public reads?
       # (i.e. grants holds a Grant object for :all_users with :read permission)
       def public_readable?
@@ -115,46 +114,19 @@
       # Add a public READ permission to this instance.
       def add_public_read_grant
         add_grant(Grant.public_read_grant)
       end
       
-      # Does the ACL make the associated resource available as a log target?
-      def log_targetable?
-        log_target_grants = Grant.log_target_grants
-        log_target_grants.each { |g| return false if !grants.include?(g) }
-        return true
+      # Remove the public READ permission from this instance.
+      def remove_public_read_grant
+        remove_grant(Grant.public_read_grant)
       end
       
-      # Add permissions to an instances which give READ_ACL
-      # and WRITE permissions to the LogDelivery group. Used
-      # to enable a bucket as a logging destination.
-      # 
-      # Returns true if grants added, false otherwise
-      # (if already a log target).
-      def add_log_target_grants
-        if log_targetable?
-          return false
-        else
-          Grant.log_target_grants.each { |g| add_grant(g) }
-          return true
-        end
+      # String representation of the policy.
+      def to_s
+        @grants.inject('') {|acc, grant| acc += "* " + grant.to_s + "\n"}
       end
-      
-      # Remove log target ACLs from the document.
-      # 
-      # Returns true if all log target grants were removed;
-      # false otherwise.
-      # 
-      # NB even if this method returns false, that doesn't mean
-      # the bucket is still a log target. Use log_targetable? to check
-      # whether a bucket can be used as a log target.
-      def remove_log_target_grants
-        ok = true
-        Grant.log_target_grants.each { |g| ok = ok and remove_grant(g) }
-        ok
-      end
-      
     end
   
     # Representation of an S3 Grant 
     # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingGrantees.html).
     # 
@@ -169,11 +141,12 @@
         if permission.is_a? String
           @permission = permission
         else
           @permission = PERMISSIONS[permission]
         end
-        raise InvalidPermission, "Permission #{permission.to_s} is not a valid permission specifier" if @permission.nil?
+        raise S3Exception::InvalidPermission, \
+        "Permission #{permission.to_s} is not a valid permission specifier" if @permission.nil?
       end
       
       # Note that setting a grant for an Amazon customer is the
       # same as setting a grant for the CanonicalUser who owns the 
       # specified email address. So when you get the ACL back, it will
@@ -194,19 +167,10 @@
       # group type.
       def Grant.public_read_grant
         Grant.new(Group.new(:all_users), :read)
       end
       
-      # Generator for a grant which gives the LogDelivery group
-      # write and read_acl permissions on a bucket.
-      # 
-      # Returns an array with the two required Grant instances.
-      def Grant.log_target_grants
-        log_delivery_group = Group.new(:log_delivery)
-        [Grant.new(log_delivery_group, :read_acl), Grant.new(log_delivery_group, :write)]
-      end
-      
       # Convert a Grant object into an XML fragment.
       def to_xml
         xml_str = ""
         xml = S33r::OrderlyXmlMarkup.new(:target => xml_str, :indent => 0)
         
@@ -237,10 +201,14 @@
           return false
         end
         return true
       end
       
+      def to_s
+        "#{@grantee.to_s} has permission #{@permission}"
+      end
+      
     end
 
     # Abstract representation of an S3 Grantee.
     class Grantee
       attr_reader :grantee_type
@@ -289,10 +257,14 @@
       
       def initialize(email_address)
         @grantee_type = GRANTEE_TYPES[:amazon_customer]
         @email_address = email_address
       end
+      
+      def to_s
+        "Amazon customer with address '#{@email_address}"
+      end
     end
     
     # An S3 user.
     class CanonicalUser < Grantee
       attr_accessor :user_id, :display_name
@@ -313,10 +285,14 @@
       def self.from_xml(user_xml_doc)
         user_id = user_xml_doc.xget('ID')
         display_name = user_xml_doc.xget('DisplayName')
         new(user_id, display_name)
       end
+      
+      def to_s
+        "Canonical user '#{@display_name}' (with user ID '#{@user_id}')"
+      end
     end
     
     # One of the predefined S3 groups.
     # 
     # A group must have a type (AllUsers or AuthenticatedUsers).
@@ -325,13 +301,17 @@
       
       # The type of group. A key from S3_GROUP_TYPES to 
       # one of the pre-defined Amazon group types.
       def initialize(group_type)
         unless S3_GROUP_TYPES.has_key?(group_type)
-          raise InvalidS3GroupType, 'No such group type #{group_type}'
+          raise S3Exception::InvalidGroupType, 'No such group type #{group_type}'
         end
         @group_type = S3_GROUP_TYPES[group_type]
         @grantee_type = GRANTEE_TYPES[:group]
+      end
+      
+      def to_s
+        "Group '#{@group_type}'"
       end
     end
     
   end
 end