Skip to content

Commit bc451b8

Browse files
committed
documentation
1 parent e99b19e commit bc451b8

9 files changed

Lines changed: 270 additions & 80 deletions

File tree

‎src/main/java/jota/IotaAPI.java‎

Lines changed: 70 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ protected IotaAPI(Builder builder) {
4646
* @param total Optional (default 1)Total number of addresses to generate
4747
* @param returnAll If true, it returns all addresses which were deterministically generated (until findTransactions returns null)
4848
* @return an array of strings with the specifed number of addresses
49+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
50+
* @exception InvalidSecurityLevelException is thrown when the specified security level is not valid
4951
*/
5052
public GetNewAddressResponse getNewAddress(final String seed, int security, final int index, final boolean checksum, final int total, final boolean returnAll) throws InvalidSecurityLevelException, InvalidAddressException {
5153

@@ -94,7 +96,14 @@ public GetNewAddressResponse getNewAddress(final String seed, int security, fina
9496
* @param end end Ending key index
9597
* @param inclusionStates Optional (default false). If True, it gets the inclusion states of the transfers.
9698
* @return Bundle
97-
**/
99+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
100+
* @throws ArgumentException
101+
* @throws InvalidBundleException
102+
* @throws InvalidSignatureException
103+
* @throws NoNodeInfoException
104+
* @throws NoInclusionStatesExcpection
105+
* @exception InvalidSecurityLevelException is thrown when the specified security level is not valid
106+
*/
98107
public GetTransferResponse getTransfers(String seed, int security, Integer start, Integer end, Boolean inclusionStates) throws ArgumentException, InvalidBundleException, InvalidSignatureException, NoNodeInfoException, NoInclusionStatesExcpection, InvalidSecurityLevelException, InvalidAddressException {
99108
StopWatch stopWatch = new StopWatch();
100109
// validate & if needed pad seed
@@ -317,11 +326,15 @@ public List<Transaction> findTransactionObjectsByBundle(String[] input) {
317326
* @param remainder Optional (default null). if defined, this address will be used for sending the remainder value (of the inputs) to.
318327
* @param inputs the inputs
319328
* @return trytes Returns bundle trytes
320-
**/
329+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
330+
* @throws NotEnoughBalanceException
331+
* @exception InvalidSecurityLevelException is thrown when the specified security level is not valid
332+
* @throws InvalidTransferException
333+
*/
321334
public List<String> prepareTransfers(String seed, int security, final List<Transfer> transfers, String remainder, List<Input> inputs) throws NotEnoughBalanceException, InvalidSecurityLevelException, InvalidAddressException, InvalidTransferException {
322335

323336
// Input validation of transfers object
324-
if (!InputValidator.isTransfersCollectionCorrect(transfers)) {
337+
if (!InputValidator.isTransfersCollectionValid(transfers)) {
325338
throw new InvalidTransferException();
326339
}
327340

@@ -475,6 +488,9 @@ public List<String> prepareTransfers(String seed, int security, final List<Trans
475488
* @param start start Starting key index
476489
* @param end end Ending key index
477490
* @param threshold threshold Min balance required
491+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
492+
* @exception InvalidSecurityLevelException
493+
478494
**/
479495
public GetBalancesAndFormatResponse getInputs(String seed, int security, int start, int end, long threshold) throws InvalidSecurityLevelException, InvalidAddressException {
480496
StopWatch stopWatch = new StopWatch();
@@ -525,7 +541,6 @@ public GetBalancesAndFormatResponse getInputs(String seed, int security, int sta
525541
}
526542
}
527543

528-
529544
/**
530545
* Gets the balances and formats the output
531546
*
@@ -536,6 +551,7 @@ public GetBalancesAndFormatResponse getInputs(String seed, int security, int sta
536551
* @param stopWatch the stopwatch
537552
* @param security security secuirty level of private key / seed
538553
* @return Inputs object
554+
* @exception InvalidSecurityLevelException is thrown when the specified security level is not valid
539555
**/
540556
public GetBalancesAndFormatResponse getBalanceAndFormat(final List<String> addresses, long threshold, int start, int end, StopWatch stopWatch, int security) throws InvalidSecurityLevelException {
541557

@@ -583,7 +599,10 @@ public GetBalancesAndFormatResponse getBalanceAndFormat(final List<String> addre
583599
* Does validation of signatures, total sum as well as bundle order
584600
* @param transaction the transaction encoded in trytes
585601
* @return an array of bundle, if there are multiple arrays it means that there are conflicting bundles.
586-
**/
602+
* @throws ArgumentException
603+
* @throws InvalidBundleException
604+
* @throws InvalidSignatureException
605+
*/
587606
public GetBundleResponse getBundle(String transaction) throws ArgumentException, InvalidBundleException, InvalidSignatureException {
588607
StopWatch stopWatch = new StopWatch();
589608

@@ -666,7 +685,11 @@ public GetBundleResponse getBundle(String transaction) throws ArgumentException,
666685
* @param depth the depth
667686
* @param minWeightMagnitude the minimum weight magnitude
668687
* @return analyzed Transaction objects
669-
**/
688+
* @throws InvalidBundleException
689+
* @throws ArgumentException
690+
* @throws InvalidSignatureException
691+
* @throws InvalidTrytesException
692+
*/
670693
public ReplayBundleResponse replayBundle(String transaction, int depth, int minWeightMagnitude) throws InvalidBundleException, ArgumentException, InvalidSignatureException, InvalidTrytesException {
671694
StopWatch stopWatch = new StopWatch();
672695

@@ -699,7 +722,8 @@ public ReplayBundleResponse replayBundle(String transaction, int depth, int minW
699722
*
700723
* @param hashes the hashes
701724
* @return inclusion state
702-
**/
725+
* @throws NoNodeInfoException
726+
*/
703727
public GetInclusionStateResponse getLatestInclusion(String[] hashes) throws NoNodeInfoException {
704728
GetNodeInfoResponse getNodeInfoResponse = getNodeInfo();
705729
if (getNodeInfoResponse == null) throw new NoNodeInfoException();
@@ -712,16 +736,21 @@ public GetInclusionStateResponse getLatestInclusion(String[] hashes) throws NoNo
712736
/**
713737
* Wrapper function that basically does prepareTransfers, as well as attachToTangle and finally, it broadcasts and stores the transactions locally.
714738
*
715-
* @param seed tryte-encoded seed
716-
* @param security security secuirty level of private key / seed
717-
* @param depth the depth
739+
* @param seed tryte-encoded seed
740+
* @param security security secuirty level of private key / seed
741+
* @param depth the depth
718742
* @param minWeightMagnitude the minimum weight magnitude
719-
* @param transfers array of transfer objects
720-
* @param inputs Option (default null). List of inputs used for funding the transfer
721-
* @param address if defined, this address will be used for sending the remainder value (of the inputs) to
743+
* @param transfers array of transfer objects
744+
* @param inputs List of inputs used for funding the transfer
745+
* @param address if defined, this address will be used for sending the remainder value (of the inputs) to
722746
* @return array of Transaction objects
723-
**/
724-
747+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
748+
* @throws NotEnoughBalanceException
749+
* @exception InvalidSecurityLevelException is thrown when the specified security level is not valid
750+
* @throws InvalidTrytesException
751+
* @throws InvalidAddressException
752+
* @throws InvalidTransferException
753+
*/
725754
public SendTransferResponse sendTransfer(String seed, int security, int depth, int minWeightMagnitude, final List<Transfer> transfers, Input[] inputs, String address) throws NotEnoughBalanceException, InvalidSecurityLevelException, InvalidTrytesException, InvalidAddressException, InvalidTransferException {
726755

727756
if (security < 1 || security > 3) {
@@ -754,7 +783,8 @@ public SendTransferResponse sendTransfer(String seed, int security, int depth, i
754783
* @param bundleHash the bundle hashes
755784
* @param bundle List of bundles to be populated
756785
* @return bundle Transaction objects
757-
**/
786+
* @throws ArgumentException
787+
*/
758788
public Bundle traverseBundle(String trunkTx, String bundleHash, Bundle bundle) throws ArgumentException {
759789
GetTrytesResponse gtr = getTrytes(trunkTx);
760790

@@ -805,7 +835,10 @@ public Bundle traverseBundle(String trunkTx, String bundleHash, Bundle bundle) t
805835
* @param inputAddress array of input addresses as well as the securitySum
806836
* @param remainderAddress has to be generated by the cosigners before initiating the transfer, can be null if fully spent
807837
* @return bundle of transaction objects
808-
**/
838+
* @throws InvalidAddressException
839+
* @throws InvalidBundleException
840+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
841+
*/
809842
private GetTransferResponse initiateTransfer(int securitySum, final List<String> inputAddress, String remainderAddress, final List<Transfer> transfers) throws InvalidAddressException, InvalidBundleException, InvalidTransferException {
810843
StopWatch sw = new StopWatch();
811844

@@ -824,7 +857,7 @@ private GetTransferResponse initiateTransfer(int securitySum, final List<String>
824857
}
825858

826859
// Input validation of transfers object
827-
if (!InputValidator.isTransfersCollectionCorrect(transfers)) {
860+
if (!InputValidator.isTransfersCollectionValid(transfers)) {
828861
throw new InvalidTransferException();
829862
}
830863

@@ -970,6 +1003,11 @@ private GetTransferResponse initiateTransfer(int securitySum, final List<String>
9701003

9711004
}
9721005

1006+
/**
1007+
* @param hash The hash.
1008+
* @return
1009+
* @throws ArgumentException
1010+
*/
9731011
public String findTailTransactionHash(String hash) throws ArgumentException {
9741012
GetTrytesResponse gtr = getTrytes(hash);
9751013

@@ -987,6 +1025,20 @@ public String findTailTransactionHash(String hash) throws ArgumentException {
9871025
else return findTailTransactionHash(trx.getBundle());
9881026
}
9891027

1028+
/**
1029+
* @param seed tryte-encoded seed
1030+
* @param security security secuirty level of private key / seed
1031+
* @param inputs List of inputs used for funding the transfer
1032+
* @param bundle to be populated
1033+
* @param tag the tag.
1034+
* @param totalValue The total value.
1035+
* @param remainderAddress if defined, this address will be used for sending the remainder value (of the inputs) to
1036+
* @param signatureFragments The signature fragments.
1037+
* @return
1038+
* @throws NotEnoughBalanceException
1039+
* @throws InvalidSecurityLevelException is thrown when the specified security level is not valid
1040+
* @throws InvalidAddressException is thrown when the specified address is not an valid address
1041+
*/
9901042
public List<String> addRemainder(final String seed,
9911043
final int security,
9921044
final List<Input> inputs,

‎src/main/java/jota/pow/ICurl.java‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,72 @@
11
package jota.pow;
22

33
/**
4+
* This interface abstracts the curl hashing algorithm
45
* @author Adrian
56
*/
67
public interface ICurl {
8+
9+
/**
10+
* Absorbs the specified trits.
11+
*
12+
* @param trits The trits.
13+
* @param offset The offset to start from.
14+
* @param length The length.
15+
* @return
16+
*/
717
ICurl absorb(final int[] trits, int offset, int length);
818

19+
/**
20+
* Absorbs the specified trits.
21+
*
22+
* @param trits The trits.
23+
* @return
24+
*/
925
ICurl absorb(final int[] trits);
1026

27+
/**
28+
* Squeezes the specified trits.
29+
* @param trits The trits.
30+
* @param offset The offset to start from.
31+
* @param length The length.
32+
* @return
33+
*/
1134
int[] squeeze(final int[] trits, int offset, int length);
1235

36+
/**
37+
* Squeezes the specified trits.
38+
* @param trits The trits.
39+
* @return
40+
*/
1341
int[] squeeze(final int[] trits);
1442

43+
/**
44+
* Transforms this instance.
45+
* @return
46+
*/
1547
ICurl transform();
1648

49+
/**
50+
* Resets this state.
51+
* @return
52+
*/
1753
ICurl reset();
1854

55+
/**
56+
* Gets or sets the state.
57+
* @return
58+
*/
1959
int[] getState();
2060

61+
/**
62+
* Sets or sets the state.
63+
* @param state
64+
*/
2165
void setState(int[] state);
2266

67+
/**
68+
* Clones this instance.
69+
* @return
70+
*/
2371
ICurl clone();
2472
}

‎src/main/java/jota/utils/Checksum.java‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,11 @@
1010
public class Checksum {
1111

1212
/**
13-
* adds the checksum to the specified address
13+
* Adds the checksum to the specified address
1414
*
1515
* @param address address without checksum
1616
* @return the address with the appended checksum
17+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
1718
**/
1819
public static String addChecksum(String address) throws InvalidAddressException {
1920
InputValidator.checkAddress(address);
@@ -23,10 +24,11 @@ public static String addChecksum(String address) throws InvalidAddressException
2324
}
2425

2526
/**
26-
* remove the checksum to the specified address
27+
* Remove the checksum to the specified address
2728
*
2829
* @param address address with checksum
2930
* @return the address without checksum
31+
* @exception InvalidAddressException is thrown when the specified address is not an address with checksum
3032
**/
3133
public static String removeChecksum(String address) throws InvalidAddressException {
3234
if (isAddressWithChecksum(address)) {
@@ -46,10 +48,11 @@ private static String getAddress(String addressWithChecksum) {
4648
}
4749

4850
/**
49-
* check if checksum is valid
51+
* Determines whether the specified address with checksum has a valid checksum.
5052
*
5153
* @param addressWithChecksum address
52-
* @return boolean
54+
* @return <c>true</c> if the specified address with checksum has a valid checksum [the specified address with checksum]; otherwise, <c>false</c>.
55+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
5356
**/
5457
public static boolean isValidChecksum(String addressWithChecksum) throws InvalidAddressException {
5558
String addressWithoutChecksum = removeChecksum(addressWithChecksum);
@@ -63,6 +66,7 @@ public static boolean isValidChecksum(String addressWithChecksum) throws Invalid
6366
*
6467
* @param address address
6568
* @return boolean
69+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
6670
**/
6771
public static boolean isAddressWithChecksum(String address) throws InvalidAddressException {
6872
return InputValidator.checkAddress(address) && address.length() == Constants.ADDRESS_LENGTH_WITH_CHECKSUM;
@@ -74,6 +78,7 @@ public static boolean isAddressWithChecksum(String address) throws InvalidAddres
7478
*
7579
* @param address address
7680
* @return boolean
81+
* @exception InvalidAddressException is thrown when the specified address is not an valid address
7782
**/
7883
public static boolean isAddressWithoutChecksum(String address) throws InvalidAddressException {
7984
return InputValidator.checkAddress(address) && address.length() == Constants.ADDRESS_LENGTH_WITHOUT_CHECKSUM;

‎src/main/java/jota/utils/Constants.java‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,23 @@
66
*/
77
public class Constants {
88

9+
/**
10+
* This String contains all possible characters of the tryte alphabet
11+
*/
912
public static final String TRYTE_ALPHABET = "9ABCDEFGHIJKLMNOPQRSTUVWXYZ";
1013

14+
/**
15+
* The maximum seed length
16+
*/
1117
public static final int SEED_LENGTH_MAX = 81;
1218

19+
/**
20+
* The length of an address without checksum
21+
*/
1322
public static int ADDRESS_LENGTH_WITHOUT_CHECKSUM = 81;
23+
24+
/**
25+
* The length of an address with checksum
26+
*/
1427
public static int ADDRESS_LENGTH_WITH_CHECKSUM = 90;
1528
}

0 commit comments

Comments
 (0)