moovatom 0.1.4 → 0.2.0

data/lib/moovatom.rb

@@ -1,149 +1,231 @@
 # :title: MoovAtom API Documentation
-# The MoovEngine API provides the RESTful interface for encoding, canceling and querying,
-# your videos on the MoovAtom servers. This library defines the methods and functionality
-# necessary for your app to communicate with that interface.
+# The MoovEngine API provides the RESTful interface for encoding, canceling
+# and querying, your videos on the MoovAtom servers. This library defines the
+# methods and functionality necessary for your app to communicate with that
+# interface.
 #
-# See README file for installation details and general usage information.
+# See README file for installation details and specific usage information.
 #
 # Author:: Dominic Giglio <mailto:humanshell@gmail.com>
-# Copyright:: Copyright (c) 2011 Dominic Giglio - All Rights Reserved
+# Copyright:: Copyright (c) 2012 Dominic Giglio - All Rights Reserved
 # License:: MIT
 
 #-- required gems/libraries
-%w[net/https rexml/document builder uri].each { |item| require item }
+%w[net/http uri rexml/document ostruct json].each { |lib| require lib }
 
 #-- wrap the whole library in a module to enforce namespace
 module MoovAtom
-  
-  #-- MoovAtom module constants
-  API_URL  = 'https://moovatom.com/api/api_request'
+  API_URL = 'https://www.moovatom.com/api/v2'
   
   class MoovEngine
+    attr_reader   :response, :action
+    attr_accessor :uuid, :username, :userkey, :content_type, :title, :blurb,
+                  :sourcefile, :callbackurl, :format, :player
     
-    #-- class setters and getters
-    attr_reader :xml_response
-    attr_accessor :guid, :username, :userkey, :content_type, :title, :blurb, :sourcefile, :callbackurl
-    
-    # The initializer creates a set of instance variables to hold all the specifics about
-    # the video you're accessing. You can define these variables when instantiating a new
-    # MoovEngine object or after a blank object has been created. All variables with the
-    # exception of @xml_response and @action are writable. @xml_response is only readable
-    # because it contains the respnse from MoovAtom's servers. @action gets set in each of
-    # the methods below to correctly correspond with the associated request.
+    ##
+    # The initializer populates the class' instance variables to hold all the
+    # specifics about the video you're accessing or starting to encode, as well
+    # as the player control attributes.
     #
-    # Usage:
-    # * moov_engine = MoovAtom::MoovEngine.new
-    # * moov_engine.username = 'YOUR_USERNAME'
-    # * moov_engine.userkey = 'YOUR_USERKEY'
-    # * etc...
+    # There are three ways to instantiate a new MoovEngine object:
     #
-    # Or:
-    # * args = { username: 'YOUR_USERNAME', userkey: 'YOUR_USERKEY', etc... }
-    # * moov_engine = MoovAtom::MoovEngine.new(args)
-    def initialize(args={})
-      @guid         = args[:guid]
-      @username     = args[:username]
-      @userkey      = args[:userkey]
-      @content_type = args[:content_type] || "video"
-      @title        = args[:title]
-      @blurb        = args[:blurb]
-      @sourcefile   = args[:sourcefile]
-      @callbackurl  = args[:callbackurl]
-    end #-- end initialize method
-    
-    # Use this method to get the details about a video that's finished encoding.
-    # This method requires @username, @userkey and @guid to be set.
+    # 1. Create a blank object and set each variable using 'dot' notation
+    # 2. Supply video and/or player attributes in hashes
+    # 3. Use a block to set attributes
     #
-    # If @guid has not yet been set then you can pass it in as a string argument.
+    # See the README for specific examples
     #
-    # Usage:
-    # * moov_engine.details
-    # * moov_engine.details 'GUID_OF_VIDEO'
-    def details(guid = "")
-      @guid = guid if @guid.nil?
-      @action = 'details'
-      @xml_response = send_xml_request(build_xml_request)
-    end #-- end details method
+    # @player is a struct (OpenStruct) that holds all the attributes for your
+    # video player. All variables with the exception of @response and @action
+    # are writable. @response is readable because it contains the response from
+    # MoovAtom's servers. @action gets set in each of the request methods below
+    # to correctly correspond with the actions you're asking MoovAtom to
+    # perform. @format allows you to get xml or json in your responses, it's set
+    # to json by default. @content_type will default to 'video'.
     
-    # Use this method to get the status of a video that is currently being encoded.
-    # This method requires @username, @userkey and @guid to be set.
+    def initialize(vattrs={}, pattrs={}, &block)
+      @player = OpenStruct.new pattrs
+      vattrs.each {|k,v| instance_variable_set "@#{k}", v}
+      yield self if block_given?
+      @content_type = 'video' if @content_type.nil?
+      @format = 'json' if @format.nil?
+    end #-- initialize method
+    
+    ##
+    # The get_details() method is responsible for communicating the details
+    # about a video that has completed encoding on Moovatom's servers. You can
+    # pass a hash of attributes and/or supply a block to update the internal
+    # state of the MoovEngine object prior to requesting the details of an
+    # existing video. This method sets the instance variable @action to 'detail'
+    # for you. It uses the send_request() method to assign the response from the
+    # Moovatom servers to the @response instance variable.
     #
-    # If @guid has not yet been set then you can pass it in as a string argument.
+    # See README for specific examples
+
+    def get_details(attrs={}, &block)
+      @action = 'detail'
+      attrs.each {|k,v| instance_variable_set "@#{k}", v}
+      yield self if block_given?
+      send_request
+    end #-- get_details method
+    
+    ##
+    # The get_status() method is almost identical to the get_details() method.
+    # It also accepts the same type/combination of arguments and sets the
+    # @action instance variable to 'status' for you. The main difference is
+    # that you will receive either a success or error status response from
+    # Moovatom's servers corresponding to the video of the uuid provided.
     #
-    # Usage:
-    # * moov_engine.status
-    # * moov_engine.status 'GUID_OF_VIDEO'
-    def status(guid = "")
-      @guid = guid if @guid.nil?
+    # See README for specific examples
+
+    def get_status(attrs={}, &block)
       @action = 'status'
-      @xml_response = send_xml_request(build_xml_request)
-    end #-- end status method
+      attrs.each {|k,v| instance_variable_set "@#{k}", v}
+      yield self if block_given?
+      send_request
+    end #-- end get_status method
     
-    # Use this method to start encoding a new video.
-    # This method requires the following variables be set:
-    # * @username
-    # * @userkey
-    # * @content_type
-    # * @title
-    # * @blurb
-    # * @sourcefile
-    # * @callbackurl
+    ##
+    # The encode() method allows you to start a new encoding on Moovatom's
+    # servers. It is almost identical to the get_details() and get_status()
+    # methods. You can pass the same type/combination of arguments and it also
+    # sets the @action instance variable to 'encode' for you. After a
+    # successful response this method will set the @uuid instance variable to
+    # the value returned from Moovatom.
     #
-    # Usage:
-    # * moov_engine.details
-    def encode
+    # See README for specific examples
+
+    def encode(attrs={}, &block)
       @action = 'encode'
-      @xml_response = send_xml_request(build_xml_request)
-      
-      if @xml_response.code == "200"
-        xml_doc = REXML::Document.new @xml_response.body
-        @guid = xml_doc.root.elements["uuid"].text
+      attrs.each {|k,v| instance_variable_set "@#{k}", v}
+      yield self if block_given?
+      send_request
+
+      case @response
+      when Hash
+        @uuid = @response["uuid"]
+      when REXML::Document
+        @uuid = @response.root.elements["uuid"].text
       end
-    end #-- end encode method
+    end #-- encode method
     
-    # Use this method to cancel the encoding of a video.
-    # This method requires @username, @userkey and @guid to be set.
+    ##
+    # The cancel() method allows you to cancel a video currently being encoded
+    # by the Moovatom servers. It is almost identical to the get_details() and
+    # get_status() methods. You can pass the same type/combination of arguments
+    # and it also sets the @action instance variable to 'cancel' for you.
     #
-    # If @guid has not yet been set then you can pass it in as a string argument.
-    #
-    # Usage:
-    # * moov_engine.cancel
-    # * moov_engine.cancel 'GUID_OF_VIDEO'
-    def cancel(guid = "")
-      @guid = guid if @guid.nil?
+    # See README for specific examples
+
+    def cancel(attrs={}, &block)
       @action = 'cancel'
-      @xml_response = send_xml_request(build_xml_request)
-    end #-- end cancel method
-    
-    #-- start of private methods
+      attrs.each {|k,v| instance_variable_set "@#{k}", v}
+      yield self if block_given?
+      send_request
+    end #-- cancel method
+
+    ##
+    # The edit_player() method allows you to change the player attributes for
+    # your videos on moovatom's servers. It accepts a hash of player attributes
+    # and/or a block to merge/update the @player instance variable created
+    # during initialization. It POSTs this (and all other instance variables) to
+    # moovatom through the send_request() method.
+    #
+    # See README for specific examples
+
+    def edit_player(attrs={}, &block)
+      @action = 'edit_player'
+      @player.instance_variable_get("@table").merge! attrs
+      yield self if block_given?
+      send_request
+    end #-- edit method
+
     private
-    
-    # Creates the XML object that is post'd to the MoovAtom servers
-    def build_xml_request
-      b = Builder::XmlMarkup.new
-      b.instruct!
-      xml = b.request do |r|
-        r.uuid(@guid)
-        r.username(@username)
-        r.userkey(@userkey)
-        r.action(@action)
-        r.content_type(@content_type)
-        r.title(@title)
-        r.blurb(@blurb)
-        r.sourcefile(@sourcefile)
-        r.callbackurl(@callbackurl)
-      end
-    end #-- end build_xml_request method
-    
-    # Sends the XML object to the MoovAtom servers
-    def send_xml_request(xml)
-      uri = URI.parse(MoovAtom::API_URL)
-      http = Net::HTTP.new(uri.host, uri.port)
+
+    ##
+    # The send_request() method is responsible for POSTing the values stored in
+    # your object's instance variables to Moovatom. The response from Moovatom
+    # is returned when the method finishes. If the response was a success it
+    # will be parsed according to the value of @format.
+
+    def send_request
+
+      # create the connection object
+      uri = URI.parse "#{MoovAtom::API_URL}/#{@action}.#{@format}"
+      http = Net::HTTP.new uri.host, uri.port
       http.use_ssl = true
       http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      response = http.post(uri.request_uri, "xml=#{URI.escape(xml)}")
-    end #-- end send_xml_request method
+
+      # open the connection and send request
+      http.start do |http|
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req.set_form_data(all_attributes, '&')
+        @response = http.request(req)
+      end
+
+      # parse the response if request was successful
+      if @response.code == "200"
+        case @format
+        when "json"
+          @response = JSON.parse @response.body
+        when "xml"
+          @response = REXML::Document.new @response.body
+        end
+      end
+
+    end #-- send_request method
+
+    ##
+    # This method assembles all video and player attributes so they can be
+    # easily added to the request that's POST'd to the Moovatom servers
+
+    def all_attributes
+
+      # get all the video instance variables
+      vattrs = Hash[
+        instance_variables.map do |iv|
+          [iv.to_s.gsub!(/@/, ""), instance_variable_get(iv)] unless iv == :@player
+        end
+      ]
+
+      # get all the player instance variables
+      pattrs = Hash[
+        @player.instance_variable_get("@table").keys.map do |iv|
+          [iv.to_s, @player.instance_variable_get("@table")[iv].to_s]
+        end
+      ]
+
+      # merge them and return as a single hash of attributes
+      vattrs.merge! pattrs
+
+    end
+
+    ##
+    # Custom to_s method for pretty printing in the console
+
+    def to_s
+      puts
+      35.times { print "*" }
+      puts
+      puts "Object ID:    #{self.object_id}"
+      puts "UUID:         #{@uuid}"
+      puts "Username:     #{@username}"
+      puts "Userkey:      #{@userkey}"
+      puts "Content Type: #{@content_type}"
+      puts "Title:        #{@title}"
+      puts "Blurb:        #{@blurb}"
+      puts "Source File:  #{@sourcefile}"
+      puts "Callback URL: #{@callbackurl}"
+      puts "Action:       #{@action}"
+      puts "Format:       #{@format}"
+      puts "Response:     #{@response.class}"
+      puts "Player:       #{@player.instance_variable_get("@table").length} attribute(s)"
+      35.times { print "*" }
+      puts
+      puts
+    end
     
-  end #-- end MoovEngine class
+  end #-- MoovEngine class
   
-end #-- end MoovAtom module
+end #-- MoovAtom module
+

data/moovatom.gemspec

@@ -19,9 +19,9 @@ Gem::Specification.new do |s|
   s.test_files        = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables       = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths     = ["lib"]
-  
+
   #-- release dependencies
-  s.add_dependency('builder')
+  s.add_dependency('json')
 
   #-- development dependencies
   s.add_development_dependency('minitest')

data/spec/cancel_spec.rb

@@ -0,0 +1,106 @@
+require "spec_helper"
+
+# this file contains all the tests associated with cancelling the encoding of
+# a video on Moovatom's servers.
+
+describe MoovAtom::MoovEngine, "Cancel Request Unit Tests" do
+
+  before do
+    @vars1 = {
+      uuid: '123',
+      username: 'jsmith',
+      userkey: '987654321',
+      title: 'My Greatest Movie',
+      blurb: 'The greatest movie ever made',
+      sourcefile: 'http://example.com/greatest.mp4',
+      callbackurl: 'http://example.com/callback'
+    }
+
+    @vars2 = {
+      uuid: '321',
+      username: 'asmith',
+      userkey: '123456789',
+      title: 'My Best Movie',
+      blurb: 'The bestest movie ever made',
+      sourcefile: 'http://example.com/best.mp4',
+      callbackurl: 'http://example.com/callback_url'
+    }
+
+    # mock up the connection to moovatom.com
+    @me = MoovAtom::MoovEngine.new @vars1
+    @url = "#{MoovAtom::API_URL}/cancel"
+    json = File.join(File.dirname(__FILE__), 'fixtures', 'cancel.json')
+    FakeWeb.register_uri(:post, "#{@url}.json", :body => json)
+    xml = File.join(File.dirname(__FILE__), 'fixtures', 'cancel.xml')
+    FakeWeb.register_uri(:post, "#{@url}.xml", :body => xml)
+  end
+
+  after do
+    # clean up the registry after each test
+    FakeWeb.clean_registry
+
+    # enable all real requests after testing
+    FakeWeb.allow_net_connect = true
+  end
+
+  it "accepts a hash to update attributes" do
+
+    # create a MoovEngine object using the values from the @vars1 hash
+    me = MoovAtom::MoovEngine.new @vars1
+
+    # call cancel() passing the hash of values from @vars2
+    me.cancel @vars2
+
+    # the instance 'me' should now contain the values from the @vars2 hash
+    @vars2.each {|k,v| me.instance_variable_get("@#{k}").must_equal v}
+
+  end
+
+  it "accepts a block to update attributes" do
+
+    # create a new MoovEngine object with a block using the values from @vars1
+    me = MoovAtom::MoovEngine.new do |me|
+      @vars1.each {|k,v| me.instance_variable_set "@#{k}", v}
+    end
+
+    # call cancel() passing a block that sets instance variables to the
+    # values in the @vars2 hash
+    me.cancel do |me|
+      @vars2.each {|k,v| me.instance_variable_set "@#{k}", v}
+    end
+
+    # the instance 'me' should now contain the values from the @vars2 hash
+    @vars2.each {|k,v| me.instance_variable_get("@#{k}").must_equal v}
+
+  end
+
+  it "sets the action attribute to cancel" do
+
+    # create a new MoovEngine object
+    me = MoovAtom::MoovEngine.new @vars1
+
+    # call the cancel() method
+    me.cancel
+
+    # after calling cancel() @action should be 'cancel'
+    me.action.must_equal 'cancel'
+
+  end
+
+  # tests for the api call to get details about an existing video
+  describe "API Requests" do
+
+    it "cancels encoding of a video using json" do
+      @me.cancel
+      @me.response["uuid"].must_equal @vars1[:uuid]
+    end
+
+    it "cancels encoding of a video using xml" do
+      @me.format = 'xml'
+      @me.cancel
+      @me.response.root.elements["uuid"].text.must_equal @vars1[:uuid]
+    end
+
+  end
+
+end

data/spec/details_spec.rb

@@ -0,0 +1,103 @@
+require "spec_helper"
+
+# this file contains all the tests associated with requesting the details of a
+# video on Moovatom's servers.
+
+describe MoovAtom::MoovEngine, "Details Request Unit Tests" do
+
+  before do
+    @vars1 = {
+      uuid: '123',
+      username: 'jsmith',
+      userkey: '987654321',
+      title: 'My Greatest Movie',
+      blurb: 'The greatest movie ever made',
+      sourcefile: 'http://example.com/greatest.mp4',
+      callbackurl: 'http://example.com/callback'
+    }
+
+    @vars2 = {
+      uuid: '321',
+      username: 'asmith',
+      userkey: '123456789',
+      title: 'My Best Movie',
+      blurb: 'The bestest movie ever made',
+      sourcefile: 'http://example.com/best.mp4',
+      callbackurl: 'http://example.com/callback_url'
+    }
+
+    # mock up the connection to moovatom.com
+    @me = MoovAtom::MoovEngine.new @vars1
+    @url = "#{MoovAtom::API_URL}/detail"
+    json = File.join(File.dirname(__FILE__), 'fixtures', 'detail.json')
+    FakeWeb.register_uri(:post, "#{@url}.json", :body => json)
+    xml = File.join(File.dirname(__FILE__), 'fixtures', 'detail.xml')
+    FakeWeb.register_uri(:post, "#{@url}.xml", :body => xml)
+  end
+
+  after do
+    # clean up the registry after each test
+    FakeWeb.clean_registry
+
+    # enable all real requests after testing
+    FakeWeb.allow_net_connect = true
+  end
+
+  it "accepts a hash to update attributes" do
+
+    # create a MoovEngine object using the values from the @vars1 hash
+    me = MoovAtom::MoovEngine.new @vars1
+
+    # call get_details() passing the hash of values from @vars2
+    me.get_details @vars2
+
+    # the instance 'me' should now contain the values from the @vars2 hash
+    @vars2.each {|k,v| me.instance_variable_get("@#{k}").must_equal v}
+  end
+
+  it "accepts a block to update attributes" do
+
+    # create a new MoovEngine object with a block using the values from @vars1
+    me = MoovAtom::MoovEngine.new do |me|
+      @vars1.each {|k,v| me.instance_variable_set "@#{k}", v}
+    end
+
+    # call get_details() passing a block that sets instance variables to the
+    # values in the @vars2 hash
+    me.get_details do |me|
+      @vars2.each {|k,v| me.instance_variable_set "@#{k}", v}
+    end
+
+    # the instance 'me' should now contain the values from the @vars2 hash
+    @vars2.each {|k,v| me.instance_variable_get("@#{k}").must_equal v}
+  end
+
+  it "sets the action attribute to detail" do
+
+    # create a new MoovEngine object
+    me = MoovAtom::MoovEngine.new @vars1
+
+    # call the get_details() method
+    me.get_details
+
+    # after calling get_details() @action should be 'detail'
+    me.action.must_equal 'detail'
+  end
+
+  # tests for the api call to get details about an existing video
+  describe "API Requests" do
+
+    it "gets details of a video using json" do
+      @me.get_details
+      @me.response["uuid"].must_equal @vars1[:uuid]
+    end
+
+    it "gets details of a video using xml" do
+      @me.format = 'xml'
+      @me.get_details
+      @me.response.root.elements["uuid"].text.must_equal @vars1[:uuid]
+    end
+
+  end
+
+end

data/spec/encode_spec.rb

@@ -0,0 +1,103 @@
+require "spec_helper"
+
+# this file contains all the tests associated with requesting a new encoding on
+# Moovatom's servers.
+
+describe MoovAtom::MoovEngine, "Encode Request Unit Tests" do
+
+  before do
+    @vars1 = {
+      uuid: '123',
+      username: 'jsmith',
+      userkey: '987654321',
+      title: 'My Greatest Movie',
+      blurb: 'The greatest movie ever made',
+      sourcefile: 'http://example.com/greatest.mp4',
+      callbackurl: 'http://example.com/callback'
+    }
+
+    @vars2 = {
+      uuid: '321',
+      username: 'asmith',
+      userkey: '123456789',
+      title: 'My Best Movie',
+      blurb: 'The bestest movie ever made',
+      sourcefile: 'http://example.com/best.mp4',
+      callbackurl: 'http://example.com/callback_url'
+    }
+
+    # mock up the connection to moovatom.com
+    @me = MoovAtom::MoovEngine.new @vars1
+    @url = "#{MoovAtom::API_URL}/encode"
+    json = File.join(File.dirname(__FILE__), 'fixtures', 'encode.json')
+    FakeWeb.register_uri(:post, "#{@url}.json", :body => json)
+    xml = File.join(File.dirname(__FILE__), 'fixtures', 'encode.xml')
+    FakeWeb.register_uri(:post, "#{@url}.xml", :body => xml)
+  end
+
+  after do
+    # clean up the registry after each test
+    FakeWeb.clean_registry
+
+    # enable all real requests after testing
+    FakeWeb.allow_net_connect = true
+  end
+
+  it "accepts a hash to update attributes" do
+
+    # create a MoovEngine object using the values from the @vars1 hash
+    me = MoovAtom::MoovEngine.new @vars1
+
+    # call encode() passing the hash of values from @vars2
+    me.encode @vars2
+
+    # the instance 'me' should now contain the values from the @vars2 hash
+    @vars2.each {|k,v| me.instance_variable_get("@#{k}").must_equal v}
+  end
+
+  it "accepts a block to update attributes" do
+
+    # create a new MoovEngine object with a block using the values from @vars1
+    me = MoovAtom::MoovEngine.new do |me|
+      @vars1.each {|k,v| me.instance_variable_set "@#{k}", v}
+    end
+
+    # call encode() passing a block that sets instance variables to the
+    # values in the @vars2 hash
+    me.encode do |me|
+      @vars2.each {|k,v| me.instance_variable_set "@#{k}", v}
+    end
+
+    # the instance 'me' should now contain the values from the @vars2 hash
+    @vars2.each {|k,v| me.instance_variable_get("@#{k}").must_equal v}
+  end
+
+  it "sets the action attribute to encode" do
+
+    # create a new MoovEngine object
+    me = MoovAtom::MoovEngine.new @vars1
+
+    # call the encode() method
+    me.encode
+
+    # after calling encode() @action should be 'encode'
+    me.action.must_equal 'encode'
+  end
+
+  # tests for the api call to get details about an existing video
+  describe "API Requests" do
+
+    it "starts a new encoding using json" do
+      @me.encode
+      @me.response["uuid"].must_equal "321"
+    end
+
+    it "starts a new encoding using xml" do
+      @me.format = 'xml'
+      @me.encode
+      @me.response.root.elements["uuid"].text.must_equal "321"
+    end
+
+  end
+
+end

data/spec/fixtures/cancel.json

@@ -0,0 +1,4 @@
+{
+    "uuid": "123",
+    "message": "This job was successfully cancelled."
+}