appengine-apis 0.0.1

data/History.txt

@@ -0,0 +1,3 @@
+== 0.0.1 2009-04-02
+
+* Initial release

data/Manifest.txt

@@ -0,0 +1,21 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+lib/appengine-apis.rb
+lib/appengine-apis/apiproxy.rb
+lib/appengine-apis/datastore.rb
+lib/appengine-apis/datastore_types.rb
+lib/appengine-apis/logger.rb
+lib/appengine-apis/merb-logger.rb
+lib/appengine-apis/testing.rb
+script/console
+script/destroy
+script/generate
+spec/datastore_spec.rb
+spec/datastore_types_spec.rb
+spec/logger_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake

data/PostInstall.txt

@@ -0,0 +1,12 @@
+
+To use the local datastore you need to have the Google App Engine SDK for Java
+installed
+(http://code.google.com/appengine/docs/java/gettingstarted/installing.html).
+Then you need to add several jars to your classpath.
+
+For example:
+$ export SDK=`pwd`/appengine-java-sdk/lib
+$ export CLASSPATH=$SDK/shared/appengine-local-runtime-shared.jar:$SDK/impl/appengine-api-stubs.jar:$SDK/impl/appengine-api.jar:$SDK/impl/appengine-local-runtime.jar
+
+For more information on appengine-apis, see
+http://code.google.com/p/appengine-jruby

data/README.rdoc

@@ -0,0 +1,27 @@
+= appengine-apis
+
+* http://code.google.com/p/appengine-jruby
+
+== DESCRIPTION:
+
+APIs and utilities for using JRuby on Google App Engine.
+
+== REQUIREMENTS:
+
+* Google App Engine SDK for Java (http://code.google.com/appengine)
+
+== LICENSE:
+
+Copyright 2009 Google Inc
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/Rakefile

@@ -0,0 +1,28 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/appengine-apis'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('appengine-apis', AppEngine::VERSION) do |p|
+  p.developer('Ryan Brown', 'ribrdb@gmail.com')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt' 
+  p.rubyforge_name       = 'appengine-jruby'
+  # p.extra_deps         = [
+  #   ['activesupport','>= 2.0.2'],
+  # ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/lib/appengine-apis.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/ruby1.8 -w
+#
+# Copyright:: Copyright 2009 Google Inc.
+# Original Author:: Ryan Brown (mailto:ribrdb@google.com)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+module AppEngine
+  VERSION = '0.0.1'
+end

data/lib/appengine-apis/apiproxy.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/ruby1.8 -w
+#
+# Copyright:: Copyright 2009 Google Inc.
+# Original Author:: Ryan Brown (mailto:ribrdb@google.com)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+#
+# Ruby interface to the Java ApiProxy.
+
+require 'java'
+
+module AppEngine
+  
+  import Java.com.google.apphosting.api.ApiProxy
+  
+  class << ApiProxy
+    def get_app_id
+      get_current_environment.getAppId
+    end
+  
+    def get_auth_domain
+      get_current_environment.getAuthDomain
+    end
+    
+    alias :add_log_record :log
+    
+    def log(level, message)
+      message = (message || "").to_s.chomp
+      return if message.nil? || message.empty?
+      record = AppEngine::ApiProxy::LogRecord.new(
+          level, java.lang.System.currentTimeMillis() * 1000, message.to_s)
+      add_log_record(record)
+    end
+  end
+end
+

data/lib/appengine-apis/datastore.rb

@@ -0,0 +1,515 @@
+#!/usr/bin/ruby1.8 -w
+#
+# Copyright:: Copyright 2009 Google Inc.
+# Original Author:: Ryan Brown (mailto:ribrdb@google.com)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+#
+# The Ruby datastore API used by app developers.
+#
+# Defines the Query class, as well as methods for all of the
+# datastore's calls. Also defines conversions between the Ruby classes and
+# their Java counterparts.
+#
+# The datastore errors are defined in datastore_types.rb.
+
+require 'appengine-apis/apiproxy'
+require 'appengine-apis/datastore_types'
+
+module AppEngine
+  
+# The +Datastore+ provides access to a schema-less data
+# storage system.  The fundamental unit of data in this system is the
+# +Entity+, which has an immutable identity (represented by a
+# +Key+) and zero of more mutable properties.  +Entity+
+# objects can be created, updated, deleted, retrieved by identifier,
+# and queried via a combination of properties.
+#
+# 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.
+#
+module Datastore
+  module_function
+  
+  # call-seq:
+  #   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.
+  #
+  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
+  
+  # call-seq:
+  #   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.
+  #
+  def put(*args)
+    convert_exceptions do
+      args = extract_tx(args)
+      @@db.put(*args)
+    end
+  end
+  
+  # call-seq:
+  #   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.
+  #
+  def delete(*args)
+    convert_exceptions do
+      args = extract_tx(args)
+      @@db.delete(*args)
+    end
+  end
+  
+  # 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.
+  #
+  def begin_transaction
+    convert_exceptions do
+      @@db.begin_transaction
+    end
+  end
+  
+  # call-seq:
+  #   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.
+  #
+  def current_transaction(*args)
+    convert_exceptions do
+      @@db.current_transaction(*args)
+    end
+  end
+  
+  # Returns all Transactions started by this thread upon which no
+  # attempt to commit or rollback has been made.
+  #
+  def active_transactions
+    convert_exceptions do
+      @@db.active_transactions
+    end
+  end
+  
+  # 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.
+  #
+  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
+  
+  def extract_tx(args)  # :nodoc:
+    tx = :none
+    keys = args[0]
+    if keys.java_kind_of?(JavaDatastore::Transaction) || keys.nil?
+      tx = args.shift
+      keys = args[0]
+    end
+    if args.size > 1
+      keys = args
+    end
+    if keys.kind_of? Array
+      keys = Iterable.new(keys)
+    end
+    if tx == :none
+      [keys]
+    else
+      [tx, keys]
+    end
+  end
+  
+  def service  # :nodoc:
+    @@db
+  end
+  
+  # Query encapsulates a request for zero or more
+  # Entity objects out of the datastore.  It supports querying on
+  # zero or more properties, querying by ancestor, and sorting.  
+  # Entity objects which match the query can be retrieved in a single
+  # list, or with an unbounded iterator.
+  #
+  # A Query does not cache results. Each use of the Query results in a new
+  # trip to the Datastore.
+  #
+  class Query
+    JQuery = JavaDatastore::Query
+    FetchOptions = JavaDatastore::FetchOptions
+    
+    module Constants
+      [JQuery::FilterOperator, JQuery::SortDirection].each do |enum|
+        enum.constants.each do |name|
+          const_set(name, enum.const_get(name))
+        end
+      end
+    end
+    include Constants
+    
+    # call-seq:
+    #   Query.new(kind)
+    #   Query.new(ancestor)
+    #   Query.new(kind, ancestor)
+    #
+    # Creates a new Query with the specified kind and/or ancestor.
+    # 
+    # Args:
+    # - kind: String. Only return entities with this kind.
+    # - ancestor: Key. Only return entities with the given ancestor.
+    #
+    def initialize(*args)
+      @query = JQuery.new(*args)
+    end
+    
+    def kind
+      @query.kind
+    end
+    
+    
+    def ancestor
+      @query.ancestor
+    end
+    
+    # Sets an ancestor for this query.
+    #
+    # This restricts the query to only return result entities that are
+    # descended from a given entity. In other words, all of the results
+    # will have the ancestor as their parent, or parent's parent, or
+    # etc.
+    #
+    # If nil is specified, unsets any previously-set ancestor.
+    #
+    # Throws ArgumentError if the ancestor key is incomplete, or if
+    # you try to unset an ancestor and have not set a kind.
+    #
+    def ancestor=(key)
+      Datastore.convert_exceptions do
+        @query.set_ancestor(key)
+      end
+      clear_cache
+    end
+
+    # call-seq:
+    #   query.set_ancestor(key) -> query
+    #
+    # Sets an ancestor for this query.
+    #
+    # This restricts the query to only return result entities that are
+    # descended from a given entity. In other words, all of the results
+    # will have the ancestor as their parent, or parent's parent, or
+    # etc.
+    #
+    # If nil is specified, unsets any previously-set ancestor.
+    #
+    # Throws ArgumentError if the ancestor key is incomplete, or if
+    # you try to unset an ancestor and have not set a kind.
+    #
+    def set_ancestor(key)
+      self.ancestor = key
+      self
+    end
+    
+    # Add a filter on the specified property.
+    #
+    # Note that entities with multi-value properties identified by name
+    # will match this filter if the multi-value property has at least one
+    # value that matches the condition expressed by +operator+ and
+    # +value+.  For more information on multi-value property filtering
+    # please see the {datastore 
+    # documentation}[http://code.google.com/appengine/docs/java/datastore]
+    #
+    def filter(name, operator, value)
+      name = name.to_s if name.kind_of? Symbol
+      value = Datastore.ruby_to_java(value)
+      @query.add_filter(name, operator, value)
+      clear_cache
+    end
+    
+    # Specify how the query results should be sorted.
+    #
+    # The first call to #sort will register the property that will
+    # serve as the primary sort key.  A second call to #sort will set
+    # a secondary sort key, etc.
+    #
+    # This method will sort in ascending order by defaul. To control the
+    # order of the sort, pass ASCENDING or DESCENDING as the direction.
+    #
+    # Note that entities with multi-value properties identified by
+    # name will be sorted by the smallest value in the list.
+    # For more information on sorting properties with multiple values please see
+    # the {datastore 
+    # documentation}[http://code.google.com/appengine/docs/java/datastore].
+    #
+    # Returns self (for chaining)
+    #
+    def sort(name, direction=ASCENDING)
+      name = name.to_s if name.kind_of? Symbol
+      @query.add_sort(name, direction)
+      clear_cache
+    end
+    
+    # Returns an unmodifiable list of the current filter predicates.
+    def filter_predicates
+      @query.getFilterPredicates
+    end
+    
+    # Returns an unmodifiable list of the current sort predicates.
+    def sort_predicates
+      @query.getSortPredicates
+    end
+    
+    # Returns the number of entities that currently match this query.
+    def count
+      pquery.count
+    end
+    
+    # Retrieves the one and only result for the {@code Query}.
+    # 
+    # Throws TooManyResults if more than one result is returned
+    # from the Query.
+    # 
+    # Returns the single, matching result, or nil if no entities match
+    #
+    def entity
+      Datastore.convert_exceptions do
+        pquery.as_single_entity
+      end
+    end
+    
+  
+    # Streams the matching entities from the datastore and yields each
+    # matching entity.
+    #
+    # See #convert_options for supported options
+    def each(options={}, &proc)  # :yields: entity
+      options = convert_options(options)
+      Datastore.convert_exceptions do
+        pquery.as_iterator(options).each(&proc)
+      end
+    end
+    
+    # Returns an Enumerable over the matching entities.
+    #
+    # See #convert_options for supported options
+    #
+    def iterator(options={})
+      options = convert_options(options)
+      Datastore.convert_exceptions do
+        pquery.as_iterator(options)
+      end
+    end
+
+    # Fetch all matching entities. For large result sets you should
+    # prefer #each or #iterator, which stream the results from the
+    # datastore.
+    #
+    def fetch(options={})
+      options = convert_options(options)
+      Datastore.convert_exceptions do
+        pquery.as_list(options)
+      end      
+    end
+
+    # Returns a Java.ComGoogleAppengineApiDatastore.PreparedQuery
+    # for this query.
+    #
+    def pquery
+      @pquery ||= Datastore.service.prepare(@query)
+    end
+    
+    # Returns a Java.ComGoogleAppengineApiDatastore.Query for this query.
+    def java_query
+      @query
+    end
+    
+    # Converts an options hash into FetchOptions.
+    #
+    # Supported options:
+    # [:limit] Maximum number of results the query will return
+    # [:offset]
+    #     Number of result to skip before returning any
+    #     results.  Results that are skipped due to offset do not count
+    #     against +limit+.
+    # [:chunk]
+    #     Determines the internal chunking strategy of the iterator
+    #     returned by #iterator. This affects only the performance of
+    #     the query, not the actual results returned.
+    #
+    def convert_options(options)
+      return options if options.java_kind_of? FetchOptions
+      limit = options.delete(:limit)
+      offset = options.delete(:offset)
+      chunk_size = options.delete(:chunk) || FetchOptions::DEFAULT_CHUNK_SIZE
+      unless options.empty?
+        raise ArgumentError, "Unsupported options #{options.inspect}"
+      end
+      options = FetchOptions::Builder.with_chunk_size(chunk_size)
+      options.offset(offset) if offset
+      options.limit(limit) if limit
+      options
+    end
+    
+    private
+    def clear_cache
+      @pquery = nil
+      self
+    end
+  end
+  
+  class Iterable  # :nodoc:
+    include java.lang.Iterable
+    def initialize(array)
+      @array = array
+    end
+    
+    def iterator
+      Iterator.new(@array)
+    end
+  end
+  
+  class Iterator  # :nodoc:
+    include java.util.Iterator
+    def initialize(array)
+      @array = array
+      @index = 0
+      @removed = false
+    end
+    
+    def hasNext
+      @index < @array.size
+    end
+    
+    def next
+      raise java.util.NoSuchElementException unless hasNext
+      @removed = false
+      @index += 1
+      @array[@index - 1]
+    end
+    
+    def remove
+      raise java.lang.IllegalStateException if @removed
+      raise java.lang.IllegalStateException unless @index > 0
+      @removed = true
+      @array.delete_at(@index - 1)
+    end
+  end
+  
+  @@db ||= JavaDatastore::DatastoreServiceFactory.getDatastoreService
+end
+end