From a290c8dd4366c1b706acabeeec1152771305c6c5 Mon Sep 17 00:00:00 2001 From: Maykel Arias Torres Date: Mon, 14 Jan 2019 01:12:34 -0500 Subject: [PATCH 1/2] refs #10 Init doc the libjava , definitions step by release, and changes in .gitignore --- .gitignore | 3 + README.md | 274 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 277 insertions(+) create mode 100644 README.md diff --git a/.gitignore b/.gitignore index 6a4480d..d9e4c68 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,6 @@ tests/mytest.py *.swp *.swo +# IDE +.idea + diff --git a/README.md b/README.md new file mode 100644 index 0000000..b9e7b53 --- /dev/null +++ b/README.md @@ -0,0 +1,274 @@ +# LibSkycoin for Java + +[![Build Status](https://travis-ci.org/libskycoin-dotnet.svg?branch=develop)](https://travis-ci.org/simelo/libskycoin-dotnet) + +Java client library for Skycoin API. This library is a .Net assembly generated with SWIG to access Skycoin API from Java. + +## Table of Contents + + + +- [LibSkycoin for Java](#libskycoin-for-java) + - [Table of Contents](#table-of-contents) + - [Install from sources](#install-from-sources) + - [Usage](#usage) + - [Naming](#naming) + - [Parameters](#parameters) + - [Handles](#handles) + - [Byte slices](#byte-slices) + - [Structures](#structures) + - [Fixed Sized Arrays](#fixed-sized-arrays) + - [Other Slices](#other-slices) + - [Memory Management](#memory-management) + - [Make Rules](#make-rules) + - [Development setup](#development-setup) + - [Running tests](#running-tests) + - [Releases](#releases) + - [Update the version](#update-the-version) + - [Pre-release testing](#pre-release-testing) + - [Creating release builds](#creating-release-builds) + + + + +## Install from sources + +Download the repository from https://github.com/simelo/libjava-skycoin.git. +Execute (`mvn compile`) to install the library. Although executing (`mvn test`) is a better choice for making changes to the library. However, when using tox these commands are not required at all because calling tox will make any necessary installation and execute the tests. + +## Usage + +### Naming + +The exported function in Libskycoin Java have the following naming format: `SKY_package_func_name` where package is replace by the package where the original Skycoin function is and func_name is the name of the function. For example, `LoadConfig` function from `cli` package is called in Java `SKY_cli_LoadConfig` + +### Parameters + +All skycoin exported functions return an error object as the last of the return parameters. In Java error is return as an `long` and it is the first return parameter. The rest of the parameters are returned in the same order. + +Receivers in Skycoin are the first of the input parameters. Simple types, like integer, float, string will be used as the corresponding types in Java, except what act as pointers. + +#### Handles + +Some of Skycoin types are too complex to be exported to a scripting language. So, handles are used instead. Therefore all functions taking a complex type will receive a handle instead of the original Skycoin type. For example, having these functions exported from Skycoin: + +```go + func LoadConfig() (Config, error) + func (c Config) FullWalletPath() string +``` + +Config is a struct type that is treated as a handle in Libskycoin Java . The usage in Java will be: + +```java + + public class Skycoin extends skycoin { + + public function main(){ + var configHandle = new_Config_HandlePtr(); + var err = SKY_cli_LoadConfig(configHandle); + if(err == SKY_OK) { + // SkY_OK means no error + var fullWalletPath = new _GoString()_; + err = SKY_cli_FullWalletPath(configHandle,fullWallerPath); + Assert.AreEqual(err,SKY_OK); + Console.WriteLine(fullWallerPath.p); + + //Close the handle after using the it + //so the garbage collector can delete the object associated with it. + SKY_handle_close( configHandle ); + } else { + #Error + Console.WriteLine(err); + } + } + } + +``` + +#### Byte slices + +Parameters of type byte[] will treated as string . Example, this function in Skycoin: + +```go +func (s ScryptChacha20poly1305) Encrypt(data, password []byte) ([]byte, error) +``` + +... should be invoked like this: + +```csharp +var encrypt_settings = new encrypt__ScryptChacha20poly1305(); +var data = new GoSlice(); //It will be passed as a parameter of type []byte +var pwd = new GoSlice(); //As []byte too +var dataStr = new _GoString(); +var pwdStr = new _GoString(); +var encrypted = new GoSlice(); + +dataStr.setString("Data to encrypt" ); +data.convertString(dataStr); +pwdStr.SetString("password"); +pwd.convertString(pwdStr); + +var err = SKY_encrypt_ScryptChacha20poly1305_Encrypt(encrypt_settings, data, pwd,encrypted); +if(err == SKY_OK){ + Console.WriteLine(encrypted.getString().p); //Encrypted is GoSlice +} +``` + +#### Structures + +Structures that are not exported as handles are treated like .NET classes. In the previous example type ScryptChacha20poly1305 is created in Java like: + +```csharp +var encrypt_settings = new encrypt__ScryptChacha20poly1305() +``` + +And passed as first parameter in call to `SKY_encrypt_ScryptChacha20poly1305_Encrypt`. + +#### Fixed Sized Arrays + +Parameters of fixed size array are wrapped in structures when called from Java. + +Given these types in Skycoin and this exported function: + +```go + type PubKey [33]byte + type SecKey [32]byte + + func GenerateDeterministicKeyPair(seed []byte) (PubKey, SecKey) +``` + +This is a way to use them to write assertions in Java: + +```csharp +//Generates random seed +var data = new GoSlice(); +var err = SKY_cipher_RandByte(32,data); + +Assert.AreEqual(err,SKY_OK); + +var pubkey = new cipher_PubKey(); +var seckey = new cipher_SecKey(); + +err = SKY_cipher_GenerateDeterministicKeyPair(data, pubkey,seckey); +``` + +In the example above `pubkey` and `seckey` are objects of an structure type containing a field named `data` holding the corresponding instance of `PubKey` and `SecKey`. Something like: + +```cpp + cipher_PubKey struct{ + data [33]byte; + } cipher_PubKey; + + cipher_SecKey struct{ + data [32]byte; + } ; +``` + +#### Other Slices + +Other slices of base type different from `byte` are indeed wrapped inside classes. Let's see how to call the following function: + +```go +func GenerateDeterministicKeyPairs(seed []byte, n int) []SecKey +``` + +In Java this how it should be used to generate a deterministic sequence of pairs of public / private keys given a random seed: + +```csharp +//Generates random seed +var seed = new GoSlice(); +var err = SKY_cipher_RandByte(32,seed); +var seckeys = new cipher__SecKeys(); + +err = SKY_cipher_GenerateDeterministicKeyPairs(seed, 2,seckeys); + +for(int i=0;i Date: Thu, 17 Jan 2019 15:07:36 -0500 Subject: [PATCH 2/2] refs #10 Updating changes for the library, release definition and tutorials --- README.md | 104 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 57 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index b9e7b53..e51b001 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # LibSkycoin for Java -[![Build Status](https://travis-ci.org/libskycoin-dotnet.svg?branch=develop)](https://travis-ci.org/simelo/libskycoin-dotnet) +[![Build Status](https://travis-ci.org/simelo/libjava-skycoin.svg?branch=develop)](https://travis-ci.org/simelo/libjava-skycoin) Java client library for Skycoin API. This library is a .Net assembly generated with SWIG to access Skycoin API from Java. @@ -63,24 +63,23 @@ Config is a struct type that is treated as a handle in Libskycoin Java . The usa public class Skycoin extends skycoin { - public function main(){ - var configHandle = new_Config_HandlePtr(); - var err = SKY_cli_LoadConfig(configHandle); - if(err == SKY_OK) { - // SkY_OK means no error - var fullWalletPath = new _GoString()_; - err = SKY_cli_FullWalletPath(configHandle,fullWallerPath); - Assert.AreEqual(err,SKY_OK); - Console.WriteLine(fullWallerPath.p); - - //Close the handle after using the it - //so the garbage collector can delete the object associated with it. - SKY_handle_close( configHandle ); - } else { - #Error - Console.WriteLine(err); - } - } + public void main() { + SWIGTYPE_p_Config__Handle configHandle = new_Config_HandlePtr(); + long err = SKY_cli_LoadConfig(configHandle); + if (err == SKY_OK) { + // SkY_OK means no error + _GoString_ fullWalletPath = new _GoString_(); + err = SKY_cli_FullWalletPath(configHandle, fullWallerPath); + assertEquals(err, SKY_OK); + System.out.println(fullWallerPath.getP()); + //Close the handle after using the it + //so the garbage collector can delete the object associated with it. + SKY_handle_close(configHandle); + } else { + // Error + System.out.println(err); + } + } } ``` @@ -95,22 +94,22 @@ func (s ScryptChacha20poly1305) Encrypt(data, password []byte) ([]byte, error) ... should be invoked like this: -```csharp -var encrypt_settings = new encrypt__ScryptChacha20poly1305(); -var data = new GoSlice(); //It will be passed as a parameter of type []byte -var pwd = new GoSlice(); //As []byte too -var dataStr = new _GoString(); -var pwdStr = new _GoString(); -var encrypted = new GoSlice(); +```java +encrypt__ScryptChacha20poly1305 encrypt_settings = new encrypt__ScryptChacha20poly1305(); +GoSlice data = new GoSlice(); //It will be passed as a parameter of type []byte +GoSlice pwd = new GoSlice(); //As []byte too +_GoString_ dataStr = new _GoString_(); +_GoString_ pwdStr = new _GoString_(); +GoSlice encrypted = new GoSlice(); dataStr.setString("Data to encrypt" ); data.convertString(dataStr); pwdStr.SetString("password"); pwd.convertString(pwdStr); -var err = SKY_encrypt_ScryptChacha20poly1305_Encrypt(encrypt_settings, data, pwd,encrypted); +long err = SKY_encrypt_ScryptChacha20poly1305_Encrypt(encrypt_settings, data, pwd,encrypted); if(err == SKY_OK){ - Console.WriteLine(encrypted.getString().p); //Encrypted is GoSlice + System.out.println(encrypted.getString().getP()); //Encrypted is GoSlice } ``` @@ -118,8 +117,8 @@ if(err == SKY_OK){ Structures that are not exported as handles are treated like .NET classes. In the previous example type ScryptChacha20poly1305 is created in Java like: -```csharp -var encrypt_settings = new encrypt__ScryptChacha20poly1305() +```java +encrypt__ScryptChacha20poly1305 encrypt_settings = new encrypt__ScryptChacha20poly1305() ``` And passed as first parameter in call to `SKY_encrypt_ScryptChacha20poly1305_Encrypt`. @@ -139,15 +138,15 @@ Given these types in Skycoin and this exported function: This is a way to use them to write assertions in Java: -```csharp +```java //Generates random seed -var data = new GoSlice(); -var err = SKY_cipher_RandByte(32,data); +GoSlice data = new GoSlice(); +long err = SKY_cipher_RandByte(32,data); -Assert.AreEqual(err,SKY_OK); +assertEquals(err,SKY_OK); -var pubkey = new cipher_PubKey(); -var seckey = new cipher_SecKey(); +cipher_PubKey pubkey = new cipher_PubKey(); +cipher_SecKey seckey = new cipher_SecKey(); err = SKY_cipher_GenerateDeterministicKeyPair(data, pubkey,seckey); ``` @@ -174,22 +173,22 @@ func GenerateDeterministicKeyPairs(seed []byte, n int) []SecKey In Java this how it should be used to generate a deterministic sequence of pairs of public / private keys given a random seed: -```csharp +```java //Generates random seed -var seed = new GoSlice(); -var err = SKY_cipher_RandByte(32,seed); -var seckeys = new cipher__SecKeys(); +GoSlice seed = new GoSlice(); +long err = SKY_cipher_RandByte(32,seed); +cipher__SecKeys seckeys = new cipher__SecKeys(); err = SKY_cipher_GenerateDeterministicKeyPairs(seed, 2,seckeys); for(int i=0;i