rtunesu 0.2.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2008-06-27
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Trek Glowacki
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,77 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/multipart.rb
+lib/rtunesu.rb
+lib/rtunesu/connection.rb
+lib/rtunesu/document.rb
+lib/rtunesu/entities/course.rb
+lib/rtunesu/entities/division.rb
+lib/rtunesu/entities/group.rb
+lib/rtunesu/entities/permission.rb
+lib/rtunesu/entities/section.rb
+lib/rtunesu/entities/site.rb
+lib/rtunesu/entities/track.rb
+lib/rtunesu/entities/theme.rb
+lib/rtunesu/entity.rb
+lib/rtunesu/user.rb
+lib/rtunesu/version.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+spec/connection_spec.rb
+spec/document_spec.rb
+spec/documents/add_spec.rb
+spec/documents/delete_spec.rb
+spec/documents/merge_spec.rb
+spec/documents/show_tree_spec.rb
+spec/entities/course_spec.rb
+spec/entities/division_spec.rb
+spec/entities/group_spec.rb
+spec/entities/permission_spec.rb
+spec/entities/section_spec.rb
+spec/entities/site_spec.rb
+spec/entities/track_spec.rb
+spec/entity_spec.rb
+spec/fixtures/add_course.xml
+spec/fixtures/add_division.xml
+spec/fixtures/add_group.xml
+spec/fixtures/add_permission.xml
+spec/fixtures/add_section.xml
+spec/fixtures/add_track.xml
+spec/fixtures/delete_course.xml
+spec/fixtures/delete_division.xml
+spec/fixtures/delete_group.xml
+spec/fixtures/delete_permission.xml
+spec/fixtures/delete_section.xml
+spec/fixtures/delete_track.xml
+spec/fixtures/merge_course.xml
+spec/fixtures/merge_division.xml
+spec/fixtures/merge_group.xml
+spec/fixtures/merge_permission.xml
+spec/fixtures/merge_section.xml
+spec/fixtures/merge_site.xml
+spec/fixtures/merge_track.xml
+spec/fixtures/requests/add_coures_request.xml
+spec/fixtures/responses/generic_entity_response.xml
+spec/fixtures/responses/show_tree_course.xml
+spec/fixtures/show_tree.xml
+spec/fixtures/update_group.xml
+spec/spec.opts
+spec/spec_helper.rb
+spec/user_spec.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+tasks/website.rake
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/README.txt

@@ -0,0 +1,38 @@
+= RTunesU
+
+== DESCRIPTION:
+RTunesU is a ruby library for accessing Apple's iTunes U Webservices to integrate your education institutions iTunes U account into ruby applications
+
+== FEATURES/PROBLEMS:
+ - TODO: file uploading
+ 
+== SYNOPSIS:
+
+== REQUIREMENTS:
+
+== INSTALL:
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Trek Glowacki
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,75 @@
+require 'rtunesu/version'
+
+AUTHOR = 'Trek Glowacki'
+EMAIL = "trek.glowacki@gmail.com"
+DESCRIPTION = "A library for using Apple's iTunes U Webservices API"
+GEM_NAME = 'rtunesu'
+RUBYFORGE_PROJECT = 'rtunesu'
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+EXTRA_DEPENDENCIES = [
+  ['ruby-hmac', '>= 0.3.1'],
+  ['hpricot', '>= 0.6'],
+  ['builder', '>= 2.0']
+]
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "unknown"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil
+# UNCOMMENT IF REQUIRED:
+# REV = YAML.load(`svn info`)['Revision']
+VERS = RTunesU::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'rtunesu documentation',
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' }
+    @extra_deps
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = EXTRA_DEPENDENCIES
+
+    #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'
+# $hoe.spec.post_install_message = File.open(File.dirname(__FILE__) + "/../PostInstall.txt").read rescue ""

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/lib/multipart.rb

@@ -0,0 +1,53 @@
+require 'net/https'
+require "rubygems"
+require "mime/types"
+require "base64"
+require 'cgi'
+
+# Add multipart/form-data support to net/http
+# From http://pivots.pivotallabs.com/users/damon/blog/articles/227-standup-04-27-07-testing-file-uploads
+#
+# == Usage
+# File.open(File.expand_path('script/test.png'), 'r') do |file|
+#   http = Net::HTTP.new('localhost', 3000)
+#   begin
+#     http.start do |http|
+#       request = Net::HTTP::Post.new('/your/url/here')
+#       request.basic_auth 'lonely_user', 'really_long_password'
+#       request.multipart_params = {:file => file, :title => 'test.png'}
+#       response = http.request(request)
+#       response.value
+#       puts response.body
+#     end
+#   rescue Net::HTTPServerException => e
+#     p e
+#   end
+# end
+class Net::HTTP::Post
+  def multipart_params=(param_hash={})
+    boundary_token = [Array.new(8) {rand(256)}].join
+    self.content_type = "multipart/form-data; boundary=#{boundary_token}"
+    boundary_marker = "--#{boundary_token}\r\n"
+    self.body = param_hash.map { |param_name, param_value|
+      boundary_marker + case param_value
+      when File: file_to_multipart(param_name, param_value)
+      when String: text_to_multipart(param_name, param_value)
+      else ''
+      end
+    }.join('') + "--#{boundary_token}--\r\n"
+  end
+
+protected
+  def file_to_multipart(key,file)
+    filename = File.basename(file.path)
+    mime_types = MIME::Types.of(filename)
+    mime_type = mime_types.empty? ? "application/octet-stream" : mime_types.first.content_type
+    part = %Q{Content-Disposition: form-data; name="#{key}"; filename="#{filename}"\r\n}
+    part += "Content-Transfer-Encoding: binary\r\n"
+    part += "Content-Type: #{mime_type}\r\n\r\n#{file.read}\r\n"
+  end
+
+  def text_to_multipart(key,value)
+    "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n#{value}\r\n"
+  end
+end

data/lib/rtunesu/connection.rb

@@ -0,0 +1,111 @@
+require 'rubygems'
+require 'cgi'
+require 'hmac'
+require 'hmac-sha2'
+require 'digest'
+require 'net/https'
+require 'uri'
+require 'timeout'
+
+module RTunesU
+  # Connection is a class for opening and using a connection to the iTunes U Webservices system.  To open a connection to iTunes U, you first need to create a RTunesU::User object using the administrator data you received from Apple when they created your iTunes U site.
+  # === Creating a Connection
+  # include RTunesU
+  # # create a new admin user from our Institution's login information
+  # user = User.new(0, 'admin', 'Admin', 'admin@example.edu')
+  # # set the User credentials to the credentials Apple provider when we signed up
+  # user.credentials = ['Administrator@urn:mace:example.edu']
+  # # Create a new Connection object.
+  # connection = Connection.new(:user => user, :site => 'example.edu', :shared_secret => 'STRINGOFTHIRTYLETTERSORNUMBERS')
+  # 
+  # === Using a Connection
+  # A Connection object is needed for operations that communicate with Apple's iTunes U Webservices.  For example, calls to .save, .create, .update, and .delete on Entity objects take a Connection object as their only argument.
+  # To communicate with the iTunes U Service, a Connection object will generate proper authentication data, hash your request, and (if neccessary) send XML data to iTunes U.
+  # For more inforamtion about this processs see: http://deimos.apple.com/rsrc/doc/iTunesUAdministratorsGuide/IntegratingAuthenticationandAuthorizationServices/chapter_3_section_3.html
+  # === Scaling tips
+  # Because the you will likely only need a single unchanging Connection object for your application you may wish to initialize a single Connection object for the admin credentials at application start time and assign it to a constant. This is especially beneficial for long running applications like web applications.
+  class Connection
+    TIMEOUT = 240
+    
+    attr_accessor :user, :options
+    
+    def initialize(options = {})
+      self.user, self.options = options[:user], options
+    end
+    
+    # iTunes U requires all request to include an authorization token that includes a User's credentials, indetifiying information, and the time of the request.  This data is hashed against your institution's shared secret (provider by Apple with your iTunes U account information). Because tokens are valid only for 90 seconds they are generated for each request attempt.
+    def generate_authorization_token
+    	# create the token that contains the necessary elements to authorize the user	
+    	# using a nested array because the alphabetical order must be maintained
+    	token = [['credentials', self.user.to_credential_string,], ['identity', self.user.to_identity_string], ['time', Time.now.to_i.to_s]]
+    	encoded_parms = token.collect {|pair| pair[1] = CGI.escape(pair[1]); pair.join('=')}.join('&')
+
+      digest = Digest::SHA2.new
+      digest.update(encoded_parms)
+
+      hmac = HMAC::SHA256.new(self.options[:shared_secret])
+      hmac.update(encoded_parms)
+
+      # add the hashed digital signature to the end of the query parameters
+      encoded_parms += "&signature=#{hmac.hexdigest}"
+    end
+        
+    def upload_url_for_location(location)
+      url_string = "#{API_URL}/GetUploadURL/#{self.options[:site]}.#{location.Handle}?#{self.generate_authorization_token}"
+      puts url_string
+      url = URI.parse(url_string)
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      response = http.start {|http| 
+        http.request(Net::HTTP::Get.new(url.path + '?' + url.query))
+      }
+      response.body
+    end
+    
+    # The URL that receives all iTunes U webservices requests.  This is different for each institution and inclues your site name provided by Apple.
+    def webservices_url
+      "#{API_URL}/ProcessWebServicesDocument/#{options[:site]}?#{self.generate_authorization_token}"
+    end
+    
+    # 
+    def browse_url
+      "#{BROWSE_URL}/#{options[:site]}?#{self.generate_authorization_token}"
+    end
+    
+    def show_tree
+      url = URI.parse("#{SHOW_TREE_URL}/#{options[:site]}?#{self.generate_authorization_token}")
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        http.start {
+          request = Net::HTTP::Post.new(url.to_s)
+          response = http.request(request)
+          response.body
+        }
+    end
+    
+    #  Sends a string of XML data to iTunes U's webservices url for processing.  Returns the iTunes U response XML. Used by Entity objects to send generated XML to iTunes U. 
+    def process(xml)
+      timeout(TIMEOUT) do
+        url = URI.parse(webservices_url)
+          http = Net::HTTP.new(url.host, url.port)
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          http.start {
+            request = Net::HTTP::Post.new(url.to_s)
+            request.body = xml
+            response = http.request(request)
+            response.body
+          }
+      end
+    end
+    
+    # Uploads a file from the local system to iTunes U.
+    def upload_file(file, itunes_location)
+      IO::popen('-') do |c|
+        exec "curl -q -F 'file=@#{file.path}' '#{upload_url_for_location(itunes_location)}'"
+      end
+    end
+  end
+end

data/lib/rtunesu/document.rb

@@ -0,0 +1,84 @@
+require 'builder'
+
+module RTunesU
+  # Document is a class that generates the neccessary XML to interact with iTunes U.  Documents are generated and sent when calling .save, .create, .update, and .delete on an specific Entity object.  Classes in the Document:: namespace aren't intended for direct use.
+  # For example:
+  # c = Course.find(12345, itunes_connection_object)
+  # c.Name # "Exemple Course"
+  # c.Name = 'Example Course'
+  # c.save # genertes and sends a Document::Merge object with the Course data.
+  module Document
+    class Base
+      INDENT = 2
+      attr_accessor :builder, :source, :options, :xml
+      
+      def initialize(source, options = {})
+        self.source, self.options = source, options
+        builder = Builder::XmlMarkup.new(:indent => INDENT)
+        builder.instruct!
+        builder.tag!('ITunesUDocument') {
+          builder.tag!('Version', RTunesU::API_VERSION)
+          self.xml = tag_action(builder)
+        }
+        self
+      end
+
+      # Implemented in each of the subclasses of Document::Base. Adds the particular action you would like to take (AddFoo, MergeFoo, DeleteFoo) to the Source class.
+      # For example, if the source Entity is of the type Track and you are creating a Document::Add the ITunesUDocument element will have a child element of <AddTrack>...</AddTrack>
+      # tag_action is called from inside Document::Base.new and is based the initializer's builder object so that proper nesting is maintained.
+      private
+        def tag_action(xml_builder)
+          return
+        end 
+    end
+      
+    # Creates an XML document that comforms to iTunes U's specification for adding an entity.  This class is used internally by Entity classes when saving.
+    class Add < Base
+      private
+        def tag_action(xml_builder)
+          raise MissingParent if source.parent_handle.nil?
+          xml_builder.tag!("Add#{source.class_name}") {
+            xml_builder.tag!('ParentHandle', source.parent_handle)
+            # The existance of ParentPath is required for iTunesU documents, but can be blank
+            xml_builder.tag!('ParentPath', '')
+            source.to_xml(xml_builder)
+          }
+        end
+    end
+        
+    # Creates an XML document that comforms to iTunes U's specification for updating an entity.  This class is used internally by Entity classes when saving.
+    class Merge < Base
+      private
+        def tag_action(xml_builder)
+          xml_builder.tag!("Merge#{source.class_name}") {
+            xml_builder.tag!("#{source.class_name}Handle", source.handle)
+            source.to_xml(xml_builder)
+          }
+      end
+    end
+  
+    # Creates an XML document that comforms to iTunes U's specification for deleting an entity.  This class is used internally by Entity classes when saving.
+    class Delete < Base
+      private
+        def tag_action(xml_builder)
+          xml_builder.tag!("Delete#{source.class_name}") {
+            xml_builder.tag!("#{source.class_name}Handle", source.handle)
+            xml_builder.tag!("#{source.class_name}Path", '') unless source.class_name == 'Track'
+          }
+        end
+    end
+    
+    # Shows the hierarchy tree for a portion of your iTunes U site.  If the source object has no handle, the tree for your entire site is shown.
+    # ShowTree.new can take an option options hash. The possible values for this hash are
+    # :key_group.  They iTunes U 'KeyGroup' that defines the amount of data returned from the ShowTree action. Possible values are 'minimal','most','maximal'.  
+    class ShowTree < Base
+      private
+        def tag_action(xml_builder)
+          xml_builder.tag!('ShowTree') {
+            xml_builder.tag!('Handle', self.source.handle) if self.source.handle
+            xml_builder.tag!('KeyGroup', options[:key_group] || 'most')
+          }
+        end
+    end
+  end
+end

data/lib/rtunesu/entities/course.rb

@@ -0,0 +1,8 @@
+module RTunesU
+  # A Course in iTunes U.
+  # == Attributes
+  # == Nested Entities
+
+  class Course < Entity
+  end
+end

data/lib/rtunesu/entities/division.rb

@@ -0,0 +1,16 @@
+module RTunesU
+  # A Division in iTunes U is a seperate nested area of your iTunes U Site.  It is different than a Section which is expressed in iTunes a a seperate area on a single page.
+  # == Attributes
+  # Handle
+  # Name
+  # ShortName
+  # AggregateFileSize (read only)
+  # Identifier
+  # 
+  #
+  # == Nested Entities
+  # Permission
+  # Section
+  class Division < Entity
+  end
+end

data/lib/rtunesu/entities/group.rb

@@ -0,0 +1,8 @@
+module RTunesU
+  # A Group in iTunes U. A Group is expressed as a tab in the iTunes interface.
+  # == Attributes
+  # == Nested Entities
+  # Track
+  class Group < Entity
+  end
+end

data/lib/rtunesu/entities/permission.rb

@@ -0,0 +1,7 @@
+module RTunesU
+  # A Permission in iTunes U.
+  # == Attributes
+  # == Nested Entities
+  class Permission < Entity
+  end
+end

data/lib/rtunesu/entities/section.rb

@@ -0,0 +1,15 @@
+module RTunesU
+  # A Section in iTunes U.  A Section is expressed in the iTunes interface as a visually seperate area on a single page.  This is different than a Division which is a seperate nested area of iTunes U.
+  # == Attributes
+  # Handle
+  # Name
+  # AllowSubscription
+  # AggregateFileSize (read only)
+  # 
+  # == Nested Entities
+  # Permission
+  # Course
+  # Division
+  class Section < Entity
+  end
+end

data/lib/rtunesu/entities/site.rb

@@ -0,0 +1,7 @@
+module RTunesU
+  # A Site in iTunes U.
+  # == Attributes
+  # == Nested Entities
+  class Site
+  end
+end

data/lib/rtunesu/entities/theme.rb

@@ -0,0 +1,4 @@
+module RTunesU
+  class Theme < Entity
+  end
+end

data/lib/rtunesu/entities/track.rb

@@ -0,0 +1,13 @@
+module RTunesU
+  # A Track in iTunes U.
+  # == Attributes
+  # == Nested Entities
+  class Track < Entity
+    # Tracks can only be found from within their Course. There is currently no way to find a Track separete from its Course.  
+    def self.find(handle, course_handle, connection)
+      entity = self.new(:handle => handle)
+      entity.source_xml = Course.find(course_handle, connection).source_xml.at("Handle[text()=#{entity.handle}]..")
+      entity
+    end
+  end
+end