Ubuntu Manpage: VM::EC2::Generic - Base class for VM::EC2 objects

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.

   $hashref = $object->tags
   $hashref = $object->tagSet
       Return the metadata tags assigned to this resource, if any, as a hashref. Both tags() and
       tagSet() work identically.

   $boolean = $object->add_tags(Tag1=>'value1',Tag2=>'value2',...)
   $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.

       Also see VM::EC2->add_tags() for a way of tagging multiple resources simultaneously.

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

   $boolean = $object->delete_tags(@args)
       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.

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.

NAME

SYNOPSIS

DESCRIPTION

METHODS

STRING OVERLOADING

SEE ALSO

AUTHOR