ld4l-open_annotation_rdf 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3300bb3c1ed7f05ad15bcc48d3db4027138b986c
+  data.tar.gz: 6d82cae01c405f875e77033a1884633ae1aa9a6b
+SHA512:
+  metadata.gz: b7e45edc10a479132f70c450330643cfc2bda517961cd6a24d3e49df2324624db5e8d7968a1b21afed4a1c9d1b74be6b41b8aec2e8795722989aae47880a3eca
+  data.tar.gz: c0d61fc82b296dd164bbd31fd81184212fc9be9493b65158949ac390e80b816a9ca530b928a05e569751c11de5bd61125836ea5050443d8bda4a99a35bdcacd1

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.idea

data/.ruby-gemset

@@ -0,0 +1 @@
+ld4l-oa-gem_no-rails

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.2

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+gemspec
+
+# GETTING FROM GEMFILE UNTIL ActiveTriples master CODE IS RELEASED (>0.4.0), THEN MOVE THIS BACK TO *.gemspec FILE
+# Use active-triples for handling of triple persistence
+gem 'active-triples', :git => 'git@github.com:ActiveTriples/ActiveTriples.git', :branch => 'master'
+
+# GETTING FROM GEMFILE UNTIL LD4L::FoafRDF GEM IS RELEASED, THEN MOVE TO *.gemspec FILE
+# Use LD4L::FoafRDF Gem
+gem 'ld4l-foaf_rdf', :git => 'git@github.com:ld4l/foaf_rdf.git', :branch => 'master'

data/LICENSE.txt

@@ -0,0 +1,14 @@
+Copyright (c) 2014 Cornell University
+
+##########################################################################
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data/README.md

@@ -0,0 +1,231 @@
+#LD4L::OpenAnnotationRDF
+
+LD4L Open Annotation RDF provides tools for modeling annotations based on the Open Annotation ontology and persisting to a triplestore.
+
+
+## Installation
+
+Temporary get the gem from github until the gem is released publicly.
+
+Add this line to your application's Gemfile:
+
+<!--    gem 'ld4l-open_annotation_rdf' -->
+    gem 'ld4l-open_annotation_rdf', '~> 0.0.3', :git => 'git@github.com:ld4l/open_annotation_rdf.git'
+    
+
+And then execute:
+
+    $ bundle install
+
+<!--
+Or install it yourself as:
+
+    $ gem install ld4l-open_annotation_rdf
+-->
+
+
+## Usage
+
+**Caveat:** This gem is part of the LD4L Project and is being used in that context.  There is no guarantee that the 
+code will work in a usable way outside of its use in LD4L Use Cases.
+
+### Examples
+
+*Setup required for all examples.*
+```
+require 'ld4l/open_annotation_rdf'
+
+# create an in-memory repository
+ActiveTriples::Repositories.add_repository :default, RDF::Repository.new
+
+p = LD4L::FoafRDF::Person.new('p4')
+```
+
+*Example creating a comment annotation.*
+```
+ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new('c10')
+ca.hasTarget = RDF::URI("http://example.org/bibref/br3")
+cb = ca.setComment("This book is a good resource on archery technique.")
+ca.annotatedBy = p
+ca.setAnnotatedAtNow
+ca.persist!
+
+puts ca.dump :ttl
+puts cb.dump :ttl
+```
+
+*Example triples created for a comment annotation.*
+```
+<http://localhost/c10> a <http://www.w3.org/ns/oa#Annotation>;
+   <http://www.w3.org/ns/oa#annotatedAt> "2014-11-26T15:53:49Z";
+   <http://www.w3.org/ns/oa#annotatedBy> <http://localhost/p4>;
+   <http://www.w3.org/ns/oa#hasBody> <http://localhost/9c8c8126-2d31-48be-81d8-3cd4748a3351>;
+   <http://www.w3.org/ns/oa#hasTarget> <http://example.org/bibref/br3>;
+   <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#commenting> .
+
+<http://localhost/9c8c8126-2d31-48be-81d8-3cd4748a3351> a <http://www.w3.org/2011/content#ContentAsText>,
+                                                          <http://purl.org/dc/dcmitype/Text>;
+   <http://purl.org/dc/terms/format> "text/plain";
+   <http://www.w3.org/2011/content#chars> "This book is a good resource on archery technique." .
+```
+
+*Example creating a tag annotation.*
+```
+ta = LD4L::OpenAnnotationRDF::TagAnnotation.new('t10')
+ta.hasTarget = RDF::URI("http://example.org/bibref/br3")
+tb = ta.setTag("archery")
+ta.annotatedBy = p
+ta.setAnnotatedAtNow
+ta.persist!
+
+puts ta.dump :ttl
+puts tb.dump :ttl
+```
+
+*Example triples created for a tag annotation.*
+```
+<http://localhost/t10> a <http://www.w3.org/ns/oa#Annotation>;
+   <http://www.w3.org/ns/oa#annotatedAt> "2014-11-26T15:56:32Z";
+   <http://www.w3.org/ns/oa#annotatedBy> <http://localhost/p4>;
+   <http://www.w3.org/ns/oa#hasBody> <http://localhost/88db4b38-8b99-4939-b376-1392019aa30c>;
+   <http://www.w3.org/ns/oa#hasTarget> <http://example.org/bibref/br3>;
+   <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#tagging> .
+
+<http://localhost/88db4b38-8b99-4939-b376-1392019aa30c> a <http://www.w3.org/ns/oa#Tag>,
+                                                          <http://www.w3.org/2011/content#ContentAsText>;
+   <http://www.w3.org/2011/content#chars> "archery" .
+```
+
+*Example creating a semantic tag annotation.*
+```
+sta = LD4L::OpenAnnotationRDF::SemanticTagAnnotation.new('st10')
+sta.hasTarget = RDF::URI("http://example.org/bibref/br3")
+stb = sta.setTerm(RDF::URI("http://example.org/term/engineering"))
+sta.annotatedBy = p
+sta.setAnnotatedAtNow
+sta.persist!
+
+puts sta.dump :ttl
+puts stb.dump :ttl
+```
+
+*Example triples created for a semantic tag annotation.*
+```
+<http://localhost/st10> a <http://www.w3.org/ns/oa#Annotation>;
+   <http://www.w3.org/ns/oa#annotatedAt> "2014-11-26T15:59:01Z";
+   <http://www.w3.org/ns/oa#annotatedBy> <http://localhost/p4>;
+   <http://www.w3.org/ns/oa#hasBody> <http://example.org/term/engineering>;
+   <http://www.w3.org/ns/oa#hasTarget> <http://example.org/bibref/br3>;
+   <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#tagging> .
+
+<http://example.org/term/engineering> a <http://www.w3.org/ns/oa#SemanticTag> .
+```
+
+
+### Configurations
+
+* base_uri - base URI used when new resources are created (default="http://localhost/")
+* localname_minter - minter function to use for creating unique local names (default=nil which uses default minter in active_triples-local_name gem)
+* unique_tags - if true, re-use existing TagBodies only creating a new TagBody if one doesn't exist with the tag value being set; otherwise, if false, create new TagBody when tag value is updated (default=true)
+
+*Setup for all examples.*
+
+* Restart your interactive session (e.g. irb, pry).
+* Use the Setup for all examples in main Examples section above.
+
+#### Example usage using **configured base_uri** and default localname_minter.
+```
+LD4L::OpenAnnotationRDF.reset
+LD4L::OpenAnnotationRDF.configure do |config|
+  config.base_uri = "http://example.org/"
+end
+
+ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new(ActiveTriples::LocalName::Minter.generate_local_name(
+              LD4L::OpenAnnotationRDF::CommentAnnotation, 10, {:prefix=>'ca'} ))
+
+puts ca.dump :ttl
+
+ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new(ActiveTriples::LocalName::Minter.generate_local_name(
+              LD4L::OpenAnnotationRDF::CommentAnnotation, 10, {:prefix=>'ca'},
+              &LD4L::OpenAnnotationRDF.configuration.localname_minter ))
+
+puts ca.dump :ttl
+```
+NOTE: If base_uri is not used, you need to restart your interactive environment (e.g. irb, pry).  Once the 
+  CommentAnnotation class is instantiated the first time, the base_uri for the class is set.  If you ran
+  through the main Examples, the base_uri was set to the default base_uri.
+
+
+**Example triples created for a person with configured base_uri and default minter.**
+```
+<http://example.org/ca45c9c85b-25af-4c52-96a4-cf0d8b70a768> a <http://www.w3.org/ns/oa#Annotation>;
+   <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#commenting> .
+```
+
+#### Example usage using **configured base_uri** and **configured localname_minter**.
+```
+LD4L::OpenAnnotationRDF.configure do |config|
+  config.base_uri = "http://example.org/"
+  config.localname_minter = lambda { |prefix=""| prefix+'_configured_'+SecureRandom.uuid }
+end
+
+ca = LD4L::OpenAnnotationRDF::CommentAnnotation.new(ActiveTriples::LocalName::Minter.generate_local_name(
+              LD4L::OpenAnnotationRDF::CommentAnnotation, 10, 'ca',
+              &LD4L::OpenAnnotationRDF.configuration.localname_minter ))
+
+puts ca.dump :ttl
+```
+NOTE: If base_uri is not used, you need to restart your interactive environment (e.g. irb, pry).  Once the 
+  CommentAnnotation class is instantiated the first time, the base_uri for the class is set.  If you ran
+  through the main Examples, the base_uri was set to the default base_uri.
+
+
+**Example triples created for a person with configured base_uri and configured minter.**
+```
+<http://example.org/ca_configured_6498ba05-8b21-4e8c-b9d4-a6d5d2180966> a <http://www.w3.org/ns/oa#Annotation>;
+   <http://www.w3.org/ns/oa#motivatedBy> <http://www.w3.org/ns/oa#commenting> .
+```
+
+#### Example configuring unique_tags
+```
+# Any of these are valid and will change the configuration of unique_tags
+LD4L::OpenAnnotationRDF.configuration.unique_tags = true
+LD4L::OpenAnnotationRDF.configuration.unique_tags = false
+LD4L::OpenAnnotationRDF.configuration.reset_unique_tags
+```
+
+### Models
+
+The LD4L::OpenAnnotationRDF gem provides model definitions using the 
+[ActiveTriples](https://github.com/ActiveTriples/ActiveTriples) framework extension of 
+[ruby-rdf/rdf](https://github.com/ruby-rdf/rdf).  The following models are provided:
+
+1. LD4L::OpenAnnotationRDF::Annotation - Implements an open annotation.
+1. LD4L::OpenAnnotationRDF::CommentAnnotation - Extends Annotation to implement a comment annotation of free-form text.
+1. LD4L::OpenAnnotationRDF::CommentBody - Implements a body holding free-form text.
+1. LD4L::OpenAnnotationRDF::TagAnnotation - Extends Annotation to implement a tag annotation of user specified short phrase tag.
+1. LD4L::OpenAnnotationRDF::TagBody - Implements a body holding the short phrase tag.
+1. LD4L::OpenAnnotationRDF::SemanticTagAnnotation - Extends Annotation to implement a semantic tag annotation with values limited to a controlled vocabulary.
+1. LD4L::OpenAnnotationRDF::SemanticTagBody - Implements a body with rdf_subject equal to the URI of the controlled vocabulary term
+.
+
+### Ontologies
+
+The listed ontologies are used to represent the primary metadata about the annotations.
+Other ontologies may also be used that aren't listed.
+ 
+* [OA](http://www.openannotation.org/spec/core/)
+* [FOAF](http://xmlns.com/foaf/spec/)
+* [RDF](http://www.w3.org/TR/rdf-syntax-grammar/)
+* [Dublin Core (DC)](http://dublincore.org/documents/dces/)
+* [Dublin Core Terms (DCTERMS)](http://dublincore.org/documents/dcmi-terms/)
+
+
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/ld4l-open_annotation_rdf/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/ld4l-open_annotation_rdf.gemspec

@@ -0,0 +1,46 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ld4l/open_annotation_rdf/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ld4l-open_annotation_rdf"
+  spec.version       = LD4L::OpenAnnotationRDF::VERSION
+  spec.authors       = ["E. Lynette Rayle"]
+  spec.email         = ["elr37@cornell.edu"]
+  spec.platform      = Gem::Platform::RUBY
+  spec.summary       = %q{OpenAnnotation RDF models.}
+  spec.description   = %q{LD4L Open Annotation RDF provides tools for modeling a annotations based on the Open Annotation ontology and persisting to a triplestore.}
+  spec.homepage      = "https://github.com/ld4l/open_annotation_rdf"
+  spec.license       = "APACHE2"
+  spec.required_ruby_version     = '>= 2.1.2'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  # spec.test_files    = `git ls-files -- {spec}/*`.split("\n")               # FROM ActiveTriples gemspec file
+  # spec.require_paths = ["lib"]                                              # NOT IN ActiveTriples gemspec file
+
+#  spec.add_dependency('ffi', '~> 1.9.5')
+  spec.add_dependency('rdf', '~> 1.1')
+
+# GETTING FROM GEMFILE UNTIL ActiveTriples master CODE IS RELEASED (>0.4.0), THEN MOVE THIS BACK TO *.gemspec FILE
+#  spec.add_dependency('active-triples', '~> 0.4')
+
+  spec.add_dependency('active_triples-local_name', '~> 0.1')
+
+# GETTING FROM GEMFILE UNTIL ld4l-foaf_rdf GEM IS RELEASED
+# spec.add_dependency('ld4l-foaf_rdf', '~> 0.0')
+
+  spec.add_development_dependency('pry')
+  spec.add_development_dependency('pry-byebug')
+  spec.add_development_dependency('rdoc')
+  spec.add_development_dependency('rspec')
+  spec.add_development_dependency('guard-rspec')
+  spec.add_development_dependency('webmock')
+
+  spec.extra_rdoc_files = [
+      "LICENSE.txt",
+      "README.md"
+  ]
+end
+

data/lib/ld4l/open_annotation_rdf.rb

@@ -0,0 +1,66 @@
+require 'rdf'
+require 'active_triples'
+require 'active_triples/local_name'
+require	'linkeddata'
+require 'ld4l/foaf_rdf'
+require 'ld4l/open_annotation_rdf/version'
+require 'ld4l/open_annotation_rdf/vocab/oa'
+require 'ld4l/open_annotation_rdf/vocab/cnt'
+require 'ld4l/open_annotation_rdf/vocab/dctypes'
+
+
+module LD4L
+  module OpenAnnotationRDF
+
+    # Methods for configuring the GEM
+    class << self
+      attr_accessor :configuration
+    end
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.reset
+      @configuration = Configuration.new
+    end
+
+    def self.configure
+      yield(configuration)
+    end
+
+
+    # RDF vocabularies
+    autoload :OA,                    'ld4l/open_annotation_rdf/vocab/oa'
+    autoload :CNT,                   'ld4l/open_annotation_rdf/vocab/cnt'
+    autoload :DCTYPES,               'ld4l/open_annotation_rdf/vocab/dctypes'
+
+
+    # autoload classes
+    autoload :Configuration,         'ld4l/open_annotation_rdf/configuration'
+    autoload :Annotation,            'ld4l/open_annotation_rdf/annotation'
+    autoload :CommentAnnotation,     'ld4l/open_annotation_rdf/comment_annotation'
+    autoload :CommentBody,           'ld4l/open_annotation_rdf/comment_body'
+    autoload :TagAnnotation,         'ld4l/open_annotation_rdf/tag_annotation'
+    autoload :TagBody,               'ld4l/open_annotation_rdf/tag_body'
+    autoload :SemanticTagAnnotation, 'ld4l/open_annotation_rdf/semantic_tag_annotation'
+    autoload :SemanticTagBody,       'ld4l/open_annotation_rdf/semantic_tag_body'
+
+    def self.class_from_string(class_name, container_class=Kernel)
+      container_class = container_class.name if container_class.is_a? Module
+      container_parts = container_class.split('::')
+      (container_parts + class_name.split('::')).flatten.inject(Kernel) do |mod, class_name|
+        if mod == Kernel
+          Object.const_get(class_name)
+        elsif mod.const_defined? class_name.to_sym
+          mod.const_get(class_name)
+        else
+          container_parts.pop
+          class_from_string(class_name, container_parts.join('::'))
+        end
+      end
+    end
+
+  end
+end
+

data/lib/ld4l/open_annotation_rdf/annotation.rb

@@ -0,0 +1,82 @@
+module LD4L
+  module OpenAnnotationRDF
+    class Annotation < ActiveTriples::Resource
+
+      class << self; attr_reader :localname_prefix end
+      @localname_prefix="oa"
+
+      @body = nil
+
+      configure :type => RDFVocabularies::OA.Annotation,
+                :base_uri => LD4L::OpenAnnotationRDF.configuration.base_uri,
+                :repository => :default
+
+      property :hasTarget,   :predicate => RDFVocabularies::OA.hasTarget    # :type => URI
+      property :hasBody,     :predicate => RDFVocabularies::OA.hasBody
+      property :annotatedBy, :predicate => RDFVocabularies::OA.annotatedBy, :class_name => LD4L::FoafRDF::Person
+      property :annotatedAt, :predicate => RDFVocabularies::OA.annotatedAt  # :type => xsd:dateTime    # the time Annotation was created
+      property :motivatedBy, :predicate => RDFVocabularies::OA.motivatedBy  # comes from RDFVocabularies::OA ontology
+
+      def self.resume(*args)
+        return nil      unless args.kind_of?(Array) && args.size > 0 && args.first.kind_of?(RDF::URI)
+
+        rdf_subject = args.first
+        a = new(rdf_subject)
+
+        # get motivatedBy
+        m = a.get_values(:motivatedBy)
+        return a    unless m.kind_of?(Array) && m.size > 0 && m.first.kind_of?(ActiveTriples::Resource)
+
+        # motivatedBy is set
+        m_uri = m.first.rdf_subject
+
+        # currently only support commenting and tagging
+        return LD4L::OpenAnnotationRDF::CommentAnnotation.new(rdf_subject) if m_uri == RDFVocabularies::OA.commenting
+        return a                                                       unless m_uri == RDFVocabularies::OA.tagging
+
+        # Tagging can be TagAnnotation or SemanticTagAnnotation.  Only way to tell is by checking type of body.
+        sta = LD4L::OpenAnnotationRDF::SemanticTagAnnotation.new(rdf_subject)
+        stb = sta.getBody
+        return sta                                           if stb.type.include?(RDFVocabularies::OA.SemanticTag)
+
+        ta = LD4L::OpenAnnotationRDF::TagAnnotation.new(rdf_subject)
+        tb = ta.getBody
+        return ta                                            if tb.type.include?(RDFVocabularies::OA.Tag)
+
+        # can't match to a known annotation type, so return as generic annotation
+        return a
+      end
+
+      ##
+      # Get the <tt>ActiveTriples::Resource</tt> instance holding the body of this annotation.
+      #
+      # @param [String] tag value
+      #
+      # @return instance of an annotation body if one is set; otherwise, nil
+      def getBody
+        @body
+      end
+
+      ##
+      # Set annotatedAt property to now.
+      #
+      # @return the value of annotatedAt property
+      def setAnnotatedAtNow
+        set_value(:annotatedAt, Time.now.utc.iso8601(0))
+      end
+
+      ##
+      # Save all annotation and annotation body triples to the triple store.
+      #
+      # @return true if annotation successfully persisted; otherwise, false
+      #
+      # @todo What to return if annotation persists fine, but body fails to persist?
+      def persist!
+        persisted = super                                               # persist annotation
+        body_persisted = persisted && @body ? @body.persist! : false    # persist body
+        persisted
+      end
+    end
+  end
+end
+