dropbox 0.0.10 → 1.0.0

data/lib/dropbox/entry.rb

@@ -0,0 +1,96 @@
+# Defines the Dropbox::Entry class.
+
+nil # doc fix
+
+module Dropbox
+
+  # A façade over a Dropbox::Session that allows the programmer to interact with
+  # Dropbox files in an object-oriented manner. The Dropbox::Entry instance is
+  # created by calling the Dropbox::API#entry method:
+  #
+  #  file = session.file('remote/file.pdf')
+  #  dir = session.directory('remote/dir') # these calls are actually identical
+  #
+  # Note that no network calls are made; this merely creates a façade that will
+  # delegate future calls to the session:
+  #
+  #  file.move('new/path') # identical to calling session.move('remote/file.pdf', 'new/path')
+  #
+  # The internal path is updated as the file is moved and renamed:
+  #
+  #  file = session.file('first_name.txt')
+  #  file.rename('second_name.txt')
+  #  file.rename('third_name.txt') # works as the internal path is updated with the first rename
+
+  class Entry
+    # The remote path of the file.
+    attr_reader :path
+
+    def initialize(session, path) # :nodoc:
+      @session = session
+      @path = path
+    end
+
+    # Delegates to Dropbox::API#metadata.
+
+    def metadata(options={})
+      @session.metadata path, options
+    end
+    alias :info :metadata
+    
+    # Delegates to Dropbox::API#list
+
+    def list(options={})
+      @session.list path, options
+    end
+    alias :ls :list
+
+    # Delegates to Dropbox::API#move.
+
+    def move(dest, options={})
+      result = @session.move(path, dest, options)
+      @path = result.path.gsub(/^\//, '')
+      return result
+    end
+    alias :mv :move
+
+    # Delegates to Dropbox::API#rename.
+
+    def rename(name, options={})
+      result = @session.rename(path, name, options)
+      @path = result.path.gsub(/^\//, '')
+      return result
+    end
+
+    # Delegates to Dropbox::API#copy.
+
+    def copy(dest, options={})
+      @session.copy path, dest, options
+    end
+    alias :cp :copy
+
+    # Delegates to Dropbox::API#delete.
+
+    def delete(options={})
+      @session.delete path, options
+    end
+    alias :rm :delete
+
+    # Delegates to Dropbox::API#download.
+
+    def download(options={})
+      @session.download path, options
+    end
+    alias :body :download
+
+    # Delegates to Dropbox::API#link.
+
+    def link(options={})
+      @session.link path, options
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.to_s} #{path}>"
+    end
+  end
+end

data/lib/dropbox/event.rb

@@ -0,0 +1,109 @@
+# Defines the Dropbox::Event class.
+
+nil # doc fix
+
+module Dropbox
+  
+  # The Dropbox::Event class stores information about which entries were
+  # modified during a pingback event. You initialize this class from the JSON
+  # string given to you by Dropbox during a pingback:
+  #
+  #  event = Dropbox::Event.new(params[:target_events])
+  #
+  # Once this is complete, the Dropbox::Event instance contains references for
+  # each of the entries, with the basic information included in the pingback:
+  #
+  #  event.user_ids #=> [ 1, 2, 3 ]
+  #  event.entries(1).first #=> #<Dropbox::Revision 1:10:100>
+  #
+  # For any of these entries, you can load its content and metadata:
+  #
+  #  event.entries(1).first.load(dropbox_session)
+  #  event.entries(1).first.content #=> "Content of file..."
+  #  event.entries(1).first.size #=> 2245
+  #
+  # You can also load only the metadata for all of a user's entries:
+  #
+  #  event.load_metadata(first_users_dropbox_session)
+  #  event.entries(1).first.size #=> 154365
+  
+  class Event
+    def initialize(json_pingback) # :nodoc:
+      @json_pingback = json_pingback
+      begin
+        @metadata = JSON.parse(json_pingback).stringify_keys_recursively
+      rescue JSON::ParserError
+        raise Dropbox::ParseError, "Invalid pingback event data"
+      end
+
+      process_pingback
+    end
+    
+    # Returns an array of Dropbox user ID's involved in this pingback.
+    
+    def user_ids
+      @entries_by_user_id.keys
+    end
+
+    # When given no arguments, returns an array of all entries (as
+    # Dropbox::Revision instances). When given a user ID, filters the list
+    # to only entries belonging to that Dropbox user.
+
+    def entries(user_id=nil)
+      user_id ? (@entries_by_user_id[user_id.to_i] || []).dup : @entries.dup
+    end
+
+    # Loads the metadata for all entries belonging to a given Dropbox session.
+    # Does not load data for files that do not belong to the user owning the
+    # given Dropbox session.
+    #
+    # Future calls to this method will result in additional network requests,
+    # though the Dropbox::Revision instances do cache their metadata values.
+    #
+    # Options:
+    #
+    # +mode+:: Temporarily changes the API mode. See the Dropbox::API::MODES
+    #          array.
+
+    def load_metadata(session, options={})
+      process_metadata session.event_metadata(@json_pingback, options).stringify_keys_recursively
+    end
+    
+    def inspect # :nodoc:
+      "#<#{self.class.to_s} (#{@entries.size} entries)>"
+    end
+    
+    private
+
+    def process_pingback
+      @entries = Array.new
+      @entries_by_user_id = Hash.new
+      @entries_hashed = Hash.new
+
+      @metadata.each do |user_id, namespaces|
+        @entries_hashed[user_id.to_i] = Hash.new
+        @entries_by_user_id[user_id.to_i] = Array.new
+        namespaces.each do |namespace_id, journals|
+          @entries_hashed[user_id.to_i][namespace_id.to_i] = Hash.new
+          journals.each do |journal_id|
+            entry = Dropbox::Revision.new(user_id.to_i, namespace_id.to_i, journal_id.to_i)
+            @entries << entry
+            @entries_by_user_id[user_id.to_i] << entry
+            @entries_hashed[user_id.to_i][namespace_id.to_i][journal_id.to_i] = entry
+          end
+        end
+      end
+    end
+
+    def process_metadata(metadata)
+      p metadata
+      metadata.each do |user_id, namespaces|
+        namespaces.each do |namespace_id, journals|
+          journals.each do |journal_id, attributes|
+            @entries_hashed[user_id.to_i][namespace_id.to_i][journal_id.to_i].process_metadata(attributes.symbolize_keys)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dropbox/memoization.rb

@@ -0,0 +1,98 @@
+# Defines the Dropbox::Memoization module.
+
+nil # doc fix
+
+module Dropbox
+
+  # Adds methods to the Dropbox::Session class to support the temporary local
+  # storage of API results to reduce the number of network calls and simplify
+  # code.
+  #
+  # Memoization is <b>opt-in</b>; you must explicitly indicate that you want
+  # this functionality by calling the enable_memoization method on your
+  # Scribd::Session instance. Once memoization is enabled, subsequent calls to
+  # memoized methods will hit an in-memory cache as opposed to making identical
+  # network calls.
+  #
+  # If you would like to use your own caching strategy (for instance, your own
+  # memcache instance), set the +cache_proc+ and +cache_clear_proc+ attributes.
+  #
+  # Enabling memoization makes removes an instance's thread-safety.
+  #
+  # Example:
+  #
+  #  session.metadata('file1') # network
+  #
+  #  session.enable_memoization
+  #  session.metadata('file1') # network
+  #  session.metadata('file1') # cache
+  #
+  #  session.metadata('file2') # network
+  #  session.metadata('file2') # cache
+  #
+  #  session.disable_memoization
+  #  session.metadata('file2') # network
+
+  module Memoization
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+    end
+
+    # The cache_proc is a proc with two arguments, the cache identifier and the
+    # proc to call and store in the event of a cache miss:
+    #
+    #  instance.cache_proc = Proc.new do |identifier, calculate_proc|
+    #    Rails.cache.fetch(identifier) { calculate_proc.call }
+    #  end
+    #
+    # The Cache identifier will always be 64 lowercase hexadecimal characters.
+    # The second argument is a curried proc including all arguments to the
+    # original method call.
+
+    def cache_proc=(prc)
+      @_memo_cache_proc = prc
+    end
+
+    # The cache_clear_proc takes an identifier and should invalidate it from the
+    # cache:
+    #
+    #  instance.cache_clear_proc = Proc.new { |identifier| Rails.cache.delete identifier }
+
+    def cache_clear_proc=(prc)
+      @_memo_cache_clear_proc = prc
+    end
+
+    # Begins memoizing the results of API calls. Memoization is off by default
+    # for new instances.
+
+    def enable_memoization
+      @_memoize = true
+      @_memo_identifiers ||= Set.new
+    end
+
+    # Halts memoization of API calls and clears the memoization cache.
+
+    def disable_memoization
+      @_memoize = false
+      @_memo_identifiers.each { |identifier| (@_memo_cache_clear_proc || Proc.new { |ident| eval "@_memo_#{ident} = nil" }).call(identifier) }
+      @_memo_identifiers.clear
+    end
+
+    module ClassMethods # :nodoc:
+      def memoize(*method_names) # :nodoc:
+        method_names.each do |meth|
+          define_method :"#{meth}_with_memo" do |*args|
+            if @_memoize then
+              identifier = Digest::SHA1.hexdigest(meth.to_s + ":" + args.to_yaml)
+              @_memo_identifiers << identifier
+              (@_memo_cache_proc || Proc.new { |ident, calculate_proc| eval "@_memo_#{ident} ||= calculate_proc.call" }).call identifier, Proc.new { send :"#{meth}_without_memo", *args }
+            else
+              send :"#{meth}_without_memo", *args
+            end
+          end
+          alias_method_chain meth, :memo
+        end
+      end
+    end
+  end
+end

data/lib/dropbox/revision.rb

@@ -0,0 +1,197 @@
+# Defines the Dropbox::Revision class.
+
+nil # doc fix
+
+module Dropbox
+
+  # A file or folder at a point in time as referenced by a Dropbox::Event
+  # pingback event. Instances start out as "shells" only storing enough
+  # information to uniquely identify a file/folder belonging to a user at a
+  # certain revision.
+  #
+  # Instances of this class only appear in a Dropbox::Event object. To load the
+  # metadata for a revision, use the Dropbox::Event#load_metadata method.
+  # To load the content of the file at this revision, use the load_content
+  # method on this class.
+  #
+  # Once the metadata has been loaded, you can access it directly:
+  #
+  #  revision.size #=> 2962
+  #
+  # The +mtime+ attribute will be a Time instance.  The +mtime+ and +size+
+  # attributes will be +nil+ (not -1) if the file was deleted. All other
+  # attributes are as defined in
+  # http://developers.getdropbox.com/base.html#event-metadata
+  #
+  # If the metadata could not be read for whatever reason, the HTTP error code
+  # will be stored in the +error+ attribute.
+
+  class Revision
+    # The ID of the Dropbox user that owns this file.
+    attr_reader :user_id
+    # The namespace ID of the file (Dropbox internal).
+    attr_reader :namespace_id
+    # The journal ID of the file (Dropbox internal).
+    attr_reader :journal_id
+    # The HTTP error code received when trying to load metadata, or +nil+ if no
+    # error has yet been received.
+    attr_reader :error
+
+    def initialize(uid, nid, jid) # :nodoc:
+      @user_id = uid
+      @namespace_id = nid
+      @journal_id = jid
+    end
+
+    # The unique identifier string used by some Dropbox event API methods.
+
+    def identifier
+      "#{user_id}:#{namespace_id}:#{journal_id}"
+    end
+
+    # Uses the given Dropbox::Session to load the content and metadata for a
+    # file at a specific revision.
+    #
+    # Options:
+    #
+    # +mode+:: Temporarily changes the API mode. See the Dropbox::API::MODES
+    #          array.
+
+    def load(session, options={})
+      @content, @metadata = session.event_content(identifier, options)
+      @metadata.symbolize_keys!
+
+      postprocess_metadata
+    end
+
+    # Returns true if the content for this revision has been previously loaded
+    # and is cached in this object.
+
+    def content_loaded?
+      @content.to_bool
+    end
+
+    # Returns true if the metadata for this revision has been previously loaded
+    # and is cached in this object.
+
+    def metadata_loaded?
+      @metadata.to_bool
+    end
+
+    # Sugar for the +latest+ attribute.
+
+    def latest?
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.latest
+    end
+
+    # Sugar for the +is_dir+ attribute.
+
+    def directory?
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.is_dir
+    end
+
+    # Synonym for the +mtime+ attribute, for "duck" compatibility with the
+    # Dropbox +metadata+ API.
+
+    def modified
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.mtime
+    end
+
+    # Returns true if an error occurred when trying to load metadata.
+
+    def error?
+      error.to_bool
+    end
+    
+    # Returns true if this change represents the file being deleted.
+    
+    def deleted?
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.mtime.nil? and self.size.nil?
+    end
+
+    # Returns the contents of the file as a string. Returns nil for directories.
+    # You must call load first to retrieve the content from the network.
+
+    def content
+      raise NotLoadedError.new(:content) unless content_loaded?
+      @content
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.to_s} #{identifier}>"
+    end
+
+    # Allows you to access metadata attributes directly:
+    #
+    #  revision.size #=> 10526
+    #
+    # A NoMethodError will be raised if the metadata has not yet been loaded for
+    # this revision, so be sure to call metadata_loaded? beforehand.
+
+    def method_missing(meth, *args)
+      if args.empty? then
+        if @metadata and @metadata.include?(meth) then
+          return @metadata[meth]
+        else
+          super
+        end
+      else
+        super
+      end
+    end
+
+    # Loads the metadata for the latest revision of the entry and returns it as
+    # as <tt>Struct</tt> object. Uses the given session and calls
+    # Dropbox::API.metadata.
+    #
+    # If the metadata for this object has not yet been loaded, raises an error.
+    # Options are passed to Dropbox::API.metadata.
+
+    def metadata_for_latest_revision(session, options={})
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      session.metadata self.path, options
+    end
+
+    def process_metadata(metadata) # :nodoc:
+      if metadata[:error] then
+        @error = metadata[:error] unless @metadata
+        return
+      end
+
+      @error = nil
+      @metadata = Hash.new
+      metadata.each { |key, value| @metadata[key.to_sym] = value }
+
+      postprocess_metadata
+    end
+
+    private
+
+    def postprocess_metadata
+      @metadata[:size] = nil if @metadata[:size] == -1
+      @metadata[:mtime] = (@metadata[:mtime] == -1 ? nil : Time.at(@metadata[:mtime])) if @metadata[:mtime]
+      @metadata[:ts] = Time.parse(@metadata[:ts]) if @metadata[:ts]
+    end
+  end
+
+  # Raised when trying to access content metadata before it has been loaded.
+
+  class NotLoadedError < StandardError
+    
+    # What data did you attempt to access before it was loaded? Either
+    # <tt>:content</tt> or <tt>:metadata</tt>.
+    attr_reader :data
+
+    def initialize(data) # :nodoc:
+      @data = data
+    end
+
+    def to_s # :nodoc:
+      "#{data.capitalize} not yet loaded -- call #load on the Dropbox::Revision instance beforehand"
+    end
+  end
+end