Activity flow api changes.

[aditya-07]

IMPORTANT: All PRs must be linked to an issue (except for extremely trivial and straightforward changes).

Fixes #2469

Description
Api for creating a flow to move a request through various phases of an ActivityFlow.

The class ActivityFlow has two main functionalities:

1. Allow users to get access to the current Phase.
2. Allow users to move to next phase of the activity flow.
3. To move to the next phase, user may first call the api to create a draft Resource for the new phase and then start that phase. These correspond with the begin and end api of the ActivityFlow.
   e.g. ActivityFlow.draftPlan corresponds to beginPlan and ActivityFlow.startPlan corresponds to endPlan .

The Phase class has two distinct hierarchies RequestPhase and EventPhase each with unique apis to allow valid state transitions for Request based phases (Proposal, Plan and Order) and Event based phases (Perform) respectively.

ActivityFlow provides various ActivityFlow.of static api to help user create ActivityFlow for particular activities with particular request or event types.

Alternative(s) considered
Have you considered any alternatives? And if so, why have you chosen the approach in this PR?

Type
Choose one: (Bug fix | Feature | Documentation | Testing | Code health | Builds | Releases | Other)

Screenshots (if applicable)

Checklist

• I have read and acknowledged the Code of conduct.
• I have read the Contributing page.
• I have signed the Google Individual CLA, or I am covered by my company's Corporate CLA.
• I have discussed my proposed solution with code owners in the linked issue(s) and we have agreed upon the general approach.
• I have run ./gradlew spotlessApply and ./gradlew spotlessCheck to check my code follows the style guide of this project.
• I have run ./gradlew check and ./gradlew connectedCheck to test my changes locally.
• I have built and run the demo app(s) to verify my change fixes the issue and/or does not break the demo app(s).

[jingtang10]

can you add a page in the doc folder?

[jingtang10]

just noting comments from bryn:

1. Can we change "draft" to "prepare"
2. Can we change "start" to "submit"
3. Can we change "resume" in the test cases to "continue"?

[MJ1998]

Thanks Aditya for the changes.
2 main concerns:-

1. Should we consider making the operations asynchronous ? Since we are dealing with Repository it only makes sense to do the operations in a IO coroutine. Suggesting to make the initiate and update methods suspend functions.
2. Do you think we should add a rollback api ? If there are errors in later phases one might want to rollback. To do this we could maintain a stack pf phases instead of only the currentPhase.

[aditya-07]

Thanks Aditya for the changes. 2 main concerns:-

1. Should we consider making the operations asynchronous ? Since we are dealing with Repository it only makes sense to do the operations in a IO coroutine. Suggesting to make the initiate and update methods suspend functions.
2. Do you think we should add a rollback api ? If there are errors in later phases one might want to rollback. To do this we could maintain a stack pf phases instead of only the currentPhase.

1. Since we are working with Repository java interface and its implementation does a runBlocking call, it is better to keep it non-suspending. I have added a note to emphasize the use of worker thread when accessing AcivityFlow/ Phase apis.

2. Once a new phase is initiated, its success marks the previous phase as Completed (status of the request in previous phase is updated to completed). The expectation is that once a Request is completed, it should never be mutated later.
   Keeping that in mind, I don't think we can allow phase rollback.
   Unless everything is OK, user won't be allow to initiate a new phase and once user is in new phase, old phase is completed.

[MJ1998]

LGTM.