mirrors/bitcoinj
1
0
Fork 0
mirror of https://github.com/bitcoinj/bitcoinj.git synced 2025-03-10 09:20:04 +01:00
Code Issues Projects Releases Packages Wiki Activity

Address, AddressParser: improve JavaDoc regarding network normalization

Browse source
This commit is contained in:
Sean Gilligan 2023-10-02 09:59:00 -07:00 • committed by Andreas Schildbach
parent a5ab229f9f
commit fea737b39b
2 changed files with 15 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
core/src/main/java/org/bitcoinj/base/Address.java
View file

@ -107,8 +107,13 @@ public interface Address extends Comparable<Address> {
int compareTo(Address o);
/**
* Get the network this address works on. Use of {@link BitcoinNetwork} is preferred to use of {@link NetworkParameters}
* when you need to know what network an address is for.
* Get the network this address is used on. Returns the <i>normalized</i> network (see below.)
* <p>
* <b>Note:</b> The network value returned is <i>normalized</i>. For example the address {@code "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx"}
* may be used on either {@link BitcoinNetwork#TESTNET} or {@link BitcoinNetwork#SIGNET}, but the value returned by
* this method will always be {@link BitcoinNetwork#TESTNET}. Similarly, the address {@code "mnHUcqUVvrfi5kAaXJDQzBb9HsWs78b42R"}
* may be used on {@link BitcoinNetwork#TESTNET}, {@link BitcoinNetwork#REGTEST}, or {@link BitcoinNetwork#REGTEST}, but
* the value returned by this method will always be {@link BitcoinNetwork#TESTNET}.
* @return the Network.
*/
Network network();

15
core/src/main/java/org/bitcoinj/base/AddressParser.java
View file

@ -22,17 +22,18 @@ import org.bitcoinj.core.NetworkParameters;
import javax.annotation.Nullable;
/**
* Functional interface for address parsing. It takes a single parameter, but its behavior is context-specific. For example if the
* function was created with ({@link AddressParser#getDefault(Network)} it will only parse addresses for a single expected
* value of {@link Network}. Or, if created with {@link AddressParser#getDefault()} it will parse addresses matching any
* network. The default set of known networks is defined by {@link BitcoinNetwork}, but be aware that the {@link Address#network()} value
* is normalized (see {@link Address} for details.
* Functional interface for parsing an {@link Address}. It takes a {@link String} parameter and will parse address
* strings for a configured set of {@link Network}s. For example, if the parser was created with ({@link AddressParser#getDefault(Network)}
* it will only parse addresses for the provided value of {@link Network}. If created with {@link AddressParser#getDefault()} it will parse
* addresses matching any known network. The default set of known networks is defined by {@link BitcoinNetwork}.
* <p>
* Note: Be aware that the value returned by {@link Address#network()} will be normalized. See {@link Address#network()} for details.
*/
@FunctionalInterface
public interface AddressParser {
/**
* Parse an address for any known/configured network
* @param addressString string representation of address
* Parse an address for a configured set of {@link Network}s.
* @param addressString string representation of an address
* @return A validated address object
* @throws AddressFormatException invalid address string
*/