contributor_guide

Contributor Guide

This article provides an overview the Nasdanika Foundation Server and different ways to contribute. It also provides short descriptions of bundles, bundle groups and features constituting the product, as well as overviews of related projects.

Vision

The vision of Nasdanika Foundation Server (NFS) to be an enabler of fast development of server-side applications which utilize complex domain models and are built leveraging Domain-Driven Design principles.

The basic pattern when developing with the NFS is as follows:

Obtain CDOTransactionContextProvider OSGi service.
Obtain additional services as needed. NFS provides annotations to inject services into method arguments.
Obtain a lock from CDOTransaction if necessary.
Work with the application domain objects and OSGi services in the context of the transaction.
Commit or rollback the transaction.

On the one hand this pattern closely follows the DDD approach, on the other hand it is similar to the JavaScript event loop approach (and JFace Data Binding Realms) with the additional benefit of transparent persitence of the object model. Similarity to the JavaScript event loop inspired scheduler, function and promise bundle groups which attempt to bring simple yet very powerful asynchronous JavaScript programming models into the Java world and bring the meaning of asynchronicity to the next level where asynchronous operations may survive JVM restarts or be executed in a distributed environment.

Core principles

Declarative development - higher level abstraction, focus on the business problem instead of low-level plumbing:
- ECore and Java metadata and annotations.
- Helper models.
- Code generation.
- Transparent persistence provided by CDO.
- Contextual execution.
Automated build:
- Maven/Tycho.
- Jenkins/CircleCI or similar solutions.
- Docker images.
Self-describing applications - the documentation system is part of the application
- Bunldes, components, services and their relationships. Visualizations - auto-generated UML diagrams.
- ECore models documentation with visualizations by auto-generated UML diagrams.
- Help topics.

Overview

Nasdanika Foundation Server is a collection of bundles which facilitate building of server (particularly Web) OSGi/Equinox-based applications which use Eclipse EMF CDO for application domain objects persistence and utilize rich metadata provided by CDO/ECore and Java language as well as helper models and code generators to build such applications in a declarative fashion which isolates the developer from low-level details and thus allows to focus on the business problem.

Nasdanika Foundation Server based applications are self-contained Eclipse products which can also be packaged as Docker images.

Nasdanika Workspace Wizard generates initial plug-in projects for the application with Maven nature and pom.xml files, ready to be built with Maven/Tycho. The wizard also generates a Docker file. This allows developers to quickly set up automated builds with tools like Jenkins or build hosting providers like CircleCI.

How to contribute

There are multiple ways how you can contribute to Nasdanika Foundation Server development:

Get the word out

If you use Nasdanika Foundation Server and can show that its value comparing to other approaches, you can let the world know about your experience by writing blog posts or articles.

You can also build examples, write tutorials, and record videos about different aspects of the Nasdanika Foundation Server, e.g. how to build a WebSocket based web application.

Once you publish blog/article/example/tutorial/video, share a link with us by creating a issue, and we will publish the link on the Wiki.

Report bugs

If you find a bug, please create an issue. It is highly recommended to provide code to reproduce the bug! If you provide the code in a form of JUnit test, its even better as it may be later incorporated into the suite of automated tests.

Code contributions

There are also several ways to contribute to the codebase. As an open source project we use the Fork and Pull Model. You can find more information about collaborative development at GitHub in this article - Collaborating with issues and pull requests.

When you contribute code, please make sure that the changes are clearly identifiable. In particular, avoid making non-functional changes in the code which you do not touch, e.g. auto-formatting of the entire compilation unit.

Write automated tests

At this point of time testing of Nasdanika bundles is manual. You can contribute by writing automated tests. In OSGi/Equinox tests are placed in fragment projects. You can use Core Tests as a template.

More information - Tycho Eclipse Test Plugin.

Write JavaDoc

We strive to make code self-descriptive, but if you find a place where it is not self-descriptive enough you can provide clarifications. Also, if you've written an example, a tutorial, or an article about a particular class or package, you can add links and/or code fragments to the JavaDoc.

Please keep in mind that Nasdanika Foundation Server uses Pegdown Doclet and therefore JavaDocs shall be written in markdown.

Fix a bug

If you find a bug and know how to fix it - go for it!

Implement new functionality

Sections below provide brief descriptions of bundles constituting Nasdanika Foundation Server, including bundle roadmaps. You may pick an item from a roadmap and implement it.

Bundles

CDO

org.nasdanika.cdo[.*] bundles provide classes and components for working with CDO objects and repositories.

cdo

org.nasdanika.cdo bundle contains core NFS classes and compoents for working with CDO such as:

Transaction and view contexts
Session provider, repository provider, and server components

cdo.boxing

org.nasdanika.cdo.boxing contains a model for "boxing" Java objects, collections and primitives into CDO objects so they can be stored into a CDO reposiroty without having to create additional models.

This bundle was created to provide support for scheduler, function, and promise bundles. The bundle has been only lightly tested and hasn't yet been used yet in an application.

cdo.h2

org.nasdanika.cdo.h2 provides H2 CDO repository component.

cdo.scheduler

org.nasdanika.cdo.scheduler provides an ECore model and a component implementing a scheduler service which stores tasks in a CDO repository. Tasks can be CDO objects or boxed Java objects implementing org.nasdanika.cdo.CDOTransactionContextCommand.

Scheduler was created to support promises. Similarly to the boxing bundle, the scheduler bundle has been only lightly tested and hasn't been used yet in an application.

CDO Security

CDO security is a group of bundles - model, edit, and editor - for implementing application level security.

The model bundle is used at runtime and design time. The model's root class is ProtectionDomain. The root of the application domain model typically implements ProtectionDomain or LoginPasswordProtectionDomain. CDO Web classes provide means of mapping HTTP request principal to the CDO principal. Routing methods annotations allow to delaratively define access restrictions.

cdo.web

org.nasdanika.cdo.web provides routing servlets which combine Web and CDO contexts. It also provides a set of EObject/CDO routes for dispatching HTTP requests to CDO repository object, as well as object path resolvers which compute an HTTP URL of a repository object.

cdo.web.doc

org.nasdanika.cdo.web.doc is the NFS documentation system. It has originally been created for generating/hosting documentation of ECore/CDO models and this is why it is under the cdo umbrella. Since then the bundle has been extended to host help topics and generate documentation for bundles, components, services, story models, and web test results (work in progress).

One interesting idea related to web test results documentation is automated generation of video clips from a series of screenshots captured by the test harness. The video can be silent or feature voice generated by some TTS engine from screenshot comments. This is envisioned to be implemented in the following fashion:

org.nasdanika.cdo.web.doc defines an service interface which generates video from a collection/array/iterator of screenshot images (BufferedImage) and associated comments.
Some other bundle implements the interface.
- Videos can be generated using Flagstone SWF, its OSGi wrapper is available in http://www.nasdanika.org/maven-osgi repository.
- The video bundle defines a service interface for generating voice from text. The interface shall produce javax.sound.sampled.AudioInputStream for text and, optionally, a locale.
  - Some bundle implements the voice generation interface. The bundle shall provide configuration of which voice to use for a particular locale. A preliminary research has identified Mary TTS as a good open-source candidate for voice generation. The research has also shown that it is better to run MaryTTS as a server, and use MaryTTS client interface in the voice generation bundle.
- https://sourceforge.net/p/jcapture-applet/code/HEAD/tree/trunk/src/com/hammurapi/jcapture/ code can be used as an example and/or adapted to compose SWF video from screenshots and generated audio.
The application defines OSGi components providing video and voice generation services.
The documentation route component defines a video generation service reference. If video generating service is present in the system, the documentation route would display a video tab in the test documentation page.
The video generation component defines a text-to-speech service references. If a text-to-speech service is present in the system, the generated video would contain sound. Otherwise it'd be silent.

If you a interested in contributing to the documentation system you can implement video and/or tts components. These components may reside in their own repository(ies) and NFS-based application will reference that repository in addition to NFS and Eclipse repositories.

cdo.xa

org.nasdanika.cdo.xa provides JTA - CDO XA bridge allowing CDO transactions to participate in JTA transactions. This functionality may eventually become part of CDO - https://bugs.eclipse.org/bugs/show_bug.cgi?id=409756. Until it does, it is available in this bundle.

core

org.nasdanika.core provides core classes used by other bundles. These classes focus on type conversion, contextual execution and declarative binding of OSGi service to method parameters.

core.tests

Testing fragment for the core bundle.

equinox.feature

Equinox feature contains Equinox bundles used by NFS-base applications.

Function

Function bundles provide JavaScript-like functions which can be stored in a CDO repository and executed at some later point of time, e.g. by a scheduler. These bundles were created to support promise-based programming, but can be used on their own. The bundles have been only lightly tested.

function

org.nasdanika.function defines Function interface which extends org.nasdanika.core.Command and as such can be executed in a context with parameters. Function also supports binding of parameters.

function.cdo

org.nasdanika.function.cdo provides generic parameter binding of Function to CDOTransactionContext.

cdo.function

org.nasdanika.function.cdo provides a CDO model which contains implementations of CDOTransactionContextFunction, i.e. functions which can be stored in a CDO repository and executed in the context of a CDO transaction, e.g. by a scheduler.

html

org.nasdanika.html bundle provides Java bindings for HTML, Bootstrap, AngularJS, KnockoutJS and FontAwesome. It allows a Java developer to build modern Web UI's by writing Java code and using coarse-grained "building blocks" such as "Bootstrap panel" instead of low-level HTML elements.

This bundle is used by the documentation bundle and a number of NFS-based applications. The bundle is independent of other NFS bundles and it will be moved into its own repository.

One of maintenance activities required by this bundle is to keep the API's in sync with the libraries it facades, Bootstrap and FontAwesome in particular.

osgi.model

org.nasdanika.osgi.model provides an ECore/CDO model of OSGi bundles, services, and components. It is used by the documentation system to generate documentation and visualizations of the OSGi environment.

Promise

!!! Work In Progress !!!

promise

promise.cdo

cdo.promise

provisioning

provisioning.feature
repository

SCA

cdo.sca

cdo.sca.edit

sca

sca.design

sca.edit

sca.editor

sca.feature

server.jetty.feature

service-stopper

Story

story
story.edit
story.editor
story.feature

Tools ?

tools.design
tools.feature

transaction

web

WebTest

webtest
webtest.feature
webtest.model
webtest.model.routes
webtest.performance
webtest.performance.feature