appengine-apis 0.0.8 → 0.0.9

data/Manifest.txt

@@ -6,6 +6,7 @@ lib/appengine-apis.rb
 lib/appengine-apis/apiproxy.rb
 lib/appengine-apis/datastore.rb
 lib/appengine-apis/datastore_types.rb
+lib/appengine-apis/labs/taskqueue.rb
 lib/appengine-apis/local_boot.rb
 lib/appengine-apis/logger.rb
 lib/appengine-apis/mail.rb
@@ -15,6 +16,8 @@ lib/appengine-apis/sdk.rb
 lib/appengine-apis/testing.rb
 lib/appengine-apis/urlfetch.rb
 lib/appengine-apis/users.rb
+lib/appengine-apis/xmpp.rb
+lib/appengine-apis/tempfile.rb
 script/console
 script/destroy
 script/generate
@@ -25,6 +28,8 @@ spec/mail_spec.rb
 spec/memcache_spec.rb
 spec/spec.opts
 spec/spec_helper.rb
+spec/taskqueue_spec.rb
 spec/urlfetch_spec.rb
 spec/users_spec.rb
+spec/xmpp_spec.rb
 tasks/rspec.rake

data/README.rdoc

@@ -22,6 +22,8 @@ See these classes for an overview of each API:
 - AppEngine::Memcache
 - AppEngine::URLFetch
 - AppEngine::Datastore
+- AppEngine::XMPP
+- AppEngine::Labs::TaskQueue
 
 Unless you're implementing your own ORM, you probably want to use the
 DataMapper API instead of the lower level AppEngine::Datastore API.

data/lib/appengine-apis.rb

@@ -19,5 +19,5 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 module AppEngine
-  VERSION = '0.0.8'
+  VERSION = '0.0.9'
 end

data/lib/appengine-apis/datastore.rb

@@ -236,6 +236,21 @@ module Datastore
     raise TransactionFailed
   end
   
+  # call-seq:
+  #   Datastore.allocate_ids(kind, num)
+  #   Datastore.allocate_ids(parent, kind, num)
+  #
+  # Ids are allocated within a namespace defined by a parent key and a kind.
+  # This method allocates a contiguous range of unique ids of size num
+  # within the namespace defined by the given parent key and the given kind.
+  #
+  # Returns a KeyRange representing the range of allocated ids.
+  def allocate_ids(*args)
+    convert_exceptions do
+      @@db.allocate_ids(*args)
+    end
+  end
+  
   def extract_tx(args)  # :nodoc:
     tx = :none
     keys = args[0]
@@ -406,8 +421,8 @@ module Datastore
     end
     
     # Returns the number of entities that currently match this query.
-    def count
-      pquery.count
+    def count(transaction=:current)
+      pquery(transaction).count_entities
     end
     
     # Retrieves the one and only result for the {@code Query}.
@@ -417,9 +432,9 @@ module Datastore
     # 
     # Returns the single, matching result, or nil if no entities match
     #
-    def entity
+    def entity(transaction=:current)
       Datastore.convert_exceptions do
-        pquery.as_single_entity
+        pquery(transaction).as_single_entity
       end
     end
     
@@ -429,9 +444,9 @@ module Datastore
     #
     # See #convert_options for supported options
     def each(options={}, &proc)  # :yields: entity
-      options = convert_options(options)
+      transaction, options = convert_options(options)
       Datastore.convert_exceptions do
-        pquery.as_iterator(options).each(&proc)
+        pquery(transaction).as_iterator(options).each(&proc)
       end
     end
     
@@ -440,9 +455,9 @@ module Datastore
     # See #convert_options for supported options
     #
     def iterator(options={})
-      options = convert_options(options)
+      transaction, options = convert_options(options)
       Datastore.convert_exceptions do
-        pquery.as_iterator(options)
+        pquery(transaction).as_iterator(options)
       end
     end
 
@@ -451,17 +466,21 @@ module Datastore
     # datastore.
     #
     def fetch(options={})
-      options = convert_options(options)
+      transaction, options = convert_options(options)
       Datastore.convert_exceptions do
-        pquery.as_list(options)
+        pquery(transaction).as_list(options)
       end      
     end
 
     # Returns a Java.ComGoogleAppengineApiDatastore.PreparedQuery
     # for this query.
     #
-    def pquery
-      @pquery ||= Datastore.service.prepare(@query)
+    def pquery(transaction=:current)
+      @pquery ||= if transaction != :current
+        Datastore.service.prepare(transaction, @query)
+      else
+        Datastore.service.prepare(@query)
+      end
     end
     
     # Returns a Java.ComGoogleAppengineApiDatastore.Query for this query.
@@ -481,9 +500,17 @@ module Datastore
     #     Determines the internal chunking strategy of the iterator
     #     returned by #iterator. This affects only the performance of
     #     the query, not the actual results returned.
+    # [:transaction]
+    #     Transaction in which the query should run. Only supported
+    #     for ancestor queries. Uses the current transaction if not
+    #     specified.
     #
     def convert_options(options)
-      return options if options.java_kind_of? FetchOptions
+      transaction = :current
+      return [transaction, options] if options.java_kind_of? FetchOptions
+      if options.include? :transaction
+        transaction = options.delete(:transaction)
+      end
       limit = options.delete(:limit)
       offset = options.delete(:offset)
       chunk_size = options.delete(:chunk) || FetchOptions::DEFAULT_CHUNK_SIZE
@@ -493,7 +520,7 @@ module Datastore
       options = FetchOptions::Builder.with_chunk_size(chunk_size)
       options.offset(offset) if offset
       options.limit(limit) if limit
-      options
+      [transaction, options]
     end
     
     def inspect

data/lib/appengine-apis/datastore_types.rb

@@ -23,11 +23,11 @@ require 'java'
 
 class Time
   def to_java
-    java.util.Date.new(tv_sec * 1000 + tv_usec / 1000)
+    java.util.Date.new(tv_sec * 1000 + tv_usec / 1000.0)
   end
 
   def self.new_from_java(date)
-    at(date.time / 1000)
+    at(date.time / 1000.0)
   end
 end
 
@@ -117,6 +117,135 @@ module AppEngine
       end
     end
     
+    # An RFC2822 email address. Makes no attempt at validation.
+    class Email < String
+      def to_java
+        JavaDatastore::Email.new(self.to_java_string)
+      end
+      
+      def self.new_from_java(email)
+        self.new(email.getEmail)
+      end      
+    end
+
+    # A tag, ie a descriptive word or phrase. Entities may be tagged by users,
+    # and later returned by a queries for that tag. Tags can also be used for
+    # ranking results (frequency), photo captions, clustering, activity, etc.
+    #
+    # More details:  http://www.zeldman.com/daily/0405d.shtml
+    class Category < String
+      def to_java
+        JavaDatastore::Category.new(self.to_java_string)
+      end
+      
+      def self.new_from_java(category)
+        self.new(category.getCategory)
+      end
+    end
+
+    # A human-readable phone number.  No validation is performed because phone
+    # numbers have many different formats - local, long distance, domestic,
+    # international, internal extension, TTY, VOIP, SMS, and alternative
+    # networks like Skype, XFire and Roger Wilco.  They all have their own
+    # numbering and addressing formats.
+    class PhoneNumber < String
+      def to_java
+        JavaDatastore::PhoneNumber.new(self.to_java_string)
+      end
+      
+      def self.new_from_java(phone)
+        self.new(phone.getNumber)
+      end
+    end
+
+    # A human-readable mailing address.  Mailing address formats vary widely so
+    # no validation is performed.
+    class PostalAddress < String
+      def to_java
+        JavaDatastore::PostalAddress.new(self.to_java_string)
+      end
+      
+      def self.new_from_java(address)
+        self.new(address.getAddress)
+      end
+    end
+    
+    Rating = JavaDatastore::Rating
+
+    # A user-provided integer rating for a piece of content. Normalized to a
+    # 0-100 scale.
+    class Rating
+      # Raises ArgumentError if rating < 0 or rating > 100.
+      def self.new(rating)
+        if rating < MIN_VALUE || rating > MAX_VALUE
+          raise ArgumentError, "rating must be no smaller than #{MIN_VALUE} " +
+              "and no greater than #{MAX_VALUE} (received #{rating})"
+        end
+        super(rating)
+      end
+      
+      alias to_i rating
+      
+      def to_s
+        rating.to_s
+      end
+      
+      def inspect
+        "#<Rating #{rating}>"
+      end
+      
+      if false
+        MIN_VALUE = 0
+        MAX_VALUE = 100
+        def rating; end
+      end
+    end
+    
+    IMHandle = JavaDatastore::IMHandle
+
+    # An instant messaging handle. Includes both an address and its protocol.
+    # The protocol value is either a standard IM scheme (legal scheme values are
+    # :sip, :xmpp, :unknown or a URL identifying the IM network for the
+    # protocol (eg http://aim.com/).
+    class IMHandle
+      SCHEMES = {
+        :sip => Scheme.sip,
+        :xmpp => Scheme.xmpp,
+        :unknown => Scheme.unknown
+      }.freeze
+      
+      def self.new(protocol, address)
+        begin
+          protocol = SCHEMES[protocol] || java.net.URL.new(protocol)
+        rescue java.net.MalformedURLException => ex
+          raise ArgumentError, ex.message
+        end
+        super
+      end
+      
+      if false
+        def protocol; end
+        def address; end
+      end
+    end
+    
+    GeoPt = JavaDatastore::GeoPt
+    
+    # A geographical point, specified by float latitude and longitude
+    # coordinates. Often used to integrate with mapping sites like Google Maps.
+    class GeoPt
+      def self.new(latitude, longitude)
+        super
+      rescue java.lang.IllegalArgumentException => ex
+        raise ArgumentError, ex.message
+      end
+      
+      if false
+        def latitude; end
+        def longitude; end
+      end
+    end
+    
     Key = JavaDatastore::Key
     
     # The primary key for a datastore entity.
@@ -219,6 +348,39 @@ module AppEngine
       end
     end
     
+    KeyRange = JavaDatastore::KeyRange
+
+    # Represents a range of unique datastore identifiers from
+    # start.id to end.id inclusive. The Keys returned by an
+    # instance of this class have been consumed in the datastore's
+    # id-space and are guaranteed never to be reused.
+    #
+    # This class can be used to construct Entity Entities with
+    # Keys that have specific id values without fear of the datastore
+    # creating new records with those same ids at a later date.  This can be
+    # helpful as part of a data migration or large bulk upload where you may
+    # need to preserve existing ids and relationships between entities.
+    class KeyRange
+      include Enumerable
+      
+      if false
+        # The first Key in the range.
+        def start; end;
+        
+        # The last Key in the range.
+        def end; end;
+        
+        # The size of the range.
+        def size; end;
+      end
+      
+      def each
+        iterator.each do |key|
+          yield key
+        end
+      end
+    end
+    
     Entity = JavaDatastore::Entity
     
     # Entity is the fundamental unit of data storage.  It has an
@@ -237,12 +399,36 @@ module AppEngine
         JavaDatastore::Blob => Blob,
         JavaDatastore::ShortBlob => ByteString,
         JavaDatastore::Link => Link,
+        JavaDatastore::Email => Email,
+        JavaDatastore::Category => Category,
+        JavaDatastore::PhoneNumber => PhoneNumber,
+        JavaDatastore::PostalAddress => PostalAddress,
         java.util.Date => Time,
       }.freeze
       
       alias :inspect :to_string
       alias :== :equals?
       
+      if false
+        # Create a new Entity with the specified kind and parent Entity.  The
+        # instantiated Entity will have anincomplete Key when this constructor
+        # returns. The Key will remain incomplete until you put the Entity,
+        # after which time the Key will have its id set.
+        def initialize(kind, parent=nil); end
+        
+        # Create a new Entity with the specified kind, key name, and parent
+        # Entity. The instantiated Entity will have a complete Key when this
+        # constructor returns. The Key's name field will be set to the value of
+        # key_name.
+        def initialize(kind, key_name, parent=nil); end
+        
+        # Create a new Entity uniquely identified by the provided Key.
+        # Creating an entity for the purpose of insertion (as opposed
+        # to update) with a key that has its id field set is strongly
+        # discouraged unless the key was returned by a KeyRange.
+        def initialize(key); end
+      end
+      
       # Returns the property with the specified name.
       def get_property(name)
         name = name.to_s if name.kind_of? Symbol
@@ -333,8 +519,9 @@ module AppEngine
       end
     end
     
-    SPECIAL_RUBY_TYPES = [Time, Text, Blob, ByteString, Link].freeze
-    
+    SPECIAL_RUBY_TYPES = [Time, Text, Blob, ByteString, Link, Email,
+                          Category, PhoneNumber, PostalAddress].freeze
+
     def Datastore.ruby_to_java(value)  # :nodoc:
       if SPECIAL_RUBY_TYPES.include? value.class
         value.to_java
@@ -357,6 +544,8 @@ module AppEngine
         yield
       rescue java.lang.IllegalArgumentException => ex
         raise ArgumentError, ex.message
+      rescue java.lang.NullPointerException => ex
+        raise ArgumentError, ex.message
       rescue java.util.ConcurrentModificationException => ex
         raise TransactionFailed, ex.message
       rescue java.util.NoSuchElementException => ex
@@ -368,7 +557,7 @@ module AppEngine
       rescue JavaDatastore::DatastoreFailureException => ex
         raise InternalError, ex.message
       rescue JavaDatastore::EntityNotFoundException => ex
-        raise EnityNotFound, ex.message
+        raise EntityNotFound, ex.message
       rescue JavaDatastore::PreparedQuery::TooManyResultsException => ex
         raise TooManyResults, ex.message
       end

data/lib/appengine-apis/labs/taskqueue.rb

@@ -0,0 +1,266 @@
+#!/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.
+# 
+# Task Queue API.
+# 
+# Enables an application to queue background work for itself. Work is done
+# through webhooks that process tasks pushed from a queue. Tasks will execute in
+# best-effort order of ETA. Webhooks that fail will cause tasks to be retried at
+# a later time. Multiple queues may exist with independent throttling controls.
+# 
+# Webhook URLs may be specified directly for Tasks, or the default URL scheme
+# may be used, which will translate Task names into URLs relative to a Queue's
+# base path. A default queue is also provided for simple usage.
+
+require 'appengine-apis/datastore_types'
+
+module AppEngine
+  module Labs
+    module TaskQueue
+      import com.google.appengine.api.labs.taskqueue.QueueFactory
+      import com.google.appengine.api.labs.taskqueue.TaskOptions
+
+      import com.google.appengine.api.labs.taskqueue.TaskAlreadyExistsException
+      import com.google.appengine.api.labs.taskqueue.TransientFailureException
+      import com.google.appengine.api.labs.taskqueue.InternalFailureException
+      import com.google.appengine.api.labs.taskqueue.TaskAlreadyExistsException
+      import com.google.appengine.api.labs.taskqueue.UnsupportedTranslationException
+
+      class TaskAlreadyExistsError < StandardError; end
+      class TransientFailureError < StandardError; end
+      class InternalError < StandardError; end
+
+      Blob = AppEngine::Datastore::Blob
+      
+      # Represents a single Task on a queue.
+      class Task
+        
+        # Initializer.
+        # 
+        # All parameters are optional.
+        # 
+        # Options:
+        # [:payload] The payload data for this Task that will be delivered to
+        #      the webhook as the HTTP request body. This is only allowed for
+        #      POST and PUT methods. Assumed to be UTF-8 unless it is a Blob.
+        # [:bytes] Binary payload data for this Task.
+        # [:countdown]: Time in seconds into the future that this Task should
+        #      execute. Defaults to zero.
+        # [:eta] Absolute time when the Task should execute. Must be a Time
+        #      object. May not be specified if 'countdown' is also supplied.
+        # [:headers] Hash of headers to pass to the webhook. Values in the
+        #      hash may be enumerable to indicate repeated header fields.
+        # [:method]: HTTP method to use when accessing the webhook. Defaults
+        #      to 'POST'.
+        # [:name] Name to give the Task; if not specified, a name will be
+        #      auto-generated when added to a queue and assigned to this object.
+        # [:params]: Hash of parameters to use for this Task.
+        #      For POST requests these params will be encoded as
+        #      'application/x-www-form-urlencoded' and set to the payload.
+        #      For all other methods, the parameters will be converted to a
+        #      query string. May not be specified if the URL already
+        #      contains a query string.
+        # [:url] Relative URL where the webhook that should handle this task is
+        #      located for this application. May have a query string unless
+        #      this is a POST method.
+        # 
+        # Raises:
+        #   InvalidTaskError if any of the parameters are invalid;
+        #   InvalidTaskNameError if the task name is invalid; InvalidUrlError if
+        #   the task URL is invalid or too long; TaskTooLargeError if the task with
+        #   its payload is too large.
+        def initialize(payload=nil, options={})
+          if payload.kind_of? Hash
+            options, payload = payload, nil
+          elsif payload.kind_of? TaskOptions
+            @task_options = payload
+            return
+          end
+          options = options.dup
+          if payload.kind_of? Blob
+            options[:bytes] = payload
+          elsif payload
+            options[:payload] = payload
+          end
+          @task_options = convert_options(options)
+        end
+        
+       # Returns whether this Task has been enqueued.
+        # 
+        # Note: This will not check if this Task already exists in the queue.
+        def enqueued?
+          !!@handle
+        end
+        
+        # Adds this Task to a queue
+        #
+        # Args:
+        # - queue: Name of the queue where this Task should be added. (optional)
+        #
+        def add(queue=nil)
+          queue = Queue.new(queue) unless Queue.kind_of? Queue
+          @handle = queue.java_queue.add(_task)
+          self
+        end
+        
+        # Returns the Time when this Task will execute.
+        def eta
+          Time.at(@handle.eta_millis / 1000.0) if @handle
+        end
+        
+        # Returns the name of this Task.
+        #
+        # Will be nil if using an auto-assigned Task name and this Task has
+        # not yet been added to a Queue.
+        def name
+          @handle.name if @handle
+        end
+
+        # Returns the name of the Queue where this Task was enqueued.
+        def queue
+          @handle.queue_name if @handle
+        end
+
+        private
+        def convert_options(options)
+          TaskQueue.convert_exceptions do
+            task = TaskOptions::Builder.with_defaults
+            if bytes = options.delete(:bytes)
+              task.payload(bytes.to_java_bytes, 'application/octet-stream')
+            end
+            if payload = options.delete(:payload)
+              task.payload(payload)
+            end
+            if countdown = options.delete(:countdown)
+              millis = (countdown * 1000).round
+              task.countdown_millis(millis)
+            end
+            if @eta = options.delete(:eta)
+              millis = @eta.tv_sec * 1000 + @eta.tv_usec / 1000.0
+              task.eta_millis(millis)
+            end
+            if headers = options.delete(:headers)
+              headers.each do |key, value|
+                if value.kind_of? Array
+                  value = value.join(",")
+                end
+                task.header(key, value)
+              end
+            end
+            if method = options.delete(:method)
+              method = TaskOptions::Method.value_of(method.to_s.upcase)
+              task.method(method)
+            end
+            if name = options.delete(:name)
+              task.task_name(name)
+            end
+            if params = options.delete(:params)
+              params.each do |name, param|
+                if param.kind_of? Blob
+                  param = param.to_java_bytes
+                end
+                task.param(name, param)
+              end
+            end
+            if url = options.delete(:url)
+              task.url(url)
+            end
+            task
+          end
+        end
+        
+        def _task
+          @task_options
+        end
+        
+      end
+      
+      # Represents a Queue.
+      class Queue
+        @queues = {}
+        
+        # Returns the named Queue, or the default queue if name is nil.
+        #
+        # The returned Queue object may not necessarily refer
+        # to an existing queue.  Queues must be configured before
+        # they may be used.  Attempting to use a non-existing queue name
+        # may result in errors at the point of use of the Queue object,
+        # not when creating it.
+        def initialize(name=nil)
+          TaskQueue.convert_exceptions do
+            if name.nil?
+              @queue = QueueFactory.default_queue
+            else
+              @queue = QueueFactory.get_queue(name)
+            end
+          end
+        end
+        
+        def self.new(name=nil)
+          @queues[name] ||= super
+        end
+        
+        # Submits a task to this queue.
+        def add(task=nil)
+          if task.nil?
+            Task.new.add(self)
+          elsif task.java_kind_of? TaskOptions
+            Task.new(task).add(self)
+          else
+            task.add(self)
+          end
+        end
+        
+        # Returns the name of this queue.
+        def name
+          @queue.queue_name
+        end
+        
+        def java_queue
+          @queue
+        end
+      end
+      
+      # Convenience method will create a Task and add it to the default queue.
+      # 
+      # Args:
+      # - args: Passed to the Task constructor.
+      # 
+      # Returns:
+      # - The Task that was added to the queue.
+      def self.add(*args)
+        Task.new(*args).add
+      end
+      
+      def self.convert_exceptions
+        begin
+          yield
+        rescue java.lang.IllegalArgumentException => ex
+          raise ArgumentError, ex.message
+        rescue UnsupportedTranslationException => ex
+          raise ArgumentError, ex.message
+        rescue TaskAlreadyExistsException => ex
+          raise TaskAlreadExistsError, ex.message
+        rescue InternalFailureException => ex
+          raise InternalError, ex.message
+        rescue TransientFailureException => ex
+          raise TransientFailureError, ex.message
+        end
+      end
+    end
+  end
+end