Class: Atom::Collection

Inherits:
Element
  • Object
show all
Defined in:
lib/sword2ruby/collection.rb

Overview

Extensions to the atom-tools Atom::Collection class to support Sword2 operations. These methods are additive to those supplied by the atom-tools gem.

Please see the atom-tools documentation for a complete list of attributes and methods.

Instance Method Summary collapse

Instance Method Details

#app_accept ⇒ Object

This method returns the string value of the <app:accept> tag, or nil if it not defined in the service document.



56
57
58
 
# File 'lib/sword2ruby/collection.rb', line 56

def app_accept
  sword_accepts.find{|a| a.alternate.nil? }
end

#app_accept_alternate_multipart_related ⇒ Object

This method returns the string value of the <app:accept alternate=“multipart-related”> tag, or nil if it not defined in the service document.



62
63
64
 
# File 'lib/sword2ruby/collection.rb', line 62

def app_accept_alternate_multipart_related
  sword_accepts.find{|a| a.alternate == "multipart-related" }
end

#collection_uri ⇒ Object

This method returns the URI string from the @href attribute of the Collection, or nil if it is not defined.



20
21
22
 
# File 'lib/sword2ruby/collection.rb', line 20

def collection_uri
  @href
end

#post!(params = {}) ⇒ Object

This method creates a new entry in the collection by posting an Atom entry to the collection URI. The method will return a Sword2Ruby::DepositReceipt object, or raise a Sword2Ruby::Exception in the case of an error.

Parameters (passed as a hash collection)

:entry

an Atom::Entry to be added to the collection

:slug

(optional) string value indicating the suggested identifier of the new entry

:collection_uri

(optional) the collection URI to post to. If not supplied, this will default to the current collection’s URI as specified in the @href attribute.

:in_progress

(optional) boolean value indicating whether the new entry will be completed at a later date

:on_behalf_of

(optional) string value indicating username on whos behalf the submission is being performed

:connection

(optional) Sword2Ruby::Connection object used to perform the operation. If not supplied, the existing collection’s connection will be used.

Note that you should call <collection>.feed.updated! followed by <collection>.feed.update! after making updates to a collection.

For more information, see the Sword2 specification: section 6.3.3. “Creating a Resource with an Atom Entry”.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/sword2ruby/collection.rb', line 81

def post!(params = {})
  Utility.check_argument_class('params', params, Hash)
  defaults = {
    :entry => nil,
    :slug => nil,
    :collection_uri => collection_uri,
    :in_progress => nil,
    :on_behalf_of => nil,
    :connection => @http
  }
  options = defaults.merge(params)

  #Validate parameters
  Utility.check_argument_class(':entry', options[:entry], ::Atom::Entry)
  Utility.check_argument_class(':slug', options[:slug], String) if options[:slug]
  Utility.check_argument_class(':collection_uri', options[:collection_uri], String)
  Utility.check_argument_class(':on_behalf_of', options[:on_behalf_of], String) if options[:on_behalf_of]
  Utility.check_argument_class(':connection', options[:connection], Sword2Ruby::Connection)
   
  headers = {"Content-Type" => "application/atom+xml;type=entry" }
  headers["Slug"] = options[:slug] if options[:slug]
  headers["In-Progress"] = options[:in_progress].to_s.downcase if (options[:in_progress] == true || options[:in_progress] == false)
  headers["On-Behalf-Of"] = options[:on_behalf_of] if options[:on_behalf_of]

  response = options[:connection].post(options[:collection_uri], options[:entry].to_s, headers)
  if response.is_a? Net::HTTPSuccess
    return DepositReceipt.new(response, options[:connection])
  else
    raise Sword2Ruby::Exception.new("Failed to do post!(#{options[:collection_uri]}): server returned code #{response.code} #{response.message}")
  end
end

#post_media!(params = {}) ⇒ Object

This method creates a new entry in the collection by posting a file to the collection URI. An MD5-digest will be calculated automatically from the file and sent to the server with the request. The method will return a Sword2Ruby::DepositReceipt object, or raise a Sword2Ruby::Exception in the case of an error.

Parameters (passed as a hash collection)

:filepath

a filepath string indicating the file to be posted. The file must be readable by the process.

:content_type

the mime content-type string of the file, e.g. “application/zip” or “text/plain”

:packaging

(optional) the Sword packaging string of the file, e.g. “purl.org/net/sword/package/METSDSpaceSIP”

:slug

(optional) the suggested identifier of the new entry

:collection_uri

(optional) the collection URI to post to. If not supplied, this will default to the current collection’s URI as specified in the @href attribute.

:in_progress

(optional) boolean value indicating whether the new entry will be completed at a later date

:on_behalf_of

(optional) username on whos behalf the submission is being performed

:connection

(optional) Sword2Ruby::Connection object used to perform the operation. If not supplied, the existing collection’s connection will be used.

Note that you should call <collection>.feed.updated! followed by <collection>.feed.update! after making updates to a collection.

For more information, see the Sword2 specification: section 6.3.1. “Creating a Resource with a Binary File Deposit”.



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/sword2ruby/collection.rb', line 129

def post_media!(params = {})
  Utility.check_argument_class('params', params, Hash)
  defaults = {
    :filepath => nil,
    :content_type => nil,
    :packaging => nil,
    :slug => nil,
    :collection_uri => collection_uri,
    :in_progress => nil,
    :on_behalf_of => nil,
    :connection => @http
  }
  options = defaults.merge(params)

  #Validate parameters
  Utility.check_argument_class(':filepath', options[:filepath], String)
  Utility.check_argument_class(':content_type', options[:content_type], String)
  Utility.check_argument_class(':packaging', options[:packaging], String) if options[:packaging]
  Utility.check_argument_class(':slug', options[:slug], String) if options[:slug]
  Utility.check_argument_class(':collection_uri', options[:collection_uri], String)
  Utility.check_argument_class(':on_behalf_of', options[:on_behalf_of], String) if options[:on_behalf_of]
  Utility.check_argument_class(':connection', options[:connection], Sword2Ruby::Connection)
    
  filename, md5, data = Utility.read_file(options[:filepath])
  
  headers = {"Content-Type" => options[:content_type]}
  headers["Content-Disposition"] = "attachment; filename=#{filename}"
  headers["Content-MD5"] = md5
  headers["Packaging"] = options[:packaging] if options[:packaging]
  headers["Slug"] = options[:slug] if options[:slug]
  headers["In-Progress"] = options[:in_progress].to_s.downcase if (options[:in_progress] == true || options[:in_progress] == false)
  headers["On-Behalf-Of"] = options[:on_behalf_of] if options[:on_behalf_of]

  response = options[:connection].post(options[:collection_uri], data, headers)
  
  if response.is_a? Net::HTTPSuccess
    return DepositReceipt.new(response, options[:connection])
  else
    raise Sword2Ruby::Exception.new("Failed to do post_media!(#{options[:collection_uri]}): server returned #{response.code} #{response.message}")
  end
end

#post_multipart!(params = {}) ⇒ Object

This method creates a new entry in the collection by posting a file and atom-entry to the collection URI. An MD5-digest will be calculated automatically from the file and sent to the server with the request. The method will return a Sword2Ruby::DepositReceipt object, or raise a Sword2Ruby::Exception in the case of an error.

Parameters (passed as a hash collection)

:entry

an Atom::Entry to be added to the collection

:filepath

a filepath string indicating the file to be posted. The file must be readable by the process.

:content_type

the mime content-type string of the file, e.g. “application/zip” or “text/plain”

:packaging

(optional) the Sword packaging string of the file, e.g. “purl.org/net/sword/package/METSDSpaceSIP”

:slug

(optional) the suggested identifier of the new entry

:collection_uri

(optional) the collection URI to post to. If not supplied, this will default to the current collection’s URI as specified in the @href attribute.

:in_progress

(optional) boolean value indicating whether the new entry will be completed at a later date

:on_behalf_of

(optional) username on whos behalf the submission is being performed

:connection

(optional) Sword2Ruby::Connection object used to perform the operation. If not supplied, the existing collection’s connection will be used.

Note that you should call <collection>.feed.updated! followed by <collection>.feed.update! after making updates to a collection.

For more information, see the Sword2 specification: section 6.3.2. “Creating a Resource with a Multipart Deposit”.



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/sword2ruby/collection.rb', line 188

def post_multipart!(params = {})
  Utility.check_argument_class('params', params, Hash)
  defaults = {
    :entry => nil,
    :filepath => nil,
    :content_type => nil,
    :packaging => nil,
    :slug => nil,
    :collection_uri => collection_uri,        
    :in_progress => nil,
    :on_behalf_of => nil,
    :connection => @http
  }
  options = defaults.merge(params)

  #Validate parameters
  Utility.check_argument_class(':entry', options[:entry], ::Atom::Entry)
  Utility.check_argument_class(':filepath', options[:filepath], String)
  Utility.check_argument_class(':content_type', options[:content_type], String)
  Utility.check_argument_class(':packaging', options[:packaging], String) if options[:packaging]
  Utility.check_argument_class('slug', options[:slug], String) if options[:slug]
  Utility.check_argument_class(':collection_uri', options[:collection_uri], String)
  Utility.check_argument_class(':on_behalf_of', options[:on_behalf_of], String) if options[:on_behalf_of]
  Utility.check_argument_class(':connection', options[:connection], Sword2Ruby::Connection)
        
  tmp = ""
  boundary = "========" + Time.now.to_i.to_s + "=="
  filename, md5, data = Utility.read_file(options[:filepath])

  headers = {"Content-Type" => 'multipart/related; boundary="' + boundary + '"; type="application/atom+xml"'}
  headers["Slug"] = options[:slug] if options[:slug]
  headers["In-Progress"] = options[:in_progress].to_s.downcase if (options[:in_progress] == true || options[:in_progress] == false)
  headers["On-Behalf-Of"] = options[:on_behalf_of] if options[:on_behalf_of]
  headers["MIME-Version"] = "1.0"
  
  
  # write boundary identifer to temp
  tmp << "--#{boundary}\r\n"

  # write entry relevant headers to temp
  tmp << "Content-Type: application/atom+xml; charset=\"utf-8\"\r\n"
  tmp << "Content-Disposition: attachment; name=atom\r\n"
  tmp << "MIME-Version: 1.0\r\n\r\n"

  # write entry to temp
  tmp << options[:entry].to_s + "\r\n"
  
  # write boundary identifier to temp
  tmp << "--#{boundary}\r\n"

  # write media part relevant headers to temp      
  tmp << "Content-Type: #{options[:content_type]}\r\n"
  tmp << "Content-Disposition: attachment; name=payload; filename=#{filename}\r\n"
  tmp << "Content-MD5: #{md5}\r\n"
  tmp << "Packaging: #{options[:packaging]}\r\n" if options[:packaging]
  tmp << "MIME-Version: 1.0\r\n\r\n"
  
  # write the file base64 encoded to temp
  tmp << Base64.encode64(data)

  # write boundary identifier to temp
  tmp << "--#{boundary}--\r\n" #The last two dashes (--) are important!
  
  response = options[:connection].post(options[:collection_uri], tmp, headers)

  if response.is_a? Net::HTTPSuccess
    return DepositReceipt.new(response, options[:connection])
  else
    raise Sword2Ruby::Exception.new("Failed to do post_multipart!(#{options[:collection_uri]}): server returned #{response.code} #{response.message}")
  end
end

#sword_accept_packagings ⇒ Object

This method returns an array of the string values of the <sword:acceptPackaging> tags, or an empty array [ ] if none are defined in the service document.



44
45
46
 
# File 'lib/sword2ruby/collection.rb', line 44

def sword_accept_packagings
  Utility.find_elements_text(extensions, "sword:acceptPackaging")
end

#sword_collection_policy ⇒ Object

This method returns the string value of the <sword:collectionPolicy>, or nil if it is not defined in the service document.



26
27
28
 
# File 'lib/sword2ruby/collection.rb', line 26

def sword_collection_policy
  Utility.find_element_text(extensions, "sword:collectionPolicy")
end

#sword_mediation ⇒ Object

This method returns the boolean value of the <sword:mediation> tag, or false if it is not defined in the service document.



32
33
34
 
# File 'lib/sword2ruby/collection.rb', line 32

def sword_mediation
  Utility.find_element_boolean(extensions, "sword:mediation") || false
end

#sword_services ⇒ Object

This method returns an array of the string values of the <sword:service> tags, or an empty array [ ] if none are defined in the service document.



50
51
52
 
# File 'lib/sword2ruby/collection.rb', line 50

def sword_services
  Utility.find_elements_text(extensions, "sword:service")
end

#sword_treatment ⇒ Object

This method returns the string value of the <sword:treatment> tag, or nil if it is not defined in the service document.



38
39
40
 
# File 'lib/sword2ruby/collection.rb', line 38

def sword_treatment
  Utility.find_element_text(extensions, "sword:treatment")
end