ro-bundle 0.1.0

data/lib/ro-bundle/ro/aggregate.rb

@@ -0,0 +1,107 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2014 The University of Manchester, UK.
+#
+# BSD Licenced. See LICENCE.rdoc for details.
+#
+# Author: Robert Haines
+#------------------------------------------------------------------------------
+
+#
+module ROBundle
+
+  # A class to represent an aggregated resource in a Research Object. It holds
+  # standard meta-data for either file or URI resources. An aggregate can only
+  # represent a file OR a URI resource, not both at once.
+  class Aggregate
+    include Provenance
+
+    # :call-seq:
+    #   new(filename, mediatype = nil)
+    #   new(URI)
+    #
+    # Create a new file or URI aggregate.
+    def initialize(object, second = nil)
+      @structure = {}
+
+      if object.instance_of?(Hash)
+        init_json(object)
+      else
+        init_file_or_uri(object)
+
+        if @structure[:file]
+          @structure[:mediatype] = second
+        end
+      end
+    end
+
+    # :call-seq:
+    #   file
+    #
+    # The path of this aggregate. It should start with '/'.
+    def file
+      @structure[:file]
+    end
+
+    # :call-seq:
+    #   file_entry
+    #
+    # The path of this aggregate in "rubyzip" format, i.e. no leading '/'.
+    def file_entry
+      Util.strip_leading_slash(file)
+    end
+
+    # :call-seq:
+    #   uri
+    #
+    # The URI of this aggregate. It should be an absolute URI.
+    def uri
+      @structure[:uri]
+    end
+
+    # :call-seq:
+    #   mediatype
+    #
+    # For a file aggregate, its
+    # {IANA media type}[http://www.iana.org/assignments/media-types].
+    def mediatype
+      @structure[:mediatype]
+    end
+
+    # :call-seq:
+    #   to_json(options = nil) -> String
+    #
+    # Write this Aggregate out as a json string. Takes the same options as
+    # JSON#generate.
+    def to_json(*a)
+      Util.clean_json(@structure).to_json(*a)
+    end
+
+    private
+
+    def structure
+      @structure
+    end
+
+    def init_json(object)
+      init_file_or_uri(object[:file] || object[:uri])
+      @structure = init_provenance_defaults(object)
+
+      if @structure[:file]
+        @structure[:mediatype] = object[:mediatype]
+      end
+    end
+
+    def init_file_or_uri(object)
+      if object.is_a?(String) && !Util.is_absolute_uri?(object)
+        name = object.start_with?("/") ? object : "/#{object}"
+        @structure[:file] = name
+      elsif Util.is_absolute_uri?(object)
+        @structure[:uri] = object.to_s
+      else
+        raise InvalidAggregateError.new(object)
+      end
+    end
+
+  end
+
+end

data/lib/ro-bundle/ro/annotation.rb

@@ -0,0 +1,89 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2014 The University of Manchester, UK.
+#
+# BSD Licenced. See LICENCE.rdoc for details.
+#
+# Author: Robert Haines
+#------------------------------------------------------------------------------
+
+#
+module ROBundle
+
+  # A class to represent an Annotation in a Research Object.
+  class Annotation
+    include Provenance
+
+    # :call-seq:
+    #   new(target, content = nil)
+    #
+    # Create a new Annotation with the specified "about" identifier. A new
+    # annotation ID is generated and set for the new annotation. The +content+
+    # parameter can be optionally used to set the file or URI that holds the
+    # body of the annotation.
+    #
+    # An annotation id is a UUID prefixed with "urn:uuid" as per
+    # {RFC4122}[http://www.ietf.org/rfc/rfc4122.txt].
+    def initialize(object, content = nil)
+      if object.instance_of?(Hash)
+        @structure = object
+        init_provenance_defaults(@structure)
+      else
+        @structure = {}
+        @structure[:about] = object
+        @structure[:annotation] = UUID.generate(:urn)
+        @structure[:content] = content
+      end
+    end
+
+    # :call-seq:
+    #   target
+    #
+    # The identifier for the annotated resource. This is considered the target
+    # of the annotation, that is the resource the annotation content is
+    # "somewhat about".
+    def target
+      @structure[:about]
+    end
+
+    # :call-seq:
+    #   content
+    #
+    # The identifier for a resource that contains the body of the annotation.
+    def content
+      @structure[:content]
+    end
+
+    # :call-seq:
+    #   content = new_content
+    #
+    # Set the content of this annotation.
+    def content=(new_content)
+      @structure[:content] = new_content
+    end
+
+    # :call-seq:
+    #   annotation_id -> String
+    #
+    # Return the annotation id of this Annotation.
+    def annotation_id
+      @structure[:annotation]
+    end
+
+    # :call-seq:
+    #   to_json(options = nil) -> String
+    #
+    # Write this Annotation out as a json string. Takes the same options as
+    # JSON#generate.
+    def to_json(*a)
+      Util.clean_json(@structure).to_json(*a)
+    end
+
+    private
+
+    def structure
+      @structure
+    end
+
+  end
+
+end

data/lib/ro-bundle/ro/directory.rb

@@ -0,0 +1,120 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2014 The University of Manchester, UK.
+#
+# BSD Licenced. See LICENCE.rdoc for details.
+#
+# Author: Robert Haines
+#------------------------------------------------------------------------------
+
+#
+module ROBundle
+
+  # The managed .ro directory entry of a Research Object.
+  #
+  # For internal use only.
+  class RODir < ZipContainer::ManagedDirectory
+
+    DIR_NAME = ".ro" # :nodoc:
+
+    # :call-seq:
+    #   new(manifest)
+    #
+    # Create a new .ro managed directory entry with the specified manifest
+    # file object.
+    def initialize(manifest)
+      @manifest = manifest
+      @annotations_directory = AnnotationsDir.new
+
+      super(DIR_NAME, :required => true,
+        :entries => [@manifest, @annotations_directory])
+    end
+
+    # :stopdoc:
+    def cleanup_annotation_data
+      container.glob("#{@annotations_directory.full_name}/*",
+        :include_hidden => true) do |file|
+
+        found = false
+        @manifest.annotations.each do |ann|
+          content_name = normalize_content_name(ann.content)
+
+          if content_name == file.name
+            found = true
+            break
+          end
+        end
+
+        container.remove(file.name, true) unless found
+      end
+    end
+
+    def write_annotation_data(source, options)
+      uuid = UUID.generate
+
+      if options[:aggregate]
+        entry = uuid
+        content = "/#{uuid}"
+      else
+        mk_annotations_dir
+        content = "#{@annotations_directory.name}/#{uuid}"
+        entry = "#{full_name}/#{content}"
+      end
+
+      if ::File.exist?(source)
+        container.add(entry, source, options)
+      else
+        container.file.open(entry, "w") do |annotation|
+          annotation.write source.to_s
+        end
+
+        if options[:aggregate]
+          @manifest.add_aggregate(entry)
+        end
+      end
+
+      content
+    end
+    # :startdoc:
+
+    private
+
+    def mk_annotations_dir
+      dir_name = "#{full_name}/#{@annotations_directory.name}"
+      if container.find_entry(dir_name, :include_hidden => true).nil?
+        container.mkdir dir_name
+      end
+    end
+
+    # Convert an annotation content field into something compatible with the
+    # rubyzip file naming convention (i.e. full paths not prefixed with /).
+    def normalize_content_name(name)
+      return if name.nil?
+
+      if name.start_with?(@annotations_directory.name)
+        "#{full_name}/#{name}"
+      elsif name.start_with?("/#{@annotations_directory.full_name}")
+        name.slice(1, name.length)
+      else
+        nil
+      end
+    end
+
+    # The managed annotations directory within the .ro directory.
+    #
+    # For internal use only.
+    class AnnotationsDir < ZipContainer::ManagedDirectory
+
+      DIR_NAME = "annotations" # :nodoc:
+
+      # :call-seq:
+      #   new
+      #
+      # Create a new annotations managed directory. The directory is hidden
+      # under normal circumstances.
+      def initialize
+        super(DIR_NAME, :hidden => true)
+      end
+
+    end
+  end
+end

data/lib/ro-bundle/ro/manifest.rb

@@ -0,0 +1,338 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2014 The University of Manchester, UK.
+#
+# BSD Licenced. See LICENCE.rdoc for details.
+#
+# Author: Robert Haines
+#------------------------------------------------------------------------------
+
+#
+module ROBundle
+
+  # The manifest.json managed file entry for a Research Object.
+  class Manifest < ZipContainer::ManagedFile
+    include Provenance
+
+    FILE_NAME = "manifest.json" # :nodoc:
+    DEFAULT_CONTEXT = "https://w3id.org/bundle/context" # :nodoc:
+    DEFAULT_ID = "/" # :nodoc:
+
+    # :call-seq:
+    #   new
+    #
+    # Create a new managed file entry to represent the manifest.json file.
+    def initialize
+      super(FILE_NAME, :required => true)
+
+      @edited = false
+    end
+
+    # :call-seq:
+    #   context -> List of context URIs
+    #
+    # Return the list of @context URIs for this Research Object manifest.
+    def context
+      structure[:@context].dup
+    end
+
+    # :call-seq:
+    #   add_context
+    #
+    # Add a URI to the front of the @context list.
+    def add_context(uri)
+      @edited = true
+      structure[:@context].insert(0, uri.to_s)
+    end
+
+    # :call-seq:
+    #   id -> String
+    #
+    # An RO identifier (usually '/') indicating the relative top-level folder
+    # as the identifier.
+    def id
+      structure[:id]
+    end
+
+    # :call-seq:
+    #   id = new_id
+    #
+    # Set the id of this Manifest.
+    def id=(new_id)
+      @edited = true
+      structure[:id] = new_id
+    end
+
+    # :call-seq:
+    #   history -> List of history entry names
+    #
+    # Return a list of filenames that hold provenance information for this
+    # Research Object.
+    def history
+      structure[:history].dup
+    end
+
+    # :call-seq:
+    #   add_history(entry)
+    #
+    # Add the given entry to the history list in this manifest.
+    # <tt>Errno:ENOENT</tt> is raised if the entry does not exist.
+    def add_history(entry)
+      raise Errno::ENOENT if container.find_entry(entry).nil?
+
+      # Mangle the filename according to the RO Bundle specification.
+      name = entry_name(entry)
+      dir = "#{@parent.full_name}/"
+      name = name.start_with?(dir) ? name.sub(dir, "") : "/#{name}"
+
+      @edited = true
+      structure[:history] << name
+    end
+
+    # :call-seq:
+    #   aggregates -> List of aggregated resources.
+    #
+    # Return a list of all the aggregated resources in this Research Object.
+    def aggregates
+      structure[:aggregates].dup
+    end
+
+    # :call-seq:
+    #   add_aggregate(entry) -> Aggregate
+    #   add_aggregate(uri) -> Aggregate
+    #
+    # Add the given entry or URI to the list of aggregates in this manifest.
+    # <tt>Errno:ENOENT</tt> is raised if the entry does not exist.
+    #
+    # The Aggregate object added to the Research Object is returned.
+    def add_aggregate(entry)
+      unless entry.instance_of?(Aggregate)
+        unless Util.is_absolute_uri?(entry)
+          raise Errno::ENOENT if container.find_entry(entry).nil?
+        end
+
+        entry = Aggregate.new(entry)
+      end
+
+      @edited = true
+      structure[:aggregates] << entry
+      entry
+    end
+
+    # :call-seq:
+    #   remove_aggregate(filename)
+    #   remove_aggregate(uri)
+    #   remove_aggregate(Aggregate)
+    #
+    # Remove (unregister) an aggregate from this Research Object. If a
+    # filename is supplied then the file is no longer aggregated, but it is
+    # not deleted from the bundle by this method.
+    #
+    # Any annotations with the removed aggregate as their target are also
+    # removed from the RO.
+    def remove_aggregate(object)
+      removed = nil
+
+      if object.is_a?(Aggregate)
+        removed = structure[:aggregates].delete(object)
+
+        unless removed.nil?
+          removed = removed.file.nil? ? removed.uri : removed.file
+        end
+      else
+        removed = remove_aggregate_by_file_or_uri(object)
+      end
+
+      unless removed.nil?
+        remove_annotation(removed)
+        @edited = true
+      end
+    end
+
+    # :call-seq:
+    #   add_annotation(annotation) -> Annotation
+    #   add_annotation(target, content = nil) -> Annotation
+    #
+    # Add an annotation to this Research Object. An annotation can either be
+    # an already created annotation object, or a pair of values to build a new
+    # annotation object explicitly.
+    #
+    # <tt>Errno:ENOENT</tt> is raised if the target of the annotation is not
+    # an annotatable resource in this RO.
+    #
+    # The Annotation object added to the Research Object is returned.
+    def add_annotation(object, content = nil)
+      if object.instance_of?(Annotation)
+        # If the supplied Annotation object is already registered then it is
+        # the annotation itself we are annotating!
+        if container.annotation?(object)
+          object = Annotation.new(object.annotation_id, content)
+        end
+      else
+        object = Annotation.new(object, content)
+      end
+
+      target = object.target
+      unless container.annotatable?(target)
+        raise Errno::ENOENT,
+          "'#{target}' is not a member of this Research Object or a URI."
+      end
+
+      @edited = true
+      structure[:annotations] << object
+      object
+    end
+
+    # :call-seq:
+    #   remove_annotation(Annotation)
+    #   remove_annotation(target)
+    #   remove_annotation(id)
+    #
+    # Remove (unregister) annotations from this Research Object and return
+    # them. Return +nil+ if the annotation does not exist.
+    #
+    # Any annotation content that is stored in the .ro/annotations directory
+    # is automatically cleaned up when the RO is closed.
+    def remove_annotation(object)
+      if object.is_a?(Annotation)
+        removed = [structure[:annotations].delete(object)].compact
+      else
+        removed = remove_annotation_by_field(object)
+      end
+
+      removed.each do |ann|
+        id = ann.annotation_id
+        remove_annotation(id) unless id.nil?
+      end
+
+      @edited = true unless removed.empty?
+    end
+
+    # :call-seq:
+    #   annotations
+    #
+    # Return a list of all the annotations in this Research Object.
+    def annotations
+      structure[:annotations].dup
+    end
+
+    # :call-seq:
+    #   edited? -> true or false
+    #
+    # Has this manifest been altered in any way?
+    def edited?
+      @edited
+    end
+
+    # :call-seq:
+    #   to_json(options = nil) -> String
+    #
+    # Write this Manifest out as a json string. Takes the same options as
+    # JSON#generate.
+    def to_json(*a)
+      Util.clean_json(structure).to_json(*a)
+    end
+
+    protected
+
+    # :call-seq:
+    #   validate -> true or false
+    #
+    # Validate the correctness of the manifest file contents.
+    def validate
+      begin
+        structure
+      rescue JSON::ParserError, ROError
+        return false
+      end
+
+      true
+    end
+
+    private
+
+    # The internal structure of this class cannot be setup at construction
+    # time in the initializer as there is no route to its data on disk at that
+    # point. Once loaded, parts of the structure are converted to local
+    # objects where appropriate.
+    def structure
+      return @structure if @structure
+
+      begin
+        struct ||= JSON.parse(contents, :symbolize_names => true)
+      rescue Errno::ENOENT
+        struct = {}
+      end
+
+      @structure = init_defaults(struct)
+    end
+
+    def init_defaults(struct)
+      init_default_context(struct)
+      init_default_id(struct)
+      init_provenance_defaults(struct)
+      struct[:history] = [*struct.fetch(:history, [])]
+      struct[:aggregates] = [*struct.fetch(:aggregates, [])].map do |agg|
+        Aggregate.new(agg)
+      end
+      struct[:annotations] = [*struct.fetch(:annotations, [])].map do |ann|
+        Annotation.new(ann)
+      end
+
+      struct
+    end
+
+    def init_default_context(struct)
+      context = struct[:@context]
+      if context.nil?
+        @edited = true
+        struct[:@context] = [ DEFAULT_CONTEXT ]
+      else
+        struct[:@context] = [*context]
+      end
+
+      struct
+    end
+
+    def init_default_id(struct)
+      id = struct[:id]
+      if id.nil?
+        @edited = true
+        struct[:id] = DEFAULT_ID
+      end
+
+      struct
+    end
+
+    def remove_aggregate_by_file_or_uri(object)
+      aggregates.each do |agg|
+        if Util.is_absolute_uri?(object)
+          return structure[:aggregates].delete(agg).uri if object == agg.uri
+        else
+          if object == agg.file || object == agg.file_entry
+            return structure[:aggregates].delete(agg).file
+          end
+        end
+      end
+
+      # Return nil if nothing removed.
+      nil
+    end
+
+    def remove_annotation_by_field(object)
+      removed = []
+
+      annotations.each do |ann|
+        if ann.annotation_id == object ||
+          ann.target == object ||
+          ann.content == object
+
+          removed << structure[:annotations].delete(ann)
+        end
+      end
+
+      removed
+    end
+
+  end
+
+end