class ROBundle::File
This class represents a Research Object Bundle file. See the RO Bundle specification for more details.
Many of the methods that this class provides are actually implemented in the Manifest
class, so please see its documentation for details.
Attributes
Public Class Methods
Create a new RO Bundle file on disk and open it for editing. A custom mimetype for the bundle may be specified but is unnecessary if the default, “application/vnd.wf4ever.robundle+zip”, will be used.
Please see the UCF documentation for much more information and a list of all the other methods available in this class. RDoc does not list inherited methods, unfortunately.
# File lib/ro-bundle/file.rb 58 def self.create(filename, mimetype = MIMETYPE, &block) 59 # Wow. I have to specifically send nil as the block to stop super from 60 # sending the other block up automatically. Is this a bug in Ruby? 61 ro = super(filename, mimetype, &nil) 62 ro.init_metadata 63 64 if block_given? 65 begin 66 yield ro 67 ensure 68 ro.close 69 end 70 end 71 72 ro 73 end
Public Instance Methods
Convenience method for adding the contents of a file to the bundle file. If asked to add a file with a reserved name, such as the special mimetype header file or .ro/manifest.json, this method will raise a ReservedNameClashError.
This method automatically adds new entries to the list of bundle aggregates unless the :aggregate
option is set to false.
If the added entry is aggregated then the Aggregate
object is returned, otherwise nil
is returned.
See the rubyzip documentation for details of the continue_on_exists_proc
parameter.
# File lib/ro-bundle/file.rb 91 def add(entry, src_path, options = {}, &continue_on_exists_proc) 92 super(entry, src_path, &continue_on_exists_proc) 93 94 options = { :aggregate => true }.merge(options) 95 96 if options[:aggregate] 97 @manifest.add_aggregate(entry) 98 end 99 end
The first form of this method adds a URI as an aggregate of the bundle.
The second form adds an already existing entry in the bundle to the list of aggregates. Errno:ENOENT
is raised if the entry does not exist.
The third form is equivalent to File#add
called without any options.
In all cases the Aggregate
object added to the Research Object is returned.
# File lib/ro-bundle/file.rb 116 def add_aggregate(entry, src_path = nil, &continue_on_exists_proc) 117 if src_path.nil? 118 @manifest.add_aggregate(entry) 119 else 120 add(entry, src_path, &continue_on_exists_proc) 121 end 122 end
This method has two forms.
The first form registers an already initialized Annotation
object in this Research Object.
The second form creates a new Annotation
object for the specified target with the specified (or empty content) and registers it in this Research Object.
In both cases Errno:ENOENT
is raised if the target of the annotation is not an annotatable resource.
The Annotation
object added to the Research Object is returned.
# File lib/ro-bundle/file.rb 149 def add_annotation(target, body = nil, options = {}) 150 options = { :aggregate => false }.merge(options) 151 152 if target.is_a?(Annotation) || annotatable?(target) 153 if body.nil? || aggregate?(body) 154 content = body 155 elsif Util.is_absolute_uri?(body) 156 content = body 157 @manifest.add_aggregate(body) if options[:aggregate] 158 else 159 content = @ro_dir.write_annotation_data(body, options) 160 end 161 162 @manifest.add_annotation(target, content) 163 else 164 raise Errno::ENOENT, 165 "'#{target}' is not a member of this Research Object or a URI." 166 end 167 end
The first form of this method adds an already existing entry in the bundle to the history list in the manifest. Errno:ENOENT
is raised if the entry does not exist.
The second form adds the entry before adding it to the history list. The entry is not aggregated.
# File lib/ro-bundle/file.rb 179 def add_history(entry, src_path = nil, &continue_on_exists_proc) 180 unless src_path.nil? 181 add(entry, src_path, :aggregate => false, &continue_on_exists_proc) 182 end 183 184 @manifest.add_history(entry) 185 end
Is the supplied URI or entry aggregated in this Research Object?
# File lib/ro-bundle/file.rb 192 def aggregate?(entry) 193 return true if entry == @manifest.id 194 195 if Util.is_absolute_uri?(entry) 196 entry = entry.to_s 197 else 198 entry = entry_name(entry) 199 end 200 201 aggregates.each do |agg| 202 return true if agg.uri == entry || agg.file_entry == entry 203 end 204 205 false 206 end
Is the supplied target an annotatable resource? An annotatable resource is either an absolute URI (which may or may not be aggregated in the RO), an aggregated resource or another registered annotation.
# File lib/ro-bundle/file.rb 214 def annotatable?(target) 215 Util.is_absolute_uri?(target) || annotation?(target) || aggregate?(target) 216 end
Is the supplied id or annotation registered in this Research Object?
# File lib/ro-bundle/file.rb 223 def annotation?(id) 224 id = id.uri if id.instance_of?(Annotation) 225 226 annotations.each do |ann| 227 return true if ann.uri == id 228 end 229 230 false 231 end
Commits changes that have been made since the previous commit to the RO Bundle file. Returns true
if anything was actually done, false
otherwise.
# File lib/ro-bundle/file.rb 240 def commit 241 if @manifest.edited? 242 # This will overwrite the old version. 243 @manifest.write 244 245 @ro_dir.cleanup_annotation_data 246 end 247 248 super 249 end
Returns true
if any changes have been made to this RO Bundle file since the last commit, false
otherwise.
# File lib/ro-bundle/file.rb 258 def commit_required? 259 super || @manifest.edited? 260 end
Searches for the entry with the specified name. Returns nil
if no entry is found or if the specified entry is hidden for normal use. You can specify :include_hidden => true
to include hidden entries in the search.
# File lib/ro-bundle/file.rb 269 def find_entry(entry_name, options = {}) 270 return if Util.is_absolute_uri?(entry_name) 271 272 super(entry_name, options) 273 end
Removes the specified entry from the Research Object bundle. If asked to remove any reserved files such as the special mimetype header file this method will do nothing.
If the entry being removed is aggregated in this RO then the aggregation is removed. All annotations that refer to the removed entry are also removed.
# File lib/ro-bundle/file.rb 285 def remove(entry, preserve_manifest = false) 286 super(entry) 287 288 # The preserve manifest flag is STRICTLY for internal use only. 289 unless preserve_manifest 290 name = entry_name(entry) 291 @manifest.remove_aggregate("/#{name}") 292 remove_annotation("/#{name}") 293 end 294 end
Remove (unregister) an aggregate from this Research Object. If it is a file then the file is no longer aggregated, and it is deleted from the bundle by this method unless the option :keep_file => true
is supplied.
Any annotations with the removed aggregate as their target are also removed from the RO.
# File lib/ro-bundle/file.rb 308 def remove_aggregate(object, options = {}) 309 options = { :keep_file => false }.merge(options) 310 file = nil 311 312 if object.is_a?(Aggregate) 313 file = object.file_entry 314 elsif !Util.is_absolute_uri?(object) 315 object = entry_name(object) 316 file = Util.strip_leading_slash(object) 317 end 318 319 if !file.nil? && !options[:keep_file] 320 remove(file, true) 321 end 322 323 @manifest.remove_aggregate(object) 324 end