VM::EC2::Dispatch(3pm)

1VM::EC2::Dispatch(3)  User Contributed Perl Documentation VM::EC2::Dispatch(3)
2
3
4

NAME

6       VM::EC2::Dispatch - Create Perl objects from AWS XML requests
7

SYNOPSIS

9         use VM::EC2;
10
11         VM::EC2::Dispatch->register('DescribeRegions'=>\&mysub);
12
13         VM::EC2::Dispatch->replace('DescribeRegions'=>'My::Type');
14
15         sub mysub {
16             my ($parsed_xml_object,$ec2) = @_;
17             my $payload = $parsed_xml_object->{regionInfo}
18             return My::Type->new($payload,$ec2);
19         }
20

DESCRIPTION

22       This class handles turning the XML response to AWS requests into perl
23       objects. Only one method is likely to be useful to developers, the
24       replace() class method. This allows you to replace the handlers used to
25       map the response onto objects.
26
27   VM::EC2::Dispatch->replace($request_name => \&sub)
28   VM::EC2::Dispatch->replace($request_name => 'Class::Name')
29   VM::EC2::Dispatch->replace($request_name => 'method_name,arg1,arg2,...')
30       Before invoking a VM::EC2 request you wish to customize, call the
31       replace() method with two arguments. The first argument is the name of
32       the request you wish to customize, such as "DescribeVolumes". The
33       second argument is either a code reference, a VM::EC2::Dispatch method
34       name and arguments (separated by commas), or a class name.
35
36       In the case of a code reference as the second argument, the subroutine
37       you provide will be invoked with four arguments consisting of the
38       parsed XML response, the VM::EC2 object, the XML namespace string from
39       the request, and the Amazon-assigned request ID. In practice, only the
40       first two arguments are useful.
41
42       In the case of a string containing a classname, the class will be
43       loaded if it needs to be, and then its new() method invoked as follows:
44
45         Your::Class->new($parsed_xml,$ec2,$xmlns,$requestid)
46
47       Your new() method should return one or more objects. It is suggested
48       that you subclass VM::EC2::Generic and use the inherited new() method
49       to store the parsed XML and EC2 object. See the code for
50       VM::EC2::AvailabilityRegion for a simple template.
51
52       If the second argument is neither a code reference nor a classname, it
53       will be treated as a VM::EC2::Dispatch method name and its arguments,
54       separated by commas. The method will be invoked as follows:
55
56        $dispatch->$method_name($raw_xml,$ec2,$arg1,$arg2,$arg3,...)
57
58       There are two methods currently defined for this purpose, boolean(),
59       and fetch_items(), which handle the preprocessing of several common XML
60       representations of EC2 data. Note that in this form, the RAW XML is
61       passed in, not the parsed data structure.
62
63       The parsed XML response is generated by the XML::Simple module using
64       these options:
65
66         $parser = XML::Simple->new(ForceArray    => ['item', 'member'],
67                                    KeyAttr       => ['key'],
68                                    SuppressEmpty => undef);
69         $parsed = $parser->XMLin($raw_xml)
70
71       In general, this will give you a hash of hashes. Any tag named 'item'
72       or 'member' will be forced to point to an array reference, and any tag
73       named "key" will be flattened as described in the XML::Simple
74       documentation.
75
76       A simple way to examine the raw parsed XML is to invoke any
77       VM::EC2::Object's as_string method:
78
79        my ($i) = $ec2->describe_instances;
80        print $i->as_string;
81
82       This will give you a Data::Dumper representation of the XML after it
83       has been parsed. Look at the calls to VM::EC2::Dispatch->register() in
84       the various VM/EC2/REST/*.pm modules for many examples of how this
85       works.
86
87       Note that the replace() method was called add_override() in previous
88       versions of this module. add_override() is recognized as an alias for
89       backward compatibility.
90
91   VM::EC2::Dispatch->register($request_name1 => \&sub1,$request_name2 =>
92       \&sub2,...)
93       Similar to replace() but if the request name is already registered does
94       not overwrite it. You may provide multiple request=>handler pairs.
95

OBJECT CREATION METHODS

97       The following methods perform simple pre-processing of the parsed XML
98       (a hash of hashes) before passing the modified data structure to the
99       designated object class. They are used as the second argument to
100       VM::EC2::Dispatch->register().
101
102   $bool = $dispatch->boolean($raw_xml,$ec2,$tag)
103       This is used for XML responses like this:
104
105        <DeleteVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2011-05-15/">
106           <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
107           <return>true</return>
108        </DeleteVolumeResponse>
109
110       It looks inside the structure for the tag named $tag ("return" if not
111       provided), and returns a true value if the contents equals "true".
112
113       Pass it to replace() like this:
114
115         VM::EC2::Dispatch->replace(DeleteVolume => 'boolean,return';
116
117       or, since "return" is the default tag:
118
119         VM::EC2::Dispatch->replace(DeleteVolume => 'boolean';
120
121   @list = $dispatch->elb_member_list($raw_xml,$ec2,$tag)
122       This is used for XML responses from the ELB API such as this:
123
124        <DisableAvailabilityZonesForLoadBalancerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2011-11-15/">
125          <DisableAvailabilityZonesForLoadBalancerResult>
126            <AvailabilityZones>
127              <member>us-west-2a</member>
128              <member>us-west-2b</member>
129            </AvailabilityZones>
130          </DisableAvailabilityZonesForLoadBalancerResult>
131          <ResponseMetadata>
132            <RequestId>02eadcfc-fc38-11e1-a1bf-9de31EXAMPLE</RequestId>
133          </ResponseMetadata>
134        </DisableAvailabilityZonesForLoadBalancerResponse>
135
136       It looks inside the Result structure for the tag named $tag and returns
137       the list wrapped in member elements.  In this case the tag is
138       'AvailabilityZones' and the return value would be: ( 'us-west-2a',
139       'us-west-2b' )
140
141       If $embedded_tag is passed, then it is used for XML responses such as
142       this, where the member list has an embedded tag:
143
144        <RegisterInstancesWithLoadBalancerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2011-11-15/">
145          <RegisterInstancesWithLoadBalancerResult>
146            <Instances>
147              <member>
148                <InstanceId>i-12345678</InstanceId>
149              </member>
150              <member>
151                <InstanceId>i-90abcdef</InstanceId>
152              </member>
153            </Instances>
154          </RegisterInstancesWithLoadBalancerResult>
155          <ResponseMetadata>
156            <RequestId>f4f12596-fc3b-11e1-be5a-f71ecEXAMPLE</RequestId>
157          </ResponseMetadata>
158        </RegisterInstancesWithLoadBalancerResponse>
159
160       It looks inside the Result structure for the tag named $tag and returns
161       the list wrapped in a member element plus the embedded tag.  In this
162       case the tag is 'Instances', the embedded tag is 'InstanceId' and the
163       return value would be: ( 'i-12345678', 'i-90abcdef' )
164
165   @objects =
166       $dispatch->fetch_items($raw_xml,$ec2,$container_tag,$object_class,$nokey)
167       This is used for XML responses like this:
168
169        <DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2011-05-15/">
170           <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
171           <keySet>
172             <item>
173                <keyName>gsg-keypair</keyName>
174                <keyFingerprint>
175                1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f
176                </keyFingerprint>
177             </item>
178             <item>
179                <keyName>default-keypair</keyName>
180                <keyFingerprint>
181                0a:93:bb:e8:c2:89:e9:d8:1f:42:5d:37:1d:8d:b8:0a:88:f1:f1:1a
182                </keyFingerprint>
183             </item>
184          </keySet>
185        </DescribeKeyPairsResponse>
186
187       It looks inside the structure for the tag named $container_tag, pulls
188       out the items that are stored under <item> and then passes the parsed
189       contents to $object_class->new(). The optional $nokey argument is used
190       to suppress XML::Simple's default flattening behavior turning tags
191       named "key" into hash keys.
192
193       Pass it to replace() like this:
194
195         VM::EC2::Dispatch->replace(DescribeVolumes => 'fetch_items,volumeSet,VM::EC2::Volume')
196
197   @objects =
198       $dispatch->fetch_members($raw_xml,$ec2,$container_tag,$object_class,$nokey)
199       Used for XML responses from ELB API calls which contain a key that is
200       the name of the API call with 'Result' appended.  All these XML
201       responses contain 'member' as the item delimiter instead of 'item'
202
203   @objects =
204       $dispatch->fetch_rds_objects($raw_xml,$ec2,$container_tag,$object_class,$nokey)
205       Used for XML responses from RDS API calls which contain a key that is
206       the name of the API call with 'Result' appended.  In addition, the
207       structure is a list of objects wrapped in a plural version of the
208       object's name.
209
210   @objects =
211       $dispatch->fetch_items_iterator($raw_xml,$ec2,$container_tag,$object_class,$token_name)
212       This is used for requests that have a -max_results argument. In this
213       case, the response will have a nextToken field, which can be used to
214       fetch the "next page" of results.
215
216       The $token_name is some unique identifying token. It will be turned
217       into two temporary EC2 instance variables, one named
218       "${token_name}_token", which contains the nextToken value, and the
219       other "${token_name}_stop", which flags the caller that no more results
220       will be forthcoming.
221
222       This must all be coordinated with the request subroutine. See how
223       describe_instance_status() and describe_spot_price_history() do it.
224

EXAMPLE OF USING OVERRIDE TO SUBCLASS VM::EC2::Volume

226       The author decided that a volume object should not be able to delete
227       itself; you disagree with that decision. Let's subclass VM::EC2::Volume
228       to add a delete() method.
229
230       First subclass the VM::EC2::Volume class:
231
232        package MyVolume;
233        use base 'VM::EC2::Volume';
234
235        sub delete {
236           my $self = shift;
237           $self->ec2->delete_volume($self);
238        }
239
240       Now subclass VM::EC2 to add the appropriate overrides to the new()
241       method:
242
243        package MyEC2;
244        use base 'VM::EC2';
245
246        sub new {
247          my $class = shift;
248          VM::EC2::Dispatch->replace(CreateVolume   =>'MyVolume');
249          VM::EC2::Dispatch->replace(DescribeVolumes=>'fetch_items,volumeSet,MyVolume');
250          return $class->SUPER::new(@_);
251        }
252
253       Now we can test it out:
254
255        use MyEC2;
256        # find all volumes that are "available" and not in-use
257        my @vol = $ec2->describe_volumes({status=>'available'});
258        for my $vol (@vol) {
259           $vol->delete && print "$vol deleted\n"
260        }
261

AUTHOR

274       Lincoln Stein <lincoln.stein@gmail.com>.
275
276       Copyright (c) 2011 Ontario Institute for Cancer Research
277
278       This package and its accompanying libraries is free software; you can
279       redistribute it and/or modify it under the terms of the GPL (either
280       version 1, or at your option, any later version) or the Artistic
281       License 2.0.  Refer to LICENSE for the full license text. In addition,
282       please see DISCLAIMER.txt for disclaimers of warranty.
283
284
285
286perl v5.34.0                      2021-07-27              VM::EC2::Dispatch(3)

NAME

SYNOPSIS

DESCRIPTION

OBJECT CREATION METHODS

EXAMPLE OF USING OVERRIDE TO SUBCLASS VM::EC2::Volume

SEE ALSO

AUTHOR