annotations2triannon 0.1.0

data/lib/annotations2triannon/open_annotation.rb

@@ -0,0 +1,262 @@
+require 'uuid'
+
+module Annotations2triannon
+
+  # class OpenAnnotation < Resource
+  class OpenAnnotation
+
+    OA = RDF::Vocab::OA
+    OA_CONTEXT = 'http://www.w3.org/ns/oa.jsonld'
+    IIIF_CONTEXT = 'http://iiif.io/api/presentation/2/context.json'
+
+    attr_accessor :id
+    attr_accessor :graph # an RDF::Graph
+
+    # instantiate this class
+    # @param graph [RDF::Graph] for an open annotation
+    # @param id [UUID|URI|String] to identify an open annotation
+    def initialize(graph=RDF::Graph.new, id=nil)
+      @@agent ||= Annotations2triannon::AGENT
+      raise TypeError, 'graph must be RDF::Graph instance' unless graph.instance_of? RDF::Graph
+      if graph.empty?
+        # create a new open annotation
+        @graph = graph
+        id.nil? ? @id = get_id : @id = RDF::URI.parse(id)
+        insert_annotation
+      else
+        @graph = graph
+        raise TypeError, 'graph must be an open annotation' unless is_annotation?
+        if id.nil?
+          @id = get_id
+        else
+        end
+      end
+    end
+
+    def get_id
+      return @id unless @id.nil?
+      q = [nil, RDF.type, OA.Annotation]
+      @id = @graph.query(q).collect {|s| s.subject }.first || RDF::URI.parse(UUID.generate)
+    end
+
+    # @return [boolean] true if RDF.type is OA.Annotation, with OA.hasBody and OA.hasTarget
+    def open_annotation?
+      # TODO: check rules for basic open annotation
+      q = RDF::Query.new
+      q << [@id, RDF.type, OA.Annotation]
+      q << [@id, OA.hasBody, :b]
+      q << [@id, OA.hasTarget, :t]
+      @graph.query(q).size > 0
+    end
+
+    def insert_annotation
+      s = [@id, RDF.type, OA.Annotation]
+      @graph.delete(s)
+      @graph.insert(s)
+    end
+
+    # @return [boolean] true if RDF.type is OA.Annotation
+    def is_annotation?
+      q = [@id, RDF.type, OA.Annotation]
+      @graph.query(q).size > 0
+    end
+
+    def insert_hasTarget(target)
+      # TODO: raise ValueError when target is outside hasTarget range?
+      @graph.insert([@id, OA.hasTarget, target])
+    end
+
+    # @return [Array] The hasTarget object(s)
+    def hasTarget
+      q = [nil, OA.hasTarget, nil]
+      @graph.query(q).collect {|s| s.object }
+    end
+
+    def hasTarget?
+      hasTarget.length > 0
+    end
+
+    def insert_hasBody(body)
+      # TODO: raise ValueError when body is outside hasBody range?
+      @graph.insert([@id, OA.hasBody, body])
+    end
+
+    # @return [Array] The hasBody object(s)
+    def hasBody
+      q = [nil, OA.hasBody, nil]
+      @graph.query(q).collect {|s| s.object }
+    end
+
+    def hasBody?
+      hasBody.length > 0
+    end
+
+    def body_contentAsText
+      body_type RDF::CONTENT.ContentAsText
+    end
+
+    def body_contentAsText?
+      body_contentAsText.size > 0
+    end
+
+    # For all bodies that are of type ContentAsText, get the characters as a single String in the returned Array.
+    # @return [Array<String>] body chars as Strings, in an Array (one element for each contentAsText body)
+    def body_contentChars
+      q = RDF::Query.new
+      q << [nil, OA.hasBody, :body]
+      q << [:body, RDF.type, RDF::CONTENT.ContentAsText]
+      q << [:body, RDF::CONTENT.chars, :body_chars]
+      @graph.query(q).collect {|s| s.body_chars.value }
+    end
+
+    def body_semanticTag
+      body_type OA.SemanticTag
+    end
+
+    def body_semanticTag?
+      body_semanticTag.size > 0
+    end
+
+    def body_type(uri=nil)
+      uri = RDF::URI.parse(uri) unless uri.nil?
+      q = RDF::Query.new
+      q << [nil, OA.hasBody, :body]
+      q << [:body, RDF.type, uri]
+      @graph.query(q)
+    end
+
+    # Insert an ?o for [id, OA.motivatedBy, ?o] where ?o is 'motivation'
+    # @param motivation [String|URI] An open annotation motivation
+    def insert_motivatedBy(motivation)
+      # TODO: only accept values allowed by OA.motivationBy range?
+      motivation = RDF::URI.parse(motivation)
+      @graph.insert([@id, OA.motivatedBy, motivation])
+    end
+
+    # Find any matching ?o for ?s OA.motivatedBy ?o where ?o is 'uri'
+    # @param uri [RDF::URI|String|nil] Any object of a motivatedBy predicate
+    # @return [Array] The motivatedBy object(s)
+    def motivatedBy(uri=nil)
+      uri = RDF::URI.parse(uri) unless uri.nil?
+      q = [nil, OA.motivatedBy, uri]
+      @graph.query(q).collect {|s| s.object }
+    end
+
+    # Are there any matching ?o for [?s, OA.motivatedBy, ?o] where ?o is 'uri'
+    # @param uri [RDF::URI|String|nil] Any object of a motivatedBy predicate
+    # @return [boolean] True if the open annotation has any motivatedBy 'uri'
+    def motivatedBy?(uri=nil)
+      motivatedBy(uri).length > 0
+    end
+
+    # Insert [id, OA.motivatedBy, OA.commenting]
+    def insert_motivatedByCommenting
+      insert_motivatedBy OA.commenting
+    end
+
+    # Find all the matching ?s for [?s, OA.motivatedBy, OA.commenting]
+    def motivatedByCommenting
+      q = [nil, OA.motivatedBy, OA.commenting]
+      @graph.query(q).collect {|s| s.subject }
+    end
+
+    # Are there any matching ?s for [?s, OA.motivatedBy, OA.commenting]
+    def motivatedByCommenting?
+      motivatedByCommenting.length > 0
+    end
+
+    # Insert [id, OA.motivatedBy, OA.tagging]
+    def insert_motivatedByTagging
+      insert_motivatedBy OA.tagging
+    end
+
+    # Find all the matching ?s for [?s, OA.motivatedBy, OA.tagging]
+    def motivatedByTagging
+      q = [nil, OA.motivatedBy, OA.tagging]
+      @graph.query(q).collect {|s| s.subject }
+    end
+
+    # Are there any matching ?s for [?s, OA.motivatedBy, OA.tagging]
+    def motivatedByTagging?
+      motivatedByTagging.length > 0
+    end
+
+    def insert_annotatedBy(annotator=nil)
+      @graph.insert([@id, OA.annotatedBy, annotator])
+    end
+
+    # @return [Array<String>|nil] The identity for the annotatedBy object(s)
+    def annotatedBy
+      q = [:s, OA.annotatedBy, :o]
+      @graph.query(q).collect {|s| s.object }
+    end
+
+    # @param uri [RDF::URI|String|nil] Any object of an annotatedBy predicate
+    # @return [boolean] True if the open annotation has any annotatedBy 'uri'
+    def annotatedBy?(uri=nil)
+      uri = RDF::URI.parse(uri) unless uri.nil?
+      q = [nil, OA.annotatedBy, uri]
+      @graph.query(q).size > 0
+    end
+
+    def insert_annotatedAt(datetime=rdf_now)
+      @graph.insert([@id, OA.annotatedAt, datetime])
+    end
+
+    # @return [Array<String>|nil] The datetime from the annotatedAt object(s)
+    def annotatedAt
+      q = [nil, OA.annotatedAt, nil]
+      @graph.query(q).collect {|s| s.object }
+    end
+
+    def rdf_now
+      RDF::Literal.new(Time.now.utc, :datatype => RDF::XSD.dateTime)
+    end
+
+    def provenance
+      # http://www.openannotation.org/spec/core/core.html#Provenance
+      # When adding the agent, ensure it's not there already, also
+      # an open annotation cannot have more than one oa:serializedAt.
+      @graph.delete([nil,nil,@@agent])
+      @graph.delete([nil, OA.serializedAt, nil])
+      @graph << [@id, OA.serializedAt, rdf_now]
+      @graph << [@id, OA.serializedBy, @@agent]
+    end
+
+    # A json-ld representation of the open annotation
+    def as_jsonld
+      provenance
+      JSON::LD::API::fromRDF(@graph)
+    end
+
+    # @param context [String] A JSON-LD context URI
+    # @return json-ld representation of graph with default context
+    def to_jsonld(context=nil)
+      provenance
+      if context.nil?
+        @graph.dump(:jsonld, standard_prefixes: true)
+      else
+        @graph.dump(:jsonld, standard_prefixes: true, context: context)
+      end
+    end
+
+    # @return json-ld representation of graph with IIIF context
+    def to_jsonld_iiif
+      to_jsonld IIIF_CONTEXT
+    end
+
+    # @return json-ld representation of graph with OpenAnnotation context
+    def to_jsonld_oa
+      to_jsonld OA_CONTEXT
+    end
+
+    # A turtle string representation of the open annotation
+    def to_ttl
+      provenance
+      @graph.dump(:ttl, standard_prefixes: true)
+    end
+
+  end
+
+end
+

data/lib/annotations2triannon/open_annotation_harvest.rb

@@ -0,0 +1,37 @@
+require 'rdf'
+require 'rdf-vocab'
+
+# Module designed to be a mixin for manifest and annotation list.
+module OpenAnnotationHarvest
+
+  # @param rdf [RDF::Graph] a graph to search for RDF::Vocab::OA.Annotation
+  # @return [Array<RDF::Graph>] for graphs of type RDF::Vocab::OA.Annotation
+  def collect_open_annotations(rdf)
+    oa_graphs = []
+    q = [nil, RDF.type, RDF::Vocab::OA.Annotation]
+    rdf.query(q).each_subject do |subject|
+      g = RDF::Graph.new
+      rdf.query([subject, nil, nil]) do |s,p,o|
+        g << [s,p,o]
+        g << rdf_expand_blank_nodes(o) if o.node?
+      end
+      oa_graphs << g
+    end
+    oa_graphs
+  end
+
+  # @param object [RDF::Node] An RDF blank node
+  # @return [RDF::Graph] graph of recursive resolution for a blank node
+  def rdf_expand_blank_nodes(object)
+    g = RDF::Graph.new
+    if object.node?
+      rdf.query([object, nil, nil]) do |s,p,o|
+        g << [s,p,o]
+        g << rdf_expand_blank_nodes(o) if o.node?
+      end
+    end
+    g
+  end
+
+end
+

data/lib/annotations2triannon/resource.rb

@@ -0,0 +1,264 @@
+
+module Annotations2triannon
+
+  class Resource
+
+    @@config = nil
+
+    def self.http_head_request(url)
+      uri = nil
+      begin
+        response = RestClient.head(url)
+        uri = response.args[:url]
+      rescue
+        @@config.logger.error "RestClient.head failed for #{url}"
+        begin
+          response = RestClient.get(url)
+          uri = response.args[:url]
+        rescue
+          @@config.logger.error "RestClient.get failed for #{url}"
+        end
+      end
+      uri
+    end
+
+    attr_accessor :iri
+
+    def initialize(uri=nil)
+      @@agent ||= Annotations2triannon::AGENT
+      @@config ||= Annotations2triannon.configuration
+      if uri =~ /\A#{URI::regexp}\z/
+        uri = Addressable::URI.parse(uri.to_s) rescue nil
+      end
+      raise 'invalid uri' unless uri.instance_of? Addressable::URI
+      @iri = uri
+    end
+
+    def id
+      @iri.basename
+    end
+
+    def iri_type?(type)
+      iri_types.include? RDF::URI.parse(type)
+    end
+
+    def iri_types
+      q = [rdf_uri, RDF.type, :o]
+      rdf.query(q).collect {|s| s.object }
+    end
+
+    # Assert PROV.SoftwareAgent and PROV.generatedAtTime
+    def provenance
+      s = [rdf_uri, RDF::PROV.SoftwareAgent, @@agent]
+      rdf.insert(s)
+      s = [rdf_uri, RDF::PROV.generatedAtTime, rdf_now]
+      rdf.insert(s)
+    end
+
+    # This method is often overloaded in subclasses because
+    # RDF services use variations in the URL 'extension' patterns; e.g.
+    # see Loc#rdf and Viaf#rdf
+    def rdf
+      # TODO: try to retrieve the rdf from a local triple store
+      # TODO: if local triple store fails, try remote source(s)
+      # TODO: if retrieved from a remote source, save the rdf to a local triple store
+      return @rdf unless @rdf.nil?
+      uri4rdf = @iri.to_s
+      tries = 0
+      begin
+        tries += 1
+        @rdf = RDF::Graph.load(uri4rdf)
+      rescue
+        sleep 1*tries
+        retry if tries < 3
+        binding.pry if @@config.debug
+        @@config.logger.error("Failed to retrieve RDF for #{uri4rdf}")
+        @rdf = nil
+      end
+    end
+
+    # RDF query to find all objects of a predicate
+    # @param predicate [RDF::URI] An RDF predicate, the ?p in ?s ?p ?o
+    # @return [Array] The objects of predicate, the ?o in ?s ?p ?o
+    def query_predicate_objects(predicate)
+      q = [:s, predicate, :o]
+      rdf.query(q).collect {|s| s.object }
+    end
+
+    # RDF query to find all subjects with a predicate
+    # @param predicate [RDF::URI] An RDF predicate, the ?p in ?s ?p ?o
+    # @return [Array] The subjects with predicate, the ?s in ?s ?p ?o
+    def query_predicate_subjects(predicate)
+      q = [:s, predicate, :o]
+      rdf.query(q).collect {|s| s.subject }
+    end
+
+    # Regexp search to find an object matching a string, if it belongs to @iri
+    # @param id [String] A string literal used to construct a Regexp
+    # @return [RDF::URI] The first object matching the Regexp
+    def rdf_find_object(id)
+      return nil unless rdf_valid?
+      rdf.each_statement do |s|
+        if s.subject == @iri.to_s
+          return s.object if s.object.to_s =~ Regexp.new(id, Regexp::IGNORECASE)
+        end
+      end
+      nil
+    end
+
+    # Regexp search to find a subject matching a string
+    # @param id [String] A string literal used to construct a Regexp
+    # @return [RDF::URI] The first subject matching the Regexp
+    def rdf_find_subject(id)
+      return nil unless rdf_valid?
+      rdf.each_subject do |s|
+        return s if s.to_s =~ Regexp.new(id, Regexp::IGNORECASE)
+      end
+      nil
+    end
+
+    # @param object [RDF::Node] An RDF blank node
+    # @return [RDF::Graph] graph of recursive resolution for a blank node
+    def rdf_expand_blank_nodes(object)
+      g = RDF::Graph.new
+      if object.node?
+        rdf.query([object, nil, nil]) do |s,p,o|
+          g << [s,p,o]
+          g << rdf_expand_blank_nodes(o) if o.node?
+        end
+      end
+      g
+    end
+
+    # ----
+    # RDF::Graph convenience wrappers
+
+    def rdf_insert(uriS, uriP, uriO)
+      @rdf.insert RDF::Statement(uriS, uriP, uriO)
+    end
+    def rdf_insert_sameAs(uriS, uriO)
+      rdf_insert(uriS, RDF::OWL.sameAs, uriO)
+    end
+    def rdf_insert_seeAlso(uriS, uriO)
+      rdf_insert(uriS, RDF::RDFS.seeAlso, uriO)
+    end
+    def rdf_insert_creator(uriS, uriO)
+      rdf_insert(uriS, RDF::SCHEMA.creator, uriO)
+    end
+    def rdf_insert_contributor(uriS, uriO)
+      rdf_insert(uriS, RDF::SCHEMA.contributor, uriO)
+    end
+    def rdf_insert_editor(uriS, uriO)
+      rdf_insert(uriS, RDF::SCHEMA.editor, uriO)
+    end
+    def rdf_insert_exampleOfWork(uriS, uriO)
+      rdf_insert(uriS, RDF::SCHEMA.exampleOfWork, uriO)
+    end
+    def rdf_insert_foafFocus(uriS, uriO)
+      # http://xmlns.com/foaf/spec/#term_focus
+      # relates SKOS:Concept to a 'real world thing'
+      rdf_insert(uriS, RDF::FOAF.focus, uriO)
+    end
+    def rdf_insert_name(uriS, name)
+      rdf_insert(uriS, RDF::FOAF.name, name) if @@config.use_foaf
+      rdf_insert(uriS, RDF::SCHEMA.name, name) if @@config.use_schema
+    end
+
+    def rdf_now
+      RDF::Literal.new(Time.now.utc, :datatype => RDF::XSD.dateTime)
+    end
+
+    def rdf_uri
+      RDF::URI.new(@iri)
+    end
+
+    # Methods that assert RDF.type
+
+    def rdf_insert_type(uriS, uriO)
+      rdf_insert(uriS, RDF.type, uriO)
+    end
+
+    def rdf_type_agent(uriS)
+      # Note: schema.org has no immediate parent for Person or Organization
+      rdf_insert_type(uriS, RDF::FOAF.Agent) if @@config.use_foaf
+      rdf_insert_type(uriS, RDF::SCHEMA.Thing) if @@config.use_schema
+    end
+
+    def rdf_type_concept(uriS)
+      rdf_insert_type(uriS, RDF::SKOS.Concept)
+    end
+
+    def rdf_type_organization(uriS)
+      rdf_insert_type(uriS, RDF::FOAF.Organization) if @@config.use_foaf
+      rdf_insert_type(uriS, RDF::SCHEMA.Organization) if @@config.use_schema
+    end
+
+    def rdf_type_person(uriS)
+      rdf_insert_type(uriS, RDF::FOAF.Person) if @@config.use_foaf
+      rdf_insert_type(uriS, RDF::SCHEMA.Person) if @@config.use_schema
+    end
+
+    def rdf_valid?
+      iri_types.length > 0
+    end
+
+
+
+    # ---
+    # HTTP methods
+
+    # @param url [String|URI] A URL that can be resolved via HTTP request
+    # @return [String] The URL that resolves, after permanent redirections
+    def resolve_url(url)
+      begin
+        # RestClient does all the response code handling and redirection.
+        url = Resource.http_head_request(url)
+        if url.nil?
+          @@config.logger.warn "#{@iri}\t// #{url}"
+        else
+          @@config.logger.debug "Mapped #{@iri}\t-> #{url}"
+        end
+      rescue
+        binding.pry if @@config.debug
+        @@config.logger.error "unknown http error for #{@iri}"
+        url = nil
+      end
+      url
+    end
+
+    def same_as_org_graph
+      return @same_as_org_graph unless @same_as_org_graph.nil?
+      same_as_url = 'http://sameas.org/rdf?uri=' + URI.encode(@iri.to_s)
+      @same_as_org_graph = RDF::Graph.load(same_as_url)
+    end
+    def same_as_org_query
+      # q = SPARQL.parse("SELECT * WHERE { <#{@iri}> <http://www.w3.org/2002/07/owl#sameAs> ?o }")
+      q = [rdf_uri, RDF::OWL.sameAs, nil]
+      same_as_org_graph.query(q).collect {|s| s.object }
+    end
+
+
+
+    # ---
+    # Transforms or Serialization
+
+    # A json-ld object for the rdf resource
+    def as_jsonld
+      JSON::LD::API::fromRdf(rdf)
+    end
+
+    # A json-ld serialization of the rdf resource
+    def to_jsonld
+      rdf.dump(:jsonld, standard_prefixes: true)
+    end
+
+    # A turtle serialization of the rdf resource
+    def to_ttl
+      rdf.dump(:ttl, standard_prefixes: true)
+    end
+
+  end
+
+end
+
+