Merge pull request #149 from OpenElements/cleanup

cleanup: documentation and annotations

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/FileClient.java

@@ -22,6 +22,15 @@ public interface FileClient {
     @NonNull
     FileId createFile(@NonNull byte[] contents) throws HieroException;
 
+    /**
+     * Create a new file with the given contents and expiration time.
+     *
+     * @param contents       the contents of the file
+     * @param expirationTime the expiration time of the file
+     * @return the ID of the new file
+     * @throws HieroException if the file could not be created
+     */
+    @NonNull
     FileId createFile(@NonNull byte[] contents, @NonNull Instant expirationTime) throws HieroException;
 
     /**
@@ -108,5 +117,6 @@ default void deleteFile(@NonNull String fileId) throws HieroException {
      * @return the expiration time of the file
      * @throws HieroException if the file could not be checked
      */
+    @NonNull
     Instant getExpirationTime(@NonNull FileId fileId) throws HieroException;
 }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/FungibleTokenClient.java

@@ -23,6 +23,7 @@ public interface FungibleTokenClient {
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     TokenId createToken(@NonNull String name, @NonNull String symbol) throws HieroException;
 
     /**
@@ -34,6 +35,7 @@ public interface FungibleTokenClient {
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull PrivateKey supplyKey)
             throws HieroException;
 
@@ -47,6 +49,7 @@ TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull Priva
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull String supplyKey)
             throws HieroException {
         Objects.requireNonNull(name, "name must not be null");
@@ -66,6 +69,7 @@ default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNu
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull AccountId treasuryAccountId,
             @NonNull PrivateKey treasuryKey) throws HieroException;
 
@@ -80,6 +84,7 @@ TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull Accou
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull String treasuryAccountId,
             @NonNull String treasuryKey) throws HieroException {
         Objects.requireNonNull(name, "name must not be null");
@@ -99,6 +104,7 @@ default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNu
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull Account treasuryAccount)
             throws HieroException {
         Objects.requireNonNull(name, "name must not be null");
@@ -118,6 +124,7 @@ default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNu
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull AccountId treasuryAccountId,
             @NonNull PrivateKey treasuryKey, @NonNull PrivateKey supplyKey) throws HieroException;
 
@@ -132,6 +139,7 @@ TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull Accou
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull String treasuryAccountId,
             @NonNull String treasuryKey, @NonNull String supplyKey) throws HieroException {
         Objects.requireNonNull(name, "name must not be null");
@@ -153,6 +161,7 @@ default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNu
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull Account treasuryAccount,
             @NonNull PrivateKey supplyKey) throws HieroException {
         Objects.requireNonNull(name, "name must not be null");
@@ -172,6 +181,7 @@ default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNu
      * @return the ID of the new token
      * @throws HieroException if the token could not be created
      */
+    @NonNull
     default TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull Account treasuryAccount,
             @NonNull String supplyKey) throws HieroException {
         Objects.requireNonNull(name, "name must not be null");

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/NftClient.java

@@ -313,17 +313,47 @@ default List<Long> mintNfts(@NonNull String tokenId, @NonNull String supplyKey,
         return mintNfts(TokenId.fromString(tokenId), PrivateKey.fromString(supplyKey), metadata);
     }
 
+    /**
+     * Burn an NFT.
+     *
+     * @param tokenId      the ID of the NFT type
+     * @param serialNumber the serial number of the NFT
+     * @throws HieroException if the NFT could not be burned
+     */
     default void burnNft(@NonNull TokenId tokenId, long serialNumber) throws HieroException {
         burnNfts(tokenId, Set.of(serialNumber));
     }
 
+    /**
+     * Burn an NFT.
+     *
+     * @param tokenId      the ID of the NFT type
+     * @param serialNumber the serial number of the NFT
+     * @param supplyKey    the private key of the supply account
+     * @throws HieroException if the NFT could not be burned
+     */
     default void burnNft(@NonNull TokenId tokenId, long serialNumber, @NonNull PrivateKey supplyKey)
             throws HieroException {
         burnNfts(tokenId, Set.of(serialNumber), supplyKey);
     }
 
+    /**
+     * Burn NFTs.
+     *
+     * @param tokenId       the ID of the NFT type
+     * @param serialNumbers the serial numbers of the NFTs
+     * @throws HieroException if the NFTs could not be burned
+     */
     void burnNfts(@NonNull TokenId tokenId, @NonNull Set<Long> serialNumbers) throws HieroException;
 
+    /**
+     * Burn NFTs.
+     *
+     * @param tokenId       the ID of the NFT type
+     * @param serialNumbers the serial numbers of the NFTs
+     * @param supplyKey     the private key of the supply account
+     * @throws HieroException
+     */
     void burnNfts(@NonNull TokenId tokenId, @NonNull Set<Long> serialNumbers, @NonNull PrivateKey supplyKey)
             throws HieroException;
 

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/config/HieroConfig.java

@@ -10,16 +10,12 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 import org.jspecify.annotations.NonNull;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 /**
  * Hiero configuration for one network connection.
  */
 public interface HieroConfig {
 
-    final static Logger log = LoggerFactory.getLogger(HieroConfig.class);
-
     /**
      * Returns the operator account for the network.
      *
@@ -52,9 +48,19 @@ public interface HieroConfig {
     @NonNull
     Set<ConsensusNode> getConsensusNodes();
 
+    /**
+     * Returns the chain ID of the network.
+     *
+     * @return the chain ID of the network
+     */
     @NonNull
     Optional<Long> chainId();
 
+    /**
+     * Returns the relay URL of the network.
+     *
+     * @return the relay URL of the network
+     */
     @NonNull
     Optional<String> relayUrl();
 
@@ -95,7 +101,7 @@ default Client createClient() {
             client.setMirrorNetwork(mirrorNodeAddresses);
             client.setOperator(getOperatorAccount().accountId(), getOperatorAccount().privateKey());
             return client;
-        } catch (Exception e) {
+        } catch (final Exception e) {
             throw new IllegalArgumentException("Can not create client for custom network", e);
         }
     }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/config/NetworkSettings.java

@@ -1,6 +1,7 @@
 package com.openelements.hiero.base.config;
 
 import com.openelements.hiero.base.config.implementation.NetworkSettingsProviderLoader;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
 import org.jspecify.annotations.NonNull;
@@ -68,6 +69,7 @@ public interface NetworkSettings {
      *
      * @return all available network settings
      */
+    @NonNull
     static Set<NetworkSettings> all() {
         return NetworkSettingsProviderLoader.getInstance().all();
     }
@@ -78,7 +80,9 @@ static Set<NetworkSettings> all() {
      * @param identifier the identifier of the network
      * @return the network settings for the given identifier
      */
-    static Optional<NetworkSettings> forIdentifier(String identifier) {
+    @NonNull
+    static Optional<NetworkSettings> forIdentifier(@NonNull String identifier) {
+        Objects.requireNonNull(identifier, "identifier must not be null");
         return NetworkSettingsProviderLoader.getInstance().forIdentifier(identifier);
     }
 }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/config/NetworkSettingsProvider.java

@@ -1,6 +1,7 @@
 package com.openelements.hiero.base.config;
 
 import java.util.Set;
+import org.jspecify.annotations.NonNull;
 
 /**
  * SPI interface to provide predefined {@link NetworkSettings} instances. Java SPI functionality is documented at
@@ -13,12 +14,14 @@ public interface NetworkSettingsProvider {
      *
      * @return the name of the provider
      */
+    @NonNull
     String getName();
 
     /**
      * Return a set of {@link NetworkSettings} instances provided by this provider.
      *
      * @return a set of {@link NetworkSettings} instances
      */
+    @NonNull
     Set<NetworkSettings> createNetworkSettings();
 }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/config/hedera/HederMainnetSettings.java

@@ -6,8 +6,14 @@
 import java.util.Set;
 import org.jspecify.annotations.NonNull;
 
+/**
+ * Network settings for the Hedera Mainnet.
+ */
 public final class HederMainnetSettings implements NetworkSettings {
 
+    /**
+     * The network identifier.
+     */
     public static final String NETWORK_IDENTIFIER = "hedera-mainnet";
 
     @Override

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/config/hedera/HederTestnetSettings.java

@@ -6,8 +6,14 @@
 import java.util.Set;
 import org.jspecify.annotations.NonNull;
 
+/**
+ * Network settings for the Hedera Testnet.
+ */
 public final class HederTestnetSettings implements NetworkSettings {
 
+    /**
+     * The network identifier.
+     */
     public static final String NETWORK_IDENTIFIER = "hedera-testnet";
 
     @Override

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/config/hedera/HederaNetworkSettingsProvider.java

@@ -5,6 +5,9 @@
 import com.openelements.hiero.base.config.NetworkSettingsProvider;
 import java.util.Set;
 
+/**
+ * Provides network settings for the Hedera networks.
+ */
 @AutoService(NetworkSettingsProvider.class)
 public final class HederaNetworkSettingsProvider implements NetworkSettingsProvider {
 

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/config/implementation/NetworkSettingsProviderLoader.java

@@ -11,6 +11,9 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Loads network settings from all available {@link NetworkSettingsProvider} implementations by using Java SPI.
+ */
 public final class NetworkSettingsProviderLoader {
 
     private final static Logger logger = LoggerFactory.getLogger(NetworkSettingsProviderLoader.class);
@@ -41,15 +44,31 @@ private NetworkSettingsProviderLoader() {
         this.settings = Collections.unmodifiableSet(loaded);
     }
 
+    /**
+     * Returns all loaded network settings.
+     *
+     * @return all loaded network settings
+     */
     public Set<NetworkSettings> all() {
         return settings;
     }
 
+    /**
+     * Returns the network settings for the given identifier.
+     *
+     * @param identifier the network identifier
+     * @return the network settings for the given identifier
+     */
     public Optional<NetworkSettings> forIdentifier(String identifier) {
         return all().stream().filter(settings -> Objects.equals(settings.getNetworkIdentifier(), identifier))
                 .findFirst();
     }
 
+    /**
+     * Returns the singleton instance of this class.
+     *
+     * @return the singleton instance of this class
+     */
     public static NetworkSettingsProviderLoader getInstance() {
         return instance;
     }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/implementation/AccountClientImpl.java

@@ -5,11 +5,11 @@
 import com.openelements.hiero.base.AccountClient;
 import com.openelements.hiero.base.HieroException;
 import com.openelements.hiero.base.data.Account;
-import com.openelements.hiero.base.protocol.AccountBalanceRequest;
-import com.openelements.hiero.base.protocol.AccountBalanceResponse;
-import com.openelements.hiero.base.protocol.AccountCreateRequest;
-import com.openelements.hiero.base.protocol.AccountCreateResult;
-import com.openelements.hiero.base.protocol.AccountDeleteRequest;
+import com.openelements.hiero.base.protocol.data.AccountBalanceRequest;
+import com.openelements.hiero.base.protocol.data.AccountBalanceResponse;
+import com.openelements.hiero.base.protocol.data.AccountCreateRequest;
+import com.openelements.hiero.base.protocol.data.AccountCreateResult;
+import com.openelements.hiero.base.protocol.data.AccountDeleteRequest;
 import com.openelements.hiero.base.protocol.ProtocolLayerClient;
 import java.util.Objects;
 import org.jspecify.annotations.NonNull;

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/implementation/FileClientImpl.java

@@ -3,15 +3,15 @@
 import com.hedera.hashgraph.sdk.FileId;
 import com.openelements.hiero.base.FileClient;
 import com.openelements.hiero.base.HieroException;
-import com.openelements.hiero.base.protocol.FileAppendRequest;
-import com.openelements.hiero.base.protocol.FileContentsRequest;
-import com.openelements.hiero.base.protocol.FileContentsResponse;
-import com.openelements.hiero.base.protocol.FileCreateRequest;
-import com.openelements.hiero.base.protocol.FileCreateResult;
-import com.openelements.hiero.base.protocol.FileDeleteRequest;
-import com.openelements.hiero.base.protocol.FileInfoRequest;
-import com.openelements.hiero.base.protocol.FileInfoResponse;
-import com.openelements.hiero.base.protocol.FileUpdateRequest;
+import com.openelements.hiero.base.protocol.data.FileAppendRequest;
+import com.openelements.hiero.base.protocol.data.FileContentsRequest;
+import com.openelements.hiero.base.protocol.data.FileContentsResponse;
+import com.openelements.hiero.base.protocol.data.FileCreateRequest;
+import com.openelements.hiero.base.protocol.data.FileCreateResult;
+import com.openelements.hiero.base.protocol.data.FileDeleteRequest;
+import com.openelements.hiero.base.protocol.data.FileInfoRequest;
+import com.openelements.hiero.base.protocol.data.FileInfoResponse;
+import com.openelements.hiero.base.protocol.data.FileUpdateRequest;
 import com.openelements.hiero.base.protocol.ProtocolLayerClient;
 import java.time.Instant;
 import java.util.Arrays;