Java API for Nevermined Data platform

Java SDK for connecting with Nevermined Data Platform nevermined.io

---

Table of Contents

• Java API for Nevermined Data platform
  • Table of Contents
  • Features
  • Installation
  • Configuration
    • Using the SDK with the Nevermined Tools
    • Dealing with Flowables
  • Documentation
  • Testing
    • Unit Tests
    • Integration Tests
    • Documentation
    • All the tests
    • Code Coverage
  • New Release
  • Attribution
  • License

---

Features

This library enables to integrate the Nevermined Data Platform based in Ocean Protocol.

Installation

Typically in Maven you can add nevermined sdk as a dependency:

<dependency>
  <groupId>io.keyko.nevermined</groupId>
  <artifactId>api</artifactId>
  <version>0.3.2</version>
</dependency>

Nevermined SDK requires Java 11 and Maven >= 3.5.2

Configuration

You can configure the library using TypeSafe Config or a Java Properties Object

In case you want to use TypeSafe Config you would need an application.conf file with this shape:

keeper.url="http://localhost:8545"
keeper.gasLimit=4712388
keeper.gasPrice=100000000000
keeper.tx.attempts=50
keeper.tx.sleepDuration=2000


metadata.url="http://localhost:5000"
# Used in the internal communications between Docker containers (Spree network)
metadata-internal.url="http://172.15.0.15:5000" # Running Nevermined tools
# metadata-internal.url="http://localhost:5000" # Running local metadata
gateway.url="http://localhost:8030"
secretstore.url="http://localhost:12001"
faucet.url="http://localhost:3001"

provider.address="0x068ed00cf0441e4829d9784fcbe7b9e26d4bd8d0"

# Contracts addresses

contract.SignCondition.address="0x8F006DbB3727d18f032C5618595ecDD2EDE13b61"
contract.HashLockCondition.address="0x19513460bc16254c74AE806683E906478A42B543"
contract.LockPaymentCondition.address="0x4999A8428d1D42fc955FbBC2f1E22323a55B6f86"
contract.AccessCondition.address="0x3Ef2ebF03002D828943EB1AbbFC470D1A53c6B21"
contract.EscrowPaymentCondition.address="0xE6E685823Ddd2e0D0B29917D84D687E5431136F6"
contract.AccessTemplate.address="0x3c83D8E1F1BF33Ebb1E8D5A2ac56cE482e54caCd"
contract.NeverminedToken.address="0xEEE56e2a630DD29F9A628d618E58bb173911F393"
contract.Dispenser.address="0x85cCa2B01adddCA8Df221e6027EE0D7716224202"
contract.DIDRegistry.address="0xfeA10BBb093d7fcb1EDf575Aa7e28d37b9DcFcE9"
contract.ConditionStoreManager.address="0x645439117eB378a6d35148452E287a038666Ed67"
contract.TemplateStoreManager.address="0x3a3926f3f88F1eE05164404f93FDb3887cbE8e35"
contract.AgreementStoreManager.address="0x15338ade17C4b6F65E4ff7b3aCE22AAdED00aC4d"
contract.ComputeExecutionCondition.address="0x884AAAAf48D4A7B4Dc4CB9B2cf47a150b3d535A6"
contract.EscrowComputeExecutionTemplate.address="0x02175de5A7F168517688e3E93f55936C9c2C7A19"

consume.basePath = "/tmp"

## Main account
account.main.address="0x0207cb2f99eb2e005893d6108e2633641ca9dd3e"
account.main.password="pass"
account.main.credentialsFile="/accounts/parity/0x0207cb2f99eb2e005893d6108e2633641ca9dd3e.json.testaccount"

And you can instantiate the API with the following lines:

 Config config = ConfigFactory.load();
 NeverminedAPI neverminedAPI = NeverminedAPI.getInstance(config);

Remember that TypeSafe Config allows you to overwrite the values using environment variables or arguments passed to the JVM.

If you want to use Java's Properties, you just need to create a Properties object with the same properties of the application.conf. You can read these Properties from a properties file, or define the values of these properties in your code:

// Default values for KEEPER_URL, KEEPER_GAS_LIMIT, KEEPER_GAS_PRICE, Nevermined_URL, SECRETSTORE_URL, CONSUME_BASE_PATH
Properties properties = new Properties();
properties.put(NeverminedConfig.MAIN_ACCOUNT_ADDRESS, "0x0207cb2f99eb2e005893d6108e2633641ca9dd3e");
properties.put(NeverminedConfig.MAIN_ACCOUNT_PASSWORD,"pass");
properties.put(NeverminedConfig.MAIN_ACCOUNT_CREDENTIALS_FILE,"/accounts/parity/0x0207cb2f99eb2e005893d6108e2633641ca9dd3e.json.testaccount");
properties.put(NeverminedConfig.DID_REGISTRY_ADDRESS,"0x4A0f7F763B1A7937aED21D63b2A78adc89c5Db23");
properties.put(NeverminedConfig.AGREEMENT_STORE_MANAGER_ADDRESS, "0x62f84700b1A0ea6Bfb505aDC3c0286B7944D247C");
properties.put(NeverminedConfig.LOCKREWARD_CONDITIONS_ADDRESS, "0xE30FC30c678437e0e8F78C52dE9db8E2752781a0");
properties.put(NeverminedConfig.ESCROWREWARD_CONDITIONS_ADDRESS, "0xeD4Ef53376C6f103d2d7029D7E702e082767C6ff");
properties.put(NeverminedConfig.ACCESS_SS_CONDITIONS_ADDRESS, "0x45DE141F8Efc355F1451a102FB6225F1EDd2921d");
properties.put(NeverminedConfig.TEMPLATE_STORE_MANAGER_ADDRESS, "0x9768c8ae44f1dc81cAA98F48792aA5730cAd2F73");
properties.put(NeverminedConfig.TOKEN_ADDRESS, "0x9861Da395d7da984D5E8C712c2EDE44b41F777Ad");
properties.put(NeverminedConfig.DISPENSER_ADDRESS, "0x865396b7ddc58C693db7FCAD1168E3BD95Fe3368");
properties.put(NeverminedConfig.PROVIDER_ADDRESS, "0x413c9ba0a05b8a600899b41b0c62dd661e689354");

NeverminedAPI NeverminedAPIFromProperties = NeverminedAPI.getInstance(properties);

Once you have initialized the API you can call the methods through their corresponding API class. For instance:

 Balance balance = neverminedAPI.getAccountsAPI().balance(neverminedAPI.getMainAccount());

 String filesJson = metadataBase.toJson(metadataBase.base.files);
 String did = DID.builder().getHash();
 String encryptedDocument = neverminedAPI.getSecretStoreAPI().encrypt(did, filesJson, 0);

 Flowable<OrderResult> response = neverminedAPI.getAssetsAPI().order(did, SERVICE_DEFINITION_ID);
 boolean result = neverminedAPI.getAssetsAPI().consume(orderResult.getServiceAgreementId(), did, SERVICE_DEFINITION_ID, "/tmp");

Using the SDK with the Nevermined Tools

If you are using Nevermined Tools for playing with the Nevermined stack, you can use the following command to run the components necessary to have a fully functional environment:

bash start_nevermined.sh --no-commons --local-spree-node

After a few minutes, when Keeper has deployed the contracts, the ABI files describing the Smart Contracts can be found in the ${HOME}/.nevermined/nevermined-contracts/artifacts/ folder. Depending on the network you are using, each ABI includes the address where the Smart Contract is deployed in each network.

If you want to run the integration tests on your local machine, you can execute the Bash script src/test/resources/scripts/updateConfAddresses.sh to update the addresses to use in your src/test/resources/application.conf file.

Dealing with Flowables

The library uses web3j to interact with Solidity's Smart Contracts. It relies on RxJava to deal with asynchronous calls.

The order method in AssetsAPI returns a Flowable over an OrderResult object. It's your choice if you want to handle this in a synchronous or asynchronous fashion.

If you prefer to deal with this method in a synchronous way, you will need to block the current thread until you get a response:

 Flowable<OrderResult> response = neverminedAPI.getAssetsAPI().order(did, SERVICE_DEFINITION_ID);
 OrderResult orderResult = response.blockingFirst();

On the contrary, if you want to handle the response asynchronously, you will need to subscribe to the Flowable:

response.subscribe(
     orderResultEvent -> {
         if (orderResultEvent.isAccessGranted())
             System.out.println("Access Granted for Service Agreement " + orderResultEvent.getServiceAgreementId());
         else if (orderResultEvent.isRefund())
             System.out.println("There was a problem with Service Agreement " + orderResultEvent.getServiceAgreementId() + " .Payment Refund");
     }
 );

The subscribe method will launch a new Thread to react to the events of the Flowable. More information: RxJava , Flowable

Documentation

All the API documentation is hosted on javadoc.io:

• https://www.javadoc.io/doc/io.keyko.nevermined/api

You can also generate the Javadoc locally using the following command:

mvn javadoc:javadoc

Testing

You can run both, the unit and integration tests by using:

mvn clean verify -P all-tests

Unit Tests

You can execute the unit tests only using the following command:

mvn clean test

Integration Tests

The execution of the integration tests require to have running the complete Nevermined stack using Nevermined Tools.

After having the tools in your environment, you can run the components needed running:

KEEPER_VERSION=v0.13.2 bash start_nevermined.sh --latest --no-commons --force-pull

If you have older versions of the docker images is recommended to delete all them to be sure you are running the last version of the stack.

You can execute the integration tests using the following command:

mvn clean verify -P integration-test

Documentation

You can generate the Javadoc using the following command:

mvn javadoc:javadoc

All the tests

You can run the unit and integration tests running:

mvn clean verify -P all-tests

You can run the integration tests in Nile environment using the command:

mvn verify  -P integration-test -Dconfig.file=src/test/resources/networks/integration-application.conf

Code Coverage

The code coverage reports are generated using the JaCoCo Maven plugin. Reports are generated in the target/site folder.

New Release

The bumpversion.sh script helps to bump the project version. You can execute the script using as first argument {major|minor|patch} to bump accordingly the version.

Attribution

This library is based in the Ocean Protocol Squid Java library. It keeps the same Apache v2 License and adds some improvements. See NOTICE file.

License

Copyright 2020 Keyko GmbH
This product includes software developed at
BigchainDB GmbH and Ocean Protocol (https://www.oceanprotocol.com/)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.