majortom_connector 0.0.2 → 0.0.3

data/README.rdoc

@@ -4,40 +4,52 @@ This gem provides easy access to any MaJorToM-Server.
 
 == Requirements
 
-* HTTParty http://github.com/jnunemaker/httparty/ - For the HTTP requests.
+* JSON for ruby - http://flori.github.com/json/
 
 == Install
 
-* sudo gem install majortom_connector
-* Copy the majortom-server.yml from the examples folder into the config folder of your Rails app and configure it to your needs.
+* sudo gem install majortom_connector (mandatory)
+* Copy the majortom-server.yml from the examples folder into the config folder of your Rails app and configure it to your needs (optional).
 
 == Usage
 
+This documentation describes the use of majortom_connector version 0.0.3. 
+
 1. Before executing any request, you must connect to the server with
-     MajortomConnector.connect "base_iri_or_map_id"
-2. Start the topic map madness.
+     c = MajortomConnector.connect "base_iri_or_map_id"
+2. In case you did not provide and edit the config/majortom-server.yml you can configure the connector by calling
+     c.config.(host|port|context|api_key|map_id) = your_value
+3. Check the completeness of your configuration with
+     c.ready?
+   or check, whether the configured server actually responds with
+     c.established?
+4. Start the topic map madness.
    * Get the _id_ of the map you are connected with
-       MajortomConnector.topic_map_id
+       c.topic_map_id
    * Get all maps that are on the server
-       MajortomConnector.list_maps
+       c.list_maps
    * Find the id of a map with given base locator
-       MajortomConnector.find_topic_map_id_by_base_iri(base_iri)
+       c.find_topic_map_id_by_base_iri(base_iri)
    * Get all topics of the connected map*
-       MajortomConnector.topics
+       c.topics
    * Fire a TMQL query against the server*
-       MajortomConnector.tmql(query)
+       c.tmql(query)
    * Fire a SPARQL query against the server
-       MajortomConnector.sparql(query)
+       c.sparql(query)
    * Do a search in the fulltext index of the map that was created while loading
-       MajortomConnector.search(query)
-3. Have fun!
-
-Note: All methods (except those that just return ids) return a +Result+ object, that carries several values:
+       c.search(query)
+   * Receive an XTM or CTM serialization of your map with
+       c.to_xtm and c.to_ctm
+   * In case you want to clear the query cache, you can call
+       c.clear_cache
+5. Get your data from the connector by calling
+       data = c.request.result 
+The result object has several values:
+* +http_status+, +http_message+ and +http_body+ represent the data from the HTTP response
 * +code+ says, whether all went fine (if it's 0) or not
 * +message+ has a message from the server for you ('OK' or any error message)
 * +data+ contains the actual data that was returned from the server if no error occured
-* +jtmqr+ contains the JTMQR that comes with all methods marked with * above
 
-== Documentation
+== External documentation
 
 * You can find the JTMQR result format there: https://code.google.com/p/tmql/wiki/JTMQR

data/lib/majortom_connector/config.rb

@@ -0,0 +1,29 @@
+module MajortomConnector
+  class Config
+    
+    attr_accessor :host, :port, :context, :api_key, :map_id
+    
+    def initialize
+      load_server_config
+    end
+
+    def ready?
+      !(@host.blank? || @port.blank? || @context.blank? || @api_key.blank?)
+    end
+    
+    protected
+    
+    def load_server_config
+      begin
+        # Usual way of loading the configuration is from file.
+        file_config = YAML.load_file(File.join(::Rails.root, 'config', 'majortom-server.yml'))
+        @host = file_config['server']['host']
+        @port = file_config['server']['port']
+        @context = file_config['server']['context']
+        @api_key = file_config['user']['api_key']
+      rescue Exception
+        # Wow! The config file was not there!
+      end
+    end
+  end
+end

data/lib/majortom_connector/connector.rb

@@ -0,0 +1,65 @@
+module MajortomConnector
+  class Connector
+    
+    def initialize(id_or_base_iri)
+      return unless ready?
+      config.map_id = id_or_base_iri.match(/^http/) ? find_topic_map_id_by_base_iri(id_or_base_iri) : id_or_base_iri
+    end
+    
+    def topic_map_id
+      config.map_id ||= ""
+    end
+  
+    def list_maps
+      request.run('topicmaps') if ready?
+    end
+  
+    def find_topic_map_id_by_base_iri(base_iri)
+      request.run('resolvetm', base_iri).data if ready?
+    end
+  
+    def topics
+      request.run('topics') if ready?
+    end
+  
+    def tmql(query)
+      request.run('tmql', query) if ready?
+    end
+  
+    def sparql(query)
+      request.run('sparql', query) if ready?
+    end
+  
+    def search(query = "")
+      request.run('beru', query) if ready?
+    end
+  
+    def to_xtm
+      request.run('xtm') if ready?
+    end
+  
+    def to_ctm
+      request.run('ctm') if ready?
+    end
+    
+    def clear_cache
+      request.run('clearcache') if ready?
+    end
+  
+    def ready?
+      config.ready?
+    end
+    
+    def established?
+      ready? && request.run('connectiontest').code == "0"
+    end
+    
+    def request
+      @request ||= Request.new(config)
+    end
+  
+    def config
+      @config ||= Config.new
+    end
+  end
+end

data/lib/majortom_connector/request.rb

@@ -1,83 +1,82 @@
-require 'httparty'
-require 'net/http'
-
 module MajortomConnector
   class Request
-
-    AVAILABLE_COMMANDS = [
-      "topics",
-      "topicmaps",
-      "resolvetm",
-      "xtm",
-      "ctm",
-      "tmql",
-      "sparql",
-      "beru",
-      "clearcache"
-    ]
+    
+    AVAILABLE_COMMANDS = {
+      'topics' => 'topics',
+      'topicmaps' => 'list_maps',
+      'resolvetm' => 'find_topic_map_id_by_base_iri',
+      'xtm' => 'to_xtm',
+      'ctm' => 'to_ctm',
+      'tmql' => 'tmql',
+      'sparql' => 'sparql',
+      'beru' => 'search',
+      'clearcache' => 'clear_cache',
+      'connectiontest' => 'established?'
+    }
 
     attr_reader :result
 
-    def self.call(config, command, query)
-      new(config).run(command, query)
-    end
-
+    
     def self.available_commands
       AVAILABLE_COMMANDS
     end
 
     def self.command_available?(command)
-      available_commands.include?(command)
+      available_commands.keys.include?(command)
     end
 
     def initialize(config)
-      @mts_config = config
+      @config = config
     end
 
     def run(command, param = "")
-      raise ArgumentError, "Command #{command} not available. Try one of the following: #{MajortomConnector::Request.available_commands.join(', ')}" unless self.class.command_available?(command)
-      @mts_result = Result.new
+      raise ArgumentError, "Command #{MajortomConnector::Request.available_commands[command]} not available. Try one of the following: #{MajortomConnector::Request.available_commands.values.join(', ')}" unless self.class.command_available?(command)
+      @result = Result.new
       post(command, param) if %w[tmql sparql beru].include?(command)
       get(command, param) if %w[topics topicmaps resolvetm clearcache].include?(command)
       stream(command) if %w[xtm ctm].include?(command)
-      return @mts_result
+      test if %w[connectiontest].include?(command)
+      return @result
     end
 
     def successful?
-      @mts_result.successful?
+      @result.result_successful?
     end
-
-    protected
-
+    
     def get(command, query = "")
-      @mts_result.parse(HTTParty.get("#{server_uri}/tm/#{command}#{parameter_builder(command, query)}"))
+      @result.parse(Net::HTTP.get_response(URI.parse("#{server_uri}/tm/#{command}#{parameter_builder(command, query)}")))
     end
 
     def post(command, query)
-      post_options = {:body => {:query => query, :apikey => @mts_config['user']['api_key']}}
-      @mts_result.parse(HTTParty.post("#{server_uri}/tm/#{command}/#{@mts_config['map']['id']}/", post_options))
+      @result.parse(Net::HTTP.post_form(URI.parse("#{server_uri}/tm/#{command}/#{@config.map_id}/"), {:query => query, :apikey => @config.api_key}))
     end
 
     def stream(command)
       buffer = ""
-      response = Net::HTTP.get_response(URI.parse("#{@mts_config['server']['host']}:#{@mts_config['server']['port']}/#{@mts_config['server']['context']}/tm/#{command}/#{@mts_config['map']['id']}?apikey=#{@mts_config['user']['api_key']}")) do |response|
-        response.read_body do |segment|
+      response = Net::HTTP.get_response(URI.parse("#{server_uri}/tm/#{command}/#{@config.map_id}?apikey=#{@config.api_key}")) do |res|
+        res.read_body do |segment|
           buffer << segment
         end
       end
-      @mts_result.parse({'code' => response.code, 'msg' => response.message, 'data' => buffer})
+      @result.parse(response, command, buffer)
+    end
+
+    def test
+      @result.parse(Net::HTTP.get_response(URI.parse("#{server_uri}/")), 'html')
     end
 
+    protected
+
     def server_uri
-      "#{@mts_config['server']['host']}:#{@mts_config['server']['port']}/#{@mts_config['server']['context']}"
+      "#{@config.host}:#{@config.port}/#{@config.context}"
     end
 
     def parameter_builder(command, query = "")
       parameter = case command
-      when 'topics', 'clearcache' then "/#{@mts_config['map']['id']}?"
+      when 'topics', 'clearcache' then "/#{@config.map_id}?"
       when 'resolvetm' then "?bl=#{query}&"
       else "?"
-      end << "apikey=#{@mts_config['user']['api_key']}"
+      end << "apikey=#{@config.api_key}"
     end
   end
 end

data/lib/majortom_connector/result.rb

@@ -1,43 +1,43 @@
+require 'json'
+
 module MajortomConnector
   class Result
 
-    attr_reader :code
+    attr_reader :http_status
+    attr_reader :http_message
+    attr_reader :http_body
 
+    attr_reader :code
     attr_reader :message
-
     attr_reader :data
     
-    attr_reader :jtmqr
-    
-    def successful?
+    def request_successful?
+      @http_status == "200" ? true : false
+    end
+
+    def response_successful?
       @code == "0" ? true : false
     end
     
-    def parse (result)
-      @code = %w[0 200].include?(result['code']) ? "0" : result['code']  
-      @message = result['msg']
-      @data = @code == "0" ? result['data'] : "" 
-      
-      if @data.kind_of?(Hash) && @data.has_key?('version')
-        send("handle_jtmqr_v#{@data['version'].to_i}")
-      end
-    end
+    def parse(response, format = "", buffer = nil)
+      @http_status = response.code
+      @http_message = response.message
+      @http_body = response.read_body
 
-    protected
-    
-    def handle_jtmqr_v1
-      @jtmqr = Array.new
-      @data['seq'].each do |tupel|
-        cells = Array.new
-        tupel['t'].each do |c|
-          cells << c[c.keys.first]
-        end
-        @jtmqr << cells
+      return unless @http_status == "200"
+      
+      case format
+      when 'xtm', 'ctm'
+        @code = "0"
+        @data = buffer
+      when 'html'
+        @code = "0"
+      else
+        json = JSON.parse(@http_body)
+        @data = json['data']
+        @code = json['code']
+        @message = json['msg']
       end
     end
-    
-    def handle_jtmqr_v2
-      # JTMQR v2 is currently not supported by MaJorToM-Server
-    end
   end
 end

data/lib/majortom_connector/version.rb

@@ -1,3 +1,3 @@
 module MajortomConnector
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/majortom_connector.rb

@@ -1,68 +1,12 @@
-require 'pathname'
-
-dir = Pathname(__FILE__).dirname.expand_path
-
-require dir + 'majortom_connector/result'
-require dir + 'majortom_connector/request'
+require 'majortom_connector/config'
+require 'majortom_connector/connector'
+require 'majortom_connector/result'
+require 'majortom_connector/request'
 
 module MajortomConnector
+  
   def self.connect(id_or_base_iri = "")
     raise ArgumentError, 'Parameter must not be blank' if id_or_base_iri.blank?
-    id = id_or_base_iri.match(/^http/) ? find_topic_map_id_by_base_iri(id_or_base_iri) : id_or_base_iri
-    config.merge!({'map' => {'id' => id}})
-  end
-
-  def self.topic_map_id
-    config['map']['id'] ||= ""
-  end
-
-  def self.list_maps
-    request.run('topicmaps')
-  end
-
-  def self.find_topic_map_id_by_base_iri(base_iri)
-    request.run('resolvetm', base_iri).data
-  end
-
-  def self.topics
-    request.run('topics')
-  end
-
-  def self.tmql(query)
-    request.run('tmql', query)
-  end
-
-  def self.sparql(query)
-    request.run('sparql', query)
-  end
-
-  def self.search(query = "")
-    request.run('beru', query)
-  end
-
-  def self.to_xtm
-    request.run('xtm')
-  end
-
-  def self.to_ctm
-    request.run('ctm')
-  end
-  
-  def self.clear_cache
-    request.run('clearcache')
-  end
-
-  protected
-  
-  def self.request
-    @mts_request ||= Request.new(config)
-  end
-
-  def self.config
-    @mts_config ||= load_server_config
-  end
-
-  def self.load_server_config
-    YAML.load_file(File.join(::Rails.root, 'config', 'majortom-server.yml'))
+    connector = Connector.new(id_or_base_iri)
   end
 end

data/majortom_connector.gemspec

@@ -19,6 +19,5 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
-  s.add_dependency('httparty', '>= 0.7.4')
-  s.post_install_message = %q{You have successfully installed the majortom_connector gem. Don't forget to put the majortom-server.yml into rails' config folder.}
+  s.add_dependency('json', '>= 1.5.1')
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: majortom_connector
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Sven Windisch
@@ -15,23 +15,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-14 00:00:00 +02:00
+date: 2011-04-17 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: httparty
+  name: json
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 11
+        hash: 1
         segments: 
-        - 0
-        - 7
-        - 4
-        version: 0.7.4
+        - 1
+        - 5
+        - 1
+        version: 1.5.1
   type: :runtime
   version_requirements: *id001
 description: Provides easy and configurable access to MaJorToM-Server data stores.
@@ -51,6 +51,8 @@ files:
 - Rakefile
 - examples/majortom-server.yml
 - lib/majortom_connector.rb
+- lib/majortom_connector/config.rb
+- lib/majortom_connector/connector.rb
 - lib/majortom_connector/request.rb
 - lib/majortom_connector/result.rb
 - lib/majortom_connector/version.rb
@@ -59,7 +61,7 @@ has_rdoc: true
 homepage: https://github.com/semantosoph/majortom_connector
 licenses: []
 
-post_install_message: You have successfully installed the majortom_connector gem. Don't forget to put the majortom-server.yml into rails' config folder.
+post_install_message: 
 rdoc_options: []
 
 require_paths: