NAME
Net::Amazon::Utils - Implementation of a set of utilities to help in developing Amazon web service modules in Perl.
VERSION
Version 0.21
SYNOPSIS
This module implements a set of helpers that should be of aid to programming client to Amazon RESTful webservices.
Loosely based in com.amazonaws.regions.Region at http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/regions/Region.html
use Net::Amazon::Utils;
my $utils = Net::Amazon::Utils->new();
# get a list of all regions
my @all_regions = $utils->get_regions();
# get a list of all services abbreviations
my @all_services = $utils->get_services();
# get all endpoints for ec2
my @service_endpoints = $utils->get_service_endpoints( 'ec2' );
my $endpoint_uri;
# check that ec2 exists in region us-west-1
if ( $utils->is_service_supported( 'ec2', 'us-west-1' ) ) {
# check that http is supported by the end point
if ( $utils->get_http_support( 'ec2', 'us-west-1' ) ) {
# get the first http endpoint for ec2 in region us-west-1
$endpoint_uri =($utils->get_endpoint_uris( 'Http', 'ec2', 'us-west-1' ))[0];
#... use LWP to POST, send get comments
#... use Net::Amazon::EC2
}
}
# get endpoints for ec2 with http support on two given regions
my @some_endpoints = $utils->get_http_support( 'ec2', 'us-west-1', 'us-east-1' );
# check ec2 is supported on all us regions
my @us_regions = grep( /^us/, $utils->get_regions );
my @us_endpoints;
if ( $utils->is_service_supported( 'ec2', @us_regions ) ) {
# get endpoints for ec2 with http support on all us regions
@us_endpoints = $utils->get_http_support( 'ec2', @us_regions );
# choose a random one and give you images a spin
# ...
}SUBROUTINES/METHODS
new( [ $no_cache = 0 ], [ $no_inet = 1 ] )
Spawns a blessed Net::Amazon::Utils minion.
$no_cache means regions will be reloaded with each call to a function and will likely be deprecated. $no_inet means regions should never be fetched from the Internet unless forced by fetch_region_update.
fetch_region_update
Fetch regions file from the internet even if no_inet was specified when intanciating the object.
get_domain
Currently returns 'amazonaws.com' which is the only supported domain.
get_regions
Returns a list of regions abbreviations, i.g., us-west-1, us-east-1, eu-west-1, sa-east-1.
get_services
Returns a list of services abbreviations, i.g., ec2, sqs, glacier.
get_service_endpoints
Returns a list of the available services endpoints.
get_http_support( $service, [ @regions ] )
Returns a list of the available http services endpoints for a service abbreviation as returned by get_services. A region or list of regions can be specified to narrow down the results.
get_https_support( $service, [ @regions ] )
@regions is an optional list of regions to narrow down the results.
Returns a list of the available https services endpoints for a service abbreviation as returned by get_services.
get_protocol_support( $protocol, $service, [ @regions ] )
@regions is an optional list of regions to narrow down the results.
Returns a list of the available services endpoints for a service abbreviation as returned by get_services for a given protocol. Protocols should be cased accordingly.
get_service_endpoint( $protocol, $service, @regions )
$protocol is a protocol as returned by get_known_protocols. $service is a service abbreviation as returned by get_services. @regions is a list of regions as returned by get_regions.
Returns the list of endpoints for the specified protocol and service on a list of regions.
is_service_supported( $service, @regions )
$service is a service abbreviation as returned by get_services. @regions is a list of regions as returned by get_regions.
Returns true if the service is supported in all listed regions.
has_http_endpoint( $service, @regions )
$service is a service abbreviation as returned by get_services. @regions is a list of regions as returned by get_regions.
Returns true if an http endpoint exists for the service on the region or list or regions
has_https_endpoint( $service, @regions )
$service is a service abbreviation as returned by get_services. @regions is a list of regions as returned by get_regions.
Returns true if an https endpoint exists for the service on the region or list or regions
has_protocol_endpoint( $protocol, $service, @regions )
$protocol is a protocol as returned by get_known_protocols. $service is a service abbreviation as returned by get_services. @regions is a list of regions as returned by get_regions.
Returns true if an endpoint of the specified protocol exists for the service on the region or list or regions
get_known_protocols
Returns a list of known endpoint protocols, e.g. Http, Https (note casing).
set_known_protocols ( @protocols )
Sets the list of known protocols. Should not be used unless Net::Amazon::Utils::Regions is really outdated or you are blatantly galant and brave, probably reckless. Remember to properly case protocols and rerun test including your set protocols.
Returns the newly set protocols.
reset_known_protocols
Sets the list of known protocols to Net::Amazon::Utils::Regions defaults. Should fix bad set_known_protocols.
get_endpoint_uris( $protocol, $service, @regions )
$protocol is a protocol as returned by get_known_protocols. $service is a service abbreviation as returned by get_services. @regions is a list of regions as returned by get_regions.
Returns a list of protocol://service.region.domain URIs usable for RESTful fidling.
Internal Functions
_load_regions( [$force] )
Loads regions from local cached file or the Internet performing reasonable formatting.
$force, does what it should when set.
If Internet fails local cached file is used. If loading of new region definitions fail, old regions remain unaffected.
_unload_regions
Unloads regions recovering memory unless object has been instantiated with cache_regions set to any true value.
_force_unload_regions
Unloads regions recovering memory.
_get_remote_regions_file_uri
Returns the uri of the remote regions.xml file.
get_regions_file_raw
Returns the full structure (plus possibly cached queries) of the interpreted regions.xml file.
_is_true
Converts a supposed truth into a true Perl true value if the value should be true perlishly speaking.
Returns a true value on strings that should be true in regions.xml parlance.
AUTHOR
Gonzalo Barco, <gbarco uy at gmail com, no spaces>
TODO
Online tests that endpoints are actually there.
Better return values when scalar is expected.
Probably helpers for assembling and signing requests to actual endpoints.
BUGS
Please report any bugs or feature requests to bug-net-amazon-utils at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Amazon-Utils. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Net::Amazon::UtilsYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT
Copyright 2014 Gonzalo Barco.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.