NAME¶
VM::EC2::Dispatch - Create Perl objects from AWS XML requests
SYNOPSIS¶
use VM::EC2;
VM::EC2::Dispatch->register('DescribeRegions'=>\&mysub);
VM::EC2::Dispatch->replace('DescribeRegions'=>'My::Type');
sub mysub {
my ($parsed_xml_object,$ec2) = @_;
my $payload = $parsed_xml_object->{regionInfo}
return My::Type->new($payload,$ec2);
}
DESCRIPTION¶
This class handles turning the XML response to AWS requests into perl objects.
Only one method is likely to be useful to developers, the
replace()
class method. This allows you to replace the handlers used to map the response
onto objects.
VM::EC2::Dispatch->replace($request_name => \&sub)¶
VM::EC2::Dispatch->replace($request_name => 'Class::Name')¶
VM::EC2::Dispatch->replace($request_name => 'method_name,arg1,arg2,...')¶
Before invoking a VM::EC2 request you wish to customize, call the
replace() method with two arguments. The first argument is the name of
the request you wish to customize, such as "DescribeVolumes". The
second argument is either a code reference, a VM::EC2::Dispatch method name
and arguments (separated by commas), or a class name.
In the case of a code reference as the second argument, the subroutine you
provide will be invoked with four arguments consisting of the parsed XML
response, the VM::EC2 object, the XML namespace string from the request, and
the Amazon-assigned request ID. In practice, only the first two arguments are
useful.
In the case of a string containing a classname, the class will be loaded if it
needs to be, and then its
new() method invoked as follows:
Your::Class->new($parsed_xml,$ec2,$xmlns,$requestid)
Your
new() method should return one or more objects. It is suggested that
you subclass VM::EC2::Generic and use the inherited
new() method to
store the parsed XML and EC2 object. See the code for
VM::EC2::AvailabilityRegion for a simple template.
If the second argument is neither a code reference nor a classname, it will be
treated as a VM::EC2::Dispatch method name and its arguments, separated by
commas. The method will be invoked as follows:
$dispatch->$method_name($raw_xml,$ec2,$arg1,$arg2,$arg3,...)
There are two methods currently defined for this purpose,
boolean(), and
fetch_items(), which handle the preprocessing of several common XML
representations of EC2 data. Note that in this form, the RAW XML is passed in,
not the parsed data structure.
The parsed XML response is generated by the XML::Simple module using these
options:
$parser = XML::Simple->new(ForceArray => ['item', 'member'],
KeyAttr => ['key'],
SuppressEmpty => undef);
$parsed = $parser->XMLin($raw_xml)
In general, this will give you a hash of hashes. Any tag named 'item' or
'member' will be forced to point to an array reference, and any tag named
"key" will be flattened as described in the XML::Simple
documentation.
A simple way to examine the raw parsed XML is to invoke any VM::EC2::Object's
as_string method:
my ($i) = $ec2->describe_instances;
print $i->as_string;
This will give you a Data::Dumper representation of the XML after it has been
parsed. Look at the calls to VM::EC2::Dispatch->
register() in the
various VM/EC2/REST/*.pm modules for many examples of how this works.
Note that the
replace() method was called
add_override() in
previous versions of this module.
add_override() is recognized as an
alias for backward compatibility.
VM::EC2::Dispatch->register($request_name1 => \&sub1,$request_name2 => \&sub2,...)¶
Similar to
replace() but if the request name is already registered does
not overwrite it. You may provide multiple request=>handler pairs.
OBJECT CREATION METHODS¶
The following methods perform simple pre-processing of the parsed XML (a hash of
hashes) before passing the modified data structure to the designated object
class. They are used as the second argument to VM::EC2::Dispatch->
register().
$bool = $dispatch->boolean($raw_xml,$ec2,$tag)¶
This is used for XML responses like this:
<DeleteVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2011-05-15/">
<requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
<return>true</return>
</DeleteVolumeResponse>
It looks inside the structure for the tag named $tag ("return" if not
provided), and returns a true value if the contents equals "true".
Pass it to
replace() like this:
VM::EC2::Dispatch->replace(DeleteVolume => 'boolean,return';
or, since "return" is the default tag:
VM::EC2::Dispatch->replace(DeleteVolume => 'boolean';
@list = $dispatch->elb_member_list($raw_xml,$ec2,$tag)¶
This is used for XML responses from the ELB API such as this:
<DisableAvailabilityZonesForLoadBalancerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2011-11-15/">
<DisableAvailabilityZonesForLoadBalancerResult>
<AvailabilityZones>
<member>us-west-2a</member>
<member>us-west-2b</member>
</AvailabilityZones>
</DisableAvailabilityZonesForLoadBalancerResult>
<ResponseMetadata>
<RequestId>02eadcfc-fc38-11e1-a1bf-9de31EXAMPLE</RequestId>
</ResponseMetadata>
</DisableAvailabilityZonesForLoadBalancerResponse>
It looks inside the Result structure for the tag named $tag and returns the list
wrapped in member elements. In this case the tag is 'AvailabilityZones' and
the return value would be: ( 'us-west-2a', 'us-west-2b' )
If $embedded_tag is passed, then it is used for XML responses such as this,
where the member list has an embedded tag:
<RegisterInstancesWithLoadBalancerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2011-11-15/">
<RegisterInstancesWithLoadBalancerResult>
<Instances>
<member>
<InstanceId>i-12345678</InstanceId>
</member>
<member>
<InstanceId>i-90abcdef</InstanceId>
</member>
</Instances>
</RegisterInstancesWithLoadBalancerResult>
<ResponseMetadata>
<RequestId>f4f12596-fc3b-11e1-be5a-f71ecEXAMPLE</RequestId>
</ResponseMetadata>
</RegisterInstancesWithLoadBalancerResponse>
It looks inside the Result structure for the tag named $tag and returns the list
wrapped in a member element plus the embedded tag. In this case the tag is
'Instances', the embedded tag is 'InstanceId' and the return value would be: (
'i-12345678', 'i-90abcdef' )
fetch_items($raw_xml,$ec2,$container_tag,$object_class,$nokey)¶
@objects =
$dispatch->fetch_items($raw_xml,$ec2,$container_tag,$object_class,$nokey)
This is used for XML responses like this:
<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2011-05-15/">
<requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
<keySet>
<item>
<keyName>gsg-keypair</keyName>
<keyFingerprint>
1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f
</keyFingerprint>
</item>
<item>
<keyName>default-keypair</keyName>
<keyFingerprint>
0a:93:bb:e8:c2:89:e9:d8:1f:42:5d:37:1d:8d:b8:0a:88:f1:f1:1a
</keyFingerprint>
</item>
</keySet>
</DescribeKeyPairsResponse>
It looks inside the structure for the tag named $container_tag, pulls out the
items that are stored under <item> and then passes the parsed contents
to $object_class->
new(). The optional $nokey argument is used to
suppress XML::Simple's default flattening behavior turning tags named
"key" into hash keys.
Pass it to
replace() like this:
VM::EC2::Dispatch->replace(DescribeVolumes => 'fetch_items,volumeSet,VM::EC2::Volume')
@objects = $dispatch->fetch_members($raw_xml,$ec2,$container_tag,$object_class,$nokey)¶
Used for XML responses from ELB API calls which contain a key that is the name
of the API call with 'Result' appended. All these XML responses contain
'member' as the item delimiter instead of 'item'
@objects = $dispatch->fetch_rds_objects($raw_xml,$ec2,$container_tag,$object_class,$nokey)¶
Used for XML responses from RDS API calls which contain a key that is the name
of the API call with 'Result' appended. In addition, the structure is a list
of objects wrapped in a plural version of the object's name.
@objects = $dispatch->fetch_items_iterator($raw_xml,$ec2,$container_tag,$object_class,$token_name)¶
This is used for requests that have a -max_results argument. In this case, the
response will have a nextToken field, which can be used to fetch the
"next page" of results.
The $token_name is some unique identifying token. It will be turned into two
temporary EC2 instance variables, one named "${token_name}_token",
which contains the nextToken value, and the other
"${token_name}_stop", which flags the caller that no more results
will be forthcoming.
This must all be coordinated with the request subroutine. See how
describe_instance_status() and
describe_spot_price_history() do
it.
EXAMPLE OF USING OVERRIDE TO SUBCLASS VM::EC2::Volume¶
The author decided that a volume object should not be able to delete itself; you
disagree with that decision. Let's subclass VM::EC2::Volume to add a
delete() method.
First subclass the VM::EC2::Volume class:
package MyVolume;
use base 'VM::EC2::Volume';
sub delete {
my $self = shift;
$self->ec2->delete_volume($self);
}
Now subclass VM::EC2 to add the appropriate overrides to the
new()
method:
package MyEC2;
use base 'VM::EC2';
sub new {
my $class = shift;
VM::EC2::Dispatch->replace(CreateVolume =>'MyVolume');
VM::EC2::Dispatch->replace(DescribeVolumes=>'fetch_items,volumeSet,MyVolume');
return $class->SUPER::new(@_);
}
Now we can test it out:
use MyEC2;
# find all volumes that are "available" and not in-use
my @vol = $ec2->describe_volumes({status=>'available'});
for my $vol (@vol) {
$vol->delete && print "$vol deleted\n"
}
SEE ALSO¶
VM::EC2 VM::EC2::Object VM::EC2::Generic VM::EC2::BlockDevice
VM::EC2::BlockDevice::Attachment VM::EC2::BlockDevice::Mapping
VM::EC2::BlockDevice::Mapping::EBS VM::EC2::Error VM::EC2::Generic
VM::EC2::Group VM::EC2::Image VM::EC2::Instance
VM::EC2::Instance::ConsoleOutput VM::EC2::Instance::Set
VM::EC2::Instance::State VM::EC2::Instance::State::Change
VM::EC2::Instance::State::Reason VM::EC2::Region VM::EC2::ReservationSet
VM::EC2::SecurityGroup VM::EC2::Snapshot VM::EC2::Tag VM::EC2::Volume
AUTHOR¶
Lincoln Stein <lincoln.stein@gmail.com>.
Copyright (c) 2011 Ontario Institute for Cancer Research
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the GPL (either version 1,
or at your option, any later version) or the Artistic License 2.0. Refer to
LICENSE for the full license text. In addition, please see DISCLAIMER.txt for
disclaimers of warranty.