Solution Overview

COHORTE is a platform for developing and rolling out robust and reliable software. Software produced with COHORTE has a high level of robustness and reliability since its is made up of a range of components and services protected from one another by isolation containers. This modular architecture guarantees that software cannot be paralyzed in the event of failure of one of its components and that, for example, 100% of the data communicated is processed.

This modular architecture ensures automatic service recovery after errors and to supply degraded responses in the event of unavailability of a component. The platform incorporates a range of tried and tested basic components dramatically reducing specific developments, thereby reducing the cost of projects using them. The level of reliability of software produced with COHORTE SDK also reduces operating and maintenance costs for the companies software packages.

Goals and Benefits

There are a number of benefits to using COHORTE to build your software applications. The most evident ones are:

Service-oriented Component-based Applications

COHORTE provides a framework to construct modularised applications consisting of software components that uses software services provided by other components. This approach allows to construct IT applications as mean of a set of components providing and requiring services. COHORET is compliant to OSGi specification.

Multi-language programming

Components in a COHORTE system can be implemented in Java or Python programming languages using Apache Felix iPOJO (Java) and/or isandlatech iPOPO (Python) service-based component-model frameworks. There is also a partial support for .Net components using IronPython component facade (full support for .Net is in the project's roadmap) . You can also wrap other legacy modules implemented in other programming languages by using Python component wrappers. In addition, you can dynamically update the C code without any complications. COHORTE Provides a common implementation for Remotes Services allowing the integration of a mixture of components with zero configuration. Service provider can be implemented using Python and used by another component implemented in Java, and vise versa

Components Distribution

COHORTE developers provide only implementations for the different components providing or requiring services. At runtime, the concrete placement of components in execution nodes is managed by the COHORTE runtime. Two components can work together transparantly even they are located on two seperate machines.

Heterogeneous Environments

COHORTE components can be executed on different kind of devices, from small devices like Raspberry-Pi to big servers whereas having windows, linux, or Mac OS operating systems.

Dynamic Isolation and Resilience

COHORTE automatically prevents and corrects component failures by isolating them and restarting them seperatly from others. Users can also define static isolates in which they put components that are guaranteed to be safe.

Development and Monitoring Tools

COHORTE Platform includes a centralized monitoring web interface for all the running nodes. This interface allows to dynamically watch what is happening in the COHORTE system (Nodes, Isolates, and Components updates)

About

Project is an open source framework hosted on GitHub and sponsored by isandlaTech . To help you developping your business applications using COHORTE, feel free to contact isandlaTech’s support team at contact@isandlatech.com .

A COHORTE system is a set of (distributed) Software Components connected together using services to ensure some functionality.

In the following sub-section, we detail the main concepts behind COHORET system.

Dynamic Components

COHORTE Components represents a software component providing a service and eventually requiring other services to do ensure some tasks. Components can be implemented using Python or Java programming languages. We support and provide component-based framework for each language. Cohorte components implements only business logic, all the distribution and dependencies with other components are managed by COHORTE. Components can be deployed and removed dynamically without stopping the system.

Java components are implemented using Apache Felix iPOJO component-based model. Whereas Python components are implemented using isandlaTech iPOPO component-based model. This two component-based service-oriented models uses OSGi container as runtime support. C#, C and other programming languages components could be wrapper in either Java or Python supported dynamic components.

Isolates

In COHORTE, OSGI containers could be created dynamically to host some set of related components. To communicate two remote components, COHORTE provides an implementation of Remote Services specification (part of OSGi specification) for Java and Python components. There is no need to provide specific configurations / proxies to get the Remote Services work, COHORTE provides zero-config approach for connecting remote services (Discovery and Transportation are automatic).

COHORTE provides a mechanism to isolate faulty components in a seperate OSGi containers. This is way we refer and call OSGi containers Isolates .

Nodes

COHORTE Isolates are located and managed on COHORTE Nodes . Nodes can be created by users using a provided scripts. Each Node can manage (create / monitor / delete) several isolates. COHORTE internal components responsible for managing local isolates and their relation with other remote isolates are located on special purpose Isolate (created at Node’s startup and can not host applicative components).

Composers

The Composer is a special COHORTE Runtime Component responsible of instantiating the different components of an application respecting a composition specification. In COHORTE there are different Composer levels:

• Top Composer : It loads the composition declarative description and computes the sets of components according to the node they must be instantiated on.
• Node Composer : It calculates the different isolates that must be exist for the local set of components.
• Isolate Composer : It uses framework-specific agents to request the instantiation of the components assigned to its isolate, and looks after their evolution.

There are several ways of installing COHORTE on your system. In the following, we detail the manual installation (as the installers are not yet available).

Manual installation

Depending on your operating system, we give some insights about how install COHORTE distribution using specific platform instructions.

• Donwload the COHORTE distribution adequate to your operating system from the downloads page . E.g., for Linux OS you download cohorte-1.0.0-linux-distribution.tar.gz .

Unix-based Operating Systems (Linux, Solaris and Max OS X)

1. Extract the distribution archive, i.e. cohorte-1.0.0-linux-distribution.tar.gz to the directory you wish to install COHORTE. These instructions assume you chose /opt/isandlatech/cohorte . The subdirectory cohorte-1.0.0 will be created from the archive.
2. Go to the cohorte-1.0.0 directory and launch setup.sh command. This will export COHORTE_HOME environment variable (and add it to your home directory’s .bashrc file).
3. Ensure to have the access rights to $COHORTE_HOME directory (e.g., `sudo chgrp -R your_login cohorte-1.0.0; chown -R your_login cohorte-1.0.0).

Windows

1. Prior to install Cohorte, you should have Python 3.4 installed on your machine. You have also to install Pywin32 adequat to your operating system.
2. Set PYTHON_HOME environment variable to target your installed Python distribution.
3. Set PYTHON_INTERPRETER=%PYTHON_HOME%\python.exe environment variable to target your python interpreter executable.
4. Unzip the distribution archive to the directory you wish to install COHORTE. These instructions assume you chose C:\Program Files\Cohorte . The subdirectory cohorte-1.0.0 will be created from the archive.
5. Add the COHORTE_HOME environment variable by opening up the system properties (WinKey + Pause), selecting the “Advanced” tab, and the “Environment Variables” button, then adding the COHORTE_HOME variable in the user variables with the value C:\Program Files\Cohorte\cohorte-1.0.0\home . Be sure to omit any quotation marks around the path even if it contains spaces.
6. Add %COHORTE_HOME%\bin to the system’s PATH environment variable.

Using Installers

Not yet available.

Overview

A COHORTE application is composed of a set of components requiring and providing services. These components can be located in one node or dispatched between a set of nodes.

In a classical component-based frameworks, components are instantiated statically at a predefined locations. They are also configured to communicate together before starting the application. This leads to a situation in which a lot of configuration files should be managed or to recompile the components if the communication aspects are hard coded.

In contrast, COHORTE Components are instantiated, configured and placed in the right node automatically. There is no need to implement the distribution related aspects like serialization or client/server interaction. Components are seen as black-boxes wired by declared (remote) services.

Service Oriented Component Models (SOCM)

To implement COHORTE managed components, COHORTE supports two main, already existing component-based frameworks :

• Apache Felix iPOJO (Java)
• Pelix/iPOPO (Python)

If you are already familiar with one of the two frameworks, all whats you have to do in order to get your components managed by COHORTE is to not instantiate them (using @Instantiate annotation or its XML equivalent). COHORTE will instantiate them automatically. To have benefits of Remote Services feature, your services should use primitive types instead of complex user-specific types. Next, you need to write a small description of your application components using the format explained hereafter.

Remote Services

What is?

Herald

Multi-platform discovery and transport framework

Supported protocols :

Supported SOCMs

In this section, we will provide a brief introduction to the supported Service Oriented Components Models in COHORTE.

OSGi / Apache Felix iPOJO

Java

@Component("AggregatorFactory")
@Provides
public class Aggregator implements ITemperature {
  @Requires List<ISensor> sensors;
  @Requires IStore store;

  @Validate public void start( ) {
  /* Do something to regulate 
  temperature depending on room's 
  internal temperature. */
  }
}

Pelix / iPOPO

Python

@Component("AggregatorFactory")
@Provides("java:/Itemperature")
@Requires("sensors", "java:/ISensor", aggregate=True)
@Requires("store", "java:/IStore")
class Aggregator(object):
  def __init__(self):
    self.sensors = []
    self.store = None

  @Validate 
  def start(self): 
    """
    Do something useful to regulate 
    temperature depending on room's
    internal temperature.
    """
    pass

Interoperability between Java and Python implementation?

• We should add java:/ prefix to required services in Python.

C# support

Partial support using IronPython.

Other legacy code

Wrapping in iPOPO (Python) or iPOJO (Java) components

This specification is used to describe the composition of the final application in term of component that should be instantiated in which isolate of which node.

Composition

{
  // Composition's name
  "name": "composition-name",
 
  // Top composite
  "root": { /* see 'composite' */ }
}

Composite

{
  // Name of composite
  "name": "composite1",
 
  // List of components
  "components" : [ /* see 'components' */ ],
 
  // List of sub-composites
  "composites" : [
     {
       "name": "subcomposite",
       "components" : [ /* ... */ ]
       // this composite hasn't sub-composites.
     }
  ]
}

Components

{
  // Name of the component
  "name" : "aggregator-UI",
  // Name of its Component Factory
  "factory" : "demo-sensor-aggregator-ui-factory",
  // Indication on the implementation language
  "language" : "python",
  // Location on a precise isolate
  "isolate" : "aggregator.ui",
  // Location on a precise node
  "node" : "central"
  // Initial configuration of the component
  "properties" : {
    "servlet.path" : "/sensors"
  },
  // Wiring with another component named 'aggregtor' 
  // which can be found in any composite of this composition
  "wires" : {
    "_aggregator" : "aggregator"
  },
  "filters" : {
    "_handler": "(ready=1)"
  }
}

import-files

base.js

{
  "root": "root",
  "imported": {
    "top-value": "top",
    "answer": 42,
    // Import from another file
    "import-files": ["imported.js"]
  }
}

imported.js

{
  // New property
  "hello": "World",
  // This value will be overloaded by the high level property's value
  "answer": 51
}

Obtained result :

{
  "root": "root",
  "imported": {
    // Non modified value
    "top-value": "top",
    // Conserved value
    "answer": 42,
    // New property
    "hello": "world"
  }
}

Complete example

{
  "name" : "hello-world",
  "root" : {
    "name" : "hello-worldd-composition",
    "components" : [ 
      {
        "name" : "Hello_Components",
        "factory" : "hello_components_factory",
        "node" : "node1",
        "isolate": "web"
      }, {
        "name" : "A_component",
        "factory" : "component_a_factory",
        "node" : "node1"
      }, {
        "name" : "B_component",
        "factory" : "component_b_factory",
        "node" : "node1"
      }, {
        "name" : "E_component",
        "factory" : "component_e_factory",
        "node" : "node1"
      }, {
        "name" : "C_component",
        "factory" : "component_c_factory",        
        "node" : "node2"
      }, {
        "name" : "D_component",
        "factory" : "component_d_factory",
        "node" : "node2"
      }
    ]
  }
}

COHORTE system is composed of several Nodes. Only one node is specified to be Top Composer. It manages the components distribution among the available participating nodes.

In this chapter, we will detail how to create and start COHORTE nodes using simple command lines.

Creating nodes

To create COHORTE node, you have to use the provided cohorte-create-node command.

Usage

$ ./cohorte-create-node [-h] [-n NODE_NAME] [-a APP_NAME]

Options

This command has the following options :

  -h, --help            show this help message and exit

  -n NODE_NAME, --name NODE_NAME
                        Name of the node
  -a APP_NAME, --app-name APP_NAME
                        application's symbolic name

Results

This command will create a directory containing the following structure:

• node_name correspond to the provided name by the user using the --name option.
• run is the starting script. It will be detail in the next section (Starting nodes)
• repo is a directory where user provided bundles should be placed.
• conf is a directory containing configuration files. Only one configuration file is created initially (composition.js), other files are generated by run script in this location.

Here is the content of the generated conf/composition.js file. You should add component descriptions on the indicated zone (see Composition Specification ).

{ 
  "name": "default-application",
  "root": {
    "name": "default-application-composition",
    "components": [
      /* your component descriptions here */
    ]
  }
}

Only the node started as Top Composer (see next section) should have this configuration file completed. Other nodes started as simple nodes will ignore this file.

Starting nodes

To start a COHORTE node, you have to use the generated run command (this command calls cohorte-start-node internal command).

Usage

$ ./run [-h] [-a APPLICATION_ID]
        [--use-config CONFIG_FILE] [--update-config]
        [--show-config] [-b BASE_ABSOLUTE_PATH]
        [-n NODE_NAME] [--top-composer IS_TOP_COMPOSER]
        [--composition-file COMPOSITION_FILE]
        [--auto-start AUTO_START]
        [--web-admin WEB_ADMIN_PORT]
        [--shell-admin SHELL_ADMIN_PORT]
        [--transport TRANSPORT_MODES]
        [--xmpp-server XMPP_SERVER]
        [--xmpp-port XMPP_PORT]
        [--http-ipv HTTP_IPV]

Options

There are different kind of options depending on the use of the actual node.

Mandatory options

  -a APPLICATION_ID, --app-id APPLICATION_ID
                        Application's ID

All the nodes participating for a given application should have the same APPLICATION_ID .

Startup configuration options

  --use-config CONFIG_FILE  Configuration file to use for starting cohorte node.
                        By default the run.js file is used if available
  --update-config       Update startup configuration file with provided
                        options
  --show-config         Show startup configuration file content
  -b BASE_ABSOLUTE_PATH, --base BASE_ABSOLUTE_PATH
                        absolute file path of the node's directory

We can write the startup configurations in a separate JSON file (see How to use startup configuration files section). This options will simplify the command options list and allows sharing the same startup configurations between several nodes.

Information about the node to start

  -n NODE_NAME, --node NODE_NAME
                        Node name
  --top-composer IS_TOP_COMPOSER
                        Flag indicating that this node is a Top Composer
  --composition-file COMPOSITION_FILE
                        Composition file (by default 'composition.js'). All
                        composition files should be placed on 'conf' directory
  --auto-start AUTO_START
                        Auto-start the composition if this node is a Top
                        Composer
  --web-admin WEB_ADMIN_PORT
                        Node web admin port
  --shell-admin SHELL_ADMIN_PORT
                        Node remote shell port

We can provide a different node name than the already provided when the node is created (by using –node option). One important option of cohorte nodes is the --top-composer . If set, the node will be considered as a Top Composer (manages all the distribution of components among the available nodes). Users can also provide customised informations such as the http port to use for the web-admin component (see monitoring chapter ), or the port to use for the remote shell admin component.

Information about the transport protocols to use

  --transport TRANSPORT_MODES
                        Transport mode (http and/or xmpp - seperated by comma)
  --xmpp-server XMPP_SERVER
                        XMPP server
  --xmpp-port XMPP_PORT
                        XMPP server port
  --http-ipv HTTP_IPV
                        HTTP IP version to use (when transport mode is http)

The --transport option allow the use to choose which transport protocol to use between the actual node and the other nodes participating in the same application. You can provide a common seperated list of the supported protocols ( http and xmpp for the moment). Each protocol need additional configuration options that should be provided seperataly using dedicated options (–xmpp-server for instance to mention the XMPP server to use).

How to use startup configuration files

To avoid re-typing the same options each time a node is started, or to share the same configuration between several nodes, you can provide a startup configuration file which contains such startup configurations. The content of such file is described hereafter.

run.js

{	
	"application-id": "ABCDEF",

	"node": {		
		"name": "node-rasp",
		"top-composer": true,
		"web-admin": 9001,
		"shell-admin": 9001		
	},
	"transport": ["xmpp"],
	"transport-xmpp": {
		"xmpp-server": "charmanson.isandlatech.com",
		"xmpp-port": 5222
	}
}

• To show the content of the startup configuration file :

$ ./run --show-config 

• To use other configuration file than the default run.js file :

$ ./run --use-config other_run_conf.js

• Update the startup configuration using command options (–some-configuration should be replaced with a supported options list):

$ ./run --update-config --some-configurations 

This will update all the provided options within the startup configuration file (run.js).

Connection modes

Using HTTP

./run --app-id myapplication --transport http 

The discovery is done using TCP multi-caste feature. This limits the scope of the discovered COHORET nodes to only available at a local network area LAN. To deploy you COHORTE nodes at the Internet level, you should use XMPP mode.

Using XMPP

You need to start the Top Composer with the following configurations :

./run --app-id myapplication --transport xmpp \
--xmpp-server server_url \
--xmpp-port 5222 \

The XMPP server should accept anonymous connections and `multi-user chat .

Using HTTP/XMPP

You can use the two transport protocols in the same time. At runtime, only one is used, if it does not work COHORTE choose the other one.

COHORTE has an integrated shell to allow users manipulate and monitor the system. Here the list of the provided shell commands and their explanation.

Manage COHORTE Platform

Other advanced commands

These commands are categorized by namespace.

“default” name space

“herald” name space (COHORTE messaging layer)

“ipopo” name space (Service-Oriented Component Model)

“shell” name space

“top” name space

In this document, we detail the ADMIN RESTful API v1 of COHORTE platform as well as the web admin interface built on the top of this API.

Web Admin

Admin REST API v1

API endpoints

Detail of REST APIs

APIV1-001 : GET the list of all Nodes

• URL: http://myhost:port/admin/api/v1/nodes
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "code": 200,
        "count": 2
    },
    "nodes": [
        {
            "uid": "56e5b100-c8a2-4bd8-a818-30edaf9a8fe9",
            "name": "central"
        },
        {
            "uid": "acfd6479-f29f-4bf0-ae4d-acd681e3a531",
            "name": "raspberry-pi-1"
        }
    ]
}

APIV1-002 : GET the list of all Isolates

• URL: http://myhost:port/admin/api/v1/isolates
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "code": 200,
        "lastupdate": 1411979225.65,
        "count": 2
    },
    "isolates": [
        {
            "uid": "50684926acb4387d0f007ced",
            "name": "webadmin-isolate",
            "node_uid": "41110b1d-b510-4e51-9945-a752da04a16d",
            "node_name": "central"
        },
        {
            "uid": "03ff839a-df24-4bdf-b734-9fac1c886c65",
            "name": "spellcheck-isolate",
            "node_uid": "41110b1d-b510-4e51-9945-a752da04a16d",
            "node_name": "central"
        }
    ]
}

APIV1-003 : GET the list of all Components

• URL: http://myhost:port/admin/api/v1/components
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "code": 200,
        "count": 2
    },
    "components": [
        {
            "name": "spell_check_client",
            "factory": "spell_check_client_factory",
            "language": "python",
            "isolate_uid": "03ff839a-df24-4bdf-b734-9fac1c886c65",
            "isolate_name": "spellcheck-isolate"
        },
        {
            "name": "spell_dictionray_FR",
            "factory": "spell_dictionary_FR_factory",
            "language": "python",
            "isolate_uid": "03ff839a-df24-4bdf-b734-9fac1c886c65",
            "isolate_name": "spellcheck-isolate"
        }
    ]
}

APIV1-050 : GET Node detail

• URL: http://myhost:port/admin/api/v1/nodes/56e5b100-c8a2-4bd8-a818-30edaf9a8fe9
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "node": "41110b1d-b510-4e51-9945-a752da04a16d",
        "code": 200
    },
    "node": {
        "name": "central",
        "nbr_isolates": 3
    }
}

APIV1-051 : GET Isolate detail

• URL: http://myhost:port/admin/api/v1/isolates/50684926acb4387d0f007ced
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "isolate": "50684926acb4387d0f007ced",
        "code": 200
    },
    "isolate": {
        "name": "webadmin-isolate",
        "type": "cohorte-isolate",
        "nbr_components": 3,
        "node_uid": "41110b1d-b510-4e51-9945-a752da04a16d",
        "node_name": "central",
        "http_access" : "10.130.1.97",
        "http_port" : 9500,
        "shell_port" : 9501
    }
}

APIV1-052 : GET Component detail

• URL: http://myhost:port/admin/api/v1/components/spell_check_client
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "component": "spell_check_client",
        "code": 200
    },
    "node": {
        "name": "spell_check_client",
        "factory": "spell_check_client_factory",
        "language": "python",
        "isolate_uid": "03ff839a-df24-4bdf-b734-9fac1c886c65",
        "isolate_name": "spellcheck-isolate"
        "bundle_name": "spellchecker.spell_check"
        "bundle_version": "1.0.0"
        "properties": {
             "prop1": "value1",
             "prop2": "value2",
        }
    }
}

APIV1-100 : Get Isolates of one particular Node

• URL: http://myhost:port/admin/api/v1/nodes/56e5b100-c8a2-4bd8-a818-30edaf9a8fe9/isolates
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "node": "41110b1d-b510-4e51-9945-a752da04a16d",
        "code": 200,
        "count": 2
    },
    "isolates": [
        {
            "uid": "50684926acb4387d0f007ced",
            "name": "webadmin-isolate"
        },
        {
            "uid": "03ff839a-df24-4bdf-b734-9fac1c886c65",
            "name": "spellcheck-isolate"
        }
    ]
}

APIV1-101 : Get Components of one particular Isolate

• URL: http://myhost:port/admin/api/v1/isolates/50684926acb4387d0f007ced/components
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "isolate": "50684926acb4387d0f007ced",
        "code": 200,
        "count": 3
    },
    "components": [
        {
            "name": "spell_dictionary_FR",
            "factory": "spell_dictionary_FR_factory",
            "language": "python"
        },
        {
            "name": "spell_check",
            "factory": "spell_check_factory",
            "language": "python"
        },
        {
            "name": "spell_client",
            "factory": "spell_client_factory",
            "language": "python"
        }
    ]
}

APIV1-150 : Kill all nodes

• URL: http://myhost:port/admin/api/v1/nodes/kill
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "code": 200
    },
    "status": {
        "code": 0,
        "description": "All nodes successfully destroyed"
    }
}

APIV1-151 : Kill node

• URL: http://myhost:port/admin/api/v1/nodes/56e5b100-c8a2-4bd8-a818-30edaf9a8fe9/kill
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "node": "56e5b100-c8a2-4bd8-a818-30edaf9a8fe9",
        "code": 200
    },
    "status": {
        "code": 0,
        "description": "Node successfully destroyed"
    }
}

APIV1-152 : Kill isolate

• URL: http://myhost:port/admin/api/v1/isolates/41110b1d-b510-4e51-9945-a752da04a16d/kill
• Supported request methods: GET
• Response format: json
• Requires authentication?: not required
• Response:

• JSON Response Example :

{
    "meta": {
        "isolate": "41110b1d-b510-4e51-9945-a752da04a16d",
        "code": 200
    },
    "status": {
        "code": 0,
        "description": "Isolate successfully destroyed"
    }
}