class Cassandra::Execution::Options

Attributes

arguments[R]

@return [Array] positional arguments for the statement

consistency[R]

@return [Symbol] consistency for request. Must be one of

{Cassandra::CONSISTENCIES}
load_balancing_policy[R]

@return [Cassandra::LoadBalancing::Policy] load-balancing policy that determines which node will run the

next statement.
page_size[R]

@return [Integer] requested page size

paging_state[R]

@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.

@see Cassandra::Result#paging_state

payload[R]

@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')
         })
retry_policy[R]

@return [Cassandra::Retry::Policy] retry policy that determines how request retries should be handled for

different failure modes.
serial_consistency[R]

@return [Symbol] consistency for request with conditional updates

(lightweight - compare-and-set, CAS - transactions). Must be one of
{Cassandra::SERIAL_CONSISTENCIES}
timeout[R]

@return [Numeric] request timeout interval

type_hints[R]

@return [Array] type hints for positional arguments for the statement

Public Class Methods

new(options, trusted_options = nil) click to toggle source

@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

==(other)
Alias for: eql?
eql?(other) click to toggle source

@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
Also aliased as: ==
idempotent?() click to toggle source

@return [Boolean] whether statement can be retried on timeout

    # File lib/cassandra/execution/options.rb
229 def idempotent?
230   @idempotent
231 end
override(*options) click to toggle source

@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
trace?() click to toggle source

@return [Boolean] whether request tracing was enabled

    # File lib/cassandra/execution/options.rb
224 def trace?
225   @trace
226 end