Merge pull request #186 from iotaledger/dev

Merged 1.0.0beta6 into master

Author: Brord van Wierst

README.md

@@ -69,7 +69,7 @@ To download the IOTA Java client library and its dependencies, you can use one o
 
     ```gradle
     dependencies {
-        compile 'com.github.iotaledger:iota-java:1.0.0-beta5'
+        compile 'com.github.iotaledger:iota-java:1.0.0-beta6'
     }
     ```
     
@@ -96,7 +96,7 @@ To download the IOTA Java client library and its dependencies, you can use one o
     ```
     
 3. Change the value of the `<version>` tag to either a release number or the first 10 characters of a Git commit hash:
-`<version>e4fd314b3e</version>` or `<version>1.0.0-beta5</version>`
+`<version>efdc784d8a9ef</version>` or `<version>1.0.0-beta6</version>`
 
 **Note:** Find the latest version on the [Jitpack](https://jitpack.io/#iotaledger/iota-java) page.
 
@@ -119,6 +119,9 @@ You'll have a .jar file called `jota-[VERSION]-jar-with-dependencies.jar`, depen
 ## Getting Started
 
 After you've [downloaded the library](#downloading-the-library), you can connect to an IRI node to send transactions to it and interact with the ledger.
+An extended guide can be found on our [documentation website](https://docs.iota.org/docs/iota-java/0.1/README), we strongly recommend you to go here for starting 
+off. A quick starting tutorial is shown below.
+
 
 To connect to a local IRI node, do the following:
 
@@ -139,6 +142,7 @@ GetNodeInfoResponse response = api.getNodeInfo();
 ```
 
 **Note:** To separate your IRI node configuration from the implementation, you can also specify your IRI node configuration in a [**Java `.properties` file**](https://en.wikipedia.org/wiki/.properties) or as command line flags. These options are useful if you develop an open-source app which is deployed on a CI and don't want contributors to see the internal IRI node configuration.
+To make the API read from this file, add the configuration to the builder like so: `.config(new FileConfig("node_config.properties"))`
 
 **Example .properties files**
 
@@ -175,9 +179,10 @@ Here are some of the most commonly used API functions:
 ## Examples
 
 We have a list of test cases on the [`src/test/java` directory][tests] that you can use as a reference when developing apps with IOTA.
-A good starter is the [`IotaAPITest` case](https://github.com/iotaledger/iota-java/blob/master/jota/src/test/java/jota/IotaAPITest.java).
+A good starter is the [`IotaAPITest` case](https://github.com/iotaledger/iota-java/blob/master/jota/src/test/java/org/iota/jota/IotaAPITest.java).
 
 ## Change logs:
+- Changes in [**1.0.0-beta6**](https://github.com/iotaledger/iota-java/compare/1.0.0-beta5...1.0.0-beta6)
 - Changes in [**1.0.0-beta5**](https://github.com/iotaledger/iota-java/compare/1.0.0-beta4...1.0.0-beta5)
 - Changes in [**1.0.0-beta4**](https://github.com/iotaledger/iota-java/compare/1.0.0-beta3...1.0.0-beta4)
 - Changes in [**1.0.0-beta3**](https://github.com/iotaledger/iota-java/compare/1.0.0-beta2...1.0.0-beta3)
@@ -194,15 +199,15 @@ A good starter is the [`IotaAPITest` case](https://github.com/iotaledger/iota-ja
 ## Supporting the project
 
 If the IOTA Java client library has been useful to you and you feel like contributing, consider posting a [bug report](https://github.com/iotaledger/iota-java/issues/new-issue), feature request or a [pull request](https://github.com/iotaledger/iota-java/pulls/).  
-We have some [basic contribution guidelines](contribution-guidelines.md) to keep our code base stable and consistent.
+We have some [basic contribution guidelines](CONTRIBUTING.md) to keep our code base stable and consistent.
 
 ## Joining the Discussion
 
 If you want to get involved in the community, need help with getting setup, have any issues related with the library or just want to discuss blockchain, distributed ledgers, and IoT with other people, feel free to join our [Discord](https://discordapp.com/invite/fNGZXvh).  
 
 ## License
 
-The Apache 2.0 license can be found [here](license).
+The Apache 2.0 license can be found [here](LICENSE).
 
 [iota-logo]: https://avatars0.githubusercontent.com/u/20126597?s=200&v=4
 [codacy]: https://www.codacy.com/app/kwek20/iota-java?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=iotaledger/iota-java&amp;utm_campaign=Badge_Grade
@@ -223,6 +228,6 @@ The Apache 2.0 license can be found [here](license).
 [pull-requests]: https://github.com/iotaledger/iota-java/pulls
 [new-pull-request]: https://github.com/iotaledger/iota-java/compare
 [contribution-guidelines]: https://github.com/iotaledger/iota-java/blob/master/CONTRIBUTING.md
-[tests]: https://github.com/iotaledger/iota-java/tree/master/jota/src/test/java/jota
+[tests]: https://github.com/iotaledger/iota-java/tree/master/jota/src/test/java/org/iota/jota
 [iota-discord]: https://discord.gg/7Gu2mG5
 [iota-forum]: https://forum.iota.org/

docs/iota-java/addRemainder.md

@@ -0,0 +1,49 @@
+
+# [addRemainder](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L1598)
+ List<String> addRemainder(String seed , int security , List<[Input](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Input.java)> inputs , [Bundle](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Bundle.java) bundle , String tag , long totalValue , String remainderAddress , List<String> signatureFragments)
+
+Uses input, and adds to the bundle, untill `totalValue` is reached. If there is a remainder left on the last input, a remainder transfer is added.
+> **Important note:** This API is currently in Beta and is subject to change. Use of these APIs in production applications is not supported.
+
+## Input
+| Parameter       | Type | Required or Optional | Description |
+|:---------------|:--------|:--------| :--------|
+| seed | String | Required | The tryte-encoded seed. It should be noted that this seed is not transferred. |
+| security | int | Required | Security level to be used for the private key / address. Can be 1, 2 or 3. |
+| inputs | List<[Input](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Input.java)> | Required | List of inputs used for funding the transfer. |
+| bundle | [Bundle](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Bundle.java) | Required | The [Bundle](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Bundle.java) to be populated. |
+| tag | String | Required | The tag to add to each bundle entry (input and remainder) |
+| totalValue | long | Required | The total value of the desired transaction |
+| remainderAddress | String | Required | The address used for sending the remainder value (of the last input).   If this is `null`, [getNextAvailableAddress(String, int, boolean)](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L115) is used. |
+| signatureFragments | List<String> | Required | The signature fragments (message), used for signing.Should be 2187 characters long, can be padded with 9s. |
+    
+## Output
+| Return type | Description |
+|--|--|
+| List<String>  | A list of signed inputs to be used in a transaction |
+
+## Exceptions
+| Exceptions     | Description |
+|:---------------|:--------|
+| [ArgumentException](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/error/ArgumentException.java) | When the seed is invalid |
+| [ArgumentException](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/error/ArgumentException.java) | When the security level is wrong. |
+| IllegalStateException | When the inputs do not contain enough balance to reach <tt>totalValue</tt>. |
+
+## Related APIs (link to other product documentation)
+| API     | Description |
+|:---------------|:--------|
+| [signInputsAndReturn(String, List, Bundle, List, org.iota.jota.pow.ICurl)](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/utils/IotaAPIUtils.java#L64) | Finalizes and signs the bundle transactions. Bundle and inputs are assumed correct. |
+| [getNextAvailableAddress(String, int, boolean)](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L115) | Checks all addresses until the first unspent address is found. Starts at index 0. |
+
+ ## Example
+ 
+ ```Java
+ IotaAPI iotaAPI = new IotaAPI.Builder().build();
+
+try { 
+    List<String> response = iotaAPI.addRemainder("GJRKVXECSQFPQOEMFNKWZLBKMYXUW9ZX9DCBBKFUFFICTCL9BXCWDEUQWHWRDYYSJEBYRRTJJZEVFXROV", "365", ["inputs", "inputs"], "bundle", "OVTBVZF9UHIMBKAE9NQZUNWZ9AUWGAMTKUPG9BOEOS9LFYYYXGPCOZWVXARKK9QXJJEQITVIODK9AZNOG", "totalvalue", "VIGLBXE9SWTYGJYDLSPNGVTRLIVRVGHXFMMZAIXNGFWZVQYXMQISB99MACJ9XUOVMSXALC99YPWAVCCJL", ["AFGGZR9I9GCPKYAE9PEWRIUDIUBQKQWUOR9BIL9QKUQOTAKTNKYLRTBQ9HL9NRULMPJIDEWIEAMWLLERI", "YHKJKHNRUFGRJ9CYZVFOJXLAWNWC9OEPXMTNPLNUBGKKFI9AOBWTNQZPARWILW9FHSUVRSLFNJNTLVI9K"]);
+} catch (ArgumentException e) { 
+    // Handle error
+    e.printStackTrace(); 
+}
+ ```

docs/iota-java/bundlesFromAddresses.md

@@ -0,0 +1,37 @@
+
+# [bundlesFromAddresses](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L309)
+ [Bundle[]](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Bundle.java) bundlesFromAddresses(Boolean inclusionStates , String[] addresses)
+
+Internal function to get the formatted bundles of a list of addresses.
+> **Important note:** This API is currently in Beta and is subject to change. Use of these APIs in production applications is not supported.
+
+## Input
+| Parameter       | Type | Required or Optional | Description |
+|:---------------|:--------|:--------| :--------|
+| inclusionStates | Boolean | Required | Array of addresses. |
+| addresses | String[] | Required | If `true`, it also gets the inclusion state of each bundle. |
+    
+## Output
+| Return type | Description |
+|--|--|
+| [Bundle[]](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Bundle.java)  | All the transaction bundles for the addresses, or `null` when our thread gets interrupted |
+
+## Exceptions
+| Exceptions     | Description |
+|:---------------|:--------|
+| [ArgumentException](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/error/ArgumentException.java) | When the addresses are invalid |
+| IllegalStateException | When inclusion state/confirmed could not be determined (<tt>null</tt> returned) |
+
+
+ ## Example
+ 
+ ```Java
+ IotaAPI iotaAPI = new IotaAPI.Builder().build();
+
+try { 
+    Bundle response = iotaAPI.bundlesFromAddresses("true", ["KVB9GPIDVFGM9MIVJES9IPRRFUSBWWFLG9BYEOY9JIBMIMBTERXSIXSUUGYEQZZQEQGBKZJNZZVIOSZDL", "LNIHWRCCWVTEZYGEWDZBRHIWVXWCIKSSPGYPB9PU9JYOIP9VQDJU9ADCCZLDDQXCHNLKFLNRKOJZUOIVC"]);
+} catch (ArgumentException e) { 
+    // Handle error
+    e.printStackTrace(); 
+}
+ ```

docs/iota-java/reference/checkWereAddressSpentFrom.md renamed to docs/iota-java/checkWereAddressSpentFrom.md

@@ -1,8 +1,8 @@
 
-# [checkWereAddressSpentFrom](https://github.com/iotaledger/iota-java/blob/dev/jota/src/main/java/jota/IotaAPI.java#L823)
+# [checkWereAddressSpentFrom](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L1022)
  boolean[] checkWereAddressSpentFrom(String[] addresses)
 
-Check if a list of addresses was ever spent from, in the current epoch, or in previous epochs.  If the address has a checksum, it is removed
+Check if a list of addresses was ever spent from, in the current epoch, or in previous epochs. Addresses must have a checksum.
 > **Important note:** This API is currently in Beta and is subject to change. Use of these APIs in production applications is not supported.
 
 ## Input
@@ -18,7 +18,7 @@ Check if a list of addresses was ever spent from, in the current epoch, or in pr
 ## Exceptions
 | Exceptions     | Description |
 |:---------------|:--------|
-| [ArgumentException](https://github.com/iotaledger/iota-java/blob/dev/jota/src/main/java/jota/error/ArgumentException.java) |  |
+| [ArgumentException](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/error/ArgumentException.java) | when an address is invalid |
 
 
  ## Example
@@ -27,7 +27,7 @@ Check if a list of addresses was ever spent from, in the current epoch, or in pr
  IotaAPI iotaAPI = new IotaAPI.Builder().build();
 
 try { 
-    boolean response = iotaAPI.checkWereAddressSpentFrom(["QBMKILBOYESLUCXMNIQIBBOICSRWMO9PMY99YHPACWLFPXLCVAELQZNRFLJPGDHWZHGIQYDG9JLREW99WOEWUXYVLVRXPXJJWSY9LCGSRYKLPZRSEHKKYNBSD9ESNDN9YUPBOGBXOBPOKASLNUEHANHCNWD99GLLMF", "RUKJQZIQHBSPRVRFOQMPIZOTP9FGQBVREIVLYL9HBSMTJCKBNLARQNLVWMEFAJQSEHVZPI9XRPJAKDAHOVRBMRUKREZWXVJEZGXIPREGDPWNFZDWIEPNDLNAN9CGEKEGUPIQNVC9KZGLUISHLZMOQGIHVJOZRRULGG"]);
+    boolean response = iotaAPI.checkWereAddressSpentFrom(["WXBYKDMRDYKCQBJWZZFPNHKZLYINE9TLYSETXLOFXQKRUKDVRGWFQHVPSNHJMNIHU9QVPLPQKSNXRBLAV", "JYWRGZDJJCRUOUVZJKNWGMEWOLJEEQLHAIVM9D9GWEZN9YJZWYLOBGUCBBWIMEUQDYZG9HPVAZZDSVLSP"]);
 } catch (ArgumentException e) { 
     // Handle error
     e.printStackTrace(); 

docs/iota-java/findTransactionObjectsByAddresses.md

@@ -0,0 +1,58 @@
+
+# [findTransactionObjectsByAddresses](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L480)
+ List<[Transaction](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Transaction.java)> findTransactionObjectsByAddresses(String[] addresses)
+
+Wrapper function: Finds transactions, gets trytes and turns it into [Transaction](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Transaction.java) objects.
+> **Important note:** This API is currently in Beta and is subject to change. Use of these APIs in production applications is not supported.
+
+## Input
+| Parameter       | Type | Required or Optional | Description |
+|:---------------|:--------|:--------| :--------|
+| addresses | String[] | Required | The addresses we should get the transactions for, must contain checksums |
+    
+## Output
+List<[Transaction](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Transaction.java)>, which contains the following fields:
+| Return type | Description |
+|--|--|
+| long attachmentTimestampLowerBound |  |
+| long attachmentTimestampUpperBound |  |
+| String hash | Get the hash. |
+| String signatureFragments | Get the signature fragments. |
+| String address | Get the address. |
+| long value | Get the value. |
+| String tag | Get the tag. |
+| long timestamp | Get the timestamp. |
+| long currentIndex | Get the current index. |
+| long lastIndex | Get the last index. |
+| String bundle | Get the bundle. |
+| String trunkTransaction | Get the trunk transaction. |
+| String branchTransaction | Get the branch transaction. |
+| String nonce | Get the nonce. |
+| Boolean persistence | Get the persistence. |
+| String obsoleteTag | Get the obsoleteTag. |
+| long attachmentTimestamp | Get the attachmentTimestamp. |
+| boolean tailTransaction | Checks if the current index is 0 |
+
+## Exceptions
+| Exceptions     | Description |
+|:---------------|:--------|
+| [ArgumentException](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/error/ArgumentException.java) | if addresses is not a valid array of hashes |
+
+## Related APIs (link to other product documentation)
+| API     | Description |
+|:---------------|:--------|
+| [findTransactionsByAddresses(String...)](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPICore.java#L273) | Find the transactions by addresses with checksum |
+| [findTransactionsObjectsByHashes](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L454) | Wrapper function: get trytes and turns into [Transaction](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Transaction.java) objects. Gets the trytes and transaction object from a list of transaction hashes. |
+
+ ## Example
+ 
+ ```Java
+ IotaAPI iotaAPI = new IotaAPI.Builder().build();
+
+try { 
+    List<Transaction> response = iotaAPI.findTransactionObjectsByAddresses(["AYZWDCHCJLLEAXMLMHR9OKZW9KXFQEJVMNNMQCFYAOMVRIIAOYNUVAINKORAFDADZRHFCYWIZVSHZFNLS", "ZHCFE9YXMOOHCHCKFRTCIXCXPTRFHIUITFSUEYORRLQVWKVQQUJTAALHEGJJIWAHEMZNSVDHPLCFTCGMV"]);
+} catch (ArgumentException e) { 
+    // Handle error
+    e.printStackTrace(); 
+}
+ ```

docs/iota-java/findTransactionObjectsByApprovees.md

@@ -0,0 +1,57 @@
+
+# [findTransactionObjectsByApprovees](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPI.java#L516)
+ List<[Transaction](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Transaction.java)> findTransactionObjectsByApprovees(String[] approvees)
+
+Wrapper function: Finds transactions, gets trytes and turns it into [Transaction](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Transaction.java) objects.
+> **Important note:** This API is currently in Beta and is subject to change. Use of these APIs in production applications is not supported.
+
+## Input
+| Parameter       | Type | Required or Optional | Description |
+|:---------------|:--------|:--------| :--------|
+| approvees | String[] | Required | The transaction hashes of which we want to approvers |
+    
+## Output
+List<[Transaction](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/model/Transaction.java)>, which contains the following fields:
+| Return type | Description |
+|--|--|
+| long attachmentTimestampLowerBound |  |
+| long attachmentTimestampUpperBound |  |
+| String hash | Get the hash. |
+| String signatureFragments | Get the signature fragments. |
+| String address | Get the address. |
+| long value | Get the value. |
+| String tag | Get the tag. |
+| long timestamp | Get the timestamp. |
+| long currentIndex | Get the current index. |
+| long lastIndex | Get the last index. |
+| String bundle | Get the bundle. |
+| String trunkTransaction | Get the trunk transaction. |
+| String branchTransaction | Get the branch transaction. |
+| String nonce | Get the nonce. |
+| Boolean persistence | Get the persistence. |
+| String obsoleteTag | Get the obsoleteTag. |
+| long attachmentTimestamp | Get the attachmentTimestamp. |
+| boolean tailTransaction | Checks if the current index is 0 |
+
+## Exceptions
+| Exceptions     | Description |
+|:---------------|:--------|
+| [ArgumentException](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/error/ArgumentException.java) | if addresses is not a valid array of hashes |
+
+## Related APIs (link to other product documentation)
+| API     | Description |
+|:---------------|:--------|
+| [findTransactionsByApprovees](https://github.com/iotaledger/iota-java/blob/master/jota/src/main/java/org/iota/jota/IotaAPICore.java#L304) | Find the transactions by approvees |
+
+ ## Example
+ 
+ ```Java
+ IotaAPI iotaAPI = new IotaAPI.Builder().build();
+
+try { 
+    List<Transaction> response = iotaAPI.findTransactionObjectsByApprovees(["VKXPUUA9QIRJCIPIOGOWCLTDHNPAM99NYWPKOCVDKJVES9EWQ9TN9IMIU9GRTANLI9QMZEBGNZTOR9OVB", "FQCOXX99V9HMBAKSFKJTMDYUPKNYLGFE9LAJMRFQIGTOQNGXWEXVGALCEHHTC9LFTQY9IRJWLZZFFAGUN"]);
+} catch (ArgumentException e) { 
+    // Handle error
+    e.printStackTrace(); 
+}
+ ```