Java SDK for Hyperledger Fabric 1.0

Welcome to Java SDK for Hyperledger project. This is a summary of steps required to get you started with building and using the Java SDK. Please note that this is not the API documentation or a tutorial for the SDK, this will only help you familiarize to get started with the SDK if you are new in this domain.

The 1.0 sdk is currently under development and the api is still subject to change. It is likely any code depending on this 1.0 version preview many need updating with subsequent updates of this sdk.

Compiling

To build this project, following dependencies must be met

JDK 1.8 or above
Apache Maven

Once your JAVA_HOME points to your installation of JDK 1.8 (or above) and JAVA_HOME/bin and Apache maven are in your PATH, issue the following command to build the jar file: mvn install or mvn install -DskipTests if you don't want to run the unit tests

Running the unit tests

To run the unit tests, please use mvn test or mvn install which will run the unit tests and build the jar file. You must be running a local a peer and orderer to be able to run the unit tests.

Running the End to End tests

To run the End-to-End tests, please use mvn failsafe:integration-test -DskipITs=false which will run the End2end tests. You must be running a local instance of membersrvcs and a peer to be able to run the End-to-End tests.

Hyperledger Fabric v1.0 is currently under active development and the very latest Hyperledger Fabric builds may not work with this sdk. You should use the following commit levels of the Hyperledger projects:

Project	Commit level	Date
fabric	e3fe66ba19c3d77d88431d74d5647d0372496313	Feb 21 16:50:46 2017 +0000
fabric-ca	c4e83c10292d53fa0f1a1688899a594fe4ece26b	Jan 27 2017

50372c16c76fb2bfbafb2f8ffaf085f085b75b1c

You can clone these projects by going to the Hyperledger repository.

As sdk developement continues, this file will be updated with compatible Hyperledger Fabric commit levels.

Once you have cloned fabric and fabric-ca, use the git reset --hard commitlevel to set your repositories to the correct commit.

To make the ports available to the sdk from vagrant, edit the devenv/Vagrantfile file

Open the file Vagrantfile and verify that the following config.vm.network statements are set:

  config.vm.network :forwarded_port, guest: 7050, host: 7050 # orderer service
  config.vm.network :forwarded_port, guest: 7051, host: 7051 # Openchain gRPC services
  config.vm.network :forwarded_port, guest: 7054, host: 7054 # Membership service/Fabric CA
  config.vm.network :forwarded_port, guest: 7053, host: 7053 # GRPCCient gRPC services
  config.vm.network :forwarded_port, guest: 5984, host: 15984 # CouchDB service

Follow the instructions here to setup the development environment.

ssh into vagrant,

go to $GOPATH/src/github.com/hyperledger/fabric
- run make docker to create the docker images for peer and orderer
go to 4GOPATH/src/github/hyperledger/fabric-cop
- currently, you want to run fabric-ca with TLS disabled which is the default for commit aa5fb82 mentioned above.
- if you do need to turn off TLS, edit the COP server configuration file at /hyperledger/fabric-ca/images/fabric-ca/config/server-config.json
- run make docker to create the docker image for COP

On your native system where you have the sdk installed you need to copy the docker compose file that starts the services to the directory mapped to vagrant On your native system from the sdk directory: cp ./test/fixture/src/docker-compose.yml <directory where fabric was installed >

The fabric service creation may have created some files for testing that need to be removed. In the vagrant system:

rm -rf /var/hyperledger/*

Now start the needed fabric services in vagrant. In the vagrant system:

cd /hyperledger
docker-compose up

Once done setting up the fabric The end2end unit test will deploy GO code to the fabric that init's, modifies and queries the fabric's ledger. The sdk finds this code by setting the GOPATH environment variable. For this test set this to: GOPATH=<fullpath to your sdk directory>/src/test/fixture

With the Fabric services up and running you can run the End2end integration test. To do this with maven run this command:

mvn failsafe:integration-test -DskipITs=false

This runs the src/test/java/org/hyperledger/fabric/sdk/End2endIT.java code. It constructs the Hyperledger Chain, deploys the GO chain code and initializes the ledger with to variables A= "100", B= "200" It then invokes the chain code function move that transfers 100 from A to B on the ledger. Then queries the ledger to see if B is now 300.

SDK dependencies

SDK depends on few third party libraries that must be included in your classpath when using the JAR file. To get a list of dependencies, refer to pom.xml file or run mvn dependency:tree or mvn dependency:list.

Alternatively, mvn dependency:analyze-report will produce a report in HTML format in target directory listing all the dependencies in a more readable format.

Using the SDK

See the fabric-sdk-java/src/test/java/org/hyperledger/fabric/sdk/End2endIT.java for an example of installing, initialising, invoking chain code. The sdk jar is in. target/fabric-sdk-java-1.0-SNAPSHOT.jar and you will need the additional dependencies listed above. When the SDK is published to Maven you'll will be able to simply include it in a your application's pom.xml.

#Basic Troubleshooting identity or token do not match

Keep in mind that you can perform the enrollment process with the membership services server only once, as the enrollmentSecret is a one-time-use password. If you have performed a user registration/enrollment with the membership services and subsequently deleted the crypto tokens stored on the client side, the next time you try to enroll, errors similar to the ones below will be seen.

Error: identity or token do not match

Error: user is already registered

To address this, remove any stored crypto material from the CA server by following the instructions here which typically involves deleting the /var/hyperledger/production directory and restarting the membership services. You will also need to remove any of the crypto tokens stored on the client side by deleting the KeyValStore . That KeyValStore is configurable and is set to ${user.home}/test.properties within the unit tests.

When running the unit tests, you will always need to clean the membership services database, and delete the KeyValStore file, otherwise the unit tests will fail.

java.security.InvalidKeyException: Illegal key size

If you get this error, this means your JDK does not capable of handling unlimited strength crypto algorithms. To fix this issue, You will need to download the JCE libraries for your version of JDK. Please follow the instructions here to download and install the JCE for your version of the JDK.

#Reporting Issues To report issue please use: Hyperledger's JIRA. To login you will need a Linux Foundation ID (LFID) which you get at The Linux Foundation if you don't already have one.

JIRA Fields should be:

Type: Bug or New Feature
Component: fabric-sdk-java
Fix Versions: v1.0.0

Pleases provide as much information that you can with the issue you're experiencing: stack traces logs.

#Communicating with developers and fellow users. Sign into Hyperledger project's Rocket chat For this you will also need a Linux Foundation ID