class Cassandra::Execution::Options
Attributes
@return [Array] positional arguments for the statement
@return [Symbol] consistency for request. Must be one of
{Cassandra::CONSISTENCIES}
@return [Cassandra::LoadBalancing::Policy] load-balancing policy that determines which node will run the
next statement.
@return [Integer] requested page size
@return [String] paging state
@note Although this feature exists to allow web applications to store
paging state in an [HTTP cookie](http://en.wikipedia.org/wiki/HTTP_cookie), **it is not safe to expose without encrypting or otherwise securing it**. Paging state contains information internal to the Apache Cassandra cluster, such as partition key and data. Additionally, if a paging state is sent with CQL statement, different from the original, the behavior of Cassandra is undefined and will likely cause a server process of the coordinator of such request to abort.
@return [nil, Hash<String, String>] custom outgoing payload, a map of
string and byte buffers.
@see github.com/apache/cassandra/blob/cassandra-3.4/doc/native_protocol_v4.spec#L125-L131 Description
of custom payload in Cassandra native protocol v4.
@see dsdocs30_java/manual/custom_payloads/#enabling-custom-payloads-on-c-nodes
Enabling custom payloads on Cassandra nodes.
@example Sending a custom payload
result = session.execute(payload: { 'some key' => Cassandra::Protocol::CqlByteBuffer.new .append_string('some value') })
@return [Cassandra::Retry::Policy] retry policy that determines how request retries should be handled for
different failure modes.
@return [Symbol] consistency for request with conditional updates
(lightweight - compare-and-set, CAS - transactions). Must be one of {Cassandra::SERIAL_CONSISTENCIES}
@return [Numeric] request timeout interval
@return [Array] type hints for positional arguments for the statement
Public Class Methods
@private @param options [Hash] execution options to validate and encapsulate @param trusted_options [Options] (optional) base Execution::Options
from which
to create this new Options object.
# File lib/cassandra/execution/options.rb 79 def initialize(options, trusted_options = nil) 80 consistency = options[:consistency] 81 page_size = options[:page_size] 82 trace = options[:trace] 83 timeout = options[:timeout] 84 serial_consistency = options[:serial_consistency] 85 paging_state = options[:paging_state] 86 arguments = options[:arguments] 87 type_hints = options[:type_hints] 88 idempotent = options[:idempotent] 89 payload = options[:payload] 90 load_balancing_policy = options[:load_balancing_policy] 91 retry_policy = options[:retry_policy] 92 93 # consistency is a required attribute of an Options object. If we are creating 94 # an Options object from scratch (e.g. no trusted_options as base) validate the 95 # given consistency value (even if nil). Otherwise we're overlaying and only 96 # validate the consistency option if given. 97 if trusted_options.nil? || !consistency.nil? 98 Util.assert_one_of(CONSISTENCIES, consistency) do 99 ":consistency must be one of #{CONSISTENCIES.inspect}, " \ 100 "#{consistency.inspect} given" 101 end 102 end 103 104 # load_balancing_policy and retry_policy are required, but can fallback to trusted_options, just like 105 # consistency. 106 if trusted_options.nil? || !load_balancing_policy.nil? 107 methods = [:host_up, :host_down, :host_found, :host_lost, :setup, :teardown, 108 :distance, :plan] 109 Util.assert_responds_to_all(methods, load_balancing_policy, 110 ":load_balancing_policy #{load_balancing_policy.inspect} must respond " \ 111 "to #{methods.inspect}, but doesn't") 112 end 113 if trusted_options.nil? || !retry_policy.nil? 114 methods = [:read_timeout, :write_timeout, :unavailable] 115 Util.assert_responds_to_all(methods, retry_policy, 116 ":retry_policy #{retry_policy.inspect} must respond to #{methods.inspect}, " \ 117 "but doesn't") 118 end 119 120 unless serial_consistency.nil? 121 Util.assert_one_of(SERIAL_CONSISTENCIES, serial_consistency) do 122 ":serial_consistency must be one of #{SERIAL_CONSISTENCIES.inspect}, " \ 123 "#{serial_consistency.inspect} given" 124 end 125 end 126 127 unless page_size.nil? 128 page_size = Integer(page_size) 129 Util.assert(page_size > 0) do 130 ":page_size must be a positive integer, #{page_size.inspect} given" 131 end 132 end 133 134 unless timeout.nil? 135 Util.assert_instance_of(::Numeric, timeout) do 136 ":timeout must be a number of seconds, #{timeout} given" 137 end 138 Util.assert(timeout > 0) { ":timeout must be greater than 0, #{timeout} given" } 139 end 140 141 unless paging_state.nil? 142 paging_state = String(paging_state) 143 Util.assert_not_empty(paging_state) { ':paging_state must not be empty' } 144 145 # We require page_size in either the new options or trusted options. 146 Util.assert(!page_size.nil? || 147 !(trusted_options.nil? || trusted_options.page_size.nil?)) do 148 ':page_size is required when :paging_state is given' 149 end 150 end 151 152 # :arguments defaults to empty-list, but we want to delegate to trusted_options 153 # if it's set. So the logic is as follows: 154 # If an arguments option was given, validate and use it regardless of anything 155 # else. 156 # Otherwise, if we have trusted_options, leave arguments nil for now so as not 157 # to override trusted_options. Finally, if we don't have an arguments option 158 # nor do we have trusted_options, fall back to the default empty-list. 159 # 160 # :type_hints works exactly the same way. 161 if !arguments.nil? 162 Util.assert_instance_of_one_of([::Array, ::Hash], arguments) do 163 ":arguments must be an Array or a Hash, #{arguments.inspect} given" 164 end 165 elsif trusted_options.nil? 166 arguments = EMPTY_LIST 167 end 168 169 if !type_hints.nil? 170 Util.assert_instance_of_one_of([::Array, ::Hash], type_hints) do 171 ":type_hints must be an Array or a Hash, #{type_hints.inspect} given" 172 end 173 elsif trusted_options.nil? 174 type_hints = EMPTY_LIST 175 end 176 177 unless payload.nil? 178 Util.assert_instance_of(::Hash, payload) { ':payload must be a Hash' } 179 Util.assert_not_empty(payload) { ':payload must not be empty' } 180 Util.assert(payload.size <= 65535) do 181 ':payload cannot contain more than 65535 key/value pairs' 182 end 183 184 payload = payload.each_with_object(::Hash.new) do |(key, value), p| 185 p[String(key)] = String(value) 186 end 187 payload.freeze 188 end 189 190 # Ok, validation is done. Time to save off all our values in our instance vars, 191 # merging in values from trusted_options if it's set. To keep things readable, 192 # we just put this into two branches of an if-else. 193 194 if trusted_options.nil? 195 @consistency = consistency 196 @page_size = page_size 197 @trace = !!trace 198 @timeout = timeout 199 @serial_consistency = serial_consistency 200 @arguments = arguments 201 @type_hints = type_hints 202 @load_balancing_policy = load_balancing_policy 203 @retry_policy = retry_policy 204 else 205 @consistency = consistency || trusted_options.consistency 206 @page_size = page_size || trusted_options.page_size 207 @trace = trace.nil? ? trusted_options.trace? : !!trace 208 @timeout = options.key?(:timeout) ? timeout : trusted_options.timeout 209 @serial_consistency = serial_consistency || trusted_options.serial_consistency 210 @arguments = arguments || trusted_options.arguments 211 @type_hints = type_hints || trusted_options.type_hints 212 @load_balancing_policy = load_balancing_policy || trusted_options.load_balancing_policy 213 @retry_policy = retry_policy || trusted_options.retry_policy 214 end 215 216 # The following fields are *not* inherited from trusted_options, so we always 217 # rely on the options we were given. 218 @paging_state = paging_state 219 @idempotent = !!idempotent 220 @payload = payload 221 end
Public Instance Methods
@private
# File lib/cassandra/execution/options.rb 234 def eql?(other) 235 other.is_a?(Options) && 236 other.consistency == @consistency && 237 other.page_size == @page_size && 238 other.trace? == @trace && 239 other.timeout == @timeout && 240 other.serial_consistency == @serial_consistency && 241 other.paging_state == @paging_state && 242 other.arguments == @arguments && 243 other.type_hints == @type_hints && 244 other.load_balancing_policy == @load_balancing_policy && 245 other.retry_policy == @retry_policy 246 end
@return [Boolean] whether statement can be retried on timeout
# File lib/cassandra/execution/options.rb 229 def idempotent? 230 @idempotent 231 end
@private
# File lib/cassandra/execution/options.rb 250 def override(*options) 251 merged = options.unshift({}).inject do |base, opts| 252 # Skip nil args 253 next base unless opts 254 255 if opts.is_a?(Cassandra::Execution::Profile) 256 base.merge!(opts.to_h) 257 else 258 Util.assert_instance_of(::Hash, opts, "options must be a Hash, #{opts.inspect} given") 259 base.merge!(opts) 260 end 261 end 262 263 Options.new(merged, self) 264 end
@return [Boolean] whether request tracing was enabled
# File lib/cassandra/execution/options.rb 224 def trace? 225 @trace 226 end