The following is a guide for developers working on OpenLegacy platform source code and interested in contributing code, fixing a bug, add new screen analysis rules (analyzer), add new protocols and adapters, adding template project, add a theme, or add a new feature.

You may find additional useful information in the developer guide.

We encourage you to fork us on github and send us pull requests. Pull request guide: https://help.github.com/articles/using-pull-requests

Initial Environment Setup
Development environment installation guide

Prerequisites:
JDK 1.6 / 1.7 Installed (or available as a directory). Spring tool suite – STS (Spring’s eclipse) from: http://www.springsource.org/downloads/sts

OR

Eclipse 3.7 / 4.2 including Maven plug-in, AspectJ plug-in and EGit plug-in.

Tested with Eclipse 3.7 / STS 3.0/3.1

A complete Eclipse bundle, including OpenLegacy and all the necessary plug-ins, is available at: http://eclipse.openlegacy.org/downloads/

  1. For STS – start springsource/sts-/sts.exe. OR start your Eclipse
  2. Select a clean workspace folder.
  3. Select file-> “import” -> Git -> “Project from git”, select “Uri”
  4. Click “Clone”
    STS 3.X – Copy the following URL https://github.com/openlegacy/openlegacy.git to URI field
    Provide your github user and password.
  5. Select the working branch (master). Click “Next”.
  6. Select a local git folder. Click “Next”, and “Finish”. Wait for the import to complete.
  7. Once complete, select “Next” and “Import existing projects”.
    Select all projects.
  8. Perform project -> clean…, “Clean all project”, in case of errors
    Execute the test suite: OpenLegacyRuntimeSuite (CTRL+SHIFT+T to find it) to run all OpenLegacy runtime unitests.
    NOTE: On Windows, you may need to allow Windows firewall.
    Designtime project is using Drools rule engine. It is recommended to install the plug-in from: http://download.jboss.org/jbosstools…o/soa-tooling/ (enables DRL & BPMN rules file editing).
    To install the plug-in, select “Help” -> “Install New Software”, click “Add…” and add the above URL.
    Select “JBoss SOA development” -> JBoss Drools Core.
    Uncheck “Contact All update sites”.
  9. Import code style preferences. Select Import -> preferences, and select the file from openlegacy root project -> openlegacy-prefs.epf
  10. For running OpenLegacy as a Web application, import:
    – /openlegacy/openlegacy-templates/openlegacy-mvc-sample project (web demo application)
    (URL is http://localhost:8080/openlegacy-mvc-sample)
    OR
    – /openlegacy/openlegacy-templates/openlegacy-mvc-new project (new empty web application)
    (URL is http://localhost:8080/openlegacy-mvc-new/emulation)
    Right click on “run-application.launch”, and click run as-> “run-application”.
    Verify the launcher is using JDK 1.6 in case of an error.
    Open your browser to the chosen application above mentioned URL.
Projects Overview

openlegacy-api
Contains mostly interfaces and annotation for runtime purposes, which enables defining screens API classes using OpenLegacy annotations, session API, modules API, entities registry API and connectors API.

openlegacy-utils
Utility classes for common tasks.

openlegacy-impl
Main implementation of OpenLegacy runtime API. Contains common implementation of runtime components

openlegacy-web
Contains Web and Spring MVC related components.

openlegacy-designtime
Contains all designtime components (non UI): snapshots analyzer, code generators, create project, etc.

openlegacy-ide-eclipse
Containes OpenLegacy eclipse plug-in code: Create project, Generate API / Web pages, project builder, project nature, etc.

openlegacy-ide-eclipse-feature
An Eclipse feature project for installing into Eclipse as a feature.

openlegacy-ide-eclipse-updatesite
A container for Eclipse update site for installing/updating OpenLegacy plug-in from URL.

Openlegacy-providers
OpenLegacy Providers are the layer which enables various Legacy API provider to integrate with OpenLegacy framework & tools. OpenLegacy is shipped with two open source providers and one commercial provider (requires manual JAR installing and license). The provider host properties is configured via src/main/resources/host.properties file within the project. Providers projects are not available by default when importing projects for the first time.

In order to import a legacy provider project, use Import -> existing projects into workspace, and select <git_clone_dir>/openlegacy/openlegacy-providers/<openlegacy-provider_name>.

openlegacy-applinx
Applinx (commercial product) provider from Software AG provides the ability to connect various legacy systems (AS/400, MainFrame, NATUX, BS2000, Hitachi, Fujitsu, Unisys). It can be used by OpenLegacy as a connector for these types of hosts, and provide a supported connector for your Legacy system.

http://www.softwareag.com/corporate/…ew/default.asp

Follow the instructions in the readme file within the project in order to use Applinx JAR files and license. OpenLegacy can use Applinx as an embedded connector, or can connect to a standalone Applinx server. Applinx settings is done via the applinx.properties file.

openlegacy-tn5250j
TN5250J is a popular open source project which provides a connector for connecting to AS/400 (TN5250). The provider code is implementing OpenLegacy provider API, using TN5250J jar.
TN5250 jars is provided via OpenLegacy maven repository. http://tn5250j.sourceforge.net/

openlegacy-h3270
H3270 is a popular open source project which provides a connector for connecting to Mainframe (TN3270). The provider code is implementing OpenLegacy provider API. H3270 source code is embedded within the provider code (org.h3270 package). http://h3270.sourceforge.net/

OpenLegacy Templates

OpenLegacy templates are a variety of web/java eclipse projects for new/demo applications based on OpenLegacy.

Template projects are not available by default when importing projects for the first time. In order to import a template project, use Import -> existing projects into workspace, and select <git_clone_dir>/openlegacy/openlegacy-templates/<openlegacy-provider_name>.

openlegacy-mvc-new
An OpenLegacy empty web and mobile application based on Spring MVC and Dojo frameworks. Provides an HTML based emulator (/emulation in the URL), which allows you to access your legacy system from within a browser.

Once recorded, a trail of screens-generated API should be generated into it, and ready to use Web pages will be generated based on the API (see Getting Started).

openlegacy-mvc-vanilla
An OpenLegacy automatically-analyzed Web application based on Spring MVC and Dojo frameworks. Provides an example of OpenLegacy capabilities based on an Inventory toys Legacy application. It demonstrate OpenLegacy automatic API and web capabilities.

openlegacy-mvc-sample
An OpenLegacy sample Web and mobile application based on Spring MVC and Dojo frameworks. Provides a customized combined web and mobile demo application based on an inventory toys legacy application. It demonstrates OpenLegacy’s various Web capabilities and the ability to extend the Legacy application with new UI component and business logic functionalities.

openlegacy-rest-new
An OpenLegacy empty REST enablement project, designed to expose screen entities to external applications in XML or JSON format. For further information, read more about this template in the OpenLegacy REST guide.

Development Guidelines

Coding Standards
OpenLegacy contains a ready eclipse preference file, which apply our coding standards. Make sure you import the file /openlegacy/eclipse-openlegacy-prefs.epf into your workspace
(File->Import->Preferences)

Testing
Most OpenLegacy functionality is covered by JUnit tests. Most tests rely on Spring JUnit framework, and uses a common/specific spring xml context file. Specific context files typically points to specific beans and resources which the tests check. Every commit to github master is tested under a continuous integration server at: http://build.openlegacy.org/hudson

Working With GIT
OpenLegacy is stored at github.com and developers should use EGit eclipse plug-in (built into Eclipse STS, the recommended IDE).

EGit provides a “git staging” view which should be used to determine what files are about to be committed. Drag the files from the “Unstaged changes” to “Staged changes”.

Each commit should be covered by a ticket at: http://github.com/openlegacy/openlegacy/issues/ (We plan to migrate to JIRA later on).

GIT uses a push/pull from github.com, so make sure you pull changes before a commit, and push your changes afterwards. Commits are not sent to github automatically (if this is the first time you are using git source control).

Feature branches should be created when working on a task which requires a few working days/ large number of commits, or incomplete work sharing with other developers.
(right click on project -> Team -> Switch to -> New Branch…)

Only once a task is completed should it be merged to master branch, and push to github.
It is OK to push to a feature branch to github. (right click on project -> Team -> push to upstream). Note that only completed tasks should be merged to master branch.

Commits must refer to a ticket in github (JIRA later): refers #XXX … or fixes #XXX …
Commit comment should reflect the technical solution of the problem.

GIT Tips & Tricks
If you are working in Windows and using EGit within eclipse STS, you may find the following commands required, as white spaces tend to cause white space diffs, and show a large number of file changes:
http://stackoverflow.com/questions/8…ile-as-changed

Build
All OpenLegacy code is built using Maven. The development environment contains many launchers (*.launch files) which is used for tasks not covered by the IDE.

When working on OpenLegacy Web application (openlegacy-mvc-new, etc.), and modifying OL Java projects, it is required to run “Run As -> Maven install” to build and install a JAR of the relevant project into Maven local repository.

You may want to use “Run as -> Maven build…”, Goal: install, skip test -> checked, to disable local tests execution.

OpenLegacy resources:
Maven repository: