.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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 "2022-10-14" "perl v5.34.0" "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
\&\fBreplace()\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
\&\fBreplace()\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 \fBnew()\fR method invoked as
follows:
.PP
.Vb 1
\& Your::Class\->new($parsed_xml,$ec2,$xmlns,$requestid)
.Ve
.PP
Your \fBnew()\fR method should return one or more objects. It is suggested
that you subclass VM::EC2::Generic and use the inherited \fBnew()\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, \fBboolean()\fR,
and \fBfetch_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\->\fBregister()\fR in
the various VM/EC2/REST/*.pm modules for many examples of how this
works.
.PP
Note that the \fBreplace()\fR method was called \fBadd_override()\fR in previous
versions of this module. \fBadd_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 \fBreplace()\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\->\fBregister()\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
\&
\& 59dbff89\-35bd\-4eac\-99ed\-be587EXAMPLE
\& true
\&
.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 \fBreplace()\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
\&
\&
\&
\& us\-west\-2a
\& us\-west\-2b
\&
\&
\&
\& 02eadcfc\-fc38\-11e1\-a1bf\-9de31EXAMPLE
\&
\&
.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
\&
\&
\&
\&
\& i\-12345678
\&
\&
\& i\-90abcdef
\&
\&
\&
\&
\& f4f12596\-fc3b\-11e1\-be5a\-f71ecEXAMPLE
\&
\&
.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
\&
\& 59dbff89\-35bd\-4eac\-99ed\-be587EXAMPLE
\&
\& -
\& gsg\-keypair
\&
\& 1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f
\&
\&
\& -
\& default\-keypair
\&
\& 0a:93:bb:e8:c2:89:e9:d8:1f:42:5d:37:1d:8d:b8:0a:88:f1:f1:1a
\&
\&
\&
\&
.Ve
.PP
It looks inside the structure for the tag named \f(CW$container_tag\fR, pulls
out the items that are stored under - and then passes the parsed
contents to \f(CW$object_class\fR\->\fBnew()\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 \fBreplace()\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
\&\fBdescribe_instance_status()\fR and \fBdescribe_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 \fBdelete()\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 \fBnew()\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 .
.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.