Class: AWS::S3::ACL::Grant

Inherits:
Object show all
Includes:
SelectiveAttributeProxy
Defined in:
lib/aws/s3/acl.rb

Overview

A Policy is made up of one or more Grant objects. A grant sets a specific permission and grants it to the associated grantee.

When creating a new grant to add to a policy, you need only set its permission and then associate with a Grantee.

grant = ACL::Grant.new
=> #<AWS::S3::ACL::Grant (permission) to (grantee)>

Here we see that neither the permission nor the grantee have been set. Let’s make this grant provide the READ permission.

grant.permission = 'READ'
grant
=> #<AWS::S3::ACL::Grant READ to (grantee)>

Now let’s assume we have a grantee to the AllUsers group already set up. Just associate that grantee with our grant. 

grant.grantee = all_users_group_grantee
grant
=> #<AWS::S3::ACL::Grant READ to AllUsers Group>

And now are grant is complete. It provides READ permission to the AllUsers group, effectively making this object publicly readable without any authorization.

Assuming we have some object’s policy available in a local variable called policy, we can now add this grant onto its collection of grants.

policy.grants << grant

And then we send the updated policy to the S3 servers.

some_s3object.acl(policy)

Defined Under Namespace

Classes: Builder

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from SelectiveAttributeProxy

included

Constructor Details

#initialize(attributes = {}) {|_self| ... } ⇒ Grant

Returns a new instance of Grant.

Yields:

  • (_self)

Yield Parameters:



294
295
296
297
298
299
 
# File 'lib/aws/s3/acl.rb', line 294

def initialize(attributes = {})
  attributes = {'permission' => nil}.merge(attributes)
  @attributes = attributes
  extract_grantee!
  yield self if block_given?
end

Instance Attribute Details

#grantee ⇒ Object

Returns the value of attribute grantee.



236
237
238
 
# File 'lib/aws/s3/acl.rb', line 236

def grantee
  @grantee
end

Class Method Details

.grant(type) ⇒ Object

Returns stock grants with name type.

public_read_grant = ACL::Grant.grant :public_read
=> #<AWS::S3::ACL::Grant READ to AllUsers Group>

Valid stock grant types are:

  • :authenticated_read

  • :authenticated_read_acp

  • :authenticated_write

  • :authenticated_write_acp

  • :logging_read

  • :logging_read_acp

  • :logging_write

  • :logging_write_acp

  • :public_read

  • :public_read_acp

  • :public_write

  • :public_write_acp



258
259
260
261
262
263
264
265
 
# File 'lib/aws/s3/acl.rb', line 258

def grant(type)
  case type
  when *stock_grant_map.keys
    build_stock_grant_for type
  else
    raise ArgumentError, "Unknown grant type `#{type}'"
  end
end

Instance Method Details

#eql?(grant) ⇒ Boolean Also known as: ==

:nodoc:

Returns:

  • (Boolean) 


328
329
330
331
332
 
# File 'lib/aws/s3/acl.rb', line 328

def eql?(grant) #:nodoc:
  # This won't work for an unposted AmazonCustomerByEmail because of the normalization
  # to CanonicalUser but it will work for groups.
  to_s == grant.to_s
end

#hash ⇒ Object

:nodoc:



335
336
337
 
# File 'lib/aws/s3/acl.rb', line 335

def hash #:nodoc:
  to_s.hash
end

#inspect ⇒ Object

:nodoc:



320
321
322
 
# File 'lib/aws/s3/acl.rb', line 320

def inspect #:nodoc:
  "#<%s:0x%s %s>" % [self.class, object_id, self]
end

#permission=(permission_level) ⇒ Object

Set the permission for this grant.

grant.permission = 'READ'
grant
=> #<AWS::S3::ACL::Grant READ to (grantee)>

If the specified permisison level is not valid, an InvalidAccessControlLevel exception will be raised.



308
309
310
311
312
313
 
# File 'lib/aws/s3/acl.rb', line 308

def permission=(permission_level)
  unless self.class.valid_permissions.include?(permission_level)
    raise InvalidAccessControlLevel.new(self.class.valid_permissions, permission_level)
  end
  attributes['permission'] = permission_level
end

#to_s ⇒ Object

:nodoc:



324
325
326
 
# File 'lib/aws/s3/acl.rb', line 324

def to_s #:nodoc:
  [permission || '(permission)', 'to', grantee ? grantee.type_representation : '(grantee)'].join ' '
end

#to_xml ⇒ Object

The xml representation of this grant.



316
317
318
 
# File 'lib/aws/s3/acl.rb', line 316

def to_xml
  Builder.new(permission, grantee).to_s
end