ld4l-open_annotation_rdf 0.0.4

data/lib/ld4l/open_annotation_rdf/comment_annotation.rb

@@ -0,0 +1,47 @@
+module LD4L
+  module OpenAnnotationRDF
+    class CommentAnnotation < LD4L::OpenAnnotationRDF::Annotation
+
+      @localname_prefix="ca"
+
+      property :hasBody, :predicate => RDFVocabularies::OA.hasBody, :class_name => LD4L::OpenAnnotationRDF::CommentBody
+
+
+      ##
+      # Create a comment annotation body and set the hasBody property to it.
+      #
+      # @param [String]
+      #
+      # @return instance of SemanticTagBody
+      def setComment(comment)
+        @body = LD4L::OpenAnnotationRDF::CommentBody.new(
+            ActiveTriples::LocalName::Minter.generate_local_name(
+                LD4L::OpenAnnotationRDF::CommentBody, 10, @localname_prefix,
+                LD4L::OpenAnnotationRDF.configuration.localname_minter ))
+        @body.content = comment
+        @body.format  = "text/plain"
+        set_value(:hasBody, @body)
+        @body
+      end
+
+      ##
+      # Special processing for new and resumed CommentAnnotations
+      #
+      def initialize(*args)
+        super(*args)
+
+        # set motivatedBy
+        m = get_values(:motivatedBy)
+        set_value(:motivatedBy, RDFVocabularies::OA.commenting) unless m.kind_of?(Array) && m.size > 0
+
+        # resume CommentBody if it exists
+        comment_uri = get_values(:hasBody).first
+        if( comment_uri )
+          comment_uri = comment_uri.rdf_subject  if comment_uri.kind_of?(ActiveTriples::Resource)
+          @body  = LD4L::OpenAnnotationRDF::CommentBody.new(comment_uri)
+        end
+      end
+    end
+  end
+end
+

data/lib/ld4l/open_annotation_rdf/comment_body.rb

@@ -0,0 +1,24 @@
+module LD4L
+  module OpenAnnotationRDF
+    class CommentBody < ActiveTriples::Resource
+
+      class << self; attr_reader :localname_prefix end
+      @localname_prefix="cb"
+
+      configure :type => RDFVocabularies::CNT.ContentAsText,
+                :base_uri => LD4L::OpenAnnotationRDF.configuration.base_uri,
+                :repository => :default
+
+      property :content, :predicate => RDFVocabularies::CNT.chars  # :type => XSD.string
+      property :format,  :predicate => RDF::DC.format              # :type => XSD.string
+
+      def initialize(*args)
+        super(*args)
+
+        t = get_values(:type)
+        t << RDFVocabularies::DCTYPES.Text
+        set_value(:type,t)
+      end
+    end
+  end
+end

data/lib/ld4l/open_annotation_rdf/configuration.rb

@@ -0,0 +1,127 @@
+module LD4L
+  module OpenAnnotationRDF
+
+    # Used by LD4L::OpenAnnotationRDF class to configure...
+    # * base_uri
+    # * local_minter
+    # * unique_tags
+    #
+    # @example Configure all configurable properties
+    #   LD4L::OpenAnnotationRDF.configure do |config|
+    #     config.base_uri         = "http://www.example.org/annotations/"
+    #     config.localname_minter = lambda { |prefix=""| prefix+SecureRandom.uuid }
+    #     config.unique_tags      = true
+    #   end
+    #
+    # @example Usage of base uri and local name
+    #   # uri = base_uri + localname"
+    #   annotation = LD4L::OpenAnnotationRDF::CommentAnnotation.new(
+    #     ActiveTriples::LocalName::Minter.generate_local_name(
+    #         LD4L::OpenAnnotationRDF::CommentBody, 10, 'a',
+    #         LD4L::OpenAnnotationRDF.configuration.localname_minter ))
+    #   annotation.rdf_subject
+    #   # => "http://www.example.org/annotations/a9f85752c-9c2c-4a65-997a-68482895a656"
+    #
+    # @note Use LD4L::OpenAnnotationRDF.configure to call the methods in this class.  See 'Configure all configurable
+    #   properties' example for most common approach to configuration.
+    class Configuration
+
+      ##
+      # @overload base_uri
+      #   Get the base_uri to be used when generating rdf_subjects for new objects.  See example configuration and usage in class documentation examples.
+      #   @return the configured base_uri
+      # @overload base_uri=(new_base_uri)
+      #   Set the base_uri to be used when generating rdf_subjects for new objects.  See example configuration and usage in class documentation examples.
+      #   @param [String] new value for the base_uri
+      #   @note base_uri will only take effect when a model class is first created.  Once the model class is created, the base_uri is bound to the class.
+      attr_reader :base_uri
+
+      ##
+      # @overload localname_minter
+      #   Get the localname_minter to be used when generating rdf_subjects for new objects.  See example configuration and usage in class documentation examples.
+      #   @return the configured localname_minter
+      # @overload localname_minter=(new_localname_minter)
+      #   Set the localname_minter to be used when generating rdf_subjects for new objects.  See example configuration and usage in class documentation examples.
+      #   @param [String] new value for the localname_minter
+      attr_reader :localname_minter
+
+      ##
+      # @overload unique_tags
+      #   Get whether the GEM should enforce uniqueness of user generated tags when using
+      #   the TagAnnotation::setTag method.  See example configuration and usage in class documentation examples.
+      #   @return the configured unique_tags
+      # @overload unique_tags=(new_unique_tags)
+      #   Set whether the GEM should enforce uniqueness of user generated tags when using
+      #   the TagAnnotation::setTag method.
+      #   @param [Boolean] new value for the unique_tags
+      #
+      #     true - enforce uniqueness (default)
+      #       - annotations share TagBodys
+      #       - setTag method looks for an existing TagBody with the tag value and reuses the existing TagBody
+      #       - setTag to change a tag's value will create/reuse a different TagBody for the new tag value
+      #     false - do not enforce uniqueness
+      #       - annotation owns its TagBody
+      #       - setTag first time call creates a TagBody with the tag value
+      #       - setTag to change the tag's value will modify the tag value in this annotation's TagBody
+      attr_reader :unique_tags
+
+      def self.default_base_uri
+        @default_base_uri = "http://localhost/".freeze
+      end
+      private_class_method :default_base_uri
+
+      def self.default_localname_minter
+        # by setting to nil, it will use the default minter in the minter gem
+        @default_localname_minter = nil
+      end
+      private_class_method :default_localname_minter
+
+      def self.default_unique_tags
+        @default_unique_tags = true
+      end
+      private_class_method :default_unique_tags
+
+      def initialize
+        @base_uri         = self.class.send(:default_base_uri)
+        @localname_minter = self.class.send(:default_localname_minter)
+        @unique_tags      = self.class.send(:default_unique_tags)
+      end
+
+      def base_uri=(new_base_uri)
+        @base_uri = new_base_uri
+      end
+
+      ##
+      # Reset the base_uri to be used when generating rdf_subject for new objects back to the default configuration.
+      #
+      def reset_base_uri
+        @base_uri = self.class.send(:default_base_uri)
+      end
+
+      def localname_minter=(new_minter)
+        @localname_minter = new_minter
+      end
+
+      ##
+      # Reset the minter to be used to generate the local name portion of the rdf_subject for new objects to the
+      # default minter.
+      #
+      def reset_localname_minter
+        @localname_minter = self.class.send(:default_localname_minter)
+      end
+
+      def unique_tags=(new_unique_indicator)
+        @unique_tags = new_unique_indicator
+      end
+
+      ##
+      # Reset whether the GEM should enforce uniqueness of user generated tags, when using
+      # the TagAnnotation::setTag method, to the default configuration (true).
+      #
+      # @see unique_tags=
+      def reset_unique_tags
+        @unique_tags = self.class.send(:default_unique_tags)
+      end
+    end
+  end
+end

data/lib/ld4l/open_annotation_rdf/semantic_tag_annotation.rb

@@ -0,0 +1,66 @@
+module LD4L
+  module OpenAnnotationRDF
+    class SemanticTagAnnotation < LD4L::OpenAnnotationRDF::Annotation
+
+      @localname_prefix = "sta"
+
+      # USAGE: Use setTerm to set the hasBody property to be the URI of the controlled vocabulary term that
+      #        is the annotation.
+
+      # TODO: Should a semantic tag be destroyed when the last annotation referencing the term is destroyed?
+
+      ##
+      # Set the hasBody property to the URI of the controlled vocabulary term that is the annotation and
+      # create the semantic tag body instance identifying the term as a semantic tag annotation.
+      #
+      # @param [String] controlled vocabulary uri for the term
+      #
+      # @return instance of SemanticTagBody
+      def setTerm(term_uri)
+        raise ArgumentError, 'Argument must be a uri string or an instance of RDF::URI'  unless
+            term_uri.kind_of?(String) && term_uri.size > 0 || term_uri.kind_of?(RDF::URI)
+
+        # return existing body if term is unchanged
+        old_term_uri = @body ? @body.rdf_subject.to_s : nil
+        term_uri = RDF::URI(term_uri) unless term_uri.kind_of?(RDF::URI)
+        return @body if old_term_uri && old_term_uri == term_uri.to_s
+
+        @body = LD4L::OpenAnnotationRDF::SemanticTagBody.new(term_uri)
+        set_value(:hasBody, @body)
+        @body
+      end
+
+      ##
+      # Special processing for new and resumed SemanticTagAnnotations
+      #
+      def initialize(*args)
+        super(*args)
+
+        # set motivatedBy
+        m = get_values(:motivatedBy)
+        set_value(:motivatedBy, RDFVocabularies::OA.tagging) unless m.kind_of?(Array) && m.size > 0
+
+        # resume SemanticTagBody if it exists
+        term_uri = get_values(:hasBody).first
+        if( term_uri )
+          term_uri = term_uri.rdf_subject  if term_uri.kind_of?(ActiveTriples::Resource)
+          @body  = LD4L::OpenAnnotationRDF::SemanticTagBody.new(term_uri)
+        end
+      end
+
+      def destroy
+        # TODO Determine behavior of destroy
+        #   Behaviour Options
+        #     * Always destroy SemanticTagAnnotation
+        #     * Handling of SemanticTagBody
+        #     **  If SemanticTagBody is used only by this SemanticTagAnnotation, destroy it.
+        #     **  Otherwise, do not destroy it.
+        # TODO Write tests for this behaviour.
+        # TODO Write code here to enforce.
+        super
+      end
+    end
+  end
+end
+
+

data/lib/ld4l/open_annotation_rdf/semantic_tag_body.rb

@@ -0,0 +1,70 @@
+module LD4L
+  module OpenAnnotationRDF
+    class SemanticTagBody < ActiveTriples::Resource
+
+      class << self; attr_reader :localname_prefix end
+      @localname_prefix="stb"
+
+      # USAGE: When creating a semantic tag body, use the URI of the controlled vocabulary term as the RDF Subject URI
+      #        for an instance of this class.
+
+      configure :type => RDFVocabularies::OA.SemanticTag,
+                :base_uri => LD4L::OpenAnnotationRDF.configuration.base_uri,
+                :repository => :default
+
+      ##
+      # Get a list of annotations using a term.
+      #
+      # @param [String] controlled vocabulary uri for the term
+      #
+      # @return array of annotation URIs
+      #
+      # NOTE: This method returns only persisted annotations.
+      def self::annotations_using( term_uri )
+        raise ArgumentError, 'Argument must be a uri string or an instance of RDF::URI'  unless
+            term_uri.kind_of?(String) && term_uri.size > 0 || term_uri.kind_of?(RDF::URI)
+
+        term_uri = RDF::URI(term_uri) unless term_uri.kind_of?(RDF::URI)
+
+        # find usage by Annotations
+        graph = ActiveTriples::Repositories.repositories[repository]
+        query = RDF::Query.new({
+                                   :annotation => {
+                                       RDF.type =>  RDFVocabularies::OA.Annotation,
+                                       RDFVocabularies::OA.hasBody => term_uri,
+                                   }
+                               })
+        annotations = []
+        results = query.execute(graph)
+        results.each { |r| annotations << r.to_hash[:annotation] }
+        annotations
+      end
+
+
+      ##
+      # Destroy the SemanticTagBody only if the term is not used by another SemanticAnnotation
+      #
+      # @param [String] controlled vocabulary uri for the term
+      #
+      # @return true if destroyed; otherwise, false if used by other annotations
+      #
+      # NOTE: Use this method after changing the term AND persisting the annotation on which the term was changed.
+      def self::destroy_if_unused( term_uri )
+        raise ArgumentError, 'Argument must be a uri string or an instance of RDF::URI'  unless
+            term_uri.kind_of?(String) && term_uri.size > 0 || term_uri.kind_of?(RDF::URI)
+
+        term_uri = RDF::URI(term_uri) unless term_uri.kind_of?(RDF::URI)
+
+        # find usage by Annotations
+        annotations = self::annotations_using( term_uri )
+        destroyed = false
+        if( annotations.empty? )
+          stb = LD4L::OpenAnnotationRDF::SemanticTagBody.new(term_uri)
+          destroyed = stb.destroy!
+        end
+        destroyed
+      end
+
+    end
+  end
+end

data/lib/ld4l/open_annotation_rdf/tag_annotation.rb

@@ -0,0 +1,98 @@
+module LD4L
+  module OpenAnnotationRDF
+    class TagAnnotation < LD4L::OpenAnnotationRDF::Annotation
+
+      @localname_prefix="ta"
+
+      property :hasBody,  :predicate => RDFVocabularies::OA.hasBody,   :class_name => LD4L::OpenAnnotationRDF::TagBody
+
+      # TODO: Should a tag be destroyed when the last annotation referencing the tag is destroyed?
+
+      ##
+      # Set the hasBody property to the URI of the one and only TagBody holding the tag value. Create a new TagBody
+      # if one doesn't exist with this value.
+      #
+      # @param [String] tag value
+      #
+      # @return instance of TagBody
+      def setTag(tag)
+        raise ArgumentError, 'Argument must be a string with at least one character'  unless tag.kind_of?(String) && tag.size > 0
+
+        # return existing body if tag value is unchanged
+        old_tag = @body ? @body.tag : nil
+        return @body if old_tag && old_tag.include?(tag)
+
+        if LD4L::OpenAnnotationRDF.configuration.unique_tags
+          # when unique_tags = true, try to find an existing TagBody with the tag value before creating a new TagBody
+          # TODO Determine behavior of setTag when unique_tags=true
+          #   Behaviour Options:
+          #     * Look for an existing TagBody with this value.
+          #     **  If none found, create a new TagBody.
+          #     **  If one found, set @body to this TagBody
+          #     **  If multiple found, use the first one found
+          #           ### the same one may not be the first one found each time the query executes
+          @body = LD4L::OpenAnnotationRDF.configuration.unique_tags ? LD4L::OpenAnnotationRDF::TagBody.fetch_by_tag_value(tag) : nil
+          if @body == nil
+            @body = LD4L::OpenAnnotationRDF::TagBody.new(
+                ActiveTriples::LocalName::Minter.generate_local_name(
+                    LD4L::OpenAnnotationRDF::TagBody, 10, @localname_prefix,
+                    LD4L::OpenAnnotationRDF.configuration.localname_minter ))
+            @body.tag = tag
+          end
+        else
+          # when unique_tags = false, ???  (see TODO)
+          # TODO Determine behavior of setTag when unique_tags=false
+          #   Behaviour Options:
+          #     * If this TagAnnotation does not have a TagBody (@body) set, then create a new TagBody.
+          #     * If this TagBody is used only by this TagAnnotation, then change the value in the TagBody.
+          #     * If this TagBody is used by multiple TagAnnotations,
+          #     **  EITHER change the value in the TagBody which changes it for all the TagAnnotations.
+          #           ### Likely an undesirable side effect having the value change for all TagAnnotations
+          #     **  OR create a new TagBody and update @body to that TagBody
+          #   OR
+          #     * [CURRENT] Always create a new TagBody each time setTag is called and update @body
+          #         ### This last options has the potential for orphaned TagBodys that no TagAnnotation references.
+          # TODO Rethink the current behavior which is always to create a new TagBody potentially leaving around orphans.
+          @body = LD4L::OpenAnnotationRDF::TagBody.new(
+              ActiveTriples::LocalName::Minter.generate_local_name(
+                  LD4L::OpenAnnotationRDF::TagBody, 10, @localname_prefix,
+                  LD4L::OpenAnnotationRDF.configuration.localname_minter ))
+          @body.tag = tag
+        end
+        set_value(:hasBody, @body)
+        @body
+      end
+
+      ##
+      # Special processing for new and resumed TagAnnotations
+      #
+      def initialize(*args)
+        super(*args)
+
+        # set motivatedBy
+        m = get_values(:motivatedBy)
+        set_value(:motivatedBy, RDFVocabularies::OA.tagging) unless m.kind_of?(Array) && m.size > 0
+
+        # resume TagBody if it exists
+        tag_uri = get_values(:hasBody).first
+        if( tag_uri )
+          tag_uri = tag_uri.rdf_subject  if tag_uri.kind_of?(ActiveTriples::Resource)
+          @body  = LD4L::OpenAnnotationRDF::TagBody.new(tag_uri)
+        end
+      end
+
+      def destroy
+        # TODO Determine behavior of destroy
+        #   Behaviour Options
+        #     * Always destroy TagAnnotation
+        #     * Handling of TagBody
+        #     **  If TagBody is used only by this TagAnnotation, destroy it.
+        #     **  Otherwise, do not destroy it.
+        # TODO Write tests for this behaviour.
+        # TODO Write code here to enforce.
+        super
+      end
+    end
+  end
+end
+

data/lib/ld4l/open_annotation_rdf/tag_body.rb

@@ -0,0 +1,83 @@
+module LD4L
+  module OpenAnnotationRDF
+    class TagBody < ActiveTriples::Resource
+
+      class << self; attr_reader :localname_prefix end
+      @localname_prefix="tb"
+
+      configure :type => RDFVocabularies::OA.Tag,
+                :base_uri => LD4L::OpenAnnotationRDF.configuration.base_uri,
+                :repository => :default
+
+      property :tag,     :predicate => RDFVocabularies::CNT.chars  # :type => XSD.string
+
+      ##
+      # Get a list of annotations using the tag value.
+      #
+      # @param [String] tag value
+      #
+      # @return array of annotation URIs
+      #
+      # NOTE: This method returns only persisted annotations.
+      def self::annotations_using( tag_value )
+        raise ArgumentError, 'Argument must be a string with at least one character'  unless
+            tag_value.kind_of?(String) && tag_value.size > 0
+
+        tb = self::fetch_by_tag_value( tag_value )
+        return []  unless tb
+        tag_uri = tb.rdf_subject
+
+        # find usage by Annotations
+        graph = ActiveTriples::Repositories.repositories[repository]
+        query = RDF::Query.new({
+                                   :annotation => {
+                                       RDF.type =>  RDFVocabularies::OA.Annotation,
+                                       RDFVocabularies::OA.hasBody => tag_uri,
+                                   }
+                               })
+        results = query.execute(graph)
+
+        # process results
+        annotations = []
+        results.each { |r| annotations << r.to_hash[:annotation] }
+        annotations
+      end
+
+
+      ##
+      # Search the configured repository for a TagBody triple that has the tag value for the tag property.
+      #
+      # @param [String] tag value
+      #
+      # @return instance of TagBody if found; otherwise, nil
+      def self::fetch_by_tag_value( tag_value )
+        raise ArgumentError, 'Argument must be a string with at least one character'  unless
+            tag_value.kind_of?(String) && tag_value.size > 0
+
+        graph = ActiveTriples::Repositories.repositories[repository]
+        query = RDF::Query.new({
+          :tagbody => {
+            RDF.type =>  RDFVocabularies::OA.Tag,
+            RDFVocabularies::CNT.chars => tag_value,
+          }
+        })
+
+        tagbody = nil
+        results = query.execute(graph)
+        unless( results.empty? )
+          tagbody_uri = results[0].to_hash[:tagbody]
+          tagbody = LD4L::OpenAnnotationRDF::TagBody.new(tagbody_uri)
+        end
+        tagbody
+      end
+
+      def initialize(*args)
+        super(*args)
+
+        t = get_values(:type)
+        t << RDFVocabularies::CNT.ContentAsText
+        set_value(:type,t)
+      end
+    end
+  end
+end