metaforce 0.3.1 → 0.3.2

data/Gemfile

@@ -7,4 +7,6 @@ group :development do
   gem "guard"
   gem "guard-rspec"
   gem "growl"
+  gem "yard"
+  gem "redcarpet"
 end

data/README.md

@@ -1,9 +1,10 @@
-# Metaforce
-![travis-ci](https://secure.travis-ci.org/ejholmes/metaforce.png)
+# Metaforce [![travis-ci](https://secure.travis-ci.org/ejholmes/metaforce.png)](https://secure.travis-ci.org/ejholmes/metaforce)
 
 Metaforce is a Ruby gem for interacting with the [Salesforce Metadata API](http://www.salesforce.com/us/developer/docs/api_meta/index.htm).
 The goal of this project is to make the [Migration Tool](http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_deploying_ant.htm) obsolete, favoring Rake over Ant.
 
+[Documentation](http://rubydoc.info/gems/metaforce/frames)
+
 ## Installation
 ```bash
 gem install metaforce
@@ -74,6 +75,11 @@ feature on a new branch, then send me a pull request with a detailed
 description. Please provide applicable rspec specs.
 
 ## Version History
+**0.3.2** (February 3, 2012)
+
+* Improved documentation.
+* Added `.status` method to Transaction class.
+
 **0.3.1** (February 3, 2012)
 
 * Dynamically defined helper methods for .list (e.g. `client.list_apex_classes`, `client.list_custom_objects`).

data/lib/metaforce/api/metadata.rb

@@ -11,12 +11,15 @@ module Metaforce
       RETRIEVE_ZIP = 'retrieve.zip' # :nodoc:
 
       # Performs a login and sets the session_id and metadata_server_url.
-      # _options_ should be hash containing the :username, :password and
-      # :security_token keys.
       #
-      #  Metaforce::Metadata::Client.new :username => "username",
-      #    :password => "password",
-      #    :security_token => "security token"
+      # +options+ should be hash containing the +:username+, +:password+ and
+      # +:security_token+ keys.
+      #
+      # == Examples
+      #
+      #   Metaforce::Metadata::Client.new :username => "username",
+      #     :password => "password",
+      #     :security_token => "security token"
       def initialize(options=nil)
         @session = Services::Client.new(options).session
         @client = Savon::Client.new File.expand_path("../../../../wsdl/#{Metaforce.configuration.api_version}/metadata.xml", __FILE__) do |wsdl|
@@ -30,12 +33,17 @@ module Metaforce
         }
       end
 
-      # Specify an array of component types to list
+      # Specify an array of component types to list.
+      #
+      # == Examples
+      #
+      #   # Get a list of apex classes on the server and output the names of each
+      #   client.list(:type => "ApexClass").collect { |t| t[:full_name] }
+      #   #=> ["al__SObjectPaginatorListenerForTesting", "al__IndexOutOfBoundsException", ... ]
       #
-      #   [
-      #     { :type => "ApexClass" },
-      #     { :type => "ApexComponent" }
-      #   ]
+      #   # Get a list of apex components and apex classes
+      #   client.list([{ :type => "CustomObject" }, { :type => "ApexComponent" }])
+      #   #=> ["ContractContactRole", "Solution", "Invoice_Statements__c", ... ]
       def list(queries=[])
         unless queries.is_a?(Array)
           queries = [ queries ]
@@ -51,10 +59,15 @@ module Metaforce
 
       # Defines some helper methods for listing metadata types
       #
-      # Example
+      # == Examples
       #  
-      #   client.list_apex_classes
-      #   client.list_custom_objects
+      #   # List the names of all apex classes
+      #   client.list_apex_classes.collect { |t| t[:full_name] }
+      #   #=> ["al__SObjectPaginatorListenerForTesting", "al__IndexOutOfBoundsException", ... ]
+      #
+      #   # List the names of all custom objects
+      #   client.list_custom_objects.collect { |t| t[:full_name] }
+      #   #=> ["Asset", "estore__Ida_Menu_Item__c", "SfoMatchHistoryItem", ... ]
       METADATA_TYPES.each do |type, value|
         define_method("list_#{value[:plural]}".to_sym) do
           list :type => value[:name]
@@ -62,11 +75,17 @@ module Metaforce
       end
 
       # Describe the organization's metadata and cache the response
+      #
+      # == Examples
+      #
+      #   # List the names of all metedata types
+      #   client.describe[:metadata_objects].collect { |t| t[:xml_name] }
+      #   #=> ["CustomLabels", "StaticResource", "Scontrol", "ApexComponent", ... ]
       def describe
         @describe ||= describe!
       end
 
-      # Describe the organization's metadata
+      # See +describe+
       def describe!
         response = @client.request(:describe_metadata) do |soap|
           soap.header = @header
@@ -74,10 +93,13 @@ module Metaforce
         @describe = response.body[:describe_metadata_response][:result]
       end
 
-      # Checks the status of an async result
+      # Checks the status of an async result. If type is +:retrieve+ or +:deploy+,
+      # it returns the RetrieveResult or DeployResult, respectively
       #
-      # If type is :retrieve or :deploy, it returns the RetrieveResult or
-      # DeployResult, respectively
+      # == Examples
+      # 
+      #   client.status('04sU0000000Wx6KIAS')
+      #   #=> {:done=>true, :id=>"04sU0000000Wx6KIAS", :state=>"Completed", :state_detail_last_modified_date=>#<DateTime: 2012-02-03T18:30:38+00:00 ((2455961j,66638s,0n),+0s,2299161j)>}
       def status(ids, type=nil)
         request = "check_status"
         request = "check_#{type.to_s}_status" unless type.nil?
@@ -93,15 +115,31 @@ module Metaforce
       end
 
       # Returns true if the deployment with id id is done, false otherwise
+      #
+      # == Examples
+      #
+      #   client.done?('04sU0000000Wx6KIAS')
+      #   #=> true
       def done?(id)
-        self.status(id)[:done]
+        self.status(id)[:done] || false
       end
 
-      # Deploys _dir_ to the organisation
+      # Deploys +dir+ to the organisation.
       #
       # See http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_deploy.htm#deploy_options
       # for a list of _deploy_options_. Options should be convereted from
       # camelCase to an :underscored_symbol.
+      #
+      # == Examples
+      # 
+      #   deploy = client.deploy File.expand_path("myeclipseproj")
+      #   #=> #<Metaforce::Transaction:0x1159bd0 @id='04sU0000000Wx6KIAS' @type=:deploy>
+      #
+      #   deploy.done?
+      #   #=> true
+      #
+      #   deploy.status[:state]
+      #   #=> "Completed"
       def deploy(dir, deploy_options={})
         if dir.is_a?(String)
           filename = File.join(File.dirname(dir), DEPLOY_ZIP)
@@ -135,9 +173,12 @@ module Metaforce
         Transaction.retrieval self, response[:retrieve_response][:result][:id]
       end
 
-      # Retrieves files specified in the manifest file (package.xml)
+      # Retrieves files specified in the manifest file (package.xml). Specificy any extra +retrieve_request+ options in +extra+.
+      #
+      # == Examples
       #
-      # Specificy any extra _retrieve_request_ options in _extra_.
+      #   retrieve = client.retrieve_unpackaged File.expand_path("spec/fixtures/sample/src/package.xml")
+      #   #=> #<Metaforce::Transaction:0x1159bd0 @id='04sU0000000Wx6KIAS' @type=:retrieve>
       def retrieve_unpackaged(manifest, extra=nil)
         if manifest.is_a?(Metaforce::Manifest)
           package = manifest.to_package

data/lib/metaforce/api/transaction.rb

@@ -4,24 +4,33 @@ module Metaforce
 
   # Convenience class for deployment/retrieval results
   class Transaction
+    # The Salesforce ID for this task
     attr_reader :id
+    # The type of transaction (e.g. _:deploy_, _:retrieve_)
     attr_reader :type
 
     def initialize(client, id, type)
-      @id = id
+      @id     = id
       @client = client
-      @type = type
+      @type   = type
     end
 
+    # Creates a new transaction and sets type to +:deploy+.
     def self.deployment(client, id)
       self.new client, id, :deploy
     end
 
+    # Creates a new transaction and sets type to +:retrieve+.
     def self.retrieval(client, id)
       self.new client, id, :retrieve
     end
 
-    # Returns true if the transaction has completed, false otherwise
+    # Wrapper for <tt>Client.status</tt>.
+    def status
+      @status = @client.status(@id)
+    end
+
+    # Wrapper for <tt>Client.done?</tt>.
     def done?
       @done = @client.done?(@id) unless @done
       @done
@@ -29,13 +38,13 @@ module Metaforce
     alias :complete? :done?
     alias :completed? :done?
 
-    # Returns the zip file from a retrieval
+    # Returns the decoded content of the returned zip file.
     def zip_file
       raise "Request was not a retrieve." if @type != :retrieve
       Base64.decode64(@result[:zip_file])
     end
 
-    # Unzips the returned zip file to _destination_
+    # Unzips the returned zip file to +destination+.
     def unzip(destination)
       zip = zip_file
       file = Tempfile.new("retrieve")

data/lib/metaforce/version.rb

@@ -1,3 +1,3 @@
 module Metaforce
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/spec/lib/api/transaction_spec.rb

@@ -30,6 +30,17 @@ describe Metaforce::Transaction do
 
   end
 
+  describe ".status" do
+
+    it "returns the status" do
+      savon.expects(:deploy).with(:zip_file => '', :deploy_options => {}).returns(:in_progress)
+      deployment = client.deploy(File.expand_path('../../../fixtures/sample', __FILE__))
+      savon.expects(:check_status).with(:ids => [ "04sU0000000WNWoIAO" ]).returns(:done)
+      deployment.status.should be_a(Hash)
+    end
+    
+  end
+
   describe ".result" do
 
     it "raises an error if .done? hasn't been called" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: metaforce
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &9206270 !ruby/object:Gem::Requirement
+  requirement: &8411610 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 1.5.0
   type: :runtime
   prerelease: false
-  version_requirements: *9206270
+  version_requirements: *8411610
 - !ruby/object:Gem::Dependency
   name: savon
-  requirement: &9187580 !ruby/object:Gem::Requirement
+  requirement: &8409890 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 0.9.7
   type: :runtime
   prerelease: false
-  version_requirements: *9187580
+  version_requirements: *8409890
 - !ruby/object:Gem::Dependency
   name: rubyzip
-  requirement: &9170720 !ruby/object:Gem::Requirement
+  requirement: &8424970 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 0.9.5
   type: :runtime
   prerelease: false
-  version_requirements: *9170720
+  version_requirements: *8424970
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &9164330 !ruby/object:Gem::Requirement
+  requirement: &8422930 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *9164330
+  version_requirements: *8422930
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &9145350 !ruby/object:Gem::Requirement
+  requirement: &8422420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *9145350
+  version_requirements: *8422420
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &9142060 !ruby/object:Gem::Requirement
+  requirement: &8421570 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *9142060
+  version_requirements: *8421570
 - !ruby/object:Gem::Dependency
   name: savon_spec
-  requirement: &9115390 !ruby/object:Gem::Requirement
+  requirement: &8420670 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -87,7 +87,7 @@ dependencies:
         version: 0.1.6
   type: :development
   prerelease: false
-  version_requirements: *9115390
+  version_requirements: *8420670
 description: A Ruby gem for interacting with the Salesforce Metadata API
 email:
 - eric@ejholmes.net
@@ -184,3 +184,4 @@ test_files:
 - spec/lib/dsl_spec.rb
 - spec/lib/manifest_spec.rb
 - spec/spec_helper.rb
+has_rdoc: