cloudfs 1.0.0

data/lib/cloudfs/filesystem_common.rb

@@ -0,0 +1,228 @@
+require_relative 'rest_adapter'
+
+module CloudFS
+  # @private
+  # Provides common filesystem operations consumed by other classes
+  module FileSystemCommon
+    extend self
+
+    # @return [Audio, Video, Photo, Document, File] based on mime type
+    def create_file_from_mime_type(rest_adapter, parent: nil,
+                                   in_trash: false, in_share: false, old_version: false, ** hash)
+      require_relative 'file'
+      require_relative 'media'
+
+      mime = hash[:mime]
+      if mime.include?('audio')
+        Audio.new(rest_adapter, parent: parent,
+                  in_trash: in_trash, in_share: in_share,
+                  old_version: old_version, ** hash)
+      elsif mime.include?('video')
+        Video.new(rest_adapter, parent: parent,
+                  in_trash: in_trash, in_share: in_share,
+                  old_version: old_version, ** hash)
+      elsif mime.include?('image')
+        Photo.new(rest_adapter, parent: parent,
+                  in_trash: in_trash, in_share: in_share,
+                  old_version: old_version, ** hash)
+      elsif mime.include?('text') || mime.include?('pdf')
+        Document.new(rest_adapter, parent: parent,
+                     in_trash: in_trash, in_share: in_share,
+                     old_version: old_version, ** hash)
+      else
+        File.new(rest_adapter, parent: parent,
+                 in_trash: in_trash, in_share: in_share,
+                 old_version: old_version, ** hash)
+      end
+    end
+
+
+    # Create item from hash
+    # @param rest_adapter [RestAdapter] RESTful Client instance
+    # @param parent [Item, String] parent item of type folder
+    # @option parent_state [Hash] parent_state the parent state of the item
+    # @param in_trash [Boolean] set true to specify, item exists in trash
+    # @param in_share [Boolean] set true to specify, item exists in share
+    # @param old_version [Boolean] set true to specify, item is an old version
+    # @param hash [Hash] item properties
+    # @return [File, Folder, Share] item
+    # @raise [RestAdapter::Errors::ArgumentError]
+    #	@review not creating file objects based on mime type,
+    #		since save operation cannot update the class of file object,
+    #		if mime is changed
+    def create_item_from_hash(rest_adapter, parent: nil, parent_state: nil,
+                              in_trash: false, in_share: false, old_version: false, ** hash)
+      require_relative 'file'
+      require_relative 'folder'
+      require_relative 'share'
+
+      return Share.new(rest_adapter, ** hash) if hash.key?(:share_key)
+      fail RestAdapter::Errors::ArgumentError,
+           'Did not recognize item' unless hash.key?(:type)
+      if hash[:type] == 'folder' || hash[:type] == 'root'
+        Folder.new(rest_adapter, parent: parent, parent_state: parent_state,
+                   in_trash: in_trash, in_share: in_share, ** hash)
+      else
+        File.new(rest_adapter, parent: parent, parent_state: parent_state,
+                 in_trash: in_trash, in_share: in_share,
+                 old_version: old_version, ** hash)
+      end
+    end
+
+    # Create array items from corresponding array of hashes
+    # @param hashes [Array<Hash>] array of hash properties of items
+    # @param rest_adapter [RestAdapter] RESTful Client instance
+    # @option parent [Item, String] parent item of type folder
+    # @option parent_state [Hash] parent_state the parent state of the item
+    # @option in_trash [Boolean] set true to specify, items exist in trash
+    # @option in_share [Boolean] set true to specify, items exist in share
+    # @option old_version [Boolean] set true to specify, items are old version
+    # @return [Array<File, Folder, Share>] items
+    # @raise [RestAdapter::Errors::ArgumentError]
+    def create_items_from_hash_array(hashes, rest_adapter,
+                                     parent: nil, parent_state: nil, in_trash: false, in_share: false, old_version: false)
+      items = []
+      hashes.each do |item|
+        resp = create_item_from_hash(rest_adapter, parent: parent, parent_state: parent_state,
+                                     in_trash: in_trash, in_share: in_share,
+                                     old_version: old_version, ** item)
+        items << resp
+      end
+      items
+    end
+
+    # Get folder url
+    # @param folder [Item, String]
+    # @return [String] url of item
+    # @raise [RestAdapter::Errors::ArgumentError]
+    def get_folder_url(folder)
+      return nil if RestAdapter::Utils.is_blank?(folder)
+      return folder.url if (folder.respond_to?(:url) &&
+          folder.respond_to?(:type) && (folder.type == 'folder'))
+      return folder if folder.is_a?(String)
+      fail RestAdapter::Errors::ArgumentError,
+           "Invalid input of type #{folder.class}, expected destination item of type CloudFS::Folder or string"
+    end
+
+    # Get item url
+    # @param item [File, Folder, String]
+    # @return [String] url of item
+    # @raise [RestAdapter::Errors::ArgumentError]
+    def get_item_url(item)
+      return nil if RestAdapter::Utils.is_blank?(item)
+      return item.url if item.respond_to?(:url)
+      return item if item.is_a?(String)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected destination item of type file, folder or string'
+    end
+
+    # Get item name
+    # @param item [File, Folder, String]
+    # @return [String] name of item
+    # @raise [RestAdapter::Errors::ArgumentError]
+    def get_item_name(item)
+      return nil if RestAdapter::Utils.is_blank?(item)
+      return item.name if item.respond_to?(:name)
+      return item if item.is_a?(String)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected destination item of type file, folder or string'
+    end
+
+    # Validate item's current state for operations
+    # @param item [Item] item to validate
+    # @option in_trash [Boolean] set false to avoid check if item in trash
+    # @option in_share [Boolean] set false to avoid check if item in share
+    # @option exists [Boolean] set false to avoid check if item exists
+    # @version version [Boolean] set false to avoid check if item is not current version
+    # @raise [RestAdapter::Errors::InvalidItemError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    def validate_item_state(item, in_trash: true, in_share: true, exists: true,
+                            old_version: true)
+      require_relative 'item'
+      require_relative 'file'
+      return nil unless item.kind_of?(Item)
+      fail RestAdapter::Errors::InvalidItemError,
+           'Operation not allowed as item does not exist anymore' if (exists && item.exists? == false)
+      fail RestAdapter::Errors::OperationNotAllowedError,
+           'Operation not allowed as item is in trash' if (in_trash && item.in_trash?)
+      fail RestAdapter::Errors::OperationNotAllowedError,
+           'Operation not allowed as item is in share' if (in_share && item.in_share?)
+      fail RestAdapter::Errors::OperationNotAllowedError,
+           'Operation not allowed as item is an older version' if (
+      item.kind_of?(CloudFS::File) && old_version && item.old_version?)
+    end
+
+    # Validate share's current state for operations
+    # @param share [Share] share instance to validate
+    # @option exists [Boolean] set false to avoid check if share exists
+    # @raise [RestAdapter::Errors::InvalidShareError,
+    #		RestAdapter::Errors::ArgumentError]
+    def validate_share_state(share, exists: true)
+      require_relative 'share'
+      fail RestAdapter::Errors::ArgumentError,
+           "Invalid object of type #{share.class}, expected Share" unless share.kind_of?(Share)
+      fail RestAdapter::Errors::InvalidShareError,
+           'Operation not allowed as share does not exist anymore' if (exists && share.exists? == false)
+    end
+
+
+    # Fetches properties of named path by recursively listing each member
+    #			starting root with depth 1 and filter=name=path_member
+    # @param rest_adapter [RestAdapter] RESTful Client instance
+    # @option named_path [String] named (not pathid) cloudfs path of item i.e. /a/b/c
+    # @return [Hash] containing url and meta of item
+    # @raise [RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError]
+    def get_properties_of_named_path(rest_adapter, named_path)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected destination string' if RestAdapter::Utils.is_blank?(named_path)
+      fail RestAdapter::Errors::ArgumentError,
+           'invalid rest_adapter, input type must be RestAdapter' unless rest_adapter.is_a?(RestAdapter)
+
+      named_path = "#{named_path}".insert(0, '/') unless (named_path[0] == '/')
+      first, *path_members = named_path.split('/')
+      path = first
+
+      response = []
+      path_members.each do |member|
+        response = rest_adapter.list_folder(path: path, depth: 1,
+                                            filter: "name=#{member}", strict_traverse: true)
+        path << "/#{response.first[:id]}"
+      end
+
+      {url: path, meta: response[0]}
+    end
+
+    # Get an item's properties from server
+    #
+    # @param rest_adapter [RestAdapter] RESTful Client instance
+    # @param parent_url [String] url of parent
+    # @param id [String] pathid of item
+    # @param type [String] ("file", "folder")
+    # @return [Hash] metadata of item
+    #
+    # @raise [RestAdapter::Errors::ServiceError]
+    def get_item_properties_from_server(rest_adapter, parent_url, id, type, in_trash: false)
+      item_url = parent_url.nil? ? "#{id}" : "#{parent_url}/#{id}"
+      if in_trash
+        properties = rest_adapter.browse_trash(path: item_url).fetch(:meta)
+      elsif type == 'folder'
+        properties = rest_adapter.get_folder_meta(item_url)
+      else
+        properties = rest_adapter.get_file_meta(item_url)
+      end
+    end
+
+    # Get an item's properties from server
+    #
+    # @param rest_adapter [RestAdapter] RESTful Client instance
+    # @param item_url [String] url of item
+    # @return File, Folder, Share] item
+    #
+    # @raise [RestAdapter::Errors::ServiceError]
+    def get_item(rest_adapter, item_url)
+      item_meta = rest_adapter.get_file_meta(item_url)
+      create_item_from_hash(rest_adapter, ** item_meta)
+    end
+
+  end
+end	

data/lib/cloudfs/folder.rb

@@ -0,0 +1,94 @@
+require_relative 'container'
+require_relative 'filesystem_common'
+
+
+module CloudFS
+  # Represents a folder in the user's filesystem that can contain files and other folders.
+  #
+  #	@author Mrinal Dhillon
+  #	@example
+  #		folder = session.filesystem.root.create_folder(name_of_folder)
+  #		folder.name = "newname"
+  #		folder.save
+  #		file = folder.upload(local_file_path)
+  #		folder.list		#=> Array<File, Folder>
+  class Folder < Container
+
+    # Upload file to this folder
+    #
+    # @param file_system_path [String, #read&#pos&#pos=] local file path, in-memory string,
+    #		an io object for example StringIO, File, Tempfile.
+    # @param name [String] default: nil, name of uploaded file, must be set
+    #		if file_system_path does not respond to #path unless file_system_path is local file path
+    # @param exists [String] ('FAIL', 'OVERWRITE', 'RENAME')
+    #		action to take in case of a conflict with an existing folder.
+    #	@param upload_io [Boolean] default: false,
+    #		if set to false, file_system_path is considered to be a local file path
+    #
+    # @return [File] instance reference to uploaded file
+    # @raise [Client::Errors::SessionNotLinked, Client::Errors::ServiceError,
+    #		Client::Errors::InvalidItemError, Client::Errors::OperationNotAllowedError]
+    # @example
+    #		Upload local file path
+    #			file = folder.upload(local_file_path, name: "testfile.txt")
+    #	@example
+    #		Upload ::File instance
+    # 	file = ::File.open(local_file_path, "r") do |fp|
+    #				folder.upload(fp, name: "testfile.txt", upload_io: true)
+    #		end
+    #	@example
+    #		Upload string
+    #			file = folder.upload("This is upload string",
+    #				name: 'testfile.txt', upload_io: true)
+    #	@example
+    #		Upload stream
+    #			io = StringIO.new
+    #			io.write("this is test stringio")
+    #			file = folder.upload(io, name: 'testfile.txt', upload_io: true)
+    #			io.close
+    def upload(file_system_path, name: nil, exists: 'FAIL', upload_io: false)
+      FileSystemCommon.validate_item_state(self)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected file system path.' if RestAdapter::Utils.is_blank?(file_system_path)
+
+      if upload_io == false
+        response = ::File.open(file_system_path, 'r') do |file|
+          @rest_adapter.upload(@url, file, name: name, exists: exists)
+        end
+      else
+        response = @rest_adapter.upload(@url, file_system_path, name: name, exists: exists)
+      end
+      FileSystemCommon.create_item_from_hash(@rest_adapter,
+                                             parent: @url, ** response)
+    end
+
+    # Create folder under this container
+    #
+    # @param name [String] name of folder to be created
+    # @param exists [String] ('FAIL', 'OVERWRITE', 'RENAME') action to take
+    #		if the item already exists
+    #
+    # @return [Folder] instance
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::ArgumentError, RestAdapter::Errors::InvalidItemError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    def create_folder(name, exists: 'FAIL')
+      FileSystemCommon.validate_item_state(self)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid argument, must pass name' if RestAdapter::Utils.is_blank?(name)
+
+      properties = @rest_adapter.create_folder(name, path: @url, exists: exists)
+      FileSystemCommon.create_item_from_hash(@rest_adapter, parent: @url, ** properties)
+    end
+
+    #	@return [String]
+    #	@!visibility private
+    def to_s
+      "#{self.class}: url #{@url}, name: #{@name}"
+    end
+
+    alias inspect to_s
+    # overriding inherited properties that are not not valid for folder
+    private :blocklist_key, :blocklist_id, :versions, :old_version?
+  end
+end

data/lib/cloudfs/item.rb

@@ -0,0 +1,640 @@
+require_relative 'client/constants'
+require_relative 'filesystem_common'
+require_relative 'rest_adapter'
+
+module CloudFS
+  # An object managed by CloudFS. An item can be either a file or folder.
+  #
+  #	Item is the base class for File, Container whereas Folder is derived from Container
+  #	Provides common APIs for files, folders
+  # @author Mrinal Dhillon
+  class Item
+
+    # @return [String] the internal id of item that is right most path segment in url
+    attr_reader :id
+
+    #	@return [String] id of parent of item
+    attr_reader :parent_id
+
+    # @return [String]	type of item, either file or folder
+    attr_reader :type
+
+    #	@return [String] known current version of item
+    attr_reader :version
+
+    # @return [Boolean] indicating whether the item was created by mirroring a file
+    attr_reader :is_mirrored
+
+    #	@return [String] blocklist_key of file
+    attr_reader :blocklist_key
+
+    #	@return [String] blocklist_id of file
+    attr_reader :blocklist_id
+
+    # @return [String] absolute path of item in user's account
+    attr_reader :url
+
+    # @return [String] absolute path of item in user's account
+    def path
+      @url
+    end
+
+    # name of item
+    #
+    # @param value [String] name.
+    #
+    # @raise [RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    attr_reader :name
+
+    # Sets the new name and updates to CloudFS
+    def name=(new_name)
+      FileSystemCommon.validate_item_state(self)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected new name' if RestAdapter::Utils.is_blank?(new_name)
+
+      @name = new_name
+      @changed_properties[:name] = new_name
+      change_attributes(@changed_properties)
+    end
+
+    #	@!attribute [r] date_created
+    #	Time when item was created
+    # @overload date_created
+    #		@return [Time] creation time
+    def date_created
+      if @date_created
+        Time.at(@date_created)
+      else
+        nil
+      end
+    end
+
+    #	@!attribute [r] date_meta_last_modified
+    #	Time when item's metadata was last modified
+    # @overload date_meta_last_modified
+    #		@return [Time] time when metadata was last modified
+    def date_meta_last_modified
+      if @date_meta_last_modified
+        Time.at(@date_meta_last_modified)
+      else
+        nil
+      end
+    end
+
+    #	@!attribute [r] date_content_last_modified
+    #	Time when item's content was last modified
+    # @overload date_content_last_modified
+    #		@return [Time] time when content was last modified
+    def date_content_last_modified
+      if @date_content_last_modified
+        Time.at(@date_content_last_modified)
+      else
+        nil
+      end
+    end
+
+    def application_data
+      if @application_data
+        Marshal.load(Marshal.dump(@application_data))
+      else
+        {}
+      end
+    end
+
+    def application_data=(hash={})
+      FileSystemCommon.validate_item_state(self)
+      if @application_data
+        @application_data.merge!(hash)
+      else
+        @application_data = hash.dup
+      end
+      @changed_properties[:application_data].merge!(hash)
+      change_attributes(@changed_properties)
+    end
+
+    # @param rest_adapter [RestAdapter] RESTful Client instance
+    # @param parent [Item, String] default: ("/") parent folder item or url
+    # @option parent_state [Hash] parent_state the parent state of the item
+    # @param in_trash [Boolean] set true to specify item exists in trash
+    # @param in_share [Boolean] set true to specify item exists in share
+    # @param old_version [Boolean] set true to specify item is an old version
+    # @param [Hash] properties metadata of item
+    #   @option properties [String] :id path id of item
+    #   @option properties [String] :parent_id (nil) pathid of parent of item
+    #   @option properties [String] :type (nil) type of item either file, folder
+    #   @option properties [String] :name (nil)
+    #   @option properties [Timestamp] :date_created (nil)
+    #   @option properties [Timestamp] :date_meta_last_modified (nil)
+    #   @option properties [Timestamp] :date_content_last_modified (nil)
+    #   @option properties [Fixnum] :version (nil)
+    #   @option properties [Boolean] :is_mirrored (nil)
+    #   @option properties [String] :mime (nil) applicable to item
+    #     type file only
+    #   @option properties [String] :blocklist_key (nil) applicable to item
+    #     type file only
+    #   @option properties [String] :blocklist_id (nil) applicable to item
+    #     type file only
+    #   @option properties [Fixnum] :size (nil) applicable to item of
+    #     type file only
+    #   @option properties [Hash] :application_data ({}) extra metadata of item
+    #
+    # @raise [RestAdapter::Errors::ArgumentError]
+    def initialize(rest_adapter, parent: nil, parent_state: nil, in_trash: false,
+                   in_share: false, old_version: false, ** properties)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid RestAdapter, input type must be CloudFS::RestAdapter' unless rest_adapter.is_a?(RestAdapter)
+
+      @rest_adapter = rest_adapter
+      set_item_properties(parent: parent, parent_state: parent_state, in_trash: in_trash,
+                          in_share: in_share, old_version: old_version, ** properties)
+    end
+
+    # @see #initialize
+    # @review required properties
+    def set_item_properties(parent: nil, parent_state: nil, in_trash: false,
+                            in_share: false, old_version: false, ** params)
+      # id, type and name are required instance variables
+      @id = params.fetch(:id) {
+        fail RestAdapter::Errors::ArgumentError, 'Provide item id' }
+      @type = params.fetch(:type) {
+        fail RestAdapter::Errors::ArgumentError, 'Provide item type' }
+      @name = params.fetch(:name) {
+        fail RestAdapter::Errors::ArgumentError, 'Provide item name' }
+
+      @type = 'folder' if @type == 'root'
+      @parent_id = params[:parent_id]
+      @date_created = params[:date_created]
+      @date_meta_last_modified = params[:date_meta_last_modified]
+      @date_content_last_modified = params[:date_content_last_modified]
+      @version = params[:version]
+
+      if @type == 'file'
+        @is_mirrored = params[:is_mirrored]
+        @mime = params[:mime]
+        @blocklist_key = params[:blocklist_key]
+        @extension = params[:extension]
+        @blocklist_id = params[:blocklist_id]
+        @size = params[:size]
+      end
+
+      @application_data = params[:application_data]
+      @in_trash = in_trash
+      @in_share = in_share
+      @old_version = old_version
+      @exists = true
+
+      @state = parent_state
+
+      set_url(parent)
+      changed_properties_reset
+    end
+
+    #	@return [Boolean] whether the item is an older version
+    def old_version?
+      @old_version
+    end
+
+    #	@return [Boolean] whether the item exists in trash
+    def in_trash?
+      @in_trash
+    end
+
+    #	@return [Boolean] whether the item exists in share
+    def in_share?
+      @in_share
+    end
+
+    # @return [Boolean] whether item exists, false if item
+    #		has been deleted permanently
+    def exists?
+      @exists
+    end
+
+    # Reset changed properties
+    def changed_properties_reset
+      @changed_properties = {application_data: {}}
+    end
+
+
+    # Move this item to destination folder
+    # @note	Updates this item and it's reference is returned.
+    # @note Locally changed properties get discarded
+    #
+    # @param destination [Item, String] destination to move item to, should be folder
+    # @param name [String] (nil) new name of moved item
+    # @param exists [String] ('FAIL', 'OVERWRITE', 'RENAME')
+    #		action to take in case of a conflict with an existing folder, default 'RENAME'
+    #
+    # @return [Item] returns self
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError,
+    #   RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    def move(destination, name: nil, exists: 'RENAME')
+      FileSystemCommon.validate_item_state(self)
+      FileSystemCommon.validate_item_state(destination)
+
+      destination_url = FileSystemCommon.get_folder_url(destination)
+      name ||= @name
+
+      if @type == 'folder'
+        response = @rest_adapter.move_folder(
+            @url,
+            destination_url,
+            name,
+            exists: exists)
+      else
+        response = @rest_adapter.move_file(
+            @url,
+            destination_url,
+            name,
+            exists: exists)
+      end
+      # Overwrite this item's properties with Moved Item's properties
+      set_item_properties(parent: destination_url, ** response)
+      self
+    end
+
+    # Copy this item to destination
+    # @note	Locally changed properties are not copied
+    #
+    # @param destination [Item, String] destination to copy item to,
+    #   should be folder
+    # @param name [String] (nil) new name of copied item
+    # @param exists [String] ('FAIL', 'OVERWRITE', 'RENAME')
+    #		action to take in case of a conflict with an existing folder,
+    #   default 'RENAME'
+    #
+    # @return [Item] new instance of copied item
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError,
+    #   RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    def copy(destination, name: nil, exists: 'RENAME')
+      FileSystemCommon.validate_item_state(self)
+      FileSystemCommon.validate_item_state(destination)
+
+      destination_url = FileSystemCommon.get_folder_url(destination)
+      name = @name unless name
+
+      if @type == 'folder'
+        response = @rest_adapter.copy_folder(
+            @url,
+            destination_url,
+            name,
+            exists: exists)
+      else
+        response = @rest_adapter.copy_file(
+            @url,
+            destination_url,
+            name,
+            exists: exists)
+      end
+      FileSystemCommon.create_item_from_hash(
+          @rest_adapter,
+          parent: destination_url,
+          ** response)
+    end
+
+    # Delete this item
+    # @note Updates this item if operation is successful
+    # @note	Locally changed properties get discarded
+    #
+    # @param commit [Boolean] (false) set true to remove item permanently,
+    #		else will be moved to trash, RestAdapter::Errors::InvalidItemError
+    #   is raised for subsequent operation if commit: true
+    # @param force [Boolean] (false) set true to delete non-empty folder
+    # @param raise_exception [Boolean] (false)
+    #		method suppresses exceptions and returns false if set to false,
+    #			added so that consuming application can control behaviour
+    #
+    # @return [Boolean] whether operation is successful
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    #
+    #		if raise_exception is true
+    def delete(commit: false, force: false, raise_exception: false)
+      FileSystemCommon.validate_item_state(self, in_trash: false)
+
+      if @in_trash
+        # @review NOOP if commit is false since item is already in trash, return true
+        if commit
+          @rest_adapter.delete_trash_item(path: @url)
+          @exists = false
+          @in_trash = false
+        end
+        return true
+      end
+
+      if @type == 'folder'
+        @rest_adapter.delete_folder(@url, commit: commit, force: force)
+      else
+        @rest_adapter.delete_file(@url, commit: commit)
+      end
+
+      if commit
+        @exists = false
+        @in_trash = false
+      else
+        @application_data[:_bitcasa_original_path] = ::File.dirname(@url)
+        set_url(nil)
+        @in_trash = true
+      end
+      changed_properties_reset
+      true
+    rescue RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError,
+        RestAdapter::Errors::OperationNotAllowedError, RestAdapter::Errors::InvalidItemError
+      raise $! if raise_exception
+      false
+    end
+
+    # Get this item's properties from server
+    # @return [Hash] metadata of this item
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError]
+    def get_properties_from_server
+      if @in_trash
+        properties = @rest_adapter.browse_trash(path: @url).fetch(:meta)
+      elsif @type == 'folder'
+        properties = @rest_adapter.get_folder_meta(@url)
+      else
+        properties = @rest_adapter.get_file_meta(@url)
+      end
+    end
+
+    # Refresh this item's properties from server
+    #
+    #	@note	Locally changed properties get discarded
+    #
+    # @return [Item] returns self
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    def refresh
+      FileSystemCommon.validate_item_state(self, in_trash: false, in_share: false)
+
+      properties = get_properties_from_server
+      parent_url = ::File.dirname(@url)
+
+      set_item_properties(
+          parent: parent_url,
+          in_trash: @in_trash,
+          in_share: @in_share,
+          ** properties)
+      self
+    end
+
+    # Sets restored item's url and properties based on exists and destination url
+    # This method is called to update this item after it has been restored.
+    #		If exist == 'Fail' then this item's expected url is its original path
+    #			elseif exists == 'RESCUE' the url should be destination_url/(item's trashid)
+    #			elseif exists == 'RECREATE' then url should be
+    #					(url of named path)/(item' trashid)
+    #
+    # @param destination_url [String] ('RESCUE' (default root), RECREATE(named path))
+    #		path depending on exists option to place item into
+    #		if the original path does not exist.
+    # @param exists [String] ('FAIL', 'RESCUE', 'RECREATE')
+    #		action to take if the recovery operation encounters issues, default 'FAIL'
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError]
+    def set_restored_item_properties(destination_url, exists)
+      begin
+        parent_url = @application_data[:_bitcasa_original_path]
+        properties = FileSystemCommon.get_item_properties_from_server(
+            @rest_adapter,
+            parent_url,
+            @id,
+            @type)
+      rescue
+        raise $! if exists == 'FAIL'
+
+        if exists == 'RESCUE'
+          parent_url = destination_url
+          properties = FileSystemCommon.get_item_properties_from_server(
+              @rest_adapter,
+              parent_url,
+              @id,
+              @type)
+
+        elsif exists == 'RECREATE'
+          response = FileSystemCommon.get_properties_of_named_path(
+              @rest_adapter,
+              destination_url)
+
+          parent_url = response[:url]
+          properties = FileSystemCommon.get_item_properties_from_server(
+              @rest_adapter,
+              parent_url,
+              @id,
+              @type)
+        end
+      end
+      set_item_properties(parent: parent_url, in_trash: false, ** properties)
+    end
+
+    # Restore this item from trash
+    # @note This item's properties are updated if successful
+    #
+    # @param destination [Folder, String] ('RESCUE' (default root),
+    #		RECREATE(named path)) destination folder path depending on exists
+    #		option to place item into if the original path does not exist.
+    # @param method [String] ('FAIL', 'RESCUE', 'RECREATE')
+    #		action to take if the recovery operation encounters issues, default 'FAIL'
+    # @param raise_exception [Boolean] (false)
+    #		method suppresses exceptions and returns false if set to false,
+    #			added so that consuming application can control behaviour
+    # @param restore_argument [String] update this item after it has been restored
+    #
+    # @return [Boolean] true/false
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError,
+    #   RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError] if raise_exception is true
+    #
+    # @note exist: 'RECREATE' with named path is expensive operation
+    #		as items in named path hierarchy are traversed
+    #		in order to fetch Restored item's properties.
+    #
+    # @example
+    #		item.restore
+    #		item.restore("/FOPqySw3ToK_25y-gagUfg", exists: 'RESCUE')
+    #		item.restore(folderobj, exists: 'RESCUE')
+    #		item.restore("/depth1/depth2", exists: 'RECREATE')
+    def restore(destination, method: 'FAIL', restore_argument: nil, raise_exception: false) # restore argument.
+      fail RestAdapter::Errors::OperationNotAllowedError,
+           'Item needs to be in trash for Restore operation' unless @in_trash
+      FileSystemCommon.validate_item_state(destination)
+
+      destination_url = FileSystemCommon.get_folder_url(destination)
+      @rest_adapter.recover_trash_item(
+          @url,
+          destination: destination_url,
+          restore: method)
+
+      if restore_argument
+        set_restored_item_properties(destination_url, method)
+      end
+
+      true
+    rescue RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError,
+        RestAdapter::Errors::ArgumentError, RestAdapter::Errors::InvalidItemError,
+        RestAdapter::Errors::OperationNotAllowedError
+      raise $! if raise_exception
+      false
+    end
+
+    # List versions of this item if file.
+    #	@note The list of files returned are mostly non-functional,
+    #		though their meta-data is correct.
+    #
+    # @param start_version [Fixnum] version number to begin listing file versions
+    # @param stop_version [Fixnum] version number from which to stop
+    #		listing file versions
+    # @param limit [Fixnum] how many versions to list in the result set.
+    #		It can be negative to list items prior to given start version
+    #
+    # @return [Array<Item>] listed versions
+    #
+    #	@raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    #
+    #	@review confirm if versions should be allowed for items in trash, in share
+    def versions(start_version: 0, stop_version: nil, limit: 10)
+      FileSystemCommon.validate_item_state(self, in_trash: false, in_share: false)
+      fail OperationNotAllowedError,
+           "Operation not allowed for item of type #{@type}" unless @type == 'file'
+
+      response = @rest_adapter.list_file_versions(
+          @url,
+          start_version: start_version,
+          stop_version: stop_version,
+          limit: limit)
+
+      FileSystemCommon.create_items_from_hash_array(
+          response, @rest_adapter,
+          parent: @url,
+          in_share: @in_share,
+          in_trash: @in_trash,
+          old_version: true)
+    end
+
+    # Save this item's current state.
+    #		Locally changed properties are committed to this item in user's account
+    #
+    # @param version_conflict [String] ('FAIL', 'IGNORE') action to take
+    #		if the version on this item does not match the version on the server
+    #
+    # @return [Item] returns self
+    #
+    #	@raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError,
+    #   RestAdapter::Errors::InvalidItemError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    def save(version_conflict: 'FAIL')
+      FileSystemCommon.validate_item_state(self)
+      return self if RestAdapter::Utils.is_blank?(@changed_properties)
+
+      if @type == 'folder'
+        response = @rest_adapter.alter_folder_meta(
+            @url,
+            @version,
+            version_conflict: version_conflict,
+            ** @changed_properties)
+      else
+        response = @rest_adapter.alter_file_meta(
+            @url,
+            @version,
+            version_conflict: version_conflict,
+            ** @changed_properties)
+      end
+
+      parent_url = ::File.dirname(@url)
+      set_item_properties(parent: parent_url, ** response)
+      self
+    end
+
+    # Gets properties in hash format
+    # @return [Hash] metadata of item
+    def get_properties_in_hash
+      properties = {
+          :'name' => "#{@name}",
+          :'date_created' => "#{@date_created}",
+          :'date_meta_last_modified' => "#{@date_meta_last_modified}",
+          :'date_content_last_modified' => "#{@date_content_last_modified}",
+          :'extension' => "#{@extension}",
+          :'mime' => "#{@mime}",
+          :'application_data' => @application_data
+      }
+      properties
+    end
+
+    # Sets the url of item
+    #
+    # @param parent [Folder, String]
+    #
+    # @return [void]
+    def set_url(parent)
+      parent_url = FileSystemCommon.get_folder_url(parent)
+      @url = parent_url == '/' ? "/#{@id}" : "#{parent_url}/#{@id}"
+    end
+
+    #	@return [String]
+    #	@!visibility private
+    def to_s
+      "#{self.class}: url #{@url}, name: #{@name}"
+    end
+
+    alias inspect to_s
+
+    #	@return [Boolean]
+    #	@!visibility private
+    def eql?(item)
+      self.class.equal?(item.class) &&
+          item.respond_to?(:id) &&
+          item.id == @id
+    end
+
+    # Changes the attributes of a given file or folder.
+    #
+    # @param values [Hash] attribute changes.
+    # @param if_conflict [String] ('FAIL', 'IGNORE') action to take
+    #		if the version on this item does not match the version on the server.
+    #
+    #	@return [Boolean] based on the success or fail status of the action.
+    def change_attributes(values, if_conflict: 'FAIL')
+      if @type == 'folder'
+        response = @rest_adapter.alter_folder_meta(
+            @url,
+            @version,
+            version_conflict: if_conflict,
+            ** values)
+      else
+        response = @rest_adapter.alter_file_meta(
+            @url,
+            @version,
+            version_conflict: if_conflict,
+            ** values)
+      end
+
+      parent_url = ::File.dirname(@url)
+      set_item_properties(parent: parent_url, ** response)
+      response.has_key?(:id)
+    end
+
+    alias == eql?
+    private :set_item_properties, :changed_properties_reset,
+            :set_restored_item_properties, :get_properties_in_hash, :set_url,
+            :get_properties_from_server
+  end
+end