hyrax 3.0.2 → 3.1.0

data/app/services/hyrax/collections/collection_member_service.rb

@@ -3,7 +3,7 @@ module Hyrax
   module Collections
     ##
     # Retrieves collection members
-    class CollectionMemberService < Hyrax::SearchService
+    class CollectionMemberService
       ##
       # @param scope [#repository] Typically a controller object which responds to :repository
       # @param [::Collection] collection
@@ -12,14 +12,14 @@ module Hyrax
       # @param [::Ability] current_ability
       # @param [Class] search_builder_class a {::SearchBuilder}
       def initialize(scope:, collection:, params:, user_params: nil, current_ability: nil, search_builder_class: Hyrax::CollectionMemberSearchBuilder) # rubocop:disable Metrics/ParameterLists
-        super(
-          config: scope.blacklight_config,
-          user_params: user_params || params,
-          collection: collection,
-          scope: scope,
-          current_ability: current_ability || scope.current_ability,
-          search_builder_class: search_builder_class
-        )
+        Deprecation.warn("'##{__method__}' will be removed in Hyrax 4.0.  " \
+                         "Instead, use the same method in 'Hyrax::Collections::CollectionMemberSearchService'.")
+        @member_search_service = Hyrax::Collections::CollectionMemberSearchService(scope: scope,
+                                                                                   collection: collection,
+                                                                                   params: params,
+                                                                                   user_params: user_params,
+                                                                                   current_ability: current_ability,
+                                                                                   search_builder_class: search_builder_class)
       end
 
       ##
@@ -29,14 +29,9 @@ module Hyrax
       #
       # @return [Blacklight::Solr::Response] (up to 50 solr documents)
       def available_member_subcollections
-        response, _docs = search_results do |builder|
-          # To differentiate current page for works vs subcollections, we have to use a sub_collection_page
-          # param. Map this to the page param before querying for subcollections, if it's present
-          builder.page(user_params[:sub_collection_page])
-          builder.search_includes_models = :collections
-          builder
-        end
-        response
+        Deprecation.warn("'##{__method__}' will be removed in Hyrax 4.0.  " \
+                         "Instead, use the same method in 'Hyrax::Collections::CollectionMemberSearchService'.")
+        @member_search_service.available_member_subcollections
       end
 
       ##
@@ -46,11 +41,9 @@ module Hyrax
       #
       # @return [Blacklight::Solr::Response]
       def available_member_works
-        response, _docs = search_results do |builder|
-          builder.search_includes_models = :works
-          builder
-        end
-        response
+        Deprecation.warn("'##{__method__}' will be removed in Hyrax 4.0.  " \
+                         "Instead, use the same method in 'Hyrax::Collections::CollectionMemberSearchService'.")
+        @member_search_service.available_member_works
       end
 
       ##
@@ -60,12 +53,104 @@ module Hyrax
       #
       # @return [Blacklight::Solr::Response]
       def available_member_work_ids
-        response, _docs = search_results do |builder|
-          builder.search_includes_models = :works
-          builder.merge(fl: 'id')
-          builder
+        Deprecation.warn("'##{__method__}' will be removed in Hyrax 4.0.  " \
+                         "Instead, use the same method in 'Hyrax::Collections::CollectionMemberSearchService'.")
+        @member_search_service.available_member_work_ids
+      end
+
+      class << self
+        # Check if a work or collection is already a member of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param member [Hyrax::Resource] the child collection and/or child work to check
+        # @return [Boolean] true if already in the member set; otherwise, false
+        def member?(collection_id:, member:)
+          member.member_of_collection_ids.include? collection_id
+        end
+
+        # Add works and/or collections as members of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param new_member_ids [Enumerable<Valkyrie::ID>] the ids of the new child collections and/or child works
+        # @return [Enumerable<Hyrax::Resource>] updated member resources
+        def add_members_by_ids(collection_id:, new_member_ids:, user:)
+          new_members = Hyrax.query_service.find_many_by_ids(ids: new_member_ids)
+          add_members(collection_id: collection_id, new_members: new_members, user: user)
+        end
+
+        # Add works and/or collections as members of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param new_members [Enumerable<Hyrax::Resource>] the new child collections and/or child works
+        # @return [Enumerable<Hyrax::Resource>] updated member resources
+        def add_members(collection_id:, new_members:, user:)
+          messages = []
+          new_members.map do |new_member|
+            begin
+              add_member(collection_id: collection_id, new_member: new_member, user: user)
+            rescue Hyrax::SingleMembershipError => err
+              messages += [err.message]
+            end
+          end
+          raise Hyrax::SingleMembershipError, messages if messages.present?
+        end
+
+        # Add a work or collection as a member of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param new_member_id [Valkyrie::ID] the id of the new child collection or child work
+        # @return [Hyrax::Resource] updated member resource
+        def add_member_by_id(collection_id:, new_member_id:, user:)
+          new_member = Hyrax.query_service.find_by(id: new_member_id)
+          add_member(collection_id: collection_id, new_member: new_member, user: user)
+        end
+
+        # Add a work or collection as a member of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param new_member [Hyrax::Resource] the new child collection or child work
+        # @return [Hyrax::Resource] updated member resource
+        def add_member(collection_id:, new_member:, user:)
+          message = Hyrax::MultipleMembershipChecker.new(item: new_member).check(collection_ids: [collection_id], include_current_members: true)
+          raise Hyrax::SingleMembershipError, message if message.present?
+          new_member.member_of_collection_ids << collection_id # only populate this direction
+          new_member = Hyrax.persister.save(resource: new_member)
+          Hyrax.publisher.publish('object.metadata.updated', object: new_member, user: user)
+          new_member
+        end
+
+        # Remove collections and/or works from the members set of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param member_ids [Enumerable<Valkyrie::ID>] the ids of the child collections and/or child works to be removed
+        # @return [Enumerable<Hyrax::Resource>] updated member resources
+        def remove_members_by_ids(collection_id:, member_ids:, user:)
+          members = Hyrax.query_service.find_many_by_ids(ids: member_ids)
+          remove_members(collection_id: collection_id, members: members, user: user)
+        end
+
+        # Remove collections and/or works from the members set of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param members [Enumerable<Valkyrie::Resource>] the child collections and/or child works to be removed
+        # @return [Enumerable<Hyrax::Resource>] updated member resources
+        def remove_members(collection_id:, members:, user:)
+          members.map { |member| remove_member(collection_id: collection_id, member: member, user: user) }
+        end
+
+        # Remove collections and/or works from the members set of a collection
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param member_id [Valkyrie::ID] the id of the child collection or child work to be removed
+        # @return [Hyrax::Resource] updated member resource
+        def remove_member_by_id(collection_id:, member_id:, user:)
+          member = Hyrax.query_service.find_by(id: member_id)
+          remove_member(collection_id: collection_id, member: member, user: user)
+        end
+
+        # Remove a collection or work from the members set of a collection, also removing the inverse relationship
+        # @param collection_id [Valkyrie::ID] the id of the parent collection
+        # @param member [Hyrax::Resource] the child collection or child work to be removed
+        # @return [Hyrax::Resource] updated member resource
+        def remove_member(collection_id:, member:, user:)
+          return member unless member?(collection_id: collection_id, member: member)
+          member.member_of_collection_ids.delete(collection_id)
+          member = Hyrax.persister.save(resource: member)
+          Hyrax.publisher.publish('object.metadata.updated', object: member, user: user)
+          member
         end
-        response
       end
     end
   end

data/app/services/hyrax/collections/migration_service.rb

@@ -40,6 +40,7 @@ module Hyrax
       end
       private_class_method :migrate_collection
 
+      ##
       # @api private
       #
       # Migrate a single adminset to grant depositors and viewers read access to the admin set unless the grant is for
@@ -50,7 +51,8 @@ module Hyrax
       def self.migrate_adminset(adminset)
         Hyrax::PermissionTemplateAccess.find_or_create_by(permission_template_id: adminset.permission_template.id,
                                                           agent_type: "group", agent_id: "admin", access: "manage")
-        adminset.reset_access_controls!
+
+        adminset.permission_template.reset_access_controls_for(collection: adminset)
       end
       private_class_method :migrate_adminset
 
@@ -84,7 +86,7 @@ module Hyrax
         collection.collection_type_gid = Hyrax::CollectionType.find_or_create_default_collection_type.to_global_id
         permission_template = Hyrax::PermissionTemplate.find_by(source_id: collection.id)
         if permission_template.present?
-          collection.reset_access_controls!
+          permission_template.reset_access_controls_for(collection: collection, interpret_visibility: true)
         else
           create_permissions(collection)
         end

data/app/services/hyrax/collections/nested_collection_persistence_service.rb

@@ -7,24 +7,23 @@ module Hyrax
       # Responsible for persisting the relationship between the parent and the child.
       # @see Hyrax::Collections::NestedCollectionQueryService
       #
-      # @param parent [::Collection]
-      # @param child [::Collection]
+      # @param parent [Hyrax::PcdmCollection | ::Collection]
+      # @param child [Hyrax::PcdmCollection | ::Collection]
+      # @param user [::User] current logged in user (defaults=nil for backward compatibility)
       # @note There is odd permission arrangement based on the NestedCollectionQueryService:
       #       You can nest the child within a parent if you can edit the parent and read the child.
       #       See https://wiki.lyrasis.org/display/samvera/Samvera+Tech+Call+2017-08-23 for tech discussion.
-      # @note Adding the member_of_collections method doesn't trigger reindexing of the child so we have to do it manually.
-      #       However it save and reindexes the parent unnecessarily!!
-      def self.persist_nested_collection_for(parent:, child:)
-        parent.reindex_extent = Hyrax::Adapters::NestingIndexAdapter::LIMITED_REINDEX
-        child.member_of_collections.push(parent)
-        child.update_nested_collection_relationship_indices
+      def self.persist_nested_collection_for(parent:, child:, user: nil)
+        child_resource = child.respond_to?(:valkyrie_resource) ? child.valkyrie_resource : child
+        Hyrax::Collections::CollectionMemberService.add_member(collection_id: parent.id, new_member: child_resource, user: user)
       end
 
-      # @note Removing the member_of_collections method doesn't trigger reindexing of the child so we have to do it manually.
-      #       However it doesn't save and reindex the parent, as it does when a parent is added!!
-      def self.remove_nested_relationship_for(parent:, child:)
-        child.member_of_collections.delete(parent)
-        child.update_nested_collection_relationship_indices
+      # @param parent [Hyrax::PcdmCollection | ::Collection]
+      # @param child [Hyrax::PcdmCollection | ::Collection]
+      # @param user [::User] current logged in user (defaults=nil for backward compatibility)
+      def self.remove_nested_relationship_for(parent:, child:, user: nil)
+        child_resource = child.respond_to?(:valkyrie_resource) ? child.valkyrie_resource : child
+        Hyrax::Collections::CollectionMemberService.remove_member(collection_id: parent.id, member: child_resource, user: user)
         true
       end
     end

data/app/services/hyrax/collections/nested_collection_query_service.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 module Hyrax
   module Collections
+    ##
+    # A query service handling nested collection queries.
     module NestedCollectionQueryService
       ##
       # @api private

data/app/services/hyrax/collections/permissions_create_service.rb

@@ -13,9 +13,10 @@ module Hyrax
       def self.create_default(collection:, creating_user:, grants: [])
         collection_type = Hyrax::CollectionType.find_by_gid!(collection.collection_type_gid)
         access_grants = access_grants_attributes(collection_type: collection_type, creating_user: creating_user, grants: grants)
-        PermissionTemplate.create!(source_id: collection.id,
-                                   access_grants_attributes: access_grants.uniq)
-        collection.reset_access_controls!
+        template = PermissionTemplate.create!(source_id: collection.id,
+                                              access_grants_attributes: access_grants.uniq)
+
+        template.reset_access_controls_for(collection: collection, interpret_visibility: true)
       end
 
       # @api public
@@ -38,7 +39,8 @@ module Hyrax
                                                             agent_id: grant[:agent_id],
                                                             access: grant[:access])
         end
-        collection.reset_access_controls!
+
+        template.reset_access_controls_for(collection: collection, interpret_visibility: true)
       end
 
       # @api private

data/app/services/hyrax/contextual_path.rb

@@ -1,14 +1,37 @@
 # frozen_string_literal: true
 module Hyrax
+  ##
+  # @api public
+  #
+  # Provides a polymorphic path for a target object (presenter) nested under the
+  # path of the parent, if given.
+  #
+  # @see WorkShowPresenter#contextual_path
+  #
+  # @example
+  #   Hyrax::ContextualPath.new(my_file_set, parent_object).show
+  #   # => "/concerns/parent/id4parent/file_sets/id4file_set"
+  #
+  # @example with a nil parent
+  #   Hyrax::ContextualPath.new(my_file_set, nil).show
+  #   # => "/concerns/file_sets/id4file_set"
+  #
   class ContextualPath
     include Rails.application.routes.url_helpers
     include ActionDispatch::Routing::PolymorphicRoutes
     attr_reader :presenter, :parent_presenter
+
+    ##
+    # @param presenter [#model_name] an ActiveModel-like target object
+    # @param parent_presenter [#id, nil] an ActiveModel-like presenter for the
+    #   target's parent
     def initialize(presenter, parent_presenter)
       @presenter = presenter
       @parent_presenter = parent_presenter
     end
 
+    ##
+    # @return [String]
     def show
       if parent_presenter
         polymorphic_path([:hyrax, :parent, presenter.model_name.singular.to_sym],

data/app/services/hyrax/custom_queries/find_file_metadata.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
-# Provide custom queries for finding Hyrax::FileMetadata
-# @example
-#   Hyrax.custom_queries.find_file_metadata_by(id: valkyrie_id)
-#   Hyrax.custom_queries.find_file_metadata_by_alternate_identifier(alternate_identifier: alt_id)
-#   Hyrax.custom_queries.find_many_file_metadata_by_ids(ids: [valkyrie_id, valkyrie_id])
 module Hyrax
   module CustomQueries
+    ##
+    # Provide custom queries for finding Hyrax::FileMetadata
+    #
+    # @example
+    #   Hyrax.custom_queries.find_file_metadata_by(id: valkyrie_id)
+    #   Hyrax.custom_queries.find_file_metadata_by_alternate_identifier(alternate_identifier: alt_id)
+    #   Hyrax.custom_queries.find_many_file_metadata_by_ids(ids: [valkyrie_id, valkyrie_id])
     class FindFileMetadata
       def self.queries
         [:find_file_metadata_by,

data/app/services/hyrax/custom_queries/navigators/parent_collections_navigator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module CustomQueries
+    module Navigators
+      ##
+      # Navigate from a resource to the parent collections of the resource.
+      #
+      # @see https://github.com/samvera/valkyrie/wiki/Queries#custom-queries
+      # @since 3.0.0
+      class ParentCollectionsNavigator
+        # Define the queries that can be fulfilled by this navigator.
+        def self.queries
+          [:find_parent_collections, :find_parent_collection_ids]
+        end
+
+        attr_reader :query_service
+
+        def initialize(query_service:)
+          @query_service = query_service
+        end
+
+        ##
+        # Find parent collections of a given resource, and map to Valkyrie Resources
+        #
+        # @param [Valkyrie::Resource] resource
+        #
+        # @return [Array<Valkyrie::Resource>]
+        def find_parent_collections(resource:)
+          query_service
+            .find_many_by_ids(ids: find_parent_collection_ids(resource: resource))
+        end
+
+        ##
+        # Find the ids of parent collections of a given resource, and map to Valkyrie Resources IDs
+        #
+        # @param [Valkyrie::Resource] resource
+        #
+        # @return [Array<Valkyrie::ID>]
+        def find_parent_collection_ids(resource:)
+          resource.member_of_collection_ids
+        end
+      end
+    end
+  end
+end

data/app/services/hyrax/edit_permissions_service.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 module Hyrax
+  ##
+  # @api public
+  #
   # Encapsulates the logic to determine which object permissions may be edited by a given user
-  #  - user is permitted to update any work permissions coming ONLY from collections they manage
-  #  - user is not permitted to update a work permission if it comes from a collection they do not manage, even if also from a managed collection
-  #  - user is permitted to update only non-manager permissions from any Collections
-  #  - user is permitted to update any non-collection permissions
+  # * user is permitted to update any work permissions coming ONLY from collections they manage
+  # * user is not permitted to update a work permission if it comes from a collection they do not manage, even if also from a managed collection
+  # * user is permitted to update only non-manager permissions from any Collections
+  # * user is permitted to update any non-collection permissions
   class EditPermissionsService
+    ##
     # @api public
     # @since v3.0.0
     #
@@ -14,15 +18,15 @@ module Hyrax
     # @return [Hyrax::EditPermissionService]
     #
     # @note
-    #   form object.class = SimpleForm::FormBuilder
-    #     For works (i.e. GenericWork):
-    #     - form object.object = Hyrax::GenericWorkForm
-    #     - form object.object.model = GenericWork
-    #     - use the work itself
-    #     For file_sets:
-    #     - form object.object.class = FileSet
-    #     - use work the file_set is in
-    #     No other object types are supported by this view. %>
+    #   +form object.class = SimpleForm::FormBuilder+
+    #    For works (i.e. GenericWork):
+    #    * form object.object = Hyrax::GenericWorkForm
+    #    * form object.object.model = GenericWork
+    #    * use the work itself
+    #    For file_sets:
+    #    * form object.object.class = FileSet
+    #    * use work the file_set is in
+    #    No other object types are supported by this view.
     def self.build_service_object_from(form:, ability:)
       if form.object.respond_to?(:model) && form.object.model.work?
         new(object: form.object, ability: ability)
@@ -33,7 +37,9 @@ module Hyrax
 
     attr_reader :depositor, :unauthorized_collection_managers
 
-    # @param object [#depositor, #admin_set_id, #member_of_collection_ids] GenericWorkForm (if called for object) or GenericWork (if called for file set)
+    ##
+    # @param object [#depositor, #admin_set_id, #member_of_collection_ids]
+    #   +GenericWorkForm+ (if called for object) or +GenericWork+ (if called for file set)
     # @param ability [Ability] user's current_ability
     def initialize(object:, ability:)
       @object = object
@@ -47,7 +53,7 @@ module Hyrax
     # @api private
     # @todo refactor this code to use "can_edit?"; Thinking in negations can be challenging.
     #
-    # @param permission_hash [Hash] one set of permission fields for object {:name, :access}
+    # @param permission_hash [Hash] one set of permission fields for object +:name+, :access}
     # @return [Boolean] true if user cannot edit the given permissions
     def cannot_edit_permissions?(permission_hash)
       permission_hash.fetch(:access) == "edit" && @unauthorized_managers.include?(permission_hash.fetch(:name))
@@ -55,7 +61,7 @@ module Hyrax
 
     # @api private
     #
-    # @param permission_hash [Hash] one set of permission fields for object {:name, :access}
+    # @param permission_hash [Hash] one set of permission fields for object +:name+, +:access+
     # @return [Boolean] true if given permissions are one of fixed exclusions
     def excluded_permission?(permission_hash)
       exclude_from_display.include? permission_hash.fetch(:name).downcase
@@ -68,9 +74,10 @@ module Hyrax
     # * returns false if the given permission_hash is part of the fixed exclusions.
     # * yields a PermissionPresenter to provide additional logic and text for rendering
     #
-    # @param permission_hash [Hash<:name, :access>]
-    # @return false if the given permission_hash is a fixed exclusion
-    # @yield PermissionPresenter
+    # @param permission_hash [Hash{Symbol => Object}]
+    #
+    # @return [Boolean] +false+ if the given +permission_hash+ is a fixed exclusion
+    # @yield [PermissionPresenter]
     #
     # @see #excluded_permission?
     def with_applicable_permission(permission_hash:)
@@ -81,7 +88,7 @@ module Hyrax
     # @api private
     #
     # A helper class to contain specific presentation logic related to
-    # the EditPermissionsService
+    # the {EditPermissionsService}
     class PermissionPresenter
       # @param service [Hyrax::EditPermissionsService]
       # @param permission_hash [Hash]