VM::EC2::Generic(3pm)

1VM::EC2::Generic(3)   User Contributed Perl Documentation  VM::EC2::Generic(3)
2
3
4

NAME

6       VM::EC2::Generic - Base class for VM::EC2 objects
7

SYNOPSIS

9         use VM::EC2;
10
11        my $ec2 = VM::EC2->new(-access_key => 'access key id',
12                             -secret_key => 'aws_secret_key',
13                             -endpoint   => 'http://ec2.amazonaws.com');
14
15        my $object = $ec2->some_method(...);
16
17        # getting data fields
18        my @field_names = $object->fields;
19
20        # invoking data fields as methods
21        my $request_id = $object->requestId;
22        my $xmlns      = $object->xmlns;
23
24        # tagging
25        my $tags = $object->tags;
26
27        if ($tags->{Role} eq 'WebServer') {
28           $object->delete_tags(Role=>undef);
29           $object->add_tags(Role   => 'Web Server',
30                             Status => 'development');
31        }
32
33        # get the parsed XML object as a hash
34        my $hashref = $object->payload;
35
36        # get the parsed XML object as a Data::Dumper string
37        my $text = $object->as_string;
38
39        # get the VM::EC2 object back
40        my $ec2 = $object->ec2;
41
42        # get the most recent error string
43        warn $object->error_str;
44

DESCRIPTION

46       This is a common base class for objects returned from VM::EC2. It
47       provides a number of generic methods that are used in subclasses, but
48       is not intended to be used directly.
49

METHODS

51   $object = VM::EC2::Generic->new($payload,$ec2 [,$xmlns, $requestId])
52       Given the parsed XML generated by VM::EC2::Dispatch and the VM::EC2
53       object, return a new object. Two optional additional arguments provide
54       the seldom-needed XML namespace and ID of the request that generated
55       this object.
56
57   $ec2 = $object->ec2
58   $ec2 = $object->aws
59       Return the VM::EC2 object that generated this object. This method can
60       be called as either ec2() (preferred) or aws() (deprecated).
61
62   $id = $object->primary_id  (optional method)
63       Resources that have unique Amazon identifiers, such as images,
64       instances and volumes, implement the primary_id() method to return that
65       identifier. Resources that do not have unique identifiers, will throw
66       an exception if this method is called. This method is in addition to
67       the resource-specific ID. For example, volumes have a unique ID, and
68       this ID can be fetched with either of:
69
70         $vol->volumeId;
71
72       or
73
74         $vol->primary_id;
75
76   $xmlns = $object->xmlns
77       Return the XML namespace of the request that generated this object, if
78       any. All objects generated by direct requests on the VM::EC2 object
79       will return this field, but objects returned via methods calls on these
80       objects (objects once removed) may not.
81
82   $id = $object->requestId
83       Return the ID of the reuqest that generated this object, if any. All
84       objects generated by direct requests on the VM::EC2 object will return
85       this field, but objects returned via methods calls on these objects
86       (objects once removed) may not.
87
88   $name = $object->short_name
89       Return a short name for this object for use in string interpolation. If
90       the object has a primary_id() method, then this returns that ID.
91       Otherwise it returns the default Perl object name
92       (VM::EC2::Generic=HASH(0x99f3850). Some classes override short_name()
93       in order to customized information about the object. See for example
94       VM::EC2::SecurityGroup::IpPermission.
95
96   $hashref = $object->payload
97       Return the parsed XML hashref that underlies this object. See
98       VM::EC2::Dispatch.
99
100   @fields = $object->fields
101       Return the data field names that are valid for an object of this type.
102       These field names correspond to tags in the XML returned from Amazon
103       and can then be used as method calls.
104
105       Internally, this method is called valid_fields()
106
107   $text = $object->as_string
108       Return a Data::Dumper representation of the contents of this object's
109       payload.
110
111   $hashref = $object->tags
112   $hashref = $object->tagSet
113       Return the metadata tags assigned to this resource, if any, as a
114       hashref. Both tags() and tagSet() work identically.
115
116   $boolean = $object->add_tags(Tag1=>'value1',Tag2=>'value2',...)
117   $boolean = $object->add_tags(\%hash)
118       Add one or more tags to the object. You may provide either a list of
119       tag/value pairs or a hashref. If no tag of the indicated name exsists
120       it will be created. If there is already a tag by this name, it will be
121       set to the provided value. The result code is true if the Amazon
122       resource was successfully updated.
123
124       Also see VM::EC2->add_tags() for a way of tagging multiple resources
125       simultaneously.
126
127       The alias add_tag() is also provided as a convenience.
128
129   $boolean = $object->delete_tags(@args)
130       Delete the indicated tags from the indicated resource. There are
131       several variants you may use:
132
133        # delete Foo tag if it has value "bar" and Buzz tag if it has value 'bazz'
134        $i->delete_tags({Foo=>'bar',Buzz=>'bazz'})
135
136        # same as above but using a list rather than a hashref
137        $i->delete_tags(Foo=>'bar',Buzz=>'bazz')
138
139        # delete Foo tag if it has any value, Buzz if it has value 'bazz'
140        $i->delete_tags({Foo=>undef,Buzz=>'bazz'})
141
142        # delete Foo and Buzz tags unconditionally
143        $i->delete_tags(['Foo','Buzz'])
144
145        # delete Foo tag unconditionally
146        $i->delete_tags('Foo');
147
148       Also see VM::EC2->delete_tags() for a way of deleting tags from
149       multiple resources simultaneously.
150
151   $xml = $object->as_xml
152       Returns an XML version of the object. The object will already been
153       parsed by XML::Simple at this point, and so the data returned by this
154       method will not be identical to the XML returned by AWS.
155
156   $value = $object->attribute('tag_name')
157       Returns the value of a tag in the XML returned from AWS, using a simple
158       heuristic. If the requested tag has a nested tag named <value> it will
159       return the contents of <value>. If the tag has one or more nested tags
160       named <item>, it will return a list of hashrefs located within the
161       <item> tag. Otherwise it will return the contents of <tag_name>.
162
163   $string = $object->error_str
164       Returns the error string for the last operation, if any, as reported by
165       VM::EC2.
166
167   $string = $object->error
168       Returns the VM::EC2::Error object from the last operation, if any, as
169       reported by VM::EC2.
170

STRING OVERLOADING

172       This base class and its subclasses use string overloading so that the
173       object looks and acts like a simple string when used in a string
174       context (such as when printed or combined with other strings).
175       Typically the string corresponds to the Amazon resource ID such as
176       "ami-12345" and is generated by the short_name() method.
177
178       You can sort and compare the objects as if they were strings, but
179       despite this, object method calls work in the usual way.
180

AUTHOR

192       Lincoln Stein <lincoln.stein@gmail.com>.
193
194       Copyright (c) 2011 Ontario Institute for Cancer Research
195
196       This package and its accompanying libraries is free software; you can
197       redistribute it and/or modify it under the terms of the GPL (either
198       version 1, or at your option, any later version) or the Artistic
199       License 2.0.  Refer to LICENSE for the full license text. In addition,
200       please see DISCLAIMER.txt for disclaimers of warranty.
201

POD ERRORS

203       Hey! The above document had some coding errors, which are explained
204       below:
205
206       Around line 166:
207           =back without =over
208
209
210
211perl v5.32.0                      2020-07-28               VM::EC2::Generic(3)