The following is a guide for developers who wish to use OpenLegacy platform to modernize and integrate legacy applications into web and mobile environments.

Architecture Overview

OpenLegacy extends legacy systems using connectors. These connectors extract information and perform actions on the legacy platform.
The information gathered through connectors is transformed into a structured Java data object with methods and fields.

The Java object can be used by any Java application via OpenLegacy’s SDK or it can be further transformed into a web service, RESTful service or even a complete ready to use single page web application for mobile or web using a target accelerator template. Customized target accelerator templates can be used in order to produce a wide variety of API types.

Components

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 and default implementations of runtime components

openlegacy-web
Contains Web and Spring MVC related components.

openlegacy-web-resources
Contains DOJO JavaScript library and common icons

Related technologies

Usage of Spring
openlegacy-impl component contains the run-time implementation. It uses Spring as the application container to define all the legacy modernization components, and provides defaults beans: e.g: screensRegistry, screensRecognizer, sessionNavigator, and much more.

Each Java/Web application has a single Spring application context, and a single legacy connection provider.

Usage of AspectJ
OpenLegacy is using AspectJ quite frequently. The main reason is that AspectJ allows adding additional code to existing classes, without burdening you with all of the extra work.

The most straight-forward example is getters and setters. As OpenLegacy is mapping screens to classes, and Java fields to host fields, adding extra getter and setter to each field will result in a much harder class to maintain, as it would be much bigger. In addition, each field rename/delete/add requires you to deal with the getter and setter as well. OpenLegacy saves you this effort.

Our Eclipse plug-in adds a project builder to each OpenLegacy project, which recognizes changes in @ScreenEntity classes, and auto-generates the matching AspectJ file ([Class]_Aspect.aj). The file is hidden when using OpenLegacy Eclipse perspective.

This applies to many extras that OpenLegacy provides:

  • Host fields, snapshot (when adding @ScreenEntity(supportTerminalData=true) to the class.
  • Extra interface and properties (focusField)
  • Extra methods for special fields (@ScreenFieldValues) – getValues
  • and more in the future!

AspectJ is also used within OpenLegacy MVC web controller to generate default MVC URL mapping code.

If you wish to override the AspectJ code, just use the Eclipse refactor -> push-in feature, which knows to move code from AspectJ class into your working Java class.

Usage of Eclipse
OpenLegacy Eclipse projects are standard Eclipse Java/Web project. OpenLegacy uses M2Eclipse plug-in (Maven) to enable dependency management and out-of-the-box build abilities for your new Java/Web application.

Usage of Drools
Drools is a powerful rule engine which is able to perform complex analysis using a collection of rules. OpenLegacy uses Drools as a base for its analysis engine.

For each piece of analysis logic, OpenLegacy provides a default rule with parameters configured in Spring context. The rules execution results in a ScreenEntityDefinition instance for each unique analyzed snapshot, and a generator based on freemarker templates language.

Usage of Spring MVC
OpenLegacy uses Spring MVC as the default web framework, over OpenLegacy API. Spring MVC is one the leading java based frameworks. OpenLegacy also uses Spring Mobile with Spring MVC to support both mobile and browser devices in parallel.

Usage of DOJO
OpenLegacy uses DOJO as the default JavaScript framework, over within the Spring MVC based web framework. DOJO is one the leading JavaScript frameworks, and used for Ajax capabilities and widgets.

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.

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/

Configuration Overview

These files are the main configuration files of an OpenLegacy project.

  • src/main/resources/application.properties – Common application properties settings are defined and commented here. This property file is load by all types of the project spring context files.
  • src/main/resources/host.properties – Contains the host session connection settings. Loaded into the host connectivity beans.
  • src/main/resources/log4j.properties – Logging properties
  • src/main/resources/META-INF/spring/applicationContext.xml – Spring main application context file of the web project. Useful for customizing the project beans
  • src/main/webapp/WEB-INF/spring/webmvc-config.xml – Spring MVC main web application context file of the web project. Useful for customizing controllers, views and web resources settings (Need good Spring MVC knowledge)
  • src/main/resources/META-INF/spring/applicationContext-test.xml – Spring main JUnit application context of the project. Used in all OpenLegacy generated JUnit tests.
  • src/main/webapp/WEB-INF/spring/actions-mappings.xml – Keyboard mapping between keyboard keys (ENTER, F1, PAGEDOWN, etc) to host command ([enter], [pf1], [pgdown], etc).
  • src/main/resources/META-INF/spring/openlegacy-designtime-context.xml (available only after project right-click -> OpenLegacy -> Customize Analyzer rules) – Contains spring based configuration for trails analysis to API model. Allows to enable/disable all rules, add new rules and customize parameters for all rules
  • src/main/webapp/WEB-INF/web/views/views.xml / src/main/webapp/WEB-INF/web/views/views.xml – Defines mapping between logical view names (typically screen entities names) to jspx files view, including the parent template (extends attribute)
  • src/main/webapp/WEB-INF/web/templates/layouts.xml / src/main/webapp/WEB-INF/mobile/layouts.xml – Defines a layout for template names (e.g: menu, public, template, view, etc). Each template layout defines the structure of the page, and allows views defined in views.xml to use these template layouts.
Tools Overview

OpenLegacy provides great offline support by using Trail files. Trail files are XML based, which record incoming/outgoing session snapshots. To work in offline mode, the following Spring beans should be configured in the relevant Spring context file.

applicationContext.xml – for web server runtime
applicationContext-test.xml – for JUnit tests

The following bean configures a mock up connection to “demo_session.trail” – relative to a resource folder (/trails):

Code Snippet:

The following bean configures a mock terminal session. The reason for this extra configuration is that it serves as a state machine, which serves the application for the requested screen class (only TerminalSession is aware of the screen entity classes):

Code Snippet:

REST

OpenLegacy provides an out-of-the-box HTTP REST application.

This means that once you generate an OpenLegacy API into a newly creaed project of type openlegacy-rest-new, and the Web server starts, all screen entities classes are exposed as URLs which returns and consumes XML and JSON content.

Example:
Given that you have an screen API class: inventory.ItemsList

You can get it in XML format over http using the following URL:
http://localhost:8080/YourAppName/ItemsList

With Content-Type=”application/xml” and Accept=”application/xml” http header, the following XML will be returned:

Code Snippet:

With Content-Type=”application/json” and Accept=”application/json” http header, the following JSON content will be returned:

Code Snippet:

SPECIAL NOTES:

  • This example assumes login has been performed, and ItemsList API has @ScreenNavigation defined (how to access this screen)
  • The positionTo node represents the field ItemsList.positionTo in the Java model
  • The focusField node represents the field the focus is on
  • ItemListRows nodes represent a list of table rows
  • Paths nodes represent location of other entities and can be accessed using /ENTITY-NAME
  • Actions nodes represent possible actions on the screen and can be used for POST screen entity using /ENTITY-NAME?action=

Sending XML or JSON content

To perform a send operation, you’ll be required to send the child node “screenEntity” with new values within its child. Nodes.focusField can be populated as well.

The target URL should be /ENTITY-NAME?action= (as specified in the returns actions nodes). If no action is specified in the URL, ENTER key will be performed.

No response is returned beside HTTP status code 200 if OK, and HTTP status code 400 if not.

Additional URLs (all with XML or JSON specified headers):

  • “/” – will return the first screen of the application, typically login screen
  • “/logoff” – if you wish to logoff the host session
  • “/menu” – returns a menu of all application screens
Web customization

Customizing HTML emulation

OpenLegacy is shipped with built-in HTML emulation. It provides the ability to convert host screens to HTML automatically.

OpenLegacy is shipped with a set of Spring beans which, by fine tuning their properties, you can configure fonts, proportion, etc. from src/main/resource/application.properties.

Override the default HTML elements provider in applicationContext.xml to change color and back color. Color and back color are converted using color mapper which converts a host color (org.openlegacy.terminal.Color enum) to CSS style color. If the color/back color is the default, no color/back color is rendered for the web field, and it uses the default color.

Code Snippet:

Working with themes

OpenLegacy is shipped with a predefined set of themes which can give a professional look to your Web application. Themes are packed as JARs, and predefined themes are located in the OpenLegacy Maven repository.

To add a theme of your choice for your Web application, add the theme JAR definition to your project pom.xml:

Code Snippet:

You can add multiple themes definitions, and let the user pick one.

To configure the used theme, edit src/main/resources/web.properties.

Themes are set in InsertGlobalsInterceptor. Make sure it is configured in webmvc-config.xml.

If you have configured more thanone theme, you can let the end user switch between them using the JS function: changeTheme(‘cloud,night,red’). Refer to the MVC demo, “Theme” link.

The theme is used in template.jspx and public.jspx CSS imports.

OpenLegacy themes are relying on DOJO JS framework infrastructure.

Themes are read from JAR file according to the following definition in webmvc-config.xml:

Code Snippet:

If you wish to use a custom theme, you should remove this setting and create the new theme under src/main/webapps/themes.

Customizing CSS / logo

Once you pick a theme/s, you can apply your company logo into the theme. In css/project.css, add a reference to your company logo. Refer to MVC demo for an example.

project.css is also used to allow you to make small changes to the theme. If you need a brand new theme with a different look and feel, you should create a new theme. Follow our existing themes JAR structure.

Bidi support

Bidi support requires special handling. To enable Bidi support for OpenLegacy, the following needs to be configured:

Maven
OpenLegacy is using ICU, a full Bidi support component which can handle Bidi content conversion. OpenLegacy doesn’t automatically import its Maven artifact. You should add the following dependency to you project pom.xml (under “dependencies” node):

Code Snippet:

Configure code page
Configure the correct page (i.e. 424 for Hebrew) during project creation, or under host.properties.

HTML emulation
To support Bidi language, OpenLegacy breaks mixed content fields into a few tags. To enable this functionality, you should configure the following in applicationContext.xml:

Code Snippet:

Within trail files, fields are created with additional attribute: visualValue, which is used for various display/analyze purposes.

Using Bidi analyzer rules
OpenLegacy analyzer comes with a subset of right to left rules, as Bidi applications are of course displayed from right to left.

To enable OpenLegacy to use the right to left rules, configure OpenLegacy project preferences file (/.preferences) to DESIGNTIME_CONTEXT=rtl. This will convert OpenLegacy to use the subset of right to left rules instead the standard rules (e.g. form fields, menus).

This setting is also used for customizing the rules to determine what is the design time context file to copy (contains all rules and their parameters settings).

Converting Bidi content to class/field names
OpenLegacy provide a text translator component which can have various implementations.

To enable text translator, configure the following bean (id=”textTranslator”).

You should populate the chars as expected. Alternatively, it’s possible to implement org.openlegacy.designtime.analyzer.TextTranslator and implement using different approach (dictionary, online).

Code Snippet:

Known issues
Eclipse console doesn’t display Bidi content properly, as it displays logical content. Use session viewer to determine screen positions.

Working with data types

One of OpenLegacy’s strongest features is the ability to work with strong type classes for screens, and within these classes, be able to work with standard data types.

OpenLegacy analyzer recognizes the following data types (according to analyzer rules) and converts them to Java types within the screens classes. These types are used by OpenLegacy MVC framework as well to generate a matching widget.

  • String (default)
  • Integer – for fields containing numeric values. Widget – spinner
  • Date – Using @ScreenDateField annotation. Widget – calendar
  • Enum (generated enum with the screen class) – Widget – combobox
  • List – Represent host table rows. Widget – table
Customizing analyzer rules

OpenLegacy comes with a built-in analyzer which enables you to analyze recorded screens and convert them to meaningful strong type Java classes, while analyzing all host component into data types and/or Java annotations.

The analyzer rules are bundled within OpenLegacy Eclipse plug-in, which is part of openlegacy-designtime JAR. We understand that it’s impossible to have predefined rules that know how to analyze any host application on the planet, so we let you as a developer customize it at will.

To customize the analyzer, right click on the project, and select: OpenLegacy -> “Customize Analyzer rules…”

The resulting file, contains a list of rules and matching parameters for each analyzer rule. For most cases, changing the parameters is enough. The rules are based on JBoss Drools project (.drl files), the leading open-source rule engine. It is required to learn Drools in order to write your own rules. We embrace it. In addition, it is required to understand regular expression, as they are widely used within the rules.

Let’s take a simple example. You have window screen which its frame is:

******
* *
* *
******

In this case you can either modify identify-window rule parameters to the matching regex:

Code Snippet:

Or, you can replace an existing pattern, or add a new ruleParametersSet to apply this rule in addition to the other patterns.

(NOTE: At the time of writing, OpenLegacy has no graphical representation of host windows. It is used for API purposes for now).

Writing your own rules
OpenLegacy provides you the capability to add your own custom rules. A sample.drl is included within src/main/resource/rules. It is required to include it within the project customized openlegacy-designtime-context.xml (has a commented example).

You may follow existing rules to better understand how to write rules.

Customize code generation

OpenLegacy generates Java APIs, AspectJ, JUnit, Web controller and Web pages into your project.

Sometimes you may want to control the generated content, especially in large projects.

To customize the generated content, right click on the project, and select OpenLegacy -> “customize code templates…”. This will result in a templates directory which will be used from this point for any generated content.

The templates are bases on freemarker opensource project, a leading templating framework. The templates model is based on OpenLegacy designtime model properties.

Here is the list of APIs used by each template:

  • ScreenEntity.java.template (Response for generating screens API)- org.openlegacy.designtime.terminal.model.ScreenEnt ityDesigntimeDefinition
  • ScreenEntityMvcPage.jspx.template (used for generating web pages)

org.openlegacy.layout.PageDefinition

  • ScreenEntityMvcController.aj.template (used for controller Aspectj)

org.openlegacy.layout.PageDefinition

Glossary

Application context (org.springframework.context.ApplicationContext)
A spring application context holds all OpenLegacy components.

Annotation loader
An internal component which is responsible for loading annotations information into a screen entity definition, which are stored into screen entity registry.

Connection Provider (org.openlegacy.terminal.TerminalConnectionFactory )
A provider of a terminal connection which implements terminal connection, terminal field, terminal snapshot.

Page definition (org.openlegacy.layout.PageDefinition)
A page definition is created from a screen entity, and contains a page layout. Used in runtime for presenting pages from API, and in designtime for generating real Web pages.

Screen binder (org.openlegacy.EntityBinder)
An internal component which is response to convert information from a terminal snapshot/terminal send action to/from a screen entity. Handles all the various data types conversions.

Screen entity (org.openlegacy.annotations.screen.ScreenEntity)
A screen entity is a class marked with @ScreenEntity annotation. When working within an OpenLegacy project, a screen entity also gets automatically an interface of org.openlegacy.terminal.ScreenEntity, from auto generated aspect _Aspect.aj.
A screen entity represents a specific terminal screen, and contains metadata (via annotations) relevant to this screen, so it would have a friendly API.

Screen entity definition (org.openlegacy.terminal.definitions.ScreenEntityD efinition)
Contains all metadata information on a screen entity class: fields, tables, parts, actions, navigation, etc. Stored into screen entity registry.

Screen entities registry (org.openlegacy.terminal.services.ScreenEntitiesRe gistry)
A screen registry is a component which stores information about screen entities. Should be configured with package/s of screen entities and scans these package/s for screen entities/parts/tables when application context starts.

Screen part (org.openlegacy.annotations.screen.ScreenPart)
A screen part is a part of screen, typically as a static inner class. Marked with @ScreenPart. Useful for breaking a large screen into smaller fragments. A screen entity should contain a field of the type of the screen part.

Screen Recognizer (org.openlegacy.terminal.services.ScreensRecognize r)
A component responsible for identifying a given terminal snapshot as a screen entity. Default implementation is based on screen identification, but different implementation might be relevant (pattern based, external repository).

Screen table (org.openlegacy.annotations.screen.ScreenTable)
A screen table represents a list a row of a screen table. Marked with @ScreenTable. The containing screen entity should contain a field type List.

Terminal connection (org.openlegacy.terminal.TerminalConnection)
The underlying terminal connection implemented by a specific provider: TN5250J, H3270, etc. Terminal session is internally using a terminal connection for working with a terminal.

Terminal send action (org.openlegacy.terminal.TerminalSendAction)
A send action represents a list of modified fields, cursor and action to perform on a session.

Terminal session (org.openlegacy.terminal.TerminalSession)
A terminal session is a logical representation of a terminal session. Contains methods for receiving the current terminal snapshot, the currentscreen entity, requests a specific screen entity, and performs actions on the session (Enter, F keys).

Terminal snapshot (org.openlegacy.terminal.TerminalSnapshot)
A snapshot of a current state of a terminal session. Contains terminal rows, size, cursor, text. Each row contains terminal fields.

Glossary

Application context (org.springframework.context.ApplicationContext)
A spring application context holds all OpenLegacy components.

Annotation loader
An internal component which is responsible for loading annotations information into a screen entity definition, which are stored into screen entity registry.

Connection Provider (org.openlegacy.terminal.TerminalConnectionFactory )
A provider of a terminal connection which implements terminal connection, terminal field, terminal snapshot.

Page definition (org.openlegacy.layout.PageDefinition)
A page definition is created from a screen entity, and contains a page layout. Used in runtime for presenting pages from API, and in designtime for generating real Web pages.

Screen binder (org.openlegacy.EntityBinder)
An internal component which is response to convert information from a terminal snapshot/terminal send action to/from a screen entity. Handles all the various data types conversions.

Screen entity (org.openlegacy.annotations.screen.ScreenEntity)
A screen entity is a class marked with @ScreenEntity annotation. When working within an OpenLegacy project, a screen entity also gets automatically an interface of org.openlegacy.terminal.ScreenEntity, from auto generated aspect _Aspect.aj.
A screen entity represents a specific terminal screen, and contains metadata (via annotations) relevant to this screen, so it would have a friendly API.

Screen entity definition (org.openlegacy.terminal.definitions.ScreenEntityD efinition)
Contains all metadata information on a screen entity class: fields, tables, parts, actions, navigation, etc. Stored into screen entity registry.

Screen entities registry (org.openlegacy.terminal.services.ScreenEntitiesRe gistry)
A screen registry is a component which stores information about screen entities. Should be configured with package/s of screen entities and scans these package/s for screen entities/parts/tables when application context starts.

Screen part (org.openlegacy.annotations.screen.ScreenPart)
A screen part is a part of screen, typically as a static inner class. Marked with @ScreenPart. Useful for breaking a large screen into smaller fragments. A screen entity should contain a field of the type of the screen part.

Screen Recognizer (org.openlegacy.terminal.services.ScreensRecognize r)
A component responsible for identifying a given terminal snapshot as a screen entity. Default implementation is based on screen identification, but different implementation might be relevant (pattern based, external repository).

Screen table (org.openlegacy.annotations.screen.ScreenTable)
A screen table represents a list a row of a screen table. Marked with @ScreenTable. The containing screen entity should contain a field type List.

Terminal connection (org.openlegacy.terminal.TerminalConnection)
The underlying terminal connection implemented by a specific provider: TN5250J, H3270, etc. Terminal session is internally using a terminal connection for working with a terminal.

Terminal send action (org.openlegacy.terminal.TerminalSendAction)
A send action represents a list of modified fields, cursor and action to perform on a session.

Terminal session (org.openlegacy.terminal.TerminalSession)
A terminal session is a logical representation of a terminal session. Contains methods for receiving the current terminal snapshot, the currentscreen entity, requests a specific screen entity, and performs actions on the session (Enter, F keys).

Terminal snapshot (org.openlegacy.terminal.TerminalSnapshot)
A snapshot of a current state of a terminal session. Contains terminal rows, size, cursor, text. Each row contains terminal fields.

Customizing run-emulation

run-emulation is an eclipse launcher (based on Maven plug-in) which exist in every project, and provide an emulation access to the legacy application, mainly for session recording.

To run the emulation, right click on run-emulation.launch and select Run As -> run-emulation. Once it starts it run by default onhttp://localhost:1512, and will launch your FireFox browser to this address. It is based on Jetty web server.

The launcher is aware of the project configuration (spring context and host.properties), and provide additional properties all with defaults, which can be configured through Run As-> Run Configuration…
org.openlegacy.port=PORT TO START THE WEB SERVER
org.openlegacy.browser=PATH TO YOUR BROWSER
org.openlegacy.trail.path=PATH TO SAVE TRAIL FILES
org.openlegacy. context.file=PATH TO SPRING CONTEXT FILE