grempe-amazon-ec2 0.5.1 → 0.5.2

data/.gitignore

@@ -2,5 +2,7 @@
 .DS_Store
 coverage
 rdoc
+doc
+.yardoc
 pkg
 

data/.yardopts

@@ -0,0 +1 @@
+--title amazon-ec2 - ChangeLog LICENSE

data/ChangeLog

@@ -1,3 +1,6 @@
+=== 0.5.2 2009-08-20
+ * Converted to YardDoc documentation format. See : http://yard.soen.ca/getting_started
+
 === 0.5.0 2009-08-11
  * Major re-factor by Kris Rasmussen (krisr) to add support for the AWS Elastic Load Balancer API. Kudos Kris!
 

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2008 Glenn Rempe
+Copyright (c) 2007-2009 Glenn Rempe
 
 This software is distributed under the Ruby License.  A copy of which is
 provided below.

data/README.rdoc

@@ -305,12 +305,24 @@ So, for example, if you wanted to get the image ID of the third image listed in
 
 EC2 will typically return sets of things (imagesSet, reservationSet, etc.) which we map to ruby Arrays (.imagesSet.item in the example above). If you want to iterate over a response set you will need to iterate over this array. The Arrays will typically contain additional AWS::Response objects that represent each individual item. You'll find that you can use the 'ec2sh' to help you understand the structure more completely if you try issuing commands there as a way to practice seeing what will be returned and making sure you get exactly what you want.
 
+=== Handling Exceptions
+If for some reason an error occurs when executing a method (e.g. its arguments were
+incorrect, or it simply failed) then an exception will be thrown.  The exceptions are
+defined in exceptions.rb as individual classes and should match the exceptions that
+AWS has defined in the API.  If the exception raised cannot be identified then a
+more generic exception class will be thrown.
+
+The implication of this is that you need to be prepared to handle any exceptions that
+may be raised by this library in YOUR code with a 'rescue' clause.  It is up to you
+to determine how you want to handle these exceptions in your code.
+
 
 == Additional Resources
 
 === Project Websites
 
 * Project Home : http://github.com/grempe/amazon-ec2/tree/master
+* API Documentation : http://rdoc.info/projects/grempe/amazon-ec2
 * Discussion Group : http://groups.google.com/group/amazon-ec2
 * Report Bugs / Request Features : http://github.com/grempe/amazon-ec2/issues
 * Amazon Web Services : http://aws.amazon.com
@@ -321,7 +333,7 @@ The original code for this library was provided by Amazon Web Services, LLC as s
 
 == Contact
 
-Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or use the Google Groups forum for this project.
+Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or join the Google Groups forum.
 
 Enjoy!
 

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rubygems'
 require 'rake'
+require 'yard'
 
 require 'jeweler'
 Jeweler::Tasks.new do |gem|
@@ -47,19 +48,8 @@ end
 
 task :default => :test
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION.yml')
-    config = YAML.load(File.read('VERSION.yml'))
-    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "amazon-ec2 #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+YARD::Rake::YardocTask.new do |t|
+  #t.files   = ['lib/**/*.rb']
 end
 
 begin
@@ -70,15 +60,15 @@ begin
     task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
 
     namespace :release do
-      desc "Publish RDoc to RubyForge."
-      task :docs => [:rdoc] do
+      desc "Publish YARD docs to RubyForge."
+      task :docs => [:doc] do
         config = YAML.load(
             File.read(File.expand_path('~/.rubyforge/user-config.yml'))
         )
 
         host = "#{config['username']}@rubyforge.org"
         remote_dir = "/var/www/gforge-projects/amazon-ec2/"
-        local_dir = 'rdoc'
+        local_dir = 'doc'
 
         Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
       end

data/VERSION

@@ -1 +1 @@
-0.5.1
+0.5.2

data/amazon-ec2.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{amazon-ec2}
-  s.version = "0.5.1"
+  s.version = "0.5.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Glenn Rempe"]
@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   ]
   s.files = [
     ".gitignore",
+     ".yardopts",
      "ChangeLog",
      "LICENSE",
      "README.rdoc",
@@ -75,12 +76,11 @@ Gem::Specification.new do |s|
      "wsdl/2008-05-05.ec2.wsdl",
      "wsdl/2008-12-01.ec2.wsdl"
   ]
-  s.has_rdoc = true
   s.homepage = %q{http://github.com/grempe/amazon-ec2}
   s.rdoc_options = ["--title", "amazon-ec2 documentation", "--line-numbers", "--main", "README.rdoc"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{amazon-ec2}
-  s.rubygems_version = %q{1.3.1}
+  s.rubygems_version = %q{1.3.5}
   s.summary = %q{Amazon EC2 Ruby Gem}
   s.test_files = [
     "test/test_EC2.rb",
@@ -103,7 +103,7 @@ Gem::Specification.new do |s|
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 2
+    s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<xml-simple>, [">= 1.0.12"])

data/lib/AWS.rb

@@ -1,16 +1,47 @@
-# Require any lib files that we have bundled with this Ruby Gem in the lib/AWS directory.
-# Parts of the AWS module and Base class are broken out into separate
-# files for maintainability and are organized by the functional groupings defined
-# in the AWS API developers guide.
-
+#--
+# Amazon Web Services EC2 + ELB API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
+# Copyright:: Copyright (c) 2007-2009 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
+#++
 
 %w[ base64 cgi openssl digest/sha1 net/https rexml/document time ostruct ].each { |f| require f }
 
+begin
+  require 'xmlsimple' unless defined? XmlSimple
+rescue Exception => e
+  require 'xml-simple' unless defined? XmlSimple
+end
+
+
+# A custom implementation of Hash that allows us to access hash values using dot notation
+#
+# @example Access the hash keys in the standard way or using dot notation
+#   foo[:bar] => "baz"
+#   foo.bar => "baz"
+class Hash
+  def method_missing(meth, *args, &block)
+    if args.size == 0
+      self[meth.to_s] || self[meth.to_sym]
+    end
+  end
+end
+
+
 module AWS
-  # Builds the canonical string for signing. This strips out all '&', '?', and '='
-  # from the query string to be signed.
-  #   Note:  The parameters in the path passed in must already be sorted in
-  #   case-insensitive alphabetical order and must not be url encoded.
+
+  # Builds the canonical string for signing requests. This strips out all '&', '?', and '='
+  # from the query string to be signed.  The parameters in the path passed in must already
+  # be sorted in case-insensitive alphabetical order and must not be url encoded.
+  #
+  # @param [String] params the params that will be sorted and encoded as a canonical string.
+  # @param [String] host the hostname of the API endpoint.
+  # @param [String] method the HTTP method that will be used to submit the params.
+  # @param [String] base the URI path that this information will be submitted to.
+  # @return [String] the canonical request description string.
   def AWS.canonical_string(params, host, method="POST", base="/")
     # Sort, and encode parameters into a canonical string.
     sorted_params = params.sort {|x,y| x[0] <=> y[0]}
@@ -31,10 +62,15 @@ module AWS
 
   end
 
-  # Encodes the given string with the secret_access_key, by taking the
+  # Encodes the given string with the secret_access_key by taking the
   # hmac-sha1 sum, and then base64 encoding it.  Optionally, it will also
   # url encode the result of that to protect the string if it's going to
   # be used as a query string parameter.
+  #
+  # @param [String] secret_access_key the user's secret access key for signing.
+  # @param [String] str the string to be hashed and encoded.
+  # @param [Boolean] urlencode whether or not to url encode the result., true or false
+  # @return [String] the signed and encoded string.
   def AWS.encode(secret_access_key, str, urlencode=true)
     digest = OpenSSL::Digest::Digest.new('sha1')
     b64_hmac =
@@ -48,10 +84,21 @@ module AWS
     end
   end
 
+  # This class provides all the methods for using the EC2 or ELB service
+  # including the handling of header signing and other security concerns.
+  # This class uses the Net::HTTP library to interface with the AWS Query API
+  # interface. You should not instantiate this directly, instead
+  # you should setup an instance of 'AWS::EC2::Base' or 'AWS::ELB::Base'.
   class Base
 
     attr_reader :use_ssl, :server, :proxy_server, :port
 
+    # @option options [String] :access_key_id ("") The user's AWS Access Key ID
+    # @option options [String] :secret_access_key ("") The user's AWS Secret Access Key
+    # @option options [Boolean] :use_ssl (true) Connect using SSL?
+    # @option options [String] :server ("ec2.amazonaws.com") The server API endpoint host
+    # @option options [String] :proxy_server (nil) An HTTP proxy server FQDN
+    # @return [Object] the object.
     def initialize( options = {} )
 
       options = { :access_key_id => "",
@@ -242,4 +289,5 @@ module AWS
   end
 end
 
-Dir[File.join(File.dirname(__FILE__), 'AWS/*.rb')].sort.each { |lib| require lib }
+Dir[File.join(File.dirname(__FILE__), 'AWS/**/*.rb')].sort.each { |lib| require lib }
+

data/lib/AWS/EC2.rb

@@ -1,58 +1,23 @@
-#--
-# Amazon Web Services EC2 Query API Ruby library
-#
-# Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
-# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
-# License::   Distributes under the same terms as Ruby
-# Home::      http://github.com/grempe/amazon-ec2/tree/master
-#++
-
-# Require any lib files that we have bundled with this Ruby Gem in the lib/EC2 directory.
-# Parts of the EC2 module and Base class are broken out into separate
-# files for maintainability and are organized by the functional groupings defined
-# in the EC2 API developers guide.
-Dir[File.join(File.dirname(__FILE__), 'EC2/**/*.rb')].sort.each { |lib| require lib }
-
 module AWS
   module EC2
 
     # Which host FQDN will we connect to for all API calls to AWS?
-    # If EC2_URL is defined in the users ENV we can use that. It is
-    # expected that this var is set with something like:
-    #   export EC2_URL='https://ec2.amazonaws.com'
+    # If EC2_URL is defined in the users ENV we can override the default with that.
     #
+    # @example
+    #   export EC2_URL='https://ec2.amazonaws.com'
     if ENV['EC2_URL']
       EC2_URL = ENV['EC2_URL']
       VALID_HOSTS = ['https://ec2.amazonaws.com', 'https://us-east-1.ec2.amazonaws.com', 'https://eu-west-1.ec2.amazonaws.com']
       raise ArgumentError, "Invalid EC2_URL environment variable : #{EC2_URL}" unless VALID_HOSTS.include?(EC2_URL)
       DEFAULT_HOST = URI.parse(EC2_URL).host
     else
-      # default US host
+      # Default US API endpoint
       DEFAULT_HOST = 'ec2.amazonaws.com'
     end
 
-    # This is the version of the API as defined by Amazon Web Services
     API_VERSION = '2008-12-01'
 
-    #Introduction:
-    #
-    # The library exposes one main interface class, 'AWS::EC2::Base'.
-    # This class provides all the methods for using the EC2 service
-    # including the handling of header signing and other security issues .
-    # This class uses Net::HTTP to interface with the EC2 Query API interface.
-    #
-    #Required Arguments:
-    #
-    # :access_key_id => String (default : "")
-    # :secret_access_key => String (default : "")
-    #
-    #Optional Arguments:
-    #
-    # :use_ssl => Boolean (default : true)
-    # :server => String (default : 'ec2.amazonaws.com')
-    # :proxy_server => String (default : nil)
-    #
     class Base < AWS::Base
       def api_version
         API_VERSION
@@ -64,4 +29,5 @@ module AWS
     end
 
   end
-end
+end
+

data/lib/AWS/EC2/availability_zones.rb

@@ -1,43 +1,21 @@
-#--
-# Amazon Web Services EC2 Query API Ruby library
-#
-# Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
-# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
-# License::   Distributes under the same terms as Ruby
-# Home::      http://github.com/grempe/amazon-ec2/tree/master
-#++
-
 module AWS
   module EC2
-
     class Base < AWS::Base
 
-      #Amazon Developer Guide Docs:
-      #
       # The DescribeAvailabilityZones operation describes availability zones that are currently
       # available to the account and their states.
       #
       # An optional list of zone names can be passed.
       #
-      #Required Arguments:
-      #
-      # none
+      # @option options [optional, String] :zone_name ([]) an Array of zone names
       #
-      #Optional Arguments:
-      #
-      # :zone_name => Array (default : [])
-      #
-
       def describe_availability_zones( options = {} )
-
         options = { :zone_name => [] }.merge(options)
-
         params = pathlist("ZoneName", options[:zone_name] )
-
         return response_generator(:action => "DescribeAvailabilityZones", :params => params)
-
       end
+
     end
   end
-end
+end
+

data/lib/AWS/EC2/console.rb

@@ -1,46 +1,23 @@
-#--
-# Amazon Web Services EC2 Query API Ruby library
-#
-# Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
-# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
-# License::   Distributes under the same terms as Ruby
-# Home::      http://github.com/grempe/amazon-ec2/tree/master
-#++
-
 module AWS
   module EC2
-
     class Base < AWS::Base
 
-      #Amazon Developer Guide Docs:
-      #
       # The GetConsoleOutput operation retrieves console output that has been posted for the specified instance.
       #
       # Instance console output is buffered and posted shortly after instance boot, reboot and once the instance
       # is terminated. Only the most recent 64 KB of posted output is available. Console output is available for
       # at least 1 hour after the most recent post.
       #
-      #Required Arguments:
-      #
-      # :instance_id => String (default : "")
+      # @option options [String] :instance_id ("") an Instance ID
       #
-      #Optional Arguments:
-      #
-      # none
-      #
-      def get_console_output( options ={} )
-
+      def get_console_output( options = {} )
         options = {:instance_id => ""}.merge(options)
-
         raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?
-
         params = { "InstanceId" => options[:instance_id] }
-
         return response_generator(:action => "GetConsoleOutput", :params => params)
-
       end
-    end
 
+    end
   end
-end
+end
+

data/lib/AWS/EC2/elastic_ips.rb

@@ -1,60 +1,23 @@
-#--
-# Amazon Web Services EC2 Query API Ruby library
-#
-# Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
-# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
-# License::   Distributes under the same terms as Ruby
-# Home::      http://github.com/grempe/amazon-ec2/tree/master
-#++
-
 module AWS
   module EC2
     class Base < AWS::Base
 
-
-      #Amazon Developer Guide Docs:
-      #
       # The AllocateAddress operation acquires an elastic IP address for use with your account.
       #
-      #Required Arguments:
-      #
-      # none
-      #
-      #Optional Arguments:
-      #
-      # none
-      #
       def allocate_address
-
         return response_generator(:action => "AllocateAddress")
-
       end
 
-      #Amazon Developer Guide Docs:
-      #
       # The DescribeAddresses operation lists elastic IP addresses assigned to your account.
       #
-      #Required Arguments:
-      #
-      # :public_ip => Array (default : [], can be empty)
-      #
-      #Optional Arguments:
-      #
-      # none
+      # @option options [Array] :public_ip ([]) an IP address to be described
       #
       def describe_addresses( options = {} )
-
         options = { :public_ip => [] }.merge(options)
-
         params = pathlist("PublicIp", options[:public_ip])
-
         return response_generator(:action => "DescribeAddresses", :params => params)
-
       end
 
-      #Amazon Developer Guide Docs:
-      #
       # The ReleaseAddress operation releases an elastic IP address associated with your account.
       #
       # If you run this operation on an elastic IP address that is already released, the address
@@ -68,87 +31,51 @@ module AWS
       # to update your DNS records and any servers or devices that communicate
       # with the address.
       #
-      #Required Arguments:
-      #
-      # :public_ip => String (default : '')
-      #
-      #Optional Arguments:
-      #
-      # none
+      # @option options [String] :public_ip ('') an IP address to be released.
       #
       def release_address( options = {} )
-
         options = { :public_ip => '' }.merge(options)
-
         raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
-
         params = { "PublicIp" => options[:public_ip] }
-
         return response_generator(:action => "ReleaseAddress", :params => params)
-
       end
 
-      #Amazon Developer Guide Docs:
-      #
       # The AssociateAddress operation associates an elastic IP address with an instance.
       #
       # If the IP address is currently assigned to another instance, the IP address
       # is assigned to the new instance. This is an idempotent operation. If you enter
       # it more than once, Amazon EC2 does not return an error.
       #
-      #Required Arguments:
-      #
-      # :instance_id  => String (default : '')
-      # :public_ip    => String (default : '')
-      #
-      #Optional Arguments:
-      #
-      # none
+      # @option options [String] :instance_id ('') the instance ID to associate an IP with.
+      # @option options [String] :public_ip ('') the public IP to associate an instance with.
       #
       def associate_address( options = {} )
-
         options = { :instance_id => '', :public_ip => '' }.merge(options)
-
         raise ArgumentError, "No ':instance_id' provided" if options[:instance_id].nil? || options[:instance_id].empty?
         raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
-
         params = {
           "InstanceId" => options[:instance_id],
           "PublicIp" => options[:public_ip]
         }
-
         return response_generator(:action => "AssociateAddress", :params => params)
-
       end
 
-      #Amazon Developer Guide Docs:
-      #
       # The DisassociateAddress operation disassociates the specified elastic IP
       # address from the instance to which it is assigned. This is an idempotent
       # operation. If you enter it more than once, Amazon EC2 does not return
       # an error.
       #
-      #Required Arguments:
-      #
-      # :public_ip    => String (default : '')
-      #
-      #Optional Arguments:
-      #
-      # none
+      # @option options [String] :public_ip ('') the public IP to be dis-associated.
       #
       def disassociate_address( options = {} )
-
         options = { :public_ip => '' }.merge(options)
-
         raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
-
         params = { "PublicIp" => options[:public_ip] }
-
         return response_generator(:action => "DisassociateAddress", :params => params)
-
       end
 
     end
 
   end
-end
+end
+