From 990070ff379d46b42f47937b02ac586aa7c531a1 Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Tue, 3 Apr 2018 13:25:13 +0200 Subject: [PATCH] Add Javadoc for bisq.asset types --- src/main/java/bisq/asset/AbstractAsset.java | 8 ++++ .../bisq/asset/AddressValidationResult.java | 8 ++++ .../java/bisq/asset/AddressValidator.java | 6 +++ src/main/java/bisq/asset/Asset.java | 19 ++++++++++ src/main/java/bisq/asset/AssetRegistry.java | 8 ++++ .../asset/Base58BitcoinAddressValidator.java | 7 ++++ src/main/java/bisq/asset/Coin.java | 17 +++++++++ .../bisq/asset/DefaultAddressValidator.java | 11 ++++++ src/main/java/bisq/asset/Erc20Token.java | 8 ++++ .../bisq/asset/EtherAddressValidator.java | 12 +++++- .../bisq/asset/NetworkParametersAdapter.java | 11 +++++- .../bisq/asset/RegexAddressValidator.java | 6 +++ src/main/java/bisq/asset/Token.java | 12 ++++++ src/main/java/bisq/asset/package-info.java | 37 +++++++++++++++++++ .../java/bisq/asset/AbstractAssetTest.java | 17 +++++++++ ...AbstractAssetWithDefaultValidatorTest.java | 9 +++++ 16 files changed, 193 insertions(+), 3 deletions(-) create mode 100644 src/main/java/bisq/asset/package-info.java diff --git a/src/main/java/bisq/asset/AbstractAsset.java b/src/main/java/bisq/asset/AbstractAsset.java index 5912c2f3..3cabaa2e 100644 --- a/src/main/java/bisq/asset/AbstractAsset.java +++ b/src/main/java/bisq/asset/AbstractAsset.java @@ -20,6 +20,14 @@ import static org.apache.commons.lang3.Validate.notBlank; import static org.apache.commons.lang3.Validate.notNull; +/** + * Abstract base class for {@link Asset} implementations. Most implementations should not + * extend this class directly, but should rather extend {@link Coin}, {@link Token} or one + * of their subtypes. + * + * @author Chris Beams + * @since 0.7.0 + */ public abstract class AbstractAsset implements Asset { private final String name; diff --git a/src/main/java/bisq/asset/AddressValidationResult.java b/src/main/java/bisq/asset/AddressValidationResult.java index 5adb1e80..04abb184 100644 --- a/src/main/java/bisq/asset/AddressValidationResult.java +++ b/src/main/java/bisq/asset/AddressValidationResult.java @@ -17,6 +17,14 @@ package bisq.asset; +/** + * Value object representing the result of validating an {@link Asset} address. Various + * factory methods are provided for typical use cases. + * + * @author Chris Beams + * @since 0.7.0 + * @see Asset#validateAddress(String) + */ public class AddressValidationResult { private static AddressValidationResult VALID_ADDRESS = new AddressValidationResult(true, "", ""); diff --git a/src/main/java/bisq/asset/AddressValidator.java b/src/main/java/bisq/asset/AddressValidator.java index 0fe72cd2..8cf65608 100644 --- a/src/main/java/bisq/asset/AddressValidator.java +++ b/src/main/java/bisq/asset/AddressValidator.java @@ -17,6 +17,12 @@ package bisq.asset; +/** + * An {@link Asset} address validation function. + * + * @author Chris Beams + * @since 0.7.0 + */ public interface AddressValidator { AddressValidationResult validate(String address); diff --git a/src/main/java/bisq/asset/Asset.java b/src/main/java/bisq/asset/Asset.java index 2db6300e..b67d0376 100644 --- a/src/main/java/bisq/asset/Asset.java +++ b/src/main/java/bisq/asset/Asset.java @@ -17,6 +17,25 @@ package bisq.asset; +/** + * Interface representing a given ("crypto") asset in its most abstract form, having a + * {@link #getName() name}, e.g. "Bitcoin", a {@link #getTickerSymbol() ticker symbol}, + * e.g. "BTC", and an address validation function. Together, these properties represent + * the minimum information and functionality required to register and trade an asset on + * the Bisq network. + *

+ * Implementations typically extend either the {@link Coin} or {@link Token} base + * classes, and must be registered in the {@code META-INF/services/bisq.asset.Asset} file + * in order to be available in the {@link AssetRegistry} at runtime. + * + * @author Chris Beams + * @since 0.7.0 + * @see AbstractAsset + * @see Coin + * @see Token + * @see Erc20Token + * @see AssetRegistry + */ public interface Asset { String getName(); diff --git a/src/main/java/bisq/asset/AssetRegistry.java b/src/main/java/bisq/asset/AssetRegistry.java index eddb0827..c6a0c7b3 100644 --- a/src/main/java/bisq/asset/AssetRegistry.java +++ b/src/main/java/bisq/asset/AssetRegistry.java @@ -22,6 +22,14 @@ import java.util.ServiceLoader; import java.util.stream.Stream; +/** + * Provides {@link Stream}-based access to {@link Asset} implementations registered in + * the {@code META-INF/services/bisq.asset.Asset} provider-configuration file. + * + * @author Chris Beams + * @since 0.7.0 + * @see ServiceLoader + */ public class AssetRegistry { private static final List registeredAssets = new ArrayList<>(); diff --git a/src/main/java/bisq/asset/Base58BitcoinAddressValidator.java b/src/main/java/bisq/asset/Base58BitcoinAddressValidator.java index 616bbbab..9a99385f 100644 --- a/src/main/java/bisq/asset/Base58BitcoinAddressValidator.java +++ b/src/main/java/bisq/asset/Base58BitcoinAddressValidator.java @@ -22,6 +22,13 @@ import org.bitcoinj.core.NetworkParameters; import org.bitcoinj.params.MainNetParams; +/** + * {@link AddressValidator} for Base58-encoded Bitcoin addresses. + * + * @author Chris Beams + * @since 0.7.0 + * @see org.bitcoinj.core.Address#fromBase58(NetworkParameters, String) + */ public class Base58BitcoinAddressValidator implements AddressValidator { private final NetworkParameters networkParameters; diff --git a/src/main/java/bisq/asset/Coin.java b/src/main/java/bisq/asset/Coin.java index 19cf8838..5eb596e4 100644 --- a/src/main/java/bisq/asset/Coin.java +++ b/src/main/java/bisq/asset/Coin.java @@ -17,6 +17,23 @@ package bisq.asset; +/** + * Abstract base class for {@link Asset}s with their own dedicated blockchain, such as + * {@link bisq.asset.coins.Bitcoin} itself or one of its many derivatives, competitors and + * alternatives, often called "altcoins", such as {@link bisq.asset.coins.Litecoin}, + * {@link bisq.asset.coins.Ether}, {@link bisq.asset.coins.Monero} and + * {@link bisq.asset.coins.Zcash}. + *

+ * In addition to the usual {@code Asset} properties, a {@code Coin} maintains information + * about which {@link Network} it may be used on. By default, coins are constructed with + * the assumption they are for use on that coin's "main network", or "main blockchain", + * i.e. that they are "real" coins for use in a production environment. In testing + * scenarios, however, a coin may be constructed for use only on "testnet" or "regtest" + * networks. + * + * @author Chris Beams + * @since 0.7.0 + */ public abstract class Coin extends AbstractAsset { public enum Network { MAINNET, TESTNET, REGTEST } diff --git a/src/main/java/bisq/asset/DefaultAddressValidator.java b/src/main/java/bisq/asset/DefaultAddressValidator.java index 2b45cf1c..17131035 100644 --- a/src/main/java/bisq/asset/DefaultAddressValidator.java +++ b/src/main/java/bisq/asset/DefaultAddressValidator.java @@ -17,6 +17,17 @@ package bisq.asset; +/** + * {@link AddressValidator} for use when no more specific address validation function is + * available. This implementation only checks that a given address is non-null and + * non-empty; it exists for legacy purposes and is deprecated to indicate that new + * {@link Asset} implementations should NOT use it, but should rather provide their own + * {@link AddressValidator} implementation. + * + * @author Chris Beams + * @author Bernard Labno + * @since 0.7.0 + */ @Deprecated public class DefaultAddressValidator implements AddressValidator { diff --git a/src/main/java/bisq/asset/Erc20Token.java b/src/main/java/bisq/asset/Erc20Token.java index 86a33e3c..33213a65 100644 --- a/src/main/java/bisq/asset/Erc20Token.java +++ b/src/main/java/bisq/asset/Erc20Token.java @@ -17,6 +17,14 @@ package bisq.asset; +/** + * Abstract base class for Ethereum-based {@link Token}s that implement the + * ERC-20 Token + * Standard. + * + * @author Chris Beams + * @since 0.7.0 + */ public abstract class Erc20Token extends Token { public Erc20Token(String name, String tickerSymbol) { diff --git a/src/main/java/bisq/asset/EtherAddressValidator.java b/src/main/java/bisq/asset/EtherAddressValidator.java index 10d5003c..f646ed57 100644 --- a/src/main/java/bisq/asset/EtherAddressValidator.java +++ b/src/main/java/bisq/asset/EtherAddressValidator.java @@ -17,10 +17,20 @@ package bisq.asset; +/** + * Validates an Ethereum address using the regular expression on record in the + * + * ethereum/web3.js project. Note that this implementation is widely used, not just + * for actual {@link bisq.asset.coins.Ether} address validation, but also for + * {@link Erc20Token} implementations and other Ethereum-based {@link Asset} + * implementations. + * + * @author Chris Beams + * @since 0.7.0 + */ public class EtherAddressValidator extends RegexAddressValidator { public EtherAddressValidator() { - // https://github.com/ethereum/web3.js/blob/master/lib/utils/utils.js#L403 super("^(0x)?[0-9a-fA-F]{40}$"); } } diff --git a/src/main/java/bisq/asset/NetworkParametersAdapter.java b/src/main/java/bisq/asset/NetworkParametersAdapter.java index 62ed257b..184b7dbf 100644 --- a/src/main/java/bisq/asset/NetworkParametersAdapter.java +++ b/src/main/java/bisq/asset/NetworkParametersAdapter.java @@ -24,9 +24,16 @@ import org.bitcoinj.core.StoredBlock; import org.bitcoinj.core.VerificationException; import org.bitcoinj.store.BlockStore; -import org.bitcoinj.store.BlockStoreException; import org.bitcoinj.utils.MonetaryFormat; +/** + * Convenient abstract {@link NetworkParameters} base class providing no-op + * implementations of all methods that are not required for address validation + * purposes. + * + * @author Chris Beams + * @since 0.7.0 + */ public abstract class NetworkParametersAdapter extends NetworkParameters { @Override @@ -36,7 +43,7 @@ public String getPaymentProtocolId() { @Override public void checkDifficultyTransitions(StoredBlock storedPrev, Block next, BlockStore blockStore) - throws VerificationException, BlockStoreException { + throws VerificationException { } @Override diff --git a/src/main/java/bisq/asset/RegexAddressValidator.java b/src/main/java/bisq/asset/RegexAddressValidator.java index 1855b068..38b5f13d 100644 --- a/src/main/java/bisq/asset/RegexAddressValidator.java +++ b/src/main/java/bisq/asset/RegexAddressValidator.java @@ -17,6 +17,12 @@ package bisq.asset; +/** + * Validates an {@link Asset} address against a given regular expression. + * + * @author Chris Beams + * @since 0.7.0 + */ public class RegexAddressValidator implements AddressValidator { private final String regex; diff --git a/src/main/java/bisq/asset/Token.java b/src/main/java/bisq/asset/Token.java index 215c87a3..2c162e52 100644 --- a/src/main/java/bisq/asset/Token.java +++ b/src/main/java/bisq/asset/Token.java @@ -17,6 +17,18 @@ package bisq.asset; +/** + * Abstract base class for {@link Asset}s that do not have their own dedicated blockchain, + * but are rather based on or derived from another blockchain. Contrast with {@link Coin}. + * Note that this is essentially a "marker" base class in the sense that it (currently) + * exposes no additional information or functionality beyond that found in + * {@link AbstractAsset}, but it is nevertheless useful in distinguishing between major + * different {@code Asset} types. + * + * @author Chris Beams + * @since 0.7.0 + * @see Erc20Token + */ public abstract class Token extends AbstractAsset { public Token(String name, String tickerSymbol, AddressValidator addressValidator) { diff --git a/src/main/java/bisq/asset/package-info.java b/src/main/java/bisq/asset/package-info.java new file mode 100644 index 00000000..b466aedf --- /dev/null +++ b/src/main/java/bisq/asset/package-info.java @@ -0,0 +1,37 @@ +/* + * This file is part of Bisq. + * + * Bisq is free software: you can redistribute it and/or modify it + * under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or (at + * your option) any later version. + * + * Bisq is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public + * License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with Bisq. If not, see . + */ + +/** + * Bisq's family of abstractions representing different ("crypto") + * {@link bisq.asset.Asset} types such as {@link bisq.asset.Coin}, + * {@link bisq.asset.Token} and {@link bisq.asset.Erc20Token}, as well as concrete + * implementations of each, such as {@link bisq.asset.coins.Bitcoin} itself, altcoins like + * {@link bisq.asset.coins.Litecoin} and {@link bisq.asset.coins.Ether} and tokens like + * {@link bisq.asset.tokens.DaiStablecoin}. + *

+ * The purpose of this package is to provide everything necessary for registering + * ("listing") new assets and managing / accessing those assets within, e.g. the Bisq + * Desktop UI. + *

+ * Note that everything within this package is intentionally designed to be simple and + * low-level with no dependencies on any other Bisq packages or components. + * + * @author Chris Beams + * @since 0.7.0 + */ + +package bisq.asset; diff --git a/src/test/java/bisq/asset/AbstractAssetTest.java b/src/test/java/bisq/asset/AbstractAssetTest.java index a658043d..5965e55f 100644 --- a/src/test/java/bisq/asset/AbstractAssetTest.java +++ b/src/test/java/bisq/asset/AbstractAssetTest.java @@ -26,6 +26,23 @@ import static org.hamcrest.CoreMatchers.is; import static org.junit.Assert.assertThat; +/** + * Abstract base class for all {@link Asset} unit tests. Subclasses must implement the + * {@link #testValidAddresses()} and {@link #testInvalidAddresses()} methods, and are + * expected to use the convenient {@link #assertValidAddress(String)} and + * {@link #assertInvalidAddress(String)} assertions when doing so. + *

+ * Blank / empty addresses are tested automatically by this base class and are always + * considered invalid. + *

+ * This base class also serves as a kind of integration test for {@link AssetRegistry}, in + * that all assets tested through subclasses are tested to make sure they are also + * properly registered and available there. + * + * @author Chris Beams + * @author Bernard Labno + * @since 0.7.0 + */ public abstract class AbstractAssetTest { private final AssetRegistry assetRegistry = new AssetRegistry(); diff --git a/src/test/java/bisq/asset/AbstractAssetWithDefaultValidatorTest.java b/src/test/java/bisq/asset/AbstractAssetWithDefaultValidatorTest.java index db5bb82b..9522298d 100644 --- a/src/test/java/bisq/asset/AbstractAssetWithDefaultValidatorTest.java +++ b/src/test/java/bisq/asset/AbstractAssetWithDefaultValidatorTest.java @@ -19,6 +19,15 @@ import org.junit.Test; +/** + * Convenient abstract base class for {@link Asset} implementations still using the + * deprecated {@link DefaultAddressValidator}. + * + * @author Bernard Labno + * @since 0.7.0 + * @see DefaultAddressValidator + */ +@Deprecated public abstract class AbstractAssetWithDefaultValidatorTest extends AbstractAssetTest { public AbstractAssetWithDefaultValidatorTest(Asset asset) {