dse-driver 1.0.1

data/lib/dse/graph.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+require 'dse/graph/edge'
+require 'dse/graph/options'
+require 'dse/graph/path'
+require 'dse/graph/result'
+require 'dse/graph/result_set'
+require 'dse/graph/statement'
+require 'dse/graph/vertex'
+require 'dse/graph/vertex_property'
+require 'dse/graph/duration'

data/lib/dse/graph/duration.rb

@@ -0,0 +1,131 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # Represents a duration of time, corresponding to the Duration datatype in DSE Graph. In DSE Graph,
+    # this type is represented by the
+    # {https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html Java 8 Duration} type.
+    class Duration
+      # Days in duration of time.  May be negative. Is internally coerced to an integer,
+      # so a value being assigned need not be an `Integer` itself.
+      # @return [Integer] days in duration of time.
+      attr_reader :days
+
+      # Hours in duration of time.  May be negative. Is internally coerced to an integer,
+      # so a value being assigned need not be an `Integer` itself.
+      # @return [Integer] hours in duration of time.
+      attr_reader :hours
+
+      # Minutes in duration of time.  May be negative. Is internally coerced to an integer,
+      # so a value being assigned need not be an `Integer` itself.
+      # @return [Integer] minutes in duration of time.
+      attr_reader :minutes
+
+      # Seconds in duration of time.  May be negative. Is internally coerced to an float,
+      # so a value being assigned need not be an `Float` itself.
+      # @return [Float] seconds in duration of time.
+      attr_reader :seconds
+
+      # @private
+      # We expect a string of the form PnDTnHnMn.nS, where n's are positive or negative integers, and where
+      # components may be missing (e.g. PT7.8S is valid)
+      PAT = /^P((?<days>-?\d+)D)?T((?<hours>-?\d+)H)?((?<minutes>-?\d+)M)?((?<seconds>-?[0-9.]+)S)?$/
+
+      # Create a {Duration} object. All arguments are internally coerced to desired types.
+      # @param days [Integer] number of days in the time-frame. May be negative.
+      # @param hours [Integer] number of hours in the time-frame. May be negative.
+      # @param minutes [Integer] number of minutes in the time-frame. May be negative.
+      # @param seconds [Float] number of seconds in the time-frame. May be negative.
+      def initialize(days, hours, minutes, seconds)
+        @days = days.to_i
+        @hours = hours.to_i
+        @minutes = minutes.to_i
+        @seconds = seconds.to_f
+      end
+
+      def days=(days)
+        @days = days.to_i
+      end
+
+      def hours=(hours)
+        @hours = hours.to_i
+      end
+
+      def minutes=(minutes)
+        @minutes = minutes.to_i
+      end
+
+      def seconds=(seconds)
+        @seconds = seconds.to_f
+      end
+
+      # Parse a duration string from DSE Graph and construct a {Duration} object
+      # @param duration [String] duration string from DSE Graph.
+      # @raise [ArgumentError] if the duration string fails to parse.
+      def self.parse(duration)
+        parse_result = PAT.match(duration.to_s)
+        raise(ArgumentError,
+              "Failed to parse '#{duration}': expected format PnDTnHnMn.nS with integer n" \
+              ' and optionally missing duration components') unless parse_result
+        Duration.new(parse_result[:days], parse_result[:hours], parse_result[:minutes], parse_result[:seconds])
+      end
+
+      # A string formatted as `PnDTnHnMn.nS`, where `n` is a number that goes with the character code following it.
+      #
+      # D - days<br>
+      # H - hours<br>
+      # M - minutes<br>
+      # S - seconds<br>
+      #
+      # @example a duration of 1 day, 2 hours, 3 minutes, 4.5 seconds
+      #  P1DT2H3M4.5S
+      # @return [String] this {Duration} as a string formatted `PnDTnHnMn.nS`.
+      #
+      # @see https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-
+      #   Java 8 Duration#parse
+      def to_s
+        # Construct a string of the form PnDTnHnMn.nS
+        "P#{@days}DT#{@hours}H#{@minutes}M#{@seconds}S"
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(Duration) && as_seconds == other.as_seconds
+      end
+      alias == eql?
+
+      # @return [Float] this {Duration} object converted to seconds
+      def as_seconds
+        @seconds + @minutes * 60 + @hours * 3600 + @days * 86400
+      end
+
+      # @private
+      def hash
+        @hash ||= begin
+          h = 17
+          h = 31 * h + @days.hash
+          h = 31 * h + @hours.hash
+          h = 31 * h + @minutes.hash
+          h = 31 * h + @seconds.hash
+          h
+        end
+      end
+
+      # @private
+      def inspect
+        "#<Duration:0x#{object_id.to_s(16)} " \
+          "@days=#{@days.inspect}, " \
+          "@hours=#{@hours.inspect}, " \
+          "@minutes=#{@minutes.inspect}, " \
+          "@seconds=#{@seconds.inspect}>"
+      end
+    end
+  end
+end

data/lib/dse/graph/edge.rb

@@ -0,0 +1,74 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # Edge represents an edge in DSE graph. An edge connects two vertices.
+    class Edge
+      include Cassandra::Util
+
+      # @return [Hash] id of this edge
+      attr_reader :id
+      # @return [String] label of this edge
+      attr_reader :label
+      # @return [Hash<String, String>] properties of this edge
+      attr_reader :properties
+      # @return [String] id of the "to" vertex of the edge
+      attr_reader :in_v
+      # @return [String] label of the "to" vertex of the edge
+      attr_reader :in_v_label
+      # @return [String] id of the "from" vertex of the edge
+      attr_reader :out_v
+      # @return [String] label of the "from" vertex of the edge
+      attr_reader :out_v_label
+
+      # @private
+      def initialize(id, label, properties, in_v, in_v_label, out_v, out_v_label)
+        @id = id
+        @label = label
+        @properties = properties
+        @in_v = in_v
+        @in_v_label = in_v_label
+        @out_v = out_v
+        @out_v_label = out_v_label
+      end
+
+      # @private
+      def [](key)
+        @properties[key]
+      end
+
+      # @private
+      def eql?(other)
+        # id's are unique among graph objects, so we only need to compare id's to test for equality.
+        other.is_a?(Edge) && \
+          @id == other.id
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        # id's are unique among graph objects, so we only need to hash on the id for safely adding to a hash/set.
+        @hash ||= 31 * 17 + @id.hash
+      end
+
+      # @private
+      def inspect
+        "#<Dse::Graph::Edge:0x#{object_id.to_s(16)} " \
+          "@id=#{@id.inspect}, " \
+          "@label=#{@label.inspect}, " \
+          "@properties=#{@properties.inspect}, " \
+          "@in_v=#{@in_v.inspect}, " \
+          "@in_v_label=#{@in_v_label.inspect}, " \
+          "@out_v=#{@out_v.inspect}, " \
+          "@out_v_label=#{@out_v_label.inspect}>"
+      end
+    end
+  end
+end

data/lib/dse/graph/options.rb

@@ -0,0 +1,194 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # @!parse
+    #   class Options
+    #     # @return [String] name of the targeted graph; required unless the statement is a system query.
+    #     attr_accessor :graph_name
+    #     # @return [String] graph traversal source (default "g")
+    #     attr_accessor :graph_source
+    #     # @return [String] language used in the graph statement (default "gremlin-groovy")
+    #     attr_accessor :graph_language
+    #     # @return [Cassandra::CONSISTENCIES] read consistency level for graph statement.
+    #     #   Overrides the standard statement consistency level. Defaults to ONE in the server,
+    #     #   but the default may be configured differently.
+    #     attr_accessor :graph_read_consistency
+    #     # @return [Cassandra::CONSISTENCIES] write consistency level for graph statement.
+    #     #   Overrides the standard statement consistency level. Defaults to QUORUM in the server,
+    #     #   but the default may be configured differently.
+    #     attr_accessor :graph_write_consistency
+    #   end
+
+    # Options for DSE Graph queries
+    class Options
+      # @return [Numeric] the timeout for graph requests
+      attr_reader :timeout
+
+      # @private
+      DEFAULT_GRAPH_OPTIONS = {
+        'graph-source' => 'g',
+        'graph-language' => 'gremlin-groovy'
+      }.freeze
+
+      # @private
+      OPTION_NAMES = [
+        :graph_name,
+        :graph_source,
+        :graph_language,
+        :graph_read_consistency,
+        :graph_write_consistency
+      ].freeze
+
+      # Create an Options object.
+      # @param options [Hash] optional hash containing graph options. Keys are option name symbols
+      #    (e.g. `:graph_name`). Unset options will inherit from the defaults.
+      def initialize(options = {})
+        # Filter the given options to only those we care about.
+        @real_options = {}
+        return unless options
+
+        options.each do |k, v|
+          set(k, v) if OPTION_NAMES.include?(k)
+        end
+
+        set_timeout(options[:timeout])
+      end
+
+      OPTION_NAMES.each do |attr|
+        define_method(attr.to_s) do
+          @real_options[stringify(attr)]
+        end
+
+        define_method("#{attr}=") do |value|
+          @real_options[stringify(attr)] = value
+        end
+      end
+
+      # @private
+      def timeout=(val)
+        set_timeout(val)
+        val
+      end
+
+      # @private
+      # rubocop:disable Style/AccessorMethodName
+      def set_timeout(new_timeout)
+        @timeout = new_timeout
+        if @timeout
+          @real_options['request-timeout'] = [@timeout * 1000].pack('Q>')
+        else
+          @real_options.delete('request-timeout')
+        end
+        nil
+      end
+
+      # Set an option in this {Options} object. This is primarily used to set "expert" options that
+      # are not part of the public api and thus may change over time.
+      # @param key [String, Symbol] option to set.
+      # @param value [String] value to set for the option.
+      # @return [Options] self, thus allowing method chaining.
+      def set(key, value)
+        string_key = stringify(key)
+        if string_key == 'timeout'
+          set_timeout(value)
+        elsif value
+          @real_options[stringify(key)] = value
+        end
+        self
+      end
+
+      # Delete an option from this {Options} object.
+      # @param key [String, Symbol] option to delete.
+      # @return nil
+      def delete(key)
+        string_key = stringify(key)
+        if string_key == 'timeout'
+          @timeout = nil
+          @real_options.delete('request-timeout')
+        else
+          @real_options.delete(string_key)
+        end
+        nil
+      end
+
+      # Merge another {Options} object with this one to produce a new merged {Options} object.
+      # The "other" object's values take precedence over this one.
+      # @param other [Options] Options object to merge with this one.
+      # @return [Options] new Options object with the merged options.
+      def merge(other)
+        # Just return our-self (no need to copy) if we're merging in nothing.
+        return self if other.nil?
+
+        # This is fairly efficient, but manipulates the guts of an Options object.
+        result = Options.new
+        result.instance_variable_set(:@real_options,
+                                     @real_options.merge(other.instance_variable_get(:@real_options)))
+        other_timeout = other.instance_variable_get(:@timeout)
+        result.instance_variable_set(:@timeout,
+                                     other_timeout ? other_timeout : @timeout)
+        result
+      end
+
+      # Clear the options within this {Options} object.
+      def clear
+        @real_options.clear
+        @timeout = nil
+      end
+
+      # @private
+      def stringify(attr)
+        attr.to_s.tr('_', '-')
+      end
+
+      # @private
+      def merge!(other)
+        result = merge(other)
+        @real_options = result.instance_variable_get(:@real_options)
+        @timeout = result.instance_variable_get(:@timeout)
+        self
+      end
+
+      # @return whether or not this options object is configured for the analytics graph source.
+      def analytics?
+        @real_options['graph-source'] == 'a'
+      end
+
+      # @private
+      def as_payload
+        # Merge in real options with defaults to get a final payload
+        DEFAULT_GRAPH_OPTIONS.merge(@real_options)
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(Options) && \
+          @real_options == other.instance_variable_get(:@real_options)
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= 31 * 17 + @real_options.hash
+      end
+
+      # @private
+      def inspect
+        "#<Dse::Graph::Options:0x#{object_id.to_s(16)} " \
+        "@graph_name=#{@real_options['graph-name'].inspect}, " \
+        "@graph_source=#{@real_options['graph-source'].inspect}, " \
+        "@graph_language=#{@real_options['graph-language'].inspect}, " \
+        "@graph_read_consistency=#{@real_options['graph-read-consistency'].inspect}, " \
+        "@graph_write_consistency=#{@real_options['graph-write-consistency'].inspect}, " \
+        "@timeout=#{@timeout.inspect}>"
+      end
+    end
+  end
+end

data/lib/dse/graph/path.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # Path represents a path connecting a set of vertices.
+    class Path
+      # @return [Array<Array>] labels in the path
+      attr_reader :labels
+      # @return [Array<Vertex, Edge, Result>] objects in the path, coerced to domain objects that
+      #   we recognize, or a {Result} otherwise
+      attr_reader :objects
+
+      # @private
+      def initialize(labels, objects)
+        @labels = labels
+        @objects = objects.map do |o|
+          Result.new(o).cast
+        end
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(Path) && \
+          @labels == other.labels && \
+          @objects == other.objects
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= begin
+          h = 17
+          h = 31 * h + @labels.hash
+          h = 31 * h + @objects.hash
+          h
+        end
+      end
+
+      # @private
+      def inspect
+        "#<Dse::Graph::Path:0x#{object_id.to_s(16)} " \
+          "@labels=#{@labels.inspect}, " \
+          "@objects=#{@objects.inspect}>"
+      end
+    end
+  end
+end