metaforce 0.5.3 → 1.0.0a

data/lib/metaforce/job/retrieve.rb

@@ -0,0 +1,92 @@
+module Metaforce
+  class Job::Retrieve < Job
+
+    # Public: Instantiate a new retrieve job.
+    #
+    # Examples
+    #
+    #   job = Metaforce::Job::Retrieve.new(client)
+    #   # => #<Metaforce::Job::Retrieve @id=nil>
+    #
+    # Returns self.
+    def initialize(client, options={})
+      super(client)
+      @options = options
+    end
+
+    # Public: Perform the job.
+    #
+    # Examples
+    #
+    #   job = Metaforce::Job::Retrieve.new(client)
+    #   job.perform
+    #   # => #<Metaforce::Job::Retrieve @id='1234'>
+    #
+    # Returns self.
+    def perform
+      @id = client._retrieve(@options).id
+      super
+    end
+
+    # Public: Get the detailed status of the retrieve.
+    #
+    # Examples
+    #
+    #   job.result
+    #   # => { :id => '1234', :zip_file => '<base64 encoded content>', ... }
+    #
+    # Returns the RetrieveResult (http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_retrieveresult.htm).
+    def result
+      client.status(id, :retrieve)
+    end
+
+    # Public: Decodes the content of the returned zip file.
+    #
+    # Examples
+    #
+    #   job.zip_file
+    #   # => '<binary content>'
+    #
+    # Returns the decoded content.
+    def zip_file
+      Base64.decode64(result.zip_file)
+    end
+
+    # Public: Unzips the returned zip file to the location.
+    #
+    # destination - Path to extract the contents to.
+    #
+    # Examples
+    #
+    #   job.extract_to('./path')
+    #   # => #<Metaforce::Job::Retrieve @id='1234'>
+    #
+    # Returns self.
+    def extract_to(destination)
+      return on_complete { |job| job.extract_to(destination) } unless @id
+      Zip::ZipFile.open(tmp_zip_file) do |zip|
+        zip.each do |f|
+          path = File.join(destination, f.name)
+          FileUtils.mkdir_p(File.dirname(path))
+          zip.extract(f, path) { true }
+        end
+      end
+      self
+    end
+
+  private
+
+    # Internal: Writes the zip file content to a temporary location so it can
+    # be extracted.
+    def tmp_zip_file
+      @tmp_zip_file ||= begin
+        file = Tempfile.new('retrieve')
+        file.write(zip_file)
+        path = file.path
+        file.close
+        path
+      end
+    end
+
+  end
+end

data/lib/metaforce/job.rb

@@ -0,0 +1,183 @@
+require 'zip/zip'
+require 'base64'
+
+module Metaforce
+  class Job
+    autoload :Deploy,   'metaforce/job/deploy'
+    autoload :Retrieve, 'metaforce/job/retrieve'
+    autoload :CRUD,     'metaforce/job/crud'
+
+    # Public: The id of the AsyncResult returned from Salesforce for
+    # this job.
+    attr_reader :id
+
+    # Public: Instantiate a new job. Doesn't actually do anything until
+    # .perform is called.
+    #
+    # Examples
+    #
+    #   job = Metaforce::Job.new(client)
+    #   # => #<Metaforce::Job @id=nil>
+    #
+    # Returns self.
+    def initialize(client)
+      @_callbacks = Hash.new { |h,k| h[k] = [] }
+      @client = client
+    end
+
+    # Public: Perform the job.
+    #
+    # Examples
+    #
+    #   job = Metaforce::Job.new
+    #   job.perform
+    #   # => #<Metaforce::Job @id=nil>
+    #
+    # Returns self.
+    def perform
+      start_heart_beat
+      self
+    end
+
+    # Public: Register a block to be called when the job has completed.
+    #
+    # Yields the job.
+    #
+    # &block - Proc or Lambda to be run when the job completes.
+    #
+    # Examples
+    #
+    #   job.on_complete do |job|
+    #     puts "Job ##{job.id} completed!"
+    #   end
+    #
+    # Returns self.
+    def on_complete(&block)
+      @_callbacks[:on_complete] << block
+      self
+    end
+
+    # Public: Register a block to be called when if the job fails.
+    #
+    # Yields the job.
+    #
+    # &block - Proc or Lambda to be run when the job fails.
+    #
+    # Examples
+    #
+    #   job.on_error do |job|
+    #     puts "Job ##{job.id} failed!"
+    #   end
+    #
+    # Returns self.
+    def on_error(&block)
+      @_callbacks[:on_error] << block
+      self
+    end
+
+    # Public: Queries the job status from the API.
+    #
+    # Examples
+    #
+    #   job.status
+    #   # => { :id => '1234', :done => false, ... }
+    #
+    # Returns the AsyncResult (http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_asyncresult.htm).
+    def status
+      client.status(id)
+    end
+
+    # Public: Returns true if the job has completed. 
+    #
+    # Examples
+    #
+    #   job.done
+    #   # => true
+    #
+    # Returns true if the job has completed, false otherwise.
+    def done?
+      status.done
+    end
+
+    # Public: Returns the state if the job has finished processing.
+    #
+    # Examples
+    #
+    #   job.state
+    #   # => 'Completed'
+    #
+    # Returns the state if the job is done, false otherwise.
+    def state
+      done? && status.state
+    end
+
+    # Public: Check if the job is in a given state.
+    #
+    # Examples
+    #
+    #   job.queued?
+    #   # => false
+    #
+    # Returns true or false.
+    #
+    # Signature
+    #
+    #   queued?
+    #   in_progress?
+    #   completed?
+    #   error?
+    %w[Queued InProgress Completed Error].each do |state|
+      define_method :"#{state.underscore}?" do; self.state == state end
+    end
+
+    def inspect
+      "#<#{self.class} @id=#{@id.inspect}>"
+    end
+
+    class << self
+
+      # Internal: Disable threading in tests.
+      def disable_threading!
+        self.class_eval do
+          def start_heart_beat
+            loop do
+              trigger_callbacks && break if completed? || error?
+            end
+          end
+        end
+      end
+
+    end
+
+  private
+    attr_reader :client
+
+    # Internal: Starts a heart beat in a thread, which polls the job status
+    # until it has completed or timed out.
+    def start_heart_beat
+      Thread.abort_on_exception = true
+      @heart_beat ||= Thread.new do
+        delay = 1
+        loop do
+          sleep (delay = delay * 2)
+          trigger_callbacks && Thread.stop if completed? || error?
+        end
+      end
+    end
+
+    def trigger_callbacks
+      @_callbacks[callback_type].each do |block|
+        block.call(self)
+      end
+    end
+
+    def callback_type
+      if completed?
+        :on_complete
+      elsif error?
+        :on_error
+      end
+    end
+
+  end
+end

data/lib/metaforce/login.rb

@@ -0,0 +1,39 @@
+module Metaforce
+  class Login
+    def initialize(username, password, security_token=nil)
+      @username, @password, @security_token = username, password, security_token
+    end
+
+    # Public: Perform the login request.
+    #
+    # Returns a hash with the session id and server urls.
+    def login
+      response = client.request(:login) do
+        soap.body = {
+          :username => username,
+          :password => password
+        }
+      end
+      response.body[:login_response][:result]
+    end
+
+  private
+
+    # Internal: Savon client.
+    def client
+      @client ||= Savon.client(Metaforce.configuration.partner_wsdl) do |wsdl|
+        wsdl.endpoint = Metaforce.configuration.endpoint
+      end.tap { |client| client.http.auth.ssl.verify_mode = :none }
+    end
+
+    # Internal: Usernamed passed in from options.
+    def username
+      @username
+    end
+
+    # Internal: Password + Security Token combined.
+    def password
+      [@password, @security_token].join('')
+    end
+  end
+end

data/lib/metaforce/manifest.rb

@@ -1,11 +1,11 @@
 require 'nokogiri'
-require 'metaforce/types'
+require 'active_support/core_ext'
 
 module Metaforce
-  class Manifest
+  class Manifest < Hash
 
-    # Initializes a new instance of a manifest (package.xml) file.
-    # 
+    # Public: Initializes a new instance of a manifest (package.xml) file.
+    #
     # It can either take a hash:
     #   {
     #     :apex_class => [
@@ -35,71 +35,17 @@ module Metaforce
     #    </types>
     #    <version>23.0</version>
     #  </Package>
-    # 
+    #
     def initialize(components={})
-      # Map component type => folder
+      self.replace Hash.new { |h,k| h[k] = [] }
       if components.is_a?(Hash)
-        @components = components
+        self.merge!(components)
       elsif components.is_a?(String)
-        @components = {}
         self.parse(components)
       end
     end
 
-    # Adds components to the package
-    #
-    #  manifest.add :apex_class, 'SomeClass'
-    def add(type, members=nil)
-      unless members.nil?
-        @components[type] = [] if @components[type].nil?
-        members = [members] if members.is_a?(String)
-        members.each do |member|
-          member = member.gsub(/.*\//, '').gsub(/\..*/, '');
-          @components[type].push(member)
-        end
-      end
-      self
-    end
-
-    # Removes components from the package
-    #
-    #  manifest.remove :apex_class, 'SomeClass'
-    def remove(type, members=nil)
-      unless members.nil?
-        members = [members] if members.is_a?(String)
-        members.each do |member|
-          member = member.gsub(/.*\//, '').gsub(/\..*/, '');
-          @components[type].delete(member)
-        end
-      end
-      if @components[type].empty?
-        @components.delete(type)
-      end
-      self
-    end
-
-    # Filters the components based on a list of files
-    #
-    #  manifest.only(['classes/SomeClass'])
-    def only(files)
-      components = @components
-      @components = {}
-      files.each do |file|
-        parts = file.split('/').last(2)
-        folder = parts[0]
-        file = parts[1].gsub(/.*\//, '').gsub(/\..*/, '')
-        components.each_key do |type|
-          if Metaforce::Metadata::Types.folder(type) =~ /#{folder}/i
-            unless components[type].index(file).nil?
-              self.add(type, file);
-            end
-          end
-        end
-      end
-      self
-    end
-
-    # Returns a string containing a package.xml file
+    # Public: Returns a string containing a package.xml file
     #
     #  <?xml version="1.0"?>
     #  <Package xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -120,13 +66,13 @@ module Metaforce
     #  </Package>
     def to_xml
       xml_builder = Nokogiri::XML::Builder.new do |xml|
-        xml.Package("xmlns" => "http://soap.sforce.com/2006/04/metadata") {
-          @components.each do |key, members|
+        xml.Package('xmlns' => 'http://soap.sforce.com/2006/04/metadata') {
+          self.each do |key, members|
             xml.types {
               members.each do |member|
                 xml.members member
               end
-              xml.name Metaforce::Metadata::Types.name(key)
+              xml.name key.to_s.camelize
             }
           end
           xml.version Metaforce.configuration.api_version
@@ -135,43 +81,22 @@ module Metaforce
       xml_builder.to_xml
     end
 
-    # Returns the underlying hash structure
-    #
-    #   {
-    #     :apex_class => [
-    #       "TestController",
-    #       "TestClass"
-    #     ],
-    #     :apex_component => [
-    #       "SiteLogin"
-    #     ]
-    #   }
-    def to_hash
-      @components
-    end
-
-    # Used internall my Metaforce::Metadata::Client
+    # Public: Converts the manifest into a format that can be used by the
+    # metadata api.
     def to_package
-      components = []
-      @components.each do |type, members|
-        name = Metaforce::Metadata::Types.name(type)
-        components.push :members => members, :name => name
+      self.map do |type, members|
+        { :members => members, :name => type.to_s.camelize }
       end
-      components
     end
 
-    # Parses a package.xml file
+    # Public: Parses a package.xml file
     def parse(file)
       document = Nokogiri::XML(file).remove_namespaces!
       document.xpath('//types').each do |type|
         name = type.xpath('name').first.content
-        key = Metaforce::Metadata::Types.key(name);
+        key = name.underscore.to_sym
         type.xpath('members').each do |member|
-          if @components[key].is_a?(Array)
-            @components[key].push(member.content)
-          else
-            @components[key] = [member.content]
-          end
+          self[key] << member.content
         end
       end
       self

data/lib/metaforce/metadata/client/crud.rb

@@ -0,0 +1,86 @@
+module Metaforce
+  module Metadata
+    class Client
+      module CRUD
+
+        # Public: Create metadata
+        #
+        # Examples
+        #
+        #   client._create(:apex_page, :full_name => 'TestPage', label: 'Test page', :content => '<apex:page>foobar</apex:page>')
+        def _create(type, metadata={})
+          type = type.to_s.camelize
+          request :create do |soap|
+            soap.body = {
+              :metadata => prepare(metadata)
+            }.merge(attributes!(type))
+          end
+        end
+
+        # Public: Delete metadata
+        #
+        # Examples
+        #
+        #   client._delete(:apex_component, 'Component')
+        def _delete(type, *args)
+          type = type.to_s.camelize
+          metadata = args.map { |full_name| {:full_name => full_name} }
+          request :delete do |soap|
+            soap.body = {
+              :metadata => metadata
+            }.merge(attributes!(type))
+          end
+        end
+
+        # Public: Update metadata
+        #
+        # Examples
+        #
+        #   client._update(:apex_page, 'OldPage', :full_name => 'NewPage')
+        def _update(type, current_name, metadata={})
+          type = type.to_s.camelize
+          request :update do |soap|
+            soap.body = {
+              :metadata => {
+                :current_name => current_name,
+                :metadata => prepare(metadata),
+                :attributes! => { :metadata => { 'xsi:type' => "ins0:#{type}" } }
+              }
+            }
+          end
+        end
+
+        def create(*args)
+          Job::CRUD.new(self, :_create, args)
+        end
+
+        def update(*args)
+          Job::CRUD.new(self, :_update, args)
+        end
+
+        def delete(*args)
+          Job::CRUD.new(self, :_delete, args)
+        end
+
+      private
+
+        def attributes!(type)
+          {:attributes! => { 'ins0:metadata' => { 'xsi:type' => "ins0:#{type}" } }}
+        end
+
+        # Internal: Prepare metadata by base64 encoding any content keys.
+        def prepare(metadata)
+          metadata = [metadata] unless metadata.is_a? Array
+          metadata.each { |m| encode_content(m) }
+          metadata
+        end
+
+        # Internal: Base64 encodes any :content keys.
+        def encode_content(metadata)
+          metadata[:content] = Base64.encode64(metadata[:content]) if metadata.has_key?(:content)
+        end
+        
+      end
+    end
+  end
+end

data/lib/metaforce/metadata/client/file.rb

@@ -0,0 +1,113 @@
+module Metaforce
+  module Metadata
+    class Client
+      module File
+
+        # Public: 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_metadata('ApexClass').collect { |t| t.full_name }
+        #   #=> ["al__SObjectPaginatorListenerForTesting", "al__IndexOutOfBoundsException", ... ]
+        #
+        #   # Get a list of apex components and apex classes
+        #   client.list_metadata('CustomObject', 'ApexComponent')
+        #   #=> ["ContractContactRole", "Solution", "Invoice_Statements__c", ... ]
+        def list_metadata(*args)
+          queries = args.map(&:to_s).map(&:camelize).map { |t| {:type => t} }
+          request :list_metadata do |soap|
+            soap.body = { :queries => queries }
+          end
+        end
+
+        # Public: Describe the organization's metadata.
+        #
+        # version - API version (default: latest).
+        #
+        # Examples
+        #
+        #   # List the names of all metadata types
+        #   client.describe.metadata_objects.collect { |t| t.xml_name }
+        #   #=> ["CustomLabels", "StaticResource", "Scontrol", "ApexComponent", ... ]
+        def describe(version=nil)
+          request :describe_metadata do |soap|
+            soap.body = { :api_version => version } unless version.nil?
+          end
+        end
+
+        # Public: Checks the status of an async result.
+        #
+        # ids  - A list of ids to check.
+        # type - either :deploy or :retrieve
+        #
+        # Examples
+        # 
+        #   client.status('04sU0000000Wx6KIAS')
+        #   #=> {:done=>true, :id=>"04sU0000000Wx6KIAS", :state=>"Completed", ...}
+        def status(ids, type=nil)
+          method = :check_status
+          method = :"check_#{type}_status" if type
+          ids = [ids] unless ids.respond_to?(:each)
+          request method do |soap|
+            soap.body = { :ids => ids }
+          end
+        end
+
+        # Public: Deploy code to Salesforce.
+        #
+        # zip_file - The base64 encoded contents of the zip file.
+        # options  - Hash of DeployOptions.
+        # 
+        # Returns the AsyncResult
+        def _deploy(zip_file, options={})
+          request :deploy do |soap|
+            soap.body = { :zip_file => zip_file, :deploy_options => options }
+          end
+        end
+
+        # Public: Retrieve code from Salesforce.
+        #
+        # Returns the AsyncResult
+        def _retrieve(options={})
+          request :retrieve do |soap|
+            soap.body = { :retrieve_request => options }
+          end
+        end
+
+        # Public: Deploy code to Salesforce.
+        #
+        # path    - A path to a zip file, or a directory to deploy.
+        # options - Deploy options.
+        #
+        # Examples
+        #
+        #   client.deploy(File.expand_path('./src'))
+        def deploy(path, options={})
+          Job::Deploy.new(self, path, options)
+        end
+
+        def retrieve(options={})
+          Job::Retrieve.new(self, options)
+        end
+
+        # Public: Retrieves files specified in the manifest file (A package.xml
+        # file).
+        def retrieve_unpackaged(manifest, options={})
+          package = if manifest.is_a?(Metaforce::Manifest)
+            manifest
+          elsif manifest.is_a?(String)
+            Metaforce::Manifest.new(File.open(manifest).read)
+          end
+          options = {
+            :api_version    => Metaforce.configuration.api_version,
+            :single_package => true,
+            :unpackaged     => { :types => package.to_package }
+          }.merge(options)
+          retrieve(options)
+        end
+
+      end
+    end
+  end
+end