fix: resolve JSpecify annotation errors and improve observer framework stability

Twiineenock · Twiineenock · commit ba090c700355 · 2026-04-26T07:58:00.000+03:00
Signed-off-by: Twiineenock &lt;Twiineenock@users.noreply.github.com&gt;
diff --git a/hiero-enterprise-base/src/main/java/module-info.java b/hiero-enterprise-base/src/main/java/module-info.java
@@ -8,6 +8,7 @@
   exports org.hiero.base.verification;
   exports org.hiero.base.data;
   exports org.hiero.base.config;
+  exports org.hiero.base.observer;
   exports org.hiero.base.implementation to
       org.hiero.base.test;
   exports org.hiero.base.implementation.data to
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/TopicRepositoryImpl.java b/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/TopicRepositoryImpl.java
@@ -1,6 +1,7 @@
 package org.hiero.base.implementation;
 
 import com.hedera.hashgraph.sdk.TopicId;
+import java.time.Instant;
 import java.util.Objects;
 import java.util.Optional;
 import org.hiero.base.HieroException;
@@ -32,7 +33,7 @@ public TopicRepositoryImpl(@NonNull final MirrorNodeClient mirrorNodeClient) {
   }
 
   @Override
-  public @NonNull Page<TopicMessage> getMessages(@NonNull TopicId topicId, @NonNull java.time.Instant after)
+  public @NonNull Page<TopicMessage> getMessages(@NonNull TopicId topicId, @NonNull Instant after)
       throws HieroException {
     Objects.requireNonNull(topicId, "topicId must not be null");
     Objects.requireNonNull(after, "after must not be null");
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/TransactionRepositoryImpl.java b/hiero-enterprise-base/src/main/java/org/hiero/base/implementation/TransactionRepositoryImpl.java
@@ -1,6 +1,7 @@
 package org.hiero.base.implementation;
 
 import com.hedera.hashgraph.sdk.AccountId;
+import java.time.Instant;
 import java.util.Objects;
 import java.util.Optional;
 import org.hiero.base.HieroException;
@@ -31,7 +32,7 @@ public Page<TransactionInfo> findByAccount(@NonNull final AccountId accountId)
 
   @Override
   public @NonNull Page<TransactionInfo> findByAccount(
-      @NonNull AccountId accountId, @NonNull java.time.Instant after) throws HieroException {
+      @NonNull AccountId accountId, @NonNull Instant after) throws HieroException {
     Objects.requireNonNull(accountId, "accountId must not be null");
     Objects.requireNonNull(after, "after must not be null");
     return this.mirrorNodeClient.queryTransactionsByAccount(accountId, after);
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/mirrornode/MirrorNodeClient.java b/hiero-enterprise-base/src/main/java/org/hiero/base/mirrornode/MirrorNodeClient.java
@@ -4,6 +4,7 @@
 import com.hedera.hashgraph.sdk.ContractId;
 import com.hedera.hashgraph.sdk.TokenId;
 import com.hedera.hashgraph.sdk.TopicId;
+import java.time.Instant;
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
@@ -183,8 +184,7 @@ default Optional<Nft> queryNftsByAccountAndTokenIdAndSerial(
    * @return a page of transaction information
    * @throws HieroException if an error occurs during the query
    */
-  @NonNull
-  Page<TransactionInfo> queryTransactionsByAccount(@NonNull AccountId accountId, @NonNull java.time.Instant after)
+  @NonNull Page<TransactionInfo> queryTransactionsByAccount(@NonNull AccountId accountId, @NonNull Instant after)
       throws HieroException;
 
   /**
@@ -416,8 +416,7 @@ default Optional<Topic> queryTopicById(String topicId) throws HieroException {
    * @return Page of TopicMessage
    * @throws HieroException if the search fails
    */
-  @NonNull
-  Page<TopicMessage> queryTopicMessages(@NonNull TopicId topicId, @NonNull java.time.Instant after)
+  @NonNull Page<TopicMessage> queryTopicMessages(@NonNull TopicId topicId, @NonNull Instant after)
       throws HieroException;
 
   /**
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/mirrornode/TopicRepository.java b/hiero-enterprise-base/src/main/java/org/hiero/base/mirrornode/TopicRepository.java
@@ -67,8 +67,7 @@ default Page<TopicMessage> getMessages(String topicId) throws HieroException {
    * @return Page of TopicMessage
    * @throws HieroException if the search fails
    */
-  @NonNull
-  Page<TopicMessage> getMessages(@NonNull TopicId topicId, @NonNull Instant after)
+  @NonNull Page<TopicMessage> getMessages(@NonNull TopicId topicId, @NonNull Instant after)
       throws HieroException;
 
   /**
@@ -79,8 +78,7 @@ Page<TopicMessage> getMessages(@NonNull TopicId topicId, @NonNull Instant after)
    * @return Page of TopicMessage
    * @throws HieroException if the search fails
    */
-  @NonNull
-  default Page<TopicMessage> getMessages(@NonNull String topicId, @NonNull Instant after)
+  @NonNull default Page<TopicMessage> getMessages(@NonNull String topicId, @NonNull Instant after)
       throws HieroException {
     Objects.requireNonNull(topicId, "topicId must not be null");
     Objects.requireNonNull(after, "after must not be null");
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/mirrornode/TransactionRepository.java b/hiero-enterprise-base/src/main/java/org/hiero/base/mirrornode/TransactionRepository.java
@@ -47,8 +47,7 @@ default Page<TransactionInfo> findByAccount(@NonNull String accountId) throws Hi
    * @return page of transactions
    * @throws HieroException if the search fails
    */
-  @NonNull
-  Page<TransactionInfo> findByAccount(@NonNull AccountId accountId, @NonNull Instant after)
+  @NonNull Page<TransactionInfo> findByAccount(@NonNull AccountId accountId, @NonNull Instant after)
       throws HieroException;
 
   /**
@@ -59,8 +58,7 @@ Page<TransactionInfo> findByAccount(@NonNull AccountId accountId, @NonNull Insta
    * @return page of transactions
    * @throws HieroException if the search fails
    */
-  @NonNull
-  default Page<TransactionInfo> findByAccount(@NonNull String accountId, @NonNull Instant after)
+  @NonNull default Page<TransactionInfo> findByAccount(@NonNull String accountId, @NonNull Instant after)
       throws HieroException {
     Objects.requireNonNull(accountId, "accountId must not be null");
     Objects.requireNonNull(after, "after must not be null");
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/observer/AbstractPollingObserver.java b/hiero-enterprise-base/src/main/java/org/hiero/base/observer/AbstractPollingObserver.java
@@ -75,7 +75,7 @@ private void pollSafe() {
      *
      * @throws Exception if polling fails.
      */
-    protected abstract void poll() throws Exception;
+    public abstract void poll() throws Exception;
 
     /**
      * Notifies the listener of a new event.
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/observer/TopicObserver.java b/hiero-enterprise-base/src/main/java/org/hiero/base/observer/TopicObserver.java
@@ -43,11 +43,11 @@ public TopicObserver(
     }
 
     @Override
-    protected void poll() throws Exception {
+    public void poll() throws Exception {
         log.trace("Polling messages for topic {} after {}", topicId, lastSeenTimestamp);
 
         Page<TopicMessage> page = repository.getMessages(topicId, lastSeenTimestamp);
-        List<TopicMessage> messages = page.getData();
+        List<TopicMessage> messages = new java.util.ArrayList<>(page.getData());
 
         if (messages.isEmpty()) {
             return;
@@ -57,8 +57,8 @@ protected void poll() throws Exception {
         messages.sort(Comparator.comparing(TopicMessage::consensusTimestamp));
 
         for (TopicMessage msg : messages) {
-            notifyListener(msg);
             if (msg.consensusTimestamp().isAfter(lastSeenTimestamp)) {
+                notifyListener(msg);
                 lastSeenTimestamp = msg.consensusTimestamp();
             }
         }
diff --git a/hiero-enterprise-base/src/main/java/org/hiero/base/observer/TransactionObserver.java b/hiero-enterprise-base/src/main/java/org/hiero/base/observer/TransactionObserver.java
@@ -47,11 +47,11 @@ public TransactionObserver(
     }
 
     @Override
-    protected void poll() throws Exception {
+    public void poll() throws Exception {
         log.trace("Polling transactions for account {} after {}", accountId, lastSeenTimestamp);
 
         Page<TransactionInfo> page = repository.findByAccount(accountId, lastSeenTimestamp);
-        List<TransactionInfo> transactions = page.getData();
+        List<TransactionInfo> transactions = new java.util.ArrayList<>(page.getData());
 
         if (transactions.isEmpty()) {
             return;
@@ -61,8 +61,8 @@ protected void poll() throws Exception {
         transactions.sort(Comparator.comparing(TransactionInfo::consensusTimestamp));
 
         for (TransactionInfo tx : transactions) {
-            notifyListener(tx);
             if (tx.consensusTimestamp().isAfter(lastSeenTimestamp)) {
+                notifyListener(tx);
                 lastSeenTimestamp = tx.consensusTimestamp();
             }
         }
diff --git a/hiero-enterprise-base/src/test/java/org/hiero/base/test/TransactionObserverTest.java b/hiero-enterprise-base/src/test/java/org/hiero/base/test/TransactionObserverTest.java
@@ -1,4 +1,4 @@
-package org.hiero.base.observer;
+package org.hiero.base.test;
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
@@ -12,6 +12,8 @@
 import org.hiero.base.data.Page;
 import org.hiero.base.data.TransactionInfo;
 import org.hiero.base.mirrornode.TransactionRepository;
+import org.hiero.base.observer.EventObserver;
+import org.hiero.base.observer.TransactionObserver;
 import org.hiero.base.protocol.data.TransactionType;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -44,7 +46,7 @@ void testPollDetectsNewTransactions() throws Exception {
         TransactionInfo tx = new TransactionInfo(
                 "0.0.1234@1234567890.000000001",
                 null, 0, txTime, null, "100", null,
-                TransactionType.CRYPTOTRANSFER, Collections.emptyList(), null, 0, null,
+                TransactionType.CRYPTO_TRANSFER, Collections.emptyList(), null, 0, null,
                 "SUCCESS", false, Collections.emptyList(), Collections.emptyList(), null,
                 Collections.emptyList(), "120", Instant.now()
         );
diff --git a/hiero-enterprise-microprofile/src/main/java/org/hiero/microprofile/implementation/MirrorNodeClientImpl.java b/hiero-enterprise-microprofile/src/main/java/org/hiero/microprofile/implementation/MirrorNodeClientImpl.java
@@ -4,6 +4,7 @@
 import com.hedera.hashgraph.sdk.TokenId;
 import com.hedera.hashgraph.sdk.TopicId;
 import jakarta.json.JsonObject;
+import java.time.Instant;
 import java.util.List;
 import java.util.Objects;
 import java.util.function.Function;
@@ -73,7 +74,7 @@ public MirrorNodeClientImpl(
 
   @Override
   public @NonNull Page<TransactionInfo> queryTransactionsByAccount(
-      @NonNull AccountId accountId, @NonNull java.time.Instant after) throws HieroException {
+      @NonNull AccountId accountId, @NonNull Instant after) throws HieroException {
     Objects.requireNonNull(accountId, "accountId must not be null");
     Objects.requireNonNull(after, "after must not be null");
     final String path = "/api/v1/transactions?account.id=" + accountId + "&timestamp=gt:" + formatInstant(after);
@@ -155,7 +156,7 @@ public Page<Token> queryTokensForAccount(@NonNull AccountId accountId) throws Hi
 
   @Override
   public @NonNull Page<TopicMessage> queryTopicMessages(
-      @NonNull TopicId topicId, @NonNull java.time.Instant after) throws HieroException {
+      @NonNull TopicId topicId, @NonNull Instant after) throws HieroException {
     Objects.requireNonNull(topicId, "topicId must not be null");
     Objects.requireNonNull(after, "after must not be null");
     final String path = "/api/v1/topics/" + topicId + "/messages?timestamp=gt:" + formatInstant(after);
@@ -164,7 +165,7 @@ public Page<Token> queryTokensForAccount(@NonNull AccountId accountId) throws Hi
     return new RestBasedPage<>(restClient.getTarget(), dataExtractionFunction, path);
   }
 
-  private String formatInstant(java.time.Instant instant) {
+  private String formatInstant(Instant instant) {
     return instant.getEpochSecond() + "." + String.format("%09d", instant.getNano());
   }
 
diff --git a/hiero-enterprise-spring/src/main/java/org/hiero/spring/implementation/MirrorNodeClientImpl.java b/hiero-enterprise-spring/src/main/java/org/hiero/spring/implementation/MirrorNodeClientImpl.java
@@ -5,6 +5,7 @@
 import com.hedera.hashgraph.sdk.AccountId;
 import com.hedera.hashgraph.sdk.TokenId;
 import com.hedera.hashgraph.sdk.TopicId;
+import java.time.Instant;
 import java.util.List;
 import java.util.Objects;
 import java.util.function.Function;
@@ -99,7 +100,7 @@ public Page<TransactionInfo> queryTransactionsByAccount(@NonNull final AccountId
 
   @Override
   public Page<TransactionInfo> queryTransactionsByAccount(
-      @NonNull AccountId accountId, @NonNull java.time.Instant after) throws HieroException {
+      @NonNull AccountId accountId, @NonNull Instant after) throws HieroException {
     Objects.requireNonNull(accountId, "accountId must not be null");
     Objects.requireNonNull(after, "after must not be null");
     final String path = "/api/v1/transactions?account.id=" + accountId + "&timestamp=gt:" + formatInstant(after);
@@ -186,7 +187,7 @@ public Page<Token> queryTokensForAccount(@NonNull AccountId accountId) throws Hi
   }
 
   @Override
-  public @NonNull Page<TopicMessage> queryTopicMessages(@NonNull TopicId topicId, @NonNull java.time.Instant after)
+  public @NonNull Page<TopicMessage> queryTopicMessages(@NonNull TopicId topicId, @NonNull Instant after)
       throws HieroException {
     Objects.requireNonNull(topicId, "topicId must not be null");
     Objects.requireNonNull(after, "after must not be null");
@@ -197,7 +198,7 @@ public Page<Token> queryTokensForAccount(@NonNull AccountId accountId) throws Hi
         objectMapper, restClient.mutate().clone(), path, dataExtractionFunction);
   }
 
-  private String formatInstant(java.time.Instant instant) {
+  private String formatInstant(Instant instant) {
     return instant.getEpochSecond() + "." + String.format("%09d", instant.getNano());
   }
 

Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ private void pollSafe() {`
`75`	`75`	`*`
`76`	`76`	`* @throws Exception if polling fails.`
`77`	`77`	`*/`
`78`		`- protected abstract void poll() throws Exception;`
	`78`	`+ public abstract void poll() throws Exception;`
`79`	`79`
`80`	`80`	`/**`
`81`	`81`	`* Notifies the listener of a new event.`
Original file line number	Diff line number	Diff line change
`@@ -43,11 +43,11 @@ public TopicObserver(`
`43`	`43`	`}`
`44`	`44`
`45`	`45`	`@Override`
`46`		`- protected void poll() throws Exception {`
	`46`	`+ public void poll() throws Exception {`
`47`	`47`	`log.trace("Polling messages for topic {} after {}", topicId, lastSeenTimestamp);`
`48`	`48`
`49`	`49`	`Page<TopicMessage> page = repository.getMessages(topicId, lastSeenTimestamp);`
`50`		`- List<TopicMessage> messages = page.getData();`
	`50`	`+ List<TopicMessage> messages = new java.util.ArrayList<>(page.getData());`
`51`	`51`
`52`	`52`	`if (messages.isEmpty()) {`
`53`	`53`	`return;`
`@@ -57,8 +57,8 @@ protected void poll() throws Exception {`
`57`	`57`	`messages.sort(Comparator.comparing(TopicMessage::consensusTimestamp));`
`58`	`58`
`59`	`59`	`for (TopicMessage msg : messages) {`
`60`		`- notifyListener(msg);`
`61`	`60`	`if (msg.consensusTimestamp().isAfter(lastSeenTimestamp)) {`
	`61`	`+ notifyListener(msg);`
`62`	`62`	`lastSeenTimestamp = msg.consensusTimestamp();`
`63`	`63`	`}`
`64`	`64`	`}`
Original file line number	Diff line number	Diff line change
`@@ -47,11 +47,11 @@ public TransactionObserver(`
`47`	`47`	`}`
`48`	`48`
`49`	`49`	`@Override`
`50`		`- protected void poll() throws Exception {`
	`50`	`+ public void poll() throws Exception {`
`51`	`51`	`log.trace("Polling transactions for account {} after {}", accountId, lastSeenTimestamp);`
`52`	`52`
`53`	`53`	`Page<TransactionInfo> page = repository.findByAccount(accountId, lastSeenTimestamp);`
`54`		`- List<TransactionInfo> transactions = page.getData();`
	`54`	`+ List<TransactionInfo> transactions = new java.util.ArrayList<>(page.getData());`
`55`	`55`
`56`	`56`	`if (transactions.isEmpty()) {`
`57`	`57`	`return;`
`@@ -61,8 +61,8 @@ protected void poll() throws Exception {`
`61`	`61`	`transactions.sort(Comparator.comparing(TransactionInfo::consensusTimestamp));`
`62`	`62`
`63`	`63`	`for (TransactionInfo tx : transactions) {`
`64`		`- notifyListener(tx);`
`65`	`64`	`if (tx.consensusTimestamp().isAfter(lastSeenTimestamp)) {`
	`65`	`+ notifyListener(tx);`
`66`	`66`	`lastSeenTimestamp = tx.consensusTimestamp();`
`67`	`67`	`}`
`68`	`68`	`}`