cassie 1.0.0.beta.33 → 1.0.0.1

data/lib/cassie/statements/statement/mapping.rb

@@ -1,15 +1,43 @@
 module Cassie::Statements::Statement
   module Mapping
-    extend ActiveSupport::Concern
 
-    included do
-      # We are mapping term values from a client provided resource.
-      # store this object in `_resource` attribte
-      # as they could reasonably want to name it `resource`
-      attr_accessor :_resource
+    def self.included(base)
+      base.instance_eval do
+        # We are mapping term values from a client provided resource.
+        # store this object in `_resource` attribte
+        # as they could reasonably want to name it `resource`
+        attr_accessor :_resource
+      end
+      base.extend ClassMethods
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
+      # DSL setting a getter and setter.
+      #
+      # When use with a relation (+where+) or assignment (+set+),
+      # the fetching of column values are
+      # delegated to the object in this getter.
+      #
+      # @note This delegation behavor gets last preference.
+      #   * An overwritten +column_name+ getter has first preference
+      #   * the +@column_name+ instance variable has next preference
+      #   * the mapped resource delegation has last preference
+      #
+      # @example Simple Mapping delegation
+      #   Class Statement
+      #     include Cassie::Statements::Statement:Relations
+      #     include Cassie::Statements::Statement:Mapping
+      #
+      #     where :name
+      #
+      #     map_from :user
+      #   end
+      #
+      #   s = Statement.new
+      #   s.user = User.new(id: 1)
+      #   s.id
+      #   #=> 1
       def map_from(resource_name)
         define_method resource_name do
           _resource

data/lib/cassie/statements/statement/preparation/cache.rb

@@ -43,7 +43,7 @@ module Cassie::Statements::Statement
     def self.init_cache
       previous_cache = defined?(@cache) ? @cache : nil
 
-      #TODO: research why memory story is blowing up when
+      # @todo research why memory story is blowing up when
       #     serializing the Cassandra prepared statement result
       # @cache = ActiveSupport::Cache::MemoryStore.new
       @cache = Cache.new

data/lib/cassie/statements/statement/preparation.rb

@@ -1,27 +1,57 @@
 require_relative 'preparation/cache'
 
 module Cassie::Statements::Statement
+  # Sepcific functionality and DSL for prepared statements.
+  #
+  # When included, a local, in-memory statement cache will be used
+  # when generating the statement object if +prepared?+ is +true+.
+  #
+  # By default, {.prepare} defaults to +true+, since most statements should be prepared.
+  #
+  # The cache key is the +cql+ for the statment, or the statement itself
+  # if it does not respond to +cql+. For bound statments (recommended)
+  # this results in only cacheing once per unique statement type, independent
+  # of the values for a particular statemtn (which are in the +params+ attribute, not the +cql+ attribute).
+  #
+  # The following class attributes are affected when included:
+  # * Sets {.prepared} to +true+ since most statements should be prepared.
   module Preparation
-    extend ::ActiveSupport::Concern
-
-    included do
-      class << self
-        attr_accessor :prepare
+    # @!visibility private
+    def self.included(base)
+      base.extend ClassMethods
+      base.instance_eval do
+        self.prepare = true
       end
-      self.prepare = true
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
+
+      #@!visibility private
       def inherited(subclass)
         subclass.prepare = prepare
         super
       end
 
+      # @return [Boolean] whether the statement will be prepared when executed
+      def prepare
+        @prepare
+      end
+
+      def prepare=(val)
+        @prepare = !!val
+      end
+
+      # @return [Boolean] indicating whether the statement will be prepared when executed
       def prepare?
         !!prepare
       end
     end
 
+    # override. The statement object, fetched from perpared statements
+    # cache if {#prepare?} is +true+
+    # @return [Cassandra::Statements::Prepared, Object] A bound,
+    # prepared statement if {#prepare?} is +true+, otherwise +super+
     def statement
       statement = super
       if self.class.prepare?
@@ -37,7 +67,7 @@ module Cassie::Statements::Statement
       end
     end
 
-    private
+    protected
 
     def statement_cache
       Cassie::Statements::Statement::Preparation.cache

data/lib/cassie/statements/statement/relations.rb

@@ -20,30 +20,51 @@ module Cassie::Statements::Statement
     extend ActiveSupport::Concern
 
     module ClassMethods
-      #    where :username, :eq, value: :method
-      #    where :phone, :in
-      #    relation :user_id, :gteq, term: "minTimeuuid('2013-02-02 10:00+0000')"
-      def where(identifier, op, opts={})
-        opts[:value] ||= implied_argument_method(identifier, op)
+      # DSL to set a ranging relation (+WHERE+ clause) for the statement.
+      #
+      # Defining a relation also defines an +attr_accessor+ with the same name as
+      # the identifier (or the +:value+ option if a symbol is used). The underlying instance
+      # variable value for this accessor will be used when determining the value for the relation.
+      #
+      # @param [String, Symbol] identifier The field name or other CQL identifier to restrict the query.
+      # @param [Symbol] operation Which operation to use. See {Cassie::Statements::Statement::Relation::OPERATIONS} for valid symbols and their associated operations.
+      # @param [Hash] opts options for the relation
+      # @option opts [Symbol, Object] :value The value to use for the ranging relation (constraint). If a [Symbol], a method with that name will be called when the statement is built. Otherwise, the value itself will be used.
+      # @option opts [Symbol, Object] :if Determines if the relation is applied to the statement or not. If a [Symbol], a method with that name will be called when the statement is built. Otherwise, the value itself will be used.
+      # @option opts [String] :term The argument value to use instead of a positional placeholder (?). If a [Symbol], a method with that name will be called when the statement is built. Otherwise, the value itself will be used.
+      # @return [Enumerable<Array<Object>>] The enumeration of current relations' parameters
+      # @raise [StandardError] if there is already a getter or setter method defined for the
+      #   relation value's implied accessor (+identifier+ or symbol +:value+ option).
+      #
+      # @example Range relation with implied accessor
+      #   where :username, :eq #<= gets relation value from `:username` method
+      # @example Range relation with explicit accessor
+      #   where :username, :eq, value: :name #<= gets relation value from `:name` method
+      # @example Range relation with multi-value, pluarlized accessr
+      #   where :phone, :in #<= gets relation value from `:phones` method
+      def where(identifier, operation, opts={})
+        opts[:value] ||= implied_argument_method(identifier, operation)
 
         define_argument_accessor(opts[:value])
 
-        relations_args << [identifier, op, opts.delete(:value), opts]
+        relations_args << [identifier, operation, opts.delete(:value), opts]
       end
 
+      # The enumeration of current relations' parameters that will be
+      # used to build Relation objects when the statement is built
       def relations_args
         @relations_args ||= []
       end
 
       protected
 
-      #TODO: extract argument accessor creation for
+      # @todo extract argument accessor creation for
       #      more DRY and clear usage. See mapping module.
       def define_argument_accessor(name)
         unless Symbol === name
           raise ArgumentError, "A Symbol is required for the accessor methods for setting/getting a relation's value. #{name.class} (#{name}) given."
         end
-        #TODO: this should probably only raise
+        # @todo this should probably only raise
         #      if value option was nil and we
         #      are implicilty creating getter/setters.
         if method_defined?(name) || method_defined?("#{name}=")

data/lib/cassie/statements/statement/selection.rb

@@ -5,21 +5,42 @@ require_relative 'relations'
 require_relative 'ordering'
 
 module Cassie::Statements::Statement
+  # Sepcific functionality and DSL for selection statements
+  #
+  # The following class attributes are affected when included:
+  # * Sets {.idempotent} to +true+ since selection queries are idempotent by definition.
+  # * Sets the {.result_class} to {Cassie::Statements::Results::QueryResult}
   module Selection
-    extend ::ActiveSupport::Concern
 
-    included do
-      include Relations
-      include Ordering
-      include Limiting
-      include AllowFiltering
-      include Pagination
-
-      @result_class = Cassie::Statements::Results::QueryResult
-      @idempotent = true
+    # @!visibility private
+    # @!parse include Relations
+    # @!parse extend Relations::ClassMethods
+    # @!parse include Ordering
+    # @!parse extend Ordering::ClassMethods
+    # @!parse include Limiting
+    # @!parse extend Limiting::ClassMethods
+    # @!parse include AllowFiltering
+    # @!parse extend AllowFiltering::ClassMethods
+    # @!parse include Pagination
+    # @!parse extend Pagination::ClassMethods
+    def self.included(base)
+      base.instance_eval do
+        include Relations
+        include Ordering
+        include Limiting
+        include AllowFiltering
+        include Pagination
+
+        @result_class = Cassie::Statements::Results::QueryResult
+        @idempotent = true
+      end
+      base.extend ClassMethods
     end
 
     module ClassMethods
+      # DSL to set the statement type and table for selection
+      # @param [String, Symbol] table The table to taret for the select statement
+      # @return [void]
       def select_from(table)
         self.table = table
         self.type = :select
@@ -27,26 +48,41 @@ module Cassie::Statements::Statement
         yield(self) if block_given?
       end
 
-      def select(selector, opts={})
-        selector = selector.to_s
-        selector += " AS #{opts[:as]}" if opts[:as]
-        selectors << selector
+      # DSL to add a column to be ruturned for each row in the query results
+      # @param [String, Symbol] column The column name in the CQL schmea to return
+      # @param [Hash] opts options for the selector
+      # @option opts [String] :as The identifier to use for the field when returned in the result if different than the column name
+      # @return [String] the current enumeration of selectors
+      def select(column, opts={})
+        column = column.to_s
+        column += " AS #{opts[:as]}" if opts[:as]
+        selectors << column
       end
 
-      # a select clause is built up of selectors
+      # The enumeration of selectors for use in the statement
+      # @return [Array<String>]
       def selectors
         @selectors ||= []
       end
 
+      # DSL to wrap a selector in the +WRITETIME+ CQL,
+      # used to select the time the field was written
+      # instead of the value itself
       def write_time(selector)
         "WRITETIME(#{selector})"
       end
       alias writetime write_time
 
+      # DSL to wrap a selector in the +TTL+ CQL,
+      # used to select the time until the field will be
+      # tombstoned, instead of the value itself
       def ttl(selector)
         "TTL(#{selector})"
       end
 
+      # DSL to wrap a selector in the +COUNT+ CQL,
+      # used to select the aggregation of the number of rows
+      # instead of the value in each row
       def count(selector='*')
         "COUNT(#{selector})"
       end

data/lib/cassie/statements/statement/type_hinting.rb

@@ -1,4 +1,4 @@
-module Cassie::Statements  
+module Cassie::Statements
   module Statement::TypeHinting
     extend ActiveSupport::Concern
 
@@ -7,6 +7,7 @@ module Cassie::Statements
     end
 
     module ClassMethods
+      # @!visibility private
       def inherited(subclass)
         subclass.type_hints = type_hints if defined?(@type_hints)
         super
@@ -16,16 +17,23 @@ module Cassie::Statements
         @type_hints = val
       end
 
-      def type_hints(val=:get)
-        if val == :get
+      # DSL to set the type hints execution option
+      # Defaults to +nil+ if none are set
+      # @param [Array, Hash] hints Hints to use for value serialization. Array for positional arguments, Hash for named arguments.
+      # @return [Array, Hash] hints to use for value serialization. Array for positional arguments, Hash for named arguments.
+      def type_hints(hints=:get)
+        if hints == :get
           return @type_hints if defined?(@type_hints)
           nil
         else
-          self.type_hints = val
+          self.type_hints = hints
         end
       end
     end
 
+    # The type hints for this object's statement
+    # Defaults to {.type_hints} if none are set on the object
+    # @return [Array, Hash] hints to use for value serialization. Array for positional arguments, Hash for named arguments.
     def type_hints
       return @type_hints if defined?(@type_hints)
       self.class.type_hints

data/lib/cassie/statements/statement/updating.rb

@@ -3,17 +3,30 @@ require_relative 'conditions'
 
 module Cassie::Statements::Statement
   module Updating
-    extend ::ActiveSupport::Concern
 
-    included do
-      include Relations
-      include Assignments
-      include Conditions
-
-      @result_class = Cassie::Statements::Results::ModificationResult
+    # @!visibility private
+    # @!parse include Relations
+    # @!parse extend Relations::ClassMethods
+    # @!parse include Assignments
+    # @!parse extend Assignments::ClassMethods
+    # @!parse include Conditions
+    # @!parse extend Conditions::ClassMethods
+    def self.included(base)
+      base.instance_eval do
+        include Relations
+        include Assignments
+        include Conditions
+
+        @result_class = Cassie::Statements::Results::ModificationResult
+      end
+      base.extend ClassMethods
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
+      # DSL to set the statement type and table for updating
+      # @param [String, Symbol] table The table to taret for the update statement
+      # @return [void]
       def update(table)
         self.table = table
         self.type = :update
@@ -23,7 +36,8 @@ module Cassie::Statements::Statement
     end
 
     protected
-
+    # Sets the {#cql} and {#params} for a building a bound statement
+    # @return [void]
     def build_update_cql_and_params
       assignment_str, update_params = build_update_and_params
       where_str, where_params = build_where_and_params

data/lib/cassie/statements/statement.rb

@@ -16,16 +16,23 @@ module Cassie::Statements
 
     class Invalid < StandardError; end
 
-    extend ::ActiveSupport::Concern
-
-    included do
-      include Preparation
-      include TypeHinting
-      include Idempotency
-
-      class << self
-        attr_accessor :table
-        attr_accessor :type
+    # @!visibility private
+    # @!parse include Preparation
+    # @!parse extend Preparation::ClassMethods
+    # @!parse include TypeHinting
+    # @!parse include TypeHinting::ClassMethods
+    # @!parse include Idempotency
+    # @!parse include Idempotency::ClassMethods
+    def self.included(base)
+      base.instance_eval do
+        include Preparation
+        include TypeHinting
+        include Idempotency
+
+        class << self
+          attr_accessor :table
+          attr_accessor :type
+        end
       end
     end
 
@@ -33,14 +40,22 @@ module Cassie::Statements
       self.class.table
     end
 
-    # returns a CQL string, or a Cassandra::Statement
-    # that is ready for execution
+    # A bound statment with type hint and idempotent options, ready for execution ready for execution with a [Cassandra::Session]
+    # @return [Cassandra::Statement]
     def statement
       Cassandra::Statements::Simple.new(*build_cql_and_params, type_hints, idempotent?)
     end
 
-    # returns a CQL string with inline parameters, that
-    # is representative of what could be executed in a CQL shell
+    # A CQL string with inline parameters, representing the current statement
+    # as it would be executed in a CQL shell
+    #
+    # @note This CQL string does not include execution options like type hinting,
+    #  idempotency, consistency level, etc -- just the raw CQL instruction and values.
+    # @return [String]
+    #
+    # @example
+    #   statement.to_cql
+    #   #=> "SELECT * FROM table WHERE first='evan' AND middle='thomas' and last='prothro"
     def to_cql
       if statement.respond_to?(:cql) && statement.respond_to?(:params)
         Cassie::Support::StatementParser.new(statement).to_cql
@@ -53,11 +68,21 @@ module Cassie::Statements
       Cassie::Statements.logger
     end
 
+    # The CQL string portion for the statment
+    # @!parse attr_reader :cql
+    # @example
+    #   statement.cql
+    #   #=> "SELECT * FROM table WHERE first=? AND middle=? and last=?"
     def cql
       return @cql if defined?(@cql)
       ""
     end
 
+    # The positional values portion for the statment
+    # @example
+    #   statement.params
+    #   #=> ['evan', 'thomas', 'prothro']
+    # @!parse attr_reader :params
     def params
       return @params if defined?(@params)
       nil

data/lib/cassie/statements.rb

@@ -1,4 +1,16 @@
 module Cassie
+  # Contains components related to Cassandra statements, including
+  # * building with a CQL DSL
+  # * options for executing built statements
+  # * executing built statements
+  # * instrumenting
+  # * logging (using instrumentation)
+  #
+  # See +Statements+ submodules for more information on the responsibilities of
+  # these individual components.
+  #
+  # See {Cassie::Query}, {Cassie::Modification} or {Cassie::Definition}
+  # to see concrete query interfaces implementeing these components.
   module Statements
     require_relative 'statements/core'
     require_relative 'statements/query'

data/lib/cassie/support/server_process.rb

@@ -0,0 +1,117 @@
+module Cassie
+  module Support
+    class ServerProcess
+
+      attr_reader :pid
+
+      # Scan the system for cassandra processes running
+      # @return [Array<ServerProcess>] Running cassandra processes
+      # @raise [RuntimeError] if scanning with +ps+ system calls fails.
+      def self.all
+        pids.map{|pid| new(pid)}
+      end
+
+      # The path to the active cassandra binary's log file
+      # Does not yet respect a configured log path,
+      # and assumes the path is relative to bin/casandra at ../logs/system.log
+      # @!parse attr_reader :log_path
+      def self.log_path
+        which = Cassie::Support::SystemCommand.new("which", ["cassandra"])
+        which.succeed
+
+        bin_path = which.output.tr("\n", '')
+        bin_path.sub('bin/cassandra', 'logs/system.log')
+      end
+
+      # Starts a cassandra server process. {#running?} will be true if it started correctly.
+      def initialize(pid=nil)
+        @pid = pid
+
+        if pid
+          @running = true
+        else
+          start_cassandra
+        end
+      end
+
+      # @return [Boolean] If the cassandra server started correctly. See {#errors} if false.
+      def running?
+        !!@running
+      end
+
+      # Stops the cassandra server processes, synchronously.
+      # @raise [RuntimeError] if the process could not be killed.
+      def stop
+        self.class.pids.each do|pid|
+          Process.kill("TERM", pid)
+          loop do
+            sleep(0.1)
+            begin
+              Process.getpgid( pid )
+            rescue Errno::ESRCH
+              break
+            end
+          end
+        end
+      end
+
+      def command
+        details[:command]
+      end
+
+      # @return [Array<String>] The Cassandra output lines tagged with ERROR
+      # @!parse attr_reader :errors
+      def errors
+        return [] unless command && command.output
+        command.output.split("\n").grep(/ERROR/)
+      end
+
+      protected
+
+      def self.pids
+        ps = Cassie::Support::SystemCommand.new("ps", ["-awx"])
+        ps.succeed
+        cassandra_awx = ps.output.split("\n").grep(/cassandra/)
+        cassandra_awx.map{ |p| p.split(' ').first.to_i }
+      end
+
+      def start_cassandra
+        start_pids = self.class.pids
+        cassandra = Cassie::Support::SystemCommand.new("cassandra")
+        cassandra.run
+        new_pids = self.class.pids - start_pids
+        Cassie.logger.warn "[WARN] - Multiple cassandra processes started, using first one." if new_pids.length > 1
+
+        @running = !!(cassandra.output =~ /state jump to NORMAL/)
+        @pid = new_pids.first
+      end
+
+      def details
+        @details ||= fetch_details
+      end
+
+      def fetch_details
+        # http://linuxcommand.org/man_pages/ps1.html (key long descriptions)
+        # virtual memory size of the process in KiB
+        # ps -p 62027 -o pid,user,ltime,vsize,pcpu,args -ww
+        # PID USER     TIME      VSZ  %CPU ARGS
+        # 62027 eprothro   44:24  6201356   1.0 /Library/Java/Java
+        ps = Cassie::Support::SystemCommand.new("ps", ["-p", pid, "-o", "pid,user,etime,vsize,pcpu,args", "-ww"])
+        ps.succeed
+        puts ps.output
+        elements = ps.output.split("\n")[1]
+        elements = elements.split(" ")
+        raise "Error fetching details, pid fetched doesn't match pid queried" unless elements.shift.to_i == self.pid
+
+        {}.tap do |h|
+          h[:user] = elements.shift
+          offset = Time.now.getlocal.to_s.split(' ').last
+          h[:started_at] = DateTime.parse("#{elements.shift} #{offset}")
+          h[:memory] = elements.shift * 1024
+          h[:cpu] = elements.shift / 100.0
+        end
+        #{p.split(' ').first.ljust(5,' ')} | #{p.split(' ').last}"
+      end
+    end
+  end
+end

data/lib/cassie/support/statement_parser.rb

@@ -1,5 +1,7 @@
 module Cassie::Support
   class StatementParser
+    QUOTED_TYPES = [:date, :time, :text, :timestamp, :inet, :ascii].freeze
+
     attr_reader :statement
 
     def initialize(statement)
@@ -24,7 +26,7 @@ module Cassie::Support
       params_types.map.with_index do |type, i|
         cassandra_param = type.new(params[i])
         quoted_val = if QUOTED_TYPES.include? type.kind
-          "'#{cassandra_param.to_s}'"
+          "'#{cassandra_param}'"
         else
           cassandra_param.to_s
         end
@@ -33,9 +35,5 @@ module Cassie::Support
       end
       cql
     end
-
-    protected
-
-    QUOTED_TYPES = [:date, :time, :text, :timestamp, :inet, :ascii].freeze
   end
 end