bigbluebutton-api-ruby 0.0.10 → 0.0.11

data/.gitignore

@@ -1,5 +1,5 @@
 *.gem
 pkg
-*.*~
+*~
 test/config.yml
 doc/

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rvmrc

@@ -0,0 +1,6 @@
+#!/bin/bash
+if [ -e '.rvmrc_custom' ]; then
+  source .rvmrc_custom;
+else
+  rvm --create use 1.9.2@bigbluebutton-api-ruby;
+fi

data/CHANGELOG.rdoc

@@ -1,3 +1,11 @@
+== 0.0.11
+
+* The file "bigbluebutton-api" was renamed to "bigbluebutton_api". All "require" calls must be updated.
+* Splitted the library in more files (more modular) and created rspec tests for it.
+* Added a BigBlueButtonApi.timeout attribute to timeout get requests and avoid blocks when the server is down. Defaults to 2 secs.
+* New method last_http_response to access the last HTTP response object.
+* Automatically detects the BBB server version if not informed by the user.
+
 == 0.0.10
 
 * Returning hash now will *always* have these 3 values: :returncode (boolean), :messageKey (string) and :message (string).

data/Gemfile

@@ -0,0 +1,7 @@
+source 'http://rubygems.org'
+
+gem 'nokogiri', '1.4.1'
+
+group :developement do
+  gem 'rspec', '~> 2.6'
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    nokogiri (1.4.1)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  nokogiri (= 1.4.1)
+  rspec (~> 2.6)

data/bigbluebutton-api-ruby.gemspec

@@ -2,7 +2,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name = 'bigbluebutton-api-ruby'
-  s.version = '0.0.10'
+  s.version = '0.0.11'
   s.extra_rdoc_files = ['README.rdoc', 'LICENSE', 'CHANGELOG.rdoc']
   s.summary = 'Provides an interface to the BigBlueButton web meeting API (https://github.com/mconf/bigbluebutton-api-ruby)'
   s.description = s.summary

data/lib/{bigbluebutton-api.rb → bigbluebutton_api.rb}

@@ -5,26 +5,15 @@ require 'digest/sha1'
 require 'rubygems'
 require 'nokogiri'
 require 'hash_to_xml'
+require 'bigbluebutton_exception'
+require 'bigbluebutton_formatter'
 
 module BigBlueButton
 
-  class BigBlueButtonException < Exception
-    attr_accessor :key
-
-    def to_s
-      unless key.blank?
-        super.to_s + ", messageKey: #{key}"
-      else
-        super
-      end
-    end
-
-  end
-
   # This class provides access to the BigBlueButton API. BigBlueButton
   # is an open source project that provides web conferencing for distance
   # education (http://code.google.com/p/bigbluebutton/wiki/API). This API
-  # was developed to support the following version of BBB: 0.64, 0.7
+  # was developed to support the following version of BBB: 0.7, 0.8 (soon)
   #
   # Sample usage of the API is as follows:
   # 1) Create a meeting with the create_meeting call
@@ -42,8 +31,6 @@ module BigBlueButton
   # Copyright:: Copyright (c) 2010 Joe Kinsella
   # License::   Distributes under same terms as Ruby
   #
-  # TODO: Automatically detect API version using request to index - added in 0.7
-  #
   # Considerations about the returning hash:
   # * The XML returned by BBB is converted to a Hash. See the desired method's documentation for examples.
   # * Three values will *always* exist in the hash: :returncode (boolean), :messageKey (string) and :message (string)
@@ -58,54 +45,38 @@ module BigBlueButton
   #
   class BigBlueButtonApi
 
-    attr_accessor :url, :supported_versions, :salt, :version, :debug
+    attr_accessor :url, :supported_versions, :salt, :version, :debug, :timeout
 
     # Initializes an instance
     # url::       URL to a BigBlueButton server (e.g. http://demo.bigbluebutton.org/bigbluebutton/api)
     # salt::      Secret salt for this server
-    # version::   API version: 0.64 or 0.7
+    # version::   API version: 0.7 (valid for 0.7, 0.71 and 0.71a)
     def initialize(url, salt, version='0.7', debug=false)
-      @supported_versions = ['0.7', '0.64']
-      unless @supported_versions.include?(version)
-        raise BigBlueButtonException.new("BigBlueButton error: Invalid API version #{version}. Supported versions: #{@supported_versions.join(', ')}")
-      end
+      @supported_versions = ['0.7']
       @url = url
       @salt = salt
       @debug = debug
-      @version = version
-      puts "BigBlueButtonAPI: Using version #{@version}" if @debug
-    end
+      @timeout = 2 # 2 seconds timeout for get requests
 
-    # DEPRECATED
-    # Use join_meeting_url
-    def moderator_url(meeting_id, user_name, password,
-                      user_id = nil, web_voice_conf = nil)
-      warn "#{caller[0]}: moderator_url is deprecated and will soon be removed, please use join_meeting_url instead."
-      join_meeting_url(meeting_id, user_name, password, user_id, web_voice_conf)
-    end
+      @version = version || get_api_version
+      unless @supported_versions.include?(@version)
+        raise BigBlueButtonException.new("BigBlueButton error: Invalid API version #{version}. Supported versions: #{@supported_versions.join(', ')}")
+      end
 
-    # DEPRECATED
-    # Use join_meeting_url
-    def attendee_url(meeting_id, user_name, password,
-                     user_id = nil, web_voice_conf = nil)
-      warn "#{caller[0]}: attendee_url is deprecated and will soon be removed, please use join_meeting_url instead."
-      join_meeting_url(meeting_id, user_name, password, user_id, web_voice_conf)
+      puts "BigBlueButtonAPI: Using version #{@version}" if @debug
     end
 
     # Returns the url used to join the meeting
     # meeting_id::        Unique identifier for the meeting
     # user_name::         Name of the user
     # password::          Password for this meeting - used to set the user as moderator or attendee
-    # user_id::           Unique identifier for this user (>= 0.7)
-    # web_voice_conf::    Custom voice-extension for users using VoIP (>= 0.7)
+    # user_id::           Unique identifier for this user
+    # web_voice_conf::    Custom voice-extension for users using VoIP
     def join_meeting_url(meeting_id, user_name, password,
                          user_id = nil, web_voice_conf = nil)
 
-      params = { :meetingID => meeting_id, :password => password, :fullName => user_name }
-      if @version == '0.7'
-        params[:userID] = user_id
-        params[:webVoiceConf] = web_voice_conf
-      end
+      params = { :meetingID => meeting_id, :password => password, :fullName => user_name,
+                 :userID => user_id, :webVoiceConf => web_voice_conf }
       get_url(:join, params)
     end
 
@@ -118,7 +89,7 @@ module BigBlueButton
     # welcome_message::     Welcome message to display in chat window
     # dialin_number::       Dial in number for conference using a regular phone
     # logout_url::          URL to return user to after exiting meeting
-    # voice_bridge::        Voice conference number (>= 0.7)
+    # voice_bridge::        Voice conference number
     #
     # === Return examples (for 0.7)
     #
@@ -139,7 +110,6 @@ module BigBlueButton
     #    :message=>"This conference was already in existence and may currently be in progress."
     #   }
     #
-    # TODO check if voice_bridge exists in 0.64
     def create_meeting(meeting_name, meeting_id, moderator_password = nil, attendee_password = nil,
                        welcome_message = nil, dial_number = nil, logout_url = nil,
                        max_participants = nil, voice_bridge = nil)
@@ -147,15 +117,16 @@ module BigBlueButton
       params = { :name => meeting_name, :meetingID => meeting_id,
                  :moderatorPW => moderator_password, :attendeePW => attendee_password,
                  :welcome => welcome_message, :dialNumber => dial_number,
-                 :logoutURL => logout_url, :maxParticpants => max_participants }
-      params[:voiceBridge] = voice_bridge if @version == '0.7'
+                 :logoutURL => logout_url, :maxParticpants => max_participants,
+                 :voiceBridge => voice_bridge }
 
       response = send_api_request(:create, params)
 
-      response[:meetingID] = response[:meetingID].to_s
-      response[:moderatorPW] = response[:moderatorPW].to_s
-      response[:attendeePW] = response[:attendeePW].to_s
-      response[:hasBeenForciblyEnded] = response[:hasBeenForciblyEnded].downcase == "true"
+      formatter = BigBlueButtonFormatter.new(response)
+      formatter.to_string(:meetingID)
+      formatter.to_string(:moderatorPW)
+      formatter.to_string(:attendeePW)
+      formatter.to_boolean(:hasBeenForciblyEnded)
 
       response
     end
@@ -183,7 +154,7 @@ module BigBlueButton
     # meeting_id::          Unique identifier for the meeting
     def is_meeting_running?(meeting_id)
       hash = send_api_request(:isMeetingRunning, { :meetingID => meeting_id } )
-      hash[:running].downcase == "true"
+      BigBlueButtonFormatter.new(hash).to_boolean(:running)
     end
 
     # Warning: As of this version of the gem, this call does not work
@@ -196,16 +167,11 @@ module BigBlueButton
     # meeting_id::        Unique identifier for the meeting
     # user_name::         Name of the user
     # password::          Moderator or attendee password for this meeting
-    # user_id::           Unique identifier for this user (>=0.7)
-    # web_voice_conf::    Custom voice-extension for users using VoIP (>=0.7)
+    # user_id::           Unique identifier for this user
+    # web_voice_conf::    Custom voice-extension for users using VoIP
     def join_meeting(meeting_id, user_name, password, user_id = nil, web_voice_conf = nil)
-      params = { :meetingID => meeting_id, :password => password, :fullName => user_name }
-      if @version == '0.64'
-        params[:redirectImmediately] = 0
-      elsif @version == '0.7'
-        params[:userID] = user_id
-        params[:webVoiceConf] = web_voice_conf
-      end
+      params = { :meetingID => meeting_id, :password => password, :fullName => user_name,
+                 :userID => user_id, :webVoiceConf => web_voice_conf }
       send_api_request(:join, params)
     end
 
@@ -242,30 +208,17 @@ module BigBlueButton
     def get_meeting_info(meeting_id, password)
       response = send_api_request(:getMeetingInfo, { :meetingID => meeting_id, :password => password } )
 
-      # simplify the hash making a node :attendees with an array with all attendees
-      if response[:attendees].empty?
-        attendees = []
-      else
-        node = response[:attendees][:attendee]
-        if node.kind_of?(Array)
-          attendees = node
-        else
-          attendees = []
-          attendees << node
-        end
-      end
-      response[:attendees] = attendees
-      response[:attendees].each { |att| att[:role] = att[:role].downcase.to_sym }
-
-      response[:meetingID] = response[:meetingID].to_s
-      response[:moderatorPW] = response[:moderatorPW].to_s
-      response[:attendeePW] = response[:attendeePW].to_s
-      response[:hasBeenForciblyEnded] = response[:hasBeenForciblyEnded].downcase == "true"
-      response[:running] = response[:running].downcase == "true"
-      response[:startTime] = response[:startTime].downcase == "null" ?
-                             nil : DateTime.parse(response[:startTime])
-      response[:endTime] = response[:endTime].downcase == "null" ?
-                           nil : DateTime.parse(response[:endTime])
+      formatter = BigBlueButtonFormatter.new(response)
+      formatter.flatten_objects(:attendees, :attendee)
+      response[:attendees].each { |a| formatter.format_attendee(a) }
+
+      formatter.to_string(:meetingID)
+      formatter.to_string(:moderatorPW)
+      formatter.to_string(:attendeePW)
+      formatter.to_boolean(:hasBeenForciblyEnded)
+      formatter.to_boolean(:running)
+      formatter.to_datetime(:startTime)
+      formatter.to_datetime(:endTime)
 
       response
     end
@@ -292,52 +245,23 @@ module BigBlueButton
     def get_meetings
       response = send_api_request(:getMeetings, { :random => rand(9999999999) } )
 
-      # simplify the hash making a node :meetings with an array with all meetings
-      if response[:meetings].empty?
-        meetings = []
-      else
-        node = response[:meetings][:meeting]
-        if node.kind_of?(Array)
-          meetings = node
-        else
-          meetings = []
-          meetings << node
-        end
-      end
-      response[:meetings] = meetings
-
-      response[:meetings].each do |meeting|
-        meeting[:meetingID] = meeting[:meetingID].to_s
-        meeting[:moderatorPW] = meeting[:moderatorPW].to_s
-        meeting[:attendeePW] = meeting[:attendeePW].to_s
-        meeting[:hasBeenForciblyEnded] = meeting[:hasBeenForciblyEnded].downcase == "true"
-        meeting[:running] = meeting[:running].downcase == "true"
-      end
-
+      formatter = BigBlueButtonFormatter.new(response)
+      formatter.flatten_objects(:meetings, :meeting)
+      response[:meetings].each { |m| formatter.format_meeting(m) }
       response
     end
 
     # Returns the API version (as string) of the associated server. This actually returns
-    # the version requested to the BBB server, and not the version set by the user in
-    # the initialization.
-    #
-    # Works for BBB >= 0.7 only. For earlier versions, returns an empty string.
+    # the version returned by the BBB server, and not the version set by the user in
+    # the initialization of this object.
     def get_api_version
       response = send_api_request(:index)
-      if response[:returncode]
-        response[:version].to_s
-      else
-        ""
-      end
+      response[:returncode] ? response[:version].to_s : ""
     end
 
     # Make a simple request to the server to test the connection
     def test_connection
-      if @version == '0.7'
-        response = send_api_request(:index)
-      else
-        response = get_meetings
-      end
+      response = send_api_request(:index)
       response[:returncode]
     end
 
@@ -350,56 +274,50 @@ module BigBlueButton
       r
     end
 
-    protected
+    def last_http_response
+      @http_response
+    end
 
-    def get_url(method, data)
+    def get_url(method, data={})
       if method == :index
         return @url
       end
 
       url = "#{@url}/#{method}?"
 
+      # stringify and escape all params
       data.delete_if { |k, v| v.nil? } unless data.nil?
       params = ""
       params = data.map{ |k,v| "#{k}=" + CGI::escape(v.to_s) unless k.nil? || v.nil? }.join("&")
 
+      # checksum calc
       checksum_param = params + @salt
-      checksum_param = method.to_s + checksum_param if @version == '0.7'
+      checksum_param = method.to_s + checksum_param
       checksum = Digest::SHA1.hexdigest(checksum_param)
 
-      "#{url}#{params}&checksum=#{checksum}"
+      # final url
+      url += "#{params}&" unless params.empty?
+      url += "checksum=#{checksum}"
     end
 
     def send_api_request(method, data = {})
       url = get_url(method, data)
-      begin
-        res = Net::HTTP.get_response(URI.parse(url))
-        puts "BigBlueButtonAPI: URL request = #{url}" if @debug
-        puts "BigBlueButtonAPI: URL response = #{res.body}" if @debug
-      rescue Exception => socketerror
-        raise BigBlueButtonException.new("Connection error. Your URL is probably incorrect: \"#{@url}\"")
-      end
 
-      if res.body.empty?
-        raise BigBlueButtonException.new("No response body")
-      end
+      @http_response = send_request(url)
+      return { } if @http_response.body.empty?
 
       # 'Hashify' the XML
-      hash = Hash.from_xml res.body
+      hash = Hash.from_xml(@http_response.body)
 
       # simple validation of the xml body
       unless hash.has_key?(:response) and hash[:response].has_key?(:returncode)
         raise BigBlueButtonException.new("Invalid response body. Is the API URL correct? \"#{@url}\", version #{@version}")
       end
 
-      # and remove the "response" node
-      hash = Hash[hash[:response]].inject({}){|h,(k,v)| h[k] = v; h}
-
-      # Adjust some values. There will always be a returncode, message and messageKey in the hash.
-      hash[:returncode] = hash[:returncode].downcase == "success"                                  # true instead of "SUCCESS"
-      hash[:messageKey] = "" if !hash.has_key?(:messageKey) or hash[:messageKey].empty?            # "" instead of {}
-      hash[:message] = "" if !hash.has_key?(:message) or hash[:message].empty?                     # "" instead of {}
+      # default cleanup in the response
+      hash = BigBlueButtonFormatter.new(hash).default_formatting
 
+      # all responses should have a returncode
       unless hash[:returncode]
         exception = BigBlueButtonException.new(hash[:message])
         exception.key = hash.has_key?(:messageKey) ? hash[:messageKey] : ""
@@ -409,6 +327,25 @@ module BigBlueButton
       hash
     end
 
+    protected
+
+    def send_request(url)
+      begin
+        puts "BigBlueButtonAPI: URL request = #{url}" if @debug
+        url_parsed = URI.parse(url)
+        http = Net::HTTP.new(url_parsed.host, url_parsed.port)
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        response = http.get(url_parsed.request_uri)
+        puts "BigBlueButtonAPI: URL response = #{response.body}" if @debug
+      rescue TimeoutError => error
+        raise BigBlueButtonException.new("Timeout error. Your server is probably down: \"#{@url}\"")
+      rescue Exception => error
+        raise BigBlueButtonException.new("Connection error. Your URL is probably incorrect: \"#{@url}\"")
+      end
+      response
+    end
+
   end
 end
 

data/lib/bigbluebutton_exception.rb

@@ -0,0 +1,13 @@
+module BigBlueButton
+
+  class BigBlueButtonException < Exception
+    attr_accessor :key
+
+    def to_s
+      s = super.to_s
+      s += ", messageKey: #{key.to_s}" unless key.nil? or key.to_s.empty?
+      s
+    end
+  end
+
+end

data/lib/bigbluebutton_formatter.rb

@@ -0,0 +1,76 @@
+module BigBlueButton
+
+  # Helper class to format the response hash received when the BigBlueButtonApi makes API calls
+  class BigBlueButtonFormatter
+    attr_accessor :hash
+
+    def initialize(hash)
+      @hash = hash
+    end
+
+    # converts a value in the @hash to boolean
+    def to_boolean(key)
+      @hash[key] = @hash[key].downcase == "true"
+    end
+
+    # converts a value in the @hash to string
+    def to_string(key)
+      @hash[key] = @hash[key].to_s
+    end
+
+    # converts a value in the @hash to DateTime
+    def to_datetime(key)
+      @hash[key] = @hash[key].downcase == "null" ? nil : DateTime.parse(@hash[key])
+    end
+
+    # Default formatting for all responses given by a BBB server
+    def default_formatting
+
+      # remove the "response" node
+      response = Hash[@hash[:response]].inject({}){|h,(k,v)| h[k] = v; h}
+
+      # Adjust some values. There will always be a returncode, a message and a messageKey in the hash.
+      response[:returncode] = response[:returncode].downcase == "success"                              # true instead of "SUCCESS"
+      response[:messageKey] = "" if !response.has_key?(:messageKey) or response[:messageKey].empty?    # "" instead of {}
+      response[:message] = "" if !response.has_key?(:message) or response[:message].empty?             # "" instead of {}
+
+      @hash = response
+    end
+
+    # default formatting for a meeting hash
+    def format_meeting(meeting)
+      meeting[:meetingID] = meeting[:meetingID].to_s
+      meeting[:moderatorPW] = meeting[:moderatorPW].to_s
+      meeting[:attendeePW] = meeting[:attendeePW].to_s
+      meeting[:hasBeenForciblyEnded] = meeting[:hasBeenForciblyEnded].downcase == "true"
+      meeting[:running] = meeting[:running].downcase == "true"
+      meeting
+    end
+
+    # default formatting for an attendee hash
+    def format_attendee(attendee)
+      attendee[:userID] = attendee[:userID].to_s
+      attendee[:role] = attendee[:role].downcase.to_sym
+      attendee
+    end
+
+    # simplifies the hash making a node e.g. :attendee with an array with all attendees
+    # TODO: comments with the expected @hash at this point
+    def flatten_objects(first, second)
+      if @hash[first].empty?
+        collection = []
+      else
+        node = @hash[first][second]
+        if node.kind_of?(Array)
+          collection = node
+        else
+          collection = []
+          collection << node
+        end
+      end
+      @hash[first] = collection
+      @hash
+    end
+
+  end
+end

data/spec/bigbluebutton_api_spec.rb

@@ -0,0 +1,386 @@
+require 'spec_helper'
+
+describe BigBlueButton::BigBlueButtonApi do
+
+  # default variables and API object for all tests
+  let(:url) { "http://server.com" }
+  let(:salt) { "1234567890abcdefghijkl" }
+  let(:version) { "0.7" }
+  let(:debug) { false }
+  let(:api) { BigBlueButton::BigBlueButtonApi.new(url, salt, version, debug) }
+
+  describe "#initialize" do
+    context "standard initialization" do
+      subject { BigBlueButton::BigBlueButtonApi.new(url, salt, version, debug) }
+      it { subject.url.should be(url) }
+      it { subject.salt.should be(salt) }
+      it { subject.version.should be(version) }
+      it { subject.debug.should be(debug) }
+      it { subject.timeout.should be(2) }
+      it { subject.supported_versions.should include("0.7") }
+    end
+
+    context "when the version is not informed, get it from the BBB server" do
+      before { BigBlueButton::BigBlueButtonApi.any_instance.should_receive(:get_api_version).and_return("0.7") }
+      subject { BigBlueButton::BigBlueButtonApi.new(url, salt, nil) }
+      it { subject.version.should == "0.7" }
+    end
+
+    it "when the version is not supported raise an error" do
+      expect {
+        BigBlueButton::BigBlueButtonApi.new(url, salt, "0.not-supported", nil)
+      }.to raise_error(BigBlueButton::BigBlueButtonException)
+    end
+
+    context "current supported versions" do
+      subject { BigBlueButton::BigBlueButtonApi.new(url, salt) }
+      it { subject.supported_versions.should == ["0.7"] }
+    end
+  end
+
+  describe "#join_meeting_url" do
+    let(:meeting_id) { "meeting-id" }
+    let(:password) { "password" }
+    let(:user_name) { "user-name" }
+    let(:user_id) { "user-id" }
+    let(:web_voice_conf) { "web-voice-conf" }
+    let(:params) {
+      { :meetingID => meeting_id, :password => password, :fullName => user_name,
+        :userID => user_id, :webVoiceConf => web_voice_conf }
+    }
+
+    before { api.should_receive(:get_url).with(:join, params).and_return("test-url") }
+    it { api.join_meeting_url(meeting_id, user_name, password, user_id, web_voice_conf).should == "test-url" }
+  end
+
+  describe "#create_meeting" do
+    let(:meeting_name) { "name" }
+    let(:meeting_id) { "meeting-id" }
+    let(:moderator_password) { "moderator-password" }
+    let(:attendee_password) { "attendee-password" }
+    let(:welcome_message) { "welcome" }
+    let(:dial_number) { "dial-number" }
+    let(:logout_url) { "logout-url" }
+    let(:max_participants) { "max-participants" }
+    let(:voice_bridge) { "voice-bridge" }
+    let(:params) {
+      { :name => meeting_name, :meetingID => meeting_id,
+        :moderatorPW => moderator_password, :attendeePW => attendee_password,
+        :welcome => welcome_message, :dialNumber => dial_number,
+        :logoutURL => logout_url, :maxParticpants => max_participants,
+        :voiceBridge => voice_bridge }
+    }
+    let(:response) { { :meetingID => 123, :moderatorPW => 111, :attendeePW => 222, :hasBeenForciblyEnded => "FALSE" } }
+    let(:expected_response) { { :meetingID => "123", :moderatorPW => "111", :attendeePW => "222", :hasBeenForciblyEnded => false } }
+
+    # ps: not mocking the formatter here because it's easier to just check the results (expected_response)
+    before { api.should_receive(:send_api_request).with(:create, params).and_return(response) }
+    subject { api.create_meeting(meeting_name, meeting_id, moderator_password,
+                                 attendee_password, welcome_message, dial_number,
+                                 logout_url, max_participants, voice_bridge) }
+    it { subject.should == expected_response }
+  end
+
+  describe "#end_meeting" do
+    let(:meeting_id) { "meeting-id" }
+    let(:moderator_password) { "password" }
+    let(:params) { { :meetingID => meeting_id, :password => moderator_password } }
+    let(:response) { "anything" }
+
+    before { api.should_receive(:send_api_request).with(:end, params).and_return(response) }
+    it { api.end_meeting(meeting_id, moderator_password).should == response }
+  end
+
+  describe "#is_meeting_running?" do
+    let(:meeting_id) { "meeting-id" }
+    let(:params) { { :meetingID => meeting_id } }
+
+    context "when the meeting is running" do
+      let(:response) { { :running => "TRUE" } }
+      before { api.should_receive(:send_api_request).with(:isMeetingRunning, params).and_return(response) }
+      it { api.is_meeting_running?(meeting_id).should == true }
+    end
+
+    context "when the meeting is not running" do
+      let(:response) { { :running => "FALSE" } }
+      before { api.should_receive(:send_api_request).with(:isMeetingRunning, params).and_return(response) }
+      it { api.is_meeting_running?(meeting_id).should == false }
+    end
+  end
+
+  describe "#join_meeting" do
+    let(:meeting_id) { "meeting-id" }
+    let(:password) { "password" }
+    let(:user_name) { "user-name" }
+    let(:user_id) { "user-id" }
+    let(:web_voice_conf) { "web-voice-conf" }
+    let(:params) {
+      { :meetingID => meeting_id, :password => password, :fullName => user_name,
+        :userID => user_id, :webVoiceConf => web_voice_conf }
+    }
+
+    before { api.should_receive(:send_api_request).with(:join, params).and_return("join-return") }
+    it { api.join_meeting(meeting_id, user_name, password, user_id, web_voice_conf).should == "join-return" }
+  end
+
+  describe "#get_meeting_info" do
+    let(:meeting_id) { "meeting-id" }
+    let(:password) { "password" }
+    let(:params) { { :meetingID => meeting_id, :password => password } }
+
+    let(:attendee1) { { :userID => 123, :fullName => "Dexter Morgan", :role => "MODERATOR" } }
+    let(:attendee2) { { :userID => "id2", :fullName => "Cameron", :role => "VIEWER" } }
+    let(:response) {
+      { :meetingID => 123, :moderatorPW => 111, :attendeePW => 222, :hasBeenForciblyEnded => "FALSE",
+        :running => "TRUE", :startTime => "Thu Sep 01 17:51:42 UTC 2011", :endTime => "null",
+        :returncode => true, :attendees => { :attendee => [ attendee1, attendee2 ] }, :messageKey => "mkey", :message => "m" }
+    } # hash after the send_api_request call, before the specific formatting
+
+    let(:expected_attendee1) { { :userID => "123", :fullName => "Dexter Morgan", :role => :moderator } }
+    let(:expected_attendee2) { { :userID => "id2", :fullName => "Cameron", :role => :viewer } }
+    let(:expected_response) {
+      { :meetingID => "123", :moderatorPW => "111", :attendeePW => "222", :hasBeenForciblyEnded => false,
+        :running => true, :startTime => DateTime.parse("Thu Sep 01 17:51:42 UTC 2011"), :endTime => nil,
+        :returncode => true, :attendees => [ expected_attendee1, expected_attendee2 ], :messageKey => "mkey", :message => "m" }
+    } # expected return hash after all the formatting
+
+    # ps: not mocking the formatter here because it's easier to just check the results (expected_response)
+    before { api.should_receive(:send_api_request).with(:getMeetingInfo, params).and_return(response) }
+    it { api.get_meeting_info(meeting_id, password).should == expected_response }
+  end
+
+  describe "#get_meetings" do
+    let(:meeting_hash1) { { :meetingID => "Demo Meeting", :attendeePW => "ap", :moderatorPW => "mp", :hasBeenForciblyEnded => false, :running => true } }
+    let(:meeting_hash2) { { :meetingID => "Ended Meeting", :attendeePW => "pass", :moderatorPW => "pass", :hasBeenForciblyEnded => true, :running => false } }
+    let(:flattened_response) {
+      { :returncode => true, :meetings => [ meeting_hash1, meeting_hash2 ], :messageKey => "mkey", :message => "m" }
+    } # hash *after* the flatten_objects call
+
+    before {
+      # FIXME: how to expect a hash with a random value in the should_receive below?
+      api.should_receive(:send_api_request).with(:getMeetings, anything).and_return(flattened_response)
+      formatter_mock = mock(BigBlueButton::BigBlueButtonFormatter)
+      formatter_mock.should_receive(:flatten_objects).with(:meetings, :meeting)
+      formatter_mock.should_receive(:format_meeting).with(meeting_hash1)
+      formatter_mock.should_receive(:format_meeting).with(meeting_hash2)
+      BigBlueButton::BigBlueButtonFormatter.should_receive(:new).and_return(formatter_mock)
+    }
+    it { api.get_meetings }
+  end
+
+  describe "#get_api_version" do
+    context "returns the version returned by the server" do
+      let(:hash) { { :returncode => true, :version => "0.7" } }
+      before { api.should_receive(:send_api_request).with(:index).and_return(hash) }
+      it { api.get_api_version.should == "0.7" }
+    end
+
+    context "returns an empty string when the server responds with an empty hash" do
+      before { api.should_receive(:send_api_request).with(:index).and_return({}) }
+      it { api.get_api_version.should == "" }
+    end
+  end
+
+  describe "#test_connection" do
+    context "returns the returncode returned by the server" do
+      let(:hash) { { :returncode => "any-value" } }
+      before { api.should_receive(:send_api_request).with(:index).and_return(hash) }
+      it { api.test_connection.should == "any-value" }
+    end
+  end
+
+  describe "#==" do
+    let(:api2) { BigBlueButton::BigBlueButtonApi.new(url, salt, version, debug) }
+
+    context "compares attributes" do
+      it { api.should == api2 }
+    end
+
+    context "differs #debug" do
+      before { api2.debug = !api.debug }
+      it { api.should_not == api2 }
+    end
+
+    context "differs #salt" do
+      before { api2.salt = api.salt + "x" }
+      it { api.should_not == api2 }
+    end
+
+    context "differs #version" do
+      before { api2.version = api.version + "x" }
+      it { api.should_not == api2 }
+    end
+
+    context "differs #supported_versions" do
+      before { api2.supported_versions << "x" }
+      it { api.should_not == api2 }
+    end
+  end
+
+  describe "#last_http_response" do
+    # we test this through a #test_connection call
+
+    let(:request_mock) { mock }
+    before {
+      api.should_receive(:get_url)
+      # this return value will be stored in @http_response
+      api.should_receive(:send_request).and_return(request_mock)
+      # to return fast from #send_api_request
+      request_mock.should_receive(:body).and_return("")
+      api.test_connection
+    }
+    it { api.last_http_response.should == request_mock }
+  end
+
+  describe "#get_url" do
+
+    context "when method = :index" do
+      it { api.get_url(:index).should == api.url }
+    end
+
+    context "when method != :index" do
+      context "validates the entire url" do
+        context "with params" do
+          let(:params) { { :param1 => "value1", :param2 => "value2" } }
+          subject { api.get_url(:join, params) }
+          it { subject.should match(/#{url}\/join\?param1=value1&param2=value2/) }
+        end
+
+        context "without params" do
+          subject { api.get_url(:join) }
+          it { subject.should match(/#{url}\/join\?[^&]/) }
+        end
+      end
+
+      context "discards params with nil value" do
+        let(:params) { { :param1 => "value1", :param2 => nil } }
+        subject { api.get_url(:join, params) }
+        it { subject.should_not match(/param2=/) }
+      end
+
+      context "escapes all params" do
+        let(:params) { { :param1 => "value with spaces", :param2 => "@$" } }
+        subject { api.get_url(:join, params) }
+        it { subject.should match(/param1=value\+with\+spaces/) }
+        it { subject.should match(/param2=%40%24/) }
+      end
+
+      context "includes the checksum" do
+        let(:params) { { :param1 => "value1", :param2 => "value2" } }
+        let(:checksum) { Digest::SHA1.hexdigest("joinparam1=value1&param2=value2#{salt}") }
+        subject { api.get_url(:join, params) }
+        it { subject.should match(/checksum=#{checksum}$/) }
+      end
+    end
+  end
+
+  # FIXME: this complex test means that the method is too complex - try to refactor it
+  describe "#send_api_request" do
+    let(:method) { :join }
+    let(:params) { { :param1 => "value1" } }
+    let(:target_url) { "http://test-server:8080?param1=value1&checksum=12345" }
+    let(:make_request) { api.send_api_request(method, params) }
+    before { api.should_receive(:get_url).with(method, params).and_return(target_url) }
+
+    def setup_http_mock
+      @http_mock = mock(Net::HTTP)
+      Net::HTTP.should_receive(:new).with("test-server", 8080).and_return(@http_mock)
+      @http_mock.should_receive(:"open_timeout=").with(api.timeout)
+      @http_mock.should_receive(:"read_timeout=").with(api.timeout)
+    end
+
+    context "sets up the Net::HTTP object correctly" do
+      before do
+        setup_http_mock
+        response_mock = mock()
+        @http_mock.should_receive(:get).and_return(response_mock)
+        response_mock.should_receive(:body).and_return("") # so the method exits right after the setup
+      end
+      it { make_request }
+    end
+
+    context "handles a TimeoutError" do
+      before do
+        setup_http_mock
+        @http_mock.should_receive(:get) { raise TimeoutError }
+      end
+      it { expect { make_request }.to raise_error(BigBlueButton::BigBlueButtonException) }
+    end
+
+    context "handles general Exceptions" do
+      before do
+        setup_http_mock
+        @http_mock.should_receive(:get) { raise Exception }
+      end
+      it { expect { make_request }.to raise_error(BigBlueButton::BigBlueButtonException) }
+    end
+
+    context "returns an empty hash if the response body is empty" do
+      before do
+        setup_http_mock
+        response_mock = mock()
+        @http_mock.should_receive(:get).and_return(response_mock)
+        response_mock.should_receive(:body).and_return("")
+      end
+      it { make_request.should == { } }
+    end
+
+    context "hashfies and validates the response body" do
+      before do
+        setup_http_mock
+        response_mock = mock()
+        @http_mock.should_receive(:get).and_return(response_mock)
+        response_mock.should_receive(:body).twice.and_return("response-body")
+      end
+
+      context "checking if it has a :response key" do
+        before { Hash.should_receive(:from_xml).with("response-body").and_return({ }) }
+        it { expect { make_request }.to raise_error(BigBlueButton::BigBlueButtonException) }
+      end
+
+      context "checking if it the :response key has a :returncode key" do
+        before { Hash.should_receive(:from_xml).with("response-body").and_return({ :response => { } }) }
+        it { expect { make_request }.to raise_error(BigBlueButton::BigBlueButtonException) }
+      end
+    end
+
+    context "formats the response hash" do
+      let(:response) { { :response => { :returncode => true } } }
+      let(:formatted_response) { { :returncode => true } }
+      before do
+        setup_http_mock
+
+        response_mock = mock()
+        @http_mock.should_receive(:get).and_return(response_mock)
+        response_mock.should_receive(:body).twice.and_return("response-body")
+        Hash.should_receive(:from_xml).with("response-body").and_return(response)
+
+        # here starts the validation
+        formatter_mock = mock(BigBlueButton::BigBlueButtonFormatter)
+        BigBlueButton::BigBlueButtonFormatter.should_receive(:new).with(response).and_return(formatter_mock)
+        formatter_mock.should_receive(:default_formatting).and_return(formatted_response)
+      end
+      it { make_request }
+    end
+
+    context "raise an error if the formatted response has no :returncode" do
+      let(:response) { { :response => { :returncode => true } } }
+      let(:formatted_response) { { } }
+      before do
+        setup_http_mock
+
+        response_mock = mock()
+        @http_mock.should_receive(:get).and_return(response_mock)
+        response_mock.should_receive(:body).twice.and_return("response-body")
+        Hash.should_receive(:from_xml).with("response-body").and_return(response)
+
+        formatter_mock = mock(BigBlueButton::BigBlueButtonFormatter)
+        BigBlueButton::BigBlueButtonFormatter.should_receive(:new).with(response).and_return(formatter_mock)
+        formatter_mock.should_receive(:default_formatting).and_return(formatted_response)
+      end
+      it { expect { make_request }.to raise_error(BigBlueButton::BigBlueButtonException) }
+    end
+
+  end
+
+end

data/spec/bigbluebutton_exception_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe BigBlueButton::BigBlueButtonException do
+
+  describe "#key" do
+    subject { BigBlueButton::BigBlueButtonException.new }
+    it { should respond_to(:key) }
+    it { should respond_to("key=") }
+  end
+
+  describe "#to_s" do
+    context "when key is set" do
+      let(:api) { BigBlueButton::BigBlueButtonException.new("super-msg") }
+      before { api.key = "key-msg" }
+      it { api.to_s.should == "super-msg, messageKey: key-msg" }
+    end
+
+    context "when key is not set" do
+      let(:api) { BigBlueButton::BigBlueButtonException.new("super-msg") }
+      before { api.key = nil }
+      it { api.to_s.should == "super-msg" }
+    end
+  end
+
+end

data/spec/bigbluebutton_formatter_spec.rb

@@ -0,0 +1,143 @@
+require 'spec_helper'
+
+describe BigBlueButton::BigBlueButtonFormatter do
+
+  describe "#hash" do
+    subject { BigBlueButton::BigBlueButtonFormatter.new({}) }
+    it { subject.should respond_to(:hash) }
+    it { subject.should respond_to(:"hash=") }
+  end
+
+  describe "#to_stringtring" do
+    let(:hash) { { :param1 => "123", :param2 => 123, :param3 => true } }
+    subject { BigBlueButton::BigBlueButtonFormatter.new(hash) }
+    it { subject.to_string(:param1).should == "123" }
+    it { subject.to_string(:param2).should == "123" }
+    it { subject.to_string(:param3).should == "true" }
+  end
+
+  describe "#to_booleanoolean" do
+    let(:hash) { { :true1 => "TRUE", :true2 => "true", :false1 => "FALSE", :false2 => "false" } }
+    subject { BigBlueButton::BigBlueButtonFormatter.new(hash) }
+    it { subject.to_boolean(:true1).should be_true }
+    it { subject.to_boolean(:true2).should be_true }
+    it { subject.to_boolean(:false1).should be_false }
+    it { subject.to_boolean(:false2).should be_false }
+  end
+
+  describe "#to_datetime" do
+    let(:hash) { { :param1 => "Thu Sep 01 17:51:42 UTC 2011", :param2 => "Thu Sep 08", :param3 => "NULL" } }
+    subject { BigBlueButton::BigBlueButtonFormatter.new(hash) }
+    it { subject.to_datetime(:param1).should == DateTime.parse("Thu Sep 01 17:51:42 UTC 2011") }
+    it { subject.to_datetime(:param2).should == DateTime.parse("Thu Sep 08") }
+    it { subject.to_datetime(:param3).should == nil }
+  end
+
+  describe "#default_formatting" do
+    let(:input) { { :response => { :returncode => "SUCCESS", :messageKey => "mkey", :message => "m" } } }
+    let(:formatter) { BigBlueButton::BigBlueButtonFormatter.new(input) }
+
+    context "standard case" do
+      let(:expected_output) { { :returncode => true, :messageKey => "mkey", :message => "m" } }
+      subject { formatter.default_formatting }
+      it { subject.should == expected_output }
+    end
+
+    context "when :returncode should be false" do
+      before { input[:response][:returncode] = "ERROR" }
+      subject { formatter.default_formatting }
+      it { subject[:returncode].should be_false }
+    end
+
+    context "when :messageKey is empty" do
+      before { input[:response][:messageKey] = {} }
+      subject { formatter.default_formatting }
+      it { subject[:messageKey].should == "" }
+    end
+
+    context "when :messageKey is nil" do
+      before { input[:response].delete(:messageKey) }
+      subject { formatter.default_formatting }
+      it { subject[:messageKey].should == "" }
+    end
+
+    context "when :message is empty" do
+      before { input[:response][:message] = {} }
+      subject { formatter.default_formatting }
+      it { subject[:message].should == "" }
+    end
+
+    context "when there's no :message key" do
+      before { input[:response].delete(:message) }
+      subject { formatter.default_formatting }
+      it { subject[:message].should == "" }
+    end
+  end
+
+  describe "#format_meeting" do
+    let(:formatter) { BigBlueButton::BigBlueButtonFormatter.new({}) }
+    let(:hash) {
+      { :meetingID => 123, :moderatorPW => 111, :attendeePW => 222,
+        :hasBeenForciblyEnded => "FALSE", :running => "TRUE" }
+    }
+
+    subject { formatter.format_meeting(hash) }
+    it { subject[:meetingID].should == "123" }
+    it { subject[:moderatorPW].should == "111" }
+    it { subject[:attendeePW].should == "222" }
+    it { subject[:hasBeenForciblyEnded].should == false }
+    it { subject[:running].should == true }
+  end
+
+  describe "#format_attendee" do
+    let(:formatter) { BigBlueButton::BigBlueButtonFormatter.new({}) }
+    let(:hash) { { :userID => 123, :fullName => "Cameron", :role => "VIEWER" } }
+
+    subject { formatter.format_attendee(hash) }
+    it { subject[:userID].should == "123" }
+    it { subject[:fullName].should == "Cameron" }
+    it { subject[:role].should == :viewer }
+  end
+
+  describe "#flatten_objects" do
+    let(:formatter) { BigBlueButton::BigBlueButtonFormatter.new({ }) }
+
+    context "standard case" do
+      context "when the target key is empty" do
+        let(:hash) { { :objects => {} } }
+        before { formatter.hash = hash }
+        subject { formatter.flatten_objects(:objects, :object) }
+        it { subject.should == { :objects => [] } }
+      end
+
+      context "when there's only one object in the list" do
+        let(:object_hash) { { :id => 1 } }
+        let(:hash) { { :objects => { :object => object_hash } } }
+        before { formatter.hash = hash }
+        subject { formatter.flatten_objects(:objects, :object) }
+        it { subject.should == { :objects => [ object_hash ] } }
+      end
+
+      context "when there are several objects in the list" do
+        let(:object_hash1) { { :id => 1 } }
+        let(:object_hash2) { { :id => 2 } }
+        let(:hash) { { :objects => { :object => [ object_hash1, object_hash2 ] } } }
+        before { formatter.hash = hash }
+        subject { formatter.flatten_objects(:objects, :object) }
+        it { subject.should == { :objects => [ object_hash1, object_hash2 ] } }
+      end
+    end
+
+    context "using different keys" do
+      let(:hash1) { { :any => 1 } }
+      let(:hash2) { { :any => 2 } }
+      let(:collection_hash) { { :foos => { :bar => [ hash1, hash2 ] } } }
+      before { formatter.hash = collection_hash }
+      subject { formatter.flatten_objects(:foos, :bar) }
+      it { subject.should == { :foos => [ hash1, hash2 ] } }
+    end
+
+  end
+
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+# Load support files
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
+
+# Load Factories
+#require 'factory_girl'
+#require 'forgery'
+#Dir["#{ File.dirname(__FILE__)}/factories/*.rb"].each { |f| require f }
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+end
+
+require "bigbluebutton_api"

data/test/test.rb

@@ -1,10 +1,13 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+$:.unshift File.join(File.expand_path(File.dirname(__FILE__)), '..', 'lib')
+
 require 'bigbluebutton-api'
 require 'thread'
 require 'yaml'
 
 def prepare
 
-  config_file = 'test/config.yml'
+  config_file = File.join(File.dirname(__FILE__), 'config.yml')
   unless File.exist? config_file
     puts config_file + " does not exists. Copy the example and configure your server."
     puts "cp test/config.yml.example test/config.yml"
@@ -135,8 +138,17 @@ def join_test
 
 end
 
+def get_version_test
+  @api = BigBlueButton::BigBlueButtonApi.new(@config['bbb_url'], @config['bbb_salt'], nil, true)
+
+  puts
+  puts "---------------------------------------------------"
+  puts "The version of your BBB server is: #{@api.version}"
+end
+
 begin
   prepare
   general_test
   #join_test
+  #get_version_test
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bigbluebutton-api-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.11
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-04-28 00:00:00.000000000Z
+date: 2011-09-02 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &80178430 !ruby/object:Gem::Requirement
+  requirement: &20159120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,7 +22,7 @@ dependencies:
         version: 1.4.0
   type: :runtime
   prerelease: false
-  version_requirements: *80178430
+  version_requirements: *20159120
 description: Provides an interface to the BigBlueButton web meeting API (https://github.com/mconf/bigbluebutton-api-ruby)
 email:
 - leonardodaronco@gmail.com
@@ -35,13 +35,23 @@ extra_rdoc_files:
 - CHANGELOG.rdoc
 files:
 - .gitignore
+- .rspec
+- .rvmrc
 - CHANGELOG.rdoc
+- Gemfile
+- Gemfile.lock
 - LICENSE
 - README.rdoc
 - Rakefile
 - bigbluebutton-api-ruby.gemspec
-- lib/bigbluebutton-api.rb
+- lib/bigbluebutton_api.rb
+- lib/bigbluebutton_exception.rb
+- lib/bigbluebutton_formatter.rb
 - lib/hash_to_xml.rb
+- spec/bigbluebutton_api_spec.rb
+- spec/bigbluebutton_exception_spec.rb
+- spec/bigbluebutton_formatter_spec.rb
+- spec/spec_helper.rb
 - test/config.yml.example
 - test/test.rb
 homepage: https://github.com/mconf/bigbluebutton-api-ruby/
@@ -64,7 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.7.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Provides an interface to the BigBlueButton web meeting API (https://github.com/mconf/bigbluebutton-api-ruby)