ken 0.1.2

data/lib/ken/property.rb

@@ -0,0 +1,91 @@
+module Ken
+  class Property
+    
+    include Extlib::Assertions
+    
+    VALUE_TYPES = %w{
+     /type/id
+     /type/int
+     /type/float
+     /type/boolean
+     /type/text
+     /type/rawstring
+     /type/uri
+     /type/datetime
+     /type/key
+    }
+    
+    # initializes a resource by json result
+    def initialize(data, type)
+      assert_kind_of 'data', data, Hash
+      assert_kind_of 'type', type, Ken::Type
+      @data, @type = data, type
+    end
+    
+    # property id
+    # @api public
+    def id
+      @data["id"]
+    end
+    
+    # property name
+    # @api public
+    def name
+      @data["name"]
+    end
+    
+    # @api public
+    def to_s
+      name || id || ""
+    end
+    
+    # @api public
+    def inspect
+      result = "#<Property id=\"#{id}\" expected_type=\"#{expected_type || "nil"}\" unique=\"#{unique?}\" object_type=\"#{object_type?}\">"
+    end
+    
+    # returns the type of which the property is a part of
+    # every property always has exactly one type.
+    # that's why /type/property/schema is a unique property
+    # @api public
+    def type
+      @type
+    end
+    
+    # reverse property, which represent incoming links
+    # @api public
+    def reverse_property
+      @data["reverse_property"]
+    end
+    
+    # master property, which represent an outgoing link (or primitive value)
+    # @api public
+    def master_property
+      @data["master_property"]
+    end
+    
+    # returns true if the property is unique
+    # @api public
+    def unique?
+      return @data["unique"]==true
+    end
+    
+    # returns true if the property is an object type
+    # @api public
+    def object_type?
+      !value_type?
+    end
+    
+    # returns true if the property is a value type
+    # @api public
+    def value_type?
+      VALUE_TYPES.include?(expected_type)
+    end
+    
+    # type, which attribute values of that property are expected to have
+    # @api public
+    def expected_type
+      @data["expected_type"]
+    end
+  end
+end

data/lib/ken/resource.rb

@@ -0,0 +1,151 @@
+module Ken
+  class Resource
+    include Extlib::Assertions
+    
+    attr_reader :data
+    
+    # initializes a resource using a json result
+    def initialize(data)
+      assert_kind_of 'data', data, Hash
+      @schema_loaded, @attributes_loaded, @data = false, false, data
+      @data_fechted = data["/type/reflect/any_master"] != nil
+    end
+    
+    # resource id
+    # @api public
+    def id
+      @data["id"] || ""
+    end
+    
+    # resource guid
+    # @api public
+    def guid
+      @data['guid'] || ""
+    end
+    
+    # resource name
+    # @api public
+    def name
+      @data["name"] || ""
+    end
+    
+    # @api public
+    def to_s
+      name || id || ""
+    end
+    
+    # @api public
+    def inspect
+      result = "#<Resource id=\"#{id}\" name=\"#{name || "nil"}\">"
+    end
+    
+    # returns all assigned types
+    # @api public
+    def types
+      load_schema! unless schema_loaded?
+      @types
+    end
+    
+    # returns all available views based on the assigned types
+    # @api public
+    def views
+      @views ||= Ken::Collection.new(types.map { |type| Ken::View.new(self, type) })
+    end
+    
+    # returns individual view based on the requested type id
+    # @api public
+    def view(type)
+      views.each { |v| return v if v.type.id =~ /^#{Regexp.escape(type)}$/}
+      nil
+    end
+    
+    # returns individual type based on the requested type id
+    # @api public
+    def type(type)
+      types.each { |t| return t if t.id =~ /^#{Regexp.escape(type)}$/}
+      nil
+    end
+
+    # returns all the properties from all assigned types
+    # @api public
+    def properties
+      @properties = Ken::Collection.new
+      types.each do |type|
+        @properties.concat(type.properties)
+      end
+      @properties
+    end
+    
+    # returns all attributes for every type the resource is an instance of
+    # @api public
+    def attributes
+      load_attributes! unless attributes_loaded?
+      @attributes.values
+    end
+    
+    # search for an attribute by name and return it
+    # @api public
+    def attribute(name)
+      attributes.each { |a| return a if a.property.id == name }
+      nil
+    end
+    
+    # returns true if type information is already loaded
+    # @api public
+    def schema_loaded?
+      @schema_loaded
+    end
+    
+    # returns true if attributes are already loaded
+    # @api public
+    def attributes_loaded?
+      @attributes_loaded
+    end
+    # returns true if json data is already loaded
+    # @api public
+    def data_fetched?
+      @data_fetched
+    end
+    
+    private
+    # executes the fetch data query in order to load the full set of types, properties and attributes
+    # more info at http://lists.freebase.com/pipermail/developers/2007-December/001022.html
+    # @api private
+    def fetch_data
+      return @data if @data["/type/reflect/any_master"]
+      @data = Ken.session.mqlread(FETCH_DATA_QUERY.merge!(:id => id))
+    end
+    
+    # loads the full set of attributes using reflection
+    # information is extracted from master, value and reverse attributes
+    # @api private
+    def load_attributes!
+      fetch_data unless data_fetched?
+      # master & value attributes
+      raw_attributes = Ken::Util.convert_hash(@data["/type/reflect/any_master"])
+      raw_attributes.merge!(Ken::Util.convert_hash(@data["/type/reflect/any_value"]))
+      @attributes = {}
+      raw_attributes.each_pair do |a, d|
+        properties.select { |p| p.id == a}.each do |p|
+          @attributes[p.id] = Ken::Attribute.create(d, p)
+        end
+      end
+      # reverse properties
+      raw_attributes = Ken::Util.convert_hash(@data["/type/reflect/any_reverse"])
+      raw_attributes.each_pair do |a, d|
+        properties.select { |p| p.master_property == a}.each do |p|
+          @attributes[p.id] = Ken::Attribute.create(d, p)
+        end
+      end
+      @attributes_loaded = true
+    end
+    
+    # loads the resource's metainfo
+    # @api private
+    def load_schema!
+      fetch_data unless data_fetched?
+      @types = Ken::Collection.new(@data["ken:type"].map { |type| Ken::Type.new(type) })
+      @schema_loaded = true
+    end
+  end # class Resource
+end # module Ken

data/lib/ken/session.rb

@@ -0,0 +1,129 @@
+module Ken
+  class << self
+    attr_accessor :session
+  end
+  
+  # A class for returing errors from the freebase api.
+  # For more infomation see the freebase documentation:
+  class ReadError < ArgumentError
+    attr_accessor :code, :msg
+    def initialize(code,msg)
+      self.code = code
+      self.msg = msg
+    end
+    def message
+      "#{code}: #{msg}"
+    end
+  end
+  
+  class AttributeNotFound < StandardError ; end
+  class PropertyNotFound < StandardError ; end
+  class ResourceNotFound < StandardError ; end
+  class ViewNotFound < StandardError ; end
+  
+  # partially taken from chris eppstein's freebase api
+  # http://github.com/chriseppstein/freebase/tree
+  class Session
+    public
+    # Initialize a new Ken Session
+    #   Ken::Session.new(host{String, IO}, username{String}, password{String})
+    #
+    # @param host<String>          the API host
+    # @param username<String>      freebase username
+    # @param password<String>      user password
+    def initialize(host, username, password)
+      @host = host
+      @username = username
+      @password = password
+      
+      Ken.session = self
+
+      # TODO: check connection
+      Ken.logger.info("connection established.")
+    end
+    
+    SERVICES = {
+      :mqlread => '/api/service/mqlread',
+      :mqlwrite => '/api/service/mqlwrite',
+      :login => '/api/account/login',
+      :upload => '/api/service/upload'
+    }
+
+    # get the service url for the specified service.
+    def service_url(svc)
+      "#{@host}#{SERVICES[svc]}"
+    end
+
+    SERVICES.each_key do |k|
+      define_method("#{k}_service_url") do
+        service_url(k)
+      end
+    end
+
+    # raise an error if the inner response envelope is encoded as an error
+    def handle_read_error(inner)
+      unless inner['code'][0, '/api/status/ok'.length] == '/api/status/ok'
+        Ken.logger.error "Read Error #{inner.inspect}"
+        error = inner['messages'][0]
+        raise ReadError.new(error['code'], error['message'])
+      end
+    end # handle_read_error
+
+    # Perform a mqlread and return the results
+    # Specify :cursor => true to batch the results of a query, sending multiple requests if necessary.
+    # TODO: should support multiple queries
+    #       you should be able to pass an array of queries
+    def mqlread(query, options = {})
+      Ken.logger.info ">>> Sending Query: #{query.to_json}"
+      cursor = options[:cursor]
+      if cursor
+        query_result = []
+        while cursor
+          response = get_query_response(query, cursor)
+          query_result += response['result']
+          cursor = response['cursor']
+        end
+      else
+        response = get_query_response(query, cursor)
+        cursor = response['cursor']
+        query_result = response['result']
+      end
+      query_result
+    end
+
+    protected
+    # returns parsed json response from freebase mqlread service
+    def get_query_response(query, cursor=nil)
+      envelope = { :qname => {:query => query }}
+      envelope[:qname][:cursor] = cursor if cursor
+      
+      response = http_request mqlread_service_url, :queries => envelope.to_json
+      
+      result = JSON.parse response
+      
+      inner = result['qname']
+      handle_read_error(inner)
+      Ken.logger.info "<<< Received Response: #{inner['result'].inspect}"
+      inner
+    end
+    
+    # encode parameters
+    def params_to_string(parameters)
+      parameters.keys.map {|k| "#{URI.encode(k.to_s)}=#{URI.encode(parameters[k])}" }.join('&')
+    end
+    
+    # does the dirty work
+    def http_request(url, parameters = {})
+      params = params_to_string(parameters)
+      url << '?'+params unless params !~ /\S/
+
+      return Net::HTTP.get_response(::URI.parse(url)).body
+      
+      fname = "#{MD5.md5(params)}.mql"
+      open(fname,"w") do |f|
+        f << response
+      end
+      Ken.logger.info("Wrote response to #{fname}")
+    end
+  end # class Session
+end # module Ken

data/lib/ken/type.rb

@@ -0,0 +1,53 @@
+module Ken
+  class Type
+    
+    include Extlib::Assertions
+    
+    # initializes a resource using a json result
+    def initialize(data)
+      assert_kind_of 'data', data, Hash
+      @data = data
+    end
+    
+    # access property info
+    # @api public
+    def properties
+      @properties ||= Ken::Collection.new(@data["properties"].map { |property| Ken::Property.new(property, self) })
+    end
+    
+    # type id
+    # @api public
+    def id
+      @data["id"]
+    end
+    
+    # type name
+    # @api public
+    def name
+      @data["name"]
+    end
+    
+    # @api public
+    def to_s
+      name || id || ""
+    end
+    
+    # @api public
+    def inspect
+      result = "#<Type id=\"#{id}\" name=\"#{name || "nil"}\">"
+    end
+    
+    # delegate to property_get
+    def method_missing sym
+      property_get(sym.to_s)
+    end
+    
+    private
+    # @api private
+    # search for a property by name and return it
+    def property_get(name)
+      properties.each { |p| return p if p.id =~ /\/#{name}$/ }
+      raise PropertyNotFound
+    end
+  end
+end

data/lib/ken/util.rb

@@ -0,0 +1,18 @@
+module Ken
+  module Util
+    # magic hash conversion
+    def convert_hash(source)
+      source.inject({}) do |result, item|
+        if result[item["link"]]
+          result[item["link"]] << { "id" => item["id"], "name" => item["name"], "value" => item["value"] }
+        else
+          result[item["link"]] = []
+          result[item["link"]] << { "id" => item["id"], "name" => item["name"], "value" => item["value"] }
+        end
+        result
+      end
+    end
+    module_function :convert_hash
+  end
+end
+

data/lib/ken/view.rb

@@ -0,0 +1,56 @@
+# provides an interface to view a resource as a specific type
+# provides an interface for working with attributes, properties
+module Ken
+  class View
+    
+    include Extlib::Assertions
+    
+    # initializes a resource by json result
+    def initialize(resource, type)
+      assert_kind_of 'resource', resource, Ken::Resource
+      assert_kind_of 'type', type, Ken::Type
+      @resource, @type = resource, type
+    end
+    
+    # @api public
+    def to_s
+      @type.to_s
+    end
+    
+    # return correspondent type
+    # @api public
+    def type
+      @type
+    end
+    
+    # @api public
+    def inspect
+      result = "#<View type=\"#{type.id || "nil"}\">"
+    end
+    
+    # returns attributes which are member of the view's type
+    # @api public
+    def attributes
+      @resource.attributes.select { |a| a.property.type == @type}
+    end
+    
+    # search for an attribute by name and return it
+    # @api public
+    def attribute(name)
+      attributes.each { |a| return a if a.property.id =~ /\/#{name}$/ }
+      nil
+    end
+    
+    # returns properties which are member of the view's type    
+    # @api public
+    def properties
+      @resource.properties.select { |p| p.type == @type}
+    end
+    
+    # delegate to attribute
+    def method_missing sym
+      attribute(sym.to_s)
+    end
+    
+  end
+end