rtunesu 0.2.4 → 0.3.5

data/lib/rtunesu/entity.rb

@@ -1,56 +1,144 @@
-require 'hpricot'
-
 module RTunesU
-  # A Base class reprenseting the various entities seen in iTunes U.  Subclassed into the actual entity classes (Course, Division, Track, etc).  Entity is mostly an object oriented interface to the underlying XML data returned from iTunes U.  Most of attributes of an Entity are read by searching the souce XML returned from iTunes U by the Entity class's implemention of method_missing. 
-  # Attribute of an Entity are written through method missing as well.  Methods that end in '=' will write data that will be saved to iTunes U.
+  # http://deimos.apple.com/rsrc/xsd/iTunesURequest-1.1.3.xsd
+  # A Base class reprenseting the various entities seen in iTunes U.  Subclassed into the actual entity 
+  # classes (Course, Division, Track, etc).  Entity is mostly an object oriented interface to the 
+  # underlying XML data returned from iTunes U.  Most attributes of an Entity are read by searching
+  # the souce XML returned from iTunes U
   # == Reading and Writing Attributes
   # c = Course.find(12345, rtunes_connection_object) # finds the Course in iTunes U and stores its XML data
-  # c.Handle # finds the <Handle> element in the XML data and returns its value (in this case 12345)
-  # c.Name   # finds the <Name> element in the XML data and returns its value (e.g. 'My Example Course')
-  # c.Name = 'Podcasting: a Revolution' # writes a hash of unsaved data that will be sent to iTunes U.
+  # c.handle # finds the <Handle> element in the XML data and returns its value (in this case 12345)
+  # c.name   # finds the <Name> element in the XML data and returns its value (e.g. 'My Example Course')
+  # c.name = 'Podcasting: a Revolution' # writes a hash of unsaved data that will be sent to iTunes U.
   #
   # == Accessing related entities 
-  # Related Entity objects are accessed with the pluralized form of their class name.  To access a Course's related Group entities, you would use c.Groups. This will return an array of Group objects (or an empty Array object if there are no associated Groups)
-  # You can set the array of associated entities by using the '=' form of the accessor and add anothe element to the end of an array of related entities with '<<'
+  # Related Entity objects are accessed with the pluralized form of their class name.  
+  # To access a Course's related Group entities, you would use c.groups. This will return an array of 
+  # Group objects (or an empty Array object if there are no associated Groups)
+  # You can set the array of associated entities by using the '=' form of the accessor and add another 
+  # element to the end of an array of related entities with '<<'
   # Examples:
   # c = Course.find(12345, rtunes_connection_object) # finds the Course in iTunes U and stores its XML data
-  # c.Groups # returns an array of Group entities or an empty array of there are no Group entities
-  # c.Groups = [Group.new(:Name => 'Lectures')] # assigns the Groups related entity array to an existign array (overwriting any local data about Groups)
-  # c.Groups << Group.new(:Name => 'Videos') # Adds the new Group object to the end of hte Groups array
-  # c.Groups.collect {|g| g.Name} # ['Lectures', 'Videos']
-  #
-  # == Notes on arbitrary XML
-  # Because Entity is, at heart, an object oriented wrapper for iTunes U XML data it is possible to add arbitrary (and possibly meaningless or invalidating) data that will be sent to iTunes U.  You should have a solid understanding of how Entites relate in iTunes U to avoind sending bad data.
-  # Examples:
-  # c = Course.find(12345, rtunes_connection_object)
-  # c.Junk = 'some junk xml' 
-  # c.save
-  # # c.save will generate XML that inclucdes 
-  # # <Course>
-  # #   <Junk>some junk xml</Junk>
-  # #   ... some other XML data ...
-  # # </Course>
-  # # this XML may raise errors in iTunes U because it doesn't match valid iTunes U documents
+  # c.groups # returns an array of Group entities or an empty array of there are no Group entities
+  # c.groups = [Group.new(:name => 'Lectures')] # assigns the Groups related entity array to an existing 
+  # array (overwriting any local data about Groups)
+  # c.groups << Group.new(:name => 'Videos') # Adds the new Group object to the end of hte Groups array
+  # c.groups.collect {|g| g.name} # ['Lectures', 'Videos']
   class Entity
-    attr_accessor :connection, :attributes, :handle, :parent, :parent_handle, :saved, :source_xml
     
-    # Creates a new Entity object with attributes based on the hash argument  Some of these attributes are assgined to instance variables of the obect (if there is an attr_accessor for it), the rest will be written to a hash of edits that will be saved to iTunes U using method_missing
+    attr_accessor :connection, :parent, :parent_handle, :saved, :source_xml
+    attr_reader :handle
+    
+    def self.attributes
+      @attributes ||= Set.new
+    end
+    
+    def self.get_base_connection # :nodoc:
+      @base_connection
+    end
+    
+    def self.base_connection 
+      Entity.get_base_connection
+    end
+    
+    def self.set_base_connection(connection)
+      @base_connection = connection
+    end
+    
+    def self.validates!(name, values)
+      return
+    end
+    
+    def self.composed_of(*names)
+      options = names.last.is_a?(Hash) ? names.pop : {}
+      self.attributes.merge(names)
+      names.each do |name|
+        storage_name = options[:as] || name.to_s.camelize
+        
+        define_method(name) do
+          value_from_edits_or_store(storage_name)
+        end
+        
+        unless options[:readonly]
+          define_method(:"#{name}=") do |arg|
+            edits[storage_name] = arg
+          end
+        end
+      end
+    end
+    
+    def self.has_a(*names)
+      options = names.last.is_a?(Hash) ? names.pop : {}
+      self.attributes.merge(names)
+      names.each do |name|
+        define_method(name) do
+          entity_name = options[:as] || name.to_s.camelize
+          instance_variable_get("@#{name}") || instance_variable_set("@#{name}", RTunesU::HasAEntityCollectionProxy.new(self.source_xml./(entity_name), self, entity_name))
+        end
+        
+        unless options[:readonly]
+          define_method(:"#{name}=") do |arg|
+            edits[options[:as] || name.to_s.camelize] = arg
+          end
+        end
+      end
+    end
+    
+    def self.has_n(*names)
+      options = names.last.is_a?(Hash) ? names.pop : {}
+      self.attributes.merge(names)
+      names.each do |name|
+        define_method(name) do
+          entity_name = options[:as] || name.to_s.chop.camelize
+          instance_variable_get("@#{name}") || instance_variable_set("@#{name}", RTunesU::HasNEntityCollectionProxy.new(self.source_xml./(entity_name), self, entity_name))
+        end
+        
+        unless options[:readonly]
+          define_method(:"#{name}=") do |arg|
+            edits[options[:as] || name.to.camelize] = arg
+          end
+        end
+      end
+    end
+    
+    # Creates a new Entity object with attributes based on the hash argument  Some of these attributes 
+    # are assgined to instance variables of the obect (if there is an attr_accessor for it), the rest 
+    # will be written to a hash of edits that will be saved to iTunes U using method_missing
     def initialize(attrs = {})
-      self.attributes = {}
       attrs.each {|attribute, value| self.send("#{attribute}=", value)}
+      self.source_xml = Hpricot.XML('')
     end
-        
-    # Finds a specific entity in iTunes U. To find an entity you will need to know both its type (Course, Group, etc) and handle.  Handles uniquely identify entities in iTunes U and the entity type is used to search the returned XML for the specific entity you are looking for.  For example,
+       
+    def handle
+      @handle ||= handle_from_source
+    end
+    
+    def handle_from_source
+      return nil unless self.source_xml
+      if (handle_elem = self.source_xml % 'Handle')
+        handle_elem.innerHTML
+      else
+        nil
+      end
+    end
+    
+    # Finds a specific entity in iTunes U. To find an entity you will need to know both its type 
+    # (Course, Group, etc) and handle.  Handles uniquely identify entities in iTunes U and the entity 
+    # type is used to search the returned XML for the specific entity you are looking for.  For example,
     # Course.find(123456, rtunes_connection_object)
-    def self.find(handle, connection)
-      entity = self.new(:handle => handle)
-      entity.load_from_xml(connection.process(Document::ShowTree.new(entity).xml))
+    def self.find(handle, connection = nil)
+      connection ||= self.base_connection
+      
+      entity = self.new
+      entity.instance_variable_set('@handle', handle)
+      entity.load_from_xml(connection.upload_file(RTunesU::SHOW_TREE_FILE, handle))
       entity
+      
+    rescue LocationNotFound
+      raise EntityNotFound, "Could not find #{entity.class_name} with handle of #{handle}."
     end
-        
-    def load_from_xml(xml)
-      self.source_xml = Hpricot.XML(xml).at("//ITunesUResponse//#{self.class_name}//Handle[text()=#{self.handle}]..")
-      raise EntityNotFound if self.source_xml.nil?
+    
+    def load_from_xml(xml_or_entity)
+      self.source_xml = Hpricot.XML(xml_or_entity).at("//ITunesUResponse//#{self.class_name}//Handle[text()=#{self.handle}]..")
     end
     
     # Edits stores the changes made to an entity
@@ -58,6 +146,10 @@ module RTunesU
       @edits ||= {}
     end
     
+    def edited?
+      self.edits.any?
+    end
+    
     # Clear the edits and restores the loaded object to its original form
     def reload
       self.edits.clear
@@ -70,32 +162,13 @@ module RTunesU
       nil
     end
     
-    def method_missing(method_name, args = nil)
-      # introspect the kind of method call (read one attribute, 
-      # read an array of related items, write one attribute, write an array of related items)
-      case method_name.to_s.match(/(s)*(=)*$/).captures
-       when [nil, "="] : self.edits[method_name.to_s[0..-2]] = args
-       when ["s", "="] : self.edits[method_name.to_s[0..-2]] = args
-       when [nil, nil] : value_from_edits_or_store(method_name.to_s)
-       when ["s", nil] : value_from_edits_or_store(method_name.to_s, true)
-      end
+    def value_from_edits_or_store(name)
+      self.edits[name] ||  (self.source_xml % name).innerHTML
     rescue NoMethodError
-      raise NoMethodError, "undefined method '#{method_name}' for #{self.class}"
+      nil
     end
     
-    def value_from_edits_or_store(name, multi = false)
-      if multi
-        begin
-          self.edits[name] || (self.source_xml / name.to_s.chop).collect {|el| Object.module_eval(el.name).new(:source_xml => el)}
-        rescue NoMethodError
-          self.edits[name] = []
-        end
-      else
-        self.edits[name] ||  (self.source_xml % name).innerHTML
-      end
-    end
-
-            
+    
     # Returns the name of the object's class ignoring namespacing. 
     # === Use:
     # course = RTunesU::Course.new
@@ -105,53 +178,91 @@ module RTunesU
       self.class.to_s.split('::').last
     end
     
-    # Returns the handle of the entitiy's parent.  This can either be set directly as a string or interger or will access the parent entity.  Sometimes you know the parent_handle without the parent object (for example, stored locally from an earlier request). This allows you to add a new Entity to iTunes U without first firing a reques for a prent entity (For example, if your institution places all inside the same Section, you want to add a new Section to your Site, or a new Group to a course tied to your institution's LMS).
+    def base_connection
+      self.class.base_connection
+    end
+    
+    # Returns the handle of the entitiy's parent.  This can either be set directly as a string or interger or 
+    # will access the parent entity.  Sometimes you know the parent_handle without the parent object 
+    # (for example, stored locally from an earlier request). This allows you to add a new Entity to iTunes U 
+    # without first firing a request for a parent entity (For example, if your institution places all courses inside the 
+    # same Section, you want to add a new Section to your Site, or a new Group to a course tied to your 
+    # institution's LMS).
     def parent_handle
       self.parent ? self.parent.handle : @parent_handle
     end
     
+    # Converts the entities changed attributes and subentities to XML.  Called by Document when building
+    # documents to transfer to iTunes U.
     def to_xml(xml_builder = Builder::XmlMarkup.new)
       xml_builder.tag!(self.class_name) {
-        self.edits.each {|attribute,edit| edit.is_a?(Array) ? edit.each {|item| item.to_xml(xml_builder)} : xml_builder.tag!(attribute, edit) }
-        # self.edits.each {|attribute| xml_builder.tag!(attribute.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }, self.attributes[attribute.to_s]) unless self.attributes[attribute.to_s].nil? || self.attributes[attribute.to_s].empty? }
+        self.edits.each do |attribute,edit|
+          edit.is_a?(SubentityAssociationProxy) ? edit.to_xml(xml_builder) : xml_builder.tag!(attribute, edit)
+        end
       }
     end
     
     # called when .save is called on an object that is already stored in iTunes U
-    def update(connection)
+    def update(connection = nil)
+      connection ||= self.base_connection
+      
       connection.process(Document::Merge.new(self).xml)
+      edits.clear
       self
     end
     
     # called when .save is called on an object that has no Handle (i.e. does not already exist in iTunes U)
-    def create(connection)
+    def create(connection = nil)
+      connection ||= self.base_connection
+      
       response = Hpricot.XML(connection.process(Document::Add.new(self).xml))
-      raise Exception, response.at('error').innerHTML if response.at('error')
-      self.handle = response.at('AddedObjectHandle').innerHTML
+      raise CannotSave, response.at('error').innerHTML if response.at('error')
+      @handle = response.at('AddedObjectHandle').innerHTML
+      edits.clear
       self
     end
     
-    # Saves the entity to iTunes U.  Save takes single argument (an iTunes U connection object).  If the entity is unsaved this will create the entity and populate its handle attribte.  If the entity has already been saved it will send the updated data (if any) to iTunes U.
-    def save(connection)
+    # Saves the entity to iTunes U.  Save takes single argument (an iTunes U connection object).  
+    # If the entity is unsaved this will create the entity and populate its handle attribte.  
+    # If the entity has already been saved it will send the updated data (if any) to iTunes U.
+    def save(connection = nil)
+      connection ||= self.base_connection
       saved? ? update(connection) : create(connection)
     end
     
+    # Has the entity be previously saved in iTunes U
     def saved?
       self.handle ? true : false
     end
     
     # Deletes the entity from iTunes U.  This cannot be undone.
-    def delete(connection)
+    def delete(connection = nil)
+      connection ||= self.base_connection
+      
       response = Hpricot.XML(connection.process(Document::Delete.new(self).xml))
       raise Exception, response.at('error').innerHTML if response.at('error')
-      self.handle = nil
+      @handle = nil
       self
     end
+    
+    def inspect
+      inspected = "#<#{self.class.to_s} handle:#{@handle.inspect} "
+      self.class.attributes.each do |attribute|
+        inspected << "#{attribute}:#{self.send(attribute).inspect} "
+      end
+      inspected   << '>'
+    end
+  end
+  
+  class CannotSave < StandardError
+  end
+  
+  class ConnectionRequired < StandardError
   end
   
-  class EntityNotFound < Exception
+  class EntityNotFound < StandardError
   end
   
-  class MissingParent < Exception
+  class MissingParent < StandardError
   end
 end

data/lib/rtunesu/log.rb

@@ -0,0 +1,69 @@
+require 'time'
+
+module RTunesU
+  class Log
+    def self.parse(log_text)
+      self.new(log_text).parsed
+    end
+    
+    def initialize(raw)
+      @raw = raw
+      @parsed = parse(@raw)
+    end
+    
+    attr_reader :raw, :parsed
+    
+    module Errors
+      class LogEntryParseError < RuntimeError; end
+      class LogParseError < RuntimeError; end
+    end
+  
+    private
+    def parse_line(line)
+      log, path = line.split('"')
+      l = log.split << path
+      entry = { :version => l[0],
+                :site => l[1],
+                :time => Time.parse("#{l[2]} #{l[3]}"),
+                :action => l[4],
+                :uuid => l[5],
+                :user => l[6],
+                :address => l[7],
+                :agent => l[8],
+                :path => l[9]
+              }
+      unless validate(entry)
+        raise Errors::LogEntryParseError, "Failed to validate as an ItunesU log entry:\n#{line}"
+      end    
+      entry 
+    end
+    
+    def parse(log)
+      if not log.kind_of? IO and File.exists? log
+        log = File.open(log) 
+      elsif not log.respond_to? 'each_line'
+        log = StringIO.new(log.to_s) 
+      end
+      begin
+        log.map {|line| parse_line(line)}
+      rescue Errors::LogEntryParseError => error
+        raise Errors::LogParseError, "Failed to parse <#{log.class}>:\n#{error}"
+      end
+    end
+    
+    def validate(log_entry)
+      # if log_entry[:address].nil? or log_entry[:address].split(".").size != 4
+      #   puts log_entry[:address].inspect
+      #   return false
+      # elsif log_entry[:agent].nil? or log_entry[:agent].split("/").size != 3
+      #   puts log_entry[:agent].inspect
+      #   return false
+      # elsif log_entry[:user].nil? or log_entry[:user].split("@").size != 2
+      #   puts log_entry[:user].inspect
+      #   return false
+      # end
+      
+      return true
+    end
+  end
+end

data/lib/rtunesu/subentities.rb

@@ -0,0 +1,60 @@
+module RTunesU
+  class SubentityAssociationProxy
+    delegate :inspect, :to => :target
+    def initialize(source_xml, owner, name)
+      @source_xml = source_xml
+      @owner = owner
+      @owner.edits[name] = self
+      @edits = []
+      self.from_xml(name)
+    end
+    
+  end
+  
+  class HasAEntityCollectionProxy < SubentityAssociationProxy
+    delegate :class, :to => :target
+    attr_reader :target 
+    def from_xml(name)
+      if @source_xml
+       @target = "RTunesU::#{name}".constantize.new(:source_xml => @source_xml.first, :parent_handle => @owner.handle)
+      else
+       @target = "RTunesU::#{name}".constantize.new(:parent_handle => @owner.handle)
+      end
+    end
+    
+    def to_xml(builder)
+      @target.to_xml(builder) if @target.edits.any?
+    end
+    
+    def method_missing(method_name, *args)
+      @target.send(method_name, args)
+    end
+  end
+  
+  class HasNEntityCollectionProxy < SubentityAssociationProxy
+    delegate :[], :at, :first, :last, :size, :to => :target
+    attr_reader :target, :edits
+
+    def from_xml(name)
+      if @source_xml
+       @target = @source_xml.collect {|el| Object.module_eval(el.name).new(:source_xml => el, :parent_handle => @owner.handle)}
+      else
+       @target = []
+      end
+    end
+    
+    def to_xml(builder)
+      self.edits.each {|entity| entity.to_xml(builder)}
+    end
+    
+    def <<(entity)
+      @target << entity
+      @edits  << entity
+    end
+    
+    def []=(index,entity)
+      @target[index] = entity
+      @entity[index] = entity
+    end
+  end
+end

data/lib/rtunesu/user.rb

@@ -1,5 +1,7 @@
 module RTunesU
-  # Represents a User for iTunes U authentication.  Requests to iTunes U require User information in a specific format. This class exists to access data in that specific format.  Best combined with a User object from your own authentication or LMS system.
+  # Represents a User for iTunes U authentication.  Requests to iTunes U require User 
+  # information in a specific format. This class exists to access data in that specific format.
+  # Best combined with a User object from your own authentication or LMS system.
   # Webservices requests to iTunes U require your institutions administrator credentials
   # === User
   # u = RTunesU::User.new('191912121', 'jsmith', 'John Smith', 'jsmith@exmaple.edu')

data/lib/rtunesu/version.rb

@@ -1,8 +1,8 @@
 module RTunesU
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 2
-    TINY  = 4
+    MINOR = 3
+    TINY  = 5
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/rtunesu.rb

@@ -1,7 +1,8 @@
 $:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+$:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
-require 'multipart'
+require 'hpricot'
+require 'activesupport'
 
 require 'rtunesu/version'
 require 'rtunesu/connection'
@@ -10,16 +11,20 @@ require 'rtunesu/document'
 require 'rtunesu/entity'
 require 'rtunesu/entities/course'
 require 'rtunesu/entities/division'
+require 'rtunesu/entities/external_feed'
 require 'rtunesu/entities/group'
 require 'rtunesu/entities/permission'
 require 'rtunesu/entities/section'
 require 'rtunesu/entities/site'
 require 'rtunesu/entities/track'
 require 'rtunesu/entities/theme'
+require 'rtunesu/log'
+require 'rtunesu/subentities'
 
 module  RTunesU
-  API_URL = 'https://deimos.apple.com/WebObjects/Core.woa/API'
-  API_VERSION = '1.1.1'
-  BROWSE_URL = 'https://deimos.apple.com/WebObjects/Core.woa/Browse'
-  SHOW_TREE_URL = 'https://deimos.apple.com/WebObjects/Core.woa/API/ShowTree'
+  API_URL = 'https://deimos.apple.com/WebObjects/Core.woa/API'.freeze
+  API_VERSION = '1.1.3'.freeze
+  BROWSE_URL = 'https://deimos.apple.com/WebObjects/Core.woa/Browse'.freeze
+  SHOW_TREE_URL = 'https://deimos.apple.com/WebObjects/Core.woa/API/ShowTree'.freeze
+  SHOW_TREE_FILE = File.new(File.join(File.dirname(__FILE__), 'show_tree.xml'))
 end

data/lib/show_tree.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ITunesUDocument>
+  <Version>1.1.3</Version>
+  <ShowTree>
+    <KeyGroup>maximal</KeyGroup>
+  </ShowTree>
+</ITunesUDocument>

data/spec/connection_spec.rb

@@ -1,35 +1,16 @@
 require File.dirname(__FILE__) + '/spec_helper.rb'
 include RTunesU
 
-describe Connection do
-  describe 'token generation' do
-    before do 
-      Time.should_receive(:now).and_return(@current_time)
-      @current_time.should_receive(:to_i).and_return(1214619134)
-      
-      user = mock(RTunesU::User, :id => 0,
-                                 :username => 'admin',
-                                 :name => 'Admin',
-                                 :email => 'admin@example.edu',
-                                 :credentials => ['Administrator@urn:mace:itunesu.com:sites:example.edu'],
-                                 :to_credential_string => 'Administrator@urn:mace:itunesu.com:sites:example.edu',
-                                 :to_identity_string => '"Admin" <admin@example.edu> (admin) [0]')
-                                 
-      @connection = Connection.new(:user => user, :shared_secret => 'STRINGOFTHIRTYTWOLETTERSORDIGITS')
-    end
-    
-    it 'generates a token' do
-       @connection.generate_authorization_token.should eql("credentials=Administrator%40urn%3Amace%3Aitunesu.com%3Asites%3Aexample.edu&identity=%22Admin%22+%3Cadmin%40example.edu%3E+%28admin%29+%5B0%5D&time=1214619134&signature=121a6cf76c9c5ecda41450d87e3394b9d02c570a5f76b2bd16287f860f068302")
-    end
-  end
+describe Connection do  
   describe 'requesting an upload location for a file' do
   end
   
   describe 'API accessing' do
     before do
-      Time.should_receive(:now).and_return(@current_time)
-      @current_time.should_receive(:to_i).and_return(1214619134)
-      
+      now = Time.new
+      Time.stub!(:now).and_return(now)
+      now.stub!(:to_i).and_return(1214619134)
+
       user = mock(RTunesU::User, :id => 0,
                                  :username => 'admin',
                                  :name => 'Admin',
@@ -41,13 +22,8 @@ describe Connection do
       @connection = Connection.new(:user => user, :site => 'example.edu', :shared_secret => 'STRINGOFTHIRTYTWOLETTERSORDIGITS')
     end
     
-    it 'access a web services url for the institution' do
+    it 'generates a web services url for the institution' do
       @connection.webservices_url.should eql('https://deimos.apple.com/WebObjects/Core.woa/API/ProcessWebServicesDocument/example.edu?credentials=Administrator%40urn%3Amace%3Aitunesu.com%3Asites%3Aexample.edu&identity=%22Admin%22+%3Cadmin%40example.edu%3E+%28admin%29+%5B0%5D&time=1214619134&signature=121a6cf76c9c5ecda41450d87e3394b9d02c570a5f76b2bd16287f860f068302')
     end
-    
-    it 'can generate a url for uploading files'
-    it 'opens an HTTPS connection to iTunes U'
-    it 'send XML data'
-    it 'generates a url user access to a location through iTunes U'
   end
 end