icondev

> hyperconnect the world _

ICON is a scalable smart contract enabled blockchain platform with a long-term goal of interoperability between enterprise and public blockchains. Our goal is to Hyperconnect the World, and by combining groundbreaking technology, a strong community, and relentless growth strategies we believe this goal is reachable.

Get Started    

Java SDK

The source code is found on GitHub at https://github.com/icon-project/icon-sdk-java

This document describes how to interact with ICON Network using Java SDK. This document contains API usages, examples and way to import to user's Java project.

Quick Start

A simple query of the block by height is as follows.

IconService iconService = new IconService(new HttpProvider("https://url"));

// Gets a block matching the block height.
Request<Block> request = iconService.getBlock(height);
try {
    Block block = request.execute();
    ...
} catch (IOException e) {
    ...    
}

IconService

APIs are called through IconService.
It can be initialized as follows.

// Creates an instance of IconService using the HTTP provider.
IconService iconService = new IconService(new HttpProvider("https://url"));

With the customized httpclient is

OkHttpClient okHttpClient = new OkHttpClient.Builder()
    .readTimeout(200, TimeUnit.MILLISECONDS)
    .writeTimeout(600, TimeUnit.MILLISECONDS)
    .build();

IconService iconService = new IconService(new HttpProvider(okHttpClient, "https://url"));

Queries

All queries are requested by a Request object.
Its requests are executed as Synchronized or Asynchronized.
Once the request has been executed, the request can not be executed again.

Request<Block> request = iconService.getBlock(height);

// Asynchronized request execution
request.execute(new Callback<Block>(){
    void onFailure(Exception exception) {
        ...
    }

    void onResponse(Block block) {
        ...
    }
});

// Synchronized request execution
try {
    Block block = request.execute();
    ...
} catch (Exception e) {
    ...
}

The querying APIs are as follows.

// Gets the block
Request<Block> request = iconService.getBlock(new BigInteger("1000")); // by height
Request<Block> request = iconService.getBlock(new Bytes("0x000...000"); // by hash
Request<Block> request = iconService.getLatestBlock(); // latest block

// Gets the balance of an given account
Request<BigInteger> request = iconService.getBalance(new Address("hx000...1");

// Gets a list of the SCORE API
Request<List<ScoreApi>> request = iconService.getScoreApi(new Address("cx000...1"));

// Gets the total supply of icx
Request<BigInteger> request = iconService.getTotalSupply();

// Gets a transaction matching the given transaction hash
Request<Transaction> request = iconService.getTransaction(new Bytes("0x000...000"));

// Gets the result of the transaction matching the given transaction hash
Request<TransactionResult> request = iconService.getTransactionResult(new Bytes("0x000...000"));


// Calls a SCORE API just for reading
Call<BigInteger> call = new Call.Builder()
    .from(wallet.getAddress())
    .to(scoreAddress)
    .method("balanceOf")
    .params(params)
    .buildWith(BigInteger.class);
Request<BigInteger> request = iconService.call(call);

// Calls without response type                                                     
Call<RpcItem> call = new Call.Builder()
    .from(wallet.getAddress())
    .to(scoreAddress)
    .method("balanceOf")
    .params(params)
    .build();
Request<RpcItem> request = iconService.call(call);
try {
    RpcItem rpcItem = request.execute();
    BigInteger balance = rpcItem.asInteger();
    ...
} catch (Exception e) {
    ...
}

Sending Transactions

Calling SCORE APIs to change states is requested as sending a transaction.

Before sending a transaction, the transaction should be signed. It can be done using a Wallet object.

Loading wallets and storing the Keystore

// Generates a wallet.
Wallet wallet = KeyWallet.create();

// Loads a wallet from the private key.
Wallet wallet = KeyWallet.load(new Bytes("0x0000"));

// Loads a wallet from the key store file.
File file = new File("./key.keystore");
Wallet wallet = KeyWallet.load("password", file);

// Stores the keystore on the file path.
File dir = new File("./");
KeyWallet.store(wallet, "password", dir); // throw exception if an error exists.

Creating transactions

// sending icx
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .value(new BigInteger("150000000"))
    .stepLimit(new BigInteger("1000000"))
    .nonce(new BigInteger("1000000"))
    .build();

// deploy
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .stepLimit(new BigInteger("5000000"))
    .nonce(new BigInteger("1000000"))
    .deploy("application/zip", content)
    .params(params)
    .build();

// call
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .value(new BigInteger("150000000"))
    .stepLimit(new BigInteger("1000000"))
    .nonce(new BigInteger("1000000"))
    .call("transfer")
    .params(params)
    .build();

// message
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .value(BigInteger("150000000"))
    .stepLimit(BigInteger("1000000"))
    .nonce(BigInteger("1000000"))
    .message(message)
    .build();

SignedTransaction object signs a transaction using the wallet.

And the request is executed as Synchronized or Asynchronized like a querying request.

Once the request has been executed, the request can not be executed again.

SignedTransaction signedTransaction = new SignedTransaction(transaction, wallet);

Request<Bytes> request = iconService.sendTransaction(signedTransaction);

// Asynchronized request execution
request.execute(new Callback<Bytes>(){
    void onFailure(Exception e) {
        ...
    }

    void onResponse(Bytes txHash) {
        ...
    }
});

// Synchronized request execution
try {
    Bytes txHash = request.execute();
    ...
} catch (Exception e) {
    ...
}

Converter

All the requests and responses values are parcelled as RpcItem(RpcObject, RpcArray, RcpValue). You can convert your own class using RpcConverter.

iconService.addConverterFactory(new RpcConverter.RpcConverterFactory() {
    @Override
    public  RpcConverter create(Class type) {
        if (type.isAssignableFrom(Person.class)) {
            return new RpcConverter<Person>() {
                @Override
                public Person convertTo(RpcItem object) {
                    // Unpacking from RpcItem to the user defined class
                    String name = object.asObject().getItem("name").asString();
                    BigInteger age = object.asObject().getItem("age").asInteger();
                    return new Person(name, age);
                }

                @Override
                public RpcItem convertFrom(Person person) {
                    // Packing from the user defined class to RpcItem
                    return new RpcObject.Builder()
                        .put("name", person.name)
                        .put("age", person.age)
                        .build();
                }
            };
        }
        return null;
    }
});

...

class Person {
    public Person(String name, BigInteger age) {}
}

...

Call<Person> call = new Call.Builder()
                .from(fromAddress)
                .to(scoreAddress)
                .method("searchMember")
                .params(person) // the input parameter is an instance of Person type
                .buildWith(Person.class); // build with the response type 'Person'

Person memberPerson = iconService.call(call).execute();

References

Version

0.9.11 (beta)

Android Support

  • Android 3.0+ (API 11+)

Download

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>foundation.icon</groupId>
  <artifactId>icon-sdk</artifactId>
  <version>[x.y.z]</version>
</dependency>

or Gradle:

implementation 'foundation.icon:icon-sdk:[x.y.z]'

Required at minimum Java 8 (for java7, you can explore source code here)

License

This project follows the Apache 2.0 License. Please refer to LICENSE for details.