ruby-fs-stack 0.2.3 → 0.2.4

data/README.rdoc

@@ -30,6 +30,7 @@ or for the pure Ruby implementation
 
 === Authenticating with FamilySearch
 
+  require 'rubygems'
   require 'ruby-fs-stack'
 
   communicator = FsCommunicator.new :domain => 'http://www.dev.usys.org', # or 'https://api.familysearch.org'
@@ -58,6 +59,10 @@ or for the pure Ruby implementation
   puts "First spouse's gender: " + person.families[0].parents[1].gender
   puts "First spouse's ID: " + person.families[0].parents[1].id
   
+  # read multiple persons in one request (up to 10)
+  people = ftcom.person ['KW3B-NNM','KWQS-BBQ','KWQS-BBR'], :parents => 'all', :children => 'all', :families => 'all'
+  people.size #=> 3
+  
 === Searching Records
 
   search = communicator.familytree_v2.search  :givenName => "John", 
@@ -78,7 +83,20 @@ or for the pure Ruby implementation
     puts result.mother.full_name #=> "Ruby Johnson"
     puts result.spouses.first.full_name #=> "Sarah Franklin"
   end
+  
+=== Combining Records
+
+  # reads the latest version numbers for the people requested and POSTs a combine request.
+  new_person = communicator.familytree_v2.combine ['KWQS-BBQ','KWRS-BBZ','KWQS-BNR']
+  new_person.id #=> 'KWQS-ZZZ'
+  new_person.version #=> '687799'
 
+== RDoc
+
+RDoc is hosted at rdoc.info:
+
+http://rdoc.info/projects/jimmyz/ruby-fs-stack
+  
 == Discussion
 
 A Google Group has been set up for questions and discussion

data/VERSION

@@ -1 +1 @@
-0.2.3
+0.2.4

data/lib/ruby-fs-stack/errors.rb

@@ -0,0 +1,74 @@
+
+module RubyFsStack
+  class FamilySearchError < StandardError
+    attr_reader :communicator
+    def initialize(msg = nil, communicator = nil)
+      @communicator = communicator if communicator
+      super(msg)
+    end
+  end
+  
+  # 310 	The user needs to go to the family tree and perform 
+  # some action, such as read a new version of the conditions of use.
+  class UserActionRequired < FamilySearchError
+  end
+  
+  # 400 	Bad Request. Generic client error or multiple client errors.
+  class BadRequest < FamilySearchError
+  end
+  
+  # 401 	Unauthorized. The user has invalid credentials or the session 
+  # ID is missing, invalid, or has expired. This error also appears if 
+  # the query string contains multiple question marks or the the session 
+  # parameter contains letters in an incorrect case.
+  class Unauthorized < FamilySearchError
+  end
+  
+  # 403 	Forbidden. The user does not have sufficient rights to perform 
+  # the operation.
+  class Forbidden < FamilySearchError
+  end
+  
+  # 404   Not Found. This request contained an invalid ID or a bad URI.
+  class NotFound < FamilySearchError
+  end
+  
+  # 409 	Conflict. The action could not be performed because it would 
+  # create a conflict.
+  class Conflict < FamilySearchError
+  end
+  
+  # 410   Gone. The requested resource has been deleted or recanted OR the 
+  # requested version of the API has been retired.
+  class Gone < FamilySearchError
+  end
+  
+  # 415 	Unsupported media type, invalid content-type in header, or invalid 
+  # character encoding.
+  class InvalidContentType < FamilySearchError
+  end
+  
+  # 430 	Bad version. Incorrect version of the object.
+  class BadVersion < FamilySearchError
+  end
+  
+  # 431   Invalid developer key.
+  class InvalidDeveloperKey < FamilySearchError
+  end
+  
+  # 500   Server Error. A generic server error or multiple server errors 
+  # occurred. If you get this error, please report it at https://issues.devnet.familysearch.org. 
+  class ServerError < FamilySearchError
+  end
+  
+  # 501 	Not Implemented. The requested service or combination of parameters 
+  # has not been implemented.
+  class NotImplemented < FamilySearchError
+  end
+  
+  # 503 	Service Unavailable. FamilySearch or the service that you are using is not currently 
+  # available. Or you are being throttled.
+  class ServiceUnavailable < FamilySearchError
+  end  
+  
+end

data/lib/ruby-fs-stack/fs_communicator.rb

@@ -1,9 +1,10 @@
+require 'ruby-fs-stack/errors'
 require 'net/https'
 require 'uri'
 
 class FsCommunicator
   attr_accessor :domain, :key, :user_agent, :session, :handle_throttling
-  
+  include RubyFsStack
   # ====Params
   # <tt>options</tt> - a hash with the following options
   # * :domain - Defaults to "http://www.dev.usys.org" (the Reference System)
@@ -75,11 +76,59 @@ class FsCommunicator
     if res.code == '503' && @handle_throttling
       sleep 15
       res = get(url,credentials)
+    elsif res.code != '200'
+      raise_exception(res)
     end
     return res
   end
   
   private
+  
+  # 310 UserActionRequired
+  # 400 BadRequest
+  # 401 Unauthorized
+  # 403 Forbidden
+  # 404 NotFound
+  # 409 Conflict
+  # 410 Gone
+  # 415 InvalidContentType
+  # 430 BadVersion
+  # 431 InvalidDeveloperKey
+  # 500 ServerError
+  # 501 NotImplemented
+  # 503 ServiceUnavailable
+  def raise_exception(res)
+    case res.code
+    when "310"
+      exception = UserActionRequired.new res.message, self
+    when "400"
+      exception = BadRequest.new res.message, self
+    when "401"
+      exception = Unauthorized.new res.message, self
+    when "403"
+      exception = Forbidden.new res.message, self
+    when "404"
+      exception = NotFound.new res.message, self
+    when "409"
+      exception = Conflict.new res.message, self
+    when "410"
+      exception = Gone.new res.message, self
+    when "415"
+      exception = InvalidContentType.new res.message, self
+    when "430"
+      exception = BadVersion.new res.message, self
+    when "431"
+      exception = InvalidDeveloperKey.new res.message, self
+    when "500"
+      exception = ServerError.new res.message, self
+    when "501"
+      exception = NotImplemented.new res.message, self
+    when "503"
+      exception = ServiceUnavailable.new res.message, self
+    end
+    raise exception
+  end
+  
   def set_extra_params(uri,credentials = {})
     if credentials[:username] && credentials[:password]
       sessionized_url = add_key(uri)

data/ruby-fs-stack.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{ruby-fs-stack}
-  s.version = "0.2.3"
+  s.version = "0.2.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jimmy Zimmerman"]
-  s.date = %q{2009-12-14}
+  s.date = %q{2009-12-16}
   s.description = %q{A library that enables you to read and update information with the new.familysearch.org API.}
   s.email = %q{jimmy.zimmerman@gmail.com}
   s.extra_rdoc_files = [
@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
      "lib/ruby-fs-stack/enunciate/README",
      "lib/ruby-fs-stack/enunciate/familytree.rb",
      "lib/ruby-fs-stack/enunciate/identity.rb",
+     "lib/ruby-fs-stack/errors.rb",
      "lib/ruby-fs-stack/familytree.rb",
      "lib/ruby-fs-stack/fs_communicator.rb",
      "lib/ruby-fs-stack/fs_utils.rb",

data/spec/communicator_spec.rb

@@ -1,5 +1,6 @@
- require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/spec_helper'
 require 'ruby-fs-stack/fs_communicator'
+require 'fakeweb'
 
 describe FsCommunicator do
   include HttpCommunicatorHelper
@@ -211,4 +212,127 @@ describe FsCommunicator do
     
   end
   
+  # 310 UserActionRequired
+  # 400 BadRequest
+  # 401 Unauthorized
+  # 403 Forbidden
+  # 404 NotFound
+  # 409 Conflict
+  # 410 Gone
+  # 415 InvalidContentType
+  # 430 BadVersion
+  # 431 InvalidDeveloperKey
+  # 500 ServerError
+  # 501 NotImplemented
+  # 503 ServiceUnavailable
+  describe "raising exceptions" do
+    def fake_web(path,status,message)
+      FakeWeb.register_uri(:get, "https://api.familysearch.org#{path}?sessionId=SESSID&dataFormat=application/json", :body => "",
+                          :status => [status, message])
+    end
+    
+    before(:each) do
+      options = {
+        :domain => 'https://api.familysearch.org', 
+        :key => '1111-1111', 
+        :user_agent => "FsCommunicator/0.1",
+        :session => 'SESSID'
+      }
+      @com = FsCommunicator.new options
+      @path = '/familytree/v2/person'
+      FakeWeb.allow_net_connect = false
+    end
+    
+    it "should raise a UserActionRequired on a 310" do
+      fake_web(@path,'310',"User Action Required")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::UserActionRequired)
+    end
+    
+    it "should raise a BadRequest on a 400" do
+      fake_web(@path,'400',"Bad Request")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::BadRequest)
+    end
+    
+    it "should raise a BadRequest on a 401" do
+      fake_web(@path,'401',"Unauthorized")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::Unauthorized)
+    end
+    
+    it "should raise a Forbidden on 403" do
+      fake_web(@path,'403',"Forbidden")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::Forbidden)
+    end
+    
+    it "should raise a 404 NotFound" do
+      fake_web(@path,'404',"NotFound")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::NotFound)
+    end
+    
+    it "should raise a 409 Conflict" do
+      fake_web(@path,'409',"Conflict")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::Conflict)
+    end
+    
+    it "should raise a 410 Gone" do
+      fake_web(@path,'410',"Gone")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::Gone)
+    end
+    
+    it "should raise a 415 InvalidContentType" do
+      fake_web(@path,'415',"Invalid Content Type")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::InvalidContentType)
+    end
+    
+    it "should raise a 430 BadVersion" do
+      fake_web(@path,'430',"Bad Version")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::BadVersion)
+    end
+    
+    it "should raise a 431 InvalidDeveloperKey" do
+      fake_web(@path,'431',"Invalid Developer Key")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::InvalidDeveloperKey)
+    end
+    
+    it "should raise a 500 ServerError" do
+      fake_web(@path,'500',"Server Error")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::ServerError)
+    end
+    
+    it "should raise a 501 NotImplemented" do
+      fake_web(@path,'501',"Not Implemented")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::NotImplemented)
+    end
+    
+    it "should raise a 503 ServiceUnavailable" do
+      fake_web(@path,'503',"Service Unavailable")
+      lambda{
+        @com.get(@path)
+      }.should raise_error(RubyFsStack::ServiceUnavailable)
+    end
+  end
+  
 end

data/spec/familytree_v2/match_results_spec.rb

@@ -2,7 +2,7 @@ require File.dirname(__FILE__) + '/../spec_helper'
 require 'ruby-fs-stack/familytree'
 
 describe Org::Familysearch::Ws::Familytree::V2::Schema::MatchResults, "parsing match results" do
-  FamilyTreeV2 = Org::Familysearch::Ws::Familytree::V2::Schema
+  FamilyTreeV2 = Org::Familysearch::Ws::Familytree::V2::Schema unless Object.const_defined?(:FamilyTreeV2)
   
   def read_file(filename)
     fname = File.join(File.dirname(__FILE__),'json',filename)

data/spec/familytree_v2/search_results_spec.rb

@@ -3,7 +3,7 @@ require 'ruby-fs-stack/familytree'
 
 
 describe Org::Familysearch::Ws::Familytree::V2::Schema::SearchResults do
-  FamilyTreeV2 = Org::Familysearch::Ws::Familytree::V2::Schema
+  FamilyTreeV2 = Org::Familysearch::Ws::Familytree::V2::Schema unless Object.const_defined?(:FamilyTreeV2)
   
   def read_file(filename)
     fname = File.join(File.dirname(__FILE__),'json',filename)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-fs-stack
 version: !ruby/object:Gem::Version 
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors: 
 - Jimmy Zimmerman
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-14 00:00:00 -07:00
+date: 2009-12-16 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -56,6 +56,7 @@ files:
 - lib/ruby-fs-stack/enunciate/README
 - lib/ruby-fs-stack/enunciate/familytree.rb
 - lib/ruby-fs-stack/enunciate/identity.rb
+- lib/ruby-fs-stack/errors.rb
 - lib/ruby-fs-stack/familytree.rb
 - lib/ruby-fs-stack/fs_communicator.rb
 - lib/ruby-fs-stack/fs_utils.rb