opencellid-client 0.1.0

data/lib/opencellid/utils.rb

@@ -0,0 +1,25 @@
+module Opencellid
+
+  # A helper function that avoids invoking `to_i` on a string when it is null or empty
+  # @param string [String] the nullable string containing the data to transformed into an integer
+  # @return [Integer] `nil` if the string passed is nil or empty, the result of `to_i` otherwise
+  def self.to_i_or_nil(string)
+    string and string.length > 0 ? string.to_i : nil
+  end
+
+  # A helper function that avoids invoking `to_f` on a string when it is null or empty
+  # @param string [String] the nullable string containing the data to transformed into a float
+  # @return [Float] `nil` if the string passed is nil or empty, the result of `to_f` otherwise
+  def self.to_f_or_nil(string)
+    string and string.length > 0 ? string.to_f : nil
+  end
+
+  # A helper function that avoids invoking `strptime` on a string when it is null or empty
+  # @param string [String] the nullable string containing the data to transformed into a DateTime
+  # @param format [String] the format string as specified by `strptime`
+  # @return [DateTime] `nil` if the string passed is nil or empty, the result of `DateTime.strptime` otherwise
+  def self.to_datetime_or_nil(string, format)
+    string and string.length > 0 ? DateTime.strptime(string, format) : nil
+  end
+
+end

data/lib/opencellid/version.rb

@@ -0,0 +1,5 @@
+module Opencellid
+
+  # This library current version
+  VERSION = "0.1.0"
+end

data/opencellid-client.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "opencellid/version"
+
+Gem::Specification.new do |s|
+  s.name        = "opencellid-client"
+  s.version     = Opencellid::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Marco Sandrini"]
+  s.email       = ["nessche@gmail.com"]
+  s.homepage    = "https://github.com/nessche/opencellid-client"
+  s.summary     = "A Ruby client for OpenCellID API"
+  s.description = "A Ruby client for OpenCellID API"
+
+
+  s.files         = `git ls-files`.split("\n")
+  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"]
+
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "webmock"
+  s.add_development_dependency "simplecov"
+  # s.add_runtime_dependency "rest-client"
+end

data/spec/lib/bbox_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+require 'opencellid'
+
+module Opencellid
+
+  describe BBox do
+
+    describe "new" do
+
+      context "when one or more parameters are nil" do
+
+        it "should raise an ArgumentError" do
+          expect{BBox.new(nil,1.0,1.0,1.0)}.to raise_error ArgumentError
+          expect{BBox.new(1.0,nil,1.0,1.0)}.to raise_error ArgumentError
+          expect{BBox.new(1.0,1.0,nil,1.0)}.to raise_error ArgumentError
+          expect{BBox.new(1.0,1.0,1.0,nil)}.to raise_error ArgumentError
+        end
+
+      end
+
+      context "when all parameters are not nil" do
+
+        it "should return the correct object" do
+          bbox = BBox.new(1.0,2.0,3.0,4.0)
+          bbox.latmin.should == 1.0
+          bbox.latmax.should == 3.0
+          bbox.lonmin.should == 2.0
+          bbox.lonmax.should == 4.0
+        end
+
+      end
+
+    end
+
+    describe "to_s" do
+
+      it "should return a string in the format needed by opencellid" do
+        bbox = BBox.new(1.0,2.0,3.0,4.0)
+        expected_string = "1.0,2.0,3.0,4.0"
+        bbox.to_s.should == expected_string
+      end
+
+    end
+
+  end
+
+end

data/spec/lib/cell_spec.rb

@@ -0,0 +1,138 @@
+require 'spec_helper'
+require 'opencellid'
+require 'rexml/document'
+
+module Opencellid
+
+  WELL_FORMED_CELL =  '<cell lat="60.3276113" mcc="244" lon="24.8689952" nbSamples="5" cellId="118135" mnc="91" lac="" range="6000"/>'
+  WELL_FORMED_CELL_WITH_MEASURE = <<XML
+
+  <cell lat="60.3276113" mcc="244" lon="24.8689952" cellId="118135" nbSamples="5" mnc="91" lac="" range="6000">
+    <measure lat="60.3277783333333" lon="24.8693505" takenOn="Fri Jul 22 15:02:17 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.3275705" lon="24.8689813333333" takenOn="Sun Aug 07 23:22:04 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.3273111666667" lon="24.867736" takenOn="Mon Aug 08 11:10:47 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.3278625" lon="24.8698973333333" takenOn="Mon Aug 08 12:31:59 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.327534" lon="24.8690108333333" takenOn="Mon Aug 08 12:32:03 +0200 2011" takenBy="4207"></measure>
+  </cell>
+
+XML
+
+  describe "Cell" do
+
+    describe "from_element" do
+
+      context "when passed a well formed XML" do
+
+        it "should parse the cell attributes correctly" do
+
+          doc = REXML::Document.new WELL_FORMED_CELL
+          result = Cell.from_element(doc.root)
+          result.should be_a Cell
+          result.lat.should == 60.3276113
+          result.lon.should == 24.8689952
+          result.mcc.should == 244
+          result.mnc.should == 91
+          result.no_of_samples.should == 5
+          result.id.should == 118135
+          result.lac.should be_nil
+          result.range.should == 6000
+
+        end
+
+
+      end
+
+      context "when passed nil" do
+
+        it "should return nil" do
+          Cell.from_element(nil).should be_nil
+        end
+
+      end
+
+      context "when passed something else than an XML element" do
+
+        it "should raise an ArgumentError" do
+          expect{Cell.from_element "This is just a String"}.to raise_error ArgumentError
+        end
+
+      end
+
+      context "when passed an XML element not of type cell" do
+
+        it "should raise an ArgumentError" do
+          doc = REXML::Document.new "<a>This is not a cell</a>"
+          expect{Cell.from_element doc}.to raise_error ArgumentError
+        end
+
+      end
+
+    end
+
+    describe "has_measures?" do
+
+      context "when measures array is empty" do
+
+        it "should return false" do
+          cell = Cell.new(1,2,3,4)
+          cell.has_measures?.should be_false
+        end
+
+      end
+
+      context "when measures array is not empty" do
+
+        it "should return true" do
+          cell = Cell.new(1,2,3,4)
+          cell.add_measure(Measure.new(1.0,1.0))
+          cell.has_measures?.should be_true
+        end
+
+      end
+
+    end
+
+    describe "to_query_hash" do
+
+      it "should return a hash" do
+        Cell.new(1,2,3,4).to_query_hash.should be_a Hash
+      end
+
+      it "should only have query parameters" do
+        cell = Cell.new(1,2,3,4)
+        cell.range = 3000
+        cell.add_measure Measure.new(1.0,1.0)
+        hash = cell.to_query_hash
+        hash.count.should == 4
+        hash.should include :cellid
+        hash.should include :mnc
+        hash.should include :mcc
+        hash.should include :lac
+
+      end
+
+      it "should have parameters correctly mapped" do
+        cell = Cell.new(1,2,3,4)
+        hash = cell.to_query_hash
+        hash[:cellid].should == 1
+        hash[:mnc].should == 2
+        hash[:mcc].should == 3
+        hash[:lac].should == 4
+
+      end
+
+      it "should leave out nil parameters" do
+        Cell.new(nil,2,3,4).to_query_hash.should_not include :cellid
+        Cell.new(1,nil,3,4).to_query_hash.should_not include :mnc
+        Cell.new(1,2,nil,4).to_query_hash.should_not include :mcc
+        Cell.new(1,2,3,nil).to_query_hash.should_not include :lac
+      end
+
+
+    end
+
+
+
+  end
+
+end

data/spec/lib/data/cell_not_found.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<rsp stat="fail">
+  <err info=" cell not found" code="1"/>
+</rsp>

data/spec/lib/data/cell_with_measures.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<rsp stat="ok">
+  <cell lat="60.3276113" mcc="244" lon="24.8689952" cellId="118135" nbSamples="5" mnc="91" lac="" range="6000">
+    <measure lat="60.3277783333333" lon="24.8693505" takenOn="Fri Jul 22 15:02:17 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.3275705" lon="24.8689813333333" takenOn="Sun Aug 07 23:22:04 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.3273111666667" lon="24.867736" takenOn="Mon Aug 08 11:10:47 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.3278625" lon="24.8698973333333" takenOn="Mon Aug 08 12:31:59 +0200 2011" takenBy="4207"></measure>
+    <measure lat="60.327534" lon="24.8690108333333" takenOn="Mon Aug 08 12:32:03 +0200 2011" takenBy="4207"></measure>
+  </cell>
+</rsp>

data/spec/lib/data/measure_added.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<rsp cellid="1252312" stat="ok" id="56216401">
+  <res>Measure added, id:56216401</res>
+</rsp>

data/spec/lib/data/measure_list.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<measures total="2">
+  <measure lat="60.5" measured_at="Fri Feb 03 15:33:43 +0100 2012" mcc="1" lon="30.3" signal="" cellId="123456" mnc="1" id="56198375" lac="9000"/>
+  <measure lat="60.6" measured_at="Fri Feb 03 15:43:06 +0100 2012" mcc="1" lon="30.5" signal="" cellId="123457" mnc="1" id="56198417" lac="9000"/>
+</measures>

data/spec/lib/data/one_cell.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<rsp stat="ok">
+  <cell lat="60.3276113" mcc="244" lon="24.8689952" nbSamples="5" cellId="118135" mnc="91" lac="" range="6000"/>
+</rsp>

data/spec/lib/error_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+require 'opencellid'
+
+module Opencellid
+
+  WELL_FORMED_ERROR = '<err info="cell not found" code="1"/>'
+
+  describe Error do
+
+    describe "from_element" do
+
+      context "when passed a well formed error" do
+
+        it "should parse the XML correctly" do
+          doc = REXML::Document.new WELL_FORMED_ERROR
+          error = Error.from_element doc.root
+          error.should be_a Error
+          error.code.should == 1
+          error.info.should == "cell not found"
+        end
+
+      end
+
+      context "when passed nil" do
+
+        it "should return nil" do
+          Error.from_element(nil).should be_nil
+        end
+
+      end
+
+      context "when passing something else than an XML element" do
+
+        it "should raise an ArgumentError" do
+          expect{Error.from_element "This is just a String"}. to raise_error ArgumentError
+        end
+
+
+      end
+
+      context "when passed something else then a measure" do
+
+        it "should raise an Argument Error" do
+          doc = REXML::Document.new "<a>this is not an error</a>"
+          expect{Error.from_element doc}.to raise_error ArgumentError
+        end
+
+
+      end
+
+    end
+
+
+
+  end
+
+
+end

data/spec/lib/measure_spec.rb

@@ -0,0 +1,73 @@
+require 'spec_helper'
+require 'opencellid'
+require 'rexml/document'
+
+module Opencellid
+
+  WELL_CELL_SUB = '<measure lat="60.3277783333333" lon="24.8693505" takenOn="Fri Jul 22 15:02:17 +0200 2011" takenBy="4207"></measure>'
+  MEASURE_LIST_SUB = '<measure measured_at="Fri Jul 22 10:10:10 +0200 2011" lat="1.0" mcc="1" lon="2.0" signal="10" cellId="2" mnc="1" id="56216430" lac="4"/>'
+  describe "Measure" do
+
+    describe "from_element" do
+
+      context "when passed a well formed measure" do
+
+        it "should parse the cell sub-element correctly" do
+          doc = REXML::Document.new WELL_CELL_SUB
+          measure = Measure.from_element doc.root
+          measure.should be_a Measure
+          measure.lat.should == 60.3277783333333
+          measure.lon.should == 24.8693505
+          measure.taken_by.should == "4207"
+          measure.signal.should be_nil
+          measure.id.should be_nil
+          expected_data = DateTime.new(2011,7,22,15,2,17,Rational(2,24))
+          measure.taken_on.should == expected_data
+        end
+
+        it "should parse the measure list sub-element correctly" do
+          doc = REXML::Document.new MEASURE_LIST_SUB
+          measure = Measure.from_element doc.root
+          measure.should be_a Measure
+          measure.lat.should == 1.0
+          measure.lon.should == 2.0
+          measure.id.should == 56216430
+          measure.taken_by.should be_nil
+          expected_data = DateTime.new(2011,7,22,10,10,10,Rational(2,24))
+          measure.taken_on.should == expected_data
+        end
+
+      end
+
+      context "when passed nil" do
+
+        it "should return nil" do
+          Measure.from_element(nil).should be_nil
+        end
+
+      end
+
+      context "when passing something else than an XML element" do
+
+        it "should raise an ArgumentError" do
+          expect{Measure.from_element "This is just a String"}. to raise_error ArgumentError
+        end
+
+
+      end
+
+      context "when passed something else then a measure" do
+
+        it "should raise an Argument Error" do
+          doc = REXML::Document.new "<a>this is not a measure</a>"
+          expect{Measure.from_element doc}.to raise_error ArgumentError
+        end
+
+
+      end
+
+    end
+
+  end
+
+end

data/spec/lib/opencellid_spec.rb

@@ -0,0 +1,242 @@
+require 'spec_helper'
+require 'opencellid'
+
+module Opencellid
+
+  describe Opencellid do
+
+    before do
+      WebMock.disable_net_connect!
+      stub_request(:get, /www\.opencellid\.org/).to_return(status: 200, body: data_file_as_string('one_cell.xml'))
+      @oci = Opencellid.new
+      @response = double(:response)
+      Response.stub(:from_xml).and_return(@response)
+    end
+
+    describe "execute_request_and_parse_response" do
+
+      before do
+        @method = @oci.method(:execute_request_and_parse_response)
+
+      end
+
+      context "when the api key is specified" do
+
+        before do
+          @oci = Opencellid.new "myapikey"
+          @method = @oci.method(:execute_request_and_parse_response)
+        end
+
+        it "should add it to the parameters" do
+          @method.call("/")
+          WebMock.should have_requested(:get, "www.opencellid.org/")
+                         .with(query: { "key" => "myapikey"})
+        end
+
+      end
+
+      context "when the api key is not specified" do
+
+        it "should not add it to the parameters" do
+          @method.call("/")
+          WebMock.should have_requested(:get, "www.opencellid.org/")
+        end
+
+      end
+
+      it "should add the params as query params" do
+
+        @method.call("/",{"a" => "10", "b" => "20", "c" => "30"})
+        WebMock.should have_requested(:get, "www.opencellid.org/")
+                       .with(query: {"a" => "10", "b" => "20", "c" => "30"})
+      end
+
+      it "should set the path correctly" do
+        @method.call("/mypath")
+        WebMock.should have_requested(:get, "www.opencellid.org/mypath")
+      end
+
+      context "when HTTP Response status is 200" do
+
+        it "should invoke from_xml on Response" do
+          expected_xml = data_file_as_string('one_cell.xml')
+          Response.should_receive(:from_xml).with(expected_xml)
+          @method.call("/")
+        end
+
+        it "should return the Response object" do
+          @method.call("/").should == @response
+        end
+
+      end
+
+      context "when HTTP Response is not 200" do
+
+        before do
+          stub_request(:get, /www\.opencellid\.org/).to_return(status: 500, body: "Internal Server Error")
+        end
+
+        it "should return a response of type failure" do
+          response = @method.call("/")
+          response.should_not be_ok
+          response.error.code.should == 0
+          response.error.info.should == "Http Request failed with code 500"
+        end
+
+      end
+
+    end
+
+    describe "get_cell" do
+
+      context "when parameter is not a Cell" do
+
+        it "should raise an ArgumentError" do
+          expect{@oci.get_cell nil}.to raise_error ArgumentError
+          expect{@oci.get_cell "This is a not a Cell"}.to raise_error ArgumentError
+        end
+
+      end
+
+      it "should set the correct path and parameters" do
+        @oci.get_cell(Cell.new(1,2,3,4))
+        WebMock.should have_requested(:get, "www.opencellid.org/cell/get")
+                       .with(query: {"cellid" => "1", "mnc" => "2", "mcc" => "3", "lac" => "4"})
+      end
+
+      it "should return a response" do
+        @oci.get_cell(Cell.new(1,2,3,4)).should == @response
+      end
+
+    end
+
+    describe "get_cell_measures" do
+
+      context "when parameter is not a Cell" do
+
+        it "should raise an ArgumentError" do
+          expect{@oci.get_cell_measures nil}.to raise_error ArgumentError
+          expect{@oci.get_cell_measures "This is a not a Cell"}.to raise_error ArgumentError
+        end
+
+      end
+
+      it "should set the correct path and parameters" do
+        @oci.get_cell_measures(Cell.new(1,2,3,4))
+        WebMock.should have_requested(:get, "www.opencellid.org/cell/getMeasures")
+                       .with(query: {"cellid" => "1", "mnc" => "2", "mcc" => "3", "lac" => "4"})
+      end
+
+      it "should return a response" do
+        @oci.get_cell_measures(Cell.new(1,2,3,4)).should == @response
+      end
+
+    end
+
+    describe "get_cells_in_area" do
+
+      before do
+        @bbox = BBox.new(1.0,2.0,3.0,4.0)
+        @options = {mnc: 10, mcc: 20, limit: 30}
+      end
+
+      context "when parameters are not of right type" do
+
+        it "should raise an ArgumentError" do
+          expect{@oci.get_cells_in_area nil, @options}.to raise_error ArgumentError
+          expect{@oci.get_cells_in_area "This is a not a BBox", @options}.to raise_error ArgumentError
+          expect{@oci.get_cells_in_area @bbox, "This is not a hash" }.to raise_error ArgumentError
+        end
+
+      end
+
+      it "should set the correct path" do
+        @oci.get_cells_in_area(@bbox)
+        WebMock.should have_requested(:get, "www.opencellid.org/cell/getInArea")
+                       .with(query: {"bbox" => @bbox.to_s, "fmt" => "xml"})
+      end
+
+      it "should filter out invalid parameters from options" do
+        @oci.get_cells_in_area(@bbox, mnc: 20, invalid_params: 50, limit: 30, mcc: 60)
+        WebMock.should have_requested(:get, "www.opencellid.org/cell/getInArea")
+                       .with(query: {"bbox" => @bbox.to_s, "fmt" => "xml", "mnc" => "20", "mcc" => "60", "limit" => "30"})
+
+      end
+
+      it "should return a response" do
+        @oci.get_cells_in_area(@bbox).should == @response
+      end
+
+    end
+
+    describe "add_measure" do
+
+      before do
+        @cell = Cell.new(1,2,3,4)
+        @measured_at = DateTime.new(2011,7,22,10,10,10,Rational(2,24))
+        @measure = Measure.new(1.0, 2.0, @measured_at)
+        @measure.signal = 10
+      end
+
+      context "when parameters are of wrong type" do
+
+        it "should raise an ArgumentError" do
+          expect{@oci.add_measure nil, @measure}.to raise_error ArgumentError
+          expect{@oci.add_measure "This is not a Cell", @measure}.to raise_error ArgumentError
+          expect{@oci.add_measure @cell, nil}.to raise_error ArgumentError
+          expect{@oci.add_measure @cell, "This is not a measure"}.to raise_error ArgumentError
+        end
+
+      end
+
+      it "should set the correct path and parameters" do
+        @oci.add_measure(@cell, @measure)
+        WebMock.should have_requested(:get, "www.opencellid.org/measure/add")
+                       .with(query: {"cellid" => "1", "mnc" => "2", "mcc" => "3", "lac" => "4",
+                                     "lat" => "1.0", "lon" => "2.0", "measured_at" => @measured_at.to_s, "signal" => "10"})
+      end
+
+      it "should return a response" do
+        @oci.add_measure(@cell, @measure).should == @response
+      end
+
+    end
+
+    describe "list_measures" do
+
+      it "should set the correct path and parameters" do
+        @oci.list_measures
+        WebMock.should have_requested(:get, "www.opencellid.org/measure/list")
+      end
+
+      it "should return a response" do
+        @oci.list_measures.should == @response
+      end
+
+    end
+
+    describe "delete_measure" do
+
+      context "when measure_id is nil" do
+
+        it "should raise an ArgumentError" do
+          expect{@oci.delete_measure nil}.to raise_error ArgumentError
+        end
+
+      end
+
+      it "should set the correct path and parameters" do
+        @oci.delete_measure 30
+        WebMock.should have_requested(:get, "www.opencellid.org/measure/delete")
+                       .with(query: {"id" => "30"})
+      end
+
+      it "should return a response" do
+        @oci.delete_measure(30).should == @response
+      end
+
+    end
+
+  end
+
+end