Add separate endpoint for create and invite participant group methods to RecruitmentService

Also marks `InviteNewParticipantGroup` Endpoint and related method as deprecated, and replace their usage with new create and invite method respectively.

Author: yuanchen233

carp.studies.core/src/commonMain/kotlin/dk/cachet/carp/studies/application/RecruitmentService.kt

@@ -74,14 +74,53 @@ interface RecruitmentService : ApplicationService<RecruitmentService, Recruitmen
      *  - not all necessary participant roles part of the study have been assigned a participant
      * @throws IllegalStateException when the study is not yet ready for deployment.
      */
+    @Deprecated(
+        "Use createParticipantGroup and inviteParticipantGroup instead",
+        ReplaceWith(
+            "inviteParticipantGroup( studyId, createParticipantGroup( studyId, UUID.randomUUID(), group, name ).id )",
+            "dk.cachet.carp.common.application.UUID"
+        ),
+        level = DeprecationLevel.WARNING
+    )
     suspend fun inviteNewParticipantGroup(
         studyId: UUID,
         group: Set<AssignedParticipantRoles>,
         name: String? = null
     ): ParticipantGroupStatus
 
     /**
-     * Get the status of all deployed participant groups in the study with the specified [studyId].
+     * Create a new participant [group] of previously added participants for the study with the given [studyId],
+     * and an optional [name] representing this group, but do not yet send out invitations.
+     * This is used to create a group of participants which can be deployed at a later time.
+     *
+     * When [groupId] identifies an existing group, the latest status for this group is returned.
+     *
+     * @throws IllegalArgumentException when:
+     *  - a study with [studyId] does not exist
+     *  - an existing participant group with [groupId] has a different configuration
+     *  - any of the participant roles specified in [group] does not exist
+     * @throws IllegalStateException when the study is not yet ready for deployment.
+     */
+    suspend fun createParticipantGroup(
+        studyId: UUID,
+        groupId: UUID,
+        group: Set<AssignedParticipantRoles>,
+        name: String? = null
+    ): ParticipantGroupStatus
+
+    /**
+     * Invite the participant group with the specified [groupId]
+     * in the study with the given [studyId] to start participating in the study.
+     *
+     * @throws IllegalArgumentException when:
+     *  - a study with [studyId] or participant group with [groupId] does not exist.
+     *  - not all necessary participant roles part of the study have been assigned a participant
+     * @throws IllegalStateException when group has already been deployed.
+     */
+    suspend fun inviteParticipantGroup( studyId: UUID, groupId: UUID ): ParticipantGroupStatus
+
+    /**
+     * Get the status of all participant groups in the study with the specified [studyId].
      *
      * @throws IllegalArgumentException when a study with [studyId] does not exist.
      */

carp.studies.core/src/commonMain/kotlin/dk/cachet/carp/studies/application/RecruitmentServiceHost.kt

@@ -16,6 +16,7 @@ import dk.cachet.carp.studies.application.users.Participant
 import dk.cachet.carp.studies.application.users.ParticipantGroupStatus
 import dk.cachet.carp.studies.domain.users.ParticipantRepository
 import dk.cachet.carp.studies.domain.users.Recruitment
+import dk.cachet.carp.studies.domain.users.StagedParticipantGroup
 import kotlinx.datetime.Clock
 
 
@@ -124,57 +125,153 @@ class RecruitmentServiceHost(
      *  - not all necessary participant roles part of the study have been assigned a participant
      * @throws IllegalStateException when the study is not yet ready for deployment.
      */
+    @Deprecated(
+        "Use createParticipantGroup and inviteParticipantGroup instead",
+        replaceWith = ReplaceWith(
+            "inviteParticipantGroup( studyId, createParticipantGroup( studyId, UUID.randomUUID(), group, name ).id )",
+            "dk.cachet.carp.common.application.UUID"
+        )
+    )
     override suspend fun inviteNewParticipantGroup(
         studyId: UUID,
         group: Set<AssignedParticipantRoles>,
         name: String?
     ): ParticipantGroupStatus
     {
         val recruitment = getRecruitmentOrThrow( studyId )
-        val (protocol, invitations) = recruitment.createInvitations( group )
+        // Support the deprecated API by reusing groups that were created through repeated calls with the same
+        // configuration (participants + name) even when no explicit groupId is supplied.
+        val existingByConfiguration = recruitment.participantGroups.entries.firstOrNull { (_, existingGroup) ->
+            existingGroup.roleAssignments == group && existingGroup.name == name
+        }
+        if ( existingByConfiguration != null )
+        {
+            val (existingId, existingGroup) = existingByConfiguration
+            if ( !existingGroup.isDeployed )
+            {
+                // A staged group should still go through the deprecated flow and trigger invitations.
+                return inviteParticipantGroup( studyId, existingId )
+            }
 
-        // In case the same participants with the same roles have been invited with the same group name before,
-        // and that deployment is still running, return the existing group.
-        val deployedStatus = recruitment.participantGroups.entries
-            .firstOrNull { (_, existingGroup) ->
-                existingGroup.roleAssignments == group && existingGroup.name == name
+            val deploymentStatus = deploymentService.getStudyDeploymentStatus( existingId )
+            if ( deploymentStatus !is StudyDeploymentStatus.Stopped )
+            {
+                return recruitment.getParticipantGroupStatus( deploymentStatus )
             }
-            ?.let { deploymentService.getStudyDeploymentStatus( it.key ) }
-        if ( deployedStatus != null && deployedStatus !is StudyDeploymentStatus.Stopped )
+        }
+
+        val participantGroupStatus = createParticipantGroup( studyId, uuidFactory.randomUUID(), group, name )
+
+        if ( participantGroupStatus is ParticipantGroupStatus.InDeployment )
         {
-            return recruitment.getParticipantGroupStatus( deployedStatus )
+            // Already deployed.
+            return participantGroupStatus
         }
 
-        // Create participant group and mark as deployed.
-        val participantGroup = recruitment.addParticipantGroup( group, name, uuidFactory.randomUUID() )
-        participantGroup.markAsDeployed()
+        // Create study deployment, which sends out invitations.
+        // TODO: If createParticipantGroup succeeds, but inviteParticipantGroup fails, repository state will be inconsistent.
+        //  This should use eventual consistency: https://github.com/imotions/carp.core-kotlin/issues/295
+
+        return inviteParticipantGroup( studyId, participantGroupStatus.id )
+    }
+
+    /**
+     * Create a new participant [group] of previously added participants for the study with the given [studyId],
+     * and an optional [name] representing this group, but do not yet send out invitations.
+     * This is used to create a group of participants which can be deployed at a later time.
+     *
+     * When [groupId] identifies an existing group, the latest status for this group is returned.
+     *
+     * @throws IllegalArgumentException when:
+     *  - a study with [studyId] does not exist
+     *  - any of the participant roles specified in [group] does not exist
+     *  - an existing participant group with [groupId] has a different configuration
+     * @throws IllegalStateException when the study is not yet ready for deployment.
+     */
+    override suspend fun createParticipantGroup(
+        studyId: UUID,
+        groupId: UUID,
+        group: Set<AssignedParticipantRoles>,
+        name: String?
+    ): ParticipantGroupStatus
+    {
+        val recruitment = getRecruitmentOrThrow( studyId )
+
+        // When the specified groupId already exists, ensure the configuration matches and return it.
+        val existingById = recruitment.participantGroups[ groupId ]
+        if ( existingById != null )
+        {
+            require( existingById.roleAssignments == group ) {
+                "Participant group with ID \"$groupId\" exists but has different role assignments."
+            }
+            require( existingById.name == name ) {
+                "Participant group with ID \"$groupId\" exists but has a different name."
+            }
+
+            return if ( existingById.isDeployed )
+            {
+                val deploymentStatus = deploymentService.getStudyDeploymentStatus( groupId )
+                recruitment.getParticipantGroupStatus( deploymentStatus )
+            }
+            else recruitment.getParticipantGroupStatus( existingById )
+        }
+
+        // Otherwise, create participant group but do not deploy yet.
+        val participantGroup = recruitment.addParticipantGroup( group, name, groupId )
         participantRepository.updateRecruitment( recruitment )
+        return recruitment.getParticipantGroupStatus( participantGroup )
+    }
+
+    /**
+     * Invite the participant group with the specified [groupId]
+     * in the study with the given [studyId] to start participating in the study.
+     *
+     * @throws IllegalArgumentException when:
+     *  - a study with [studyId] or participant group with [groupId] does not exist.
+     *  - not all necessary participant roles part of the study have been assigned a participant
+     * @throws IllegalStateException when group has already been deployed.
+     */
+    override suspend fun inviteParticipantGroup( studyId: UUID, groupId: UUID ): ParticipantGroupStatus
+    {
+        val (recruitment, participantGroup) = getRecruitmentAndGroupOrThrow( studyId, groupId )
+        check( !participantGroup.isDeployed ) { "Participant group has already been deployed." }
 
-        // Create study deployment, which sends out invitations.
         // TODO: If the repository gets updated but `createStudyDeployment` fails, state will be inconsistent.
         //  This should use eventual consistency: https://github.com/imotions/carp.core-kotlin/issues/295
-        //  And probably be separate requests: https://github.com/imotions/carp.core-kotlin/issues/319
+
+        val (protocol, invitations) = recruitment.createInvitations( participantGroup.roleAssignments )
         val deploymentStatus = deploymentService.createStudyDeployment( participantGroup.id, protocol, invitations )
 
+        // Mark participant group as deployed.
+        participantGroup.markAsDeployed()
+        participantRepository.updateRecruitment( recruitment )
         return recruitment.getParticipantGroupStatus( deploymentStatus )
     }
 
     /**
-     * Get the status of all deployed participant groups in the study with the specified [studyId].
+     * Get the status of all participant groups in the study with the specified [studyId].
      *
      * @throws IllegalArgumentException when a study with [studyId] does not exist.
      */
     override suspend fun getParticipantGroupStatusList( studyId: UUID ): List<ParticipantGroupStatus>
     {
         val recruitment: Recruitment = getRecruitmentOrThrow( studyId )
 
+        // Get status list for staged participant groups.
+        val stagedParticipantGroups = recruitment.participantGroups
+            .filter { !it.value.isDeployed }
+            .values
+            .map { recruitment.getParticipantGroupStatus( it ) }
+
         // Get study deployment status list.
-        val studyDeploymentIds = recruitment.participantGroups.keys
+        val deployedStudyDeploymentIds = recruitment.participantGroups.filter { it.value.isDeployed }.keys
+
+        // Get status list for deployed participant groups.
         val studyDeploymentStatusList: List<StudyDeploymentStatus> =
-            if ( studyDeploymentIds.isEmpty() ) emptyList()
-            else deploymentService.getStudyDeploymentStatusList( studyDeploymentIds )
+            if ( deployedStudyDeploymentIds.isEmpty() ) emptyList()
+            else deploymentService.getStudyDeploymentStatusList( deployedStudyDeploymentIds )
 
-        return studyDeploymentStatusList.map { recruitment.getParticipantGroupStatus( it ) }
+        return stagedParticipantGroups + studyDeploymentStatusList.map { recruitment.getParticipantGroupStatus( it ) }
     }
 
     /**
@@ -186,19 +283,22 @@ class RecruitmentServiceHost(
      */
     override suspend fun stopParticipantGroup( studyId: UUID, groupId: UUID ): ParticipantGroupStatus
     {
-        val recruitment = getRecruitmentWithGroupOrThrow( studyId, groupId )
+        val (recruitment, _) = getRecruitmentAndGroupOrThrow( studyId, groupId )
 
         val deploymentStatus = deploymentService.stop( groupId )
         return recruitment.getParticipantGroupStatus( deploymentStatus )
     }
 
-    private suspend fun getRecruitmentWithGroupOrThrow( studyId: UUID, groupId: UUID ): Recruitment
+    private suspend fun getRecruitmentAndGroupOrThrow(
+        studyId: UUID,
+        groupId: UUID
+    ): Pair<Recruitment, StagedParticipantGroup>
     {
         val recruitment: Recruitment = getRecruitmentOrThrow( studyId )
         val participations = recruitment.participantGroups[ groupId ]
         requireNotNull( participations ) { "Study deployment with the specified groupId not found." }
 
-        return recruitment
+        return recruitment to participations
     }
 
     private suspend fun getRecruitmentOrThrow( studyId: UUID ): Recruitment =

carp.studies.core/src/commonMain/kotlin/dk/cachet/carp/studies/domain/users/Recruitment.kt

@@ -215,16 +215,34 @@ class Recruitment( val studyId: UUID, id: UUID = UUID.randomUUID(), createdOn: I
         val deploymentId = studyDeploymentStatus.studyDeploymentId
         val group: StagedParticipantGroup = requireNotNull( _participantGroups[ deploymentId ] )
             { "A study deployment with ID \"$deploymentId\" is not part of this recruitment." }
-
-        val participants = group.participantIds.map { id -> _participants.first { it.id == id } }
+        val participants = getParticipantsFor( group )
         return ParticipantGroupStatus.InDeployment.fromDeploymentStatus(
-            participants.toSet(),
+            participants,
             group.roleAssignments,
             studyDeploymentStatus,
             group.name
         )
     }
 
+    /**
+     * Get the [ParticipantGroupStatus] for the staged participant [group].
+     *
+     * @throws IllegalArgumentException when the specified [group] is not part of this recruitment.
+     */
+    fun getParticipantGroupStatus( group: StagedParticipantGroup ): ParticipantGroupStatus.Staged
+    {
+        val participants = getParticipantsFor( group )
+        return ParticipantGroupStatus.Staged(
+            id = group.id,
+            participants = participants,
+            assignedParticipantRoles = group.roleAssignments,
+            name = group.name
+        )
+    }
+
+    private fun getParticipantsFor( group: StagedParticipantGroup ): Set<Participant> =
+        group.participantIds.map { id -> _participants.first { it.id == id } }.toSet()
+
     /**
      * Get an immutable snapshot of the current state of this [Recruitment] using the specified snapshot [version].
      */

carp.studies.core/src/commonMain/kotlin/dk/cachet/carp/studies/infrastructure/RecruitmentServiceDecorator.kt

@@ -33,12 +33,30 @@ class RecruitmentServiceDecorator(
     override suspend fun getParticipants( studyId: UUID ) =
         invoke( RecruitmentServiceRequest.GetParticipants( studyId ) )
 
+    @Deprecated(
+        "Use CreateParticipantGroup and InviteParticipantGroup instead",
+        ReplaceWith(
+            "inviteParticipantGroup( studyId, createParticipantGroup( studyId, UUID.randomUUID(), group, name ).id )",
+            "dk.cachet.carp.common.application.UUID"
+        )
+    )
+    @Suppress( "DEPRECATION" )
     override suspend fun inviteNewParticipantGroup(
         studyId: UUID,
         group: Set<AssignedParticipantRoles>,
         name: String?
     ) = invoke( RecruitmentServiceRequest.InviteNewParticipantGroup( studyId, group, name ) )
 
+    override suspend fun createParticipantGroup(
+        studyId: UUID,
+        groupId: UUID,
+        group: Set<AssignedParticipantRoles>,
+        name: String?
+    ) = invoke( RecruitmentServiceRequest.CreateParticipantGroup( studyId, groupId, group, name ) )
+
+    override suspend fun inviteParticipantGroup( studyId: UUID, groupId: UUID ) =
+        invoke( RecruitmentServiceRequest.InviteParticipantGroup( studyId, groupId ) )
+
     override suspend fun getParticipantGroupStatusList( studyId: UUID ) =
         invoke( RecruitmentServiceRequest.GetParticipantGroupStatusList( studyId ) )
 
@@ -49,6 +67,7 @@ class RecruitmentServiceDecorator(
 
 object RecruitmentServiceInvoker : ApplicationServiceInvoker<RecruitmentService, RecruitmentServiceRequest<*>>
 {
+    @Suppress( "DEPRECATION" )
     override suspend fun RecruitmentServiceRequest<*>.invoke( service: RecruitmentService ): Any =
         when ( this )
         {
@@ -58,6 +77,9 @@ object RecruitmentServiceInvoker : ApplicationServiceInvoker<RecruitmentService,
             is RecruitmentServiceRequest.GetParticipants -> service.getParticipants( studyId )
             is RecruitmentServiceRequest.InviteNewParticipantGroup ->
                 service.inviteNewParticipantGroup( studyId, group, name )
+            is RecruitmentServiceRequest.CreateParticipantGroup ->
+                service.createParticipantGroup( studyId, groupId, group, name )
+            is RecruitmentServiceRequest.InviteParticipantGroup -> service.inviteParticipantGroup( studyId, groupId )
             is RecruitmentServiceRequest.GetParticipantGroupStatusList ->
                 service.getParticipantGroupStatusList( studyId )
             is RecruitmentServiceRequest.StopParticipantGroup -> service.stopParticipantGroup( studyId, groupId )

carp.studies.core/src/commonMain/kotlin/dk/cachet/carp/studies/infrastructure/RecruitmentServiceRequest.kt

@@ -65,6 +65,7 @@ sealed class RecruitmentServiceRequest<out TReturn> : ApplicationServiceRequest<
     }
 
     @Serializable
+    @Deprecated( "Use CreateParticipantGroup and InviteParticipantGroup instead." )
     data class InviteNewParticipantGroup(
         val studyId: UUID,
         val group: Set<AssignedParticipantRoles>,
@@ -75,6 +76,28 @@ sealed class RecruitmentServiceRequest<out TReturn> : ApplicationServiceRequest<
         override fun getResponseSerializer() = serializer<ParticipantGroupStatus>()
     }
 
+    @Serializable
+    data class CreateParticipantGroup(
+        val studyId: UUID,
+        val groupId: UUID,
+        val group: Set<AssignedParticipantRoles>,
+        val name: String? = null
+    ) :
+        RecruitmentServiceRequest<ParticipantGroupStatus>()
+    {
+        override fun getResponseSerializer() = serializer<ParticipantGroupStatus>()
+    }
+
+    @Serializable
+    data class InviteParticipantGroup(
+        val studyId: UUID,
+        val groupId: UUID
+    ) :
+        RecruitmentServiceRequest<ParticipantGroupStatus>()
+    {
+        override fun getResponseSerializer() = serializer<ParticipantGroupStatus>()
+    }
+
     @Serializable
     data class GetParticipantGroupStatusList( val studyId: UUID ) :
         RecruitmentServiceRequest<List<ParticipantGroupStatus>>()