Component definitions for Dart

This module is a part of the Pip.Services polyglot microservices toolkit.

The Components module contains standard component definitions that can be used to build applications and services.

The module contains the following packages:

• Auth - authentication credential stores
• Build - basic factories for constructing objects
• Cache - distributed cache
• Config - configuration readers and managers, whose main task is to deliver configuration parameters to the application from wherever they are being stored
• Connect - connection discovery and configuration services
• Count - performance counters
• Info - context info implementations that manage the saving of process information and sending additional parameter sets
• Lock - distributed lock components
• Log - basic logging components that provide console and composite logging, as well as an interface for developing custom loggers
• Test - minimal set of test components to make testing easier
• Component - the root package

Quick links:

• Logging

• Configuration

• API Reference

• Change Log

• Get Help

• Contribute

• Examples

• Warning! Config package now not work with condition {{#if var}} something {{/}} in config files. Use Mustache syntax, for example {{#var}} something {{/var}}

Use

Add this to your package's pubspec.yaml file:

dependencies:
  pip_services3_components: version

Now you can install package from the command line:

pub get

Example how to use Logging and Performance counters. Here we are going to use CompositeLogger and CompositeCounters components. They will pass through calls to loggers and counters that are set in references.

import 'package:pip_services3_commons/src/config/ConfigParams.dart';
import 'package:pip_services3_commons/src/config/IConfigurable.dart';
import 'package:pip_services3_commons/src/refer/IReferences.dart';
import 'package:pip_services3_commons/src/refer/IReferenceable.dart';
import 'package:pip_services3_components/src/log/CompositeLogger.dart';
import 'package:pip_services3_components/src/count/CompositeCounters.dart';
import 'package:pip_services3_components/src/count/Timing.dart';


class MyComponent implements IConfigurable, IReferenceable {
  CompositeLogger _logger = CompositeLogger();
  CompositeCounters _counters = CompositeCounters();
  
  configure(ConfigParams config) {
    this._logger.configure(config);
  }
  
  setReferences(IReferences refs) {
    this._logger.setReferences(refs);
    this._counters.setReferences(refs);
  }
  
  myMethod(String correlationId, dynamic param1) {
    try{
      this._logger.trace(correlationId, "Executed method mycomponent.mymethod");
      this._counters.increment("mycomponent.mymethod.exec_count", 1);
      Timing timing = this._counters.beginTiming("mycomponent.mymethod.exec_time");
      ....
      timing.endTiming();
    } catch(e) {
      this._logger.error(correlationId, e, "Failed to execute mycomponent.mymethod");
      this._counters.increment("mycomponent.mymethod.error_count", 1);
    }
  }
}

Example how to get connection parameters and credentials using resolvers. The resolvers support "discovery_key" and "store_key" configuration parameters to retrieve configuration from discovery services and credential stores respectively.

import 'package:pip_services3_commons/src/config/ConfigParams.dart';
import 'package:pip_services3_commons/src/config/IConfigurable.dart';
import 'package:pip_services3_commons/src/refer/IReferences.dart';
import 'package:pip_services3_commons/src/refer/IReferenceable.dart';
import 'package:pip_services3_commons/src/run/IOpenable.dart';
import 'package:pip_services3_components/src/connect/ConnectionParams.dart';
import 'package:pip_services3_components/src/connect/ConnectionResolver.dart';
import 'package:pip_services3_components/src/auth/CredentialParams.dart';
import 'package:pip_services3_components/src/auth/CredentialResolver.dart';

class MyComponent implements IConfigurable, IReferenceable, IOpenable {
  final _connectionResolver = ConnectionResolver();
  final _credentialResolver = CredentialResolver();
  bool _opened = false;

  @override
  void configure(ConfigParams config) {
    _connectionResolver.configure(config);
    _credentialResolver.configure(config);
  }

  @override
  void setReferences(IReferences refs) {
    _connectionResolver.setReferences(refs);
    _credentialResolver.setReferences(refs);
  }

  // ...
  @override
  Future open(String? correlationId) async {
    ConnectionParams? connection =
        await _connectionResolver.resolve(correlationId);

    CredentialParams? credential =
        await _credentialResolver.lookup(correlationId);

    if (connection != null && credential != null) {
      String? host = connection.getHost();
      int? port = connection.getPort();
      String? user = credential.getUsername();
      String? pass = credential.getPassword();
      // ...
      _opened = true;
    }
  }

  @override
  Future close(String? correlationId) {
    // do closing
    return Future.value();
  }

  @override
  bool isOpen() {
    return _opened;
  }
}

Example how to use caching and locking. Here we assume that references are passed externally.

import 'package:pip_services3_commons/src/refer/Descriptor.dart';
import 'package:pip_services3_commons/src/refer/References.dart';
import 'package:pip_services3_commons/src/refer/IReferences.dart';
import 'package:pip_services3_commons/src/refer/IReferenceable.dart';
import 'package:pip_services3_components/src/lock/ILock.dart';
import 'package:pip_services3_components/src/lock/MemoryLock.dart';
import 'package:pip_services3_components/src/cache/ICache.dart';
import 'package:pip_services3_components/src/cache/MemoryCache.dart';

class MyComponent implements IReferenceable {
  ICache? _cache;
  ILock? _lock;

  @override
  void setReferences(IReferences refs) {
    _cache =
        refs.getOneRequired<ICache>(Descriptor('*', 'cache', '*', '*', '1.0'));
    _lock =
        refs.getOneRequired<ILock>(Descriptor('*', 'lock', '*', '*', '1.0'));
  }

  Future myMethod(String? correlationId, dynamic param1) async {
    // First check cache for result
    dynamic result = await _cache!.retrieve(correlationId, 'mykey');

    // Lock..
    await _lock!.acquireLock(correlationId, 'mykey', 1000, 1000);

    // Do processing
    // ...

    // Store result to cache async
    await _cache!.store(correlationId, 'mykey', result, 3600000);

    // Release lock async
    await _lock!.releaseLock(correlationId, 'mykey');
  }
}

void main() async {
// Use the component
  MyComponent myComponent = MyComponent();

  myComponent.setReferences(References.fromTuples([
    Descriptor('pip-services', 'cache', 'memory', 'default', '1.0'),
    MemoryCache(),
    Descriptor('pip-services', 'lock', 'memory', 'default', '1.0'),
    MemoryLock(),
  ]));

  await myComponent.myMethod(null, 'param1');
}

If you need to create components using their locators (descriptors) implement component factories similar to the example below.

import 'package:pip_services3_components/src/build/Factory.dart';
import 'package:pip_services3_commons/src/refer/Descriptor.dart';

class MyFactory extends Factory {
  static Descriptor myComponentDescriptor =
      Descriptor('myservice', 'mycomponent', 'default', '*', '1.0');

  MyFactory() : super() {
    registerAsType(MyFactory.myComponentDescriptor, MyComponent);
  }
}

// Using the factory

MyFactory myFactory = MyFactory();

MyComponent1 myComponent1 = myFactory.create(
    Descriptor('myservice', 'mycomponent', 'default', 'myComponent1', '1.0'));
MyComponent2 myComponent2 = myFactory.create(
    Descriptor('myservice', 'mycomponent', 'default', 'myComponent2', '1.0'));
...

Develop

For development you shall install the following prerequisites:

• Dart SDK 2
• Visual Studio Code or another IDE of your choice
• Docker

Install dependencies:

pub get

Run automated tests:

pub run test

Generate API documentation:

./docgen.ps1

Before committing changes run dockerized build and test as:

./build.ps1
./test.ps1
./clear.ps1

Contacts

The library is created and maintained by Sergey Seroukhov and Levichev Dmitry.

The documentation is written by Egor Nuzhnykh, Alexey Dvoykin, Mark Makarychev, Levichev Dmitry.