athen core concepts

Overview into the project folder structure of ATHEN

ATHEN is an application based on eclipse 4 RCP, which means every a couple of things:

Every project that is a part of ATHEN is a so called "plugin" project. A plugin itself can be compared to an artifact in the maven terminology
Every plugin project has its own classloader. The plugin project (from now on i will just call it project) is configured using the MANIFEST.MF located in the META-INF folder of every project. That means if you want to have new dependencies you need to add them via the MANIFEST to your classpath.
Every project also has a pom.xml, it contains required meta information for the maven-tycho builder. It is important to note, that you cannot specify any dependencies using this pom.xml, instead you need to add it to your MANIFEST.MF. Such a .pom barely has any information in it:

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>de.uniwue.mk.athen</groupId>
    <artifactId>de.uniwue.mk.athen.root</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <relativePath>../..</relativePath>
  </parent>
  <groupId>de.uniwue.mk.athen</groupId>
  <artifactId>de.uniwue.mk.kall.ie.ieview</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>eclipse-plugin</packaging>
</project>

It merely contains the GAV attributes, every maven project requires, as well as parent project information.

All the user created code (aka the plugin projects) are stored in a folder bundles right below the root of ATHEN (which is the project de.uniwue.mk.athen). Besides this folder, there are two further folder, one is called features and the other one is called releng.

The folder features

Inside this folder is a single project that wraps the ATHEN feature. If you dont know what a feature is, you can think of it as one of the two explanations:

A feature is a collection of plugin projects
A feature is the analogon to a maven group

In its current state, ATHEN only deploys a single feature with all projects stored in it. If you create a new project for ATHEN you should remember to add it to this feature definition.

The feature itself is a neat thing, since eclipse 4 rcp applications come with a possibility to update themselfes from an online repository. Since ATHEN is a desktop application, having an update site eases up the process of getting access to a new version.

The folder releng (Release Engineering)

The projects located in this folder are responsible for a couple of things:

The configuration of ATHEN!
The product definition (in the end this produces the executable)
the target definition (which contains all online dependencies to build ATHEN)
The project responsible for building the p2-update repository
The documentation of ATHEN

The following picture shows the current situation of this folder:

ATHENs layout

If you want to work on ATHEN you should understand the terminology that is introduced with ATHEN. Below there is a picure of the layout which appears after you start ATHEN:

As you can see there are four different parts of ATHEN:

The Project Explorer
The Editor
The Views
The Analyzer

This section walks through the four different parts of ATHEN and explains their purpose. But first, the core ideas of their common behaviour needs to be addressed.

Eclispe 4 RCP -Parts

Every different implementation of an editor, a view or an anayzer is inherently something called a part (in the code those come as MPart instances). Every part contains different code for their own purpose. A part can be visible or hidden, which gives an easy way to define something called perspectives (yes a perspective is just a bunch of visible parts). All those parts are located within a window - The main application window.

Parts can communicate using the eclipse 4 RCP bus, which is called the EventBroker. Using this bus system, parts can communicate and notify other parts whenever necessary. The broker can be considered a global variable which exists once for the whole application. Every class which has access to the broker can send events using its send method and can register for events using the subscribe() und unsubscribe() methods.

Parts in ATHEN

If you start ATHEN, you usually end up in the annotation perspective. In this perspective you will always see the previously shown layout of the parts, with only the project explorer being visible. Now it is time to further address the purpose of those parts.

The Project Explorer

In the beginning, the project explorer shows which projects are available in the workspace. This is its main purpose. Its other main feature is to listen to the filesystem for changes and immediately reflect them in the explorer (which means you can just change the filesystem and the application remains up-to-date)

Currently the project explorer allows the user to perform delete, copy and paste options from the operating system to the project explorer and vice versa.

The Project Explorer allows to open a document, which is caused by either double clicking or pressing Enter on a single document. This causes an event to be fired which notifiys the current editor, that a document should be opened. A fitting reader is searched and the final document (in the form of a CAS) is handed over to the editor (by the use of the EventBroker)

The Editor

The Editor is the heart of ATHENs Userinterface. After the project explorer requested that a document should be opened, the editor starts to display the document. From now on, the editors main purpose is to keep its listening Views and Analyzer parts up to date. Which means, that after the editor performed internal initializations, it immediately notifies all listening parts for a document change, this cause a change in the corresponding parts.

The Views

The views, which is every part which is located to the right of the editor reflect the current document which is opened in the editor. They represent the end of the event chain as they usually only consume events and do not notify other parts. Views define the behaviour of the editor, which could mean that the behaviour of a double click, or a key stroke could differ complete, when different views are active.

Views of a perspective are all located in a so called partstack. Only the view which is currently focused communicates with the editor.

The Analyzer

The Analyzer parts are the last group of interest. They are actually very similar to the views. However they should not reflect the complete document (which is currently) opened but a mere snippet of it. As an example let us use the SelectionAnalyzer, which shows all annotations that are located below the current position of the caret of the editor. As soon as the caret changes, the analyzer updates its content. Analyzer parts can communicate with the editor, similarly to the view parts. This allows e.g. that the user can delete annotations from an analyzer.