gom-client 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 47c079f7884f7690f09f7ce8c4c0a50bfc65e38e
+  data.tar.gz: 6231c9a90c47c9fa3f791b350e99e3219bbcd018
+SHA512:
+  metadata.gz: e0c2f0fefd4cd006b1dad046c576ba8cd1e1720a763a502c062c8629ff18ab42ef30ef26ab019ca7e81bfc102333b36560eaa5af6adc1ad4f558f8eb474e064e
+  data.tar.gz: 63e505910da3384fca83820a086ac192de61280f1e1f3a397941bcbf5aa02522a6221a6fd938cff1e0011a9b9704abbf70ce074affa7037a1d8d1f8d6b571017

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+
+## PROJECT::SPECIFIC
+README.html
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+bundler_args: --without development
+before_script:
+script: "bundle exec rspec"
+env:
+  - CI=true
+rvm:
+  - 1.9.3
+  - 2.0.0
+gemfile:
+  - Gemfile
+notifications:
+  recipients:
+    - dirk.luesebrink@artcom.com
+branches:
+  only:
+    - webmock

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/Guardfile

@@ -0,0 +1,8 @@
+# Guardfile info at: https://github.com/guard/guard#readme
+
+guard 'rspec', all_on_start: true, cli: '--format nested --debug --color' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+  watch('lib/gom/client.rb')    { "spec" }
+end

data/README.md

@@ -0,0 +1,146 @@
+# Ruby Gom Client
+
+## Requirements
+
+* Ruby 1.9
+
+## Setup and Initialization
+
+```ruby
+GOM = Gom::Client.new GOM_ROOT
+```
+
+Where the GOM_ROOT is of format `"http://<ip | hostname>[:<port>]"`. Further
+operations are then performed via the initialized object (in this example
+`GOM`)
+
+## RESTful operations
+
+### GET/retrieve
+
+Attribute retrieval:
+
+```ruby
+>>> myAttribute = GOM.retrieve("/test:myAttr")    
+{'attribute': {'ctime': '2012-10-12T08:46:48+02:00',
+           'mtime': '2012-10-12T08:46:48+02:00',
+           'name': 'myAttr',
+           'node': '/test',
+           'type': 'string',
+           'value': 'test'}}
+```
+
+Node retrieval:
+
+  ```ruby
+  >>> myNode = GOM.retrieve("/areas")
+  {'node': {'ctime': '2012-09-20T04:51:56+02:00',
+        'entries': [{'ctime': '2012-07-30T16:13:02+02:00',
+                     'mtime': '2012-07-30T16:13:02+02:00',
+                     'node': '/areas/home'},
+                    {'ctime': '2012-09-29T17:51:47+02:00',
+                   'mtime': '2012-09-29T17:51:47+02:00',
+                   'node': '/areas/life'},
+                  {'ctime': '2012-06-26T21:13:35+02:00',
+                   'mtime': '2012-06-26T21:13:35+02:00',
+                   'node': '/areas/mobile'},
+                  {'ctime': '2012-10-10T18:30:50+02:00',
+                   'mtime': '2012-10-10T18:30:50+02:00',
+                   'node': '/areas/move'},
+                  {'ctime': '2012-09-20T02:19:30+02:00',
+                   'mtime': '2012-09-20T02:19:30+02:00',
+                   'node': '/areas/pre-show'},
+                  {'ctime': '2012-07-30T14:03:57+02:00',
+                   'mtime': '2012-07-30T14:03:57+02:00',
+                   'node': '/areas/welcome'},
+                  {'attribute': {'ctime': '2012-10-11T07:02:18+02:00',
+                                 'mtime': '2012-10-11T07:02:18+02:00',
+                                 'name': 'operational_mode',
+                                 'node': '/areas',
+                                 'type': 'string',
+                                 'value': 'idle'}}],
+      'mtime': '2012-09-20T04:51:56+02:00',
+      'uri': '/areas'}}
+```
+
+Retrieval of non-existent Node/Attribute:
+
+```ruby
+>>> pprint(GOM.retrieve("/test/does-not-exist"))
+None
+>>> pprint(GOM.retrieve("/test:does-not-exist"))
+None
+```
+
+### PUT/update
+
+Attribute update
+
+```ruby
+>>> GOM.update!("/test:temperature", "50 °C")
+'50 °C'
+```
+   
+Node update
+
+```ruby
+>>> GOM.update!("/test/weather", {"temperature": "50 °C", "wind_velocity": "3 km/h", "wind_direction": "NNW"})
+{'status': 201}
+```
+
+### DELETE/destroy
+
+Delete existing node
+  
+```ruby
+>>> GOM.destroy("/test/c18bf546-e577-414a-92d2-2ebdfb69b4f6")
+True
+```
+
+Delete non-existing node
+  
+```ruby
+>>> print(GOM.destroy("/test/does-not-exist"))
+None
+```
+  
+Attributes are deleted accordingly
+
+### POST/create
+  
+Create empty node
+
+```ruby
+>>> GOM.create!("/test")
+'/test/c18bf546-e577-414a-92d2-2ebdfb69b4f6'
+```
+
+Create node with attributes
+  
+```ruby
+>>> GOM.create!("/test", {"name":"Hans", "profession": "Lumberjack"})
+'/test/419e9db0-2800-43ed-9053-edaafd4f60b3'
+>>> GOM.retrieve("/test/419e9db0-2800-43ed-9053-edaafd4f60b3")
+{'node': {'ctime': '2012-10-12T10:43:25+02:00',
+          'entries': [{'attribute': {'ctime': '2012-10-12T10:43:25+02:00',
+                                     'mtime': '2012-10-12T10:43:25+02:00',
+                                     'name': 'name',
+                                     'node': '/test/419e9db0-2800-43ed-9053-edaafd4f60b3',
+                                     'type': 'string',
+                                     'value': 'Hans'}},
+                      {'attribute': {'ctime': '2012-10-12T10:43:25+02:00',
+                                     'mtime': '2012-10-12T10:43:25+02:00',
+                                     'name': 'profession',
+                                     'node': '/test/419e9db0-2800-43ed-9053-edaafd4f60b3',
+                                     'type': 'string',
+                                     'value': 'Lumberjack'}}],
+          'mtime': '2012-10-12T10:43:25+02:00',
+          'uri': '/test/419e9db0-2800-43ed-9053-edaafd4f60b3'}}
+```
+
+## Packaging
+
+## TODO
+
+* Document script runner (run_script)
+* Document gom observer creation (register_observer)

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/gom-client-ruby.gemspec

@@ -0,0 +1,36 @@
+require 'rake'
+
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require 'gom/client/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'gom-client'
+  s.version     = Gom::Client::VERSION
+  s.date        = Gom::Client::DATE
+  s.authors     = "ART+COM"
+  s.homepage    = 'http://www.artcom.de/'
+  s.summary     = 'REST client for the gom HTTP API'
+
+  s.add_dependency 'json'
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'guard'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'rb-fsevent', '~>0.9.1'
+  s.add_development_dependency 'webmock'
+  s.add_development_dependency 'vcr'
+
+  if RUBY_PLATFORM.match /java/i
+    s.add_development_dependency 'ruby-debug'
+  else
+    s.add_development_dependency 'debugger'
+  end
+
+  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 do |f| 
+    File.basename(f)
+  end
+  s.require_paths = ["lib"]
+end

data/lib/gom/client/version.rb

@@ -0,0 +1,6 @@
+module Gom
+  class Client
+    VERSION = '0.0.2'
+    DATE    = '2013-08-15'
+  end
+end

data/lib/gom/client.rb

@@ -0,0 +1,226 @@
+require 'uri'
+require 'net/http'
+#require 'active_support'
+require 'rexml/document'
+require 'gom/client/version'
+require 'json' #/pure'
+
+module Gom
+
+  class HttpError < StandardError
+    attr_reader :response, :description
+
+    def initialize(http_response, description)
+      @response    = http_response
+      @description = description
+    end
+
+    def to_s
+      "#{@response.code} #{@response.message} #{@description}"
+    end
+  end
+
+  class Client
+    attr_reader :root
+
+    def initialize(gom_root = 'http://gom')
+      @root = URI.parse(gom_root)
+    end
+
+    # returns nil but NOT raise error on non-existing attributes
+    def retrieve_val(path_or_uri)
+      (a = retrieve(path_or_uri)) && a[:attribute][:value]
+    end
+
+    def retrieve(path_or_uri, redirect_limit=10)
+      self.retrieve! path_or_uri, redirect_limit
+      rescue Gom::HttpError => e
+        return nil if e.response.code == "404"
+        raise e
+    end
+
+    def retrieve!(path_or_uri, redirect_limit=10)
+      uri      = path_or_uri.kind_of?(URI) ? path_or_uri : URI.parse("#{@root}#{path_or_uri}")
+      response = Net::HTTP.new(uri.host, uri.port).request_get(uri.path, {"Accept" => "application/json" })
+
+      begin
+        if response.kind_of?(Net::HTTPSuccess)
+          return JSON.parse(response.body, symbolize_names: true)
+        end
+      rescue StandardError => e
+        raise HttpError.new(response, "#{e} -- could not parse body: '#{response.body}'")
+      end
+
+      if (redirect_limit == 0 && response.kind_of?(Net::HTTPRedirection))
+        raise "too many redirects"
+      end
+
+      if response.kind_of?(Net::HTTPRedirection)
+        return Gom::retrieve(response['location'], redirect_limit - 1)
+      end
+
+      raise HttpError.new(response, "while GETting #{uri.path}")
+    end
+
+    # GOM API Change: Destroy will NOT return error on non-existing attributes
+    # or nodes. So no error will every be raised from this methods
+    def destroy!(path_or_uri)
+      uri      = path_or_uri.kind_of?(URI) ? path_or_uri  : URI.parse("#{@root}#{path_or_uri}")
+      response = Net::HTTP.new(uri.host, uri.port).delete(uri.path)
+
+      return true if response.kind_of?(Net::HTTPSuccess)
+      raise HttpError.new(response, "while DELETEing #{uri.path}")
+    end
+
+    def destroy(uri)
+      self.destroy! uri
+      rescue Gom::HttpError => e
+        return nil if e.response.code == "404"
+        raise e
+    end
+
+    def create!(path_or_uri, attributes={})
+      uri          = path_or_uri.kind_of?(URI) ? path_or_uri : URI.parse("#{@root}#{path_or_uri}")
+      request_body = attributes_to_xml attributes
+      headers      = { 'Content-Type' => 'application/xml' }
+      response     = Net::HTTP.new(uri.host, uri.port).request_post(uri.path, request_body, headers)
+
+      if response.kind_of?(Net::HTTPRedirection)
+        return URI.parse(response['location']).path
+      end
+
+      raise HttpError.new(response, "while CREATEing (#{uri.path})")
+    end
+
+    def update!(path_or_uri, hash_or_text=nil)
+      uri = path_or_uri.kind_of?(URI) ? path_or_uri : URI.parse("#{@root}#{path_or_uri}")
+
+      if is_attribute?(uri.path)
+          raise "update attribute call must include value" if hash_or_text.nil?
+          raise "update attribute value must be a string" unless hash_or_text.kind_of?(String)
+          response_format              = "text/plain"
+          if hash_or_text != ""
+            doc                          = REXML::Document.new
+            attr_node                    = doc.add_element 'attribute'
+            attr_node.attributes['type'] = 'string';
+            attr_node.text               = hash_or_text
+            request_body                 = doc.to_s
+            headers  = { 'Content-Type' => 'application/xml',
+                         'Accept'       => response_format }
+          else
+            request_body                 = "attribute=#{hash_or_text}&type=string"
+            headers  = { 'Content-Type' => 'application/x-www-form-urlencoded',
+                         'Accept'       => response_format }
+          end
+      else
+          raise "update node values must be a hash of attributes" unless hash_or_text.nil? or hash_or_text.kind_of?(Hash)
+          request_body = attributes_to_xml hash_or_text || {}
+          response_format = "application/json"
+          headers  = { 'Content-Type' => 'application/xml',
+                       'Accept'       => response_format }
+      end
+
+      #headers  = { 'Content-Type' => 'application/xml',
+      #             'Accept'       => response_format }
+
+      response = Net::HTTP.new(uri.host, uri.port).request_put(uri.path, request_body, headers)
+
+      return response.body if response.kind_of?(Net::HTTPSuccess) && response_format == "text/plain"
+      if response.kind_of?(Net::HTTPSuccess) && response_format == "application/json"
+        return JSON.parse(response.body, symbolize_names: true)
+      end
+      raise HttpError.new(response, "while PUTting #{uri.path}")
+    end
+    alias update update!
+
+    # supports stored and posted scripts
+    def run_script(options = {})
+      path   = options[:path]   || nil
+      script = options[:script] || nil
+      params = options[:params] || {}
+
+      if path.nil?
+        script.nil? and (raise ArgumentError, "must provide script OR path")
+      else
+        script and (raise ArgumentError, "must not provide script AND path")
+        params[:_script_path] = path
+      end
+
+      params = params.keys.zip(params.values).map {|k,v| "#{k}=#{v}"}
+      url = URI.parse("#{@root}/gom/script/v8?#{params.join('&')}")
+
+      response = Net::HTTP.start(url.host, url.port) do |http|
+        if script
+          request = Net::HTTP::Post.new(url.to_s)
+          request.set_content_type "text/javascript"
+          http.request(request, script)
+        else
+          request  = Net::HTTP::Get.new(url.to_s)
+          http.request(request)
+        end
+      end
+
+      if response.kind_of?(Net::HTTPSuccess)
+        return response
+      else
+        raise HttpError.new(
+          response, "while executing server-side-script:\n#{response.body}"
+        )
+      end
+    end
+
+    # supports anonymous and named observers
+    def register_observer(options={})
+      name         = options[:name]         || nil
+      callback_url = options[:callback_url] || nil
+      node         = options[:node]         || nil
+      filters      = options[:filters]      || {}
+      format       = options[:format]       || "application/json"
+
+      callback_url.nil? and (raise ArgumentError, "callback_url must not be nil")
+      node.nil? and (raise ArgumentError, "node must not be nil")
+      unless ['application/json', 'application/xml'].include?(format)
+        raise ArgumentError, "invalid format: '#{format}'"
+      end
+
+      url       = URI.parse("#{@root}/gom/observer#{node}")
+      form_data = { 'callback_url' => callback_url,
+                    'accept'       => format }
+      form_data.merge!(filters)
+
+      if name
+        observer_url = url.path.gsub(/\:/,'/')
+        my_uri       = "#{observer_url}/.#{name}"
+        destroy my_uri
+
+        form_data['observed_uri'] = "#{node}"
+        update(my_uri, form_data)
+      else
+        request = Net::HTTP::Post.new(url.path)
+        request.set_form_data(form_data)
+        response = Net::HTTP.new(url.host, url.port).start do |http|
+          http.request(request)
+        end
+        my_uri = URI.parse(response['location']).path
+      end
+      my_uri
+    end
+
+    private
+
+    def is_attribute?(the_path)
+      not the_path.index(":").nil?
+    end
+
+    def attributes_to_xml(hash={})
+      doc  = REXML::Document.new
+      node = doc.add_element 'node'
+      hash.each do |key, value|
+        attrib = node.add_element 'attribute'
+        attrib.attributes['name'] = key
+        attrib.text = value
+      end
+      doc.to_s
+    end
+  end
+end