Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VM::EC2::Dispatch(3)  User Contributed Perl Documentation VM::EC2::Dispatch(3)

NAME
       VM::EC2::Dispatch - Create Perl objects from AWS	XML requests

SYNOPSIS
	 use VM::EC2;

	 VM::EC2::Dispatch->register('DescribeRegions'=>\&mysub);

	 VM::EC2::Dispatch->replace('DescribeRegions'=>'My::Type');

	 sub mysub {
	     my	($parsed_xml_object,$ec2) = @_;
	     my	$payload = $parsed_xml_object->{regionInfo}
	     return My::Type->new($payload,$ec2);
	 }

DESCRIPTION
       This class handles turning the XML response to AWS requests into	perl
       objects.	Only one method	is likely to be	useful to developers, the
       replace() class method. This allows you to replace the handlers used to
       map the response	onto objects.

   VM::EC2::Dispatch->replace($request_name => \&sub)
   VM::EC2::Dispatch->replace($request_name => 'Class::Name')
   VM::EC2::Dispatch->replace($request_name => 'method_name,arg1,arg2,...')
       Before invoking a VM::EC2 request you wish to customize,	call the
       replace() method	with two arguments. The	first argument is the name of
       the request you wish to customize, such as "DescribeVolumes". The
       second argument is either a code	reference, a VM::EC2::Dispatch method
       name and	arguments (separated by	commas), or a class name.

       In the case of a	code reference as the second argument, the subroutine
       you provide will	be invoked with	four arguments consisting of the
       parsed XML response, the	VM::EC2	object,	the XML	namespace string from
       the request, and	the Amazon-assigned request ID.	In practice, only the
       first two arguments are useful.

       In the case of a	string containing a classname, the class will be
       loaded if it needs to be, and then its new() method invoked as follows:

	 Your::Class->new($parsed_xml,$ec2,$xmlns,$requestid)

       Your new() method should	return one or more objects. It is suggested
       that you	subclass VM::EC2::Generic and use the inherited	new() method
       to store	the parsed XML and EC2 object. See the code for
       VM::EC2::AvailabilityRegion for a simple	template.

       If the second argument is neither a code	reference nor a	classname, it
       will be treated as a VM::EC2::Dispatch method name and its arguments,
       separated by commas. The	method will be invoked as follows:

	$dispatch->$method_name($raw_xml,$ec2,$arg1,$arg2,$arg3,...)

       There are two methods currently defined for this	purpose, boolean(),
       and fetch_items(), which	handle the preprocessing of several common XML
       representations of EC2 data. Note that in this form, the	RAW XML	is
       passed in, not the parsed data structure.

       The parsed XML response is generated by the XML::Simple module using
       these options:

	 $parser = XML::Simple->new(ForceArray	  => ['item', 'member'],
				    KeyAttr	  => ['key'],
				    SuppressEmpty => undef);
	 $parsed = $parser->XMLin($raw_xml)

       In general, this	will give you a	hash of	hashes.	Any tag	named 'item'
       or 'member' will	be forced to point to an array reference, and any tag
       named "key" will	be flattened as	described in the XML::Simple
       documentation.

       A simple	way to examine the raw parsed XML is to	invoke any
       VM::EC2::Object's as_string method:

	my ($i)	= $ec2->describe_instances;
	print $i->as_string;

       This will give you a Data::Dumper representation	of the XML after it
       has been	parsed.	Look at	the calls to VM::EC2::Dispatch->register() in
       the various VM/EC2/REST/*.pm modules for	many examples of how this
       works.

       Note that the replace() method was called add_override()	in previous
       versions	of this	module.	add_override() is recognized as	an alias for
       backward	compatibility.

   VM::EC2::Dispatch->register($request_name1 => \&sub1,$request_name2 =>
       \&sub2,...)
       Similar to replace() but	if the request name is already registered does
       not overwrite it. You may provide multiple request=>handler pairs.

OBJECT CREATION	METHODS
       The following methods perform simple pre-processing of the parsed XML
       (a hash of hashes) before passing the modified data structure to	the
       designated object class.	They are used as the second argument to
       VM::EC2::Dispatch->register().

   $bool = $dispatch->boolean($raw_xml,$ec2,$tag)
       This is used for	XML responses like this:

	<DeleteVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2011-05-15/">
	   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
	   <return>true</return>
	</DeleteVolumeResponse>

       It looks	inside the structure for the tag named $tag ("return" if not
       provided), and returns a	true value if the contents equals "true".

       Pass it to replace() like this:

	 VM::EC2::Dispatch->replace(DeleteVolume => 'boolean,return';

       or, since "return" is the default tag:

	 VM::EC2::Dispatch->replace(DeleteVolume => 'boolean';

   @list = $dispatch->elb_member_list($raw_xml,$ec2,$tag)
       This is used for	XML responses from the ELB API such as this:

	<DisableAvailabilityZonesForLoadBalancerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2011-11-15/">
	  <DisableAvailabilityZonesForLoadBalancerResult>
	    <AvailabilityZones>
	      <member>us-west-2a</member>
	      <member>us-west-2b</member>
	    </AvailabilityZones>
	  </DisableAvailabilityZonesForLoadBalancerResult>
	  <ResponseMetadata>
	    <RequestId>02eadcfc-fc38-11e1-a1bf-9de31EXAMPLE</RequestId>
	  </ResponseMetadata>
	</DisableAvailabilityZonesForLoadBalancerResponse>

       It looks	inside the Result structure for	the tag	named $tag and returns
       the list	wrapped	in member elements.  In	this case the tag is
       'AvailabilityZones' and the return value	would be: ( 'us-west-2a',
       'us-west-2b' )

       If $embedded_tag	is passed, then	it is used for XML responses such as
       this, where the member list has an embedded tag:

	<RegisterInstancesWithLoadBalancerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2011-11-15/">
	  <RegisterInstancesWithLoadBalancerResult>
	    <Instances>
	      <member>
		<InstanceId>i-12345678</InstanceId>
	      </member>
	      <member>
		<InstanceId>i-90abcdef</InstanceId>
	      </member>
	    </Instances>
	  </RegisterInstancesWithLoadBalancerResult>
	  <ResponseMetadata>
	    <RequestId>f4f12596-fc3b-11e1-be5a-f71ecEXAMPLE</RequestId>
	  </ResponseMetadata>
	</RegisterInstancesWithLoadBalancerResponse>

       It looks	inside the Result structure for	the tag	named $tag and returns
       the list	wrapped	in a member element plus the embedded tag.  In this
       case the	tag is 'Instances', the	embedded tag is	'InstanceId' and the
       return value would be: (	'i-12345678', 'i-90abcdef' )

   @objects =
       $dispatch->fetch_items($raw_xml,$ec2,$container_tag,$object_class,$nokey)
       This is used for	XML responses like this:

	<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2011-05-15/">
	   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
	   <keySet>
	     <item>
		<keyName>gsg-keypair</keyName>
		<keyFingerprint>
		1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f
		</keyFingerprint>
	     </item>
	     <item>
		<keyName>default-keypair</keyName>
		<keyFingerprint>
		0a:93:bb:e8:c2:89:e9:d8:1f:42:5d:37:1d:8d:b8:0a:88:f1:f1:1a
		</keyFingerprint>
	     </item>
	  </keySet>
	</DescribeKeyPairsResponse>

       It looks	inside the structure for the tag named $container_tag, pulls
       out the items that are stored under <item> and then passes the parsed
       contents	to $object_class->new(). The optional $nokey argument is used
       to suppress XML::Simple's default flattening behavior turning tags
       named "key" into	hash keys.

       Pass it to replace() like this:

	 VM::EC2::Dispatch->replace(DescribeVolumes => 'fetch_items,volumeSet,VM::EC2::Volume')

   @objects =
       $dispatch->fetch_members($raw_xml,$ec2,$container_tag,$object_class,$nokey)
       Used for	XML responses from ELB API calls which contain a key that is
       the name	of the API call	with 'Result' appended.	 All these XML
       responses contain 'member' as the item delimiter	instead	of 'item'

   @objects =
       $dispatch->fetch_rds_objects($raw_xml,$ec2,$container_tag,$object_class,$nokey)
       Used for	XML responses from RDS API calls which contain a key that is
       the name	of the API call	with 'Result' appended.	 In addition, the
       structure is a list of objects wrapped in a plural version of the
       object's	name.

   @objects =
       $dispatch->fetch_items_iterator($raw_xml,$ec2,$container_tag,$object_class,$token_name)
       This is used for	requests that have a -max_results argument. In this
       case, the response will have a nextToken	field, which can be used to
       fetch the "next page" of	results.

       The $token_name is some unique identifying token. It will be turned
       into two	temporary EC2 instance variables, one named
       "${token_name}_token", which contains the nextToken value, and the
       other "${token_name}_stop", which flags the caller that no more results
       will be forthcoming.

       This must all be	coordinated with the request subroutine. See how
       describe_instance_status() and describe_spot_price_history() do it.

EXAMPLE	OF USING OVERRIDE TO SUBCLASS VM::EC2::Volume
       The author decided that a volume	object should not be able to delete
       itself; you disagree with that decision.	Let's subclass VM::EC2::Volume
       to add a	delete() method.

       First subclass the VM::EC2::Volume class:

	package	MyVolume;
	use base 'VM::EC2::Volume';

	sub delete {
	   my $self = shift;
	   $self->ec2->delete_volume($self);
	}

       Now subclass VM::EC2 to add the appropriate overrides to	the new()
       method:

	package	MyEC2;
	use base 'VM::EC2';

	sub new	{
	  my $class = shift;
	  VM::EC2::Dispatch->replace(CreateVolume   =>'MyVolume');
	  VM::EC2::Dispatch->replace(DescribeVolumes=>'fetch_items,volumeSet,MyVolume');
	  return $class->SUPER::new(@_);
	}

       Now we can test it out:

	use MyEC2;
	# find all volumes that	are "available"	and not	in-use
	my @vol	= $ec2->describe_volumes({status=>'available'});
	for my $vol (@vol) {
	   $vol->delete	&& print "$vol deleted\n"
	}

SEE ALSO
       VM::EC2 VM::EC2::Object VM::EC2::Generic	VM::EC2::BlockDevice
       VM::EC2::BlockDevice::Attachment	VM::EC2::BlockDevice::Mapping
       VM::EC2::BlockDevice::Mapping::EBS VM::EC2::Error VM::EC2::Generic
       VM::EC2::Group VM::EC2::Image VM::EC2::Instance
       VM::EC2::Instance::ConsoleOutput	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.

perl v5.24.1			  2017-07-02		  VM::EC2::Dispatch(3)

NAME | SYNOPSIS | DESCRIPTION | OBJECT CREATION METHODS | EXAMPLE OF USING OVERRIDE TO SUBCLASS VM::EC2::Volume | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=VM::EC2::Dispatch&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help