kalimba 0.0.1

data/lib/kalimba/exceptions.rb

@@ -0,0 +1,18 @@
+module Kalimba
+  class KalimbaError < StandardError; end
+  class UnknownAttributeError < KalimbaError; end
+  class AttributeAssignmentError < KalimbaError
+    attr_reader :exception, :attribute
+    def initialize(message, exception, attribute)
+      @exception = exception
+      @attribute = attribute
+      @message = message
+    end
+  end
+  class MultiparameterAssignmentErrors < KalimbaError
+    attr_reader :errors
+    def initialize(errors)
+      @errors = errors
+    end
+  end
+end

data/lib/kalimba/localized_attributes.rb

@@ -0,0 +1,36 @@
+require "active_support/concern"
+
+module Kalimba
+  # This module handles localized literals of RDF such that:
+  #   1. they are presented as normal "single" attributes,
+  #   2. storing the attribute in the same language overwrites
+  #      only the attribute value in that language and does not
+  #      delete this attribute values in other languages,
+  module LocalizedAttributes
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def localizable_property?(name)
+        !properties[name][:collection] && properties[name][:datatype] == NS::XMLSchema["string"]
+      end
+    end
+
+    def retrieve_localizable_property(name, predicate)
+      localized_names = send "localized_#{name.pluralize}"
+      Kalimba.repository.statements.each(:subject => subject, :predicate => predicate) do |statement|
+        value = statement.object.value
+        lang = value.respond_to?(:lang) ? value.lang : nil
+        localized_names[lang] = value
+      end
+      localized_names[I18n.locale] || localized_names[nil]
+    end
+
+    def store_localizable_property(name, value, predicate, datatype)
+      localized_names = send "localized_#{name.pluralize}"
+      lang = value.respond_to?(:lang) ? value.lang : nil
+      localized_names.merge!(lang => value).all? do |_, v|
+        store_single_value(v, predicate, datatype)
+      end
+    end
+  end
+end

data/lib/kalimba/persistence.rb

@@ -0,0 +1,225 @@
+require "securerandom"
+require "active_support/concern"
+
+module Kalimba
+  # @abstract
+  #   Backend implementations should override all methods
+  #   that delegate processing to their parent class (invoking "super").
+  module Persistence
+    extend ActiveSupport::Concern
+
+    class << self
+      # Create an instance of the backend storage (repository)
+      #
+      # @param [Hash] options backend storage options
+      # @return [Any] instance of the backend storage
+      def repository(options = {})
+        raise NotImplementedError
+      end
+
+      # Module of the persistence backend
+      #
+      # @return [Module]
+      def backend
+        self
+      end
+
+      def logger
+        @logger ||= defined?(::Rails) && ::Rails.logger
+      end
+    end
+
+    module ClassMethods
+      # Create a new instance of RDFS class
+      #
+      # @param [Hash<Symbol, String> => Any] attributes
+      # @return [Resource, nil]
+      def create(attributes = {})
+        raise NotImplementedError
+      end
+
+      # Check whether instances of the RDFS class exist in the repository
+      #
+      # @param [Hash<[Symbol, String] => Any>] attributes
+      # @return [Boolean]
+      def exist?(attributes = {})
+        raise NotImplementedError
+      end
+
+      # Remove all instances of the RDFSClass from the repository
+      #
+      # @return [Boolean]
+      def destroy_all
+        raise NotImplementedError
+      end
+
+      def find(scope, options = {})
+        case scope
+        when :first
+          find_each(options.merge(:limit => 1)).first
+        when :all
+          find_each(options).to_a
+        else
+          find_by_id(scope)
+        end
+      end
+
+      def find_by_id(id_value)
+        raise NotImplementedError
+      end
+
+      def find_each(options = {})
+        raise NotImplementedError
+      end
+
+      def first(options = {})
+        find(:first, options)
+      end
+
+      def all(options = {})
+        find(:all, options)
+      end
+
+      def count(attributes = {})
+        raise NotImplementedError
+      end
+
+      def logger
+        Kalimba::Persistence.logger
+      end
+    end
+
+    def id
+      subject && subject.fragment
+    end
+
+    # Check whether the model has never been persisted
+    #
+    # @return [Boolean]
+    def new_record?
+      raise NotImplementedError
+    end
+
+    # Check whether the model has ever been persisted
+    #
+    # @return [Boolean]
+    def persisted?
+      raise NotImplementedError
+    end
+
+    # Check whether the model has been destroyed
+    # (remove from the storage)
+    #
+    # @return [Boolean]
+    def destroyed?
+      @destroyed
+    end
+
+    # Retrieve model attributes from the backend storage
+    #
+    # @return [self]
+    def reload
+      raise NotImplementedError
+    end
+
+    # Remove the resource from the backend storage
+    #
+    # @return [Boolean]
+    def destroy
+      @destroyed = true
+      freeze
+    end
+
+    # Assign attributes from the given hash and persist the model
+    #
+    # @param [Hash<[Symbol, String] => Any>] params
+    # @return [Boolean]
+    def update_attributes(params = {})
+      assign_attributes(params)
+      save
+    end
+
+    # Persist the model into the backend storage
+    #
+    # @raise [Kalimba::KalimbaError] if fails to obtain the subject for a new record
+    # @return [Boolean]
+    def save(options = {})
+      @previously_changed = changes
+      @changed_attributes.clear
+      true
+    end
+
+    def logger
+      self.class.logger
+    end
+
+    private
+
+    def read_attribute(name, *args)
+      value = attributes[name]
+      if value.nil?
+        self.class.properties[name][:collection] ? [] : nil
+      else
+        value
+      end
+    end
+    alias_method :attribute, :read_attribute
+
+    def write_attribute(name, value)
+      attribute_will_change!(name) unless value == attributes[name]
+      attributes[name] = value
+    end
+
+    # Overridden implementation should return URI for the subject, generated by
+    # using specific random/default/sequential URI generation capabilities.
+    # Otherwise it should return nil.
+    #
+    # @raise [Kalimba::KalimbaError] if cannot generate subject URI
+    # @return [URI, nil]
+    def generate_subject
+      if self.class.base_uri
+        s = self.class.base_uri.dup
+        s.fragment = SecureRandom.urlsafe_base64
+        s
+      else
+        raise Kalimba::KalimbaError, "Cannot generate subject without a base URI"
+      end
+    end
+
+    def type_cast_to_rdf(value, datatype)
+      if value.respond_to?(:to_rdf)
+        value.to_rdf
+      else
+        if XmlSchema.datatype_of(value) == datatype
+          value
+        else
+          v = XmlSchema.instantiate(value.to_s, datatype) rescue nil
+          !v.nil? && XmlSchema.datatype_of(v) == datatype ? v : nil
+        end
+      end
+    end
+
+    def type_cast_from_rdf(value, datatype)
+      if value.is_a?(URI)
+        klass = Kalimba::Resource.from_datatype(datatype)
+        if klass
+          klass.for(value.fragment)
+        else
+          anonymous_class_from(value, datatype).for(value.fragment)
+        end
+      else
+        value
+      end
+    end
+
+    def anonymous_class_from(uri, datatype)
+      (uri = uri.dup).fragment = nil
+      Class.new(Kalimba::Resource).tap do |klass|
+        klass.class_eval do
+          base_uri uri
+          type datatype
+        end
+      end
+    end
+  end
+end

data/lib/kalimba/railtie.rb

@@ -0,0 +1,11 @@
+module Kalimba
+  class Railtie < Rails::Railtie
+    initializer "kalimba.initialize_database" do |app|
+      Kalimba.set_repository_options app.config.database_configuration[Rails.env]
+    end
+
+    rake_tasks do
+      load "kalimba/railties/repository.rake"
+    end
+  end
+end

data/lib/kalimba/railties/repository.rake

@@ -0,0 +1,7 @@
+desc "Create RDF storage"
+namespace :db do
+  task :setup do
+    options = Rails.configuration.database_configuration[Rails.env] || {}
+    Kalimba::Persistence.repository(options.merge(:new => true))
+  end
+end

data/lib/kalimba/reflection.rb

@@ -0,0 +1,54 @@
+# Enables "association-like" behaviour that many
+# Rails-dependent gems rely upon.
+#
+# The content is mostly copied from ActiveRecord::Reflection
+#
+module Kalimba
+  module Reflection
+    def reflections
+      @reflections ||= {}
+    end
+
+    def create_reflection(name, params = {})
+      reflections[name] = AssociationReflection.new(name, {class_name: params[:datatype]})
+    end
+
+    def reflect_on_association(association)
+      reflections[association].is_a?(AssociationReflection) ? reflections[association] : nil
+    end
+
+    class AssociationReflection
+      attr_reader :macro, :name, :options
+
+      def initialize(name, options = {})
+        # only :has_many macro is available for RDF
+        # (Sets, Bags and Unions are thus "downgraded" to it)
+        @macro = :has_many
+        @name = name
+        @options = options
+      end
+
+      # Returns the class for the macro.
+      #
+      # <tt>composed_of :balance, :class_name => 'Money'</tt> returns the Money class
+      # <tt>has_many :clients</tt> returns the Client class
+      def klass
+        @klass ||= class_name.constantize
+      end
+
+      # Returns the class name for the macro.
+      #
+      # <tt>composed_of :balance, :class_name => 'Money'</tt> returns <tt>'Money'</tt>
+      # <tt>has_many :clients</tt> returns <tt>'Client'</tt>
+      def class_name
+        @class_name ||= (options[:class_name] || derive_class_name).to_s
+      end
+
+      private
+
+      def derive_class_name
+        name.to_s.singularize.camelize
+      end
+    end
+  end
+end

data/lib/kalimba/resource.rb

@@ -0,0 +1,266 @@
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/class/subclasses"
+require "kalimba/persistence" # fallback to abstract backend
+require "kalimba/validations"
+require "kalimba/callbacks"
+require "kalimba/reflection"
+require "kalimba/attribute_assignment"
+require "kalimba/localized_attributes"
+
+module Kalimba
+  class Resource
+    include ActiveModel::AttributeMethods
+    include ActiveModel::Dirty
+    include ActiveModel::Conversion
+
+    extend Kalimba::Reflection
+    include Kalimba::AttributeAssignment
+    include Kalimba::LocalizedAttributes
+
+    include Kalimba::Persistence.backend
+
+    # Subject URI if the resource
+    attr_reader :subject
+
+    # Hash{String => any} with the resource attributes
+    #
+    # @note
+    #   Do not modify it directly, unless you know what you are doing!
+    attr_accessor :attributes
+
+    # Properties with their options
+    #
+    # @return [Hash{String => Hash}]
+    class_attribute :properties, instance_writer: false, instance_reader: false
+    self.properties = {}
+
+    class << self
+      # Create a new record with the given subject URI
+      #
+      # @note
+      #   In the world of RDF a resource cannot be instantly defined as "new",
+      #   because any arbitrary subject that you specify might be already present
+      #   in the storage.
+      #   So you can use ID of an existing resource as well.
+      #
+      #   Don't forget to {#reload} the resource, if you need its actual attributes
+      #   (if any) pulled from the storage.
+      #
+      # @note
+      #   The resource ID that you supply will be added as an URI
+      #   fragment to base_uri (or raise an error if base_uri is not defined).
+      #
+      # @param [String] rid ID to use for the resource
+      # @param [Hash<[Symbol, String] => Any>] params (see {RDFSResource#initialize})
+      # @return [Object] instance of the model
+      def for(rid, params = {})
+        new(params.merge(:_subject => rid))
+      end
+
+      # Type URI of RDFS class
+      #
+      # @note Can be set only once
+      #
+      # @param [URI, String] uri
+      # @return [URI]
+      def type(uri = nil)
+        if uri
+          @type ||= URI(uri)
+        else
+          @type
+        end
+      end
+
+      # Base URI for the resource
+      #
+      # @param [String, URI] uri
+      # @return [URI]
+      def base_uri(uri = nil)
+        @base_uri ||= uri && URI(uri.to_s.sub(/\/?$/, "/"))
+      end
+
+      # Property declaration
+      #
+      # Model attributes should be declared using `property`.
+      # Two mandatory parameters are `:predicate` and `:datatype`,
+      # that can accept URIs as URI or String objects.
+      # You can also use "NS::" namespaces provided by `xml_schema` gem.
+      #
+      # @param [Symbol, String] name
+      # @param [Hash] params
+      # @option params [String, URI] :predicate
+      # @option params [String, URI, Symbol] :datatype
+      # @option params [Boolean] :collection
+      # @return [void]
+      def property(name, params = {})
+        name = name.to_s
+
+        params[:predicate] = URI(params[:predicate])
+        association = Kalimba::Resource.from_datatype(params[:datatype])
+        if association
+          params[:datatype] = association.type
+          class_eval <<-HERE, __FILE__, __LINE__
+            def #{name}_id
+              self.#{name}.try(:id)
+            end
+
+            def #{name}_id=(value)
+              self.#{name} = value.blank? ? nil : #{association}.for(value)
+            end
+          HERE
+        else
+          params[:datatype] = URI(params[:datatype])
+        end
+
+        define_collection(name, params) if params[:collection]
+
+        self.properties[name] = params
+
+        define_attribute_method name if self.is_a?(Class)
+
+        class_eval <<-HERE, __FILE__, __LINE__
+          def #{name}=(value)
+            write_attribute "#{name}", value
+          end
+        HERE
+
+        if localizable_property?(name)
+          class_eval <<-HERE, __FILE__, __LINE__
+            def localized_#{name.pluralize}
+              @localized_#{name.pluralize} ||= {}
+            end
+          HERE
+        end
+      end
+
+      # Collection definition
+      #
+      # "Has-many" relations/collections are declared with help of `has_many` method.
+      # It accepts the same parameters as `property` (basically, it is an alias to
+      # `property name, ..., collection: true`).
+      # Additionally, you can specify `:datatype` as a name of another model,
+      # as seen below. If you specify datatype as an URI, it will be automatically
+      # resolved to either a model (having the same `type`) or anonymous class.
+      #
+      # @example
+      #   has_many :friends, :predicate => "http://schema.org/Person", :datatype => :Person
+      #
+      # You don't have to treat `has_many` as an association with other models, however.
+      # It is acceptable to declare a collection of strings or any other resources
+      # using `has_many`:
+      #
+      # @example
+      #   has_many :duties, :predicate => "http://works.com#duty", :datatype => NS::XMLSchema["string"]
+      #
+      # @param (see #property)
+      def has_many(name, params = {})
+        property name, params.merge(:collection => true)
+      end
+
+      # Return Kalimba resource class associated with the given datatype
+      #
+      # @param [String, URI, Symbol] uri
+      # @return [Kalimba::Resource]
+      def from_datatype(datatype)
+        datatype =
+          case datatype
+          when URI
+            datatype
+          when Symbol
+            const_get(datatype).type
+          when String
+            if datatype =~ URI.regexp
+              URI(datatype)
+            else
+              const_get(datatype).type
+            end
+          else
+            if datatype.respond_to?(:uri)
+              datatype.uri
+            else
+              raise KalimbaError, "invalid datatype identifier"
+            end
+          end
+        Kalimba::Resource.descendants.detect {|a| a.type == datatype }
+      end
+
+
+      private
+
+      def inherited(child)
+        super
+        child.properties = properties.dup
+      end
+
+      def define_collection(name, params)
+        create_reflection(name, params)
+
+        class_eval <<-HERE, __FILE__, __LINE__
+          def #{name.singularize}_ids
+            self.#{name}.map(&:id)
+          end
+
+          def #{name.singularize}_ids=(ids)
+            klass = self.class.reflect_on_association(:#{name}).klass
+            self.#{name} = ids.reject(&:blank?).map {|i| klass.for(i) }
+          end
+        HERE
+      end
+    end
+
+    # Create a new record
+    #
+    # If given a block, yields the created object into it.
+    #
+    # @param [Hash<[Symbol, String] => Any>] params properties to assign
+    def initialize(params = {}, options = {})
+      params = params.stringify_keys
+
+      if params["_subject"]
+        if self.class.base_uri
+          @subject = self.class.base_uri.dup
+          @subject.fragment = params.delete("_subject")
+        else
+          raise KalimbaError, "Cannot assign an ID to a resource without base_uri"
+        end
+      end
+
+      @attributes = self.class.properties.inject({}) do |attrs, (name, options)|
+        value = options[:collection] ? [] : nil
+        attrs.merge(name => value)
+      end
+      assign_attributes(params, options)
+
+      @destroyed = false
+
+      yield self if block_given?
+    end
+
+    # Freeze the attributes hash such that associations are still accessible,
+    # even on destroyed records
+    #
+    # @return [self]
+    def freeze
+      @attributes.freeze; self
+    end
+
+    # Checks whether the attributes hash has been frozen
+    #
+    # @return [Boolean]
+    def frozen?
+      @attributes.frozen?
+    end
+
+    # RDF representation of the model
+    #
+    # @return [URI, nil] subject URI
+    def to_rdf
+      subject
+    end
+
+    private
+
+    include Kalimba::Callbacks
+    include Kalimba::Validations
+  end
+end