From 6634e1a7e83ed2f3317456a652df1d653555d75c Mon Sep 17 00:00:00 2001 From: andrew-coleman Date: Fri, 28 Sep 2018 09:38:38 +0100 Subject: [PATCH] FABN-944 JSDoc for fabric-network classes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add outline jsdoc comments for the fabric-network API Add fabric-network to the ‘gulp doc’ task Change-Id: I364d642bde89d1a2739861b753588bf89691e627 Signed-off-by: andrew-coleman --- build/tasks/doc.js | 2 + fabric-network/README.md | 14 ++++++ fabric-network/index.js | 5 +++ fabric-network/lib/api/queryhandler.js | 5 +++ fabric-network/lib/api/wallet.js | 32 +++++++++++++- fabric-network/lib/contract.js | 22 +++++++--- fabric-network/lib/gateway.js | 44 ++++++++++++++----- .../impl/event/defaulteventhandlermanager.js | 2 +- .../event/defaulteventhandlerstrategies.js | 26 +++++++++++ fabric-network/lib/impl/wallet/basewallet.js | 7 ++- .../lib/impl/wallet/filesystemwallet.js | 3 +- .../lib/impl/wallet/inmemorywallet.js | 4 ++ .../lib/impl/wallet/x509walletmixin.js | 3 ++ fabric-network/lib/network.js | 16 ++++--- 14 files changed, 158 insertions(+), 27 deletions(-) diff --git a/build/tasks/doc.js b/build/tasks/doc.js index 5810d7e6e7..9af8c64f79 100644 --- a/build/tasks/doc.js +++ b/build/tasks/doc.js @@ -25,6 +25,8 @@ gulp.task('clean', function(){ gulp.task('doc', ['clean'], function () { gulp.src([ 'docs/index.md', + 'fabric-network/index.js', + 'fabric-network/lib/**/*.js', 'fabric-client/index.js', 'fabric-client/lib/**/*.js', '!fabric-client/lib/protos/**', diff --git a/fabric-network/README.md b/fabric-network/README.md index e69de29bb2..16fde01f6e 100644 --- a/fabric-network/README.md +++ b/fabric-network/README.md @@ -0,0 +1,14 @@ +## Hyperledger Fabric Client for Node.js + +SDK for writing node.js applications to interact with [Hyperledger Fabric](http://hyperledger-fabric.readthedocs.io/en/latest/). + +This package encapsulates the APIs to connect to a Fabric network, submit transactions and perform queries against the ledger. + +Two separate packages are also provided: +1. `fabric-client`, supporting fine grain interactions with Peers and Orders of the Fabric network to install and instantiate chaincodes, send transaction invocations and perform chaincode queries. +2. `fabric-ca-client`, to interact with the fabric-ca to manage user certificates. + +For application developer documentations, please visit [https://fabric-sdk-node.github.io/](https://fabric-sdk-node.github.io/) + +Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License. + diff --git a/fabric-network/index.js b/fabric-network/index.js index 2c6633947a..6f3332b0aa 100644 --- a/fabric-network/index.js +++ b/fabric-network/index.js @@ -4,7 +4,12 @@ * SPDX-License-Identifier: Apache-2.0 */ +/** + * @module fabric-network + */ + module.exports.Gateway = require('./lib/gateway'); +module.exports.Wallet = require('./lib/api/wallet'); module.exports.InMemoryWallet = require('./lib/impl/wallet/inmemorywallet'); module.exports.X509WalletMixin = require('./lib/impl/wallet/x509walletmixin'); module.exports.FileSystemWallet = require('./lib/impl/wallet/filesystemwallet'); diff --git a/fabric-network/lib/api/queryhandler.js b/fabric-network/lib/api/queryhandler.js index 431417a03d..afa7eb6832 100644 --- a/fabric-network/lib/api/queryhandler.js +++ b/fabric-network/lib/api/queryhandler.js @@ -6,6 +6,11 @@ 'use strict'; +/** + * QueryHandler defines the interface for pluggable query handlers. + * + * @interface + */ class QueryHandler { constructor(channel, mspId, peerMap, queryOptions) { diff --git a/fabric-network/lib/api/wallet.js b/fabric-network/lib/api/wallet.js index b967f0b0dd..8309715076 100644 --- a/fabric-network/lib/api/wallet.js +++ b/fabric-network/lib/api/wallet.js @@ -8,7 +8,12 @@ 'use strict'; -/* eslint-disable no-unused-vars */ +/** + * Wallet defines the interface for storing and managing users' identities in a fabric network. + * This is an abstract base class and must be extended. + * + * @interface + */ class Wallet { // =============================================== @@ -27,22 +32,47 @@ class Wallet { // End user APIs //========================================================= + /** + * Import an identity into the wallet + * @param label + * @param identity + * @returns {Promise} + */ async import(label, identity) { throw new Error('Not implemented'); } + /** + * Extract an identity from the wallet + * @param label + * @returns {Promise} + */ async export(label) { throw new Error('Not implemented'); } + /** + * List the contents of the wallet + * @returns {Promise} + */ async list() { throw new Error('Not implemented'); } + /** + * Removes an identity from the wallet + * @param label + * @returns {Promise} + */ async delete(label) { throw new Error('Not implemented'); } + /** + * Query the existence of an identity in the wallet + * @param label + * @returns {Promise} + */ async exists(label) { throw new Error('Not implemented'); } diff --git a/fabric-network/lib/contract.js b/fabric-network/lib/contract.js index 2ba5d40b85..fb80583c03 100644 --- a/fabric-network/lib/contract.js +++ b/fabric-network/lib/contract.js @@ -9,6 +9,11 @@ const logger = require('./logger').getLogger('Contract'); const util = require('util'); +/** + * Represents a smart contract (chaincode) instance in a network. + * Applications should get a Contract instance using the + * networks's [getContract]{@link Network#getContract} method. + */ class Contract { constructor(channel, chaincodeId, gateway, queryHandler, eventHandlerFactory) { @@ -72,10 +77,12 @@ class Contract { } /** - * Submit a transaction to the contract. + * Submit a transaction to the ledger. The transaction function transactionName + * will be executed on the endorsing peers and then submitted to the ordering service + * for committing to the ledger. * @param {string} transactionName Transaction function name * @param {...string} parameters Transaction function parameters - * @returns {Buffer} Payload response + * @returns {Buffer} Payload response from the transaction function */ async submitTransaction(transactionName, ...parameters) { logger.debug('in submitTransaction: ' + transactionName); @@ -175,9 +182,14 @@ class Contract { } /** - * @param {string} transactionName transaction name - * @param {string[]} parameters transaction parameters - * @returns {byte[]} payload response + * Execute a transaction function and return its results. + * The transaction function transactionName + * will be executed on the endorsing peers but the responses will not be sent to to + * the ordering service and hence will not be committed to the ledger. + * This is used for querying the world state. + * @param {string} transactionName Transaction function name + * @param {...string} parameters Transaction function parameters + * @returns {Buffer} Payload response from the transaction function */ async executeTransaction(transactionName, ...parameters) { this._verifyTransactionDetails('executeTransaction', transactionName, parameters); diff --git a/fabric-network/lib/gateway.js b/fabric-network/lib/gateway.js index ffec821e89..44ca1dc323 100644 --- a/fabric-network/lib/gateway.js +++ b/fabric-network/lib/gateway.js @@ -13,6 +13,17 @@ const EventStrategies = require('fabric-network/lib/impl/event/defaulteventhandl const logger = require('./logger').getLogger('Gateway'); +/** + * The gateway peer provides the connection point for an application to access the Fabric network. It is instantiated using + * the default constructor. + * It can then be connected to a fabric network using the [connect]{@link Gateway#connect} method by passing either a CCP definition + * or an existing {@link Client} object. + * Once connected, it can then access individual Network instances (channels) using the [getNetwork]{@link Gateway#getNetwork} method + * which in turn can access the [smart contracts]{@link Contract} installed on a network and + * [submit transactions]{@link Contract#submitTransaction} to the ledger. + * + * @class + */ class Gateway { static _mergeOptions(defaultOptions, suppliedOptions) { @@ -60,20 +71,29 @@ class Gateway { */ /** - * @typedef {Object} DefaultEventHanderOptions + * @typedef {Object} DefaultEventHandlerOptions * @property {number} [commitTimeout = 300] The timeout period in seconds to wait for commit notification to complete - * @property {*} [strategy] Event handling strategy to identify successful transaction commits. A null value - * indicates that no event handling is desired. + * @property {MSPID_SCOPE_ALLFORTX|MSPID_SCOPE_ANYFORTX|NETWORK_SCOPE_ALLFORTX|NETWORK_SCOPE_ANYFORTX} [strategy] Event + * handling strategy to identify successful transaction commits. A null value + * indicates that no event handling is desired. The default is {@link MSPID_SCOPE_ALLFORTX}. */ /** * Connect to the Gateway with a connection profile or a prebuilt Client instance. * - * @param {Client | string} config The configuration for this Gateway which can come from a common connection + * @param {string|Client} config The configuration for this Gateway which can come from a common connection * profile or an existing fabric-client Client instance - * @see see {Client} * @param {GatewayOptions} options specific options for creating this Gateway instance * @memberof Gateway + * @example + * const gateway = new Gateway(); + * const wallet = new FileSystemWallet('./WALLETS/wallet'); + * const ccpFile = fs.readFileSync('./network.json'); + * const ccp = JSON.parse(ccpFile.toString()); + * await gateway.connect(ccp, { + * identity: 'admin', + * wallet: wallet + * }); */ async connect(config, options) { const method = 'connect'; @@ -129,7 +149,7 @@ class Gateway { /** * Get the current identity * - * @returns {User} a fabric-client User instance of the current identity used by this Gateway + * @returns {User} A fabric-client {@link User} instance of the current identity used by this Gateway * @memberof Gateway */ getCurrentIdentity() { @@ -140,7 +160,7 @@ class Gateway { /** * Get the underlying Client object instance * - * @returns {Client} the underlying fabric-client Client instance + * @returns {Client} The underlying fabric-client {@link Client} instance * @memberof Gateway */ getClient() { @@ -150,7 +170,7 @@ class Gateway { /** * Returns the set of options associated with the Gateway connection - * @returns {GatewayOptions} the Gateway options + * @returns {GatewayOptions} The Gateway connection options * @memberof Gateway */ getOptions() { @@ -159,7 +179,7 @@ class Gateway { } /** - * clean up and disconnect this Gateway in prep for it to be discarded and garbage collected + * Clean up and disconnect this Gateway connection in preparation for it to be discarded and garbage collected * * @memberof Gateway */ @@ -172,9 +192,9 @@ class Gateway { } /** - * Returns an object representing the network - * @param networkName - * @returns {Promise} + * Returns an object representing a network + * @param {string} networkName The name of the network (channel name) + * @returns {Network} * @memberof Gateway */ async getNetwork(networkName) { diff --git a/fabric-network/lib/impl/event/defaulteventhandlermanager.js b/fabric-network/lib/impl/event/defaulteventhandlermanager.js index 77c01d7ba2..22e90104bf 100644 --- a/fabric-network/lib/impl/event/defaulteventhandlermanager.js +++ b/fabric-network/lib/impl/event/defaulteventhandlermanager.js @@ -83,7 +83,7 @@ class DefaultEventHandlerManager { * create an Tx Event handler for the specific txid * * @param {*} txid - * @returns + * @returns The transaction event handler * @memberof DefaultEventHandlerFactory */ createTxEventHandler(txid) { diff --git a/fabric-network/lib/impl/event/defaulteventhandlerstrategies.js b/fabric-network/lib/impl/event/defaulteventhandlerstrategies.js index f6da20769b..0c850bf452 100644 --- a/fabric-network/lib/impl/event/defaulteventhandlerstrategies.js +++ b/fabric-network/lib/impl/event/defaulteventhandlerstrategies.js @@ -9,22 +9,48 @@ const AllForTxStrategy = require('fabric-network/lib/impl/event/allfortxstrategy'); const AnyForTxStrategy = require('fabric-network/lib/impl/event/anyfortxstrategy'); +/** + * Default event handler strategy.
+ * Listen to all event hubs for the connected organisation. + * The [submitTransaction]{@link Contract#submitTransaction} method will wait + * until all of the events to be received from + * all of the event hubs that are still connected (minimum 1). + */ function MSPID_SCOPE_ALLFORTX(eventHubFactory, network, mspId) { const peers = network.getPeerMap().get(mspId); return new AllForTxStrategy(eventHubFactory, peers); } +/** + * Event handler strategy.
+ * Listen to all event hubs for the connected organisation. + * The [submitTransaction]{@link Contract#submitTransaction} method will wait + * until the first event from any of the event hubs that are still connected. + */ function MSPID_SCOPE_ANYFORTX(eventHubFactory, network, mspId) { const peers = network.getPeerMap().get(mspId); return new AnyForTxStrategy(eventHubFactory, peers); } +/** + * Event handler strategy.
+ * Listen to all event hubs for all peers in the current network. + * The [submitTransaction]{@link Contract#submitTransaction} method will wait + * until all of the events to be received from + * all of the event hubs that are still connected (minimum 1). + */ //eslint-disable-next-line no-unused-vars function NETWORK_SCOPE_ALLFORTX(eventHubFactory, network, mspId) { const peers = network.getChannel().getPeers(); return new AllForTxStrategy(eventHubFactory, peers); } +/** + * Event handler strategy.
+ * Listen to all event hubs for all peers in the current network. + * The [submitTransaction]{@link Contract#submitTransaction} method will wait + * until the first event from any of the event hubs that are still connected. + */ //eslint-disable-next-line no-unused-vars function NETWORK_SCOPE_ANYFORTX(eventHubFactory, network, mspId) { const peers = network.getChannel().getPeers(); diff --git a/fabric-network/lib/impl/wallet/basewallet.js b/fabric-network/lib/impl/wallet/basewallet.js index 254eb79ff8..36d285f7fe 100644 --- a/fabric-network/lib/impl/wallet/basewallet.js +++ b/fabric-network/lib/impl/wallet/basewallet.js @@ -12,6 +12,11 @@ const Wallet = require('../../api/wallet'); const logger = require('../../logger').getLogger('BaseWallet'); const util = require('util'); +/** + * Base class for the built-in wallet implementations. For internal use only. + * @class + * @implements {Wallet} + */ class BaseWallet extends Wallet { constructor(walletMixin = new X509WalletMixin()) { @@ -31,7 +36,7 @@ class BaseWallet extends Wallet { * * @param {*} client * @param {*} label - * @returns + * @returns The user context * @memberof Wallet */ async setUserContext(client, label) { diff --git a/fabric-network/lib/impl/wallet/filesystemwallet.js b/fabric-network/lib/impl/wallet/filesystemwallet.js index 1a835ba18f..542e0e7b1e 100644 --- a/fabric-network/lib/impl/wallet/filesystemwallet.js +++ b/fabric-network/lib/impl/wallet/filesystemwallet.js @@ -17,8 +17,7 @@ const logger = require('../../logger').getLogger('FileSystemWallet'); * This class defines an implementation of an Identity wallet that persists * to the file system. * - * @class FileSystemWallet - * @see See {@link BaseWallet} + * @class * @extends {BaseWallet} */ class FileSystemWallet extends BaseWallet { diff --git a/fabric-network/lib/impl/wallet/inmemorywallet.js b/fabric-network/lib/impl/wallet/inmemorywallet.js index ef0858b0ff..c40d889c24 100644 --- a/fabric-network/lib/impl/wallet/inmemorywallet.js +++ b/fabric-network/lib/impl/wallet/inmemorywallet.js @@ -16,6 +16,10 @@ const logger = require('../../logger').getLogger('InMemoryWallet'); // label it will overwrite the existing one. const memoryStore = new Map(); +/** + * @class + * @extends {BaseWallet} + */ class InMemoryWallet extends BaseWallet { constructor(walletmixin) { super(walletmixin); diff --git a/fabric-network/lib/impl/wallet/x509walletmixin.js b/fabric-network/lib/impl/wallet/x509walletmixin.js index ad5b27dd14..0be4cc1b2a 100644 --- a/fabric-network/lib/impl/wallet/x509walletmixin.js +++ b/fabric-network/lib/impl/wallet/x509walletmixin.js @@ -8,6 +8,9 @@ const logger = require('../../logger').getLogger('X509WalletMixin'); +/** + * @class + */ class X509WalletMixin { static createIdentity(mspId, certificate, privateKey) { diff --git a/fabric-network/lib/network.js b/fabric-network/lib/network.js index 803e615da2..c65b4d99fb 100644 --- a/fabric-network/lib/network.js +++ b/fabric-network/lib/network.js @@ -11,13 +11,19 @@ const logger = require('./logger').getLogger('Network'); const DefaultEventHandlerManager = require('./impl/event/defaulteventhandlermanager'); const util = require('util'); +/** + * A Network represents the set of peers in a Fabric network. + * Applications should get a Network instance using the + * gateway's [getNetwork]{@link Gateway#getNetwork} method. + */ + class Network { - /** - * Network constructor for internal use only + /* + * Network constructor for internal use only. * @param {Gateway} gateway The owning gateway instance * @param {Channel} channel The fabric-client channel instance - * @private + * @ignore */ constructor(gateway, channel) { logger.debug('in Network constructor'); @@ -141,8 +147,8 @@ class Network { /** * Returns an instance of a contract (chaincode) on the current network - * @param chaincodeId - * @returns {Contract} + * @param {string} chaincodeId the chaincode Identifier + * @returns {Contract} the contract * @api */ getContract(chaincodeId) {