VM::EC2::Generic(3pm)

🦋 NAME 🦋

VM::EC2::Generic — the base class for VM::EC2 objects 💖

So this is a page from the User Contributed Perl Documentation (iykyk, it lives in section 3pm of the manual), and it's the blueprint every other VM::EC2 object inherits its whole personality from.

---

✨ 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 🌸

Okay so basically: this is the common base class for all the objects that come back at you from VM::EC2. It's stacked with a bunch of generic methods that the subclasses all use. It is not meant to be used directly though — it's giving backstage-pass energy, not main-character-on-stage energy. 🙈

---

💅 METHODS 💅

👑 $object = VM::EC2::Generic->new($payload,$ec2 [,$xmlns, $requestId])

Hand it the parsed XML that VM::EC2::Dispatch made, plus the VM::EC2 object, and boom — new object, slay. There's also two optional extra arguments for the seldom-needed XML namespace and the ID of the request that generated this object. Like, they exist, but you probably won't need them fr fr.

💖 $ec2 = $object->ec2 / $ec2 = $object->aws

Returns the VM::EC2 object that gave birth to this object (mother is mothering 💅). You can call it as ec2() (the preferred one, periodt) or aws() — but heads up, aws() is deprecated.

🌈 $id = $object->primary_id (optional method)

Resources with unique Amazon identifiers — think images, instances, volumes — implement primary_id() to hand you that identifier back. Resources that don't have unique identifiers will throw an exception if you call this on them, so watch out. 🚨

This method is in addition to the resource-specific ID. So like, volumes have a unique ID, and you can grab it either way:

$vol->volumeId;

or

$vol->primary_id;

Both ate. 💅

🧚 $xmlns = $object->xmlns

Returns the XML namespace of the request that generated this object, if there is one. Every object generated by direct requests on the VM::EC2 object will return this field — but objects you get from method calls on those objects (objects once removed 👻) may not.

⭐ $id = $object->requestId

Returns the ID of the reuqest that generated this object, if any. Same situation as above: all objects generated by direct requests on the VM::EC2 object will return this field, but objects returned via method calls on these objects (objects once removed 👻) may not.

🎀 $name = $object->short_name

Returns a short name for this object so it can be used in string interpolation. If the object has a primary_id() method, this returns that ID. Otherwise it returns the default Perl object name (VM::EC2::Generic=HASH(0x99f3850)), which is honestly kinda ugly, no shade to Perl. Some classes override short_name() to customize info about the object. See for example VM::EC2::SecurityGroup::IpPermission. 👀

🫶 $hashref = $object->payload

Returns the parsed XML hashref that underlies this object. See VM::EC2::Dispatch.

🌸 @fields = $object->fields

Returns the data field names that are valid for an object of this type. These field names correspond to tags in the XML that Amazon sends back, and you can then use them as method calls. The way that this just works — iconic.

Internally, this method is called valid_fields(). 🤫

✨ $text = $object->as_string

Returns a Data::Dumper representation of the contents of this object's payload.

🦋 $hashref = $object->tags / $hashref = $object->tagSet

Returns the metadata tags assigned to this resource, if any, as a hashref. Both tags() and tagSet() work identically — pick your fave, no wrong answers. 💖

🔥 $boolean = $object->add_tags(Tag1=>'value1',Tag2=>'value2',...) / $boolean = $object->add_tags(\%hash)

Adds one or more tags to the object. You can pass either a list of tag/value pairs or a hashref. If no tag with the indicated name exsists, it gets created. If there's already a tag by that name, it gets set to the value you provided. 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 — very efficient, we love that.

The alias add_tag() is also provided as a convenience. 🎀

💜 $boolean = $object->delete_tags(@args)

Deletes 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.

⚠️ Bestie, read those variants carefully before you go deleting stuff — the undef one and the unconditional ones are not the same vibe, and there's no undo button. 😭

🎀 $xml = $object->as_xml

Returns an XML version of the object. Important: the object will already been parsed by XML::Simple at this point, so the data this method returns will not be identical to the XML returned by AWS. Not a bug, just how it is. 💀

🌈 $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 returns the contents of <value>.
• If the tag has one or more nested tags named <item>, it returns a list of hashrefs located within the <item> tag.
• Otherwise it returns 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 all its subclasses use string overloading, so the object looks and acts like a simple string whenever it's in a string context (like when you print it, or smoosh it together with other strings). Typically that string corresponds to the Amazon resource ID, like "ami-12345", and it's generated by the short_name() method. ✨

You can sort and compare the objects as if they were plain strings — but despite that, object method calls still work in the usual way. It's giving dual citizenship. 💅

---

🌈 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.

---

and that's the whole page bestie, go forth and tag responsibly ✨

perl v5.38.2 · 2024-08-10 · VM::EC2::Generic(3pm) — mwah, ily, read the source, stay hydrated 🍓💖