nvx-sds 0.0.1

data/lib/nvx/sds/folder.rb

@@ -0,0 +1,236 @@
+# = Overview
+# The Folder object is used for all folder operations and to get access to 
+# files. The object is initially retrieved by calling Session.GetRootFolder.
+#
+# = Usage
+#   session = Session.new("APP-KEY", "USERNAME", "APP NAME", "PASSWORD")
+#   root_folder = session.GetRootFolder(1, 500, 0, true)
+#
+#   root_folder.folders.each do |folder|
+#       print folder.name
+#   end
+#
+# = Notes
+# * The maximum number of items reutrned in a single page is 500
+# * The folder sort codes are "Name", "CreatedDate", "SizeBytes", "FileType"
+# * LoadChildren must be called to handle paging, due to memory concerns we didnt want to return too many items
+#   in one request, doing so could cause problems for people using shared servers with memory caps or
+#   other limitations.
+module NVX
+    module SDS
+        
+        $:.unshift File.dirname(__FILE__)
+
+        require 'pathname'
+        require 'itembase'
+        require 'apiparam'
+        require 'apicommand'
+        require 'transport'
+        require 'nvxfile'
+        require 'apiclasses/fsfolderlist'
+
+        # = Overview
+        # The Folder object is used for all folder operations and to get access to 
+        # files. The object is initially retrieved by calling Session.GetRootFolder.
+        #
+        # = Usage
+        #   session = Session.new("APP-KEY", "USERNAME", "APP NAME", "PASSWORD")
+        #   root_folder = session.GetRootFolder(1, 500, 0, true)
+        #
+        #   root_folder.folders.each do |folder|
+        #       print folder.name
+        #   end
+        #
+        # = Notes
+        # * The maximum number of items reutrned in a single page is 500
+        # * The folder sort codes are "Name", "CreatedDate", "SizeBytes", "FileType"
+        # * LoadChildren must be called to handle paging, due to memory concerns we didnt want to return too many items
+        #   in one request, doing so could cause problems for people using shared servers with memory caps or
+        #   other limitations.
+        class Folder < ItemBase
+
+            # Private constructor use the ListFolder or look in the Folders to get
+            # this object directly.
+            private 
+            def initialize(account_login, fs_folder_list, fs_folder_attributes)
+                super(account_login, fs_folder_attributes)
+                @folders = Array.new
+                @files = Array.new
+                @account_login = account_login
+
+                if !fs_folder_list.nil?
+                    @fs_folder_list = fs_folder_list
+
+                    @total_file_count = @fs_folder_list.total_file_count
+                    @total_folder_count = @fs_folder_list.total_folder_count
+                    @page_file_count = @fs_folder_list.page_file_count
+                    @page_folder_count = @fs_folder_list.page_folder_count
+
+                    fs_folder_list.folder_attributes.each do |attribute|
+                        @folders << Folder.new(account_login, nil, attribute)
+                    end
+                    
+                    fs_folder_list.file_attributes.each do |attribute|
+                        @files << NVXFile.new(account_login, attribute)
+                    end
+                    
+                end
+            end
+
+            public
+            # Returns a list of folders with root children loaded.  Be sure to call loadChildren to
+            # get the paged child folders and files.
+            def Folder.ListFolder(account_login, path, page_number, page_size, folder_sort_code, should_sort_descending)
+                params = [APIParam.new("pageNumber", page_number),
+                    APIParam.new("pageSize", page_size),
+                    APIParam.new("folderPath", path)]
+                    
+                params << APIParam.new("folderSortCode", folder_sort_code) if !folder_sort_code.nil?
+                params << APIParam.new("shouldSortDescending", should_sort_descending) if !should_sort_descending.nil?
+                
+                result = Transport.execute_command_post(APICommand.ListFolder, params, account_login)
+
+                p = Pathname.new(path)
+
+                attributes = FSFolderAttributes.new(nil)
+                attributes.EmptyRootFolder(p.basename, p.cleanpath, nil)
+
+                return Folder.new(account_login, FSFolderList.new(result.to_s), attributes)
+            end
+            
+            # Date the folder was created.
+            def created_date
+                @created_date
+            end
+
+            # The array of NVXFile objects.
+            def files 
+                if @files.nil?
+                    raise "The children were not loaded."
+                end
+                @files
+            end
+
+            # The array of Folder objects.
+            def folders
+                if @folders.nil?
+                    raise "The children were not loaded."
+                end
+                @folders
+            end
+
+            # Total number of files outside of paging, this can be used to determine
+            # when you need to page.
+            def total_file_count
+                @total_file_count
+            end
+        
+            # Total number of folders outside of paging, this can be used to determine
+            # when you need to page.
+            def total_folder_count
+                @total_folder_count
+            end
+        
+            # The current paged folders count.
+            def page_folder_count
+                @page_folder_count
+            end
+        
+            # The current paged folders count.
+            def page_file_count
+                @page_file_count
+            end
+
+            # Loads children NVXFile and Folder objects including any metadata.
+            def LoadChildren(page_number, page_size, folder_sort_code = nil, should_sort_descending = nil)
+                #empty the file and folder arrays.
+                @files.clear
+                @folders.clear
+
+                params = [APIParam.new("pageNumber", page_number), 
+                    APIParam.new("pageSize", page_size), 
+                    APIParam.new("folderPath", @path)]
+                    
+                params << APIParam.new("folderSortCode", folder_sort_code) if !folder_sort_code.nil?
+                params << APIParam.new("shouldSortDescending", should_sort_descending) if !should_sort_descending.nil?
+
+                #retrieve the folder information for the current path
+                result = Transport.execute_command_post(APICommand.ListFolder, params, @account_login)
+                
+                #Load the folderlist from the xml
+                @fs_folder_list = FSFolderList.new(result.to_s)
+                
+                #load the folders array from the attributes
+                @fs_folder_list.folder_attributes.each do |folderattrib|
+                    @folders << Folder.new(@account_login, nil, folderattrib)
+                end
+                
+                #load the files array from the attributes
+                @fs_folder_list.file_attributes.each do |fileattrib|
+                    @files << NVXFile.new(@account_login, fileattrib)
+                end
+            end
+
+            #Creates the folder path in the current folder
+            def CreateFolders(folders_to_create)
+                params = Array.new
+                folders_to_create.each do |folder|
+                    params << APIParam.new("folderPath", folder)
+                end
+                Transport.execute_command_post(APICommand.CreateFolders, params, @account_login)
+            end
+            
+            #Copies an array of folders to the current folder
+            def CopyFolders(folders_to_copy)
+                params = [APIParam.new("destFolderPath", @path)]
+                folders_to_copy.each do |folder|
+                    params << APIParam.new("srcFilePath", folder)
+                end
+                Transport.execute_command_post(APICommand.CopyFolders, params, @account_login)
+            end
+
+            #Moves an array of folders to the current folder
+            def MoveFolders(folders_to_move)
+                params = [APIParam.new("destFolderPath", @path)]
+                folders_to_move.each do |folder|
+                    params << APIParam.new("srcFilePath", folder)
+                end
+                Transport.execute_command_post(APICommand.MoveFolders, params, @account_login)
+            end
+            
+            #Copies an array of files to the current folder
+            def CopyFiles(files_to_copy)
+                params = [APIParam.new("destFolderPath", @path)]
+                files_to_copy.each do |file|
+                    params << APIParam.new("srcFilePath", file)
+                end
+                Transport.execute_command_post(APICommand.CopyFiles, params, @account_login)
+            end
+
+            #Moves an array of files to the current folder
+            def MoveFiles(files_to_move)
+                params = [APIParam.new("destFolderPath", @path)]
+                files_to_move.each do |file|
+                    params << APIParam.new("srcFilePath", file)
+                end
+                Transport.execute_command_post(APICommand.MoveFiles, params, @account_login)
+            end
+
+            #Renames the current folder to the new name
+            def Rename(new_name)
+                if @path.to_s == @account_login.root_path.to_s then
+                    raise("You cannot rename the root folder")
+                end
+
+                Transport.execute_command_post(APICommand.RenameFolder, 
+                    [APIParam.new("folderPath", @path), 
+                    APIParam.new("newFolderName", new_name)], @account_login)
+                
+                splitpath = @path.to_s.split("/")
+                splitpath.delete(splitpath.last)
+                splitpath << new_name
+                @path = splitpath.join("/")
+            end
+        end
+    end
+end

data/lib/nvx/sds/hosteditem.rb

@@ -0,0 +1,115 @@
+# = Overview
+# When accessing a file or folder you can share that item publicly.  When listing a hosted
+# item this object is returned to represent a file or folder.  You can do that by calling 
+# session.ListHostedItems.
+#
+# = Usage
+# This quick example shows how to create 
+#       session = Session.new("APP-KEY", "USERNAME", "APP Name", "123123")
+#       root_folder = session.GetRootFolder(1, 500, 0, true)
+#       root_folder.CreateFolders(["testhostfolder"])
+#       root_folder.LoadChildren(1, 500, 0, true)
+#
+#       host_folder = ""
+#       root_folder.folders.each do |folder|
+#           if folder.name == "testhostfolder"
+#               host_folder = folder
+#               break
+#           end
+#       end
+#
+#       host_folder.HostItem
+#       hosted_items = session.ListHostedItems
+#       assert hosted_items.length == 2
+#
+#       host_folder.RemoveHostedItem
+#       session.DeleteFolders([host_folder.path])
+module NVX
+    module SDS
+        
+        $:.unshift File.dirname(__FILE__)
+        require 'transport'
+        require 'apicommand'
+        require 'apiparam'
+        
+        # = Overview
+        # When accessing a file or folder you can share that item publicly.  When listing a hosted
+        # item this object is returned to represent a file or folder.  You can do that by calling 
+        # session.ListHostedItems.
+        #
+        # = Usage
+        # This quick example shows how to create 
+        #       session = Session.new("APP-KEY", "USERNAME", "APP Name", "123123")
+        #       root_folder = session.GetRootFolder(1, 500, 0, true)
+        #       root_folder.CreateFolders(["testhostfolder"])
+        #       root_folder.LoadChildren(1, 500, 0, true)
+        #
+        #       host_folder = ""
+        #       root_folder.folders.each do |folder|
+        #           if folder.name == "testhostfolder"
+        #               host_folder = folder
+        #               break
+        #           end
+        #       end
+        #
+        #       host_folder.HostItem
+        #       hosted_items = session.ListHostedItems
+        #       assert hosted_items.length == 2
+        #
+        #       host_folder.RemoveHostedItem
+        #       session.DeleteFolders([host_folder.path])
+        class HostedItem            
+
+            private
+            # Private method to instantiate the object based on the xml returned.
+            def initialize(account_login, element)
+                @is_file = (text = element.elements["IsFile"].get_text and text.value).downcase == "true" ? true : false
+                @share_path = (text = element.elements["SharePath"].get_text and text.value)
+                @account_login = account_login
+            end
+            
+            public
+            # Returns if the hosted item is a file or not.
+            def is_file?
+                @is_file
+            end
+            
+            # Returns the full shared path to the file.
+            def share_path
+                @share_path
+            end
+
+            # Returns the URL for a file that can be used to download the file publicly.
+            def GetFileUrl
+                if @is_file
+                    raise("Cannot get a download link for a folder.")
+                end
+                
+                Utilities.GetDownloadUrl(@account_login, @share_path, false)
+            end
+            
+            # Returns the list of currently hosted items based on page number and page size.
+            def HostedItem.ListHostedItems(account_login, page_number, page_size)
+                params = [APIParam.new("pageNumber", page_number),
+                            APIParam.new("pageSize", page_size)]
+
+                doc = Transport.execute_command_post(APICommand.ListHostedItems, params, account_login);
+
+                hosted_items = Array.new
+
+                #if there is any metadata loop through
+                if doc.root.elements["//Response/HostedItem"]
+                    doc.root.elements.each("//Response/HostedItem") do |hosted_item|
+                        hosted_items << HostedItem.new(account_login, hosted_item)
+                    end
+                end
+                return hosted_items
+            end
+            
+            # Returns a nicely fomatted string based on the share path and if its a file or folder.
+            def to_s
+                (@is_file ? "File : " : "Folder : ") + @share_path;
+            end
+        end        
+    end
+end

data/lib/nvx/sds/itembase.rb

@@ -0,0 +1,53 @@
+# = Overview
+# Base object for both files and folders.  This object stores both the base attributes and allows
+# setting if the item is hosted or not.
+module NVX
+    module SDS
+
+        $:.unshift File.dirname(__FILE__)
+
+        require 'transport'
+        require 'apicommand'
+        require 'apiparam'
+        require 'apiclasses/fsfolderattributes'
+        
+        # = Overview
+        # Base object for both files and folders.  This object stores both the base attributes and allows
+        # setting if the item is hosted or not.
+        class ItemBase
+
+            # Creates the object based on the file/folder attributes object.
+            def initialize(account_login, fs_item_attributes)
+                if !fs_item_attributes.nil?
+                    @account_login, @created_date = account_login, fs_item_attributes.created_date
+                    @name, @path = fs_item_attributes.name, fs_item_attributes.path
+                end
+            end            
+
+            # The date the file was created on the Nirvanix system.
+            def created_date
+                @created_date
+            end
+
+            # The name of the file/folder.
+            def name
+                @name
+            end
+
+            # The relative path to the file/folder.
+            def path                
+                @path
+            end
+            
+            # A method that hosts this file / folder making it available publicly.
+            def HostItem
+                Transport.execute_command_post(APICommand.CreateHostedItem, [APIParam.new("sharePath", @path)], @account_login)
+            end
+            
+            # Removes the file / folder from the list of hosted items (Does not destroy the file.)
+            def RemoveHostedItem
+                Transport.execute_command_post(APICommand.RemoveHostedItem, [APIParam.new("sharePath", @path)], @account_login)
+            end
+       end
+    end
+end

data/lib/nvx/sds/masteraccount.rb

@@ -0,0 +1,74 @@
+# = Overview
+#
+# The Master account lets you create children, modify children, Get and Set limits, adjust account notes and
+# impersonate child accounts.  Impersonation is available as a simple way to log into a child account if you
+# do not know the child accounts password but you are the master account.  This simplifies the administration
+# of child accounts.
+module NVX
+    module SDS
+        # = Overview
+        #
+        # The Master account lets you create children, modify children, Get and Set limits, adjust account notes and
+        # impersonate child accounts.  Impersonation is available as a simple way to log into a child account if you
+        # do not know the child accounts password but you are the master account.  This simplifies the administration
+        # of child accounts.
+        class MasterAccount
+            
+            # Sets the current session and account login objects.
+            def initialize(session, account_login)
+                @account_login = account_login
+                @session = session
+            end
+
+            # Creates a new child account.  The username and password are required fields.
+            # By default there are no limits on a child account.
+            def CreateChildAccount(username, password, first_name = nil, last_name = nil, 
+                middle_initial = nil, phone_number = nil, email_address = nil, email_format = nil,
+                address_line1 = nil, address_line2 = nil, city = nil, state = nil, country = nil, postal_code = nil)
+               
+                params = [APIParam.new("username", username), APIParam.new("password", password)]
+                params << APIParam.new("firstName", first_name) if !first_name.nil?
+                params << APIParam.new("lastName", last_name) if !last_name.nil?
+                params << APIParam.new("middleInitial", middle_initial) if !middle_initial.nil?
+                params << APIParam.new("phoneNumber", phone_number) if !phone_number.nil?
+                params << APIParam.new("emailAddress", email_address) if !email_address.nil?
+                params << APIParam.new("emailFormat", email_format) if !email_format.nil?
+                params << APIParam.new("addressLine1", address_line1) if !address_line1.nil?
+                params << APIParam.new("addressLine2", address_line2) if !address_line2.nil?
+                params << APIParam.new("city", city) if !city.nil?
+                params << APIParam.new("state", state) if !state.nil?
+                params << APIParam.new("countryID", country) if !country.nil?
+                params << APIParam.new("postalCode", postal_code) if !postal_code.nil?
+                
+                Transport.execute_command_post(APICommand.CreateChildAccount, params, @account_login)
+            end
+
+            # Removes a child account.  <i>**This will also remove ALL files/notes/account info the child previously 
+            # had in their account.</i>
+            def DeleteChildAccount(username)
+                Transport.execute_command_post(APICommand.DeleteChildAccount, [APIParam.new("username", username)], @account_login)
+            end
+            
+            # Gets the account notes in xml.
+            def GetAccountNotes(username)
+                doc = Transport.execute_command_post(APICommand.GetAccountNotes, [APIParam.new("username", username)], @account_login)
+                
+                return (text = doc.root.elements["//Response/GetAccountNotes"].get_text and text.value)
+            end
+            
+            # Set the account notes.  This method expects properly formated xml.  Be sure to escape any invalid characters.
+            def SetAccountNotes(username, xml_notes)
+                params = [APIParam.new("username", username),
+                            APIParam.new("xmlNotes", xml_notes)]
+                Transport.execute_command_post(APICommand.SetAccountNotes, params, @account_login)
+            end
+
+            # This lets the master account get a session for a child account that they have previously created without
+            # knowing the password for that child account.
+            def ImpersonateChildAccount(username)
+                @session = Session.new(@account_login.app_key, username, @account_login.app_name, nil, @account_login.session_token)
+                return @session
+            end
+        end        
+    end
+end

data/lib/nvx/sds/nvxfile.rb

@@ -0,0 +1,173 @@
+# = Overview
+# The File object is used for all file operations. The object is initially retrieved 
+# by calling Session.GetRootFolder and retrieving the .Files array.  This is loaded with
+# loadchildren.
+#
+# = Usage
+#   session = Session.new("APP-KEY", "USERNAME", "APP NAME", "PASSWORD")
+#   root_folder = session.GetRootFolder(1, 500, 0, true)
+#
+#   root_folder.files.each do |file|
+#       print file.name
+#   end
+module NVX
+    module SDS
+
+        $:.unshift File.dirname(__FILE__)
+        require 'itembase'
+        
+        # = Overview
+        # The File object is used for all file operations. The object is initially retrieved 
+        # by calling Session.GetRootFolder and retrieving the .Files array.  This is loaded with
+        # loadchildren.
+        #
+        # = Usage
+        #   session = Session.new("APP-KEY", "USERNAME", "APP NAME", "PASSWORD")
+        #   root_folder = session.GetRootFolder(1, 500, 0, true)
+        #
+        #   root_folder.files.each do |file|
+        #       print file.name
+        #   end
+        class NVXFile < ItemBase
+            
+            # initialize the file using the default file attributes from the listFolder
+            # method.
+            def initialize(account_login, fs_file_attributes)
+                super(account_login, fs_file_attributes)
+                @account_login = account_login
+                @fs_file_attributes = fs_file_attributes
+                @size_bytes = fs_file_attributes.size_bytes
+            end
+            
+            # The file size in bytes.
+            def size_bytes
+                @size_bytes
+            end
+            
+            # Pass the new filename to change the path.
+            def Rename(new_name)
+                params = [APIParam.new("filePath", @path), APIParam.new("newFileName", new_name)]
+                
+                Transport.execute_command_post(APICommand.RenameFile, params, @account_login)
+                
+                splitpath = @path.to_s.split("/")
+                splitpath.delete(splitpath.last)
+                splitpath << new_name
+                @path = splitpath.join("/")
+                @name = new_name                
+            end
+
+            # Deletes all metadata including those created on the initial upload processing.
+            def DeleteAllMetadata
+                Transport.execute_command_post(APICommand.DeleteAllMetadata, [APIParam.new("path", @path)], @account_login)
+            end
+
+            # Deletes all tags.
+            def DeleteAllTags
+                Transport.execute_command_post(APICommand.DeleteAllTags, [APIParam.new("path", @path)], @account_login)
+            end
+            
+            # Deletes one or more metadata entries based on the name of the metadata.
+            def DeleteMetadata(metadata_to_delete)
+                params = [APIParam.new("path", @path)]
+                metadata_to_delete.each do |metadata|
+                    params << APIParam.new("metadata", metadata)
+                end
+                
+                Transport.execute_command_post(APICommand.DeleteMetadata, params, @account_login)
+            end
+            
+            # Retrieve all of the metadata for the current path
+            def GetMetadata
+                params = [APIParam.new("path", @path)]
+                
+                #get the metadata for the current path.
+                doc = Transport.execute_command_post(APICommand.GetMetadata, params, @account_login)
+                
+                #if there is any metadata loop through
+                metadata = Array.new
+                if doc.root.elements["//Response/Metadata"]
+                    doc.root.elements.each("//Response/Metadata") do |metadataxml|
+                        #add to the array the type and value of each in the xml.
+                        metadata << MetadataInfo.new(metadataxml.elements["Type"][0], metadataxml.elements["Value"][0])
+                    end
+                end
+                
+                return metadata
+            end
+            
+            # Retrieve all of the metadata for the current path
+            def GetTags
+                params = [APIParam.new("path", @path)]
+                
+                #get the metadata for the current path.
+                doc = Transport.execute_command_post(APICommand.GetTags, params, @account_login)
+                
+                #empty the existing metadata array
+                tags = Array.new
+
+                if doc.root.elements["//Tag"]
+                    doc.root.elements.each("//Tag") do |tag|
+                        #add to the array the type and value of each in the xml.
+                        tags << tag.get_text.value
+                    end
+                end
+
+                return tags
+            end
+
+            # Sets one or more metadata items, pass the parameter as an array of Metadata objects.
+            def SetMetadata(metadata_info_items)
+                params = [APIParam.new("path", @path)]
+                
+                metadata_info_items.each do |item|
+                    params << APIParam.new("metadata", item.type + ":" + item.value)
+                end
+                
+                Transport.execute_command_post(APICommand.SetMetadata, params, @account_login)
+            end
+
+            # Sets one or more tags on a file.
+            def SetTags(tags)
+                params = [APIParam.new("path", @path)]
+                
+                tags.each do |tag|
+                    params << APIParam.new("tag", tag)
+                end
+                
+                Transport.execute_command_post(APICommand.SetTags, params, @account_login)
+            end
+
+            # Resizes an image to the specified height and width.  If a filename or destination folder is  specified a
+            # new file will be created.  If a callbackURL is defined when the resize process is complete
+            # the URL will be called.
+            def ImageResize(width, height, new_filename = nil, destination_folder = nil, callback_url = nil)
+                path = @path                
+                if !destination_folder.nil?
+                    new_path = destination_folder
+                end
+                if !new_filename.nil?
+                    new_path += new_filename
+                end
+                
+                params = [APIParam.new("srcFilePath", @path),
+                            APIParam.new("destFilePath", new_path),
+                            APIParam.new("width", width.to_s),
+                            APIParam.new("height", height.to_s)]
+                params << APIParam.new("callbackURL", callback_url) if !callback_url.nil?
+                
+                Transport.execute_command(APICommands.ImageResize, params, @account_login)
+            end
+            
+            # Retrieves a Url to the current file.
+            def GetDownloadUrl
+                Utilities.GetDownloadUrl(@account_login, @path, true)
+            end
+
+            # Downloads the current file to a local path.
+            def DownloadToLocalFile(local_path)
+                Transport.DownloadFile(@path, local_path, @account_login)
+            end
+        end
+    end
+end