OpenLegacy Blog

OpenLegacy modules API

Share this:

Typically a legacy session API is very "boring". You perform a get screen action to retrieve the current screen and data from it, and perform send key to perform some action on the current screen, and give or take this is all you can do.

OpenLegacy breaks this paradigm with a new approach. The basic functionality is available, but enrich the session with more modular functionality, and even let advanced user to enrich the session API.

The following modules are available out of the box in OpenLegacy:
Login, Menu, Navigation, Messages, Globals, Table, Trail

Accessing each module API is simply available via:
TerminalSession.getModule(<ModuleClass>.class).<me thod name>

This simplifies the usage of the session to a more cleaner API.

Most modules have default configuration within Spring application context. Open openlegacy-basic-context.xml within openlegacy-impl JAR to review the configuration, and override the bean definition in your project applicationContext.xml.
Let's review the modules and how to use them. Most modules are used within our demo application.

Login module simplifies the process of log-in to the host application. The Login module is using metadata from a screen entity class marked with:
- @ScreenEntity(screenType=LoginEntity.class)
- User/password/error fields marked with @ScreenField(fieldType=UserField.class), @ScreenField(fieldType=PasswordField.class), @ScreenField(fieldType=ErrorField.class).

By defining the above annotation in a screen entity class, OpenLegacy API enables executing:

[code]terminalSession.getModule(Login.class).login("<user>","<password>"); [/code]

If the error field is not empty, and login screen not passed, a LoginException is thrown.

Menu module exposes the application menus tree to a tree structure for usage within web and mobile applications. The criteria for being a node in the tree is as follows:
- A screen entity class is marked with - @ScreenEntity(screenType=MenuEntity.class)
- A menu parent menu is determine by @ScreenNavigation annotation
- The menu root is a menu entity without @ScreenNavigation annotation
- Screen which are accessible via a menu screen entity (@ScreenNavigation) are leafs in the menu tree
- Screens which requires parameters @ScreenNavigation(requiresParameter=true) are not leafs.

To invoke the API:

[code]// root of the menus
MenuItem menuItem = terminalSession.getModule(Menu.class).getMenuTree()
menuItem.getMenuItems(); [/code]

Table module provide methods for handling collecting tables from multple screens, and drill-down in table by ID.
Collecting host tables is typically not a trivial task, and this module handles table collection smoothly.

The module also supports drill-down by ID. At least one of the table columns (@ScreenColumn) must be marked as key (key=true).
To configure custom table drill-down behavior add to an existing table class (marked with @ScreenTable), also @ScreenTableDrilldown annotation, and define custom implementation of: drilldownPerformer, rowFinder rowComparator, tableScroller, rowSelector or stopConditions.
Each has a well defined interface which can be implemented to control drill-down

[code]// collect
List<ItemsListRecord> items = terminalSession.getModule(Table.class).collectAll(ItemsList.class,ItemsListRecord.class);

// drill-down
ItemDetails1 itemDetails1 = terminalSession.getModule(Table.class).drillDown(ItemDetails1.class,
TerminalDrilldownActions.enter("2"), 2000); [/code]

Navigation module expose information on the current screen entity path, which is very useful for creating breadcrumb for web navigation.

[code]// root of the menus
MenuItem menuItem = terminalSession.getModule(Navigation.class).getPaths()
menuItem.getMenuItems(); [/code]

One of the most disruptive host behavior when performing modernization, and trying to control the host workflow, is messages screen which may pop-up at any point.
Messages module handles it smartly. Any messages screen is being read, and skipped, while still providing the captures messages for later usage.
The relevant messages screen must be marked with @ScreenEntity(screenType=MessagesEntity.class), and the relevant field within the entity class must be marked with @ScreenField(fieldType=MessageField.class, rectangle=).
If the field is a multiple row field, you can rectangle=true, and row, column, endRow, endColumn.

[code]List<String> messages = terminalSession.getModule(Messages.class).getMessages();
if (messages.size() > 0){
// show the messages
} [/code]

Trail module is responsible for storing the session history snapshots in memory. By default each session stores the last 2 session snapshots. In development mode, all snapshots are saved.
The bean trailWriter can be used to dump the in memory trail to file.

[code]SessionTrail trail = terminalSession.getModule(Trail.class).getSessionTrail()
trailWriter.write(trail, new FileOutputStream("<path>"); [/code]

Globals module save the entities fields marked as @ScreenField(fieldType=GlobalField.class, ...)
to be accessible in a global manner. Very useful for cross session properties such as: system name, device name, etc, which you wish to display across a web application header for example.

[code]Map<String, Object> globals = terminalSession.getModule(Globals.class).getGlobals()
String systemName = globals.get("systemName");[/code]

If you wish to implement a custom module, implement TerminalSessionModule or extend TerminalSessionModuleAdapter, copy the bean abstractTerminalSession from openlegacy-basic-context.xml to your project applicationContext.xml / applicationContext-test.xml, and add the new class under "modules" propery. Use same technique to custom the modules properties. 

Tags: Development, APIs, Tips & Tricks

Share this: