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

InstanceMethods

Attributes

Instance Attributes

database [W] public

sets the database.

Public Visibility

Public Instance Method Summary

#commit(defer = false) #save!

Saves an Aqua::Storage instance to CouchDB as a document.

Returns: Aqua::Storage

#database

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

Returns: Aqua::Store::CouchDB::Database

#delete(defer = false)

Deletes an document from CouchDB.

Returns: String

#delete!(defer = false)

Deletes an document from CouchDB.

Returns: String

#delete_logic(defer = false, mask_exceptions = true)

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

Returns: String

#delete_now

Internal logic used by delete_logic delete a resource immediately.

Returns: String

#determine_database

Looks to CouchDB.

#ensure_id

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

#escape_doc_id

Escapes document id.

#escape_for_id(str)

Escapes a string for id usage.

#exists?

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

Returns: true

#id

setters and getters couchdb document specifics ----------------- Gets the document id.

Returns: String

#id=(str)

Allows the id to be set.

Returns: String

#new? #new_document?

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

Returns: true

#retrieve

retrieves self from CouchDB database.

Returns: Hash

#rev

Returns CouchDB document revision identifier.

Returns: String

#rev=(str)
#revisions

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

Returns: Array

#save(defer = false)

Saves an Aqua::Storage instance to CouchDB as a document.

Returns: Aqua::Storage

#save_logic(defer = false, mask_exception = true)

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

Returns: Aqua::Storage

#save_now(mask_exception = true)

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

Returns: Aqua::Storage

#update_version(result)

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

#uri

couchdb database url for this document.

Returns: String

Public Instance Method Details

commit

public Aqua::Storage commit(defer = false)

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.

Meta Tags

Returns:

[Aqua::Storage]

On success.

[View source] 


86
87
88
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 86

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

database

public Aqua::Store::CouchDB::Database database

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

Meta Tags

Returns:

[Aqua::Store::CouchDB::Database]
[View source] 


241
242
243
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 241

def database
  @database ||= determine_database
end

delete

public String delete(defer = false)

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

Meta Tags

Returns:

[String, false]

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

[View source] 


161
162
163
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 161

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

delete!

public String delete!(defer = 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.

Meta Tags

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:

[Object]

Any of the CouchDB exceptions

[View source] 


172
173
174
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 172

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

delete_logic

public String delete_logic(defer = false, mask_exceptions = true)

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

Meta Tags

Returns:

[String, false]

Depening on the type of execption masking and also the outcome

Raises:

[Object]

Any of the CouchDB execptions.

[View source] 


184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 184

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

public String delete_now

Internal logic used by delete_logic delete a resource immediately.

Meta Tags

Returns:

[String, false]

Depening on the type of execption masking and also the outcome

Raises:

[Object]

Any of the CouchDB execptions.

[View source] 


206
207
208
209
210
211
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 206

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

determine_database

public determine_database

Looks to CouchDB.database_strategy for 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.

Meta Tags

Todo Item:

  • Build the strategies in CouchDB. Use them here
[View source] 


250
251
252
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 250

def determine_database
  Database.create # defaults to database 'aqua' using default server :aqua   
end

ensure_id

public ensure_id

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

Meta Tags

[View source] 


332
333
334
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 332

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

escape_doc_id

public escape_doc_id

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

Meta Tags

[View source] 


338
339
340
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 338

def escape_doc_id
  escape_for_id( id )
end

escape_for_id

public escape_for_id(str)

Escapes a string for id usage

Meta Tags

[View source] 


344
345
346
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 344

def escape_for_id( str )
  str.match(/^_design\/(.*)/) ? "_design/#{CGI.escape($1)}" : CGI.escape(str)
end

exists?

public true exists?

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

Meta Tags

Returns:

[true, false]
[View source] 


321
322
323
324
325
326
327
328
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 321

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

id

public String id

setters and getters couchdb document specifics ----------------- 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.

Meta Tags

Returns:

[String]
[View source] 


263
264
265
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 263

def id
  self[:id]
end

id=

public String id=(str)

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

Meta Tags

Returns:

[String, false]

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

[View source] 


274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 274

def id=( str )
  if str.respond_to?(:match)
    escaped = escape_for_id( 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

new?

public true new?

Also known as: new_document?

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

Meta Tags

Returns:

[true, false]
[View source] 


313
314
315
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 313

def new?
  !rev
end

retrieve

public Hash retrieve

retrieves self from CouchDB database

Meta Tags

Returns:

[Hash]

representing the CouchDB data

[View source] 


151
152
153
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 151

def retrieve
  self.class.new( CouchDB.get( uri ) )
end

rev

public String rev

Returns CouchDB document revision identifier.

Meta Tags

Returns:

[String]
[View source] 


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

def rev
  self[:_rev]
end

rev=

public rev=(str)
[View source] 


297
298
299
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 297

def rev=( str )
  self[:_rev] = str
end

revisions

public Array revisions

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

Meta Tags

Returns:

[Array]

Containing strings with revision numbers

[View source] 


218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 218

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

public Aqua::Storage save(defer = false)

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

Meta Tags

Returns:

[Aqua::Storage, false]

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

[View source] 


75
76
77
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 75

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

save_logic

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

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

Meta Tags

Returns:

[Aqua::Storage, false]

Depening on the type of execption masking and also the outcome

Raises:

[Object]

Any of the CouchDB execptions.

[View source] 


99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 99

def save_logic( defer=false, mask_exception = true )
  encode_attachments if self[:_attachment] 
  ensure_id
  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

public Aqua::Storage save_now(mask_exception = true)

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

Meta Tags

Returns:

[Aqua::Storage, false]

Depening on the type of execption masking and also the outcome

Raises:

[Object]

Any of the CouchDB execptions.

[View source] 


122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 122

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

public update_version(result)

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

Meta Tags

[View source] 


305
306
307
308
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 305

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

uri

public String uri

couchdb database url for this document

Meta Tags

Returns:

[String]

representing CouchDB uri for document

[View source] 


144
145
146
 
# File 'lib/aqua/store/couch_db/storage_methods.rb', line 144

def uri
  database.uri + '/' + ensure_id
end
Generated on Friday, August 21 2009 at 12:48:49 PM by YARD 0.2.3.5 (ruby-1.8.6).