Skip to content
This repository has been archived by the owner on Feb 22, 2019. It is now read-only.

contributor_guide

Jump to bottom
Pavel Vlasov edited this page Nov 30, 2016 · 5 revisions

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 persistence of the object model. Similarity to the JavaScript event loop inspired scheduler, function and promise bundle groups which attempt to introduce 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
    • Bundles, 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, post presentations on SlideShare, or record YTube 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/presentation/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

The promise bundles were inspired by JavaScript promises, Kris Kowal's Q in particular. The goal of the bundles to provide a simple API for working with long-running asynchronous processes.

The basic flow should be as follows:

  • Deferred is created using DeferredFactory service. Each deferred has a unique ID which can be stored by clients for looking up deferred in the future.
  • Promise is obtained from the deferred and its then() method is used to add fulfill, reject and progress handlers.
  • At some future point of time PromiseManager service is used to look up the Deferred up by its id. Then the Deferred is either fulfilled, rejected, or notified about progress.
  • The promise library invokes respective handlers registered with then() invocation.

org.nasdanika.cdo.web bundle "gives" every object in a CDO repository a URL. What it means is that deferred's stored in the repository will automatically get an URL with a REST API and Web UI to obtain deferred's status, fulfill it, reject, or report progress.

One interesting consequence of this approach is that humans may be "invoked" in the same manner as services, e.g.:

  • A deferred is created.
  • Security domain is used to notify a user or a group of users about a work item (deferred). Depending on implementation it can be an e-mail notification or an item in user's in-application inbox or something else. In either case users are furnished with the deferred's URL.
  • A user navigates to the URL and uses the deferred's Web UI to fulfill or reject the deferred with appropriate data, e.g. collected with a web form or a wizard.
  • The system invokes deferred's handlers to continue processing.

The promise bundles are not fully implemented. Also separation of promise functionality into three bundles and the use of generics might be have to be reconsidered as too complex. Promise interfaces shall be moved to the org.nasdanika.cdo.promise bundle and generic types shall be replaced with getXXXType() methods, e.g. getFulfillmentType().

promise

org.nasdanika.promise bundle defines promise API - Deferred, Promise, DeferredFactory, and PromiseManager. The API is ECore/CDO agnostic.

promise.cdo

org.nasdanika.promise.cdo is a binding of promise interfaces to CDOTransactionContext.

cdo.promise

org.nasdanika.cdo.promise is a CDO implementation of promises.

provisioning

Currently org.nasdanika.provisioning contains a single component which allows to poll p2 repositories and automatically install features found in these repositories without server restart.

The following provisioning-related capabilities are expected to be added in the future:

  • Provisioning model to store a list of known repositories and installation history into a CDO repository.
  • Web UI and REST API to manage known repositories, install/uninstall features, and check for updates.

SCA

NFS features several SCA (Service Component Architecture) bundles. The bundles are not fully developed, they were created to capture the concept. org.nasdanika.cdo.sca is the only server runtime bundle. All bundles shall be moved to a separate repository.

cdo.sca

org.nasdanika.cdo.sca contains a runtime model defining components and wires.

The model is expected to be used in the following fashion:

  • Runtime model is generated from a desing model (see below), registered using an extension point and packaged into a bundle with supporting services/classes.
  • A bundle is deployed to a runtime environment.
  • A copy of a model instantiated, configured, stored in a CDO repository.
  • The instance is activated by invoking exported wires.

The idea is to provide service wiring/execution model similar to OSGi, but with component definitions stored in a CDO repositories, so multiple service configuration can coexist at the same time, and support of asynchronous execution using deferreds and promises.

For example, an sca model may be created for an automated build and deployment with manual steps, e.g. approval, deployment, manual testing.

cdo.sca.edit

org.nasdanika.cdo.sca.edit provides edit support for org.nasdanika.cdo.sca bundle.

Diagram editor

The following bundles constitute an SCA diagram editor:

service-stopper

org.nasdanika.service-stopper is used to run Eclipse applications as Windows services. More information is here - https://github.com/Nasdanika/server/wiki/windows_service

Story

User story model is used to capture user stories. Story models are bundled with the application and used by the documentation system. The documentation system provides the means of visualizing story models as UML diagrams and linking results of automated UI tests to story model elements, providing traceability from requirements to tests.

Tools

org.nasdanika.tools.design is a helper bundle for Sirius diagram editing.

transaction

org.nasdanika.transaciton bundle features a component exposing JTA TransactionManager and UserTransaction services. The component is powered by Atomikos Transaction Essentials.

web

org.nasdanika.web is the foundation for NFS web functionality. It defines annotations, interfaces, and extension points to build route-based HTTP request processing. It also contains routing servlet class, HttpServletRequestContext implementation classes and DispatchingRoute class, which can dispatch HTTP requests to annotated methods.

WebTest

WebTest is a Web UI testing framework. It is capable of capturing screenshots and storing test results into a ECore/CDO model. The model can then be deployed with the application and the documentation system displays test results and links them to user stories.

WebTest bundles shall be moved to their own repository.

Workspace Wizard

org.nasdanika.workspace.wizard provides two wizards:

  • NFS Workspace Wizard - creates a set of projects constituting NFS application.
  • Modeling Workspace Wizard - creates a modeling project (Maven/Tycho enabled), parent, feature, repository, and aggregator projects.

Experience gained while working on the Workspace Wizard was one of the driving forces which led to creation of the "Code Generation" group of projects (see below). Once the code generation projects are implemented, the Workspace Wizard will be moved to the code generation repository and refactored to use the code generation model instead of low level API's it facades.

Related projects

Code Generation (Codegen)

Repository - https://github.com/Nasdanika/codegen.

This group of projects is under development. It will feature the following solutions:

  • Codegen
    • ECore model which facades low level code generation API's - creation of projects, natures, files, folders, compilation units, merging of changes, ...
    • Editor to create template models and generate code from those models.
  • Codegen.ecore - a model and an editor which allow to generate code by selecting a subset of Ecore model elements and then choosing generation target(s). Generation targets are contributed through extensions. For example, Java classes to generate Web UI primitives (panels, tables, forms, dialogs, java script) may be generated for a particular user story by selecting domain object and their features participating in that particular story.
  • Codegen.ecore.targets.web - Codegen.ecore targets for generating Web UI routes and helper classes/methods leveraging the HTML bundle. Once available, it will be used to generate Web UI for the Bank web application (see below).
  • More targets will be created as needed, e.g. a target to generate Android UI for selected domain model elements.

Bank

Bank web application is a reference implementation which demonstrates capabilities of NFS. Its development is explained in the Server side Java Development for Innovators online book (see below).

Server side Java Development for Innovators

Online book walking readers through NFS-base development process.

Information Center

Information center is an NFS application which features only the documentation system and has NFS models and bunldes with documentation installed. It is not currently functional and it needs adjustments in configuration.

Task Manager and UI tests

Task Manager is a simple Single Page Application built with the HTML bundle to be a test target for automated UI tests. UI Tests automated UI tests of the Task Manager application built with WebTest framework.

Home

API Docs

Clone this wiki locally