Module: RiakRest::JiakResource::ClassMethods

Defined in:
lib/riakrest/resource/jiak_resource.rb

Overview

Class methods for creating a user-defined JiakResource.

See JiakResource for example usage.

Instance Method Summary collapse

Instance Method Details

#attr_accessor(*fields) ⇒ Object

:call-seq:

attr_accessor :f1,...,:fn

Add read/write accessible fields.



114
115
116
117
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 114

def attr_accessor(*fields)
  attr_reader *fields
  attr_writer *fields
end

#attr_converter(hash) ⇒ Object

:call-seq:

attr_converter(hash)

Specify a hash of optional Procs for converting data attribute values during reading and writing data to a Jiak server. Each hash key should be a data class attribute, with an associated value of a hash containing a write and/or a read Proc for use in converting data. Each Procs should accept one argument, the data value actually stored in Riak.



146
147
148
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 146

def attr_converter(hash)
  jiak.data.attr_converter(hash)
end

#attr_reader(*fields) ⇒ Object Also known as: attr

:call-seq:

attr_reader :f1,...,:fn

Add read accessible fields.



78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 78

def attr_reader(*fields)
  check_fields(fields)
  added_fields = jiak.data.readable(*fields)
  added_fields.each do |field|
    class_eval <<-EOM
      def #{field}
        @jiak.object.data.#{field}
      end
    EOM
  end
  nil
end

#attr_writer(*fields) ⇒ Object

:call-seq:

attr_writer :f1,...,:fn

Add write accessible fields.



96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 96

def attr_writer(*fields)
  check_fields(fields)
  added_fields = jiak.data.writable(*fields)
  added_fields.each do |field|
    class_eval <<-EOM
      def #{field}=(val)
        @jiak.object.data.#{field} = val
        self.class.do_auto_update(self)
      end
    EOM
  end
  nil
end

#auto_manage(state = true) ⇒ Object

:call-seq:

JiakResource.auto_manage(state)  -> true or false

Set auto-post and auto-manage simultaneously.



228
229
230
231
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 228

def auto_manage(state=true)
  auto_post state
  auto_update state
end

#auto_manage? ⇒ Boolean

:call-seq:

JiakResource.auto_update? -> true or false

true if JiakResource is set to auto-update.



237
238
239
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 237

def auto_manage?
  return auto_post? && auto_update?
end

#auto_post(state = true) ⇒ Object

:call-seq:

JiakResource.auto_post(state)  -> true or false

Set true to have new instances of the resource auto-posted to the Jiak server.

Default value for state is true. Note the default behavior for JiakResource is auto-post false.



184
185
186
187
188
189
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 184

def auto_post(state=true)
  unless (state.is_a?(TrueClass) || state.is_a?(FalseClass))
    raise JiakResource, "auto_post must be true or false"
  end
  jiak.auto_post = state
end

#auto_post? ⇒ Boolean

:call-seq:

JiakResource.auto_post? -> true or false

true if JiakResource is set to auto-post new instances.



195
196
197
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 195

def auto_post?
  return jiak.auto_post
end

#auto_update(state = true) ⇒ Object

:call-seq:

JiakResource.auto_update(state)  -> true or false

Set true to have changes to resource fields or links trigger an auto-update to the Jiak server. Interacts with the instance-level resource setting. See JiakResource#auto_update.

Default value for state is true. Note the default behavior for JiakResource is auto-update false.



208
209
210
211
212
213
214
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 208

def auto_update(state=true)
  state = false  if state.nil?
  unless (state.is_a?(TrueClass) || state.is_a?(FalseClass))
    raise JiakResource, "auto_update must be true or false"
  end
  jiak.auto_update = state
end

#auto_update? ⇒ Boolean

:call-seq:

JiakResource.auto_update? -> true or false

true if JiakResource is set to auto-update.



220
221
222
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 220

def auto_update?
  return jiak.auto_update
end

#bi_link(r1, r2, tag1_2, tag2_1 = nil) ⇒ Object

:call-seq:

JiakResource.bi_link(rscr1,rscr2,tag1_2,tag2_1=nil)  -> JiakResource

Link from rscr1 to rsrc2 using tag1_2 and from rscr2 to rsrc1 using tag2_1. tag2_1 defaults to tag1_2 if nil.



399
400
401
402
403
404
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 399

def bi_link(r1,r2,tag1_2,tag2_1=nil)
  tag2_1 ||= tag1_2
  link(r1,r2,tag1_2)
  link(r2,r1,tag2_1)
  r1
end

#delete(resource, opts = {}) ⇒ Object

:call-seq:

JiakResource.delete(resource,opts={})  -> true or false

Delete the JiakResource store on the Jiak server by the specified key.

Valid options:

:deletes — See JiakResource#params



360
361
362
363
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 360

def delete(resource,opts={})
  check_opts(opts,DELETE_PARAMS,JiakResourceException)
  jiak.client.delete(jiak.bucket,resource.jiak.object.key,opts)
end

#do_auto_update(rsrc) ⇒ Object

:call-seq:

JiakResource.do_auto_update(resource)  -> JiakResource or nil

Determine if an auto update should be done on the resource and perform an update if so.

Public method as a by-product of implementation.



480
481
482
483
484
485
486
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 480

def do_auto_update(rsrc)  # :no-doc:
  if(!rsrc.local? &&
     (rsrc.auto_update? ||
      ((rsrc.auto_update? != false) && rsrc.class.auto_update?)))
    update(rsrc)
  end
end

#exist?(key) ⇒ Boolean

:call-seq:

JiakResource.exist?(key) -> true or false

Determine if a resource exists on the Jiak server for a key.



469
470
471
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 469

def exist?(key)
  jiak.client.exist?(jiak.bucket,key)
end

#get(key, opts = {}) ⇒ Object

:call-seq:

JiakResource.get(key,opts={})  -> JiakResource

Get a JiakResource on the Jiak server by the specified key.

Valid options:

:reads — See JiakResource#params

Raise JiakResourceNotFound if no resource exists on the Jiak server for the key.



335
336
337
338
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 335

def get(key,opts={})
  check_opts(opts,GET_PARAMS,JiakResourceException)
  new(jiak.client.get(jiak.bucket,key,opts))
end

#group(gname) ⇒ Object

:call-seq:

JiakResource.group(gname)

Set the Jiak group name for the storage area of a resource.



69
70
71
72
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 69

def group(gname)
  jiak.group = gname
  jiak.bucket.name = gname
end

#keygen(&block) ⇒ Object

:call-seq:

JiakResource.keygen(&block)

Specify the block for generating keys for a JiakResource instance.



131
132
133
134
135
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 131

def keygen(&block)
  jiak.data.class_eval <<-EOS
    define_method(:keygen,&block)
  EOS
end

#keys ⇒ Object

:call-seq:

JiakResource.keys   -> array

Get an array of the current keys for this resource. Since key lists are updated asynchronously on a Riak cluster the returned array can be out of synch immediately after new puts or deletes.



275
276
277
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 275

def keys
  jiak.client.keys(jiak.bucket)
end

#link(from, to, tag) ⇒ Object

:call-seq:

JiakResource.link(from,to,tag)  -> JiakResource

Link from a resource to another resource by tag.

Note the resource being linked to cannot be a local object since the created link needs to include the Jiak server key. Even if a local object has a local key intended for use as the Jiak server key, there is no guarentee that key will not already be in use on the Jiak server. Only after a resource is stored on the Jiak server is the key assignment guarenteed.

This restriction is not necessary for the resource being linked from, since it’s Jiak server key is not in play. This does allow for establishing links to existing Jiak resources locally and storing with the initial store of the local Jiak resource.



381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 381

def link(from,to,tag)
  if(to.local?)
    raise JiakResourceException, "Can't link to a local resource"
  end

  link = JiakLink.new(to.jiak.object.bucket, to.jiak.object.key, tag)
  unless from.jiak.object.links.include?(link)
    from.jiak.object.links << link
    do_auto_update(from)
  end
  from
end

#params(opts = {}) ⇒ Object

:call-seq:

JiakResource.params(opts={})  -> hash

Default options for request parameters during Jiak interaction.

Valid options
:reads

Minimum number of responding nodes for successful reads.

:writes

Minimum number of responding nodes for successful writes. Writes can be buffered for performance.

:durable_writes

Minimum number of responding nodes that must perform a durable write to a persistence layer.

:deletes

Minimum number of responding nodes for successful delete.

The configuration of a Riak cluster includes server setting for writes, durable_writes, reads, and deletes parameters. None of these parameter are required by RiakRest, and their use within RiakRest is to override the Riak cluster settings, either at the JiakResource level or the individual request level.

Settings passed to individual get, put, post, update, refresh, and delete requests take precendence over the setting maintained by a JiakResource. Any parameter not set in JiakResource or on an individual request will default to the values set in the Riak cluster.



172
173
174
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 172

def params(opts={})
  jiak.client.params = opts
end

#post(resource, opts = {}) ⇒ Object

:call-seq:

JiakResource.post(JiakResource,opts={})  -> JiakResource

Put a JiakResource on the Jiak server with a guard to ensure the resource has not been previously stored.

See JiakResource#put for options.



304
305
306
307
308
309
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 304

def post(resource,opts={})
  unless(resource.local?)
    raise JiakResourceException, "Resource already initially stored"
  end
  put(resource,opts)
end

#push_schema(schema = nil) ⇒ Object

:call-seq:

JiakResource.push_schema  -> nil

Push schema to the Jiak server. If no schema is provided, pushes the schema associated with the JiakResource.



254
255
256
257
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 254

def push_schema(schema=nil)
  schema ||= jiak.bucket.schema
  jiak.client.set_schema(jiak.bucket.name,schema)
end

#put(resource, opts = {}) ⇒ Object

:call-seq:

JiakResource.put(JiakResource,opts={})  -> JiakResource

Put a JiakResource on the Jiak server.

Valid options:

:writes :durable_writes :reads

See JiakResource#params for description of options.



290
291
292
293
294
295
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 290

def put(resource,opts={})
  check_opts(opts,PUT_PARAMS,JiakResourceException)
  opts[:return] = :object
  resource.jiak.object = jiak.client.store(resource.jiak.object,opts)
  resource
end

#query(from, steps, opts = {}) ⇒ Object Also known as: walk

:call-seq:

JiakResource.query(from,steps,opts={})

Retrieves an array of JiakResource objects by starting with the links in the from JiakResource and performing the query steps. Steps is an array holding a series of query links designated by JiakResource,tag pairs. The type of JiakResources returned by the query is determined by the JiakResource class designated in the last step.

Note: Although Jiak supports accumulating intermediate link step results, since RiakRest auto-inflates returned data intermediate accumulation is not supported. The most common usage, however, is to only accumulate the last step as supported by RiakRest.

Usage

<code>

JiakResource.query(resource,[Child,'child'])
JiakResource.query(resource,[Parent,'odd',Child,'normal'])

</code>



440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 440

def query(from,steps,opts={})
  check_opts(opts,GET_PARAMS,JiakResourceException)
  begin
    links = []
    klass = nil
    steps.each_slice(2) do |pair|
      klass = pair[0]
      links << QueryLink.new(klass.jiak.bucket.name,pair[1],nil)
    end
    data_class = klass.jiak.bucket.data_class
    if(klass.include?(JiakResourcePOV))
      opts[:read] = klass.jiak.read_mask
    end
    jiak.client.walk(from.jiak.object.bucket,
                     from.jiak.object.key,
                     links,
                     data_class,
                     opts).map {|jobj| klass.new(jobj)}
  # rescue
  #   raise(JiakResourceException,
  #         "each step should be JiakResource,tag pair")
  end
end

#refresh(resource, opts = {}) ⇒ Object

:call-seq:

JiakResource.refresh(resource,opts={})  -> JiakResource

Updates a JiakResource with the data on the Jiak server. The current data of the JiakResource is overwritten, so use with caution.

See JiakResource#get for options.



347
348
349
350
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 347

def refresh(resource,opts={})
  check_opts(opts,GET_PARAMS,JiakResourceException)
  resource.jiak.object = get(resource.jiak.object.key,opts).jiak.object
end

#remove_link(from, to, tag) ⇒ Object

:call-seq:

JiakResource.remove_link(from,to,tag) -> true or false



408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 408

def remove_link(from,to,tag)
  link = JiakLink.new(to.jiak.object.bucket, to.jiak.object.key, tag)
  has_link = from.jiak.object.links.include?(link)
  if has_link
    from.jiak.object.links.delete(link)
    if(from.auto_update? ||
       ((from.auto_update? != false) && from.class.auto_update?))
      put(from)
    end
  end
  has_link
end

#schema ⇒ Object

:call-seq:

JiakResource.schema  -> JiakSchema

Get the schema for a resource.



245
246
247
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 245

def schema
  jiak.data.schema
end

#server(uri, opts = {}) ⇒ Object

:call-seq:

JiakResource.server(uri,opts={})

Set the URI for Jiak server interaction. Go through a proxy if proxy option specified.

Valid options:
<code>:proxy</code> -- Proxy server URI.



60
61
62
63
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 60

def server(uri,opts={})
  jiak.client = JiakClient.new(uri,opts)
  jiak.uri = uri
end

#server_schema?(schema = nil) ⇒ Boolean

:call-seq:

JiakResource.server_schema?  -> true or false

Determine if a schema is that set on the Jiak server. If no schema is provided, use the schema associated with the JiakResource.



264
265
266
267
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 264

def server_schema?(schema=nil)
  schema ||= jiak.bucket.schema
  jiak.client.schema(jiak.bucket).eql? schema
end

#update(resource, opts = {}) ⇒ Object

:call-seq:

JiakResource.update(JiakResource,opts={})  -> JiakResource

Updates a JiakResource on the Jiak server with a guard to ensure the resource has been previously stored.

See JiakResource#put for options.



318
319
320
321
322
323
 
# File 'lib/riakrest/resource/jiak_resource.rb', line 318

def update(resource,opts={})
  if(resource.local?)
    raise JiakResourceException, "Resource not previously stored"
  end
  put(resource,opts)
end