Azure / Azure/azure-sdk-for-java
[MGMT] discussion, what to improve on LRO in core-v2
- Dominant language
- Java
- Stars
- 2.6k
- Forks
- 2.2k
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 178
Description
## Context / Requirement
LRO in mgmt follows a certain pattern, which is quite different from data-plane.
1. The response of PUT or PATCH is the resource, with `provisioningState` indicate the LRO state.
2. The response of PUT or PATCH could be 200, with `provisioningState=Succeeded` (e.g. when the resource exists in backend and there is no difference). In this case, no polling is needed (not GET need to be sent).
3. The `id` in response of PUT or PATCH is important for customer. They can use it to query the resource. In some case, it can be used to query info related to this resource (e.g. in ARM template `deployment`, the `id` is used to query the details of this deployment).
Therefore, mgmt would like
1. Poller can return the response of the PUT or PATCH (the response of the activation/initial operation).
2. API/Poller gives consistence exception (particularly, `ManagementException` on `poller.getFinalResult`) when failed to create resource.
## Current (v1)
mgmt implemented this [design](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/resourcemanager/docs/DESIGN_PREVIEW.md) for some LRO APIs
```java
// API, throws com.azure.core.management.exception.ManagementException If fails to create/update resource.
Deployment createOrUpdate(...);
Accepted beginCreateOrUpdate(...);
// interface
public interface Accepted {
/**
* Gets the activation response of LRO.
*
* @return the activation response
*/
ActivationResponse getActivationResponse();
/**
* Gets the {@link SyncPoller} of LRO.
*
* @return the sync poller.
*/
SyncPoller getSyncPoller();
/**
* Gets the final result of LRO.
*
* @return the final result.
* @throws com.azure.core.management.exception.ManagementException If polling fails.
*/
U getFinalResult();
}
```
for the LRO PUT/POST/DELETE.
(for DELETE, `T=Void`)
The `getFinalResult()` is just a wrapper of `getSyncPoller().getFinalResult()`.
The `SyncPoller` would throw a `ManagementException` if LRO is not `Succeeded`. Otherwise, it be same as typical `SyncPoller`.
related classes
- [Accepted](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/resourcemanager/azure-resourcemanager-resources/src/main/java/com/azure/resourcemanager/resources/fluentcore/model/Accepted.java)
- [ActivationResponse](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/resourcemanager/azure-resourcemanager-resources/src/main/java/com/azure/resourcemanager/resources/fluentcore/rest/ActivationResponse.java) (it is just `SimpleResponse` + LRO state + retryAfter)
- [AcceptedImpl](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/resourcemanager/azure-resourcemanager-resources/src/main/java/com/azure/resourcemanager/resources/fluentcore/model/implementation/AcceptedImpl.java)
## v2
We'd like to explore
1. Whether we should have such pattern built-in to mgmt codegen
2. Whether we should build the pattern into the subclass of [Poller](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core-v2/azure-core/src/main/java/com/azure/v2/core/http/polling/Poller.java), e.g.
```java
public final class ManagementPoller implements Poller {
public ActivationResponse getActivationResponse();
...
}
```
3. What do we do to POST (resource action)
Contributor guide
Assessment
This issue has not been assessed yet.