gitter-badger / context-adapter Goto Github PK

# Context Adapter

• [Introduction] (#section1)
• Dependencies
• Installation
• Running the Context Adapter
• Test coverage
• [How to contribute] (#section6)
• [Additional development documentation] (#section7)
• Contact

## Introduction

The Context Adapter is a FIWARE component part of the Black Button platform by Telefónica.

The Context Adapter is in charge of adapting the communication (protocols and messages) between Telefónica's IoT Platform (and, more concretely, the Orion Context Broker) and the services exposed by Third Parties.

More concretely, the Context Adapter attends 2 types of requests:

1 updateContext requests redirected by the Orion Context Broker. These requests should have a payload such as the following one:

    {
      contextElements: [
        {
          id: ,
          type: caConfig.BUTTON_ENTITY.TYPE,
          isPattern: false,
          attributes: [
            {
              name: caConfig.BUTTON_ENTITY.CA_SERVICE_ID_ATTR_NAME,
              type: 'string',
              value: ''
            },
            {
              name: caConfig.BUTTON_ENTITY.CA_INTERACTION_TYPE_ATTR_NAME,
              type: 'string',
              value: 'synchronous | asynchronous'
            },
            {
              name: caConfig.BUTTON_ENTITY.CA_OPERATION_EXTRA_ATTR_NAME,
              type: 'string',
              value: ''
            },
            {
              name: caConfig.BUTTON_ENTITY.CA_OPERATION_STATUS_ATTR_NAME,
              type: 'string',
              value: ''
            }
          ]
        }
      ],
      updateAction: 'UPDATE'
    }

2 update requests by third party's services when updating information about an asynchronous request. These requests should have a payload such as the following one:

    {
      buttonId: ,
      serviceId: ,
      action: ,
      extra: ,
      result: 
    }

On the other hand, the Context Adapter queries (queryContext) the Orion Context Broker for service information using a payload such as the following one:

    {
      entities: [
        {
          id: ,
          type: 'service',
          isPattern: false,
          attributes: [
            'endpoint',
            'method',
            'authentication',
            'mapping',
            'timeout'
          ]
        }
      ]
    }

To which, the Orion Context Broker responds providing the concrete service information, if any:

    {
      contextElements: [
        {
          id: ,
          type: 'service',
          isPattern: false,
          attributes: [
            {
              name: 'endpoint',
              type: 'string',
              value: ''
            },
            {
              name: 'method',
              type: 'string',
              value: ''
            },
            {
              name: 'authentication',
              type: 'string',
              value: 
            },
            {
              name: 'mapping',
              type: 'string',
              value: ''
            },
            {
              name: 'timeout',
              type: 'string',
              value: ''
            }
          ]
        }
      ],
      statusCode: {
        code: '200',
        reasonPhrase: 'OK'
      }
    }

Top

## Dependencies The Context Adapter component is a Node.js application which depends on certain Node.js modules as stated in the project.json file.

Top

## Installation The Context Adapter can be installed in two ways: using the RPM or cloning the Github repository.

Cloning the Github Repository

1. Clone the repository:

 git clone https://github.com/telefonicaid/context-adapter.git 

2. Get into the directory where the Context Adapter repository has been cloned:

 cd context-adapter/ 

3. Install the Node.js modules and dependencies:

 npm install 

The Context Adapter component server is ready to be started.

Using the RPM

The project contains a script for generating an RPM that can be installed in Red Hat 6.5 compatible Linux distributions. The RPM depends on Node.js 0.10 version, so EPEL repositories are advisable.

In order to create the RPM, execute the following script, inside the /rpm folder:

create-rpm.sh -v <versionNumber> -r <releaseNumber>

Once the RPM is generated, it can be installed using the following command:

yum localinstall --nogpg <nameOfTheRPM>.rpm

Top

##Running the Context Adapter

1. To run the Context Adapter component, just execute:

 npm start 

The Context Adapter component provides the user with 2 mechanisms to configure the component to the concrete needs of the user:

• Environment variables, which can be set assigning values to them or using the context-adapter_default.conf file if a packaged version of the Context Adapter component is used.
• The config.js located at the root of the Context Adapter component code, a JSON formatted file including the configuration properties.

It is important to note that environment variables, if set, take precedence over the properties defined in the config.js file.

The script accepts the following parameters as environment variables:

• CA_HOST: The host where the Context Adapter server will be started. Optional. Default value: "localhost".
• CA_PUBLIC_HOST: The public host or IP where the Context Adapter server will be listening. Default value: "127.0.0.1".
• CA_PORT: The port where the Context Adapter server will be listening. Optional. Default value: "9999".
• CA_PATH: The path to add to the routes where the Context Broker is attending requests. Optional. Default value: "/v1".
• LOGOPS_LEVEL: The logging level of the messages. Messages with a level equal or superior to this will be logged. Accepted values are: "debug", "info", "warn" and "error". Optional. Default value: "info".
• PROOF_OF_LIFE_INTERVAL: The time in seconds between proof of life logging messages informing that the server is up and running normally. Default value: "60".
• DEFAULT_SERVICE: The service to be used if not sent by the Orion Context Broker in the requests. Optional. Default value: "blackbutton".
• DEFAULT_SERVICE_PATH: The service path to be used if not sent by the Orion Context Broker in the requests. Optional. Default value: "/".
• CB_HOST: The host where the Orion Context Broker is running. Optional. Default value: "localhost".
• CB_PORT: The port where the Orion Context Broker is listening. Optional. Default value: "1026".
• CB_PATH: The path to add to the routes where the Orion Context Broker is attending requests. Optional. Default value: "/v1".

For example, to start the Context Adapter and make it listen on port 7777, use:

As already mentioned, all this configuration parameters can also be adjusted using the config.js file whose contents are self-explanatory.

It is important to note that the Context Adapter component uses the logops module. For more information about how to further configure it, please visit https://www.npmjs.com/package/logops.

Top

## Test coverage The Context Adapter component source code includes a set of tests to validate the correct functioning of the whole set of capabilities exposed by the component. This set includes:

• Attending synchronous operation requests
• Attending asynchronous operation requests
• Attending third party's service updates

Running the tests

1. To run the tests, just execute:

 make test 

Take into consideration that the tests can be run using distint configurations using environment variables or properly setting the config.js file.

Top

##How to contribute

Would you like to contribute to the project? This is how you can do it:

1. Fork this repository clicking on the "Fork" button on the upper-right area of the page.
2. Clone your just forked repository:

git clone https://github.com/your-github-username/context-adapter.git

3. Add the main Context Adapter repository as a remote to your forked repository (use any name for your remote repository, it does not have to be context-adapter, although we will use it in the next steps):

git remote add context-adapter https://github.com/telefonicaid/context-adapter.git

4. Synchronize the develop branch in your forked repository with the develop branch in the main Context Adapter repository:
   
   (step 4.1, just in case you were not in the develop branch yet)

   git checkout develop

   (step 4.2)

   git fetch context-adapter

   (step 4.3)

   git rebase context-adapter/develop

5. Create a new local branch for your new code (currently we use the prefixes: feature/ for new features, task/ for maintenance and documentation issues and bug/ for bugs):

git checkout -b feature/some-new-feature

6. Include your changes and create the corresponding commits.
7. To assure that your code will land nicely, repeat steps 4.2 and 4.3 from your feature/some-new-feature branch to synchronize it with the latest code which may have landed in the develop branch of the main context-adapter repository during your implementation.
8. Push your code to your forked repository hosted in Github:

git push origin feature/some-new-feature

9. Launch a new pull request from your forked repository to the develop branch of the main Context Adapter repository. You may find some active pull requests available at https://github.com/telefonicaid/context-adapter/pulls.
10. Assign the pull request to any of the main Context Adapter developers (currently, @gtorodelvalle or @dmoranj) for review.
11. After the review process is successfully completed, your code will land into the develop branch of the main Context Adapter repository. Congratulations!!!

For additional contributions, just repeat these steps from step 4 on.

Top

##Additional development documentation

Project build

The project is managed using Grunt Task Runner.

For a list of available task, type

grunt --help

The following sections show the available options in detail.

Testing

Mocha Test Runner + Chai Assertion Library + Sinon Spies, stubs.

The test environment is preconfigured to run BDD testing style with chai.expect and chai.should() available globally while executing tests, as well as the Sinon-Chai plugin.

Module mocking during testing can be done with proxyquire

To run tests, type

grunt test

Tests reports can be used together with Jenkins to monitor project quality metrics by means of TAP or XUnit plugins. To generate TAP report in report/test/unit_tests.tap, type

grunt test-report

Coding guidelines

jshint, gjslint

Uses provided .jshintrc and .gjslintrc flag files. The latter requires Python and its use can be disabled while creating the project skeleton with grunt-init. To check source code style, type

grunt lint

Checkstyle reports can be used together with Jenkins to monitor project quality metrics by means of Checkstyle and Violations plugins. To generate Checkstyle and JSLint reports under report/lint/, type

grunt lint-report

Continuous testing

Support for continuous testing by modifying a src file or a test. For continuous testing, type

grunt watch

Source Code documentation

dox-foundation

Generates HTML documentation under site/doc/. It can be used together with jenkins by means of DocLinks plugin. For compiling source code documentation, type

grunt doc

Code Coverage

Istanbul

Analizes the code coverage of your tests.

To generate an HTML coverage report under site/coverage/ and to print out a summary, type

# Use git-bash on Windows
grunt coverage

To generate a Cobertura report in report/coverage/cobertura-coverage.xml that can be used together with Jenkins to monitor project quality metrics by means of Cobertura plugin, type

# Use git-bash on Windows
grunt coverage-report

Code complexity

Plato

Analizes code complexity using Plato and stores the report under site/report/. It can be used together with jenkins by means of DocLinks plugin. For complexity report, type

grunt complexity

PLC

Update the contributors for the project

grunt contributors

Development environment

Initialize your environment with git hooks.

grunt init-dev-env 

We strongly suggest you to make an automatic execution of this task for every developer simply by adding the following lines to your package.json

{
  "scripts": {
     "postinstall": "grunt init-dev-env"
  }
}

Site generation

There is a grunt task to generate the GitHub pages of the project, publishing also coverage, complexity and JSDocs pages. In order to initialize the GitHub pages, use:

grunt init-pages

This will also create a site folder under the root of your repository. This site folder is detached from your repository's history, and associated to the gh-pages branch, created for publishing. This initialization action should be done only once in the project history. Once the site has been initialized, publish with the following command:

grunt site

This command will only work after the developer has executed init-dev-env (that's the goal that will create the detached site).

This command will also launch the coverage, doc and complexity task (see in the above sections).

##Contact

• Germán Toro del Valle ([email protected], @gtorodelvalle)
• Daniel Morán Jiménez ([email protected])

Top