.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VM::EC2::Dispatch 3pm"
.TH VM::EC2::Dispatch 3pm "2016-06-04" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
VM::EC2::Dispatch \- Create Perl objects from AWS XML requests
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use VM::EC2;
\&
\&  VM::EC2::Dispatch\->register(\*(AqDescribeRegions\*(Aq=>\e&mysub);
\&
\&  VM::EC2::Dispatch\->replace(\*(AqDescribeRegions\*(Aq=>\*(AqMy::Type\*(Aq);
\&  
\&  sub mysub {
\&      my ($parsed_xml_object,$ec2) = @_;
\&      my $payload = $parsed_xml_object\->{regionInfo}
\&      return My::Type\->new($payload,$ec2);
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class handles turning the \s-1XML\s0 response to \s-1AWS\s0 requests into perl
objects. Only one method is likely to be useful to developers, the
\&\fIreplace()\fR class method. This allows you to replace the handlers
used to map the response onto objects.
.SS "VM::EC2::Dispatch\->replace($request_name => \e&sub)"
.IX Subsection "VM::EC2::Dispatch->replace($request_name => &sub)"
.SS "VM::EC2::Dispatch\->replace($request_name => 'Class::Name')"
.IX Subsection "VM::EC2::Dispatch->replace($request_name => 'Class::Name')"
.SS "VM::EC2::Dispatch\->replace($request_name => 'method_name,arg1,arg2,...')"
.IX Subsection "VM::EC2::Dispatch->replace($request_name => 'method_name,arg1,arg2,...')"
Before invoking a \s-1VM::EC2\s0 request you wish to customize, call the
\&\fIreplace()\fR method with two arguments. The first argument is the
name of the request you wish to customize, such as
\&\*(L"DescribeVolumes\*(R". The second argument is either a code reference, a
VM::EC2::Dispatch method name and arguments (separated by commas), or
a class name.
.PP
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 \s-1XML\s0 response, the \s-1VM::EC2\s0 object, the \s-1XML\s0 namespace string from
the request, and the Amazon-assigned request \s-1ID.\s0 In practice, only the
first two arguments are useful.
.PP
In the case of a string containing a classname, the class will be
loaded if it needs to be, and then its \fInew()\fR method invoked as
follows:
.PP
.Vb 1
\&  Your::Class\->new($parsed_xml,$ec2,$xmlns,$requestid)
.Ve
.PP
Your \fInew()\fR method should return one or more objects. It is suggested
that you subclass VM::EC2::Generic and use the inherited \fInew()\fR method
to store the parsed \s-1XML\s0 and \s-1EC2\s0 object. See the code for
VM::EC2::AvailabilityRegion for a simple template.
.PP
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:
.PP
.Vb 1
\& $dispatch\->$method_name($raw_xml,$ec2,$arg1,$arg2,$arg3,...)
.Ve
.PP
There are two methods currently defined for this purpose, \fIboolean()\fR,
and \fIfetch_items()\fR, which handle the preprocessing of several common
\&\s-1XML\s0 representations of \s-1EC2\s0 data. Note that in this form, the \s-1RAW XML\s0
is passed in, not the parsed data structure.
.PP
The parsed \s-1XML\s0 response is generated by the XML::Simple module using
these options:
.PP
.Vb 4
\&  $parser = XML::Simple\->new(ForceArray    => [\*(Aqitem\*(Aq, \*(Aqmember\*(Aq],
\&                             KeyAttr       => [\*(Aqkey\*(Aq],
\&                             SuppressEmpty => undef);
\&  $parsed = $parser\->XMLin($raw_xml)
.Ve
.PP
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 \*(L"key\*(R" will be flattened as described in the XML::Simple
documentation.
.PP
A simple way to examine the raw parsed \s-1XML\s0 is to invoke any
VM::EC2::Object's as_string method:
.PP
.Vb 2
\& my ($i) = $ec2\->describe_instances;
\& print $i\->as_string;
.Ve
.PP
This will give you a Data::Dumper representation of the \s-1XML\s0 after it
has been parsed. Look at the calls to VM::EC2::Dispatch\->\fIregister()\fR in
the various VM/EC2/REST/*.pm modules for many examples of how this
works.
.PP
Note that the \fIreplace()\fR method was called \fIadd_override()\fR in previous
versions of this module. \fIadd_override()\fR is recognized as an alias for
backward compatibility.
.SS "VM::EC2::Dispatch\->register($request_name1 => \e&sub1,$request_name2 => \e&sub2,...)"
.IX Subsection "VM::EC2::Dispatch->register($request_name1 => &sub1,$request_name2 => &sub2,...)"
Similar to \fIreplace()\fR but if the request name is already registered
does not overwrite it. You may provide multiple request=>handler pairs.
.SH "OBJECT CREATION METHODS"
.IX Header "OBJECT CREATION METHODS"
The following methods perform simple pre-processing of the parsed \s-1XML
\&\s0(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\->\fIregister()\fR.
.ie n .SS "$bool = $dispatch\->boolean($raw_xml,$ec2,$tag)"
.el .SS "\f(CW$bool\fP = \f(CW$dispatch\fP\->boolean($raw_xml,$ec2,$tag)"
.IX Subsection "$bool = $dispatch->boolean($raw_xml,$ec2,$tag)"
This is used for \s-1XML\s0 responses like this:
.PP
.Vb 4
\& <DeleteVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2011\-05\-15/">
\&    <requestId>59dbff89\-35bd\-4eac\-99ed\-be587EXAMPLE</requestId> 
\&    <return>true</return>
\& </DeleteVolumeResponse>
.Ve
.PP
It looks inside the structure for the tag named \f(CW$tag\fR (\*(L"return\*(R" if not
provided), and returns a true value if the contents equals \*(L"true\*(R".
.PP
Pass it to \fIreplace()\fR like this:
.PP
.Vb 1
\&  VM::EC2::Dispatch\->replace(DeleteVolume => \*(Aqboolean,return\*(Aq;
.Ve
.PP
or, since \*(L"return\*(R" is the default tag:
.PP
.Vb 1
\&  VM::EC2::Dispatch\->replace(DeleteVolume => \*(Aqboolean\*(Aq;
.Ve
.ie n .SS "@list = $dispatch\->elb_member_list($raw_xml,$ec2,$tag)"
.el .SS "\f(CW@list\fP = \f(CW$dispatch\fP\->elb_member_list($raw_xml,$ec2,$tag)"
.IX Subsection "@list = $dispatch->elb_member_list($raw_xml,$ec2,$tag)"
This is used for \s-1XML\s0 responses from the \s-1ELB API\s0 such as this:
.PP
.Vb 11
\& <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>
.Ve
.PP
It looks inside the Result structure for the tag named \f(CW$tag\fR 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' )
.PP
If \f(CW$embedded_tag\fR is passed, then it is used for \s-1XML\s0 responses such as this,
where the member list has an embedded tag:
.PP
.Vb 10
\& <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>
.Ve
.PP
It looks inside the Result structure for the tag named \f(CW$tag\fR 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' )
.SS "fetch_items($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
.IX Subsection "fetch_items($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
\&\f(CW@objects\fR = \f(CW$dispatch\fR\->fetch_items($raw_xml,$ec2,$container_tag,$object_class,$nokey)
.PP
This is used for \s-1XML\s0 responses like this:
.PP
.Vb 10
\& <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>
.Ve
.PP
It looks inside the structure for the tag named \f(CW$container_tag\fR, pulls
out the items that are stored under <item> and then passes the parsed
contents to \f(CW$object_class\fR\->\fInew()\fR. The optional \f(CW$nokey\fR argument is used
to suppress XML::Simple's default flattening behavior turning tags
named \*(L"key\*(R" into hash keys.
.PP
Pass it to \fIreplace()\fR like this:
.PP
.Vb 1
\&  VM::EC2::Dispatch\->replace(DescribeVolumes => \*(Aqfetch_items,volumeSet,VM::EC2::Volume\*(Aq)
.Ve
.ie n .SS "@objects = $dispatch\->fetch_members($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
.el .SS "\f(CW@objects\fP = \f(CW$dispatch\fP\->fetch_members($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
.IX Subsection "@objects = $dispatch->fetch_members($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
Used for \s-1XML\s0 responses from \s-1ELB API\s0 calls which contain a key that is the name
of the \s-1API\s0 call with 'Result' appended.  All these \s-1XML\s0 responses contain
\&'member' as the item delimiter instead of 'item'
.ie n .SS "@objects = $dispatch\->fetch_rds_objects($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
.el .SS "\f(CW@objects\fP = \f(CW$dispatch\fP\->fetch_rds_objects($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
.IX Subsection "@objects = $dispatch->fetch_rds_objects($raw_xml,$ec2,$container_tag,$object_class,$nokey)"
Used for \s-1XML\s0 responses from \s-1RDS API\s0 calls which contain a key that is the name
of the \s-1API\s0 call with 'Result' appended.  In addition, the structure is a list
of objects wrapped in a plural version of the object's name.
.ie n .SS "@objects = $dispatch\->fetch_items_iterator($raw_xml,$ec2,$container_tag,$object_class,$token_name)"
.el .SS "\f(CW@objects\fP = \f(CW$dispatch\fP\->fetch_items_iterator($raw_xml,$ec2,$container_tag,$object_class,$token_name)"
.IX Subsection "@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 \*(L"next page\*(R" of results.
.PP
The \f(CW$token_name\fR is some unique identifying token. It will be turned
into two temporary \s-1EC2\s0 instance variables, one named
\&\*(L"${token_name}_token\*(R", which contains the nextToken value, and the
other \*(L"${token_name}_stop\*(R", which flags the caller that no more
results will be forthcoming.
.PP
This must all be coordinated with the request subroutine. See how
\&\fIdescribe_instance_status()\fR and \fIdescribe_spot_price_history()\fR do it.
.SH "EXAMPLE OF USING OVERRIDE TO SUBCLASS VM::EC2::Volume"
.IX Header "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 \fIdelete()\fR method.
.PP
First subclass the VM::EC2::Volume class:
.PP
.Vb 2
\& package MyVolume;
\& use base \*(AqVM::EC2::Volume\*(Aq;
\&
\& sub delete {
\&    my $self = shift;
\&    $self\->ec2\->delete_volume($self);
\& }
.Ve
.PP
Now subclass \s-1VM::EC2\s0 to add the appropriate overrides to the \fInew()\fR method:
.PP
.Vb 2
\& package MyEC2;
\& use base \*(AqVM::EC2\*(Aq;
\&
\& sub new {
\&   my $class = shift;
\&   VM::EC2::Dispatch\->replace(CreateVolume   =>\*(AqMyVolume\*(Aq);
\&   VM::EC2::Dispatch\->replace(DescribeVolumes=>\*(Aqfetch_items,volumeSet,MyVolume\*(Aq);
\&   return $class\->SUPER::new(@_);
\& }
.Ve
.PP
Now we can test it out:
.PP
.Vb 6
\& use MyEC2;
\& # find all volumes that are "available" and not in\-use
\& my @vol = $ec2\->describe_volumes({status=>\*(Aqavailable\*(Aq});
\& for my $vol (@vol) { 
\&    $vol\->delete && print "$vol deleted\en" 
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
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
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lincoln.stein@gmail.com>.
.PP
Copyright (c) 2011 Ontario Institute for Cancer Research
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL \s0(either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.