.\" 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::Generic 3pm"
.TH VM::EC2::Generic 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::Generic \- Base class for VM::EC2 objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use VM::EC2;
\&
\& my $ec2 = VM::EC2\->new(\-access_key => \*(Aqaccess key id\*(Aq,
\&                      \-secret_key => \*(Aqaws_secret_key\*(Aq,
\&                      \-endpoint   => \*(Aqhttp://ec2.amazonaws.com\*(Aq);
\&
\& my $object = $ec2\->some_method(...);
\&
\& # getting data fields
\& my @field_names = $object\->fields;
\&
\& # invoking data fields as methods
\& my $request_id = $object\->requestId;
\& my $xmlns      = $object\->xmlns;
\&
\& # tagging 
\& my $tags = $object\->tags;
\&
\& if ($tags\->{Role} eq \*(AqWebServer\*(Aq) {
\&    $object\->delete_tags(Role=>undef);
\&    $object\->add_tags(Role   => \*(AqWeb Server\*(Aq,
\&                      Status => \*(Aqdevelopment\*(Aq);
\& }
\&
\& # get the parsed XML object as a hash
\& my $hashref = $object\->payload;
\&
\& # get the parsed XML object as a Data::Dumper string
\& my $text = $object\->as_string;
\&
\& # get the VM::EC2 object back
\& my $ec2 = $object\->ec2;
\&
\& # get the most recent error string
\& warn $object\->error_str;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a common base class for objects returned from \s-1VM::EC2.\s0 It
provides a number of generic methods that are used in subclasses, but
is not intended to be used directly.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$object = VM::EC2::Generic\->new($payload,$ec2 [,$xmlns, $requestId])"
.el .SS "\f(CW$object\fP = VM::EC2::Generic\->new($payload,$ec2 [,$xmlns, \f(CW$requestId\fP])"
.IX Subsection "$object = VM::EC2::Generic->new($payload,$ec2 [,$xmlns, $requestId])"
Given the parsed \s-1XML\s0 generated by VM::EC2::Dispatch and the \s-1VM::EC2\s0
object, return a new object. Two optional additional arguments provide
the seldom-needed \s-1XML\s0 namespace and \s-1ID\s0 of the request that generated
this object.
.ie n .SS "$ec2 = $object\->ec2"
.el .SS "\f(CW$ec2\fP = \f(CW$object\fP\->ec2"
.IX Subsection "$ec2 = $object->ec2"
.ie n .SS "$ec2 = $object\->aws"
.el .SS "\f(CW$ec2\fP = \f(CW$object\fP\->aws"
.IX Subsection "$ec2 = $object->aws"
Return the \s-1VM::EC2\s0 object that generated this object. This method can
be called as either \fIec2()\fR (preferred) or \fIaws()\fR (deprecated).
.ie n .SS "$id = $object\->primary_id  (optional method)"
.el .SS "\f(CW$id\fP = \f(CW$object\fP\->primary_id  (optional method)"
.IX Subsection "$id = $object->primary_id (optional method)"
Resources that have unique Amazon identifiers, such as images,
instances and volumes, implement the \fIprimary_id()\fR method to return
that identifier. Resources that do not have unique identifiers, will
throw an exception if this method is called. This method is in
addition to the resource-specific \s-1ID.\s0 For example, volumes have a
unique \s-1ID,\s0 and this \s-1ID\s0 can be fetched with either of:
.PP
.Vb 1
\&  $vol\->volumeId;
.Ve
.PP
or
.PP
.Vb 1
\&  $vol\->primary_id;
.Ve
.ie n .SS "$xmlns = $object\->xmlns"
.el .SS "\f(CW$xmlns\fP = \f(CW$object\fP\->xmlns"
.IX Subsection "$xmlns = $object->xmlns"
Return the \s-1XML\s0 namespace of the request that generated this object, if
any. All objects generated by direct requests on the \s-1VM::EC2\s0 object
will return this field, but objects returned via methods calls on
these objects (objects once removed) may not.
.ie n .SS "$id = $object\->requestId"
.el .SS "\f(CW$id\fP = \f(CW$object\fP\->requestId"
.IX Subsection "$id = $object->requestId"
Return the \s-1ID\s0 of the reuqest that generated this object, if any. All
objects generated by direct requests on the \s-1VM::EC2\s0 object will return
this field, but objects returned via methods calls on these objects
(objects once removed) may not.
.ie n .SS "$name = $object\->short_name"
.el .SS "\f(CW$name\fP = \f(CW$object\fP\->short_name"
.IX Subsection "$name = $object->short_name"
Return a short name for this object for use in string
interpolation. If the object has a \fIprimary_id()\fR method, then this
returns that \s-1ID.\s0 Otherwise it returns the default Perl object name
(VM::EC2::Generic=HASH(0x99f3850). Some classes override \fIshort_name()\fR
in order to customized information about the object. See for example
VM::EC2::SecurityGroup::IpPermission.
.ie n .SS "$hashref = $object\->payload"
.el .SS "\f(CW$hashref\fP = \f(CW$object\fP\->payload"
.IX Subsection "$hashref = $object->payload"
Return the parsed \s-1XML\s0 hashref that underlies this object. See
VM::EC2::Dispatch.
.ie n .SS "@fields = $object\->fields"
.el .SS "\f(CW@fields\fP = \f(CW$object\fP\->fields"
.IX Subsection "@fields = $object->fields"
Return the data field names that are valid for an object of this
type. These field names correspond to tags in the \s-1XML\s0
returned from Amazon and can then be used as method calls.
.PP
Internally, this method is called \fIvalid_fields()\fR
.ie n .SS "$text = $object\->as_string"
.el .SS "\f(CW$text\fP = \f(CW$object\fP\->as_string"
.IX Subsection "$text = $object->as_string"
Return a Data::Dumper representation of the contents of this object's
payload.
.ie n .SS "$hashref = $object\->tags"
.el .SS "\f(CW$hashref\fP = \f(CW$object\fP\->tags"
.IX Subsection "$hashref = $object->tags"
.ie n .SS "$hashref = $object\->tagSet"
.el .SS "\f(CW$hashref\fP = \f(CW$object\fP\->tagSet"
.IX Subsection "$hashref = $object->tagSet"
Return the metadata tags assigned to this resource, if any, as a
hashref. Both \fItags()\fR and \fItagSet()\fR work identically.
.ie n .SS "$boolean = $object\->add_tags(Tag1=>'value1',Tag2=>'value2',...)"
.el .SS "\f(CW$boolean\fP = \f(CW$object\fP\->add_tags(Tag1=>'value1',Tag2=>'value2',...)"
.IX Subsection "$boolean = $object->add_tags(Tag1=>'value1',Tag2=>'value2',...)"
.ie n .SS "$boolean = $object\->add_tags(\e%hash)"
.el .SS "\f(CW$boolean\fP = \f(CW$object\fP\->add_tags(\e%hash)"
.IX Subsection "$boolean = $object->add_tags(%hash)"
Add one or more tags to the object. You may provide either a list of
tag/value pairs or a hashref. If no tag of the indicated name exsists
it will be created. If there is already a tag by this name, it will
be set to the provided value. The result code is true if the Amazon
resource was successfully updated.
.PP
Also see \s-1VM::EC2\-\s0>\fIadd_tags()\fR for a way of tagging multiple resources
simultaneously.
.PP
The alias \fIadd_tag()\fR is also provided as a convenience.
.ie n .SS "$boolean = $object\->delete_tags(@args)"
.el .SS "\f(CW$boolean\fP = \f(CW$object\fP\->delete_tags(@args)"
.IX Subsection "$boolean = $object->delete_tags(@args)"
Delete the indicated tags from the indicated resource. There are
several variants you may use:
.PP
.Vb 2
\& # delete Foo tag if it has value "bar" and Buzz tag if it has value \*(Aqbazz\*(Aq
\& $i\->delete_tags({Foo=>\*(Aqbar\*(Aq,Buzz=>\*(Aqbazz\*(Aq})  
\&
\& # same as above but using a list rather than a hashref
\& $i\->delete_tags(Foo=>\*(Aqbar\*(Aq,Buzz=>\*(Aqbazz\*(Aq)  
\&
\& # delete Foo tag if it has any value, Buzz if it has value \*(Aqbazz\*(Aq
\& $i\->delete_tags({Foo=>undef,Buzz=>\*(Aqbazz\*(Aq})
\&
\& # delete Foo and Buzz tags unconditionally
\& $i\->delete_tags([\*(AqFoo\*(Aq,\*(AqBuzz\*(Aq])
\&
\& # delete Foo tag unconditionally
\& $i\->delete_tags(\*(AqFoo\*(Aq);
.Ve
.PP
Also see \s-1VM::EC2\-\s0>\fIdelete_tags()\fR for a way of deleting tags from multiple
resources simultaneously.
.ie n .SS "$xml = $object\->as_xml"
.el .SS "\f(CW$xml\fP = \f(CW$object\fP\->as_xml"
.IX Subsection "$xml = $object->as_xml"
Returns an \s-1XML\s0 version of the object. The object will already been
parsed by XML::Simple at this point, and so the data returned by this
method will not be identical to the \s-1XML\s0 returned by \s-1AWS.\s0
.ie n .SS "$value = $object\->attribute('tag_name')"
.el .SS "\f(CW$value\fP = \f(CW$object\fP\->attribute('tag_name')"
.IX Subsection "$value = $object->attribute('tag_name')"
Returns the value of a tag in the \s-1XML\s0 returned from \s-1AWS,\s0 using a
simple heuristic. If the requested tag has a nested tag named <value>
it will return the contents of <value>. If the tag has one or more
nested tags named <item>, it will return a list of hashrefs located
within the <item> tag. Otherwise it will return the contents of
<tag_name>.
.ie n .SS "$string = $object\->error_str"
.el .SS "\f(CW$string\fP = \f(CW$object\fP\->error_str"
.IX Subsection "$string = $object->error_str"
Returns the error string for the last operation, if any, as reported
by \s-1VM::EC2.\s0
.ie n .SS "$string = $object\->error"
.el .SS "\f(CW$string\fP = \f(CW$object\fP\->error"
.IX Subsection "$string = $object->error"
Returns the VM::EC2::Error object from the last operation, if any,
as reported by \s-1VM::EC2.\s0
.SH "STRING OVERLOADING"
.IX Header "STRING OVERLOADING"
This base class and its subclasses use string overloading so that the
object looks and acts like a simple string when used in a string
context (such as when printed or combined with other
strings). Typically the string corresponds to the Amazon resource \s-1ID\s0
such as \*(L"ami\-12345\*(R" and is generated by the \fIshort_name()\fR method.
.PP
You can sort and compare the objects as if they were strings, but
despite this, object method calls work in the usual way.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
VM::EC2::Dispatch
VM::EC2::Generic
VM::EC2::BlockDevice
VM::EC2::BlockDevice::Attachment
VM::EC2::BlockDevice::Mapping
VM::EC2::BlockDevice::Mapping::EBS
VM::EC2::ConsoleOutput
VM::EC2::Error
VM::EC2::Generic
VM::EC2::Group
VM::EC2::Image
VM::EC2::Instance
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.