Module: Aqua::Store::CouchDB::StorageMethods::InstanceMethods

Defined in:
lib/aqua/store/couch_db/storage_methods.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#database ⇒ Aqua::Store::CouchDB::Database

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

retrieves the previously set database or sets the new one with a default value

Returns:



456
457
458
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 456

def database
  @database ||= determine_database
end

Instance Method Details

#attachments ⇒ Hash

Hash of attachments, keyed by name

Returns:

  • (Hash) —

    Attachments keyed by name



562
563
564
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 562

def attachments
  @attachments ||= Attachments.new( self )
end

#commit(defer = false) ⇒ Aqua::Storage Also known as: save!

Saves an Aqua::Storage instance to CouchDB as a document. Save can be deferred for bulk saving from the database. Unlike #save, this method will raise an error if the document is not saved.

Parameters:

  • Determines (optional true, false) —

    whether the document is cached for bulk saving later. true will cause it to be defered. Default is false.

Returns:



292
293
294
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 292

def commit( defer=false )
  save_logic( defer, false )
end

#delete(defer = false) ⇒ String, false

Deletes an document from CouchDB. Delete can be deferred for bulk saving/deletion.

Parameters:

  • Determines (optional true, false) —

    whether the document is cached for bulk saving later. true will cause it to be defered. Default is false.

Returns:

  • (String, false) —

    Will return a json string with the response if successful. Otherwise returns false.



376
377
378
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 376

def delete(defer = false)
  delete_logic( defer )
end

#delete!(defer = false) ⇒ String, false

Deletes an document from CouchDB. Delete can be deferred for bulk saving/deletion. This version raises an exception if an error other that resource not found is raised.

Parameters:

  • Determines (optional true, false) —

    whether the document is cached for bulk saving later. true will cause it to be defered. Default is false.

Returns:

  • (String, false) —

    Will return a json string with the response if successful. It will return false if the resource was not found. Other exceptions will be raised.

Raises:

  • Any of the CouchDB exceptions



387
388
389
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 387

def delete!(defer = false)
  delete_logic( defer, false ) 
end

#delete_logic(defer = false, mask_exceptions = true) ⇒ String, false

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Internal logic used by delete and delete! to delete a resource.

Parameters:

  • Determines (optional true, false) —

    whether resource is deleted immediately or saved for bulk processing.

  • Determines (optional true, false) —

    whether an exception is raised or whether false is returned.

Returns:

  • (String, false) —

    Depening on the type of execption masking and also the outcome

Raises:

  • Any of the CouchDB execptions.



399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 399

def delete_logic( defer = false, mask_exceptions = true )
  if defer
    database.add_to_bulk_cache( { '_id' => self['_id'], '_rev' => rev, '_deleted' => true } )
  else
    begin
      delete_now
    rescue Exception => e
      if mask_exceptions || e.class == CouchDB::ResourceNotFound
        false
      else 
        raise e
      end    
    end  
  end 
end

#delete_now ⇒ String, false

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Internal logic used by delete_logic delete a resource immediately.

Returns:

  • (String, false) —

    Depening on the type of execption masking and also the outcome

Raises:

  • Any of the CouchDB execptions.



421
422
423
424
425
426
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 421

def delete_now
  revisions.each do |rev_id| 
    CouchDB.delete( "#{uri}?rev=#{rev_id}" )
  end
  true   
end

#determine_database ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

TODO:

Build the strategies in CouchDB. Use them here

Looks to class for database information about how the CouchDB store has generally been configured to store its data across databases and/or servers. In some cases the class for the parent object has configuration details about the database and server to use.



465
466
467
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 465

def determine_database
  self.class.database    
end

#do_rev(hash, override = false) ⇒ Object

TODO:

The get method has to handle rev better!!!

Temporary hack to allow design document refresh from within a doc.



269
270
271
272
273
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 269

def do_rev( hash, override=false )
  hash.delete(:rev)   # This is omited to aleviate confusion 
  # CouchDB determines _rev attribute on saving, but when #new is loading json passed from the 
  # database rev needs to be added to the class. So, the :_rev param is not being deleted anymore
end

#ensure_id ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

gets a uuid from the server if one doesn’t exist, otherwise escapes existing id.



547
548
549
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 547

def ensure_id
  self[:_id] = ( id ? escape_doc_id : database.server.next_uuid )
end

#escape_doc_id ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Escapes document id. Different strategies for design documents and normal documents.



553
554
555
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 553

def escape_doc_id 
  CGI.escape( id )
end

#exists? ⇒ true, false

Returns true if a document exists at the CouchDB uri for this document. Otherwise returns false

Returns:

  • (true, false) 


536
537
538
539
540
541
542
543
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 536

def exists?
  begin 
    CouchDB.get uri
    true
  rescue
    false
  end    
end

#id ⇒ String

Gets the document id. In this engine id and _id are different data. The main reason for this is that CouchDB needs a relatively clean string as the key, where as the user can assign a messy string to the id. The user can continue to use the messy string since the engine also has access to the _id.

Returns:



478
479
480
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 478

def id
  self[:id]
end

#id=(str) ⇒ String, false

Allows the id to be set. If the id is changed after creation, then the CouchDB document for the old id is deleted, and the _rev is set to nil, making it a new document. The id can only be a string (right now).

return false.

Returns:

  • (String, false) —

    Will return the string it received if it is indeed a string. Otherwise it will



489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 489

def id=( str )
  if str.respond_to?(:match)
    escaped = CGI.escape( str )
    
    # CLEANUP: do a bulk delete request on the old id, now that it has changed
    delete(true) if !new? && escaped != self[:_id]
    
    self[:id] = str
    self[:_id] = escaped 
    str 
  end  
end

#initialize(hash = {}) ⇒ Aqua::Storage

Initializes a new storage document.

Parameters:

Returns:



255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 255

def initialize( hash={} )
  hash = Mash.new( hash ) unless hash.empty?
  
  hashed_id = hash.delete(:id) || hash.delete(:_id)
  self.id = hashed_id if hashed_id

  do_rev( hash )
  
  # feed the rest of the hash to the super 
  super( hash )      
end

#new? ⇒ true, false Also known as: new_document?

Returns true if the document has never been saved or false if it has been saved.

Returns:

  • (true, false) 


528
529
530
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 528

def new?
  !rev
end

#retrieve ⇒ Hash Also known as: reload

retrieves self from CouchDB database

Returns:

  • (Hash) —

    representing the CouchDB data



357
358
359
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 357

def retrieve
  self.class.get( id )
end

#rev ⇒ String

Returns CouchDB document revision identifier.

Returns:



507
508
509
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 507

def rev
  self[:_rev]
end

#revisions ⇒ Array

Gets revision history, which is needed by Delete to remove all versions of a document

Returns:

  • (Array) —

    Containing strings with revision numbers



433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 433

def revisions
  active_revisions = []
  begin
    hash = CouchDB.get( "#{uri}?revs_info=true" )
  rescue
    return active_revisions
  end    
  hash['_revs_info'].each do |rev_hash|
    active_revisions << rev_hash['rev'] if ['disk', 'available'].include?( rev_hash['status'] )
  end
  active_revisions  
end

#save(defer = false) ⇒ Aqua::Storage, false

Saves an Aqua::Storage instance to CouchDB as a document. Save can be deferred for bulk saving.

Parameters:

  • Determines (optional true, false) —

    whether the document is cached for bulk saving later. true will cause it to be defered. Default is false.

Returns:

  • (Aqua::Storage, false) —

    Will return false if the document is not saved. Otherwise it will return the Aqua::Storage object.



281
282
283
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 281

def save( defer=false )
  save_logic( defer )  
end

#save_logic(defer = false, mask_exception = true) ⇒ Aqua::Storage, false

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Internal logic used by save, save! and commit to save an object.

Parameters:

  • Determines (optional true, false) —

    whether a object cached for save in the database in bulk. By default this is false.

  • Determines (optional true, false) —

    whether an exception is raised or whether false is returned.

Returns:

  • (Aqua::Storage, false) —

    Depening on the type of execption masking and also the outcome

Raises:

  • Any of the CouchDB execptions.



305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 305

def save_logic( defer=false, mask_exception = true )
  ensure_id
  self[:_attachments] = attachments.pack unless attachments.empty?
  if defer
    database.add_to_bulk_cache( self )
  else
    # clear any bulk saving left over ...
    database.bulk_save if database.bulk_cache.size > 0
    if mask_exception
      save_now
    else
      save_now( false )
    end       
  end 
end

#save_now(mask_exception = true) ⇒ Aqua::Storage, false

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Internal logic used by save_logic to save an object immediately instead of deferring for bulk save.

Parameters:

  • Determines (optional true, false) —

    whether an exception is raised or whether false is returned.

Returns:

  • (Aqua::Storage, false) —

    Depening on the type of execption masking and also the outcome

Raises:

  • Any of the CouchDB execptions.



328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 328

def save_now( mask_exception = true ) 
  begin
    result = CouchDB.put( uri, self )
  rescue Exception => e
    if mask_exception
      result = false
    else
      raise e
    end    
  end

  if result && result['ok']
    update_version( result )
    self
  else    
    result 
  end 
end

#update_version(result) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Updates the id and rev after a document is successfully saved.

Parameters:

  • Result (Hash) —

    returned by CouchDB document save



520
521
522
523
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 520

def update_version( result ) 
  self.id     = result['id']
  self.rev    = result['rev']
end

#uri ⇒ String

couchdb database url for this document

Returns:

  • (String) —

    representing CouchDB uri for document



350
351
352
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 350

def uri
  database.uri + '/' + ensure_id
end