Class: RTunesU::Entity

Inherits:
Object
  • Object
show all
Defined in:
lib/rtunesu/entity.rb

Overview

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.

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 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 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’]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attrs = {}) ⇒ Entity

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



106
107
108
109
 
# File 'lib/rtunesu/entity.rb', line 106

def initialize(attrs = {})
  attrs.each {|attribute, value| self.send("#{attribute}=", value)}
  self.source_xml = Hpricot.XML('')
end

Instance Attribute Details

#connection ⇒ Object

Returns the value of attribute connection.



28
29
30
 
# File 'lib/rtunesu/entity.rb', line 28

def connection
  @connection
end

#handle ⇒ Object (readonly)

Returns the value of attribute handle.



29
30
31
 
# File 'lib/rtunesu/entity.rb', line 29

def handle
  @handle
end

#parent ⇒ Object

Returns the parent of the entity



159
160
161
 
# File 'lib/rtunesu/entity.rb', line 159

def parent
  @parent
end

#parent_handle ⇒ Object

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).



191
192
193
 
# File 'lib/rtunesu/entity.rb', line 191

def parent_handle
  @parent_handle
end

#saved ⇒ Object

Returns the value of attribute saved.



28
29
30
 
# File 'lib/rtunesu/entity.rb', line 28

def saved
  @saved
end

#source_xml ⇒ Object

Returns the value of attribute source_xml.



28
29
30
 
# File 'lib/rtunesu/entity.rb', line 28

def source_xml
  @source_xml
end

Class Method Details

.attributes ⇒ Object 



31
32
33
 
# File 'lib/rtunesu/entity.rb', line 31

def self.attributes
  @attributes ||= Set.new
end

.base_connection ⇒ Object 



39
40
41
 
# File 'lib/rtunesu/entity.rb', line 39

def self.base_connection 
  Entity.get_base_connection
end

.composed_of(*names) ⇒ Object 



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/rtunesu/entity.rb', line 51

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

.find(handle, connection = nil) ⇒ Object

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)



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/rtunesu/entity.rb', line 128

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

.get_base_connection ⇒ Object

:nodoc:



35
36
37
 
# File 'lib/rtunesu/entity.rb', line 35

def self.get_base_connection # :nodoc:
  @base_connection
end

.has_a(*names) ⇒ Object 



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/rtunesu/entity.rb', line 69

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

.has_n(*names) ⇒ Object 



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/rtunesu/entity.rb', line 86

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

.set_base_connection(connection) ⇒ Object 



43
44
45
 
# File 'lib/rtunesu/entity.rb', line 43

def self.set_base_connection(connection)
  @base_connection = connection
end

.validates!(name, values) ⇒ Object 



47
48
49
 
# File 'lib/rtunesu/entity.rb', line 47

def self.validates!(name, values)
  return
end

Instance Method Details

#base_connection ⇒ Object 



181
182
183
 
# File 'lib/rtunesu/entity.rb', line 181

def base_connection
  self.class.base_connection
end

#class_name ⇒ Object

Returns the name of the object’s class ignoring namespacing.

Use:

course = RTunesU::Course.new course.class #=> ‘RTunesU::Course’ course.class_name #=> ‘Course’



177
178
179
 
# File 'lib/rtunesu/entity.rb', line 177

def class_name
  self.class.to_s.split('::').last
end

#create(connection = nil) ⇒ Object

called when .save is called on an object that has no Handle (i.e. does not already exist in iTunes U)

Raises:



215
216
217
218
219
220
221
222
223
 
# File 'lib/rtunesu/entity.rb', line 215

def create(connection = nil)
  connection ||= self.base_connection
  
  response = Hpricot.XML(connection.process(Document::Add.new(self).xml))
  raise CannotSave, response.at('error').innerHTML if response.at('error')
  @handle = response.at('AddedObjectHandle').innerHTML
  edits.clear
  self
end

#delete(connection = nil) ⇒ Object

Deletes the entity from iTunes U. This cannot be undone.

Raises:

  • (Exception) 


239
240
241
242
243
244
245
246
 
# File 'lib/rtunesu/entity.rb', line 239

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')
  @handle = nil
  self
end

#edited? ⇒ Boolean

Returns:

  • (Boolean) 


149
150
151
 
# File 'lib/rtunesu/entity.rb', line 149

def edited?
  self.edits.any?
end

#edits ⇒ Object

Edits stores the changes made to an entity



145
146
147
 
# File 'lib/rtunesu/entity.rb', line 145

def edits
  @edits ||= {}
end

#handle_from_source ⇒ Object 



115
116
117
118
119
120
121
122
 
# File 'lib/rtunesu/entity.rb', line 115

def handle_from_source
  return nil unless self.source_xml
  if (handle_elem = self.source_xml % 'Handle')
    handle_elem.innerHTML
  else
    nil
  end
end

#inspect ⇒ Object 



248
249
250
251
252
253
254
 
# File 'lib/rtunesu/entity.rb', line 248

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

#load_from_xml(xml_or_entity) ⇒ Object 



140
141
142
 
# File 'lib/rtunesu/entity.rb', line 140

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

#reload ⇒ Object

Clear the edits and restores the loaded object to its original form



154
155
156
 
# File 'lib/rtunesu/entity.rb', line 154

def reload
  self.edits.clear
end

#save(connection = nil) ⇒ Object

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.



228
229
230
231
 
# File 'lib/rtunesu/entity.rb', line 228

def save(connection = nil)
  connection ||= self.base_connection
  saved? ? update(connection) : create(connection)
end

#saved? ⇒ Boolean

Has the entity be previously saved in iTunes U

Returns:

  • (Boolean) 


234
235
236
 
# File 'lib/rtunesu/entity.rb', line 234

def saved?
  self.handle ? true : false
end

#to_xml(xml_builder = Builder::XmlMarkup.new) ⇒ Object

Converts the entities changed attributes and subentities to XML. Called by Document when building documents to transfer to iTunes U.



197
198
199
200
201
202
203
 
# File 'lib/rtunesu/entity.rb', line 197

def to_xml(xml_builder = Builder::XmlMarkup.new)
  xml_builder.tag!(self.class_name) {
    self.edits.each do |attribute,edit|
      edit.is_a?(SubentityAssociationProxy) ? edit.to_xml(xml_builder) : xml_builder.tag!(attribute, edit)
    end
  }
end

#update(connection = nil) ⇒ Object

called when .save is called on an object that is already stored in iTunes U



206
207
208
209
210
211
212
 
# File 'lib/rtunesu/entity.rb', line 206

def update(connection = nil)
  connection ||= self.base_connection
  
  connection.process(Document::Merge.new(self).xml)
  edits.clear
  self
end

#value_from_edits_or_store(name) ⇒ Object 



165
166
167
168
169
 
# File 'lib/rtunesu/entity.rb', line 165

def value_from_edits_or_store(name)
  self.edits[name] ||  (self.source_xml % name).innerHTML
rescue NoMethodError
  nil
end