From 171ee474c0f6a053a56701aebfb80da082241f53 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Richard=20K=C3=B6rber?= <github@shredzone.org>
Date: Sun, 18 Aug 2024 11:42:50 +0200
Subject: [PATCH] Deprecate update() and AcmeRetryAfterException

---
 .../src/main/java/org/shredzone/acme4j/AcmeJsonResource.java  | 4 ++++
 .../shredzone/acme4j/exception/AcmeRetryAfterException.java   | 3 +++
 src/doc/docs/migration.md                                     | 1 +
 3 files changed, 8 insertions(+)

diff --git a/acme4j-client/src/main/java/org/shredzone/acme4j/AcmeJsonResource.java b/acme4j-client/src/main/java/org/shredzone/acme4j/AcmeJsonResource.java
index 82df6fea..255473af 100644
--- a/acme4j-client/src/main/java/org/shredzone/acme4j/AcmeJsonResource.java
+++ b/acme4j-client/src/main/java/org/shredzone/acme4j/AcmeJsonResource.java
@@ -123,7 +123,11 @@ public abstract class AcmeJsonResource extends AcmeResource {
      *         {@link AcmeRetryAfterException#getRetryAfter()}. Note that the status of
      *         the resource is updated even if this exception was thrown.
      * @see #fetch()
+     * @deprecated Use {@link #fetch()} instead. It returns the retry-after value as
+     * {@link Optional} instead of throwing an {@link AcmeRetryAfterException}. This
+     * method will be removed in a future version.
      */
+    @Deprecated
     public void update() throws AcmeException {
         var retryAfter = fetch();
         if (retryAfter.isPresent()) {
diff --git a/acme4j-client/src/main/java/org/shredzone/acme4j/exception/AcmeRetryAfterException.java b/acme4j-client/src/main/java/org/shredzone/acme4j/exception/AcmeRetryAfterException.java
index fd7f8931..97ffd18c 100644
--- a/acme4j-client/src/main/java/org/shredzone/acme4j/exception/AcmeRetryAfterException.java
+++ b/acme4j-client/src/main/java/org/shredzone/acme4j/exception/AcmeRetryAfterException.java
@@ -25,7 +25,10 @@ import org.shredzone.acme4j.AcmeJsonResource;
  * Note: Prefer to use {@link AcmeJsonResource#fetch()}. Invoking
  * {@link AcmeJsonResource#update()} and catching this exception is unnecessary
  * complicated and a legacy from acme4j v2 which will disappear in a future release.
+ *
+ * @deprecated Will be removed in a future version.
  */
+@Deprecated
 public class AcmeRetryAfterException extends AcmeException {
     private static final long serialVersionUID = 4461979121063649905L;
 
diff --git a/src/doc/docs/migration.md b/src/doc/docs/migration.md
index 95da4f41..25a30aa9 100644
--- a/src/doc/docs/migration.md
+++ b/src/doc/docs/migration.md
@@ -6,6 +6,7 @@ This document will help you migrate your code to the latest _acme4j_ version.
 
 - To be futureproof, you should wait for your `Order` resource's state to become `READY` before invoking `Order.execute()`. Most CAs change to the `READY` state immediately, but this behavior is not specified in RFC8555. Future CA implementations may stay in `PENDING` state for a short while, and would return an error if `execute()` is invoked too early. Also see the [example](example.md#the-main-workflow) for how wait for the `READY` state.
 - There are new methods `waitForCompletion()` and `waitUntilReady()` that will do the synchronous busy wait for the resource state for you. It will remove a lot of boilerplate code that is also bug prone if implemented individually. If you use synchronous polling and waiting (like shown in the example code), I recommend to change to these methods instead of waiting for the correct state yourself. See the [example](example.md) for how to use the new methods.
+- Marked `update()` (and `AcmeRetryAfterException`) as deprecated now. Please use `fetch()` instead, it returns the retry-after time as `Optional` instead of throwing an `AcmeRetryAfterException`.
 
 ## Migration to Version 3.3.0