NAME

Net::Amazon::S3::ACL::Grant - represent a grant in a S3 ACL

SYNOPSIS

# if you have some XPathContext and node...
my $grant = Net::Amazon::S3::ACL::Grant->create({
   xpc  => $xpc, 
   node => $node,
});

# otherwise
$grant = Net::Amazon::S3::ACL::Grant->create({
   target      => 'foo@example.com',
   permissions => [qw( READ WRITE )],
});

# or also
$grant = Net::Amazon::S3::ACL::Grant->canonical(
   'foo@example.com' => [qw( READ WRITE )],
);

# given a $grant...
my $key = $grant->key();
my $permissions = $grant->permissions();
print "permissions for '$key': [@$permissions]\n";

$grant->add_permissions(qw( READ_ACP WRITE_ACP ));
$grant->delete_permissions('WRITE');

die 'invalid!' unless $grant->is_valid();

$grant->parse($xpc, $node);
print $grant->stringify();

DESCRIPTION

This class represents a single grant in the grants hash of Net::Amazon::S3::ACL. This is actually a base class that has been specialised into three implementations, representing the three different ways to specify a grantee in AWS as of writing this.

INTERFACE

The following functions are all methods, i.e. they have to be called with the OO syntax.

new

not to be called directly, only serves for derived classes.

create

my $grant = Net::Amazon::S3::ACL::Grant->create({
   xpc  => $xpc,  # XPathContext
   node => $node,
});
my $grant = Net::Amazon::S3::ACL::Grant->create({
   target      => $target,
   permissions => $permissions,  # optional
});

factory class method to generate a new object of the rigth type. The natively supported types are:

• Email

• URI

• ID

and are available in the package array @Classes, in the given order. They are scanned in order to find a suitable class to handle each particular case, ID serving as a fall-back. Each of them maps to a subclass Net::Amazon::S3::ACL::Grant::Type.

You should pass either suitable data for parsing (in the form of an XPathContext object and a node within), or a target description for DWIM and some permissions (optional):

xpc, node

data for XML parsing

target, permissions (these are optional)

data for DWIM elaboration of the grant.

Returns the newly created object or complains about not having a suitable subclass to handle the specific case.

class_for

my $class_name = Net::Amazon::S3::ACL::Grant->class_for($type);

given a subtype, returns the name of the class supporting that subtype. In the implementation it just returns Net::Amazon::S3::ACL::Grant::Type, but it can be overridden (it used by the "create" method).

canonical

my $grant = Net::Amazon::S3::ACL::Grant->canonical($target, $perm_string);
my $grant = Net::Amazon::S3::ACL::Grant->canonical($target, $perm_aref);
my $grant = Net::Amazon::S3::ACL::Grant->canonical($target, $other_grant);

This is a class method.

Tries to apply a Do What I Mean logic upon its input, used to figure out what to do with these parameters when "add"ing or "delete"-ing stuff. Two positional parameters are accepted:

target

a string that describes the particular item we're referring to. It represents the grantee to which a particular grant applies. You can choose among the following ones:

AUTHENTICATED

AUTH

refers to the group of "all authenticated AWS customers". This is canonicalised to the URI of the group, i.e. http://acs.amazonaws.com/groups/global/AuthenticatedUsers.

ALL

ANY

ANONYMOUS

ANON

*

refers to the anonymous user group, i.e. any user without authentication. It's canonicalised to the URI of the group, i.e. http://acs.amazonaws.com/groups/global/AllUsers.

anything resembling a HTTP URI

the target is left as-is and the item type can be set to URI if the conditions apply.

anything with an @ inside

the target is left as-is and the item type can be set to email if the conditions apply.

anything else

the target is left as-is and the item type can be set to ID if the conditions apply.

item

this can be different things, which yield to different behaviours:

a string

in this case, the string is intepreted as a single permission. The canonicalisation for this permission (case-insensitive) is based on the following mappings:

READ

R

<

set the READ permission

WRITE

W

>

set the WRITE permission

READ_ACP

READ-ACP

RP

set the READ_ACP permission

WRITE_ACP

WRITE-ACP

WP

set the WRITE_ACP permission

FULL_CONTROL

FULL

F

*

set the FULL_CONTROL permission

a blessed (hash) reference

in this case the reference is supposed to be a valid Net::Amazon::S3::ACL::Grant object, and it is simply returned back.

an array reference

this fall back to the string case, because every item in the array is interpreted as a string above.

If the item parameter is already a "valid" acl element, then the target parameter could be completely overridden and read from the item itself. For example, if the input item is the following hash reference:

{
   type =>  'email',
   email => 'whatever@example.com',
}

the target will be set to the email address whatever the input value is.

On the other hand, if the item part is not a valid acl element, the target will be used to guess the actual item type and set the item accordingly. This is the very base of the DWIM behaviour.

is_valid

my $bool = $grant->is_valid();

a grant is assumed to be valid if it contains at least one permission.

add_permissions

$grant->add_permissions(qw( READ WRITE ));

add the given permissions to the grant. Accepts a list of permissions or a reference to an array containing the permissions to be added. See "canonical" for a list of accepted variants for permissions.

Returns a reference to the object, for chaining methods if needed.

delete_permissions

$grant->delete_permissions(qw( READ_ACP ));

delete the given permissions to the grant. Accepts a list of permissions or a reference to an array containing the permissions to be deleted. See "canonical" for a list of accepted variants for permissions.

Returns a reference to the object, for chaining methods if needed.

parse

$grant->parse($xpc, $node);

accepts an XPathContext and a node to draw info from. Basically, grabs a grant from the node.

stringify

my $xml_chunk = $grant->stringify();

gives back an XML representation for the grant. The output is an XML chunk, not a complete document.

GRANT CLASSES

Net::Amazon::S3::ACL::Grant comes for types to handle different grant options as of EoY 2008. In case Amazon S3 adds more options in the future and this module still doesn't implement them, or you work in Amazon and want to implement a new one, or you replicate Amazon's system, or... you get the idea, it's quite simple to add new types to handle new options.

Each class is required to derive from Net::Amazon::S3::ACL::Grant, and implement the following methods according to the given semantics:

parse_grantee

$grant->parse_grantee($xpc, $node);

accepts an XPathContext and a node to draw info from. Basically, grabs a grant of the specifically supported type from the node.

MUST return $self to allow for chaining.

populate_from_target

$grant->populate_from_target($target);

This method should implement the Do What I Mean behaviour for the specific option. The nature and content of the given target are thus depending on the specific new option you're adding. For example, in the email case it will be an email address.

If the passed $target isn't a good one for your implementation you should croak() loudly (i.e. throw an exception). Otherwise, you MUST return the $grant itself for chaining.

stringify_grantee

my $xml = $grant->stringify_grantee();

Return the XML representation of the grantee (note: of the grantee *only*, the rest is handled by Net::Amazon::S3::ACL::Grant). For example, Net::Amazon::S3::ACL::Grant::ID returns something like this when the ACL is for all:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:type="Group">
   <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
</Grantee>

See Net::Amazon::S3::ACL::Grant::ID for an example implementation.

Last thing you have to do (if you want your class to be considered when using the DWIM approach) is to notify Net::Amazon::S3::ACL::Grant of the new subclass. It keeps the subclasses registered in its package variable @Classes, so you can just do this:

unshift 'My::New::Subclass', @Net::Amazon::S3::ACL::Grant::Classes;

Be careful to unshift instead of push: the array is scanned as is when looking for a suitable class when the DWIM behaviour is triggered. The Net::Amazon::S3::ACL::Grant::ID is quite liberal as to what it accepts for target, so putting something past it is virtually a no-op. You can obviously adjust the order inside @Classes to match your order of preference for scanning classes when looking for something suitable for the given target.

DIAGNOSTICS

unknown permission %s

available permissions are described in the documentation for the "canonical" method. Stick to them - any case will be fine - and you'll have no problem.

not enough parameters to create a grant

when you "create" a grant, you have to provide either sufficient XML-related parameters, or at least a target.

no suitable subclass found to handle input data: %s

when you "create" a grant, you pass in some information that should be useful to understand what type of grant we're dealing with. This is actually a factory method that tries the types in the package array @Classes to find out some grant specialisation that is able to cope with the input data. If none of them is... you'll get this error.

AUTHOR

Flavio Poletti <flavio [at] polettix [dot] it>

LICENCE AND COPYRIGHT

Copyright (c) 2008, Flavio Poletti <flavio [at] polettix [dot] it>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.8.x itself. See perlartistic and perlgpl.

Questo modulo è software libero: potete ridistribuirlo e/o modificarlo negli stessi termini di Perl 5.8.x stesso. Vedete anche perlartistic e perlgpl.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

NEGAZIONE DELLA GARANZIA

Poiché questo software viene dato con una licenza gratuita, non c'è alcuna garanzia associata ad esso, ai fini e per quanto permesso dalle leggi applicabili. A meno di quanto possa essere specificato altrove, il proprietario e detentore del copyright fornisce questo software "così com'è" senza garanzia di alcun tipo, sia essa espressa o implicita, includendo fra l'altro (senza però limitarsi a questo) eventuali garanzie implicite di commerciabilità e adeguatezza per uno scopo particolare. L'intero rischio riguardo alla qualità ed alle prestazioni di questo software rimane a voi. Se il software dovesse dimostrarsi difettoso, vi assumete tutte le responsabilità ed i costi per tutti i necessari servizi, riparazioni o correzioni.

In nessun caso, a meno che ciò non sia richiesto dalle leggi vigenti o sia regolato da un accordo scritto, alcuno dei detentori del diritto di copyright, o qualunque altra parte che possa modificare, o redistribuire questo software così come consentito dalla licenza di cui sopra, potrà essere considerato responsabile nei vostri confronti per danni, ivi inclusi danni generali, speciali, incidentali o conseguenziali, derivanti dall'utilizzo o dall'incapacità di utilizzo di questo software. Ciò include, a puro titolo di esempio e senza limitarsi ad essi, la perdita di dati, l'alterazione involontaria o indesiderata di dati, le perdite sostenute da voi o da terze parti o un fallimento del software ad operare con un qualsivoglia altro software. Tale negazione di garanzia rimane in essere anche se i dententori del copyright, o qualsiasi altra parte, è stata avvisata della possibilità di tali danneggiamenti.

Se decidete di utilizzare questo software, lo fate a vostro rischio e pericolo. Se pensate che i termini di questa negazione di garanzia non si confacciano alle vostre esigenze, o al vostro modo di considerare un software, o ancora al modo in cui avete sempre trattato software di terze parti, non usatelo. Se lo usate, accettate espressamente questa negazione di garanzia e la piena responsabilità per qualsiasi tipo di danno, di qualsiasi natura, possa derivarne.

SEE ALSO

Net::Amazon::S3, Net::Amazon::S3::ACL, Net::Amazon::S3::ACL::Grant::ID, Net::Amazon::S3::ACL::Grant::Email, Net::Amazon::S3::ACL::Grant::URI

cpanm Net::Amazon::S3::ACL

perl -MCPAN -e shell
install Net::Amazon::S3::ACL