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.

Public Class Methods

create(filename) → File click to toggle source

create(filename, mimetype) → File

create(filename) {|file| ...}

create(filename, mimetype) {|file| ...}

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.

Calls superclass method

# File lib/ro-bundle/file.rb, line 60
def self.create(filename, mimetype = MIMETYPE, &block)
  super(filename, mimetype, &block)
end

Public Instance Methods

add(entry, src_path, options = {}, &continue_on_exists_proc) → Aggregate or nil click to toggle source

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.

Calls superclass method

# File lib/ro-bundle/file.rb, line 80
def add(entry, src_path, options = {}, &continue_on_exists_proc)
  super(entry, src_path, &continue_on_exists_proc)

  options = { :aggregate => true }.merge(options)

  if options[:aggregate]
    @manifest.add_aggregate(entry)
  end
end

add_aggregate(uri) → Aggregate click to toggle source

add_aggregate(entry) → Aggregate

add_aggregate(entry, src_path, &continue_on_exists_proc) → Aggregate

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 #add called without any options.

In all cases the Aggregate object added to the Research Object is returned.

# File lib/ro-bundle/file.rb, line 105
def add_aggregate(entry, src_path = nil, &continue_on_exists_proc)
  if src_path.nil?
    @manifest.add_aggregate(entry)
  else
    add(entry, src_path, &continue_on_exists_proc)
  end
end

add_annotation(annotation_object) → Annotation click to toggle source

add_annotation(aggregate, content, options = {}) → Annotation

add_annotation(aggregate, file, options = {}) → Annotation

add_annotation(aggregate, uri, options = {}) → Annotation

add_annotation(uri, content, options = {}) → Annotation

add_annotation(uri, file, options = {}) → Annotation

add_annotation(uri, uri, options = {}) → Annotation

add_annotation(annotation, content, options = {}) → Annotation

add_annotation(annotation, file, options = {}) → Annotation

add_annotation(annotation, uri, options = {}) → Annotation

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, line 138
def add_annotation(target, body = nil, options = {})
  options = { :aggregate => false }.merge(options)

  if target.is_a?(Annotation) || annotatable?(target)
    if body.nil? || aggregate?(body)
      content = body
    elsif Util.is_absolute_uri?(body)
      content = body
      @manifest.add_aggregate(body) if options[:aggregate]
    else
      content = @ro_dir.write_annotation_data(body, options)
    end

    @manifest.add_annotation(target, content)
  else
    raise Errno::ENOENT,
      "'#{target}' is not a member of this Research Object or a URI."
  end
end

add_history(entry) click to toggle source

add_history(entry, src_path, &continue_on_exists_proc)

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, line 168
def add_history(entry, src_path = nil, &continue_on_exists_proc)
  unless src_path.nil?
    add(entry, src_path, :aggregate => false, &continue_on_exists_proc)
  end

  @manifest.add_history(entry)
end

aggregate?(uri) → true or false click to toggle source

aggregate?(entry) → true or false

Is the supplied URI or entry aggregated in this Research Object?

# File lib/ro-bundle/file.rb, line 181
def aggregate?(entry)
  return true if entry == @manifest.id

  if Util.is_absolute_uri?(entry)
    entry = entry.to_s
  else
    entry = entry_name(entry)
  end

  aggregates.each do |agg|
    return true if agg.uri == entry ||
      agg.file == entry ||
      agg.file_entry == entry
  end

  false
end

annotatable?(target) → true or false click to toggle source

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, line 205
def annotatable?(target)
  Util.is_absolute_uri?(target) || annotation?(target) || aggregate?(target)
end

annotation?(id) → true or false click to toggle source

annotation?(annotation) → true or false

Is the supplied id or annotation registered in this Research Object?

# File lib/ro-bundle/file.rb, line 214
def annotation?(id)
  id = id.annotation_id if id.instance_of?(Annotation)

  annotations.each do |ann|
    return true if ann.annotation_id == id
  end

  false
end

close()

Alias for: commit

commit → true or false click to toggle source

close → true or false

Commits changes that have been made since the previous commit to the RO Bundle file. Returns true if anything was actually done, false otherwise.

Calls superclass method

# File lib/ro-bundle/file.rb, line 231
def commit
  if @manifest.edited?
    name = @manifest.full_name
    remove(name, true) unless find_entry(name).nil?

    file.open(name, "w") do |m|
      m.puts JSON.pretty_generate(@manifest)
    end

    @ro_dir.cleanup_annotation_data
  end

  super
end

Also aliased as: close

commit_required? → true or false click to toggle source

Returns true if any changes have been made to this RO Bundle file since the last commit, false otherwise.

Calls superclass method

# File lib/ro-bundle/file.rb, line 253
def commit_required?
  super || @manifest.edited?
end

find_entry(entry_name, options = {}) → Zip::Entry or nil click to toggle source

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.

Calls superclass method

# File lib/ro-bundle/file.rb, line 264
def find_entry(entry_name, options = {})
  return if Util.is_absolute_uri?(entry_name)

  super(entry_name, options)
end

remove(entry) click to toggle source

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.

Calls superclass method

# File lib/ro-bundle/file.rb, line 280
def remove(entry, preserve_manifest = false)
  super(entry)

  # The preserve manifest flag is STRICTLY for internal use only.
  unless preserve_manifest
    name = entry_name(entry)
    @manifest.remove_aggregate("/#{name}")
    remove_annotation("/#{name}")
  end
end

remove_aggregate(entry) click to toggle source

remove_aggregate(uri)

remove_aggregate(Aggregate)

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, line 303
def remove_aggregate(object, options = {})
  options = { :keep_file => false }.merge(options)
  file = nil

  if object.is_a?(Aggregate)
    file = object.file_entry
  elsif !Util.is_absolute_uri?(object)
    object = entry_name(object)
    file = Util.strip_leading_slash(object)
  end

  if !file.nil? && !options[:keep_file]
    remove(file, true)
  end

  @manifest.remove_aggregate(object)
end