Skip to content

Commit

Permalink
FABJ-361 JSDK v1.3.0 release
Browse files Browse the repository at this point in the history 
PS
27 Missing Javadoc on NofEvents.
28 Update dependencies.
30 Have docker-compose pull 3.0
37 Add some information on the integration tests.
38 Update network-config to reference v1.3
39 Readme.md updated.
40 Provide logging for consistency sets when there are more than one.
41 remove fork. update .env

Change-Id: I50697d15eb560865fe59342654f538e24b42164e
Signed-off-by: rickr <cr22rc@gmail.com>
  • Loading branch information
@cr22rc
cr22rc committed Dec 3, 2018
1 parent b775541 commit b9f61bd
Show file tree
Hide file tree
Showing 10 changed files with 251 additions and 90 deletions.
125 changes: 59 additions & 66 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,26 +22,21 @@ SDK's `Enrollment` interface.
only help you familiarize to get started with the SDK if you are new in this domain.


## IMPORTANT: Version 1.3 IS WORK IN PROGRESS!
If you don't require features of Fabric or Fabric CA version 1.3 you probably should consider the v1.2.x version of the SDK.
To get the actual v1.2.0 SDK: [v1.2.0](https://github.com/hyperledger/fabric-sdk-java/tree/33760188370ed4653cca93e727e509e774c5c8c1)
If you are trying to use new features of Fabric you will probably have to build Fabric to get those features.


## Release notes

|Release | Notes |
|--------|:-----:|
|1.2 | [v1.2 release notes](./docs/release_v1.2.0_notes.md)|
|1.1 | [v1.1 release notes](./docs/release_v1.1.0_notes.md)|
|Release | Notes |Summary|
|--------|:------|:------|
|1.3 | [v1.3 release notes](./docs/release_v1.3.0_notes.md)|<ul><li>Java chaincode support</li><li>Query chaincode collection configuration</li><li>Identity Mixer transaction unlinkabilty support</li></ul> |
|1.2 | [v1.2 release notes](./docs/release_v1.2.0_notes.md)|<ul><li>Private data collection support</li><li>Service discovery</li><li>Fabric CA certificate API </ul>|
|1.1 | [v1.1 release notes](./docs/release_v1.1.0_notes.md)|<ul><li>Channel service events</li><li>FilterBlocks</li><li>JCA/JCE compliance</li><li>Chaincode events</li><li>Node chaincode</li></ul>|



## Checkout SDK from Github
```
git clone https://github.com/hyperledger/fabric-sdk-java.git
cd fabric-sdk-java/
git checkout -b release-1.2
git checkout -b release-1.3
```

## Java applications
Expand All @@ -51,7 +46,7 @@ For Java applications use the latest published v1.3.x releases:
<dependency>
<groupId>org.hyperledger.fabric-sdk-java</groupId>
<artifactId>fabric-sdk-java</artifactId>
<version>1.3.0-SNAPHOST/version>
<version>1.3.0/version>
</dependency>
```
Expand All @@ -67,36 +62,6 @@ For Java applications use the latest published v1.3.x releases:

`*************************************************`

## 1.3.0-SNAPSHOT builds
Work in progress 1.3.0 SNAPSHOT builds can be used by adding the following to your application's
pom.xml
```
<repositories>
<repository>
<id>snapshots-repo</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
<dependencies>
<!-- https://mvnrepository.com/artifact/org.hyperledger.fabric-sdk-java/fabric-sdk-java -->
<dependency>
<groupId>org.hyperledger.fabric-sdk-java</groupId>
<artifactId>fabric-sdk-java</artifactId>
<version>1.3.0-SNAPSHOT</version>
</dependency>
</dependencies>
```



## Latest Fabric Builds.
Latest Fabric builds are seldom needed except for those working on the very latest Fabric features.
Expand All @@ -123,6 +88,10 @@ To build this project, the following dependencies must be met
* JDK 1.8 or above
* Apache Maven 3.5.0

To run the integration tests Fabric and Fabric CA is needed which require
* Docker 18.03
* Docker compose 1.21.2

## Using the SDK

### Compiling
Expand All @@ -149,16 +118,28 @@ Use this `maven` command to run the integration tests:
* _mvn clean install -DskipITs=false -Dmaven.test.failure.ignore=false javadoc:javadoc_

### End to end test scenario
The _src/test/java/org/hyperledger/fabric/sdkintegration/End2endIT.java_ integration test is an example of installing, instantiating, invoking and querying a chaincode.
It constructs the Hyperledger channel, deploys the `GO` chaincode, invokes the chaincode to do a transfer amount operation and queries the resulting blockchain world state.

The _src/test/java/org/hyperledger/fabric/sdkintegration/End2endAndBackAgainIT.java_ Shows recreating the channel objects created in End2endIT.java and
upgrading chaincode and invoking the up graded chaincode.

Between End2endIT.java and End2endAndBackAgainIT.java this code shows almost all that the SDK can do.
To learn the SDK you must have some understanding first of the Fabric. Then it's best to study these two integrations tests and better yet work with them in a debugger to follow the code. ( *a live demo* )
Following the below integration tests/example code shows almost all that the SDK can do.
To learn the SDK you must have some understanding first of Fabric Hyperledger. Then it's best to study the integrations tests and better yet work with them in a debugger to follow the code ( *a live demo* ).
Start first with End2endIT.java and then End2endAndBackAgainIT.java samples before exploring the other samples.
Then once you understand them you can cut and paste from there to your own application. ( _the code is done for you!_ )

**Note** These samples are for testing, validating your environment and showing how to use the APIs. Most show a **simple** balance transfer.
**They are not meant to represent best practices in design or use of chaincode or the use of the SDK**.


|Integration Test | Summary and notes|
|--------|:------|
|[End2endIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/End2endIT.java)|<ul><li>Register and enroll users with Fabric certificate authority.</li><li>Constructing channel first time.</li><li>Installing chaincode.</li><li>Instantiating chaincode.</li><li>Executing chaincode.</li><li>Querying channel for block information.</li><li>Chaincode event listener</li><li>Traversing block for information.</li><li>Prerequisite for all other testcases.</li></ul> |
|[End2endAndBackAgainIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/End2endAndBackAgainIT.java)| <ul><li>Recreate channel.</li><li>Update chaincode.</li><li>Checking installed and instantiated chaincode.</li></ul> |
|[End2endNodeIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/End2endNodeIT.java)| <ul><li>Shows running End2endIT.java but with Node chaincode.</li><li>Note subclasses En2endIT class.</li></ul> |
|[End2endJavaIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/End2endJavaIT.java)| <ul><li>Shows running End2endIT.java but with Java chaincode.</li><li>Note subclasses En2endIT class.</li></ul> |
|[End2endIdemixIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/End2endIdemixIT.java)| <ul><li>Shows running End2endIT.java but with Idemix credentials.</li><li>Note subclasses En2endIT class.</li></ul> |
|[NetworkConfigIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/NetworkConfigIT.java)| <ul><li>Shows recreating channel with [common connection profile](https://jira.hyperledger.org/browse/FABN-808).</li></ul> |
|[PrivateDataIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/PrivateDataIT.java)| <ul><li>Shows instantiating and installing chaincode that defines private data.</li><li>Information on Fabric private data can be found [read the docs.](https://hyperledger-fabric.readthedocs.io/en/release-1.2/private-data/private-data.html)</li></ul> |
|[UpdateChannelIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/UpdateChannelIT.java)| <ul><li>Shows updating channel configuration.</li><li>Details on channel configurations can be found on read the docs [Channel Configuration](https://hyperledger-fabric.readthedocs.io/en/release-1.2/configtx.html#)</li></ul> |
|[ServiceDiscoveryIT.java](https://github.com/hyperledger/fabric-sdk-java/blob/8044bac1bfe9baf9d6360b067e0d6b5445cc953d/src/test/java/org/hyperledger/fabric/sdkintegration/ServiceDiscoveryIT.java)| <ul><li>Shows service discovery.</li><li>Details on service discovery can be found on read the docs [Service Discovery](https://hyperledger-fabric.readthedocs.io/en/release-1.3/discovery-overview.html)</li><li>Note: requires adding entries in host file to remap docker fabric Peer and Orderers address to localhost</li></ul> |

### End to end test environment
The test defines one Fabric orderer and two organizations (peerOrg1, peerOrg2), each of which has 2 peers, one fabric-ca service.

Expand Down Expand Up @@ -253,9 +234,9 @@ For v1.2 integration the commands use the v12 profiles in configtx.yaml.

For v1.3 integration, cd to the `src/test/fixture/sdkintegration/e2e-2Orgs/v1.3` directory
and execute the following commands:
* configtxgen -outputBlock orderer.block -profile TwoOrgsOrdererGenesis_v13
* configtxgen -outputCreateChannelTx foo.tx -profile TwoOrgsChannel_v13 -channelID foo
* configtxgen -outputCreateChannelTx bar.tx -profile TwoOrgsChannel_v13 -channelID bar
* configtxgen --configPath . -outputBlock orderer.block -profile TwoOrgsOrdererGenesis_v13
* configtxgen --configPath . -outputCreateChannelTx foo.tx -profile TwoOrgsChannel_v13 -channelID foo
* configtxgen --configPath . -outputCreateChannelTx bar.tx -profile TwoOrgsChannel_v13 -channelID bar

This should produce the following files in the same directory: orderer.block, foo.tx, and bar.tx

Expand All @@ -269,29 +250,38 @@ Go lang chaincode dependencies must be contained in vendor folder.
For an explanation of this see [Vendor folder explanation](https://blog.gopheracademy.com/advent-2015/vendor-folder/)


## Basic Troubleshooting
## Basic Troubleshooting and frequently asked questions:

**Firewalls, load balancers, network proxies**
### Where can I find the Javadoc?

These can sometimes silently kill a network connections and prevent them from auto reconnecting. To fix this look at
adding to Peers, EventHub's and Orderer's connection properties:
`grpc.NettyChannelBuilderOption.keepAliveTime`, `grpc.NettyChannelBuilderOption.keepAliveTimeout`,
`grpc.NettyChannelBuilderOption.keepAliveWithoutCalls`. Examples of this are in End2endIT.java
Look in the [Maven repository](http://central.maven.org/maven2/org/hyperledger/fabric-sdk-java/fabric-sdk-java/)
for the release in question there should be a file fabric-sdk-java-_&lt;release&gt;_-javadoc.jar

For SNAPSHOT builds look in [Sonatype repository](https://oss.sonatype.org/content/repositories/snapshots/org/hyperledger/fabric-sdk-java/fabric-sdk-java/)
Find the release _&lt;release&gt;_-SNAPSHOT directory then search for the latest fabric-sdk-java-&lt;_release_&gt;&#45;_&lt;latest timestamp&gt;_-javadoc.jar

**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 FSUser 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.
### Is Android supported?
No.

``Error: identity or token do not match``
### Is there an API to query for all channels that exist?
No.

``Error: FSUser is already registered``
### Firewalls, load balancers, network proxies

To address this, remove any stored crypto material from the CA server by following the instructions <a href="https://github.com/hyperledger/fabric/blob/master/docs/Setup/Chaincode-setup.md#removing-temporary-files-when-security-is-enabled">here</a> 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 ${FSUser.home}/test.properties within the unit tests.
These can sometimes silently kill a network connections and prevent them from auto reconnecting. To fix this look at
adding to Peers, EventHub's and Orderer's connection properties:
`grpc.NettyChannelBuilderOption.keepAliveTime`, `grpc.NettyChannelBuilderOption.keepAliveTimeout`,
`grpc.NettyChannelBuilderOption.keepAliveWithoutCalls`. Examples of this are in End2endIT.java

### grpc message frame size exceeds maximum

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.
The message being returned from the fabric server is too large for the default grpc frame size.
On the Peer, Orderer, orEventHub add the property `grpc.NettyChannelBuilderOption.maxInboundMessageSize`
See [End2endIT's constructChannel](https://github.com/hyperledger/fabric-sdk-java/blob/b649868113e969d851720c972f660114b64247bc/src/test/java/org/hyperledger/fabric/sdkintegration/End2endIT.java#L846)

**java.security.InvalidKeyException: Illegal key size**

### 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 <a href="http://stackoverflow.com/questions/6481627/java-security-illegal-key-size-or-default-parameters">here</a> to download and install the JCE for your version of the JDK.

Expand Down Expand Up @@ -323,12 +313,15 @@ Pleases provide as much information that you can with the issue you're experienc

Please provide the output of **java -XshowSettings:properties -version**

Logging for the SDK can be enabled with setting environment variables:
### Logging for the SDK can be enabled with setting environment variables:

ORG_HYPERLEDGER_FABRIC_SDK_LOGLEVEL=TRACE

ORG_HYPERLEDGER_FABRIC_CA_SDK_LOGLEVEL=TRACE

ORG_HYPERLEDGER_FABRIC_SDK_DIAGNOSTICFILEDIR=&lt;*full path to directory*&gt; &#35; *dumps protobuf and diagnostic data. Can be produce large amounts of data!*

### Fabric debug
Fabric debug is by default enabled in the SDK docker-compose.yaml file with

On Orderer:
Expand Down
47 changes: 47 additions & 0 deletions docs/release_v1.3.0_notes.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Java SDK for Hyperledger Fabric 1.3 release notes.

The JSDK 1.3 has features added since the 1.2 based release to match those added to the Fabric 1.3 release.

## Fabric v1.0 and v1.1 considerations
The SDK is mostly backward compatible with the v1.x based Fabric with the following considerations
- The new Peer eventing service is the default for the SDK however, in v1.0 Fabric peer eventing service is not supported. To address in applications that are
connecting to Fabric 1.0 you must when adding or joining a peer to a channel provide a PeerRole option.
A role with `PeerRole.NO_EVENT_SOURCE` has been defined that has the equivalent functionality of a v1.0 peer.
You can see an example of this
in [End2endIT.java#L732](https://github.com/hyperledger/fabric-sdk-java/blob/9224fa3f45a70392d1b244c080bf41bd561470d3/src/test/java/org/hyperledger/fabric/sdkintegration/End2endIT.java#L732)
and in [End2endAndBackAgainIT.java#L597](https://github.com/hyperledger/fabric-sdk-java/blob/9224fa3f45a70392d1b244c080bf41bd561470d3/src/test/java/org/hyperledger/fabric/sdkintegration/End2endAndBackAgainIT.java#L597)


## v1.3 Fabric features


### [FABJ-355 Run Java chaincode](https://jira.hyperledger.org/browse/FABJ-355)
Fabric v1.3 now officially supporting Java chaincode an example of Java chaincode, deployment, and invocation was added to the Java SDK.
The only difference between Java and the other supported languages is when installing it is setChaincodeLanguage is `Type.JAVA` and
chaincode is of course is written in Java. The similarity, is shown by the sample JSDK to do the deployment and invocation of the Java
chaincode is just subclassed from the GO example. [End2endJavaIT SDK Java deployment ](https://github.com/hyperledger/fabric-sdk-java/blob/ef604d1fd3bc12eeed9910036f24e4a4953156c4/src/test/java/org/hyperledger/fabric/sdkintegration/End2endJavaIT.java)
The deployed Java chaincode is [Java chaincode example](https://github.com/hyperledger/fabric-sdk-java/tree/ef604d1fd3bc12eeed9910036f24e4a4953156c4/src/test/fixture/sdkintegration/javacc/sample1)

### [FABJ-375 Query for a chaincode's collection configuration](https://jira.hyperledger.org/browse/FABJ-357)
An API `queryCollectionsConfig` added to the channel to retrieve what chaincode collections a specific chaincode uses was added. An example of invoking this API was added
to [PrivateDataIT test.](https://github.com/hyperledger/fabric-sdk-java/blob/ef604d1fd3bc12eeed9910036f24e4a4953156c4/src/test/java/org/hyperledger/fabric/sdkintegration/PrivateDataIT.java#L187-L193)

### [FABJ-340 Adding IdemixUser for unlinkability](https://jira.hyperledger.org/browse/FABJ-340)
The ability to sign proposals and transactions in an unlinkable way has been added to the Java SDK. From the application perspective
there is a minimal change in API usage to achieve unlinkability. The application user as normal needs to first have a x509 certificate enrollment.
The Identity Mixer (Idemix, for short) enrollment will be derived from the x509 enrollment. Next is to have a user context that has both the MSPID that is defined for Idemix and an Idemix enrollment that's created with FabricCA `idemixEnroll` instead of
the FabricCA's `enroll` method that created the x509 enrollment. Example of this can be seen in the [End2endIdemixIt test](https://github.com/hyperledger/fabric-sdk-java/blob/ef604d1fd3bc12eeed9910036f24e4a4953156c4/src/test/java/org/hyperledger/fabric/sdkintegration/End2endIdemixIT.java#L121-L138).

When unlinkability is desired, the user context should be changed from the x509 user to the Idemix user.
An Idemix user context, however, should be limited to creating proposals to invoke chaincode.
Every proposal signed with Idemix will look like it is coming from a different user.
Only the Role and Organization Unit attributes will be disclosed in a serialized Identity and the rest will be hidden.
For further information on unlinkability and Idemix see [Identity Mixer Documentation for v1.3](https://hyperledger-fabric.readthedocs.io/en/release-1.3/idemix.html).

## v1.3 Fabric/CA features

### [FAB-10351 Idemix CA support for Java SDK](https://jira.hyperledger.org/browse/FABJ-331)

Idemix enrollment API `idemixEnroll` is used to obtain credentials needed for unlinkability.
An example of its usage can be seen in
[End2endIdemixIt test.](https://github.com/hyperledger/fabric-sdk-java/blob/ef604d1fd3bc12eeed9910036f24e4a4953156c4/src/test/java/org/hyperledger/fabric/sdkintegration/End2endIdemixIT.java#L137)
4 changes: 2 additions & 2 deletions pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<groupId>org.hyperledger.fabric-sdk-java</groupId>
<artifactId>fabric-sdk-java</artifactId>
<packaging>jar</packaging>
<version>1.3.0-SNAPSHOT</version>
<version>1.3.0</version>
<name>fabric-java-sdk</name>
<description>Java SDK for Hyperledger fabric project</description>
<url>https://www.hyperledger.org/community/projects</url>
Expand Down Expand Up @@ -93,7 +93,7 @@
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-tcnative-boringssl-static</artifactId>
<version>2.0.15.Final</version>
<version>2.0.17.Final</version>
</dependency>
<dependency>
<groupId>io.netty</groupId>
Expand Down
Loading

0 comments on commit b9f61bd

Please sign in to comment.