Kunagi Developer Guide
Kunagi uses Git for version control. You can read up about Git in Pro Git or on the Git User's Manual.
Setting up the development environment
Get ilarkesto and kunagi projects from GitHub
Kunagi is hosted on the social coding platform GitHub, so you can download the sources from there:
If you plan to contribute, you should get an GitHub account and clone the projects like described in the Collaborating section.
Building and running Kunagi from Eclipse
Download dependencies by executing the update-libs.bsh script in the ilarkesto directory. Windows users have to download ilarkesto-lib.zip manualy and extract its contents into the ilarkesto project directory.
Open ilarkesto and kunagi as projects in Eclipse.
Start Kunagi with Eclipse by running ScrumGwtApplication.linux.launch or ScrumGwtApplication.windows.launch from the kunagi project.
To compile and run unit tests, install the TestNG Eclipse plugin.
Building a .war file
If you want to test your changes as a real web application, you need to install Ant and execute it in the kunagi project directory:
ant webapp
This will create kunagi.war in the build directory. You can put this file into the webapps directory of your web application server. We recommend Tomcat 6.
Collaborating
Clone projects from GitHub
Create a GitHub account.
On GitHub, create your personal forks of ilarkesto and kunagi.
Install Git on your computer:
sudo apt-get install git-gui
Windows users can follow this tutorial.
Set username and email in git:
git config --global user.name "Full Name" git config --global user.email "email@gmail.com"
Make sure to add a public key to your Git account following the instruction on generating SSH keys if you don't already have one. Now you can create local clones of ilarkesto and kunagi in your workspace directory:
git clone https://github.com/your-github-name/ilarkesto.git git clone https://github.com/your-github-name/kunagi.git
Commiting changes
Commit changes to your local git repository:
git add . git commit -am "my commit comment"
Publishing changes
Push changes to your remote repository on GitHub:
git push
Inform us about your changes using the Pull Request button on GitHub, so we can, should we agree that it makes sense in the overall concept of Kunagi, integrate your patch. Issues with Kunagi can be discussed using the issue system on Kunagi website, while discussions about created patches may be held in the commit comments on GitHub.
To keep your copy of Kunagi up to date, pull changes from our repository to yours:
git pull git://github.com/Kunagi/kunagi.git master
More infos here: Forking a project on GitHub
Architecture Overview
Kunagi is a web application, implemented in Java, based on the Google Web Toolkit (GWT). Therefore it is separated into two runtime environments, the Java server and the GWT/JavaScript client.
GWT Client
The client sources are Java files in src/main/java/scrum/client/.... These are compiled to JavaScript by GWT. The entry point is ScrumGwtApplication. Every single user runs his own instance of the client.
Java Server
The server source files are placed in src/main/java/scrum/server/.... The entry point is ScrumWebApplication.
Client-Server communication
The client communicates with the server through asynchronous service calls. Every service call returns the same DataTransferObject to the client, which contains data for the client. It can even contain data, which has nothing to do with the service call. This could be entities, which were modified by other clients.
The server manages all active clients with Conversation objects. These conversations contain the DataTransferObject. New data can be put into the transfer object at any time. It gets transferred to the client with the next service call.
Service calls are implemented in the ScrumServiceImpl class and run on the server.
See Model Driven Architechture for creating service calls.
Entities
Entities are persistent objects. For every entity, there are two implementations. One on the server and one on the client. They always have the same class name, only the package differs.
When entity properties are changed on the client, the framework triggers the ChangePropertiesServiceCall immediately. This service call sends the changes to the server, which updates the server instance and sends the changes to all other active conversations/clients.
On the server, on startup, all entities are loaded from XML files into memory. When entity properties are changed, the framework saves the modified entities back to the XML files.
Model Driven Architecture
Some source files are generated from models. These are entities and its DAOs (Data Access Objects), service calls, events and client components. The generated Java files are checked in to SCM for convinience into src/generated/java/....
The models are coded in Java in the ScrumModelApplication class or modeled in the GUI modeller ScrumModeller and saved in model.csv. Executing ScrumModeller and clicking Save & Generate generates the sources.