neo4j_legacy 7.2.0.1

data/lib/neo4j/shared/attributes.rb

@@ -0,0 +1,220 @@
+module Neo4j::Shared
+  # Attributes provides a set of class methods for defining an attributes
+  # schema and instance methods for reading and writing attributes.
+  #
+  # @example Usage
+  #   class Person
+  #     include Neo4j::Shared::Attributes
+  #     attribute :name
+  #   end
+  #
+  #   person = Person.new
+  #   person.name = "Ben Poweski"
+  #
+  # Originally part of ActiveAttr, https://github.com/cgriego/active_attr
+  module Attributes
+    extend ActiveSupport::Concern
+    include ActiveModel::AttributeMethods
+
+    # Methods deprecated on the Object class which can be safely overridden
+    DEPRECATED_OBJECT_METHODS = %w(id type)
+
+    included do
+      attribute_method_suffix '' if attribute_method_matchers.none? { |matcher| matcher.prefix == '' && matcher.suffix == '' }
+      attribute_method_suffix '='
+      attribute_method_suffix '?'
+    end
+
+    # Performs equality checking on the result of attributes and its type.
+    #
+    # @example Compare for equality.
+    #   model == other
+    #
+    # @param [ActiveAttr::Attributes, Object] other The other model to compare
+    #
+    # @return [true, false] True if attributes are equal and other is instance
+    #   of the same Class, false if not.
+    def ==(other)
+      return false unless other.instance_of? self.class
+      attributes == other.attributes
+    end
+
+    # Returns a Hash of all attributes
+    #
+    # @example Get attributes
+    #   person.attributes # => {"name"=>"Ben Poweski"}
+    #
+    # @return [Hash{String => Object}] The Hash of all attributes
+    def attributes
+      attributes_map { |name| send name }
+    end
+
+    # Write a single attribute to the model's attribute hash.
+    #
+    # @example Write the attribute with write_attribute
+    #   person.write_attribute(:name, "Benjamin")
+    # @example Write an attribute with bracket syntax
+    #   person[:name] = "Benjamin"
+    #
+    # @param [String, Symbol, #to_s] name The name of the attribute to update.
+    # @param [Object] value The value to set for the attribute.
+    #
+    # @raise [UnknownAttributeError] if the attribute is unknown
+    def write_attribute(name, value)
+      if respond_to? "#{name}="
+        send "#{name}=", value
+      else
+        fail Neo4j::UnknownAttributeError, "unknown attribute: #{name}"
+      end
+    end
+    alias_method :[]=, :write_attribute
+
+    def query_attribute(name)
+      if respond_to? "#{name}?"
+        send "#{name}?"
+      else
+        fail Neo4j::UnknownAttributeError, "unknown attribute: #{name}"
+      end
+    end
+
+    private
+
+    # Read an attribute from the attributes hash
+    def attribute(name)
+      @attributes ||= {}
+      @attributes[name]
+    end
+
+    # Write an attribute to the attributes hash
+    def attribute=(name, value)
+      @attributes ||= {}
+      @attributes[name] = value
+    end
+
+    # Maps all attributes using the given block
+    #
+    # @example Stringify attributes
+    #   person.attributes_map { |name| send(name).to_s }
+    #
+    # @yield [name] block called to return hash value
+    # @yieldparam [String] name The name of the attribute to map.
+    #
+    # @return [Hash{String => Object}] The Hash of mapped attributes
+    def attributes_map
+      Hash[self.class.attribute_names.map { |name| [name, yield(name)] }]
+    end
+
+    def attribute?(name)
+      Neo4j::Shared::TypeConverters::BooleanConverter.to_ruby(read_attribute(name))
+    end
+
+    module ClassMethods
+      # Defines an attribute
+      #
+      # For each attribute that is defined, a getter and setter will be
+      # added as an instance method to the model. An
+      # {AttributeDefinition} instance will be added to result of the
+      # attributes class method.
+      #
+      # @example Define an attribute.
+      #   attribute :name
+      #
+      # @param (see AttributeDefinition#initialize)
+      #
+      # @raise [DangerousAttributeError] if the attribute name conflicts with
+      #   existing methods
+      #
+      # @return [AttributeDefinition] Attribute's definition
+      def attribute(name)
+        if dangerous_attribute?(name)
+          fail Neo4j::DangerousAttributeError, %(an attribute method named "#{name}" would conflict with an existing method)
+        else
+          attribute!(name)
+        end
+      end
+
+      # Returns an Array of attribute names as Strings
+      #
+      # @example Get attribute names
+      #   Person.attribute_names
+      #
+      # @return [Array<String>] The attribute names
+      def attribute_names
+        attributes.keys
+      end
+
+      # Returns a Hash of AttributeDefinition instances
+      #
+      # @example Get attribute definitions
+      #   Person.attributes
+      #
+      # @return [ActiveSupport::HashWithIndifferentAccess{String => Neo4j::Shared::AttributeDefinition}]
+      #   The Hash of AttributeDefinition instances
+      def attributes
+        @attributes ||= ActiveSupport::HashWithIndifferentAccess.new
+      end
+
+      # Determine if a given attribute name is dangerous
+      #
+      # Some attribute names can cause conflicts with existing methods
+      # on an object. For example, an attribute named "timeout" would
+      # conflict with the timeout method that Ruby's Timeout library
+      # mixes into Object.
+      #
+      # @example Testing a harmless attribute
+      #   Person.dangerous_attribute? :name #=> false
+      #
+      # @example Testing a dangerous attribute
+      #   Person.dangerous_attribute? :nil #=> "nil?"
+      #
+      # @param name Attribute name
+      #
+      # @return [false, String] False or the conflicting method name
+      def dangerous_attribute?(name)
+        attribute_methods(name).detect do |method_name|
+          !DEPRECATED_OBJECT_METHODS.include?(method_name.to_s) && allocate.respond_to?(method_name, true)
+        end unless attribute_names.include? name.to_s
+      end
+
+      # Returns the class name plus its attribute names
+      #
+      # @example Inspect the model's definition.
+      #   Person.inspect
+      #
+      # @return [String] Human-readable presentation of the attributes
+      def inspect
+        inspected_attributes = attribute_names.sort
+        attributes_list = "(#{inspected_attributes.join(', ')})" unless inspected_attributes.empty?
+        "#{name}#{attributes_list}"
+      end
+
+      protected
+
+      # Assign a set of attribute definitions, used when subclassing models
+      #
+      # @param [Array<Neo4j::Shared::DeclaredProperties>] The Array of
+      #   AttributeDefinition instances
+      def attributes=(attributes)
+        @attributes = attributes
+      end
+
+      # Overrides ActiveModel::AttributeMethods to backport 3.2 fix
+      def instance_method_already_implemented?(method_name)
+        generated_attribute_methods.method_defined?(method_name)
+      end
+
+      private
+
+      # Expand an attribute name into its generated methods names
+      def attribute_methods(name)
+        attribute_method_matchers.map { |matcher| matcher.method_name name }
+      end
+
+      # Ruby inherited hook to assign superclass attributes to subclasses
+      def inherited(subclass)
+        super
+        subclass.attributes = attributes.dup
+      end
+    end
+  end
+end

data/lib/neo4j/shared/callbacks.rb

@@ -0,0 +1,64 @@
+module Neo4j
+  module Shared
+    module Callbacks #:nodoc:
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        include ActiveModel::Callbacks
+      end
+
+      included do
+        include ActiveModel::Validations::Callbacks
+        # after_find is triggered by the `find` method defined in lib/neo4j/active_node/id_property.rb
+        define_model_callbacks :initialize, :find, only: :after
+        define_model_callbacks :save, :create, :update, :destroy, :touch
+      end
+
+      def initialize(args = nil)
+        run_callbacks(:initialize) { super }
+      end
+
+      def destroy #:nodoc:
+        tx = Neo4j::Transaction.new
+        run_callbacks(:destroy) { super }
+      rescue
+        @_deleted = false
+        @attributes = @attributes.dup
+        tx.mark_failed
+        raise
+      ensure
+        tx.close if tx
+      end
+
+      def touch #:nodoc:
+        run_callbacks(:touch) { super }
+      end
+
+      # Allows you to perform a callback if a condition is not satisfied.
+      # @param [Symbol] kind The callback type to execute unless the guard is true
+      # @param [TrueClass,FalseClass] guard When this value is true, the block is yielded without executing callbacks.
+      def conditional_callback(kind, guard)
+        return yield if guard
+        run_callbacks(kind) { yield }
+      end
+
+      private
+
+      def create_or_update #:nodoc:
+        run_callbacks(:save) { super }
+      end
+
+      def create_model #:nodoc:
+        Neo4j::Transaction.run do
+          run_callbacks(:create) { super }
+        end
+      end
+
+      def update_model(*) #:nodoc:
+        Neo4j::Transaction.run do
+          run_callbacks(:update) { super }
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/shared/cypher.rb

@@ -0,0 +1,37 @@
+module Neo4j::Shared
+  module Cypher
+    module CreateMethod
+      def create_method
+        creates_unique? ? :create_unique : :create
+      end
+
+      def creates_unique(option = :none)
+        option = :none if option == true
+        @creates_unique = option
+      end
+
+      def creates_unique_option
+        @creates_unique || :none
+      end
+
+      def creates_unique?
+        !!@creates_unique
+      end
+      alias_method :unique?, :creates_unique?
+    end
+
+    module RelIdentifiers
+      extend ActiveSupport::Concern
+
+      [:from_node, :to_node, :rel].each do |element|
+        define_method("#{element}_identifier") do
+          instance_variable_get(:"@#{element}_identifier") || element
+        end
+
+        define_method("#{element}_identifier=") do |id|
+          instance_variable_set(:"@#{element}_identifier", id.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/shared/declared_properties.rb

@@ -0,0 +1,204 @@
+module Neo4j::Shared
+  # The DeclaredPropertyuManager holds details about objects created as a result of calling the #property
+  # class method on a class that includes Neo4j::ActiveNode or Neo4j::ActiveRel. There are many options
+  # that are referenced frequently, particularly during load and save, so this provides easy access and
+  # a way of separating behavior from the general Active{obj} modules.
+  #
+  # See Neo4j::Shared::DeclaredProperty for definitions of the property objects themselves.
+  class DeclaredProperties
+    include Neo4j::Shared::TypeConverters
+
+    attr_reader :klass
+    delegate :each, :each_pair, :each_key, :each_value, to: :registered_properties
+
+    # Each class that includes Neo4j::ActiveNode or Neo4j::ActiveRel gets one instance of this class.
+    # @param [#declared_properties] klass An object that has the #declared_properties method.
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def [](key)
+      registered_properties[key.to_sym]
+    end
+
+    def property?(key)
+      registered_properties.key?(key.to_sym)
+    end
+
+    # @param [Neo4j::Shared::DeclaredProperty] property An instance of DeclaredProperty, created as the result of calling
+    # #property on an ActiveNode or ActiveRel class. The DeclaredProperty has specifics about the property, but registration
+    # makes the management object aware of it. This is necessary for type conversion, defaults, and inclusion in the nil and string hashes.
+    def register(property)
+      @_attributes_nil_hash = nil
+      @_attributes_string_map = nil
+      registered_properties[property.name] = property
+      register_magic_typecaster(property) if property.magic_typecaster
+      declared_property_defaults[property.name] = property.default_value if !property.default_value.nil?
+    end
+
+    def index_or_fail!(key, id_property_name, type = :exact)
+      return if key == id_property_name
+      fail "Cannot index undeclared property #{key}" unless property?(key)
+      registered_properties[key].index!(type)
+    end
+
+    def constraint_or_fail!(key, id_property_name, type = :unique)
+      return if key == id_property_name
+      fail "Cannot constraint undeclared property #{property}" unless property?(key)
+      registered_properties[key].constraint!(type)
+    end
+
+    # The :default option in Neo4j::ActiveNode#property class method allows for setting a default value instead of
+    # nil on declared properties. This holds those values.
+    def declared_property_defaults
+      @_default_property_values ||= {}
+    end
+
+    def registered_properties
+      @_registered_properties ||= {}
+    end
+
+    def indexed_properties
+      registered_properties.select { |_, p| p.index_or_constraint? }
+    end
+
+    # During object wrap, a hash is needed that contains each declared property with a nil value.
+    # The active_attr dependency is capable of providing this but it is expensive and calculated on the fly
+    # each time it is called. Rather than rely on that, we build this progressively as properties are registered.
+    # When the node or rel is loaded, this is used as a template.
+    def attributes_nil_hash
+      @_attributes_nil_hash ||= {}.tap do |attr_hash|
+        registered_properties.each_pair do |k, prop_obj|
+          val = prop_obj.default_value
+          attr_hash[k.to_s] = val
+        end
+      end.freeze
+    end
+
+    # During object wrapping, a props hash is built with string keys but Neo4j-core provides symbols.
+    # Rather than a `to_s` or `symbolize_keys` during every load, we build a map of symbol-to-string
+    # to speed up the process. This increases memory used by the gem but reduces object allocation and GC, so it is faster
+    # in practice.
+    def attributes_string_map
+      @_attributes_string_map ||= {}.tap do |attr_hash|
+        attributes_nil_hash.each_key { |k| attr_hash[k.to_sym] = k }
+      end.freeze
+    end
+
+    # @param [Symbol] k A symbol for which the String representation is sought. This might seem silly -- we could just call #to_s --
+    # but when this happens many times while loading many objects, it results in a surprisingly significant slowdown.
+    # The branching logic handles what happens if a property can't be found.
+    # The first option attempts to find it in the existing hash.
+    # The second option checks whether the key is the class's id property and, if it is, the string hash is rebuilt with it to prevent
+    # future lookups.
+    # The third calls `to_s`. This would happen if undeclared properties are found on the object. We could add them to the string map
+    # but that would result in unchecked, un-GCed memory consumption. In the event that someone is adding properties dynamically,
+    # maybe through user input, this would be bad.
+    def string_key(k)
+      attributes_string_map[k] || string_map_id_property(k) || k.to_s
+    end
+
+    def unregister(name)
+      # might need to be include?(name.to_s)
+      fail ArgumentError, "Argument `#{name}` not an attribute" if not registered_properties[name]
+      registered_properties.delete(name)
+      unregister_magic_typecaster(name)
+      unregister_property_default(name)
+    end
+
+    def serialize(name, coder = JSON)
+      @serialize ||= {}
+      @serialize[name] = coder
+    end
+
+    def serialized_properties=(serialize_hash)
+      @serialized_property_keys = nil
+      @serialize = serialize_hash.clone
+    end
+
+    def serialized_properties
+      @serialize ||= {}
+    end
+
+    def serialized_properties_keys
+      @serialized_property_keys ||= serialized_properties.keys
+    end
+
+    def magic_typecast_properties_keys
+      @magic_typecast_properties_keys ||= magic_typecast_properties.keys
+    end
+
+    def magic_typecast_properties
+      @magic_typecast_properties ||= {}
+    end
+
+    EXCLUDED_TYPES = [Array, Range, Regexp]
+    def value_for_where(key, value)
+      return value unless prop = registered_properties[key]
+      return value_for_db(key, value) if prop.typecaster && prop.typecaster.convert_type == value.class
+
+      if should_convert_for_where?(key, value)
+        value_for_db(key, value)
+      else
+        value
+      end
+    end
+
+    def value_for_db(key, value)
+      return value unless registered_properties[key]
+      convert_property(key, value, :to_db)
+    end
+
+    def value_for_ruby(key, value)
+      return unless registered_properties[key]
+      convert_property(key, value, :to_ruby)
+    end
+
+    def inject_defaults!(object, props)
+      declared_property_defaults.each_pair do |k, v|
+        props[k.to_sym] = v if object.send(k).nil? && props[k.to_sym].nil?
+      end
+      props
+    end
+
+    protected
+
+    # Prevents repeated calls to :_attribute_type, which isn't free and never changes.
+    def fetch_upstream_primitive(attr)
+      registered_properties[attr].type
+    end
+
+    private
+
+    def should_convert_for_where?(key, value)
+      (value.is_a?(Array) && supports_array?(key)) || !EXCLUDED_TYPES.include?(value.class)
+    end
+
+    # @param [Symbol] key An undeclared property value found in the _persisted_obj.props hash.
+    # Typically, this is a node's id property, which will not be registered as other properties are.
+    # In the future, this should probably be reworked a bit. This class should either not know or care
+    # about the id property or it should be in charge of it. In the meantime, this improves
+    # node load performance.
+    def string_map_id_property(key)
+      return unless klass.id_property_name == key
+      key.to_s.tap do |string_key|
+        @_attributes_string_map = attributes_string_map.dup.tap { |h| h[key] = string_key }.freeze
+      end
+    end
+
+    def unregister_magic_typecaster(property)
+      magic_typecast_properties.delete(property)
+      @magic_typecast_properties_keys = nil
+    end
+
+    def unregister_property_default(property)
+      declared_property_defaults.delete(property)
+      @_default_property_values = nil
+    end
+
+    def register_magic_typecaster(property)
+      magic_typecast_properties[property.name] = property.magic_typecaster
+      @magic_typecast_properties_keys = nil
+    end
+  end
+end

data/lib/neo4j/shared/declared_property/index.rb

@@ -0,0 +1,37 @@
+module Neo4j::Shared
+  class DeclaredProperty
+    # None of these methods interact with the database. They only keep track of property settings in models.
+    # It could (should?) handle the actual indexing/constraining, but that's TBD.
+    module Index
+      def index_or_constraint?
+        index?(:exact) || constraint?(:unique)
+      end
+
+      def index?(type = :exact)
+        options.key?(:index) && options[:index] == type
+      end
+
+      def constraint?(type = :unique)
+        options.key?(:constraint) && options[:constraint] == type
+      end
+
+      def index!(type = :exact)
+        fail Neo4j::InvalidPropertyOptionsError, "Can't set index on constrainted property #{name} (constraints get indexes automatically)" if constraint?(:unique)
+        options[:index] = type
+      end
+
+      def constraint!(type = :unique)
+        fail Neo4j::InvalidPropertyOptionsError, "Can't set constraint on indexed property #{name} (constraints get indexes automatically)" if index?(:exact)
+        options[:constraint] = type
+      end
+
+      def unindex!(type = :exact)
+        options.delete(:index) if index?(type)
+      end
+
+      def unconstraint!(type = :unique)
+        options.delete(:constraint) if constraint?(type)
+      end
+    end
+  end
+end

data/lib/neo4j/shared/declared_property.rb

@@ -0,0 +1,118 @@
+module Neo4j::Shared
+  # Contains methods related to the management
+  class DeclaredProperty
+    include Comparable
+
+    class IllegalPropertyError < Neo4j::Error; end
+    include Neo4j::Shared::DeclaredProperty::Index
+
+    ILLEGAL_PROPS = %w(from_node to_node start_node end_node)
+    attr_reader :name, :name_string, :name_sym, :options, :magic_typecaster
+
+    def initialize(name, options = {})
+      fail IllegalPropertyError, "#{name} is an illegal property" if ILLEGAL_PROPS.include?(name.to_s)
+      fail TypeError, "can't convert #{name.class} into Symbol" unless name.respond_to?(:to_sym)
+      @name = @name_sym = name.to_sym
+      @name_string = name.to_s
+      @options = options
+      fail_invalid_options!
+    end
+
+    # Compare attribute definitions
+    #
+    # @example
+    #   attribute_definition <=> other
+    #
+    # @param [Neo4j::Shared::DeclaredProperty, Object] other The other
+    #   attribute definition to compare with.
+    #
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      return nil unless other.instance_of? self.class
+      return nil if name == other.name && options != other.options
+      self.to_s <=> other.to_s
+    end
+
+    def inspect
+      options_description = options.map { |key, value| "#{key.inspect} => #{value.inspect}" }.sort.join(', ')
+      inspected_options = ", #{options_description}" unless options_description.empty?
+      "attribute :#{name}#{inspected_options}"
+    end
+
+    def to_s
+      name.to_s
+    end
+
+    def to_sym
+      name
+    end
+
+    def [](key)
+      respond_to?(key) ? public_send(key) : nil
+    end
+
+    def register
+      register_magic_properties
+    end
+
+    def type
+      options[:type]
+    end
+
+    def typecaster
+      options[:typecaster]
+    end
+
+    def default_value
+      options[:default]
+    end
+    alias_method :default, :default_value
+
+    def fail_invalid_options!
+      case
+      when index?(:exact) && constraint?(:unique)
+        fail Neo4j::InvalidPropertyOptionsError,
+             "#Uniqueness constraints also provide exact indexes, cannot set both options on property #{name}"
+      end
+    end
+
+    private
+
+    def option_with_value!(key, value)
+      options[key] = value
+      fail_invalid_options!
+    end
+
+    def option_with_value?(key, value)
+      options[key] == value
+    end
+
+    # Tweaks properties
+    def register_magic_properties
+      options[:type] ||= Neo4j::Config.timestamp_type if timestamp_prop?
+
+      register_magic_typecaster
+      register_type_converter
+    end
+
+    def timestamp_prop?
+      name.to_sym == :created_at || name.to_sym == :updated_at
+    end
+
+    def register_magic_typecaster
+      found_typecaster = Neo4j::Shared::TypeConverters.typecaster_for(options[:type])
+      return unless found_typecaster && found_typecaster.respond_to?(:primitive_type)
+      options[:typecaster] = found_typecaster
+      @magic_typecaster = options[:type]
+      options[:type] = found_typecaster.primitive_type
+    end
+
+    def register_type_converter
+      converter = options[:serializer]
+      return unless converter
+      options[:type]        = converter.convert_type
+      options[:typecaster]  = Neo4j::Shared::TypeConverters::ObjectConverter
+      Neo4j::Shared::TypeConverters.register_converter(converter)
+    end
+  end
+end