README.md

Portable Abstractions and Patterns for Java

This module is a part of the Pip.Services polyglot microservices toolkit. It provides a set of basic patterns used in microservices or backend services. Also the module implemenets a reasonably thin abstraction layer over most fundamental functions across all languages supported by the toolkit to facilitate symmetric implementation.

The module contains the following packages:

• Commands - Commanding and Eventing patterns
• Config - configuration framework
• Convert - portable soft value converters
• Data - data value objects and random value generators
• Errors - portable application errors
• Random - random data generators
• Refer - component referencing framework
• Reflect - portable reflection helpers
• Run - execution framework
• Validate - data validators

Quick links:

• Configuration Pattern
• Locator Pattern
• Component Lifecycle
• Data Patterns
• API Reference
• Change Log
• Get Help
• Contribute

Use

Go to the pom.xml file in Maven project and add dependencies::

<dependency>
  <groupId>org.pipservices3</groupId>
  <artifactId>pip-services3-commons</artifactId>
  <version>3.1.0</version>
</dependency>

Then you are ready to start using the Pip.Services patterns to augment your backend code.

For instance, here is how you can implement a component, that receives configuration, get assigned references, can be opened and closed using the patterns from this module.

package org.pipservices3.commons;

import org.pipservices3.commons.config.ConfigParams;
import org.pipservices3.commons.config.IConfigurable;
import org.pipservices3.commons.errors.ApplicationException;
import org.pipservices3.commons.errors.ConfigException;
import org.pipservices3.commons.refer.IReferenceable;
import org.pipservices3.commons.refer.IReferences;
import org.pipservices3.commons.refer.ReferenceException;
import org.pipservices3.commons.run.IOpenable;

public class MyComponentA implements IConfigurable, IReferenceable, IOpenable {

    private String _param1 = "ABC";
    private int _param2 = 123;
    private MyComponentB _anotherComponent;
    private boolean _opened = true;

    @Override
    public void configure(ConfigParams config) throws ConfigException {
        this._param1 = config.getAsStringWithDefault("param1", this._param1);
        this._param2 = config.getAsIntegerWithDefault("param2", this._param2);
    }

    @Override
    public void setReferences(IReferences references) throws ReferenceException, ConfigException {
        this._anotherComponent = refs.getOneRequired<MyComponentB>(
                new Descriptor("myservice", "mycomponent-b", "*", "*", "1.0")
        );
    }

    @Override
    public boolean isOpen() {
        return this._opened;
    }

    @Override
    public void open(String correlationId) throws ApplicationException {
        this._opened = true;
        System.out.println("MyComponentA has been opened.");
    }

    @Override
    public void close(String correlationId) throws ApplicationException {
        this._opened = true;
        System.out.println("MyComponentA has been closed.");
    }
}

Then here is how the component can be used in the code

import org.pipservices3.commons.config.ConfigParams;
import org.pipservices3.commons.errors.ApplicationException;
import org.pipservices3.commons.errors.ConfigException;
import org.pipservices3.commons.refer.Descriptor;
import org.pipservices3.commons.refer.References;

public class MainClass {
    public static void main(String[] args) throws ApplicationException {
        MyComponentA myComponentA = new MyComponentA();

        // Configure the component
        myComponentA.configure(ConfigParams.fromTuples(
                "param1", "XYZ",
                "param2", 987
        ));

        // Set references to the component
        myComponentA.setReferences(References.fromTuples(
                new Descriptor("myservice", "mycomponent-b", "default", "default", "1.0"),
                myComponentB
        ));

        // Open the component
        myComponentA.open("123");
        System.out.println("MyComponentA has been opened.");
    }
}

Develop

For development you shall install the following prerequisites:

• Java SE Development Kit 8+
• Eclipse Java Photon or another IDE of your choice
• Docker
• Apache Maven

Build the project:

mvn install

Run automated tests:

mvn test

Generate API documentation:

./docgen.ps1

Before committing changes run dockerized build and test as:

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

Contacts

The initial implementation is done by Sergey Seroukhov. Pip.Services team is looking for volunteers to take ownership over Java implementation in the project.