appengine-apis 0.0.2 → 0.0.3

data/History.txt

@@ -1,3 +1,9 @@
+== 0.0.3 2009-04-25
+
+* Added Memcache and Mail APIs
+* Tries to automatically add SDK to your classpath if it's missing.
+* Added AppEngine::Testing.boot to configure APIs for using in IRB.
+
 == 0.0.2 2009-04-15
 
 * Add URLFetch and Users APIs

data/Manifest.txt

@@ -7,8 +7,12 @@ lib/appengine-apis.rb
 lib/appengine-apis/apiproxy.rb
 lib/appengine-apis/datastore.rb
 lib/appengine-apis/datastore_types.rb
+lib/appengine-apis/local_boot.rb
 lib/appengine-apis/logger.rb
+lib/appengine-apis/mail.rb
+lib/appengine-apis/memcache.rb
 lib/appengine-apis/merb-logger.rb
+lib/appengine-apis/sdk.rb
 lib/appengine-apis/testing.rb
 lib/appengine-apis/urlfetch.rb
 lib/appengine-apis/users.rb
@@ -18,6 +22,8 @@ script/generate
 spec/datastore_spec.rb
 spec/datastore_types_spec.rb
 spec/logger_spec.rb
+spec/mail_spec.rb
+spec/memcache_spec.rb
 spec/spec.opts
 spec/spec_helper.rb
 spec/urlfetch_spec.rb

data/README.rdoc

@@ -6,10 +6,20 @@
 
 APIs and utilities for using JRuby on Google App Engine.
 
+To load the API stubs in IRB simply
+  require 'rubygems'
+  require 'appengine-apis/local_boot'
+
+This will configure access to the same Datastore as running
+
+  $ dev_appserver.sh .
+
 See these classes for an overview of each API:
 - AppEngine::Logger
 - AppEngine::Testing
 - AppEngine::Users
+- AppEngine::Mail
+- AppEngine::Memcache
 - AppEngine::URLFetch
 - AppEngine::Datastore
 
@@ -28,7 +38,7 @@ 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
+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,

data/Rakefile

@@ -1,6 +1,14 @@
 %w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
 require File.dirname(__FILE__) + '/lib/appengine-apis'
 
+# set up pretty rdoc if possible
+begin
+  gem 'rdoc'
+  require 'sdoc'
+  ENV['RDOCOPT'] = '-T lightblue'
+rescue
+end
+
 # 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|

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.2'
+  VERSION = '0.0.3'
 end

data/lib/appengine-apis/apiproxy.rb

@@ -18,11 +18,11 @@
 #
 # Ruby interface to the Java ApiProxy.
 
-require 'java'
+require 'appengine-apis/sdk'
 
 module AppEngine
   
-  import Java.com.google.apphosting.api.ApiProxy
+  ApiProxy = AppEngine::SDK.load_apiproxy
   
   class << ApiProxy
     def get_app_id

data/lib/appengine-apis/datastore.rb

@@ -24,7 +24,6 @@
 #
 # The datastore errors are defined in datastore_types.rb.
 
-require 'appengine-apis/apiproxy'
 require 'appengine-apis/datastore_types'
 
 module AppEngine
@@ -60,7 +59,7 @@ module AppEngine
 # - Datastore::Text
 # - Datastore::Blob
 # - Datastore::ByteString
-# - com.google.appengine.api.users.User
+# - Users::User
 
 module Datastore
   module_function
@@ -145,15 +144,15 @@ module Datastore
   # 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.
+  # 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

data/lib/appengine-apis/datastore_types.rb

@@ -125,7 +125,7 @@ module AppEngine
     # across all apps, and includes all information necessary to fetch
     # the entity from the datastore with #Datastore.get(Key).
     #
-    # See http://code.google.com/appengine/docs/java/javadoc/com/google/appengine/api/datastore/Key.html
+    # See also http://code.google.com/appengine/docs/java/javadoc/com/google/appengine/api/datastore/Key.html
     #
     class Key
       
@@ -227,7 +227,7 @@ module AppEngine
     # as an arbitrary string), and a set of zero or more typed
     # properties.
     #
-    # See http://code.google.com/appengine/docs/java/javadoc/com/google/appengine/api/datastore/Entity.html
+    # See also http://code.google.com/appengine/docs/java/javadoc/com/google/appengine/api/datastore/Entity.html
     #
     class Entity
       include Enumerable
@@ -306,7 +306,7 @@ module AppEngine
       # Add the properties from +other+ to this Entity.
       # Other may be an Entity or Hash
       def update(other)
-        hash.each do |name, value|
+        other.each do |name, value|
           self[name] = value
         end
         self
@@ -317,6 +317,14 @@ module AppEngine
       def each(&proc)  # :yields: name, value
         getProperties.each(&proc)
       end
+      
+      def to_hash
+        inject({}) do |hash, item|
+          name, value = item
+          hash[name] = value
+          hash
+        end
+      end
     end
     
     SPECIAL_RUBY_TYPES = [Time, Text, Blob, ByteString, Link].freeze

data/lib/appengine-apis/local_boot.rb

@@ -0,0 +1,29 @@
+#!/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.
+#
+#
+# Helpers for installing stub apis in unit tests.
+
+require 'appengine-apis/testing'
+AppEngine::Testing.boot
+
+require 'appengine-apis/datastore'
+require 'appengine-apis/logger'
+require 'appengine-apis/mail'
+require 'appengine-apis/memcache'
+require 'appengine-apis/urlfetch'
+require 'appengine-apis/users'

data/lib/appengine-apis/mail.rb

@@ -0,0 +1,160 @@
+#!/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.
+#
+
+module AppEngine
+  
+  # App Engine applications can send email messages on behalf of the app's
+  # administrators, and on behalf of users with Google Accounts. Apps use the
+  # Mail service to send email messages.
+  #
+  # The Mail.send method sends an email message from the application. The From:
+  # address can be either the email address of a registered administrator
+  # (developer) of the application, or the current user if signed in with
+  # Google Accounts.
+  #
+  # The following example sends an email message to the user as confirmation
+  # that the user created a new account with the application:
+  #
+  #   class SignupController < Merb::Controller
+  #     def confirm(self):
+  #       user_address = params[:email_address"]
+  #      confirmation_url = create_new_user_confirmation
+  #      sender_address = "support@example.com"
+  #      subject = "Confirm your registration"
+  #      body = <<EOM
+  #   Thank you for creating an account!  Please confirm your email address by
+  #   clicking on the link below:
+  #   
+  #   #{confirmation_url}
+  #   EOM
+  #   
+  #      AppEngine::Mail.send(sender_address, user_address, subject, body)
+  #    end
+  #  end
+  module Mail
+    import com.google.appengine.api.mail.MailServiceFactory
+    import com.google.appengine.api.mail.MailService
+    
+    module_function
+
+    # Sends an email.
+    #
+    # The message will be delivered asynchronously, and delivery problems
+    # will result in a bounce to the specified sender.
+    #
+    # Args:
+    # [sender] The From: field of the email. Must correspond to the valid
+    #          email address of one of the admins for this application, or
+    #          to the email address of the currently logged-in user.
+    # [to] Message recipient(s). Should be an email address, or an Array
+    #      of email addresses.
+    # [subject] Subject of the message.
+    # [text] Plain text body of the message. To send an HTML only email,
+    #        set +text+ to nil and use the +:html+ option.
+    # [options] See #create_java_message for supported options.
+    def send(sender, to, subject, text, options={})
+      orig_options = options
+      options = {
+        :sender => sender,
+        :to => to || [],
+        :subject => subject,
+        :text => text
+      }
+      options.merge!(orig_options)
+      message = create_java_message(options)
+      convert_mail_exceptions { service.send(message) }
+    end
+
+    # Sends an email alert to all admins of an application.
+    #
+    # The message will be delivered asynchronously, and delivery problems
+    # will result in a bounce to the admins.
+    #
+    # Args:
+    # [sender] The From: field of the email. Must correspond to the valid
+    #          email address of one of the admins for this application, or
+    #          to the email address of the currently logged-in user.
+    # [subject] Subject of the message.
+    # [text] Plain text body of the message. To send an HTML only email,
+    #        set +text+ to nil and use the +:html+ option.
+    # [options] See #create_java_message for supported options.    
+    def send_to_admins(sender, subject, text, options={})
+      orig_options = options
+      options = {
+        :sender => sender,
+        :subject => subject,
+        :text => text
+      }
+      options.merge!(orig_options)
+      message = create_java_message(options)
+      convert_mail_exceptions { service.send_to_admins(message) }
+    end
+    
+    # Creates a Java MailService.Message object.
+    #
+    # Supported options:
+    # [:atttachments]
+    #   Attachments to send with this message. Should be a Hash of
+    #   {"filename" => "data"} or an Array of [["filename", "data"], ...].
+    # [:bcc] Must be a String or an Array of Strings if set.
+    # [:cc] Must be a String or an Array of Strings if set.
+    # [:html] The html body of the message. Must not be +nil+ if +text+ is nil.
+    # [:reply_to] Must be a valid email address if set.
+    def create_java_message(options)
+      options[:text_body] = options.delete(:text)
+      options[:html_body] = options.delete(:html)
+      attachments = options[:attachments]
+      if attachments
+        options[:attachments] = attachments.collect do |filename, data|
+          MailService::Attachment.new(filename, data.to_java_bytes)
+        end
+      end
+      [:to, :cc, :bcc].each do |key|
+        value = options[key]
+        options[key] = [value] if value.kind_of? String
+      end
+      message = MailService::Message.new
+      options.each do |key, value|
+        begin
+          message.send("set_#{key}", value) if value
+        rescue NameError
+          raise ArgumentError, "Invalid option #{key.inspect}."
+        end
+      end
+      return message
+    end
+    
+    def convert_mail_exceptions  # :nodoc:
+      begin
+        yield
+      rescue java.lang.IllegalArgumentException => ex
+        raise ArgumentError, ex.message
+      rescue java.io.IOException => ex
+        raise IOError, ex.message
+      end
+    end
+    
+    def service  # :nodoc:
+      @service ||= MailServiceFactory.mail_service
+    end
+    
+    def service=(service)  # :nodoc:
+      @service = service
+    end
+  end
+end

data/lib/appengine-apis/memcache.rb

@@ -0,0 +1,580 @@
+#!/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.
+#
+
+require 'appengine-apis/datastore_types'
+
+module AppEngine
+  
+  # The Ruby API for the App Engine Memcache service. This offers a fast
+  # distrubted cache for commonly-used data. The cache is limited both in
+  # duration and also in total space, so objects stored in it may be discarded
+  # at any time.
+  # 
+  # Note that null is a legal value to store in the cache, or to use as a cache
+  # key. Strings are stored encoded as utf-8. To store binary data use
+  # AppEngine::Datastore::Blob or +str.to_java_bytes+.
+  # 
+  # The values returned from this API are mutable copies from the cache;
+  # altering them has no effect upon the cached value itself until assigned
+  # with one of the put methods. Likewise, the methods returning collections
+  # return mutable collections, but changes do not affect the cache.
+  # 
+  # Except for the #incr and #decr methods, this service does not offer
+  # atomicity guarantees. In particular, operations accessing multiple
+  # keys are non-atomic.
+  #
+  # Increment has a number of caveats to its use; please consult the method
+  # documentation.
+  class Memcache
+    import com.google.appengine.api.memcache.Expiration
+    import com.google.appengine.api.memcache.InvalidValueException
+    import com.google.appengine.api.memcache.LogAndContinueErrorHandler
+    import com.google.appengine.api.memcache.MemcacheServiceException
+    import com.google.appengine.api.memcache.MemcacheServiceFactory
+    import com.google.appengine.api.memcache.MemcacheService
+    import com.google.appengine.api.memcache.StrictErrorHandler
+    
+    ADD = MemcacheService::SetPolicy::ADD_ONLY_IF_NOT_PRESENT
+    REPLACE = MemcacheService::SetPolicy::REPLACE_ONLY_IF_PRESENT
+    SET = MemcacheService::SetPolicy::SET_ALWAYS
+    
+    # Base Memcache exception class
+    class MemcacheError < StandardError; end
+    
+    MemCacheError = MemcacheError
+    ClientError = MemcacheError
+    InternalError = MemcacheError
+    
+    MARSHAL_MARKER = '--JRuby Marshal Data--'
+    
+    # An exception for backend non-availability or similar error states which
+    # may occur, but are not necessarily indicative of a coding or usage error
+    # by the application.
+    class ServerError < MemcacheError; end
+    
+    # Raised when a cache entry has content, but it cannot be read. For example:
+    # - An attempt to #incr a non-integral value
+    # - Version skew between your application and the data in the cache,
+    #   causing a marshaling error.
+    class InvalidValueError < MemcacheError; end
+    
+    def initialize(*servers)
+      options = if servers[-1].kind_of? Hash
+        servers[-1]
+      else
+        {}
+      end
+      if options.include?(:namespace)
+        service.namespace = options[:namespace]
+      end
+      @readonly = options[:readonly]
+    end
+
+    # Returns the Java MemcacheService object used by this Memcache client.
+    def service
+      @service ||= MemcacheServiceFactory.memcache_service
+    end
+    
+    def active?
+      # TODO use the capability api to see if Memcache is disabled.
+      true
+    end
+    
+    # Empties the cache of all values. Statistics are not affected. Note that
+    # #clear does not respect namespaces - this flushes the cache for every
+    # namespace.
+    #
+    # Returns true on success, false on RPC or server error.
+    def flush_all
+      check_write
+      with_errors do
+        begin
+          service.clear_all
+          return true
+        rescue MemcacheError
+          return false
+        end
+      end
+    end
+    alias clear flush_all
+    
+    # Gets memcache statistics for this application.
+    # 
+    # All of these statistics may reset due to various transient conditions.
+    # They provide the best information available at the time of being called.
+    #
+    # Returns a Hash mapping statistic names to associated values:
+    # [:hits] Number of cache get requests resulting in a cache hit.
+    # [:misses] Number of cache get requests resulting in a cache miss.
+    # [:byte_hits] Sum of bytes transferred on get requests. Rolls over to
+    #              zero on overflow.
+    # [:items] Number of key/value pairs in the cache.
+    # [:bytes] Total size of all items in the cache.
+    # [:oldest_item_age]
+    #   How long in seconds since the oldest item in the
+    #   cache was accessed. Effectively, this indicates how long a new
+    #   item will survive in the cache without being accessed. This is
+    #   _not_ the amount of time that has elapsed since the item was
+    #   created.
+    #
+    # On error, returns +nil+.
+    def stats
+      with_errors do
+        begin
+          stats = service.statistics
+          if stats
+            {
+              :hits => stats.hit_count,
+              :misses => stats.miss_count,
+              :byte_hits => stats.bytes_returned_for_hits,
+              :items => stats.item_count,
+              :bytes => stats.total_item_bytes,
+              :oldest_item_age => stats.max_time_without_access / 1000.0
+            }
+          end
+        rescue ServerError
+          nil
+        end
+      end
+    end
+    
+    # Fetch and return the values associated with the given +key+s from the
+    # cache. Returns +nil+ for any value that wasn’t in the cache.
+    def get(*keys)
+      multiple = (keys.size != 1)
+      if !multiple && keys[0].kind_of?(Array)
+        keys = keys[0]
+        multiple = true
+      end
+      hash = get_hash(*keys)
+      values = keys.collect {|key| hash[key]}
+      if multiple
+        values
+      else
+        values[0]
+      end
+    end
+    alias [] get
+    
+    # Looks up multiple keys from memcache in one operation. This is more
+    # efficient than multiple separate calls to #get.
+    # 
+    # Args:
+    # - keys: List of keys to look up.
+    # 
+    # Returns a hash of the keys and values that were present in memcache.
+    def get_hash(*keys)
+      key_map = KeyMap.new(keys)
+      convert_exceptions do
+        map = service.getAll(key_map.java_keys)
+        key_map.map_to_hash(map) do |value|
+          if value.java_kind_of?(java.util.ArrayList) && value.size == 2 &&
+              value[0] == MARSHAL_MARKER
+            Marshal.load(String.from_java_bytes(value[1]))
+          else
+            value
+          end
+        end
+      end
+    end
+    
+    # Removes the given key from the cache, and prevents it from being added
+    # using #add for +time+ seconds thereafter. Calls to #set are not blocked.
+    #
+    # Returns true if an entry existed to delete.
+    def delete(key, time=nil)
+      time ||= 0
+      check_write
+      convert_exceptions do
+        service.delete(memcache_key(key), time * 1000)
+      end
+    end
+
+    # Removes the given keys from the cache, and prevents them from being added
+    # using #add for +time+ seconds thereafter. Calls to #set are not blocked.
+    #
+    # Returns the set of keys deleted. Any keys in +keys+ but not in the
+    # returned set were not found in the cache.
+    def delete_many(keys, time=0)
+      check_write
+      key_map = KeyMap.new(keys)
+      convert_exceptions do
+        java_keys = service.delete_all(key_map.java_keys, time * 1000)
+        key_map.ruby_keys(java_keys)
+      end      
+    end
+    
+    # Sets a key's value, iff item is not already in memcache.
+    # 
+    # Args:
+    # - key: Key to set.
+    # - value: Value to set.  Any type.  If complex, will be marshaled.
+    # - expiration: Optional expiration time, either relative number of seconds
+    #   from current time (up to 1 month), an absolute Unix epoch time, or a
+    #   Time. By default, items never expire, though items may be evicted due
+    #   to memory pressure.
+    # 
+    # Returns true if added, false on error.
+    def add(key, value, expiration=0)
+      put(key, value, expiration, ADD)
+    end
+    
+    # Set multiple keys' values iff items are not already in memcache.
+    # 
+    # Args:
+    # - pairs: Hash of keys to values, or Array of [key, value] pairs.
+    # - expiration: Optional expiration time, either relative number of seconds
+    #   from current time (up to 1 month), an absolute Unix epoch time, or a
+    #   Time. By default, items never expire, though items may be evicted due
+    #   to memory pressure.
+    # 
+    # Returns a list of keys whose values were NOT set.  On total success
+    # this list should be empty.
+    def add_many(pairs, expiration=0)
+      put_many(pairs, expiration, ADD)
+    end
+    
+    # Sets a key's value, regardless of previous contents in cache.
+    # 
+    # Unlike #add and #replace, this method always sets (or
+    # overwrites) the value in memcache, regardless of previous
+    # contents.
+    # 
+    # Args:
+    # - key: Key to set.
+    # - value: Value to set.  Any type.  If complex, will be marshaled.
+    # - expiration: Optional expiration time, either relative number of seconds
+    #   from current time (up to 1 month), an absolute Unix epoch time, or a
+    #   Time. By default, items never expire, though items may be evicted due
+    #   to memory pressure.
+    # 
+    # Returns true if set, false on error.
+    def set(key, value, expiration=0)
+      put(key, value, expiration, SET)
+    end
+    
+    # Set multiple keys' values at once, regardless of previous contents.
+    # 
+    # Args:
+    # - pairs: Hash of keys to values, or Array of [key, value] pairs.
+    # - expiration: Optional expiration time, either relative number of seconds
+    #   from current time (up to 1 month), an absolute Unix epoch time, or a
+    #   Time. By default, items never expire, though items may be evicted due
+    #   to memory pressure.
+    # 
+    # Returns a list of keys whose values were NOT set.  On total success
+    # this list should be empty.
+    def set_many(pairs, expiration=0)
+      put_many(pairs, expiration, SET)
+    end
+    
+    # call-seq:
+    #   cache[:foo, :bar] = 1, 2
+    #
+    # Syntactic sugar for calling set_many.
+    def []=(*args)
+      values = args.pop
+      if values.kind_of? Array
+        set_many(args.zip(values))
+      else
+        set(args, values)
+      end
+    end
+    
+    # Replaces a key's value, failing if item isn't already in memcache.
+    # 
+    # Unlike #add and #replace, this method always sets (or
+    # overwrites) the value in memcache, regardless of previous
+    # contents.
+    # 
+    # Args:
+    # - key: Key to set.
+    # - value: Value to set.  Any type.  If complex, will be marshaled.
+    # - expiration: Optional expiration time, either relative number of seconds
+    #   from current time (up to 1 month), an absolute Unix epoch time, or a
+    #   Time. By default, items never expire, though items may be evicted due
+    #   to memory pressure.
+    # 
+    # Returns true if replaced, false on cache miss.
+    def replace(key, value, expiration=0)
+      put(key, value, expiration, REPLACE)
+    end
+    
+    # Replace multiple keys' values, failing if the items aren't in memcache.
+    # 
+    # Args:
+    # - pairs: Hash of keys to values, or Array of [key, value] pairs.
+    # - expiration: Optional expiration time, either relative number of seconds
+    #   from current time (up to 1 month), an absolute Unix epoch time, or a
+    #   Time. By default, items never expire, though items may be evicted due
+    #   to memory pressure.
+    # 
+    # Returns a list of keys whose values were NOT set.  On total success
+    # this list should be empty.
+    def replace_many(pairs, expiration=0)
+      put_many(pairs, expiration, REPLACE)
+    end
+    
+    # Atomically fetches, increments, and stores a given integral value.
+    # "Integral" types are Fixnum and in some cases String (if the string is
+    # parseable as a number. The entry must already exist.
+    #
+    # Internally, the value is a unsigned 64-bit integer.  Memcache
+    # doesn't check 64-bit overflows.  The value, if too large, will
+    # wrap around.
+    #
+    # Args:
+    # - key: the key of the entry to manipulate
+    # - delta: the size of the increment.
+    #
+    # Returns the post-increment value.
+    #
+    # Throws InvalidValueError if the object incremented is not of
+    # an integral type.
+    def incr(key, delta=1)
+      check_write
+      convert_exceptions do
+        service.increment(memcache_key(key), delta)
+      end
+    end
+
+    # Atomically fetches, deccrements, and stores a given integral value.
+    # "Integral" types are Fixnum and in some cases String (if the string is
+    # parseable as a number. The entry must already exist.
+    #
+    # Internally, the value is a unsigned 64-bit integer.  Memcache
+    # caps decrementing below zero to zero.
+    #
+    # Args:
+    # - key: the key of the entry to manipulate
+    # - delta: the size of the decrement
+    #
+    # Returns the post-decrement value.
+    #
+    # Throws InvalidValueError if the object decremented is not of
+    # an integral type.
+    def decr(key, delta=1)
+      check_write
+      convert_exceptions do
+        service.increment(memcache_key(key), -delta)
+      end
+    end
+    
+    # Get the name of the namespace that will be used in API calls.
+    def namespace
+      service.namespace
+    end
+    
+    # Change the namespace used in API calls.
+    def namespace=(value)
+      service.namespace = value
+    end
+    
+    # Returns true if the cache was created read-only.
+    def readonly?
+      @readonly
+    end
+    
+    def inspect
+      "<Memcache ns:#{namespace.inspect}, ro:#{readonly?.inspect}>"
+    end
+    
+    # Returns whether the client raises an exception if there's an error
+    # contacting the server. By default it will simulate a cache miss
+    # instead of raising an error.
+    def raise_errors?
+      service.error_handler.kind_of? StrictErrorHandler
+    end
+    
+    # Set whether this client raises an exception if there's an error
+    # contacting the server.
+    #
+    # If +should_raise+ is true, a ServerError is raised whenever there
+    # is an error contacting the server.
+    #
+    # If +should_raise+ is false (the default), a cache miss is simulated
+    # instead of raising an error.
+    def raise_errors=(should_raise)
+      if should_raise
+        service.error_handler = StrictErrorHandler.new
+      else
+        service.error_handler = LogAndContinueErrorHandler.new
+      end
+    end
+    
+    # For backwards compatibility. Simply returns nil
+    def do_nothing(*args)
+    end
+    alias server_item_stats do_nothing
+    alias server_malloc_stats do_nothing
+    alias server_map_stats do_nothing
+    alias server_reset_stats do_nothing
+    alias server_size_stats do_nothing
+    alias server_slab_stats do_nothing
+    alias server_stats do_nothing
+    alias servers= do_nothing
+    
+    private
+    
+    def memcache_key(obj)
+      key = obj
+      key = key.to_s.to_java_string if key
+      key
+    end
+
+    def memcache_value(obj)
+      case obj
+      when Fixnum
+        java.lang.Long.new(obj)
+      when Float
+        java.lang.Double.new(obj)
+      when TrueClass, FalseClass
+        java.lang.Boolean.new(obj)
+      when JavaProxy, Java::JavaObject
+        obj
+      else
+        if obj.class == String
+          # Convert plain strings to Java strings
+          obj.to_java_string
+        else
+          bytes = Marshal.dump(obj).to_java_bytes
+          java.util.ArrayList.new([MARSHAL_MARKER.to_java_string, bytes])
+        end
+      end
+    end
+    
+    def memcache_expiration(amount)
+      if amount.nil? || amount == 0
+        nil
+      elsif amount.kind_of? Time
+        Expiration.on_date(amount.to_java)
+      elsif amount > 86400 * 30
+        millis = (amount * 1000).to_i
+        Expiration.on_date(java.util.Date.new(millis))
+      else
+        Expiration.byDeltaMillis((amount * 1000).to_i)
+      end
+    end
+    
+    def check_write
+      raise MemcacheError, "readonly cache" if self.readonly?
+    end
+
+    def with_errors(&block)
+      saved_handler = service.error_handler
+      begin
+        service.error_handler = StrictErrorHandler.new
+        convert_exceptions(&block)
+      ensure
+        service.error_handler = saved_handler
+      end
+    end
+    
+    def convert_exceptions
+      begin
+        yield
+      rescue java.lang.IllegalArgumentException => ex
+        raise ArgumentError, ex.message
+      rescue InvalidValueException => ex
+        raise InvalidValueError, ex.message
+      rescue MemcacheServiceException => ex
+        raise ServerError, ex.message
+      end
+    end
+    
+    def put(key, value, expiration, mode)
+      check_write
+      convert_exceptions do
+        key = memcache_key(key)
+        value = memcache_value(value)
+        expiriation = memcache_expiration(expiriation)
+        service.put(key, value, expiriation, mode)
+      end
+    end
+    
+    def put_many(pairs, expiration, mode)
+      check_write
+      expiration = memcache_expiration(expiration)
+      convert_exceptions do
+        key_map = KeyMap.new
+        put_map = java.util.HashMap.new
+        pairs.each do |key, value|
+          java_key = key_map << key
+          java_value = memcache_value(value)
+          put_map.put(java_key, java_value)
+        end
+        saved_keys = service.put_all(put_map, expiration, mode)
+        key_map.missing_keys(saved_keys)
+      end
+    end
+    
+    class KeyMap  # :nodoc:
+      def initialize(keys=[])
+        @orig_keys = []
+        @map = {}
+        keys.each do |key|
+          self << key
+        end
+      end
+      
+      def <<(key)
+        @orig_keys << key
+        string_key = if key
+          key.to_s
+        else
+          key
+        end
+        @map[string_key] = key
+        if string_key
+          string_key.to_java_string
+        else
+          string_key
+        end
+      end
+      
+      def java_keys
+        @map.keys.collect do |key|
+          if key
+            key.to_java_string
+          else
+            key
+          end
+        end
+      end
+      
+      def ruby_keys(keys)
+        keys.collect {|key| @map[key]}
+      end
+      
+      def missing_keys(keys)
+        @orig_keys - ruby_keys(keys)
+      end
+      
+      def map_to_hash(java_map)
+        hash = {}
+        if java_map
+          java_map.each do |key, value|
+            value = yield(value)
+            hash[@map[key]] = value
+          end
+        end
+        hash
+      end
+    end
+  end
+end