NAME¶
VM::EC2::Generic - Base class for VM::EC2 objects
SYNOPSIS¶
use VM::EC2;
my $ec2 = VM::EC2->new(-access_key => 'access key id',
-secret_key => 'aws_secret_key',
-endpoint => 'http://ec2.amazonaws.com');
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 'WebServer') {
$object->delete_tags(Role=>undef);
$object->add_tags(Role => 'Web Server',
Status => 'development');
}
# 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;
DESCRIPTION¶
This is a common base class for objects returned from VM::EC2. It provides a
number of generic methods that are used in subclasses, but is not intended to
be used directly.
METHODS¶
$object = VM::EC2::Generic->new($payload,$ec2 [,$xmlns, $requestId])¶
Given the parsed XML generated by VM::EC2::Dispatch and the VM::EC2 object,
return a new object. Two optional additional arguments provide the
seldom-needed XML namespace and ID of the request that generated this object.
$ec2 = $object->ec2¶
$ec2 = $object->aws¶
Return the VM::EC2 object that generated this object. This method can be called
as either
ec2() (preferred) or
aws() (deprecated).
$id = $object->primary_id (optional method)¶
Resources that have unique Amazon identifiers, such as images, instances and
volumes, implement the
primary_id() 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 ID. For
example, volumes have a unique ID, and this ID can be fetched with either of:
$vol->volumeId;
or
$vol->primary_id;
$xmlns = $object->xmlns¶
Return the XML namespace of the request that generated this object, if any. All
objects generated by direct requests on the VM::EC2 object will return this
field, but objects returned via methods calls on these objects (objects once
removed) may not.
$id = $object->requestId¶
Return the ID of the reuqest that generated this object, if any. All objects
generated by direct requests on the VM::EC2 object will return this field, but
objects returned via methods calls on these objects (objects once removed) may
not.
$name = $object->short_name¶
Return a short name for this object for use in string interpolation. If the
object has a
primary_id() method, then this returns that ID. Otherwise
it returns the default Perl object name (VM::EC2::Generic=HASH(0x99f3850).
Some classes override
short_name() in order to customized information
about the object. See for example VM::EC2::SecurityGroup::IpPermission.
$hashref = $object->payload¶
Return the parsed XML hashref that underlies this object. See VM::EC2::Dispatch.
@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 XML returned from Amazon and can then be
used as method calls.
Internally, this method is called
valid_fields()
$text = $object->as_string¶
Return a Data::Dumper representation of the contents of this object's payload.
Return the metadata tags assigned to this resource, if any, as a hashref. Both
tags() and
tagSet() work identically.
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.
Also see VM::EC2->
add_tags() for a way of tagging multiple resources
simultaneously.
The alias
add_tag() is also provided as a convenience.
Delete the indicated tags from the indicated resource. There are several
variants you may use:
# delete Foo tag if it has value "bar" and Buzz tag if it has value 'bazz'
$i->delete_tags({Foo=>'bar',Buzz=>'bazz'})
# same as above but using a list rather than a hashref
$i->delete_tags(Foo=>'bar',Buzz=>'bazz')
# delete Foo tag if it has any value, Buzz if it has value 'bazz'
$i->delete_tags({Foo=>undef,Buzz=>'bazz'})
# delete Foo and Buzz tags unconditionally
$i->delete_tags(['Foo','Buzz'])
# delete Foo tag unconditionally
$i->delete_tags('Foo');
Also see VM::EC2->
delete_tags() for a way of deleting tags from
multiple resources simultaneously.
$xml = $object->as_xml¶
Returns an XML 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 XML returned by AWS.
$value = $object->attribute('tag_name')¶
Returns the value of a tag in the XML returned from AWS, 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>.
$string = $object->error_str¶
Returns the error string for the last operation, if any, as reported by VM::EC2.
$string = $object->error¶
Returns the VM::EC2::Error object from the last operation, if any, as reported
by VM::EC2.
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 ID such as "ami-12345" and is generated by
the
short_name() method.
You can sort and compare the objects as if they were strings, but despite this,
object method calls work in the usual way.
SEE ALSO¶
VM::EC2 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
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.