Update Aug 29th 2019: Hyperledger Composer has been deprecated. Please see the README for more information.

Api (Runtime API)

Overview - Common API - Client API - Admin API - Runtime API

Api

A class that contains the root of the transaction processor API. Methods in this class are made available as global functions which can be called by transaction processor functions. The transaction processor API should expose no internal properties or internal methods which could be accessed or misused.

Details

  • Module runtime

Method Summary

Name Returns Description
buildQuery Query Build a query ready for later execution
emit void Emit an event defined in the transaction
getAssetRegistry Promise Get an existing asset registry using the unique identifier of the asset registry
getCurrentIdentity module:composer-common.Resource Get the current identity
getCurrentParticipant module:composer-common.Resource Get the current participant
getFactory module:composer-runtime.Factory Get the factory
getParticipantRegistry Promise Get an existing participant registry using the unique identifier of the participant registry
getSerializer module:composer-common.Serializer Get the serializer
post Promise Post a typed instance to a HTTP URL
query Promise Execute a query defined in a Composer query file, or execute a query built with buildQuery

Method Details

getFactory

module:composer-runtime.Factory getFactory( )

Get the factory. The factory can be used to create new instances of assets, participants, and transactions for storing in registries. The factory can also be used for creating relationships to assets, particpants, and transactions.

Returns

Factory - The factory.

See also

Parameters

No parameters

Example

// Get the factory.
var factory = getFactory();

getSerializer

module:composer-common.Serializer getSerializer( )

Get the serializer. The serializer can be used to create new instances of assets, participants, and transactions from a JavaScript object, or to create a JavaScript object suitable for long-lived persistence.

Returns

Serializer - The serializer.

Parameters

No parameters

Example

// Get the serializer.
var ser = getSerializer();

getAssetRegistry

Promise getAssetRegistry( string id )

Get an existing asset registry using the unique identifier of the asset registry. An asset registry can be used to retrieve, update, or delete existing assets, or create new assets.

Returns

Promise - A promise. The promise is resolved with an AssetRegistry instance representing the asset registry if it exists. If the asset registry does not exist, or the current user does not have access to the asset registry, then the promise will be rejected with an error that describes the problem.

Parameters

Name Type Mandatory Description
id string Yes The ID of the asset registry.

Example

// Get the vehicle asset registry.
return getAssetRegistry('org.example.Vehicle')
  .then(function (vehicleAssetRegistry) {
    // Call methods on the vehicle asset registry.
  })
  .catch(function (error) {
    // Add optional error handling here.
  });

getParticipantRegistry

Promise getParticipantRegistry( string id )

Get an existing participant registry using the unique identifier of the participant registry. An participant registry can be used to retrieve, update, or delete existing participants, or create new participants.

Returns

Promise - A promise. The promise is resolved with an ParticipantRegistry instance representing the participant registry if it exists. If the participant registry does not exist, or the current user does not have access to the participant registry, then the promise will be rejected with an error that describes the problem.

Parameters

Name Type Mandatory Description
id string Yes The ID of the participant registry.

Example

// Get the driver participant registry.
return getParticipantRegistry('org.example.Driver')
  .then(function (driverParticipantRegistry) {
    // Call methods on the driver participant registry.
  })
  .catch(function (error) {
    // Add optional error handling here.
  });

getCurrentParticipant

module:composer-common.Resource getCurrentParticipant( )

Get the current participant. The current participant is determined by the identity that was used to submit the current transaction.

Returns

Resource - The current participant, or null if the transaction was submitted using an identity that does not map to a participant.

Parameters

No parameters

Example

// Get the current participant.
var currentParticipant = getCurrentParticipant();
// Check to see if the current participant is a driver.
if (currentParticipant.getFullyQualifiedType() !== 'org.example.Driver') {
  // Throw an error as the current participant is not a driver.
  throw new Error('Current participant is not a driver');
}
// Check to see if the current participant is the first driver.
if (currentParticipant.getFullyQualifiedIdentifier() !== 'org.example.Driver#DRIVER_1') {
  // Throw an error as the current participant is not a driver.
  throw new Error('Current participant is not the first driver');
}

getCurrentIdentity

module:composer-common.Resource getCurrentIdentity( )

Get the current identity. The current identity is the identity that was used to submit the current transaction.

Returns

Resource - The current identity, or null if the transaction was submitted using an identity that does not map to a participant.

Parameters

No parameters

Example

// Get the current identity.
var currentIdentity = getCurrentIdentity();
// Get the certificate from the current identity.
var certificate = currentIdentity.certificate;

post

Promise post( string url, Typed typed, object options )

Post a typed instance to a HTTP URL

Returns

Promise - A promise. The promise is resolved with a HttpResponse that represents the result of the HTTP POST.

Parameters

Name Type Mandatory Description
url string Yes The URL to post the data to
typed Typed Yes The typed instance to be posted. The instance will be serialized to JSON.
options object Yes The options that are passed to Serializer.toJSON

emit

emit( Resource event )

Emit an event defined in the transaction

Parameters

Name Type Mandatory Description
event Resource Yes The event to be emitted

buildQuery

Query buildQuery( string query )

Build a query ready for later execution. The specified query string must be written in the Composer query language. This functionality is Blockchain platform dependent. For example, when a Composer business network is deployed to Hyperledger Fabric v1.0, Hyperledger Fabric must be configured with the CouchDB database for the world state.

Returns

Query - The built query, which can be passed in a call to query.

Parameters

Name Type Mandatory Description
query string Yes The query string, written using the Composer query language.

Example

// Build a query.
var q = buildQuery('SELECT org.example.sample.SampleAsset WHERE (value == _$inputValue)');
// Execute the query.
return query(q, { inputValue: 'blue' })
  .then(function (assets) {
    assets.forEach(function (asset) {
      // Process each asset.
    });
  })
  .catch(function (error) {
    // Add optional error handling here.
  });

query

Promise query( string; Query query, [Object parameters] )

Execute a query defined in a Composer query file, or execute a query built with buildQuery. This functionality is Blockchain platform dependent. For example, when a Composer business network is deployed to Hyperledger Fabric v1.0, Hyperledger Fabric must be configured with the CouchDB database for the world state.

Returns

Promise - A promise that will be resolved with an array of Resource representing the resources returned by the query.

Parameters

Name Type Mandatory Description
query string; Query Yes The name of the query, or a built query.
parameters Object Yes The parameters for the query.

Example

// Execute the query.
return query('Q1', { inputValue: 'blue' })
  .then(function (assets) {
    assets.forEach(function (asset) {
      // Process each asset.
    });
  })
  .catch(function (error) {
    // Add optional error handling here.
  });

Inherited methods