The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Amazon-Utils-0.21
River stage zero No dependents
++
/ Net::Amazon::Utils

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::Utils

You can also look for information at:

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.