active-fedora 2.2.0 → 2.2.1

data/lib/active_fedora/samples/hydra-rights_metadata_datastream.rb

@@ -0,0 +1,206 @@
+module Hydra
+  # This is an example of a NokogiriDatastream that defines a terminology for Hydra rightsMetadata xml
+  # The documentation for Hydra rightsMetadata is on the Hydra wiki at https://wiki.duraspace.org/display/hydra/Hydra+rights+metadata
+  # The real version of this Terminology is part of the hydra-head plugin.  See https://github.com/projecthydra/hydra-head/blob/master/lib/hydra/rights_metadata.rb
+  #
+  # The purpose of rightsMetadata is to store information about access controls and licensing for the object that the rightsMetadata is attached to
+  #
+  # The most interesting thing going on in this Class is the use of custom methods to access and update permissions in intuitive ways.
+  # These methods allow you to do things like
+  # * Get reports on which groups & individuals have which permissions
+  # * Update permissions for individuals & groups with straightforward syntax
+  #
+  # Another interesting thing in this Class: it extends to_solr, first calling "super" (the default to_solr behavior) and then inserting an additional embargo_release_date_dt field
+  # It uses Solrizer::Extractor.insert_solr_field_value to do this.  That method handles inserting new values into a Hash while ensuring that you don't destroy or overwrite any existing values in the hash.
+  class RightsMetadataDatastream < ActiveFedora::NokogiriDatastream       
+  
+    set_terminology do |t|
+      t.root(:path=>"rightsMetadata", :xmlns=>"http://hydra-collab.stanford.edu/schemas/rightsMetadata/v1", :schema=>"http://github.com/projecthydra/schemas/tree/v1/rightsMetadata.xsd") 
+      t.copyright {
+        t.machine {
+          t.cclicense        
+        }
+        t.human_readable(:path=>"human")
+        t.cclicense(:proxy=>[:machine, :cclicense ])                  
+      }
+      t.access {
+        t.human_readable(:path=>"human")
+        t.machine {
+          t.group
+          t.person
+        }
+        t.person(:proxy=>[:machine, :person])
+        t.group(:proxy=>[:machine, :group])
+        # accessor :access_person, :term=>[:access, :machine, :person]
+      }
+      t.discover_access(:ref=>[:access], :attributes=>{:type=>"discover"})
+      t.read_access(:ref=>[:access], :attributes=>{:type=>"read"})
+      t.edit_access(:ref=>[:access], :attributes=>{:type=>"edit"})
+      # A bug in OM prevnts us from declaring proxy terms at the root of a Terminology
+      # t.access_person(:proxy=>[:access,:machine,:person])
+      # t.access_group(:proxy=>[:access,:machine,:group])
+    
+      t.embargo {
+        t.human_readable(:path=>"human")
+        t.machine{
+          t.date(:type =>"release")
+        }
+        t.embargo_release_date(:proxy => [:machine, :date])
+      }    
+    end
+    
+    # Generates an empty Mods Article (used when you call ModsArticle.new without passing in existing xml)
+    def self.xml_template
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.rightsMetadata(:version=>"0.1", "xmlns"=>"http://hydra-collab.stanford.edu/schemas/rightsMetadata/v1") {
+          xml.copyright {
+            xml.human
+            xml.machine {
+              xml.uvalicense "no"
+            }
+          }
+          xml.access(:type=>"discover") {
+            xml.human
+            xml.machine
+          }
+          xml.access(:type=>"read") {
+            xml.human 
+            xml.machine
+          }
+          xml.access(:type=>"edit") {
+            xml.human
+            xml.machine
+          }
+          xml.embargo{
+            xml.human
+            xml.machine
+          }        
+        }
+      end
+      return builder.doc
+    end
+    
+    # Returns the permissions for the selected person/group
+    # If new_access_level is provided, updates the selected person/group access_level to the one specified 
+    # A new_access_level of "none" will remove all access_levels for the selected person/group
+    # @param [Hash] selector
+    # @param [String] new_access_level (default nil)
+    # @return [Hash] 
+    # 
+    # @example Query permissions for person123, Set the permissions to "read", then query again to see that they have changed.
+    #   permissions({:person=>"person123"})
+    #   => {"person123"=>"edit"}
+    #   permissions({:person=>"person123"}, "read")
+    #   => {"person123"=>"read"}
+    #   permissions({:person=>"person123"})
+    #   => {"person123"=>"read"}
+    def permissions(selector, new_access_level=nil)
+    
+      type = selector.keys.first.to_sym
+      actor = selector.values.first
+      if new_access_level.nil?
+        xpath = self.class.terminology.xpath_for(:access, type, actor)
+        nodeset = self.find_by_terms(xpath)
+        if nodeset.empty?
+          return "none"
+        else
+          return nodeset.first.ancestors("access").first.attributes["type"].text
+        end
+      else
+        remove_all_permissions(selector)
+        unless new_access_level == "none" 
+          access_type_symbol = "#{new_access_level}_access".to_sym
+          result = self.update_values([access_type_symbol, type] => {"-1"=>actor})
+        end
+        self.dirty = true
+        return new_access_level
+      end
+      
+    end
+  
+    # Reports on which groups have which permissions
+    # @return [Hash] 
+    # @example
+    #   sample_ds.permissions({"group"=>"group_zzz"}, "edit")
+    #   sample_ds.permissions({"group"=>"public"}, "discover")
+    #   sample_ds.groups #=>  {"public"=>"discover", "group_zzz"=>"edit"}
+    def groups
+      return quick_search_by_type(:group)
+    end
+  
+    # Reports on which groups have which permissions
+    # @return [Hash] 
+    # @example
+    #   sample_ds.permissions({"person"=>"person_123"}, "read")
+    #   sample_ds.permissions({""person"=>"person_456"}, "edit")
+    #   sample_ds.individuals #=>  {"person_123"=>"read", "person_456"=>"edit"}
+    def individuals
+      return quick_search_by_type(:person)
+    end
+  
+    # Updates permissions for all of the persons and groups in a hash
+    # @param [Hash] params example: {"group"=>{"group1"=>"discover","group2"=>"edit"}, "person"=>{"person1"=>"read","person2"=>"discover"}}
+    # Currently restricts actor type to group or person.  Any others will be ignored
+    def update_permissions(params)
+      params.fetch("group", {}).each_pair {|group_id, access_level| self.permissions({"group"=>group_id}, access_level)}
+      params.fetch("person", {}).each_pair {|group_id, access_level| self.permissions({"person"=>group_id}, access_level)}
+    end
+  
+    # This method limits the response to known access levels (:discover, :read, :edit).  Probably runs a bit faster than {#permissions}.
+    # @param [:group,:person] type 
+    # @return [Hash] 
+    def quick_search_by_type(type)
+      result = {}
+      [{:discover_access=>"discover"},{:read_access=>"read"},{:edit_access=>"edit"}].each do |access_levels_hash|
+        access_level = access_levels_hash.keys.first
+        access_level_name = access_levels_hash.values.first
+        self.find_by_terms(*[access_level, type]).each do |entry|
+          result[entry.text] = access_level_name
+        end
+      end
+      return result
+    end
+
+    attr_reader :embargo_release_date
+    def embargo_release_date=(release_date)
+      release_date = release_date.to_s if release_date.is_a? Date
+      begin
+        Date.parse(release_date)
+      rescue 
+        return "INVALID DATE"
+      end
+      self.update_values({[:embargo,:machine,:date]=>release_date})
+    end
+    def embargo_release_date(opts={})
+      embargo_release_date = self.find_by_terms(*[:embargo,:machine,:date]).first ? self.find_by_terms(*[:embargo,:machine,:date]).first.text : nil
+      if opts[:format] && opts[:format] == :solr_date
+        embargo_release_date << "T23:59:59Z"
+      end
+      embargo_release_date
+    end
+    def under_embargo?
+      (embargo_release_date && Date.today < embargo_release_date.to_date) ? true : false
+    end
+
+    def to_solr(solr_doc=Hash.new)
+      super(solr_doc)
+      ::Solrizer::Extractor.insert_solr_field_value(solr_doc, "embargo_release_date_dt", embargo_release_date(:format=>:solr_date)) if embargo_release_date
+      solr_doc
+    end
+
+
+
+
+  
+    private
+    # Purge all access given group/person 
+    def remove_all_permissions(selector)
+      type = selector.keys.first.to_sym
+      actor = selector.values.first
+      xpath = self.class.terminology.xpath_for(:access, type, actor)
+      nodes_to_purge = self.find_by_terms(xpath)
+      nodes_to_purge.each {|node| node.remove}
+    end
+  
+  end
+end

data/lib/active_fedora/samples/marpa-dc_datastream.rb

@@ -0,0 +1,97 @@
+require "active-fedora"
+module Marpa
+
+  # This is an example of a NokogiriDatastream that defines a terminology for Dublin Core xml
+  #
+  # Some things to observe about this Class:
+  # * Defines a couple of custom terms, tibetan_title and english_title, that map to dc:title with varying @language attributes
+  # * Indicates which terms should be indexed as facets using :index_as=>[:facetable]
+  # * Defines an xml template that is an empty dublin core xml document with three namespaces set
+  # * Sets the namespace using :xmlns argument on the root term
+  # * Does not override or extend to_solr, so the default solrization approach will be used (Solrizer::XML::TerminologyBasedSolrizer)
+  #
+  class DcDatastream < ActiveFedora::NokogiriDatastream
+  
+    set_terminology do |t|
+      t.root(:path=>"dc", :xmlns=>'http://purl.org/dc/terms/')
+      t.tibetan_title(:path=>"title", :attributes=>{:language=>"tibetan"})
+      t.english_title(:path=>"title", :attributes=>{:language=>:none})
+      t.contributor(:index_as=>[:facetable])
+      t.coverage
+      t.creator
+      t.description
+      t.format
+      t.identifier
+      t.language(:index_as=>[:facetable])
+      t.publisher
+      t.relation
+      t.source
+      t.title
+      t.abstract
+      t.accessRights
+      t.accrualMethod
+      t.accrualPeriodicity
+      t.accrualPolicy
+      t.alternative
+      t.audience
+      t.available
+      t.bibliographicCitation
+      t.conformsTo
+      t.contributor
+      t.coverage
+      t.created
+      t.creator
+      t.date(:index_as=>[:facetable])
+      t.dateAccepted
+      t.dateCopyrighted
+      t.dateSubmitted
+      t.description
+      t.educationLevel
+      t.extent
+      t.format
+      t.hasFormat
+      t.hasPart
+      t.hasVersion
+      t.identifier
+      t.instructionalMethod
+      t.isFormatOf
+      t.isPartOf
+      t.isReferencedBy
+      t.isReplacedBy
+      t.isRequiredBy
+      t.issued
+      t.isVersionOf
+      t.language(:index_as=>[:facetable])
+      t.license
+      t.mediator
+      t.medium
+      t.modified
+      t.provenance
+      t.publisher
+      t.references
+      t.relation
+      t.replaces
+      t.requires
+      t.rights
+      t.rightsHolder
+      t.source
+      t.spatial(:index_as=>[:facetable])
+      t.subject(:index_as=>[:facetable])
+      t.tableOfContents
+      t.temporal
+      t.type
+      t.valid
+    end
+  
+    def self.xml_template
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.dc("xmlns"=>'http://purl.org/dc/terms/',
+          "xmlns:dcterms"=>'http://purl.org/dc/terms/', 
+          "xmlns:xsi"=>'http://www.w3.org/2001/XMLSchema-instance') {
+        }
+      end
+      return builder.doc
+    end
+  
+  end
+end

data/lib/active_fedora/samples/special_thing.rb

@@ -0,0 +1,45 @@
+require "active-fedora"
+require "active_fedora/samples/hydra-mods_article_datastream.rb"
+require "active_fedora/samples/hydra-rights_metadata_datastream.rb"
+require "active_fedora/samples/marpa-dc_datastream.rb"
+
+# This is an example of an ActiveFedora Model
+#
+# Some of the datastream ids were chosen based on the Hydra modeling conventions.  You don't have to follow them in your work.  ActiveFedora itself has no notion of those conventions, but we do encourage you to use them.
+#
+# The Hydra conventions encourage you to have a datastream with this dsid whose contents are descriptive metadata like MODS or Dublin Core.  They especially encourage MODS.  
+# The rightsMetadata datastream is also a convention provided by the Hydra Common Metadata "content model"
+#
+# For more info on the Hydra conventions, see the documentation on "Common Metadata content model" in https://wiki.duraspace.org/display/hydra/Hydra+content+models+and+disseminators
+# Note that on the wiki, "content model" is often used to refer to Fedora CModels and/or abstract/notional models.  The Common Metadata content model is an example of this.
+# The wiki includes a page that attempts to shed some light on the question of "What is a content model?" https://wiki.duraspace.org/display/hydra/Don't+call+it+a+'content+model'!
+class SpecialThing < ActiveFedora::Base
+  
+  #
+  # DATASTREAMS
+  #
+  
+  # This declares a datastream with Datastream ID (dsid) of "descMetadata"
+  # The descMetadata datastream is bound to the Hydra::ModsArticleDatastream class that's defined in lib/active_fedora/samples
+  # Any time you load a Fedora object using an instance of SampleModel, the instance will assume its descMetadata datastream conforms to the assumptions in Hydra::ModsArticleDatastream class
+  has_metadata :name => "descMetadata", :type=> Hydra::ModsArticleDatastream
+  
+  # This declares a datastream with Datastream ID (dsid) of "rightsMetadata"
+  # Like the descMetadata datastream, any time you load a Fedora object using an instance of SampleModel, the instance will assume its descMetadata datastream conforms to the assumptions in Hydra::RightsMetadataDatastream class
+  has_metadata :name => "rightsMetadata", :type => Hydra::RightsMetadataDatastream
+  
+  # This is not part of the Hydra conventions
+  # Adding an extra datastream called "extraMetadataForFun" that is bound to the Marpa::DcDatastream class
+  has_metadata :name => "extraMetadataForFun", :type => Marpa::DcDatastream
+  
+  #
+  # RELATIONSHIPS
+  #
+  
+  # This is an example of how you can add a custom relationship to a model
+  # This will allow you to call .derivations on instances of the model to get a list of all of the _outbound_ "hasDerivation" relationships in the RELS-EXT datastream
+  has_relationship "derivations", :has_derivation
+
+  # This will allow you to call .inspirations on instances of the model to get a list of all of the objects that assert "hasDerivation" relationships pointing at this object
+  has_relationship "inspirations", :has_derivation, :inbound => true  
+end

data/lib/active_fedora/semantic_node.rb

@@ -394,7 +394,8 @@ module ActiveFedora
     end
     
     # Creates a RELS-EXT datastream for insertion into a Fedora Object
-    # @pid
+    # @param [String] pid
+    # @param [Hash] relationships (optional) @default self.relationships
     # Note: This method is implemented on SemanticNode instead of RelsExtDatastream because SemanticNode contains the relationships array
     def to_rels_ext(pid, relationships=self.relationships)
       starter_xml = <<-EOL
@@ -480,10 +481,10 @@ module ActiveFedora
       
       # Generates relationship finders for predicates that point in both directions
       #
-      # @name Name of the relationship method(s) to create
-      # @outbound_predicate Predicate used in outbound relationships
-      # @inbound_predicate Predicate used in inbound relationships
-      # @opts
+      # @param [String] name of the relationship method(s) to create
+      # @param [Symbol] outbound_predicate Predicate used in outbound relationships
+      # @param [Symbol] inbound_predicate Predicate used in inbound relationships
+      # @param [Hash] opts
       #
       # Example:
       #  has_bidirectional_relationship("parts", :has_part, :is_part_of)
@@ -646,11 +647,10 @@ module ActiveFedora
       # Generates relationship finders for predicates that point in both directions
       # and registers predicate relationships for each direction.
       #
-      # @name Name of the relationship method(s) to create
-      # @outbound_predicate Predicate used in outbound relationships
-      # @inbound_predicate Predicate used in inbound relationships
-      # @opts
-      #
+      # @param [String] name Name of the relationship method(s) to create
+      # @param [Symbol] outbound_predicate Predicate used in outbound relationships
+      # @param [Symbol] inbound_predicate Predicate used in inbound relationships
+      # @param [Hash] opts (optional)
       def create_bidirectional_relationship_finders(name, outbound_predicate, inbound_predicate, opts={})
         inbound_method_name = name.to_s+"_inbound"
         outbound_method_name = name.to_s+"_outbound"
@@ -693,7 +693,9 @@ module ActiveFedora
         END
       end
     
-      # relationships are tracked as a hash of structure {subject => {predicate => [object]}}
+      # relationships are tracked as a hash of structure 
+      # @example
+      #   ds.relationships # => {:self=>{:has_model=>["afmodel:SimpleThing"],:has_part=>["demo:20"]},:inbound=>{:is_part_of=>["demo:6"]} 
       def relationships
         @class_relationships ||= Hash[:self => {}]
       end
@@ -715,7 +717,8 @@ module ActiveFedora
       #alias_method :register_target, :register_object
     
       # Creates a RELS-EXT datastream for insertion into a Fedora Object
-      # @pid
+      # @param [String] pid of the object that the RELS-EXT datastream belongs to
+      # @param [Hash] relationships the relationships hash to transform into RELS-EXT RDF. @default the object's relationships hash
       # Note: This method is implemented on SemanticNode instead of RelsExtDatastream because SemanticNode contains the relationships array
       def relationships_to_rels_ext(pid, relationships=self.relationships)
         starter_xml = <<-EOL
@@ -738,7 +741,7 @@ module ActiveFedora
     
       # If predicate is a symbol, looks up the predicate in the predicate_mappings
       # If predicate is not a Symbol, returns the predicate untouched
-      # @throws UnregisteredPredicateError if the predicate is a symbol but is not found in the predicate_mappings
+      # @raise UnregisteredPredicateError if the predicate is a symbol but is not found in the predicate_mappings
       def predicate_lookup(predicate,namespace="info:fedora/fedora-system:def/relations-external#")
         if predicate.class == Symbol 
           if predicate_mappings[namespace].has_key?(predicate)

data/lib/active_fedora/version.rb

@@ -0,0 +1,3 @@
+module ActiveFedora
+    VERSION = "2.2.1"
+end

data/lib/fedora/base.rb

@@ -1,8 +1,10 @@
 require 'xmlsimple'
 
 class Hash
-  #   {:q => 'test', :num => 5}.to_query # => 'q=test&num=5'
-  #   let's avoid stomping on rails' version eh?
+  
+  # Produces a valid Fedora query based on the current hash
+  # @example
+  #   {:q => 'test', :num => 5}.to_fedora_query # => 'q=test&num=5'
   def to_fedora_query
     self.collect { |key, value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}" }.sort * '&'
   end
@@ -17,9 +19,7 @@ class Fedora::BaseObject
   attr_reader :errors, :uri
   attr_writer :new_object
   
-  # == Parameters
-  # attrs<Hash>:: object attributes
-  #-
+  # @param [Hash] attrs object attributes
   def initialize(attrs = {})
     @new_object = true
     @attributes = attrs || {}

data/lib/fedora/datastream.rb

@@ -49,7 +49,7 @@ class Fedora::Datastream < Fedora::BaseObject
     "fedora:info/#{pid}/datastreams/#{dsid}"
   end
   
-  # @returns the url of the datastream in Fedora, without the repository userinfo
+  # @return [String] url of the datastream in Fedora, without the repository userinfo
   def url
     return "#{Fedora::Repository.instance.base_url}/objects/#{pid}/datastreams/#{dsid}"
   end