The Datastore provides access to a schema-less data storage system. The fundamental unit of data in this system is the Datastore::Entity, which has an immutable identity (represented by a Datastore::Key) and zero of more mutable properties. Entity objects can be created, updated, deleted, retrieved by identifier, and queried via a combination of properties using Datastore::Query.

The Datastore can be used transactionally and supports the notion of a “current” transaction. A current transaction is established by calling begin_transaction. The transaction returned by this method ceases to be current when an attempt is made to commit or rollback or when another call is made to begin_transaction. A transaction can only be current within the Thread that created it.

The various overloads of put, get, and delete all support transactions. Users of this class have the choice of explicitly passing a (potentially null) Transaction to these methods or relying on the current transaction.

Supported property types:

Methods
Classes and Modules
Constants
JavaDatastore = Java.ComGoogleAppengineApiDatastore
Key = JavaDatastore::Key
Entity = JavaDatastore::Entity
SPECIAL_RUBY_TYPES = [Time, Text, Blob, ByteString, Link].freeze
Instance Public methods
active_transactions()

Returns all Transactions started by this thread upon which no attempt to commit or rollback has been made.

Source: show 

# File lib/appengine-apis/datastore.rb, line 183
  def active_transactions
    convert_exceptions do
      @@db.active_transactions
    end
  end
begin_transaction()

Begins a transaction agains the datastore. Callers are responsible for explicitly calling Transaction.commit or Transaction.rollback when they no longer need the Transaction.

The Transaction returned by this call will be considered the current transaction and will be returned by subsequent, same-thread calls to current_transaction until one of the following happens:

  1. begin_transaction is invoked from the same thread. In this case current_transaction will return the result of the more recent call to begin_transaction.
  2. Transaction.commit is invoked on the Transaction returned by this method. Whether or not the commit succeeds, the Transaction will no longer be current.
  3. Transaction.rollback is invoked on the Transaction returned by this method. Whether or not the rollback succeeds, the Transaction will no longer be current.

Source: show 

# File lib/appengine-apis/datastore.rb, line 157
  def begin_transaction
    convert_exceptions do
      @@db.begin_transaction
    end
  end
Datastore.current_transaction → transaction || IndexError Datastore.current_transaction(default) → transaction

Returns the current transaction for this thread. The current transaction is defined as the result of the most recent, same-thread invocation of begin_transaction that has not been committed or rolled back.

Raises IndexError if there is no current transaction and no default is specified.

Source: show 

# File lib/appengine-apis/datastore.rb, line 174
  def current_transaction(*args)
    convert_exceptions do
      @@db.current_transaction(*args)
    end
  end
Datastore.delete(transaction=current_transaction, key) Datastore.delete(transaction=current_transaction, [keys])

Deletes one or more entities from the datastore.

If transaction is specified this operation will execute within that transaction instead of the current transaction.

Source: show 

# File lib/appengine-apis/datastore.rb, line 132
  def delete(*args)
    convert_exceptions do
      args = extract_tx(args)
      @@db.delete(*args)
    end
  end
Datastore.get(transaction=current_transaction, key) → Entity Datastore.get(transaction=current_transaction, [keys]) → Entities

Retrieves one or more entities from the datastore.

Retrieves the entity or entities with the given key(s) from the datastore and returns them as fully populated Entity objects, as defined below. If there is an error, raises a subclass of Datastore::Error.

With a single key, an Entity will be returned, or EntityNotFound will be raised if no existing entity matches the key.

With an array of keys, an array of entities will be returned that corresponds to the sequence of keys. It will include entities for keys that were found and None placeholders for keys that were not found.

If transaction is specified, it will be used instead of the current transaction.

Source: show 

# File lib/appengine-apis/datastore.rb, line 87
  def get(*args)
    convert_exceptions do
      args = extract_tx(args)
      entities = @@db.get(*args)
      if entities.kind_of? java.util.Map
        keys = args[-1]
        entities = keys.collect do |key|
          entities.get(key)
        end
      end
      entities
    end
  end
Datastore.put(transaction=current_transaction, entity) → Key Datastore.put(transaction=current_transaction, entities) → Keys

Store one or more entities in the datastore.

The entities may be new or previously existing. For new entities, put will fill in the app id and key assigned by the datastore.

If the argument is a single Entity, a single Key will be returned. If the argument is an array of Entity, an Enumerable of Keys will be returned.

If transaction is specified this operation will execute within that transaction instead of the current transaction.

Source: show 

# File lib/appengine-apis/datastore.rb, line 116
  def put(*args)
    convert_exceptions do
      args = extract_tx(args)
      @@db.put(*args)
    end
  end
transaction(retries=0)

Runs the block inside a transaction. Every get, put, and delete call in the block is made within the transaction, unless another transaction is explicitly specified.

The block may raise any exception to roll back the transaction instead of committing it. If this happens, the transaction will be rolled back and the exception will be re-raised up to transaction’s caller.

If you want to roll back intentionally, but don’t have an appropriate exception to raise, you can raise an instance of Datastore::Rollback. It will cause a rollback, but will not be re-raised up to the caller.

If retries is greater than 0 and the transaction fails to commit, the block may be run more than once, so it should be idempotent. It should avoid side effects, and it shouldn’t have any side effects that aren’t safe to occur multiple times. However, this doesn’t include Put, Get, and Delete calls, of course.

Source: show 

# File lib/appengine-apis/datastore.rb, line 207
  def transaction(retries=0)
    while retries >= 0
      retries -= 1
      tx = begin_transaction
      begin
        result = yield
        tx.commit
        return result
      rescue Rollback
        tx.rollback
        return nil
      rescue TransactionFailed
        raise ex unless retries >= 0
      ensure
        begin
          tx.rollback
        rescue java.lang.IllegalStateException
          # already commited/rolled back. ignore
        rescue java.util.NoSuchElementException
          # already commited/rolled back. ignore
        end
      end
    end
    raise TransactionFailed
  end