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

See also

Method Summary

Name Returns Description
buildQuery Query Build a query ready for later execution. The specified query string must be written in the Composer query language.
emit void Emit an event defined in the transaction
getAssetRegistry Promise 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.
getCurrentParticipant module:composer-common.Resource Get the current participant. The current participant is determined by the identity that was used to submit the current transaction.
getFactory module:composer-runtime.Factory 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.
getParticipantRegistry Promise 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.
getSerializer module:composer-common.Serializer 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.
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.

Example

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

Returns

module:composer-runtime.Factory - The factory.

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.

Example

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

Returns

module:composer-common.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.

Example

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

Returns

Promise - A promise. The promise is resolved with an {@link module:composer-runtime.AssetRegistry 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 Optional Description
id string false The ID of the asset registry.

Example

// Get the vehicle asset registry.
return getAssetRegistry('org.acme.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.

Example

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

Returns

Promise - A promise. The promise is resolved with an {@link module:composer-runtime.ParticipantRegistry 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 Optional Description
id string false The ID of the participant registry.

Example

// Get the driver participant registry.
return getParticipantRegistry('org.acme.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.

Example

// Get the current participant.
var currentParticipant = getCurrentParticipant();
// Check to see if the current participant is a driver.
if (currentParticipant.getFullyQualifiedType() !== 'org.acme.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.acme.Driver#DRIVER_1') {
  // Throw an error as the current participant is not a driver.
  throw new Error('Current participant is not the first driver');
}

Returns

module:composer-common.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.acme.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.acme.Driver#DRIVER_1') {
  // Throw an error as the current participant is not a driver.
  throw new Error('Current participant is not the first driver');
}

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 Optional Description
url string false The URL to post the data to
typed Typed false The typed instance to be posted. The instance will be serialized to JSON.
options object false The options that are passed to Serializer.toJSON

emit

void emit( Resource event )

Emit an event defined in the transaction

Parameters

Name Type Optional Description
event Resource false 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.

Example

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

Returns

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

Parameters

Name Type Optional Description
query string false The query string, written using the Composer query language.

Example

// Build a query.
var query = buildQuery('SELECT org.acme.sample.SampleAsset WHERE (value == _$inputValue)');
// Execute the query.
return query(query, { 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.

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.
  });

Returns

Promise - A promise that will be resolved with an array of {@link module:composer-common.Resource Resource} representing the resources returned by the query.

Parameters

Name Type Optional Description
query string; Query false The name of the query, or a built query.
parameters Object true 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.
  });