feat: Enhance actor timer and reminder functionality with repetitions and TTL options

[matheusandre1]

Description

Adds support for TTL, repetitions (ISO 8601 Rn/ periods) and optional dueTime/period to actor timers and reminders, aligning the Java SDK with the Dapr runtime and with the API agreed in #681 (keep the existing signatures, add a builder-based API).

New API

Two new builder-based option classes in io.dapr.actors.runtime:

• ActorReminderOptions
• ActorTimerOptions

Both expose dueTime, period, repetitions and ttl, all optional. AbstractActor gets new overloads that accept them:

registerReminder("myreminder", state, ActorReminderOptions.builder()
    .setPeriod(Duration.ofSeconds(10))
    .setRepetitions(5)
    .setTtl(Duration.ofMinutes(1))
    .build());

registerActorTimer("mytimer", "callback", state, ActorTimerOptions.builder()
    .setDueTime(Duration.ofSeconds(1))
    .setPeriod(Duration.ofSeconds(2))
    .setRepetitions(3)
    .build());

The existing registerReminder(String, T, Duration, Duration) and registerActorTimer(String, String, T, Duration, Duration) methods keep working unchanged and now delegate to the new overloads.

Behavior

• dueTime not set → sent as empty, so the runtime fires immediately.
• period not set → the timer/reminder fires only once.
• repetitions set → period is sent in ISO 8601 format (R5/PT10S). It requires a positive period in whole seconds, because the runtime's ISO 8601 parser only accepts integer seconds.
• ttl set → sent in the new ttl field of RegisterActorReminderRequest / RegisterActorTimerRequest, which already exists in actors.proto.
• Validation: repetitions > 0, and ttl must not be negative.

Reminder/timer callbacks

The runtime echoes the registered period string back in the reminder/timer callback payload (ReminderPeriod.String() returns the raw value). Previously an ISO 8601 value such as R5/PT10S was silently parsed as Duration.ZERO. Now:

• DurationUtils.convertDurationFromDaprFormat also accepts ISO 8601 durations, with or without the Rn/ prefix.
• ActorObjectSerializer reads/writes ttl and the repetitions, and omits unset fields.

Other changes

• DurationUtils.convertDurationToIso8601Format(Duration) added.
• New package-private ActorScheduleUtils that centralizes the validation and formatting shared by timers and reminders.

Issue reference

Closes: #681
Closes: #652
Closes: #569

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

• Code compiles correctly
• Created/updated tests
• Extended the documentation

[javier-aliaga]

@matheusandre1 thanks! Can you check my comments?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.66%. Comparing base (8f59769) to head (91087a6).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1825      +/-   ##
============================================
+ Coverage     79.26%   79.66%   +0.39%     
- Complexity     2615     2683      +68     
============================================
  Files           264      267       +3     
  Lines          7785     7923     +138     
  Branches        820      839      +19     
============================================
+ Hits           6171     6312     +141     
+ Misses         1254     1252       -2     
+ Partials        360      359       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.