samvera-nesting_indexer 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cda0810a46d78a31bbf3dfe29b0bc43f184657c0
-  data.tar.gz: c0d79f4628040a28de9735b358223d6a648759cf
+  metadata.gz: 476ac6dd12de858bd342468c294cf3eb182681fb
+  data.tar.gz: 248c720f7ab465acfe3c9b131e96dc34ab780938
 SHA512:
-  metadata.gz: 3aceaba25afffb5c2f7776e7d0df1f6fc6bcd7de1b23b6acad1cbd2413f0f0decb7192b8cc15fc0e0e1c264bf8c9e3b2429544ce5f60aaaa162608f1d6df992c
-  data.tar.gz: 66ae2cdd1470fef272535138656a672c625de02419a992bee823fb7342a5ecdd97c421f7a585167023c5881afb569c9f4a574917a296f5ba009cdf5e73e04d0b
+  metadata.gz: 015ff0f42fb0b4e52d504f6382bcc8acac1db129db25f1f2f452cf5df7acec3edaca82fcfe8132714286ecaf316a46958c3d15dc07c7183881e429fad32f8d25
+  data.tar.gz: 683b23f760950613e746ac4fd3b2be59c2fb392acb2399245f5e8e6f9264d51704ae6599e5e613408d1d355a2321d8c429e6d40f1a4d8b318c7b7fefbfd596cf

data/README.md

@@ -109,10 +109,12 @@ end
 
 The following sequence diagram documents the interactions in [Samvera::NestingIndexer::RelationshipReindexer](lib/samvera/nesting_indexer/relationship_reindexer.rb).
 
-![Reindex Relationship Diagram](documentation/reindex_relationship.mermaid.jpg)
+![Reindex Relationship Diagram](documentation/reindex_relationship.mermaid.png)
 
 See [the text-based version of Reindex Relationship diagram](documentation/reindex_relationship.mermaid), leveraging the [Mermaid syntax](https://mermaidjs.github.io).
 
+See [documentation/README.md](documentation/README.md) for details on updating the diagram.
+
 ## Considerations
 
 Given a single object A, when we reindex A, we:

data/documentation/README.md

@@ -0,0 +1,13 @@
+For generating a JPG from a mermaid file, you may use the [mermaid.cli tool](https://github.com/mermaidjs/mermaid.cli) or use the [atom-mermaid](https://atom.io/packages/atom-mermaid) plugin for the [Atom editor](https://atom.io).
+
+## Using atom-mermaid
+
+* From Atom, install the 'atom-mermaid' package and restart Atom.
+* Then go to the corresponding `.mermaid` file
+* Select the Atom menu item Packages > Mermaid Preview > Toggle Preview
+* Right-Click on the opened preview and select "Save as PNG"
+* Copy the saved PNG to the appropriate location (e.g. `./documentation/`)
+
+## Using mermaid.cli
+
+You'll need to give it a try.

data/documentation/reindex_relationship.mermaid

@@ -15,8 +15,9 @@ sequenceDiagram
         Indexer-->>Adapter: adapter.find_preservation_document_by(id:)
         Adapter-->>Preservation: get preservation document
         Preservation-->>Indexer: receive preservation document
+        Indexer-->>Indexer: build_nesting_document_for(preservation document)
         Indexer-->>Indexer: guard_against_possiblity_of_self_ancestry
-        Indexer-->>Adapter: adapter.write_document_attributes_to_index_layer
+        Indexer-->>Adapter: adapter.write_nesting_document_to_index_layer
         Adapter-->>Index: write updated application index document
         Indexer-->>Indexer: enqueue children
     end

data/lib/generators/samvera/nesting_indexer/install_generator.rb

@@ -8,7 +8,7 @@ module Samvera
       # Responsible for exposing the install generator (e.g. rails generator install amvera:nesting_indexer:install)
       class InstallGenerator < Rails::Generators::Base
         DEFAULT_MAXIMUM_NESTING_DEPTH = 5
-        source_root File.expand_path("../templates", __FILE__)
+        source_root File.expand_path('templates', __dir__)
         desc "Creates a Samvera::NestingIndexer initializer."
         class_option(
           :adapter,

data/lib/generators/samvera/nesting_indexer/templates/samvera-nesting_indexer_initializer.rb

@@ -21,4 +21,5 @@ Samvera::NestingIndexer.configure do |config|
   # config.solr_field_name_for_storing_parent_ids = Solrizer.solr_name('nesting_collection__parent_ids', :symbol)
   # config.solr_field_name_for_storing_ancestors =  Solrizer.solr_name('nesting_collection__ancestors', :symbol)
   # config.solr_field_name_for_storing_pathnames =  Solrizer.solr_name('nesting_collection__pathnames', :symbol)
+  # config.solr_field_name_for_deepest_nested_depth =  Solrizer.solr_name('nesting_collection__deepest_nested_depth', :integer)
 end

data/lib/samvera/nesting_indexer.rb

@@ -18,12 +18,13 @@ module Samvera
     # @param id [String] - The permanent identifier of the object that will be reindexed along with its children.
     # @param maximum_nesting_depth [Integer] - used to short-circuit overly deep nesting as well as prevent accidental cyclic graphs
     #                                          from creating an infinite loop.
+    # @param extent [String] - may be leveraged in adapter to limit the extent of the reindexing of children
     # @return [Boolean] - It was successful
     # @raise Samvera::Exceptions::CycleDetectionError - A possible cycle was detected
     # @raise Samvera::Exceptions::ExceededMaximumNestingDepthError - We exceeded our maximum depth
     # @raise Samvera::Exceptions::DocumentIsItsOwnAncestorError - A document we were about to index appeared to be its own ancestor
-    def self.reindex_relationships(id:, maximum_nesting_depth: configuration.maximum_nesting_depth)
-      RelationshipReindexer.call(id: id, maximum_nesting_depth: maximum_nesting_depth, configuration: configuration)
+    def self.reindex_relationships(id:, maximum_nesting_depth: configuration.maximum_nesting_depth, extent:)
+      RelationshipReindexer.call(id: id, maximum_nesting_depth: maximum_nesting_depth, configuration: configuration, extent: extent)
       true
     end
 
@@ -36,13 +37,14 @@ module Samvera
     # @api public
     # Responsible for reindexing the entire preservation layer.
     # @param maximum_nesting_depth [Integer] - there to guard against cyclic graphs
+    # @param extent [String] - for reindex_all, should result in full reindexing... leveraged in adapter to limit the extent of the reindexing of children
     # @return [Boolean] - It was successful
     # @raise Samvera::Exceptions::ReindexingError - There was a problem reindexing the graph.
-    def self.reindex_all!(maximum_nesting_depth: configuration.maximum_nesting_depth)
+    def self.reindex_all!(maximum_nesting_depth: configuration.maximum_nesting_depth, extent:)
       # While the RepositoryReindexer is responsible for reindexing everything, I
       # want to inject the lambda that will reindex a single item.
       id_reindexer = method(:reindex_relationships)
-      RepositoryReindexer.call(maximum_nesting_depth: maximum_nesting_depth, id_reindexer: id_reindexer, configuration: configuration)
+      RepositoryReindexer.call(maximum_nesting_depth: maximum_nesting_depth, id_reindexer: id_reindexer, configuration: configuration, extent: extent)
       true
     end
 
@@ -89,9 +91,5 @@ module Samvera
       @configuration_block.call(configuration)
       @configuration_block = nil
     end
-
-    def self.semantic_version_messages
-      SemverAssistant.messages
-    end
   end
 end

data/lib/samvera/nesting_indexer/adapters/abstract_adapter.rb

@@ -37,21 +37,9 @@ module Samvera
 
         # @api public
         # @param document [Samvera::NestingIndexer::Documents::IndexDocument]
+        # @param extent [String] passed into adapter from reindex_relationships call
         # @yield [Samvera::NestingIndexer::Documents::IndexDocument]
-        def self.each_child_document_of(document:, &block)
-          raise NotImplementedError
-        end
-
-        # @api public
-        # @deprecated Use .write_nesting_document_to_index_layer instead
-        # @see README.md
-        # @param id [String]
-        # @param parent_ids [Array<String>]
-        # @param ancestors [Array<String>]
-        # @param pathnames [Array<String>]
-        # @param deepest_nested_depth [Integer]
-        # @return Hash - the attributes written to the indexing layer
-        def self.write_document_attributes_to_index_layer(id:, parent_ids:, ancestors:, pathnames:, deepest_nested_depth:)
+        def self.each_child_document_of(document:, extent:, &block)
           raise NotImplementedError
         end
 

data/lib/samvera/nesting_indexer/adapters/in_memory_adapter.rb

@@ -4,34 +4,30 @@ require 'samvera/nesting_indexer/documents'
 module Samvera
   module NestingIndexer
     module Adapters
-      # @api public
+      # @api private
       #
       # Defines the interface for interacting with the InMemory layer. It is a reference
       # implementation that is used throughout tests.
       module InMemoryAdapter
-        SemverAssistant.removing_from_public_api(context: self, as_of: '2.0.0')
         extend AbstractAdapter
-        # @api public
+        # @api private
         # @param id [String]
         # @return Samvera::NestingIndexer::Document::PreservationDocument
         def self.find_preservation_document_by(id:)
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           Preservation.find(id)
         end
 
-        # @api public
+        # @api private
         # @param id [String]
         # @return [Samvera::NestingIndexer::Documents::IndexDocument]
         def self.find_index_document_by(id:)
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           Index.find(id)
         end
 
-        # @api public
+        # @api private
         # @yieldparam id [String] The `id` of the preservation document
         # @yieldparam parent_ids [String] The ids of the parent objects of this presevation document
         def self.each_perservation_document_id_and_parent_ids(&block)
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           Preservation.find_each do |document|
             block.call(document.id, document.parent_ids)
           end
@@ -41,42 +37,29 @@ module Samvera
           Preservation.find(id).parent_ids
         end
 
-        # @api public
+        # @api private
         # @param document [Samvera::NestingIndexer::Documents::IndexDocument]
+        # @param extent [String] passed into adapter from reindex_relationships call
         # @yield [Samvera::NestingIndexer::Documents::IndexDocument]
-        def self.each_child_document_of(document:, &block)
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
-          Index.each_child_document_of(document: document, &block)
+        # rubocop:disable Lint/UnusedMethodArgument
+        def self.each_child_document_of(document:, extent:, &block)
+          Index.each_child_document_of(document: document, extent: "full", &block)
         end
+        # rubocop:enable Lint/UnusedMethodArgument
 
-        # @api public
+        # @api private
         # This is not something that I envision using in the production environment;
         # It is hear to keep the Preservation system isolated and accessible only through interfaces.
         # @param attributes [Hash]
         # @return [Samvera::NestingIndexer::Documents::PreservationDocument]
         def self.write_document_attributes_to_preservation_layer(attributes)
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           Preservation.write_document(attributes)
         end
 
-        # @api public
-        # @see README.md
-        # @param id [String]
-        # @param parent_ids [Array<String>]
-        # @param ancestors [Array<String>]
-        # @param pathnames [Array<String>]
-        # @param deepest_nested_depth [Integer]
-        # @return [Hash] - the attributes written to the indexing layer
-        def self.write_document_attributes_to_index_layer(id:, parent_ids:, ancestors:, pathnames:, deepest_nested_depth:)
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
-          Index.write_document(id: id, parent_ids: parent_ids, ancestors: ancestors, pathnames: pathnames, deepest_nested_depth: deepest_nested_depth)
-        end
-
-        # @api public
+        # @api private
         # @see README.md
         # @param nesting_document [Samvera::NestingIndexer::Documents::IndexDocument]
         def self.write_nesting_document_to_index_layer(nesting_document:)
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           Index.write_to_storage(nesting_document)
         end
 
@@ -172,18 +155,16 @@ module Samvera
             Storage.find_each(&block)
           end
 
-          def self.each_child_document_of(document:, &block)
+          # rubocop:disable Lint/UnusedMethodArgument
+          def self.each_child_document_of(document:, extent: nil, &block)
             Storage.find_children_of_id(document.id).each(&block)
           end
+          # rubocop:enable Lint/UnusedMethodArgument
 
           def self.write_to_storage(doc)
             Storage.write(doc)
           end
 
-          def self.write_document(attributes = {})
-            Documents::IndexDocument.new(attributes).tap { |doc| write_to_storage(doc) }
-          end
-
           # :nodoc:
           module Storage
             extend StorageModule

data/lib/samvera/nesting_indexer/adapters/interface_behavior_spec.rb

@@ -68,10 +68,10 @@ if defined?(RSpec)
       subject { described_class.method(:each_child_document_of) }
 
       it 'requires the :document keyword (and does not require any others)' do
-        expect(required_keyword_parameters.call(subject)).to eq([:document])
+        expect(required_keyword_parameters.call(subject)).to eq(%i(document extent))
       end
 
-      it 'does not require any other parameters (besides :document)' do
+      it 'does not require any other parameters (besides :document, :extent)' do
         expect(required_parameters.call(subject)).to eq(required_keyword_parameters.call(subject))
       end
 
@@ -79,21 +79,6 @@ if defined?(RSpec)
         expect(block_parameter_extracter.call(subject)).to eq([:block])
       end
     end
-    describe '.write_document_attributes_to_index_layer' do
-      subject { described_class.method(:write_document_attributes_to_index_layer) }
-
-      it 'requires the :ancestors, :deepest_nested_depth, :id, :parent_ids, and :pathnames keyword (and does not require any others)' do
-        expect(required_keyword_parameters.call(subject)).to eq(%i(ancestors deepest_nested_depth id parent_ids pathnames))
-      end
-
-      it 'does not require any other parameters (besides :attributes)' do
-        expect(required_parameters.call(subject)).to eq(required_keyword_parameters.call(subject))
-      end
-
-      it 'does not expect a block' do
-        expect(block_parameter_extracter.call(subject)).to be_empty
-      end
-    end
 
     describe '.write_nesting_document_to_index_layer' do
       subject { described_class.method(:write_nesting_document_to_index_layer) }

data/lib/samvera/nesting_indexer/configuration.rb

@@ -46,6 +46,14 @@ module Samvera
         @solr_field_name_for_storing_pathnames || raise(Exceptions::SolrKeyConfigurationError.new(name: __method__, config: self))
       end
 
+      def solr_field_name_for_deepest_nested_depth=(input)
+        @solr_field_name_for_deepest_nested_depth = input.to_s
+      end
+
+      def solr_field_name_for_deepest_nested_depth
+        @solr_field_name_for_deepest_nested_depth || raise(Exceptions::SolrKeyConfigurationError.new(name: __method__, config: self))
+      end
+
       # @api public
       # @return Samvera::NestingIndexer::Adapters::AbstractAdapter
       def adapter

data/lib/samvera/nesting_indexer/documents.rb

@@ -1,5 +1,4 @@
 require 'dry-equalizer'
-require 'samvera/nesting_indexer/semver_assistant'
 
 module Samvera
   module NestingIndexer
@@ -7,7 +6,7 @@ module Samvera
     module Documents
       ANCESTOR_AND_PATHNAME_DELIMITER = '/'.freeze
 
-      # @api public
+      # @api private
       #
       # A simplified document that reflects the necessary attributes for re-indexing
       # the children of Fedora objects.
@@ -16,21 +15,18 @@ module Samvera
           @id = keywords.fetch(:id).to_s
           @parent_ids = Array(keywords.fetch(:parent_ids))
         end
-        SemverAssistant.removing_from_public_api(context: self, as_of: '2.0.0')
 
-        # @api public
+        # @api private
         # @return String The Fedora object's PID
         attr_reader :id
-        SemverAssistant.removing_from_public_api(context: "#{self}#id", as_of: '2.0.0')
 
-        # @api public
+        # @api private
         #
         # All of the direct parents of the Fedora document associated with the given PID.
         #
         # This does not include grandparents, great-grandparents, etc.
         # @return Array<String>
         attr_reader :parent_ids
-        SemverAssistant.removing_from_public_api(context: "#{self}#parent_id", as_of: '2.0.0')
       end
 
       # @api public
@@ -106,18 +102,18 @@ module Samvera
           end.max
         end
 
+        # @api private
         def sorted_parent_ids
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           parent_ids.sort
         end
 
+        # @api private
         def sorted_pathnames
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           pathnames.sort
         end
 
+        # @api private
         def sorted_ancestors
-          SemverAssistant.removing_from_public_api(context: "#{self.class}##{__method__}", as_of: '2.0.0')
           ancestors.sort
         end
       end

data/lib/samvera/nesting_indexer/relationship_reindexer.rb

@@ -22,11 +22,13 @@ module Samvera
       # @param maximum_nesting_depth [Integer] What is the maximum allowed depth of nesting
       # @param configuration [#adapter, #logger] The :adapter conforms to the Samvera::NestingIndexer::Adapters::AbstractAdapter interface
       #                                          and the :logger conforms to Logger
+      # @param extent [String] - may be leveraged in adapter to limit the extent of the reindexing of children
       # @param queue [#shift, #push] queue
-      def initialize(id:, maximum_nesting_depth:, configuration:, queue: [])
+      def initialize(id:, maximum_nesting_depth:, configuration:, extent:, queue: [])
         @id = id.to_s
         @maximum_nesting_depth = maximum_nesting_depth.to_i
         @configuration = configuration
+        @extent = extent
         @queue = queue
       end
       attr_reader :id, :maximum_nesting_depth
@@ -43,13 +45,13 @@ module Samvera
 
       private
 
-      attr_reader :queue, :configuration
+      attr_reader :queue, :configuration, :extent
 
       def process_each_document
         processing_document = dequeue
         while processing_document
           process_a_document(processing_document)
-          adapter.each_child_document_of(document: processing_document) do |child|
+          adapter.each_child_document_of(document: processing_document, extent: extent) do |child|
             enqueue(child, processing_document.maximum_nesting_depth - 1)
           end
           processing_document = dequeue
@@ -57,7 +59,7 @@ module Samvera
       end
 
       def initial_index_document
-        adapter.find_index_document_by(id: id)
+        @initial_index_document ||= adapter.find_index_document_by(id: id)
       end
 
       extend Forwardable
@@ -127,7 +129,7 @@ module Samvera
 
         private
 
-        attr_reader :adapter
+        attr_reader :adapter, :extent
 
         def compile!
           @preservation_document.parent_ids.each do |parent_id|

data/lib/samvera/nesting_indexer/repository_reindexer.rb

@@ -22,10 +22,11 @@ module Samvera
       # @param maximum_nesting_depth [Integer] detect cycles in the graph
       # @param configuration [#adapter, #logger] The :adapter conforms to the Samvera::NestingIndexer::Adapters::AbstractAdapter interface
       #                                          and the :logger conforms to Logger
-      def initialize(maximum_nesting_depth:, id_reindexer:, configuration:)
+      def initialize(maximum_nesting_depth:, id_reindexer:, configuration:, extent:)
         @maximum_nesting_depth = maximum_nesting_depth.to_i
         @id_reindexer = id_reindexer
         @configuration = configuration
+        @extent = extent
         @processed_ids = []
       end
 
@@ -38,7 +39,7 @@ module Samvera
 
       private
 
-      attr_reader :maximum_nesting_depth, :processed_ids, :id_reindexer, :configuration
+      attr_reader :maximum_nesting_depth, :processed_ids, :id_reindexer, :configuration, :extent
 
       extend Forwardable
       def_delegator :configuration, :adapter
@@ -62,7 +63,7 @@ module Samvera
       end
 
       def reindex_an_id(id)
-        id_reindexer.call(id: id)
+        id_reindexer.call(id: id, extent: extent)
         processed_ids << id
       rescue StandardError => e
         logger.error(e)

data/lib/samvera/nesting_indexer/version.rb

@@ -1,5 +1,5 @@
 module Samvera
   module NestingIndexer
-    VERSION = "1.0.1".freeze
+    VERSION = "2.0.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: samvera-nesting_indexer
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Jeremy Friesen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-16 00:00:00.000000000 Z
+date: 2018-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -259,8 +259,9 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- documentation/README.md
 - documentation/reindex_relationship.mermaid
-- documentation/reindex_relationship.mermaid.jpg
+- documentation/reindex_relationship.mermaid.png
 - lib/generators/samvera/nesting_indexer/install_generator.rb
 - lib/generators/samvera/nesting_indexer/templates/README
 - lib/generators/samvera/nesting_indexer/templates/samvera-nesting_indexer_initializer.rb
@@ -275,7 +276,6 @@ files:
 - lib/samvera/nesting_indexer/railtie.rb
 - lib/samvera/nesting_indexer/relationship_reindexer.rb
 - lib/samvera/nesting_indexer/repository_reindexer.rb
-- lib/samvera/nesting_indexer/semver_assistant.rb
 - lib/samvera/nesting_indexer/version.rb
 - samvera-nesting_indexer.gemspec
 homepage: https://github.com/samvera-labs/samvera-nesting_indexer

data/lib/samvera/nesting_indexer/semver_assistant.rb

@@ -1,19 +0,0 @@
-require 'set'
-module Samvera
-  module NestingIndexer
-    # @api private
-    # A service object responsible for coordinating declarations of interface changes
-    module SemverAssistant
-      def self.messages
-        @messages ||= Set.new
-      end
-
-      def self.removing_from_public_api(context:, as_of:)
-        message = "As of version #{as_of}, #{context} will be removed from the public API"
-        messages << message
-        ActiveSupport::Deprecation.warn(message, caller[1..-1]) if defined?(ActiveSupport::Deprecation) && !ENV.key?('SKIP_ACTIVE_SUPPORT_DEPRECATION')
-      end
-    end
-  end
-end
-Samvera::NestingIndexer.private_constant :SemverAssistant