Title Page

UI developers guide
BASE24-eps™
1 Document Preface........................................................................................................................... 1-8

2 Introduction................................................................................................................................... 2-15
2.1 Intended Audience............................................................................................................. 2-15
2.2 Conventions Used by this Document ................................................................................ 2-15
2.3 Overview of BASE24-eps UIs ........................................................................................... 2-15
2.3.1 DesktopApplication Extension and Related Classes ........................................................ 2-16
2.3.2 ApplicationFrame Extension and Related Classes ........................................................... 2-16
2.3.3 Properties and Config Files............................................................................................... 2-17
2.4 Training UI ....................................................................................................................... 2-17
2.5 Training UI Screen Samples ............................................................................................. 2-18
2.6 Development Steps ............................................................................................................ 2-19

3 Determining Standard, Version Independent, or Custom............................................................. 3-21

4 The Package Name ....................................................................................................................... 4-22

5 Security ID and ES_ESF.properties.............................................................................................. 5-23

5.1 Security ID ........................................................................................................................ 5-23
5.2 ES_ESF.properties............................................................................................................ 5-23

6 ESData Definition......................................................................................................................... 6-30

6.1 Server Messages................................................................................................................ 6-30
6.2 Server Context................................................................................................................... 6-33
6.3 Field Validate Errors........................................................................................................ 6-33
6.4 All Elements ...................................................................................................................... 6-34
6.4.1 Visual Component Mapping ............................................................................................. 6-34
6.4.2 Data Validation ................................................................................................................. 6-34
6.4.3 Non Visual Element Hold Area ........................................................................................ 6-35
6.5 Screen Data....................................................................................................................... 6-35
6.5.1 Visual Component Mapping ............................................................................................. 6-36
6.5.2 Data Validation ................................................................................................................. 6-36
6.5.3 Non Visual Components ................................................................................................... 6-36
6.6 Class es.shared.ESData .................................................................................................... 6-36
6.7 ESDataConfig.cfg ............................................................................................................. 6-38

7 Determine the Application Name and Create Applications.lst..................................................... 7-39

8 Determine the UI Constant(s) ....................................................................................................... 8-40

1-2
9 UI Layout ...................................................................................................................................... 9-41
9.1 Overview ........................................................................................................................... 9-41
9.2 Primary Layout ................................................................................................................. 9-41
9.3 Key Panel .......................................................................................................................... 9-42
9.4 General Information Tab .................................................................................................. 9-43

10 UI Property File .......................................................................................................................... 10-45

10.1 Overview ......................................................................................................................... 10-45
10.2 UI Actions ....................................................................................................................... 10-45
10.3 Navigation Localization.................................................................................................. 10-47
10.3.1 List of UIs ....................................................................................................................... 10-47
10.3.2 Security ID ...................................................................................................................... 10-48
10.3.3 Root Branch .................................................................................................................... 10-48
10.3.4 Tree Branch(es)............................................................................................................... 10-49
10.3.5 Mnemonics...................................................................................................................... 10-49
10.3.6 Navigation Weight Properties......................................................................................... 10-50
10.4 Help Properties............................................................................................................... 10-51
10.4.1 General Help Properties.................................................................................................. 10-51
10.4.2 Component Help Properties............................................................................................ 10-52
10.4.3 Table Column Help Properties........................................................................................ 10-53
10.5 Tying a ManagedList to a Combo Box Component ........................................................ 10-53
10.6 UI Title ............................................................................................................................ 10-55
10.7 Tabbed Pane Titles ......................................................................................................... 10-55
10.8 Visual Component Labels ............................................................................................... 10-56
10.9 Hyperlink Labels............................................................................................................. 10-56
10.10 Localized Lists ............................................................................................................ 10-57
10.11 Table Column Headers ............................................................................................... 10-58
10.12 Key Components ......................................................................................................... 10-59
10.13 Text for the Delete Action ........................................................................................... 10-59
10.14 OLTP Warmboot Hyperlink Properties ...................................................................... 10-60
10.15 Institution Rendering .................................................................................................. 10-60
10.16 Summary of UI Property File Keywords .................................................................... 10-61

11 Table Property File ..................................................................................................................... 11-66

11.1 Overview ......................................................................................................................... 11-66
11.2 Table Parameters............................................................................................................ 11-66
11.3 Supported Editors ........................................................................................................... 11-67

1-3
 11.4 Supported Editor Optional Keywords............................................................................. 11-67
11.5 Column Parameters ........................................................................................................ 11-68
11.6 Visual Table Configuration............................................................................................. 11-71
11.6.1 Visual Table Parameters ................................................................................................. 11-71
11.6.2 Visual Column Parameters ............................................................................................. 11-72
11.6.3 Visual Table Configuration Example ............................................................................. 11-73
11.7 Data Types ...................................................................................................................... 11-74
11.8 Assigning a List Model.................................................................................................... 11-74
11.9 Differences for ManagedList Versus ManagedStringList .............................................. 11-75
11.10 Using a Custom Cell Editor/Renderer........................................................................ 11-76
11.11 Overriding isCellEditable........................................................................................... 11-76
11.12 Hidden Columns.......................................................................................................... 11-77

12 UI Constants................................................................................................................................ 12-79

13 UIInstanceManager Extension.................................................................................................... 13-80

14 ManagedList Extension .............................................................................................................. 14-81

15 ESDesktopApplication Extension............................................................................................... 15-84

15.1 Introduction..................................................................................................................... 15-84
15.2 Extending ESDesktopApplication ................................................................................... 15-85
15.2.1 Overview......................................................................................................................... 15-85
15.2.2 Class Variables................................................................................................................ 15-85
15.2.3 Constructor...................................................................................................................... 15-85
15.2.4 Implementation of Abstract Methods ............................................................................. 15-86
15.3 Implementing getList....................................................................................................... 15-87
15.4 getNavigationTree Implementation ................................................................................ 15-90
15.5 Frequently Overriden Methods....................................................................................... 15-90
15.5.1 Specify the Name of the ESData Definition File............................................................ 15-90

16 ESComponentBuilder Extension ................................................................................................ 16-92

16.1 Introduction..................................................................................................................... 16-92
16.2 Constructor ..................................................................................................................... 16-92
16.3 Profile Combo Box Actions............................................................................................. 16-93
16.4 GenericETableMgr Events.............................................................................................. 16-94
16.5 Frequently Overridden Methods..................................................................................... 16-95
16.5.1 Creating EComponent Instances..................................................................................... 16-95
16.5.2 Creating a GenericETableMgr Extension....................................................................... 16-95

1-4
 16.6 Convenience Methods ..................................................................................................... 16-95
16.6.1 EComponent Conveniences ............................................................................................ 16-95
16.6.2 Conveniences Related to SelectionComboBox .............................................................. 16-96
16.6.3 Conveniences Related to GenericETableMgr................................................................ 16-96
16.6.4 Non-EComponent Gets................................................................................................... 16-97
16.6.5 Higher Level Hierarchy Convenience Gets .................................................................... 16-97
16.7 Multiple Layout Files...................................................................................................... 16-97

17 AbstractESApplicationFrameForTable Extension...................................................................... 17-99

17.1 Introduction..................................................................................................................... 17-99
17.2 A Basic Implementation ................................................................................................ 17-100
17.2.1 Constructor and Initialize Method Requirements ......................................................... 17-100
17.2.2 Mapping the Visual Components.................................................................................. 17-102
17.2.3 Abstract Methods .......................................................................................................... 17-102
17.3 Other Frequently Overridden Methods ........................................................................ 17-103
17.3.1 notifyInitializeComplete ............................................................................................... 17-104
17.3.2 getPermissionsTaskID .................................................................................................. 17-104
17.3.3 activatedWithContext ................................................................................................... 17-104
17.4 Override Conveniences................................................................................................. 17-105
17.4.1 Formatting the Request ESData.................................................................................... 17-105
17.4.2 Affecting the Visual Components at Response Time ................................................... 17-106
17.4.3 Verification of Visual Components .............................................................................. 17-106
17.4.4 Resetting Components .................................................................................................. 17-107
17.4.5 Updating ManagedList Objects .................................................................................... 17-107
17.5 Actions........................................................................................................................... 17-108
17.6 Message Types .............................................................................................................. 17-109
17.7 Server Context............................................................................................................... 17-110
17.8 Threads and Messaging ................................................................................................ 17-111
17.9 Additional Features ...................................................................................................... 17-111
17.9.1 Class Data Variable enableOnView.............................................................................. 17-111
17.9.2 Class Data Variable keyChangesPartOfUnsaved ......................................................... 17-111
17.9.3 Class Data Variable useConditionalCanDelete ............................................................ 17-112
17.9.4 Class Data Variable negativeViewIsInsert ................................................................... 17-112
17.9.5 Class Data Variable insertRowAlwaysEnabled............................................................ 17-112
17.10 Summary of Changes from Previous Version of AbstractESApplicationFrame....... 17-112

18 GenericETableMgr ................................................................................................................... 18-114

18.1 Introduction................................................................................................................... 18-114
18.2 Creating a GenericETableMgr Extension .................................................................... 18-114
18.3 Creating a GenericETableESDataManager Extension ................................................ 18-115
18.3.1 Creating the Extension.................................................................................................. 18-115

1-5
 18.3.2 Override Conveniences................................................................................................. 18-115
18.4 Creating a GenericETableModel Extension................................................................. 18-116
18.5 GenericETableListener Interface.................................................................................. 18-116
18.6 Convenience Methods ................................................................................................... 18-116
18.7 Overview of the Classes ................................................................................................ 18-118

19 Miscellaneous Classes .............................................................................................................. 19-122

19.1 SelectionComboBox ...................................................................................................... 19-122
19.2 SelectionTextField......................................................................................................... 19-122
19.3 RefreshComboBoxModel .............................................................................................. 19-123

20 Source Code for the Training UI .............................................................................................. 20-124

21 Using XMLTestHost................................................................................................................. 21-125

22 FAQs ......................................................................................................................................... 22-126

22.1 Adding an Action to the Right-Click Menu ................................................................... 22-126
22.2 Security Considerations for a Custom UI..................................................................... 22-127
22.3 Considerations for a Table UI where Details are Outside of the Table....................... 22-128
22.4 Adding a list item to a Combo Box that uses a ManagedList ....................................... 22-132
22.5 Overriding the Default for a Table Cell ESpinner........................................................ 22-133
22.6 Using an ESFindDialog................................................................................................ 22-134
22.6.1 Layout Components ...................................................................................................... 22-135
22.6.2 FindDialog Properties ................................................................................................... 22-135
22.6.3 Action Tied to the EButton. .......................................................................................... 22-136
22.6.4 Implementing receiveSelectedValues........................................................................... 22-138
22.6.5 Implementing loadFindDialogRequest ......................................................................... 22-139
22.7 Dynamically Assigning the Column Editor/Renderer................................................... 22-139
22.7.1 Overview....................................................................................................................... 22-139
22.7.2 Example ........................................................................................................................ 22-140

23 Utility Classes ........................................................................................................................... 23-143

23.1 Overview of the Utility Classes..................................................................................... 23-143
23.2 Using the Debug Mechanism ........................................................................................ 23-143
23.2.1 Overview....................................................................................................................... 23-143
23.2.2 Add the Debug Logic.................................................................................................... 23-143
23.2.3 Activate the Debug Point .............................................................................................. 23-144
23.2.4 Example of the Output .................................................................................................. 23-145

24 Version Independent Interface Considerations......................................................................... 24-146

1-6
 24.1 Overview of Version Independent Changes.................................................................. 24-146
24.2 Common UI Property File Changes ............................................................................. 24-146
24.2.1 CommonCodeValues.properties changes ..................................................................... 24-146
24.2.2 UISecurityIDs.properties changes ................................................................................ 24-147
24.3 UI Application Jars....................................................................................................... 24-148
24.3.1 Change to existing UI Application Jars ........................................................................ 24-148
24.3.2 New UI Application Jars............................................................................................... 24-148
24.3.3 UI Application Packages Deleted (No Longer Product)............................................... 24-149
24.4 Version Independent …\if\es\desktop\ packages........................................................... 24-149
24.4.1 UI Client Desktop Packages moved to \if\es\desktop\ Directory ................................. 24-149
24.5 User Security Permission Load Script Considerations ................................................ 24-150
24.6 Synergy/CM ui/UIServer Version Independent Check-In Release Value .................... 24-150

25 Support for Multi-byte .............................................................................................................. 25-152

25.1 Introduction................................................................................................................... 25-152
25.2 Checking For Multi-byte Support ................................................................................. 25-152
25.3 Configuring the Multi-byte Message Encoding ............................................................ 25-153
25.4 Multi-byte Message Support – Client ........................................................................... 25-153
25.5 Multi-byte Message Support – Java Server .................................................................. 25-154
25.6 Controlling the Display of Multi-byte Components...................................................... 25-154
25.6.1 Controlling the display of Multi-byte Tables................................................................ 25-154
25.6.2 Controlling the display of Multi-byte Panels................................................................ 25-155
25.6.3 Controlling the display of Multi-byte Fields ................................................................ 25-155
25.7 Multi-byte Constant Values........................................................................................... 25-156
25.8 Bidirectional Multi-Byte Component Support .............................................................. 25-156
25.9 Font Support for Multi-byte Components ..................................................................... 25-158
25.10 Multi-byte Length Validation.................................................................................... 25-160
25.11 Multi-byte Utilities Support ...................................................................................... 25-161

1-7
1 Document Preface

Document Control

Version Author Major Changes Date

Distributed
1.00 B. Prewitt Initial Version March 4, 2003
1.01 B. Prewitt Added the table parameter March 13, 2003
TABLE_MAX_ROWS_ALLOWED

Added a short writeup in the ESDesktopConstants

section talking about adding a custom constant.

Added the table parameter

COLUMN_CLEAR_ROW_SUPPORTED

Added the supported edit/renderer eSpinner.

1.02 B. Prewitt Added the supported editor/renderer April 21, 2003

eComboBoxListData.

Added the supported editor/renderer eTextFieldZoom.

Added the new AbstractESApplicationFrame class

variable negativeViewIsInsert.

Created a new sub section as part of section 11 to

discuss the differences between tying a table cell editor
to a ManagedList versus a ManagedStringList.

Created a new sub section as part of Section 11 to

describe how to override the default implementation of
isCellEditable.

Added a new Section to the end of the document to

describe how to setup to use XMLTestHost.

Updated the sub section in Section 18 named Overview

of the Classes.

1.03 B.Prewitt Updated Section 10.9 to document a hyperlink with July 30, 2003
multiple context.

1-8
Version Author Major Changes Date
Distributed
Updated Sections 10.5 and 11.6 to show the how to
configure the use of the (none) option with a combo box
list.

Pulled all of the Custom UI Considerations and

Conventions out of the text boxes. Find doesn’t work
for text within text boses.

Renamed all of the classes and files from TrainingUI to

Training. This is in line with our standard. Also
changed the name of the table from Sample Table to
Acquirer Table.

Removed the source code. The training package is now

checked into Synergy.

Added Sections 22.1, 22.2, 22.3, 22.4, and 22.5.

1.04 B.Prewitt Updated Section 22.1 to say the accelerator doesn’t November 7,
work for the right-click unless the action is also on the 2003
menu bar.

Updated Section 11.2 to include the new

sendAllRowsWithRequestData parameter.

Removed the implementation of getUIInstanceManager.

This implementation is no longer a requirement as of
Release 04.1.

Updated Section 17.2.1 to reflect the fact that the UI

class no longer contains the implementation for
setPermissions. This has been moved to
AbstractESApplicationFrame. This also resulted in the
implementation of new method getPermissionsTaskID
(Section 17.3.2).

Changes to reflect the change from using method

getEditorText to using EComponent method getValue.
1.05 B.Prewitt Added Section 22.6 to describe how to use an November 13,
ESFindDialog. 2003

Added additional detail to Section 10.4 to better describe

the help properties needed for components and for table

1-9
Version Author Major Changes Date
Distributed
columns.
1.06 B.Prewitt Added Section 22.7 to describe how to dynamically January 20, 2004
change a table column editor.
1.07 B. Prewitt Updates related to Release 4.4. table enhancments. This November 9,
affected Sections 11.2, 11.3, 11.4, and 11.5. 2004

Added Section 10.13 to summarize the UI property file

keywords.

Added Section 23 to document the es.desktop utility

classes.
1.08 B. Prewitt Release 5.2 items November 19,
2004
- New actions Copy Row/Paste Row.
- Change TrainingUI to conform to the coding
standards.
- New ESComponentBuilder convenience
methods.
- New GenericETableMgr convenience methods.
- New Section 23 to document the es.desktop
utiltity classes.
1.09 B. Prewitt Made the changes specified by the Publications Tech December 15,
Edit. 2004
1.10 D. Wright Release 5.2 items Februrary 15,
2005
Added the following sections for the visual table
enhancements utilized by the new Application
Management Uis :

11.2 Table Parameters

11.6 Visual Table Configuration
11.6.1 Visual Table Parameters
11.6.2 Visual Column Parameters
11.6.3 Visual Table Configuration Example

1.11 B. Prewitt More Release 5.2 items. April 14, 2005

Support for column defaults. Affected the following

sections :

11.2 Table Parameters

11.5 Column Parameters

Support for configuring an automatic view request in

1-10
Version Author Major Changes Date
Distributed
response to a defined response.

10.13 Summary of UI Property File Keywords

1.12 B. Prewitt Version 05.4 items. November 21,

2005
- Section 17.5 updated for the Insert Row Before
action.
- Section 11.12 added to document hidden
columns.
- Section 10.2 updated to reflect that the properties
are no longer needed for commonly used actions.
- Section 15.4 updated to document that method
getNavigationAppID no longer must be defined
by the extension.
- Section 10.13 updated for the following
properties :
o ESFindDialog properties.
o List Retrieval properties.
o clearOnNewEntry
o errorStatusOnNewEntry
o noSelect
- Section 15.3 updated to reflect the super class
implementation of method getList.
- Sections 11.4 and 11.5 updated for ‘order’
support for tables.
1.13 B. Prewitt Version 06.2 items. April 9, 2006
- Changes related to moving the location of the
ESData definition and changes related to no
longer needing the ESDataConfig.cfg entries.
o Section 6 updated.
o Added Section 15.5.
- Added Section 23.2 to document ESUtilities
debug methods.
- Removed the contents of Section 21.
- Section 10.13 added to document the ability to
override the text used for the delete action.
- Section 10.14 added to document the OLTP
Warmboot UI hyperlink properties.
- Section 10.15 (keyword summary) updated to
document the new keywords :
o noSelect
o conditionalNoSelect
o uiNoSelect

1-11
Version Author Major Changes Date
Distributed
o wbootDataSource
o deleteTextOverride
- Section 11.2 updated to document the new Table
Parameter constants:
o TABLE_ACTIONS_PROPERTY
_PREFIX
o TABLE_HAS_TOOLBAR
- Section 11.3 updated to document the new editor
EDITOR_RENDERER_ETIMESTAMPLABEL.
- Section 17.5 updated to document the new
oltpRebuild action.
1.14 D. Trusty- Updated document to include changes related to the
Prewitt Version Independent Interfaces enhancement. With the
BASE24-eps 06.2 Version, Interchange mandates will
only need to be applied once per BASE24-eps Release,
e.g., BASE24-eps Release 1.0 and the changes will be
available in all BASE24-eps Versions for that Release,
e.g., BASE24-eps 06.2, 06.4, 07.4, etc. Sections
impacted by Version Independent Interfaces are:
- Requirement to use the new method and no
longer use the ESDataConfig.cfg for any UI’s
developed as Version Independent.
o Section 6 updated.
o Section 15.5 updated.
- Changes related to the properties moved from the
existing CommonCodeValues and UISecurityIDs
property files to the Version Independent
Interface extensions named
CommonCodeValues+INTF and
UISecurityIDs+INTF.
o Section 2.3.3 updated.
o Section 10.3.2 updated.
o Section 10.4.2 updated.
o Section 10.4.3 updated.
o Section 16.2 updated.
- General Version Independent Considerations
o Section 3 updated.
o Section 7 updated.
o Section 8 updated.
o Added Section 24.

1.15 B. Prewitt Updates to reflect that ESDesktopConstants and June 26, 2007
ESAppIDs are no longer required. Renamed Sections 7
and 8 accordingly.

1-12
Version Author Major Changes Date
Distributed

Removed most of the Section on ESDataConfig.cfg

since we no longer update this file.

Added a subsection to Section 10.3 to discuss navigation

weight properties.

Documented the requiredApp and moduleID properties

in Section 10.15.

Added a new section to Section 16 to document the

ability to specify multiple layout files.
1.16 B. Prewitt Documented the following new table properties: February 8, 2008

- TableParameters.useAcctTypeBehavior
- TableParameters.useAcctTypeRenderer
- TableParameters.procCodeKey
- Column.columnGroupHeaderLocaleKey
- Column.columnGroupHeaderPropertyFile

Documented the following new column editors:

- eDataLabelInstitution
- eDataLabelInstrumentType

Added a new subsection to Section 10 to document the

super class institution rendering behavior and properties.

Documented the following new UI property key words:

- useInstNameRenderer
- distinguishUnconfiguredListName
- requiredEPSVersionLevel

Added a new subsection to Section 5 to document

ES_ESF.properties.

1.17 B. Prewitt Changes related to the updated CSM methodology. May 16, 2008
1.18 B. Prewitt Added a section to cover Applications.lst. May 23, 2008
1.19 D. Wright Added the following 09.2 items Sept. 21, 2009
Haughney - Section 25 for Multi-byte Support
- Modification to Section 10.4 to note that the
helpset home property (helpTopics.helpID)
should be a link to the CommonUI property file

1-13
Version Author Major Changes Date
Distributed
entry

1-14
2 Introduction

2.1 Intended Audience

This document describes how to create a BASE24-eps UI. The intended audience is developers creating
BASE24-eps UIs. The following is assumed concerning the audience:

Working knowledge of Java.

Working knowledge of the UIF.

2.2 Conventions Used by this Document

This document uses the following conventions.

- Bold is used for the following:

o Class names.
o Method names.
o Property file names.
o Data source names.
o Emphasize selected text.
- Italics is used for the following:
o Section names within this document.
o Titles of other documents.
o Labels defined on the Training UI, used to identify visual components.
- Hyperlinks are used throughout to provide quick links to related sections of the document.
- Class names that aren’t otherwise specified, belong to package es.desktop.

2.3 Overview of BASE24-eps UIs

At a high level, a BASE24-eps UI (like any other UI derived from the UIF) consists of the following:

- A class that extends framework.desktop.DestkopApplication

- A class that extends framework.desktop.ApplicationFrame
- A properties file containing localization properties for things like the UI title and the labels for the
UI components.

DesktopApplication and ApplicationFrame extensions have been developed to create reusable

implementations for behavior that is needed for every BASE24-eps UI. These are discussed in the
following sections, as well as an elaboration on what properties and config files are used by a BASE24-
eps UI.

2-15
2.3.1 DesktopApplication Extension and Related Classes

A DesktopApplication extension and several helper classes have been created to deal with the
BASE24-eps UI requirements related to the DesktopApplication.

- ManagedList was created to deal with the specifics of a shared list. Many of the BASE24-eps UIs
maintain a list of data (e.g., list of Action Code Profiles, Acquirer Trans Allowed Profiles).
ManagedList was created to allow these lists to be easily shared by several UIs, but updated only
by the owning UI DesktopApplication.
- UIInstanceManager’s main job is to help a DesktopApplication with the opening of a UI.
Context and UI to UI associations are primarily what UIInstanceManager deals with. These are
factors when one UI opens/activates another as a result of a user clicking a hyperlink.
- ESDesktopApplication is the DesktopApplication extension. It is the owner of the
ManagedList instances that are updated by the UIs that it owns. It is also the owner of the
UIInstanceManager instances (one instance per UI owned by the ESDesktopApplication).

2.3.2 ApplicationFrame Extension and Related Classes

AbstractESApplicationFrameForTable is an ApplicationFrame extension that provides reusable

implementation for the following behaviors:

- Defining user actions and default implementations for common BASE24-eps UI user actions like
save, refresh, etc.
- Default implementation for the mapping between visual component values and ESData elements.
- Threaded messaging to the server via an instance of ESNCService.
- Default implementation for performing data validation on the visual components.
- Default implementation for dealing with unsaved changes scenarios.
- Default implementation for processing server response including updating the status bar, updating
ManagedList instances, and updating the visual components.

The definition of the visual components has been moved from java instructions in the ApplicationFrame
extension to a configuration file. Class ESComponentBuilder reads the configuration file, assembles the
components into containers (JPanel instances), and renders the components using
java.awt.GridBagLayout. ESComponentBuilder and AbstractESApplicationFrameForTable work
together to provide much of the behavior required of a BASE24-eps UI ApplicationFrame.

Many BASE24-eps UIs include a visual table. Class GenericETableMgr, and many related classes, work
together with a configuration file to provide a javax.swing.JTable implementation that includes the
behaviors needed for a BASE24-eps UI table. Some of the provided behavior includes:

- Default implementation for common table related user actions like insert row, delete row, and
undo row.
- Default implementation for the mapping between the table cell values and ESData elements.

2-16
 - Default implementation for sorting the table based on selected column.
- Configuration for table columns, column headers, and column cell editors.
- Several cell editors are already supported, and the architecture allows for the easy addition of
additional column cell editors.

2.3.3 Properties and Config Files

The following property and config files are used by a BASE24-eps UI:

BASE24-eps 06.2 Version Note:

As of the BASE24-eps Version 06.2, we have moved the UI Security entries related to the UI
packages defined under the Version Independent Interfaces directory (i.e., \ui\if\es\desktop\) into a
UISecurityIDs property file extension named UISecurityIDs+INTF.properties. This property file can be
found under the …\ui\if\es\desktop\ folder. This property file extension is packaged in the new UI
application jar, ifDT.jar, found under the …\ui\Repository\ES\Desktop\Applications\ folder. All new
User Security ID’s defined for any Version Independent UI’s will be added to the UISecurityIDs+INTF
property file.

- The UISecurityIDs or UISecurityIDs+INTF property file contains security entries for every UI.
- The ESData definition is a config file. The primary purpose of this config file is to define the
messages that will be exchanged with the server.
- The UI Layout Files are config files that contain the definition of the visual components used by
the UI.
- The UI Property file contains localization properties for things like the UI title and the labels for
the UI components.
- A Table Property File will be created for every visual table component used by the UI.

2.4 Training UI

This document walks a developer through the steps of creating a BASE24-eps UI. A UI named Training
UI is used to show a sample implementation of each step. The subsection in this introduction titled
Development Steps summarizes the development steps. These steps are ordered in the recommended
sequence for developing a BASE24-eps UI.

The Training UI was designed to show the use of different types of visual components. The components
don’t relate to each other (i.e., don’t try to think of this as a useful UI, think of it as a training tool). This
UI consists of the following components:

- A panel where a user selects a Profile to which the other components on the UI are tied.
- A tabbed pane consisting of:
o A General Information tab containing general components.
o An Acquirer Table tab designed to show how a table component is implemented.

2-17
If this were an actual production UI, the following data sources would need to exist:

- Data source truign. This data source contains general information. It’s elements correspond to
the elements on the General Information tab.
- Data source truits. This data source contains information that corresponds to the elements on the
Acquirer Table tab.

2.5 Training UI Screen Samples

General Information Tab

2-18
Acquirer Table Tab

2.6 Development Steps

The following table summarizes the steps involved in creating a BASE24-eps UI.

Section Step Training UI Class/File/etc

3 Determine whether the UI is being
developed as a standard UI or a
custom UI.
4 Determine the package name. es.desktop.training
5 Determine the security ID and update
ES_ESF.properties.
6 Create the ESData definition. es.desktop.training.Training.cfg
7 Determine the application name and Applications.lst

2-19
 create the Applications.lst file.
8 Determine the UI constant(s).
9 Create the UI layout config files. es.desktop.training.TrainingLayout.cfg
es.desktop.training.TrainingGeneral.cfg
es.desktop.training.TrainingKeyPanel.cfg
10 Create the UI property file. es.desktop.training.Training.properties
11 For a UI containing one or more es.desktop.training.TrainingAcquirerTable
visual tables, create the table property .properties
file(s).
12 Create the interface containing the es.desktop.training.TrainingConstants.java
constants used by the UI.
13 Create the UIInstanceManager As of BASE24-eps Version 08.2, most UIs will
extension(s). not need a UIInstanceManager extension.
14 Create the ManagedList extension(s). es.desktop.training.TrainingProfileManagedList
.java
15 Create the ESDesktopApplication es.desktop.training.TrainingManager.java
extension.
16 Create the ESComponentBuilder es.desktop.training.TrainingBuilder .java
extension.
17 Create the es.desktop.training.TrainingUI.java
AbstractESApplicationFrameForTable
extension.
18 When needed, create the
GenericETableMgr extension. This
step is rarely required.

2-20
3 Determining Standard, Version Independent, or Custom
This document refers to development differences based on whether the UI is being developed as standard
product, Version independent, or as a custom user interface. Consult with the lead of your project for
direction in this area.

3-21
4 The Package Name
The package for the new UI will follow the form of:

es.desktop.xxxx where xxxx describes the new UI.

The package name for the Training UI is:

es.desktop.training

Custom UI Consideration: The package name for a custom UI should follow this naming convention.

4-22
5 Security ID and ES_ESF.properties

5.1 Security ID

UI Security IDs are defined in UISecurityIDs.properties. Each UI has assigned to it a security ID. This
ID is set up on the UI side and on the server side.

Custom UI Consideration: UISecurityIDs.properties file is typically not updated when the UI is a

custom UI.

The security ID for the Training UI is:

security.ui.taskID.TRAINING_UI.text=TrainingUI

5.2 ES_ESF.properties

ES_ESF.properties is the properties file that is used to create a DALCI script which loads all of the
BASE24-eps UI security functions and tasks to the USEC database.

Custom UI Consideration: CSM_ES_ESF.properties is updated for custom UIs and site specific
changes.

The easiest way to update this file is to select a UI that has the same functions as the new UI (delete, save,
view) and copy the existing UI’s entries and paste them and modify them for the new UI.

The USEC tables that need to be loaded for a new UI are:

PermDetl
Perms
PmGpXPrm
TaskFncs
Tasks

The following are brief summaries of the data contained, example entries for each table, and the
corresponding USEC UI where the data can be viewed.

Note: The naming convention used for the unique identifier value (left hand side) is usually the UI’s
Security Task ID and an incrementing number. (i.e. ATMDHPeakLoadProfile_1)

The values that have to match are color coded below.

Be sure to keep within the field length limitations for the fields.

5-23
PermDetl
The PermDetl table contains the Permission ID, the Object ID, and Permission Type Code. This table ties
the Permission ID with the functions (Object ID) available with that Permission. This data relationship
can be configured through the Permissions tab of the User Security Role Configuration UI, but we use a
DALCI script.

The Permission ID (FullATMDHPeakLoadProfilePerm below) can be a maximum of 30

characters.

[Load_PermDetl]
ATMDHPeakLoadProfile_1=FullATMDHPeakLoadProfilePerm, Delete, FN
ATMDHPeakLoadProfile_2=FullATMDHPeakLoadProfilePerm, Save, FN
ATMDHPeakLoadProfile_3=FullATMDHPeakLoadProfilePerm, View, FN
. . .
ATMDHPeakLoadProfile_4=ViewATMDHPeakLoadProfilePerm, View, FN

The ViewATMDHPeakLoadProfilePerm only has the View function associated with it.

5-24
Perms
The Perms table contains the Permission ID, Task ID, Permission Description, Last Maintanence
Timestamp, and OwnerID. This table defines the Permission ID and associates it with the Task ID. This
data relationship can be configured through the Permissions tab of the User Security Role Configuration
UI, but we use a DALCI script.

The Permission ID (FullATMDHPeakLoadProfilePerm below) can be a maximum of 30

characters.

The Task ID (ATMDHPeakLoadProfile below) can be a maximum of 30 characters.

Ther Permission Description (Full ATMDH Peak Load Profile permission set. below)
can be a maximum of 50 characters.

[Load_Perms]
ATMDHPeakLoadProfile_1=FullATMDHPeakLoadProfilePerm,
ATMDHPeakLoadProfile, Full ATMDH Peak Load Profile permission set.,
<TS>, *
. . .
ATMDHPeakLoadProfile_2=ViewATMDHPeakLoadProfilePerm,
ATMDHPeakLoadProfile, View ATMDH Peak Load Profile permission set.,
<TS>, *

5-25
PmGpXPrm
The PmGpXPrm table associates the Permission Group ID to the Permission ID. It allows the Permission
Group to the specified access of that defined Permission ID. This data relationship can be configured
through the Permission Groups tab of the User Security Role Configuration UI, but we use a DALCI
script.

The Permission ID (FullATMDHPeakLoadProfilePerm below) can be a maximum of 30

characters.

The Permission Group ID (Level1PermissionGroup below) can be a maximum of 30 characters.

[Load_PmGpXPrm]
ATMDHPeakLoadProfile_1=Level1PermissionGroup,
FullATMDHPeakLoadProfilePerm
. . .
ATMDHPeakLoadProfile_2=Level2PermissionGroup,
FullATMDHPeakLoadProfilePerm
. . .
ATMDHPeakLoadProfile_3=SysAdminPermissionGroup,
FullATMDHPeakLoadProfilePerm

5-26
TaskFncs
The TaskFncs table ties the Task ID to the Function IDs (or available actions). These are all the possible
functions that could be performed by the UI. This data relationship can not be entered through the UI. It
must be loaded directly into the datasource with a DALCI script.

The Task ID (ATMDHPeakLoadProfile below) can be a maximum of 30 characters.

[Load_TaskFncs]
ATMDHPeakLoadProfile_1=ATMDHPeakLoadProfile, Delete
ATMDHPeakLoadProfile_2=ATMDHPeakLoadProfile, Save
ATMDHPeakLoadProfile_3=ATMDHPeakLoadProfile, View

5-27
Tasks
The Tasks table defines the Task ID and Description. The Task ID is the same as the Security Task ID
refered to by the UI. This data can not be entered through the UI. It must be loaded directly into the
datasource with a DALCI script.

The Task ID (ATMDHPeakLoadProfile below) can be a maximum of 30 characters.

Ther Description (ATMDH Peak Load Profile task. below) can be a maximum of 50 characters.

[Load_Tasks]
ATMDHPeakLoadProfile="ATMDHPeakLoadProfile,ATMDH Peak Load Profile
task., "

To find out the size of a field you can search for the table name and find the table definition. Each
field is detailed below the table definition.

[Perms]
PriKeyColumns=PermissionID
Index_OwnerID=OwnerID
Index_TaskID=TaskID
Column_1=PermissionID
Column_2=TaskID
Column_3=Descr

5-28
Column_4=LastMaintTS
Column_5=OwnerID

[Perms.PermissionID]
DataType=1
TypeName=char
Size=30
Default=
Nullable=false
Ordinal=1

5-29
6 ESData Definition
This primary purpose of the ESData definition is to define the messages that will be exchanged with the
server. The ESData definition for the Training UI is:

Training.cfg

In addition to it’s primary purpose, the ESData definition is where the validation constraints are defined
for the visual components (e.g., the visual component Description can be a maximum of 32 characters).

The structures defined in the ESData definition are represented by instances of the class
es.shared.ESData.

BASE24-eps 06.2 Version Note:

As of the BASE24-eps Version 06.2, the ESData definition goes in the UI specific package. So
Training.cfg is located in es.desktop.training. Prior to version 06.2, the ESData definitions for all UIs
were located in file ESDataConfig.cfg located in the folder es.shared.ESDataConfiguration.

6.1 Server Messages

Defining the server messages is a joint effort between the UI developer and the server developer.
Typically, the UI developer creates the ESData definition, which serves as the basis for a meeting
between the UI developer and the server developer. The result of this meeting is the final version of the
ESData definition.

The following table summarizes the types of messages defined in most UIs.

Message Type Description Training UI Definitions

List request and The server returns a list of items TrainListRq
response. from a data source. TrainListRs

The response from the server is

typically used to populate a list
which the UI can use to offer the
user a selection of available
choices.

In the case of the Training UI,

the server returns all profile
values from the truign data
source. The Training UI uses
the list response to populate the
Profile combo box drop down
list.
View request and The server returns the details for TrainViewRq

6-30
 Message Type Description Training UI Definitions
response. an item from a data source. TrainViewRs

For the Training UI, the server

returns data from the truign data
source, related to the value of
truignProfile passed in the
request.
Insert request and The server inserts an item into TrainInsertRq
response. the data source. TrainInsertRs
Update request and The server updates an item on TrainUpdateRq
response. the data source. TrainUpdateRs
Delete request and The server deletes an item from TrainDeleteRq
response. the data source. TrainDeleteRs

The view, insert, update and delete messages typically work as a single request and response. For
example, an insert request is sent to the server, and the server responds with an insert response. The list
request/response process typically involves multiple exchanges. The UI sends the initial list request
containing an empty key element(s). This instructs the server to start reading at the beginning of the data
source. If the server is unable to deliver all of the data in a single response, the UI will send subsequent
requests, and will value the key element(s) so the server knows where to continue reading the data source.

The list request definition for the Training UI includes the element truignProfile. This element will be
empty on the initial list request and will be populated if subsequent requests are needed to retrieve all of
the data.

[TrainListRq]
truignProfile =es.shared.ESString

Convention: Request message names end in Rq (e.g., TrainListRq) and response message names end in
Rs (e.g., TrainListRs).

Convention: The data elements defined in a message are prefixed with the data source name to which
they are related. Example, truignProfile is an element related to the truign data source. This is a new
standard as of January 2003.

Training.cfg also includes messages related to the Acquirer Table tab. Request and response messages
related to visual table data differ from non-table data in that these messages deal with recurring groups of
elements. Each row in a visual table component typically relates to a row (i.e., record) in the data source.
Notice how the insert request consists of an element named TrainAcqTblInsertRqEntry. This element
is defined on the next line down as consisting of RowID, truitsProfile, etc. This structure allows the UI to
transmit one or more instances of TrainAcqTblInsertRqEntry (with each instance relating to a row on
the data source) to the server in a single request. The + after the right closing bracket denotes that
TrainAcqTblInsertRqEntry is a group that can occur more than one time.

[TrainAcqTblInsertRq]

6-31
TrainAcqTblInsertRqEntry ={TrainAcqTblInsertRqEntry}+

[TrainAcqTblInsertRqEntry]
RowID =es.shared.ESString
truitsProfile =es.shared.ESString
truitsAcquirerType =es.shared.ESString
truitsAcquirerProfile =es.shared.ESString
truitsDescription =es.shared.ESString

[TrainAcqTblInsertRs]
TrainAcqTblInsertRsEntry ={TrainAcqTblInsertRsEntry}+

[TrainAcqTblInsertRsEntry]
truitsServerContext =es.shared.ESString
RowID =es.shared.ESString

Convention: The server treats updates involving multiple data source rows as a single unit of work. This
means either all of the updates are successful or none of the updates are successful. For example, if the
insert request contains three instances of TrainAcqTblInsertRqEntry, and if the first insert is successful,
but the second insert fails, the server will back out the first insert and send a denied response to the UI.

Convention: As of Feburary 2003, a new standard has been adopted that requires all table requests and
responses to contain the element RowID.

The following summarizes the types of table related messages defined in most UIs that contain a visual
table component.

Message Type Description Training UI Definitions

View request and Typically the UI request will TrainAcqTblViewRq
TrainAcqTblViewRs
response. contain a key value and the
server responds with all rows
containing the supplied key
value (or partial key). The UI
then populates the visual table
with the server response data.

Like the list request/response

discussed above, this
request/response message pair
may need to be invoked multiple
times for the UI to retrieve all of
the data from the server. In the
case of the Training UI, element
truitsAcquirerType is
provided so that the server
knows where to continue reading
in the case where multiple
exchanges are needed to retrieve
all of the data.

6-32
 Message Type Description Training UI Definitions
Insert request and The server inserts one or more TrainAcqTblInsertRq
response. rows into the data source. TrainAcqTblInsertRs
Update request and The server updates one or more TrainAcqTblUpdateRq
response. rows on the data source. TrainAcqTblUpdateRs
Delete request and The server deletes one or more TrainAcqTblDeleteRq
response. rows from the data source. TrainAcqTblDeleteRs

6.2 Server Context

As you look through Training.cfg, you will notice the element truignServerContext (or
truitsServerContext for table related messages) appears in several of the messages. This element
allows the server to ensure that the UI has the most current version of the data being updated, in the case
where the UI is sending an update request to the server. The UI retrieves the server context value from the
server as part of response processing, and provides it back to the server as part of delete/update request
processing.

6.3 Field Validate Errors

The server performs validation on messages received from the UI. For example the server will ensure that
each element contains the proper number of characters. If the element is numeric, the server will ensure
the value is within a specified range. When the server detects a field validate error, it sends back a special
response with a message type of FieldValidateErrorResponse. Since this ESData definition includes
the recurring group element Error, the server has the ability to report multiple field validate errors in a
single response.

[FieldValidateErrorResponse]
Error ={Error}+

[Error]
ErrCode =es.shared.GenericString,0
FieldID =es.shared.GenericString,0
ErrDescr =es.shared.GenericString,0
ErrIndex =es.shared.GenericString,0

The element FieldID denotes the type of error being reported. The values the server uses to populate this
element, and the corresponding message presented to the user are as follows:

InvldValue Invalid value, please review data entered

Required A value is required
Undermin Value is under the minimum allowed, review data entered
Overflow Value is over the maximum allowed, review data entered
NonNumeric Value must be numeric
OutOfRange Value is outside of the allowable range, review ….
Length Field length is invalid, review data entered

6-33
The element FieldID reports the element from the request that is in error. The element ErrDescr
contains additional text related to the error. ErrIndex is only used for reporting errors in requests
containing multiple group entries (e.g., table requests). This element is populated from the RowID
element in the request.

6.4 All Elements

A structure with a data type that typically contains the text “AllElements” is defined in most ESData.cfg
files. For the Training UI, this structure is named TrainAllElements.

[TrainAllElements]
truignProfile =es.shared.ESString,Max Length:16,Min Length:1,No
Leading Spaces,No Embedded Spaces
truignDescription =es.shared.ESString,Max Length:32
truignIssuerRteProfile =es.shared.ESString
truignCntryCde =es.shared.ESString,Min Length:1
truignServerContext =es.shared.ESString

Note: truignProfile fits on one line in the source file.

Unlike the above definitions, this definition is not a message that is exchanged with the server. It’s
purposes fall in the categories of Visual Component Mapping, Data Validation, and Non Visual Element
Hold Area.

6.4.1 Visual Component Mapping

Each non-table visual component used by the UI is defined in the AllElements ESData. Methods within
classes ESDataManager and es.shared.ESData provide for the mapping of visual component values to
the AllElements ESData, then from the AllElements ESData to the appropriate request ESData which is
then sent to the server. The reverse occurs when the response is received from the server.

6.4.2 Data Validation

To the right of each element are the AbstractDataType class for the element, and a series of keywords.
Extensions of class es.shared.AbstractDataType are used to perform data validation on the visual
components. Instances of es.shared.ESString are the generally used implementation of
AbstractDataType used for performing data validation on visual components. Before a request is sent to
the server, data validation is performed on each visual component.

The supported keywords and their meaning are as follows:

Keyword Meaning
Alpha The value of the visual component must

6-34
 Keyword Meaning
consist of alphabetic characters.
Numeric The value of the visual component must
consist of numeric characters.
Alphanumeric The value of the visual component must
consist of alphabetic and numeric
characters.
Hex The value of the visual component must
consist of hex characters.
No Leading Spaces The value of the visual component can not
contain leading spaces.
No Embedded Spaces The value of the visual component can not
contain embedded spaces.
Min Value The value of the visual component must be
greater than or equal to this value.
Max Value The value of the visual component must be
less than or equal to this value.
Min Length The length of the value of the visual
component must be greater than or equal to
this value.
Max Length The length of the value of the visual
component must be greater than or equal to
this value.

6.4.3 Non Visual Element Hold Area

Non-visual components can also be defined here as a way of holding a response element value for
inclusion in a subsequent request to the server. For example, on a view response the TrainAllElements
element truignServerContext is populated from the TrainViewResponse element
truignServerContext. Subsequently, if the user elects to save changes, the TrainUpdateRequest
element truignServerContext is populated from the TrainAllElements element truignServerContext.

6.5 Screen Data

A structure which typically contains the text “ScreenData” is defined in most ESData definitions where
the UI contains a visual table.

[TrainAcqTblScreenData]
TrainAcqTblScreenDetails ={TrainAcqTblScreenDetails}+

[TrainAcqTblScreenDetails]
truitsServerContext =es.shared.ESString
RowID =es.shared.ESString
truitsAcquirerType =es.shared.ESString,Min Length:1

6-35
truitsAcquirerProfile =es.shared.ESString
truitsDescription =es.shared.ESString,Max Length:32,Min Length:1

The ScreenData ESData definition plays the same role for table data as AllElements plays for non-table
data. Since table data is multiple rows of data, the ScreenData ESData definition will include a recurring
group (TrainAcqTblScreenDetails above) to represent multiple rows.

6.5.1 Visual Component Mapping

All table columns that are part of ESData requests and responses are included in the ScreenData
definition to allow automated mechanisms to map the table data to/from server messages.

6.5.2 Data Validation

To the right of the element is the AbstractDataType extension used for validation. To the right of this
are the validation keywords.

6.5.3 Non Visual Components

Neither truitsServerContext nor RowID are visual components. These elements are included in the
ScreenData definition because they are needed in requests to the server. truitsServerContext is saved
to the table model when response messages are received from the server, and then is retrieved from the
table model when request messages are sent to the server. RowID is a value maintained by the table model,
and is retrieved from the table model when request messages are sent to the server.

6.6 Class es.shared.ESData

Instances of class es.shared.ESData are used to represent the ESData definitions. Some of the
commonly used methods of this class are summarized below.

Method Description
public ESData( String esDataType ) This constructor is the simplest way
to create an ESData. The
esDataType is the name of the
ESData that is to be created (e.g.,
TrainListRq).
public int getArrayLength(String key) Provides the number of occurrences
throws ESException of key contained by the ESData.
This method is useful when dealing
with an ESData that contains
recurring groups. For example, this
method can be used to find out how

6-36
 Method Description
many instances of
TrainAcqTblViewRsEntry are
contained by the ESData
TrainAcqTblViewRs.
public String getValue(String key) Returns the value of the element
throws ESException specified by key. For example, this
method can be used to retrieve the
value of the element
truignDescription from the
ESData TrainViewRs.
public String getValue(String key, int index) Returns the value of the element
throws ESException specified by key at the location
specified by index. This method is
typically used to retrieve a value
from a recurring group within an
ESData. For example, this method
can be used to retrieve the value of
the element
truitsAcquirerProfile from the
ESData TrainAcqTblViewRs.
public void setValue Assigns a value to the element
(String key, String value) specified by key. For example, this
throws ESException method can be used to assign a value
to the element
truignIssuerRteProfile within
the ESData TrainUpdateRq.
public void setValue Assigns a value to the element
(String key, String value, int index) specified by key at the location
throws ESException specified by index. For example,
this method can be used to assign a
value to the element
truitsAcquirerType within the
ESData TrainAcqTblInsertRq.
public void setESData Populates the ESData from the
(ESData esDataSource) contents of esDataSource. Matching
throws ESException keys are copied. For example, this
method can be used to populate the
ESData TrainAllElements from
the ESData TrainViewRs.
public ESData getESDataItem This method is typically used to
(String key, int index) retrieve a recurring ESData at the
throws ESException location specified by index. For
example, this method can be used to
retrieve an instance of
TrainAcqTblViewRsEntry from

6-37
 Method Description
TrainAcqTblViewRs.
public String getDataType() Returns the data type value. For
example, if this method is invoked
on an instance of a TrainUpdateRq
ESData, the method will return
“TrainUpdateRq”.

6.7 ESDataConfig.cfg

BASE24-eps 06.2 Version Note:

As of the BASE24-eps Version 06.2, it is no longer necessary to add the ESData types to
ESDataConfig.cfg. There is now logic in ESDesktopApplication to dynamically build this index.
Reference this link for override information.

6-38
7 Determine the Application Name and Create Applications.lst
This section used to be titled ESAppIDs. Prior to version 07.4, it was necessary add the application name
for the new UI to ESAppIDs. As of version 07.4, this is no longer necessary.

The application name is the same as the name of the manager class. For the Training UI, the application
name is:

TrainingManager

In the section on UI Constants, instructions are provided for adding a constant for the application name.

Once the application name is known, add the Applications.lst file. The Applications.lst file contains one
or more entries, depending on the number of product IDs that are associated with the UI. The product
ID(s) come from Product Management, and will be identified in the design.

Here is an example of the Applications.lst entry for the ATM Channel Profile UI.

ATMDHChannelManager=es.desktop.atmdhchannel.ATMDHChannelManager,DA000_SUBSET2

The format of the entry is:

aaaa=bbbb,cccc

Where aaaa is the application name (which is also the manager class name).
Where the “=” is required.
Where bbbb is the fully qualified name of the manager class.
Where the “,” is required.
Where cccc is the product ID.

Custom UI Consideration: Use “*” for the product ID for a custom UI. For example, if the ATM
Channel Profile UI is a custom UI, the Applications.lst entry would be:.

ATMDHChannelManager=es.desktop.atmdhchannel.ATMDHChannelManager,*

7-39
8 Determine the UI Constant(s)
This section used to be titled ESDesktopConstants. Prior to version 07.4, it was necessary add the UI
constant(s) to ESDesktopConstants. As of version 07.4, this is no longer necessary.

There is a constant for each UI. The constant is generally the package name (upper case first letter)
followed by “UI”. The UI constant for the Training UI is:

TrainingUI

If the UI maintains a ManagedList, there will be a constant for the ManagedList. The Training UI
maintains a ManagedList. The constant is:

TrainingUIList

In the section on UI Constants, instructions are provided for adding constant for the UI name, and the list.

Convention: A new standard adopted as of December 2002, UI constants must contain no embedded,
leading, or trailing spaces. This standard is necessary to allow the navigation tree placement of the UI to
be configurable.

The UI name constant is used by configurable navigation and allows the UI to be hyperlinked to by
another UI. Many UIs have a second constant defined that represents a list maintained by the UI. This
allows a single copy of the list to be shared by multiple UIs. The list maintained by the Training UI is a
list of profiles defined on the truign data source. By defining a list constant for this list, the list is
available to other UIs. For example, if a second UI requires a combo box component for profiles on the
truign data source, this UI will make use of the same list maintained by the Training UI.

The UI constants determined during this step will be referred to in subsequent sections of this document.

8-40
9 UI Layout

9.1 Overview

This section of the document describes the aspects of the UI Layout Configuration that pertain to the
Training UI.

Visual components are defined in configuration files (suffixed by .cfg). Class ESComponentBuilder
assembles the components into containers (javax.swing.JPanel instances) and renders the components
using a java.awt.GridBagLayout layout manager.

Every UI will include a primary layout configuration file. If the UI consists of multiple panels, the
primary layout configuration will typically reference other configuration files. The UI layout files for the
Training UI are as follows:

Primary Layout TrainingLayout.cfg

Key Panel TrainingKeyPanel.cfg

General Information Tab TrainingGeneral.cfg

Acquirer Table Tab Table panels must be defined in the primary layout, so the definition for this
tab is in TrainingLayout.cfg

9.2 Primary Layout

The first definition is the Panels definition. This is where the panels are defined, and the relationships
between the panels are defined. For the Training UI, we have defined four panels as shown below.
TrainingKeyPanel and TabbedPane1will be contained by MainPanel. TrainingGeneral and
TrainingAcquirerTable will be contained by TabbedPane1.

[Panels]
TrainingKeyPanel = MainPanel
TabbedPane1 = MainPanel
TrainingGeneral = TabbedPane1
TrainingAcquirerTable = TabbedPane1

Convention: The highest level panel must be named MainPanel.

Next, definitions are provided for each panel referenced above. Each panel is defined with either a
ClassName or a ConfigFile. The definition that contains the table has some additional properties,

9-41
primarily TableDefinitionFileName and TabTitle. TableDefinitionFileName refers to the
property file for this table. TabTitle refers to a value in the UI Property File.

[TabbedPane1]
ClassName = javax.swing.JTabbedPane
PreferredSize = 615, 325
weighty = 1

[MainPanel]
ClassName = javax.swing.JPanel
PreferredSize = 615, 375
fill = both
weighty = 1

[TrainingKeyPanel]
ConfigFile = TrainingKeyPanel.cfg
PreferredSize = 615, 50

[TrainingGeneral]
ConfigFile = TrainingGeneral.cfg

[TrainingAcquirerTable]
ClassName = es.desktop.GenericETableMgr
anchor = West
insets = 4,4,4,4
PreferredSize = 615, 325
TableDefinitionFileName = TrainingAcquirerTable.properties
TabTitle = AcquirerTablePanelName
weighty = 1

The last definition, contains arguments for java.awt.GridBagLayout.

[ConstraintDefaults]
anchor = West
gridwidth = remainder
fill = both
weightx = 1

9.3 Key Panel

The first definition includes the components for this panel. The names of the components(e.g.,
profileLabel) are referenced by the UI Property File for purposes of label localization, ManagedList ties,
and key component specification. The class name assigned to each visual component must be an
EComponent.

[PanelComponents]
profileLabel = framework.desktop.ecomponents.ELabel
profileList = es.desktop.SelectionComboBox
spacerLabel1 = framework.desktop.ecomponents.ELabel

9-42
Next we have an additional definition for profileList. Here we are tying this visual component to an
ESData element. This allows the mapping between the visual component and the ESData element to take
place.

[profileList]
ESDataKey=truignProfile

Next we have an additional definition for spacerLabel1. spacerLabel1 is a filler that allows the visual
components to be spaced properly.

[spacerLabel1]
weightx = 1
gridwidth = 2

Last are the java.awt.GridBagLayout defaults.

[ConstraintDefaults]
anchor = West
fill = Horizontal
insets = 4,4,4,4
weightx = 0
weighty = 0

9.4 General Information Tab

The first section defines the property to be used to get the tab title. This definition references a property in
the UI Property File.

[PanelInfo]
PanelName = GeneralPanelName

The next section is where the components for this panel are defined.

[PanelComponents]
descriptionLabel = framework.desktop.ecomponents.ELabel
descriptionText = framework.desktop.ecomponents.ETextField
spacerLabel2 = framework.desktop.ecomponents.ELabel
issuerRouteLabel = framework.desktop.ecomponents.EHyperLinkLabel
issuerRouteList = framework.desktop.ecomponents.EComboBox
countryCodeLabel = framework.desktop.ecomponents.ELabel
countryCodeList = framework.desktop.ecomponents.EComboBox

The next section specifies that descriptionLabel be located at java.awt.GridBagConstraints

coordinates 0, 0.

[descriptionLabel]
gridx = 0
gridy = 0

9-43
The coordinates for descriptionText are defined, as well as the associated ESData element.

[descriptionText]
gridx = 1
gridy = 0
ESDataKey=truignDescription

spacerLabel2 is a filler.

[spacerLabel2]
gridwidth = 2
gridx = 2
gridy = 0
weightx = 1

The rest of the components are defined.

[issuerRouteLabel]
gridx = 0
gridy = 1

[issuerRouteList]
gridx = 1
gridy = 1
ESDataKey=truignIssuerRteProfile

[countryCodeLabel]
gridx = 0
gridy = 2

[countryCodeList]
gridx = 1
gridy = 2
ESDataKey=truignCntryCde

The java.awt.GridBagLayout arguments for this panel.

[ConstraintDefaults]
anchor = West
fill = Horizontal
insets = 4,4,4,4
weightx = 0
weighty = 0

9-44
10 UI Property File

10.1 Overview

The property file name for the Training UI is Training.properties.

The primary purpose of the UI property file is to define the localized text that appears on the UI in the
form of labels, titles, table column headers, etc. In addition, the UI property file is used to define several
other items that are specific to the UI:

- The user actions (e.g., save, delete) supported by the UI.

- Localization and placement of the UI on the navigation tree.
- Help properties
- Tying a ManagedList to a combo box component.
- Localized lists used by the UI.
- Component(s) of the UI which should be considered key fields.

10.2 UI Actions

User actions are provided by the UI on the UI toolbar and on the UI right-click popup menu. The actions
that are to be on the toolbar are defined in a property in the form of:

xxxx.toolbar

where the xxxx is equal to the property file name.

The toolbar property for the Training UI is:

Training.toolbar=save clear refresh | delete | insertRow deleteRow undo

Each action defined by the toolbar property must be further defined by three additional properties in the
format of:

xxxx.yyyy.zzzz

where xxxx is equal to the property file name

where yyyy is equal to the action from the toolbar property
where zzzz is the value icon, toolTipText, or accelerator.

The Training UI properties for the clear action follow. These properties will typically look the same in
every UI, with the exception of the first node of the property (e.g., Training).
Training.clear.icon={LINK}CommonUI:Common.clear.Tol.icon

10-45
Training.clear.toolTipText={LINK}CommonUI:Common.clear.Tol.toolTipText
Training.clear.accelerator={LINK}CommonUI:Common.clear.Accelerator

The actions that are to be on the right-click popup menu are defined in a property in the form of:

xxxx.popupMenu

where the xxxx is equal to the property file name.

The popupMenu property for the Training UI is:

Training.popupMenu=save clear refresh | delete | insertRow deleteRow undo

Each action defined by the popupMenu property must be further defined by four additional properties in
the format of:

aaaa.bbbb.cccc.dddd

where aaaa is equal to the property file name

where bbbb is equal to the action from the popupMenu property
where cccc is equal to the constant Mnu.
where dddd is the value icon, text, toolTipText, or accelerator.

The Training UI properties for the clear action follow. These properties will typically look the same in
every UI, with the exception of the first node of the property (e.g., Training).

Training.clear.Mnu.icon={LINK}CommonUI:Common.clear.Mnu.icon
Training.clear.Mnu.text={LINK}CommonUI:Common.clear.Mnu.text
Training.clear.Mnu.toolTipText={LINK}CommonUI:Common.clear.Mnu.toolTipText
Training.clear.Mnu.accelerator={LINK}CommonUI:Common.clear.Accelerator

Version 5.4 Note: As of version 5.4, properties are no longer needed for the following actions.

save
delete
submit
clear
refresh
insertRow
insertRowBefore
deleteRow
undo
template
clearRow
copyRow
pasteRow

10-46
For these actions, you just define them in the toolbar and/or popup menu property. There is no need for
the additional properties.

10.3 Navigation Localization

The navigation for the Training UI is as follows:

Configure → Training → Training UI

The Training UI properties for navigation location and localization are discussed below. In general, the
navigation properties can be categorized as follows:

- UI(s) to be included on the Navigation Tree.

- The Navigation Tree root branch for this UI.
- The Navigation Tree tree branch(es) for this UI.
- Mnemonics

10.3.1 List of UIs

The logic that is interested in the Navigation Localization properties is method getNavigationTree in the
class ESDesktopApplication. An ESDesktopApplication can own one or more UIs. The property that
identifies the UI owned by the Training UI ESDesktopApplication is:

Training.0.uilist=TrainingUI

This property takes the form of:

aaaa.n.bbbb=cccc

Where aaaa (Training in example) is the property file name.

Where n must be a number beginning with 0, and must be incremented by 1 for each additional UI. The
ESDesktopApplication for the Training UI only manages one UI, so there is only one property and the
value of this node is 0.

Where bbbb must be the value uilist.

The related text (i.e., cccc) must match the UI name constant value for this UI.

10-47
10.3.2 Security ID

The property that identifies the security task ID for the Training UI is:

Training.TrainingUI.securityTaskID=TRAINING_UI

This property takes the form of:

aaaa.bbbb.cccc=dddd

Where aaaa (Training in example) is the property file name.

Where bbbb must match the value of the uilist property (TrainingUI in example). This also matches the
UI name constant value for this UI.

Where cccc must be the value securityTaskID.

The related text (i.e., dddd) is the variable node of the UISecurityIDs.properties entry for the UI (or the
UISecurityIDs+INTF.properties entry for Version Independent UI’s).

Custom UI Consideration: For a custom UI, the related text (i.e., dddd) must be the security ID instead
of the variable node in the UISecurityIDs.properties entry. For example, if the Training UI was a
custom UI, this property might be:

Training.TrainingUI.securityTaskID=TrainingUISecurity

10.3.3 Root Branch

The root branch definition dictates the placement of the UI on the Desktop navigation tree. As shown
above, the Training UI goes on the Configure branch. The property that identifies the root navigation
branch for the Training UI is:

Training.rootbranch.TrainingUI.text={LINK}Desktop:Desktop.configure.text

This property takes the form of:

aaaa.bbbb.cccc.dddd=eeee

Where aaaa (Training in example) is the property file name.

Where bbbb must be the value rootbranch.

Where cccc must match the value of the uilist property (TrainingUI in example). This also matches the UI
name constant value for this UI.

10-48
Where dddd must be the value text.

The related text is generally a link to a property defined in Desktop.properties, under the comment:
#
# Framework navigation items:
#

10.3.4 Tree Branch(es)

The tree branch definition(s) identify the remainder of the navigation for the UI. The remaining branches
for the Training UI are Training followed by Training UI. Since there are two tree branches, there are two
properties.

Training.treebranch.0.TrainingUI.text={LINK}CommonUI:Common.TrainingNavNode.text

Training.treebranch.1.TrainingUI.text=Training UI

This property takes the form of:

aaaa.bbbb.c.dddd.eeee=ffff

Where aaaa (Training in example) is the property file name.

Where bbbb must be the value treebranch.

Where c must be a number beginning with 0, and must be incremented by 1 for each additional branch.

Where dddd must match the value of the uilist property (TrainingUI in example). This also matches the
UI name constant value for this UI.

Where eeee must be the value text.

The related text is sometimes a link to a property defined in CommonUI.properties, and is sometimes
simply text. Intermediate tree branches are typically defined in CommonUI.properties which is the case
for treebranch.0 above. It’s definition is as follows:

Common.trainingNavNode.text=Training

10.3.5 Mnemonics

The Mnemonics properties are responsible for underscoring the first letter of the navigation nodes on the
Desktop menu. Typically, there is a .mnemonic treebranch definition to match each .text treebranch
definition.

Training.treebranch.0.TrainingUI.mnemonic={LINK}CommonUI:Common.Training NavNode.mnemonic

Training.treebranch.1.TrainingUI.mnemonic=T

10-49
This property takes the form of:

aaaa.bbbb.c.dddd.eeee=ffff

Where aaaa (Training in example) is the property file name.

Where bbbb must be the value treebranch.

Where c must be a number beginning with 0, and must be incremented by 1 for each additional branch.

Where dddd must match the value of the uilist property (TrainingUI in example). This also matches the
UI name constant value for this UI.

Where eeee must be the value mnemonic.

The related text is sometimes a link to a property defined in CommonUI.properties, and is sometimes
simply a value. Intermediate tree branches are typically defined in CommonUI.properties which is the
case for treebranch.0 above. It’s definition is as follows:

Common.trainingNavNode.mnemonic=T

10.3.6 Navigation Weight Properties

A navigation weight property is needed for each “rootbranch” navigation property that is suffixed with
“.text”, and for each “treebranch” navigation property that is suffixed with “.text”. The navigation weight
properties for the Training UI are as follows:

Training.rootbranch.TrainingUI.navweight.param={LINK}CommonUI:Common.Configure.navweight.param
Training.treebranch.0.TrainingUI.navweight.param={LINK}CommonUI:Common.ConfTraining.navweight.
param
Training.treebranch.1.TrainingUI.navweight.param=11000

The placement of the UI on the navigation tree is controlled by these properties. To determine the weight
for your UI, find the weight of the 2 UIs that yours will be between, and use a weight that is at the midway
point (approxmiately).

For example, if I am adding a new Interface UI named "D-Switch" that will be under Network, I find the
navweight for the UI above (COOP as of Feb 2007) which is 11400, then find the navweight for the UI
below (Interpay BIM as of Feb 2007) which is 11600, then use a value approximately in the middle,
11500.

The 2 properties that would have been consulted for this example are:

IfCoop.treebranch.2.INTFCOOP.navweight.param=11400
IfInterpay.treebranch.2.INTFIPAY.navweight.param=11600

10-50
If your UI is being added to the end of a list of UIs, find the weight of the last UI and add 200 to it. For
example,"X-Switch" added under Network would follow LINK ISO (as of Feb 2007) which has a weight
11800, thus the weight for "X-Switch" would be 12000.

If your UI is being added to the beginning, find the weight of the first UI, and subtract 200. If your UI is
the first in the group, start with the value 11000.

If you are adding a UI that needs a common tree node (i.e., more than 1 UI will be grouped under a
common node), make sure that the navweight for the common tree node is the same in both packages. For
example, I am adding 2 UIs that I want to group under System Ops, under a common node named
Interface. The 2 UIs are Interface Totals and Interface Status. Here are the properties. Notice that the
first navweight property references an already defined property in CommonUI.properties. Notice that the
value for the second navweight property is the same for both UIs (-9550).

InterfaceStatus.rootbranch.InterfaceStatusUI.navweight.param={LINK}CommonUI:Common.Sy
stemOperations.navweight.param
InterfaceStatus.treebranch.0.InterfaceStatusUI.navweight.param=-9550
InterfaceStatus.treebranch.1.InterfaceStatusUI.navweight.param=11000

InterfaceTotals.rootbranch.InterfaceTotalsUI.navweight.param={LINK}CommonUI:Common.Sy
stemOperations.navweight.param
InterfaceTotals.treebranch.0.InterfaceTotalsUI.navweight.param=-9550
InterfaceTotals.treebranch.1.InterfaceTotalsUI.navweight.param=11100

10.4 Help Properties

The samples in this section come from the Currency Conversion Rate UI, package
es.desktop.multicurrency, property file name CurrencyConv.properties.

10.4.1 General Help Properties

There are three properties related to help.

CurrencyConv.helpset={LINK}CommonUI:Common.helpset
CurrencyConv.helpTopics.helpID={LINK}CommonUI:Common.helpTopics.helpID
CurrencyConv.helpID=ui_currency_conversion_rate_configuration

Note: As of version 09.2, the helpset home property (helpTopics.helpID) should specify the link to the
CommonUI property entry rather than aci_help_home.

CurrencyConv.helpTopics.helpID=aci_help_home
CurrencyConv.helpTopics.helpID={LINK}CommonUI:Common.helpTopics.helpID

10-51
The first property identifies the helpset jar. It is usually one of two values, either the one used by the
Currency Conversion Rate UI or if the UI is a TSS UI:

={LINK}CommonUI:Common.tss.helpset

The second property identifies helpset home. It is usually one of two values, either the one used by the
Currency Conversion Rate UI or if the UI is a TSS UI:

={LINK}CommonUI:Common.tss_helpTopics.helpID

The third property identifies the help specific to this UI. This value is provided by the help author.
Consult with the lead of your project to determine the help author.

10.4.2 Component Help Properties

Each non-table visual component requires a property for context help. Usually the property is defined in
the UI Property File, but occasionally it is defined in CommonUI.properties or
CommonCodeValues.properties.

BASE24-eps 06.2 Version Note:

As of the BASE24-eps Version 06.2, we have moved some of the entries that were considered to be
Version Independent from the CommonCodeValues property file into a new CommonCodeValues
property file extension named CommonCodeValues+INTF.properties. This property file can be found
under the …\ui\if\ folder and is packaged in the new UI application jar, ifDT.jar, found under the
…\ui\Repository\ES\Desktop\Applications\ folder.

The Currency Conversion Rate UI has two non-table visual components. They are labeled Institution ID
and Source Currency. The context help property for Institution ID is as follows:

CurrencyConv.institutionList.helpID=institution_ID

This property follows the format:

aaaa.bbbb.cccc=dddd

Where aaaa (CurrencyConv in example) is the property file name.

Where bbbb is the UI Component name defined in the UI Layout file.

Where cccc must be the value helpID.

Where dddd is equal to the help ID received from the help author.

There is no help property for Source Currency. This is because it’s help property is defined in
CommonCodeValues+INTF.properties.

10-52
CurrencyCodes.helpID=currency_code

The tie from the visual component to this help property occurs as a result of the execution of the following
two instructions in CurrencyConvRateComponentBuilder:

SelectionComboBoxNoEdit scb =
(SelectionComboBoxNoEdit)getEComponent( "sourceCurrencyList" );
scb.setLocaleKey( "CurrencyCodes", "CommonCodeValues" );

10.4.3 Table Column Help Properties

Each table column requires a property for context help. The user invokes help on a table column by
clicking into a cell under the column, then pressing F1. Usually the help property is defined in the UI
Property File, but occasionally it is defined in CommonUI.properties or CommonCodeValues.properties
(or the CommonCodeValues+INTF.properties if it’s related to properties that are Version Independent).

The help property and the columnEditorLocaleKey in the Table Property File must match. The System
Algorithm UI (package es.desktop.systemprefix) contains three table columns.

Column Help Property columnEditorLocaleKey in Table Property

Properties Location
Low SystemAlgorithm.LowPrfxHeader Column.columnEditorLocaleKey SystemPrefix
Prefix .helpID=f_low_prefix =SystemAlgorithm.LowPrfxHeader
High SystemAlgorithm.HighPrfxHeader Column.columnEditorLocaleKey SystemPrefix
Prefix .helpID=f_high_prefix =SystemAlgorithm.HighPrfxHeader
PAN SystemAlgorithm.PANLgthHeader Column.columnEditorLocaleKey SystemPrefix
Length .helpID=f_pan_length =SystemAlgorithm.PANLgthHeader

10.5 Tying a ManagedList to a Combo Box Component

Many of the BASE24-eps UIs maintain a list of data. Generally, these lists are represented by instances of
ManagedList. ManagedList instances are available to other UIs that may have a need for the same list.
Additionally, ManagedList instances allow two instances of the same UI to use a single list. For
example, a user may bring up two instances of the Training UI, but the two instances are using the same
ManagedList instance to populate the Profile combo box.

There are three ManagedList instances used by the Training UI:

10-53
Training UI List This list is maintained by the Training UI, and it is used to populate
the Profile combo box. It relates to the profiles on the truign data
source.

Issuer Route Profile List This list is maintained by the Routing Authorizers UI. It relates to
the unique issuer routing profiles defined on the routed data source.
The Training UI uses this list to populate the Issuer Route Profile
combo box on the General Information tab.

Acquirer Route Profile List This list is maintained by the Acquirer Routing Profile UI. It relates
to the profiles on the artpd data source. The Training UI uses this
list to populate the Acquirer Profile column combo box on the
Acquirer Table tab.

The Profile combo box needs to be tied to the Training UI List. The property that accomplishes this is the
following:

Training.profileList.managedList=TrainingUIList

This property follows the format:

aaaa.bbbb.cccc=dddd

Where aaaa (Training in example) is the property file name.

Where bbbb is the UI Component name defined in the UI Layout file.

Where cccc must be the value managedList.

Where dddd is equal to the UI list name constant value for the list.

The Issuer Route Profile combo box needs to be tied to the Issuer Route Profile list. The property that
accomplishes this is the following:
Training.issuerRouteList.managedList=routingPrflList

In the case where the Combo Box component is an optional user field, the (none) option needs to be added
to the list. The (none) option allows the user to specify no selection, and the result is an empty element is
sent to the server. The following property can be used to add the (none) option to the Issuer Route Profile
combo box.

Training.routingPrflList.managedListNoneOption=true

This property follows the format:

aaaa.bbbb.cccc=dddd

10-54
Where aaaa (Training in example) is the property file name.

Where bbbb is equal to the UI name constant value for the list.

Where cccc must be the value managedListNoneOption.

Where dddd is the value true.

Tying a list to a table column combo box is covered in the section titled Table Property File.

10.6 UI Title

There are two title properties that are defined for a UI. The title property is displayed on the UI title bar.
The error title property is displayed in error dialogs.

Training.title=Training UI
Training.errorTitle=Training UI - Error

This property follows the format:

aaaa.bbbb = cccc

Where aaaa (Training in example) is the property file name.

Where bbbb must equals the value title or errorTitle depending on which property is being defined.

Where cccc is the text for the title.

10.7 Tabbed Pane Titles

The Training UI makes use of a tabbed pane containing two tabs. The properties for the titles for these
tabs are:

Training.GeneralPanelName.text=General Information
Training.AcquirerTablePanelName.text=Acquirer Table

These properties follow the format:

aaaa.bbbb.cccc=dddd

Where aaaa (Training in example) is the property file name.

Where bbbb is the panel name as defined in the UI Layout file.

10-55
Where cccc must be the value text.

Where dddd is the text for the tab title.

10.8 Visual Component Labels

Properties are required for the labels that are defined on the UI. The properties for the Training UI labels
are:

Training.profileLabel.text=Profile
Training.spacerLabel1.text=

Training.descriptionLabel.text=Description
Training.issuerRouteLabel.text=Issuer Route Profile
Training.countryCodeLabel.text=Country Code
Training.spacerLabel2.text=

These properties follow the format:

aaaa.bbbb.cccc=dddd

Where aaaa (Training in example) is the property file name.

Where bbbb is the component name as defined in the UI Layout file.

Where cccc must be the value text.

Where dddd is the text for the label.

Two of the labels above have no text. These are spacerLabel1 and spacerLabel2. These are filler
labels used to balance the layout of the visual components.

10.9 Hyperlink Labels

Hyperlink labels are used to allow a user to hyperlink to another UI. The Training UI label Issuer Route
Profile is defined as a framework.desktop.ecomponents.EHyperLinkLabel. The additional properties
that are required for the hyperlink label named issuerRouteLabel are the following:

Training.issuerRouteLabel.hyperTarget=routingUI
Training.issuerRouteLabel.hyperContextField=issuerRouteList
Training.issuerRouteLabel.toolTipText=Click here to navigate to the Routing Authorizers UI

The hyperTarget property is used to identify the target UI for the hyperlink. The related text is a UI name
constant value. The value “routingUI” results in the user being taken to the Routing Authorizers UI when
the hyperlink is clicked.

10-56
Context is typically passed to the target UI. Context allows the target UI to be positioned to a specific
view. The hyperContextField property identifies the component to use to retrieve the context for the
hyperlink. The related text is a component defined in one of the UI Layout files. In the case of the
Training UI, the hyperContextField property points at the Issuer Route Profile combo box which is
defined in TrainingGeneral.cfg. When the user clicks the hyperlink, the value of the Issuer Route Profile
combo box is passed to the Routing Authorizers UI, and the UI sets the user’s view to this context.

If multiple components make up the context to be passed, the hyperContextField is replaced by two other
properties, hyperHashMapContextField and hyperHashMapContextConstant. The Card UI hyperlinks
to the Usages UI and passes multiple context values. The properties are as follows:

CardCnfg.hblUsages.toolTipText=Click here to navigate to the Usages UI.

CardCnfg.hblUsages.hyperTarget=UsagesUI
CardCnfg.hblUsages.01.hyperHashMapContextField=cboInstID
CardCnfg.hblUsages.01.hyperHashMapContextConstant=institutionID
CardCnfg.hblUsages.02.hyperHashMapContextField=txtCardNum
CardCnfg.hblUsages.02.hyperHashMapContextConstant=cardNumber
CardCnfg.hblUsages.03.hyperHashMapContextField=txtMemberNum
CardCnfg.hblUsages.03.hyperHashMapContextConstant=memberNumber

hblUsages is the component name as defined in the UI Layout file. The 01, 02, and 03 values must be
unique for each additional context component. The hyperHashMapContextField properties identify the
components to use to retrieve the context for the hyperlink. The hyperHashMapContextConstant
properties identify constant values that are associated with the specific context. These constants can be
found in ESDesktopConstants.

Tooltip text is generally specified for a hyperlink, with the related text telling the user which UI is
activated when the hyperlink is clicked. The toolTipText property provides for the specification of tooltip
text.

10.10 Localized Lists

A localized list is a static list, where the list entries are defined in a property file. Examples of this type of
list from the CommonCodeValues.properties file include the AcctStatus list and the StateCode list.

The Training UI uses the CommonCodeValues+INTF CountryCode list to populate the Country Code
combo box. The tie of this list to the Country Code combo box is accomplished via java instructions that
execute as part of the constructor of TrainingBuilder.

The Training UI also uses a localized list to populate the Acquirer Type column combo box on the
Acquirer Table panel. The tie between this list and the Acquirer Type combo box is described in the
section titled Table Property File. The localized list contains the following entries:

Training.Type.1.text=Type 1
Training.Type.2.text=Type 2
Training.Type.3.text=Type 3
Training.Type.4.text=Type 4
Training.Type.5.text=Type 5

10-57
Training.Type.6.text=Type 6
Training.Type.7.text=Type 7
Training.Type.8.text=Type 8
Training.Type.9.text=Type 9
Training.Type.10.text=Type 10

These properties follow the format:

aaaa.bbbb.cccc.dddd=eeee

Where aaaa (Training in example) is the property file name.

Where bbbb is an identifier for this list. As will be seen in the section titled Table Property File, this
identifier is used to tie the Acquirer Type combo box to this list.

Where cccc is the value to be transmitted to the server, so that if the user selects Type 2, the value
transmitted to the server will be 2.

Where dddd must be the value text.

Where eeee is the value the user will see when the combo box list is dropped down.

10.11 Table Column Headers

The column headers for table columns are defined in the property file. The Training UI Acquirer Table
tab contains a table with three columns. The properties are:

Training.acquirerTypeHeader.text=<html><center>Acquirer<BR>Type</center></html>
Training.acquirerProfileHeader.text=<html><center>Acquirer<BR>Profile</center></html>
Training.descriptionHeader.text=<html><center>Description</center></html>

These properties follow the format:

aaaa.bbbb.cccc=dddd

Where aaaa (Training in example) is the property file name.

Where bbbb is the identifier for this column. As will be seen in the section titled Table Property File, this
identifier is used in the table property file to associate a column header to a column.

Where cccc must be the value text.

Where dddd is the column header text.

10-58
10.12 Key Components

Components that are considered key components are treated differently than non-key components when it
comes to determining whether the user has unsaved changes. For example, when the user closes a UI
window, the UI needs to determine whether there are any unsaved changes. Key components are
disregarded when it comes to determining unsaved changes.

The Training UI contains one key component which is Profile. The property which denotes this is:

Training.profileList.keyField=yes

This property follows the format:

aaaa.bbbb.cccc=dddd

Where aaaa (Training in example) is the property file name.

Where bbbb is the component name as defined in the UI Layout file.

Where cccc must be the value keyField.

Where dddd must be the value yes.

10.13 Text for the Delete Action

The standard text for the delete action (trash can icon) is “Delete”. There have been occasions when a
user attempts to delete a table row, but selects the delete action which deletes the entire entity (i.e.,
Interface, Profile, etc.). Our solution to this is to override the text used for the delete action. The override
is accomplished via a property

Training.deleteTextOverride.text=Delete Training Configuration

This property follows the format:

aaaa.bbbb.cccc=dddd

Where aaaa (Training in example) is the property file name.

Where bbbb must be the value deleteTextOverride.

Where cccc must be the value text.

Where dddd is text describing what is actually being deleted. Our general approach is to use the text
“Profile” if it is a profile UI, otherwise use appropriate text.

10-59
10.14 OLTP Warmboot Hyperlink Properties

As of verion 06.2, many UIs include the oltpRebuild action on the toolbar and right-click. The UIs that
include this action are those UIs that affect a data source that has a related OLTP. There are properties
needed to define the context used in the hyperlink to the OLTP Warmboot Management UI. One property
is defined for each data source that has a related OLTP. The Training UI isn’t a real UI, so there is no data
source or related OLTP, but for the sake of example, let’s assume the Training UI affects 2 data sources
with related OLTPs, and the data source names are:

TRAINING
TRAINING_ACQUIRER

The corresponding properties would be:

Training.wbootDataSource.0.param=TRAINING
Training.wbootDataSource.1.param=TRAINING_ACQUIRER

This property follows the format:

aaaa.bbbb.cccc.dddd=eeee

Where aaaa (Training in example) is the property file name.

Where bbbb must be the value wbootDataSource.

Where cccc is a number that is 0 for the first data source and is incremented by 1 for subsequent data
sources.

Where dddd must be the value param.

Where eeee is the data source assign name.

10.15 Institution Rendering

As of version 07.4, the super class provides a rendering implementation for institution fields. The
behavior is to render the institution ID followed by the institution name. A property is used to activate the
behavior.

The Journal TDE Suppresion UI field named Issuer ID is an example of a field that uses this feature. The
property which denotes this is:

JournalTdeSuppression.fieldIssInstId.useInstNameRenderer.param=true

This property follows the format:

10-60
 aaaa.bbbb.cccc.dddd=eeee

Where aaaa (JournalTdeSuppression in example) is the property file name.

Where bbbb is the component name as defined in the UI Layout file.

Where cccc must be the value useInstNameRenderer.

Where dddd must be the value param.

Where eeee must be the value true.

There is a second property that is typically used in conjunction with useInstNameRenderer, that dictates
the ManagedList name used to distinguish whether an item is configured. This property is named
distinguishUnconfiguredListName.

In the case of the Journal TDE Suppression UI, the Issuer ID drop down items render in normal font if
configured, and italics if not configured. The ManagedList name used to determine this distinction is
JournalTdeList, thus the property is as follows:

JournalTdeSuppression.fieldIssInstId.distinguishUnconfiguredListName.param=JournalTdeList

This property follows the format:

aaaa.bbbb.cccc.dddd=eeee

Where aaaa (JournalTdeSuppression in example) is the property file name.

Where bbbb is the component name as defined in the UI Layout file.

Where cccc must be the value distinguishUnconfiguredListName.

Where dddd must be the value param.

Where eeee is the ManagedList name used to distinguish whether a list item is configured.

10.16 Summary of UI Property File Keywords

This section documents the use of property file keywords. The full set of keywords is summarized in the
following table for convenience.

Keyword Affect Reference

UI Actions Keywords
toolbar Controls the actions that Within the action properties, do a

10-61
 Keyword Affect Reference
will appear on the toolbar. search for .toolbar in any UI
property file.
popupMenu Controls the actions that Within the action properties, do a
will appear on the right search for .popupMenu in any UI
click menu. property file.

General Localization Keywords

text Specifies the text All UI property files have .text
associated with labels, properties.
localized lists, column
headers, action text, etc.
icon Specifies the icon to use Within the action properties, do a
with the action or search for .icon in any UI
component. property file.
tooltiptext Specifies the tooltiptext to Within the action properties, do a
use with the action or search for .tooltiptext in any UI
component. property file.
accelerator Specifies the accelerator Within the action properties, do a
to use with the action. search for .accelerator in any UI
property file.

UI Navigation Keywords
uilist Specifies each UI that’s Within the navigation localization
navigation is defined. properties, do a search for uilist
in any UI property file.
securityTaskID Specifies the variable Within the navigation localization
portion of the security properties, do a search for
task ID. securityTaskID in any UI
property file.
rootbranch Specifies the main Within the navigation localization
navigation branch for this properties, do a search for
UI. rootbranch in any UI property
file.
treebranch One or more of these Within the navigation localization
properties specifies the properties, do a search for
additional branches that treebranch in any UI property
make up the navigation. file.

UI Help Keywords
helpset Identifies the helpset jar Do a search for .helpset in any UI
for this UI. property file.
helpTopics Identifies the helpset Do a search for .helptopics in any
home for this UI. UI property file.
helpID Identifies the context help Do a search .helpID in any UI
file for the component property file. There will be

10-62
 Keyword Affect Reference
that corresponds to this several covering the UI itself,
property. table columns, and individual UI
components.

ESFindDialog Keywords
findDialog.startKeyWidth Specifies the width of the CardCnfg.properties
Start Key field on the
Find dialog.
findDialog.endKeyWidth Specifies the width of the CardCnfg.properties
End Key field on the Find
dialog.
findDialog Indentifies which column InterfaceTerminal.properties
.startEndKeyCorrespondingColumn in the table corresponds to
the Start/End Key fields.

List Retrieval Keywords

listRequestDataType Identifies the data type for Most UIs use this property.
the list request.
listRequestElement Identifies the element Most UIs use this property.
name in the list request.
listResponseElement Identifies the element Most UIs use this property.
name in the list response.

Miscellaneous Keywords
isListPackageOptional Dictates whether a SystemPrefix.properties
ManagedList is optional.
If this property is
specified = true, the UI
will initialize normally,
even if the package
owning list is not present.
managedList Specifies the AcquirerTransAllowed.properties
ManagedList to use as the ActionCode.properties
combo box list model.
Many others.
managedListNoneOption Results in the {none} item InstitutionCnfg.properties
being added to the drop ChannelProfile.properties
down list.
managedListAnyOption Results in the ANY item ATMReceiptFormat.properties
being added to the drop
down list.
title Specifies the title for this All UI property files contain the
UI. .title property.
hyperTarget Specifies the UI that is InstitutionCnfg.properties
instantiated when the Limit.properties

10-63
 Keyword Affect Reference
hyperlink is clicked.
Many others.
hyperContextField Specifies the component InstitutionCnfg.properties
to use to retrieve the Limit.properties
context for the hyperlink.
Many others.
hyperHashMapContext Field Used when the hyperlink CardCnfg.properties
context comes from PositiveBalance.properties
multiple components.
hyperHashMapContext Constant The key word portion of CardCnfg.properties
the hash map. PositiveBalance.properties
keyField Specifies this component AcquirerTransAllowed.properties
as a key field, which ActionCode.properties
results in this component
being added to the key Many others.
change group instead of
the detail change group.
autoResponse Specifies that a view ATMChannelAdmin.properties
request be sent to the
server following the
receipt of a response of
this type.
errorStatusOnNewEntry Denotes whether the CardCnfg.properties
status bar message that is
displayed when the user
enters a new key is
displayed in red (value of
true). The default is black
which equates to a
property value of false.
clearOnNewEntry Denotes whether the UI CardCnfg.properties
fields are cleared when
the user enters a new key.
The default is false.
noSelect Denotes whether a combo As of version 6.2, no UIs use this
box is set to the -1 state property.
when the value from the
server isn’t in the model.
The default is true.
conditionalNoSelect Denotes whether the “not PrefixConfig.properties.
in model” condition
should be ignored if the
value from the server is
empty. Used for
EComboBox instances

10-64
 Keyword Affect Reference
that have the {none}
option specified. The
default is false.
uiNoSelect Denotes that the “not in ATMChannelMgmtAll.properties
model” condition should
be checked for by this UI.
The default is true.
wbootDataSource Defines data sources that Many UIs contain this property.
are affected by this UI Reference ActionCode.properties.
that have related OLTPs.
A UI may have 0 to many
of these properties.
deleteTextOverride Specifies the text to use ActionCode.properties
for the delete action.
requiredApp Specifies that this UI will MerchantPrograms.properties.
only be added to the
navigation tree if the
application name
specified by the property
is present.
moduleID Specifies that this UI will InterfaceTerminal.properties.
only be added to the
navigation tree if the
module ID specified by
the property is present in
the response to
getModulesList.
useInstNameRenderer Specifics that this JournalTdeSuppression.properties
component use the super
class institution rendering
behavior.
distinguishUnconfiguredListName Used in conjunction with JournalTdeSuppression.properties
useInstNameRenderer.
Specifies the
ManagedList name used
to distinguish a
configured.
requiredEPSVersionLevel Used to specify that a UI
only be added to the
navigation tree of sites at
a certain EPS version
level.

10-65
11 Table Property File

11.1 Overview
There will be a separate table property file for each GenericETableMgr instance used by a UI. The
Acquirer Table tab of the Training UI uses an instance of GenericETableMgr. The property file is
named TrainingAcquirerTable.properties.

11.2 Table Parameters

The table section keywords are defined in GenericETableConstants. Refer to the
GenericETableConstants javadoc for information and a usage example of each property.

GenericETableConstants Property

TABLE_PROPERTY_FILE TableParameters.propertyFile
TABLE_AUTO_RESIZE TableParameters.autoResize
TABLE_AUTO_ROW_ADD TableParameters.autoRowAdd
TABLE_ROW_KEY TableParameters.rowKey
TABLE_ADD_ROW_ON_EMPTY_TABLE TableParameters.addRowOnEmptyTable
TABLE_GENERIC_DATA_OBJECT_TYPE TableParameters.genericDataObjectType
TABLE_SCREEN_DATA_OBJECT_TYPE TableParameters.screenDataObjectType
TABLE_SEND_ALL_ROWS_ON_UPDATE TableParameters.sendAllRowsOnUpdate
TABLE_SEND_ALL_ROWS_WITH_REQUEST_DATA TableParameters.sendAllRowsWithRequestData
TABLE_LOAD_TABLE_UNTIL_FILE_EXHASUTED TableParameters.loadTableUntilFileExhausted
TABLE_MIN_ROWS_DISPLAYED TableParameters.minRowsDisplayed
TABLE_MAX_ROWS_DISPLAYED TableParameters.maxRowsDisplayed
TABLE_MIN_ROW_HEADER_WIDTH TableParameters.minRowHeaderWidth
TABLE_MAX_ROW_HEADER_WIDTH TableParameters.maxRowHeaderWidth
TABLE_READ_ONLY TableParameters.readOnly
TABLE_ROW_HEIGHT TableParameters.rowHeight
TABLE_MAX_ROWS_ALLOWED TableParameters.maxRowsAllowed
TABLE_ROW_ID_ELEMENT TableParameters.rowIDElement
TABLE_ALLOW_ROW_COPY TableParameters.allowRowCopy
TABLE_ALLOW_SELECT_ALL TableParameters.allowSelectAll
TABLE_DISPLAY_ROW_ACTIVITY TableParameters.displayRowActivity
TABLE_USE_SIZE_LISTENER TableParameters.useSizeListener
TABLE_RESET_IS_UNDO_ALL_ROWS TableParameters.resetIsUndoAllRows
TABLE_VARIABLE_ROW_HEIGHT TableParameters.variableRowHeight
TABLE_VARIABLE_ROW_LINES_MAX TableParameters.variableRowLinesMax
TABLE_ALTERNATING_ROW TableParameters.alternatingRow
TABLE_ALTERNATING_ROW_COLOR TableParameters.alternatingRowColor
TABLE_USE_DEFAULTS TableParameters.useDefaults
TABLE_DISABLE_HIDDEN_ON_NO_ROWS_SELECTED TableParameters
.disableHiddenOnNoRowsSelected
TABLE_ACTIONS_PROPERTY_PREFIX TableParameters.actionsPropertyPrefix
TABLE_HAS_TOOLBAR TableParameters.hasToolbar
TABLE_USE_ACCT_TYPE_BEHAVIOR TableParameters.useAcctTypeBehavior
TABLE_USE_ACCT_TYPE_RENDERER TableParameters.useAcctTypeRenderer
TABLE_PROC_CODE_KEY TableParameters.procCodeKey

11-66
TrainingAcquirerTable.properties defines the following table parameters.

[TableParameters]
TableParameters.propertyFile=Training
TableParameters.screenDataObjectType=TrainAcqTblScreenData
TableParameters.rowKey=TrainAcqTblScreenDetails

Only three of the TableParameters are defined, which means the rest of the parameters will be populated
with defaults. This is typically the case.

11.3 Supported Editors

When table columns are being defined, one of the column parameters that must be specified is the column
editor. The editor keywords are defined in GenericETableConstants. Refer to the
GenericETableConstants javadoc for behavior information.

GenericETableConstant Value of Constant

EDITOR_RENDERER_DEFAULT default
EDITOR_RENDERER_ECOMBOBOX eComboBox
EDITOR_RENDERER_ECOMBOBOX_LISTDATA eComboBoxListData
EDITOR_RENDERER_ECOMBOBOX_LOCAL eComboBoxLocal
EDITOR_RENDERER_ETEXTFIELD eTextField
EDITOR_RENDERER_ECHECKBOX eCheckBox
EDITOR_RENDERER_ELABEL eLabel
EDITOR_RENDERER_EDATALABEL eDataLabel
EDITOR_RENDERER_DATE_SPINNER eDateSpinner
EDITOR_RENDERER_TIME_SPINNER eTimeSpinner
EDITOR_RENDERER_SPINNER eSpinner
EDITOR_RENDERER_HEX eTextFieldHex
EDITOR_RENDERER_INTEGER eTextFieldInt
RENDERER_READ_ONLY eReadOnly
EDITOR_RENDERER_DATE_TEXTFIELD eDateTextField
EDITOR_RENDERER_TIME_TEXTFIELD eTimeTextField
EDITOR_RENDERER_ETEXTFIELDZOOM eTextFieldZoom
EDITOR_RENDERER_ECURRENCYFIELD eCurrencyField
EDITOR_RENDERER_ETABLEZOOM eTableZoom
EDITOR_RENDERER_ETABLEFIND eTableFind
RENDERER_ROW_HEADER rowHeader
RENDERER_SELECTION_COLUMN selectionColumn
EDITOR_RENDERER_ETEXTAREA eTextArea
EDITOR_RENDERER_ETIMESTAMPLABEL eTimestampLabel
EDITOR_RENDERER_EDATALABEL_INSTRM_TYPE eDataLabelInstrmType
EDITOR_RENDERER_EDATALABEL_INSTITUTION eDataLabelInstitution

11.4 Supported Editor Optional Keywords

11-67
Some editor types support optional keywords to control alignment, font, and other miscellaneous
behavior. The optional keywords are defined in GenericETableConstants. Refer to the
GenericETableConstants javadoc for behavior information and to find out which editor types support the
optional keyword.

GenericETableConstant Value of Constant

FONT_OPTION font=
FONT_SIZE fontSize=
ECHECKBOX_BINARY_OPTION binary
ALIGN_OPTION align=
SIZE_LIMIT_OPTION sizeLimit=
NONEDITABLE_OPTION noneditable
COLUMN_REPAINT_ORDER_OPTION order=
COLUMN_REPAINT_ORDER_PREFIX prefix=
COLUMN_REPAINT_ORDER_SUFFIX suffix=

11.5 Column Parameters

The column section keywords are defined in GenericETableConstants. Refer to the

GenericETableConstants javadoc for information and a usage example of each property.

GenericETableConstant Property

COLUMN_KEY Column1.columnKey
COLUMN_KEY_ORIGINAL_VALUE Column1.columnKeyOriginalValue
COLUMN_REPEAT_COUNT Column1.columnRepeatCount
COLUMN_HEADER_LOCALE_KEY Column1.columnHeaderLocaleKey
COLUMN_HEADER_PROPERTY_FILE Column1.columnHeaderPropertyFile
COLUMN_EDITOR Column1.columnEditor
COLUMN_RENDERER Column1.columnRenderer
COLUMN_NON_EDITABLE_RENDERER Column1.columnNonEditableRenderer
COLUMN_MANAGED_LIST Column1.columnManagedList
COLUMN_EDITOR_NONE_OPTION Column1.columnEditorNoneOption
COLUMN_ACCESS Column1.columnAccess
COLUMN_WIDTH Column1.columnWidth
COLUMN_EDITOR_LOCALE_KEY Column1.columnEditorLocaleKey
COLUMN_EDITOR_PROPERTY_FILE Column1.columnEditorPropertyFile
COLUMN_KEY_FIELD_ACCESS Column1.columnKeyFieldAccess
COLUMN_OPTIONAL_INPUT Column1.columnOptionalInput
COLUMN_SORT Column1.columnSort
COLUMN_CLEAR_ROW_SUPPORTED Column1.columnClearRowSupported
COLUMN_CUSTOM_PARAM Column1.columnCustomParam
COLUMN_COPY_ROW_SUPPORTED Column1.columnCopyRowSupported
COLUMN_USE_DEFAULT Column1.columnUseDefault
COLUMN_GROUP_HEADER_LOCALE_KEY Column1.columnGroupHeaderLocaleKey
COLUMN_GROUP_HEADER_PROPERTY_FILE Column1.columnGroupHeaderPropertyFile
COLUMN_ROW_HEADER_LOCALE_KEY Column0.rowHeaderLocaleKey
COLUMN_ROW_HEADER_PROPERTY_FILE Column0.rowHeaderPropertyFile
COLUMN_ROW_HEADER_EDITOR_RENDERER Column0.rowHeaderEditorRenderer

11-68
 GenericETableConstant Property
COLUMN_ROW_HEADER_ROW_KEY Column0.rowHeaderRowKey
COLUMN_ROW_HEADER_EDITOR_RENDERER Column0.rowHeaderEditorRenderer
FIXED_ROW_ACCESS Column0.row0.rowAccess
FIXED_ROW_ACCESS_AT_COLUMN Column0.row1.rowAccessAtColumn.Column5
FIXED_ROW_CURRENT_ROW_POINTER Column0.row0.rowCurrentRowPointer
FIXED_ROW_OPTIONAL_INPUT Column0.row0.rowOptionalInput
FIXED_ROW_OPTIONAL_INPUT_AT_COLUMN Column0.row1.rowOptionalInputAtColumn.Column5
COLUMN_REPAINT_PARMS Column1.columnRepaintParms=order=true

TrainingAcquirerTable.properties contains definitions for three columns.

11.5.1.1 Acquirer Type Column

The section header for the Acquirer Type column is shown below. Column section headers must be
unique and must increment by 1.

[Column1]

The columnKey must be an element defined in the ESData Screen Data definition. columnKey allows the
mapping between the table and the ESData definitions to occur.

Column.columnKey=truitsAcquirerType

The value specified by columnHeaderLocaleKey relates to a column header property in the UI Property
File.

Column.columnHeaderLocaleKey=Training.acquirerTypeHeader

The value specified by columnEditor must be one of the supported editors, or must be a custom cell
editor. The Acquirer Type column uses a framework.desktop.ecomponent.EComboBox with a localized
list. The “,2” after editor defines the number of periods that precede the server value in the localized list.

Column.columnEditor=eComboBoxLocal,2

The list tied to the column editor combo box is determined by the columnEditorLocaleKey property.
With this property you specify the locale key of the localized list. The locale key is the property name up
to the period before the server value. In the Training UI case, the locale key for the localized list values is
Training.Type.

Column.columnEditorLocaleKey=Training.Type

The columnEditorPropertyFile property identifies the property file that contains the localized list.

11-69
Column.columnEditorPropertyFile=Training

The columnAccess value of “rw” identifies this column as read and write.

Column.columnAccess=rw

The columnKeyFieldAccess value of “ro” specifies that this column is read only once the row has been
saved.

Column.columnKeyFieldAccess=ro

The columnOptionalInput property specifies that this column requires entry before a new row can be
inserted.

Column.columnOptionalInput=r

11.5.1.2 Acquirer Profile Column

The Acquirer Profile column differs from the Acquirer Type column in the following ways:

- The columnEditor is specified as eComboBox instead of as eComboBoxLocal,2. This is because

the combo box associated with this column uses a ManagedList instance instead of a localized list.
- There is no columnEditorLocaleKey property. This is because the combo box associated with
this column does not use a localized list.
- There is no columnEditorPropertyFile property. Since a localized list isn’t used, there is no
property file specification required.
- This column uses the proprety columnManagedList. This property value is a UI list name
constant that identifies the ManagedList to use to populate the combo box.
[Column2]
Column.columnKey=truitsAcquirerProfile
Column.columnHeaderLocaleKey=Training.acquirerProfileHeader
Column.columnEditor=eComboBox
Column.columnManagedList=acqPrflStringList
Column.columnAccess=rw
Column.columnKeyFieldAccess=rw
Column.columnOptionalInput=r

In the case where the Combo Box component is an optional user field, the (none) option needs to be added
to the list. The (none) option allows the user to specify no selection, and the result is that an empty
element is sent to the server. The following column property can be used to add the (none) option to the
Acquirer Profile combo box.

Column.columnNoneOption=true

The Description column differs from the other columns in that the columnEditor is an eTextField
instead of a combo box.
[Column3]
Column.columnKey=truitsDescription

11-70
Column.columnHeaderLocaleKey=Training.descriptionHeader
Column.columnEditor=eTextField
Column.columnAccess=rw
Column.columnKeyFieldAccess=rw
Column.columnOptionalInput=r

11.6 Visual Table Configuration

This section outlines the table and column configuration properties that can be utilized to provide the
following visual table attributes:

- Display the rows with a variable row height. The rows can paint as 1 or more lines (up to some
configurable max) depending on the size of the data.
- Use of an alternating row background color to better distinguish rows.
- Allow the table activity icon to be omitted.
- Provide an option so that when the user clicks into a cell, a Text Zoomer dialog is displayed. This
is used in the case where the amount of data exceeds the max, even though we are allowing a multi
line.
- The UI intelligently sizes the columns based on the size of the data of each column.
- Support of tooltip text on a cell basis populated by ESData values. This allows the ability to
provide more information or related information on a cell basis.

11.6.1 Visual Table Parameters

GenericETableConstant Constant Value Default Value

TABLE_VARIABLE_ROW_HEI TableParameters.variableRowHe false
GHT ight

TABLE_VARIABLE_ROW_LIN TableParameters.variableRowLi 2
ES_MAX nesMax
TABLE_ALTERNATING_ROW TableParameters.alternatingRo false
w
TABLE_ALTERNATING_ROW_ TableParameters.alternatingRo If not defined the
COLOR wColor alternating row color
defaults to the color
When included the standard specified in the
java colors can be specified CommonUI.properties file
or the “custom” option can be entry below:
specified with the r,g,b
values included. Common.TableAlternatingRow
Color=Custom,r=240,g=240,b
Example of custom color: =241
TableParameters.alternatingRo
wColor=custom,r=240,g=240,b=2
41

Example of standard color:

TableParameters.alternatingRo
wColor= blue

red

11-71
 GenericETableConstant Constant Value Default Value
green
blue
yellow
black
cyan
magenta
orange
pink
darkgray
lightgray
white
CUSTOM_COLOR_OPTION Custom N/A

CUSTOM_COLOR_BLUE_OPTI b= N/A
ON
CUSTOM_COLOR_GREEN_OPT g= N/A
ION
CUSTOM_COLOR_RED_OPTIO r= N/A
N

11.6.2 Visual Column Parameters

GenericETableConstant Value of Constant Default Value

COLUMN_TOOLTIP_KEY columnToolTipKey

Example:
Column1.columnToolTipKey=IssRtePrfl
COLUMN_EDITOR Column.columnEditor N/A
(Must be
Example: specified)
Column.columnEditor=eTextFieldZoom,non
editable

COLUMN_RENDERER Column.columnRenderer N/A

(Must be
The columnRenderer specified needs to specified)
be the eTextArea in order to allow the
multi-line row display. The
noneditable option is specified if
this is a read-only cell.

Example:
Column.columnRenderer=eTextArea,nonedi
table
COLUMN_ACCESS Column.columnAccess rw

Example:
Column.columnAccess=rw

11-72
11.6.3 Visual Table Configuration Example

Specifying rows with variable row height. The rows will paint as 1 or more lines depending on
the size of the data. This will also size the columns based on the size of the data of each
column.

Set the table variableRowHeight parameter to true. To configure the maximum number of
lines to display per row other than the default which is 2, set the table variableRowLinesMax
parameter to the number of lines to display. Set the columnRenderer property for the column
to an eTextArea in order to display the text in the cell with multiple lines.
[TableParameters]
TableParameters.variableRowHeight=true
TableParameters.variableRowLinesMax=3

[Column1]
Column.columnRenderer=eTextArea,noneditable

Specifying use of alternating row colors:

Set the alternatingRow parameter to true. It is not necessary to set the alternatingRowColor as
a default is set as a standard. However, if needed, an alternating row color can be configured
by setting the alternatingRowColor property to either a standard color or to a custom color with
the r,g,b values specified as shown in the examples below.

Example of specifying a custom color with r,g,b values:

[TableParameters]
TableParameters.alternatingRow=true
TableParameters.alternatingRowColor=custom,r=240,g=240,b=241

Example of standard color:

[TableParameters]
TableParameters.alternatingRow=true
TableParameters.alternatingRowColor=blue

Allowing the user to click in view-only cells and display a Text Zoomer dialog to view data
that exceeds the maximum lines displayed :

Set the columnAccess property to “rw” to allow the user to be able to click in the cell. Set
the columnEditor to eTextFieldZoom and include the noneditable option so that the data is
not editable.
[Column1]
Column.columnEditor=eTextFieldZoom,noneditable
Column.columnAccess=rw

Setting the tooltip text values for a cell from ESData values:

11-73
 Set the columnToolTipKey property to the xml element name in the data object exchanged
with the server. The values set for the tooltiptext will be the values returned from the
server for this element. The tooltips can be viewed by clicking in the cell.

[Column1]
Column.columnToolTipKey=IssRtePrfl

Omitting the table activity icon:

Set the displayRowActivityIcon table parameter to false. This will prevent the display of the
activity icon in the selection column for any activity that occurs.
TableParameters.displayRowActivityIcon=false

11.7 Data Types

The Data Types section is where the ESData elements specific to this table are defined. Most of the
properties in this section tie directly to elements defined in the ESData. There are a few properties that
don’t fall into this category.

DataTypes.insertRowMaxEntries=10
DataTypes.updateRowMaxEntries=10
DataTypes.deleteRowMaxEntries=10
DataTypes.growTheTableKey=truitsAcquirerType

The MaxEntries properties define how many table rows are sent to the server in a single request.
Typically, 10 is a good number.

The growTheTableKey property must specify an element that is common to allow of the request data
types. In the case of the Training UI, truitsAcquirerType is in the three request data types which are:

TrainAcqTblInsertRq
TrainAcqTblUpdateRq
TrainAcqTblDeleteRq

11.8 Assigning a List Model

As a review of what was discussed previously, the list model for a table column that uses a localized
framework.desktop.ecomponents.EComboBox is dictated by the following column properties.

Column.columnEditorLocaleKey=Training.Type
Column.columnEditorPropertyFile=Training

For a table cell that uses an EComboBox with a ManagedList as the list model, the managed list is
specified by the following column property:

Column.columnManagedList=acqPrflStringList

11-74
The value assigned to columnManagedList must be a UI list name constant value. When using the
columnManagedList property, be aware of the following.

1. The default implementation assumes the combo box model is a RefreshComboBoxModel.

AbstractESApplicationFrameForTable methods setModel and refreshModel must be
overridden if the combo box model is something other than a RefreshComboBoxModel.

2. The default implementation assumes the combo box model is the result of getListModel
performed on the ManagedList. If the ManagedList needs to be copied and altered before being
used as the model, AbstractESApplicationFrameForTable methods setModel and
refreshModel must be overridden.

If neither of the provided list model implementations addresses the need, the steps for assigning your own
list model are shown below. The sample shows assigning a list model to column 4 of a theoretical table
(i.e., this doesn’t pertain to the Training UI).

Description Code Fragment

GenericCellEditorMgr routeCodeEditor =
Get a reference to the getPanelItemAsGenericETableMgr( LK_TABLE_KEY )
editor manager. .getColumnCellEditor( LC_AMOUNT_COLUMN );

routeCodeEditor.assignListModel
Assign the list model to ( EDITOR_RENDERER_ECOMBOBOX,
the editor. routeCodeEditorList );
GenericCellRendererMgr routeCodeRenderer =
Get a reference to the getPanelItemAsGenericETableMgr( LK_TABLE_KEY )
renderer manager. The .getColumnCellRenderer( LC_AMOUNT_COLUMN );
editor and renderer need
to each have their own
instance of the model.
routeCodeRenderer.assignListModel
Assign another instance ( EDITOR_RENDERER_ECOMBOBOX,
of the model to the routeCodeRendererList );
renderer.

11.9 Differences for ManagedList Versus ManagedStringList

The previous section discussed using the columnManagedList property. If the target list is an instance of
ManagedStringList, the editor type eComboBox should be used. This editor type will handle the
editor/renderer needs via base class implementation (i.e., the developer doesn’t need to provide any
additional logic).

If the target list is not an instance of ManagedStringList (i.e., the target list is a ManagedList and not a
ManagedStringList), the editor should be specified as eComboBoxListData. A ManagedList is
comprised of objects that implement the interface ManagedListData. The base class implentation will
use the ManagedListData’s toString() method to render the list and render the selected item. If the

11-75
toString() method of the ManagedListData can’t be used (i.e., it’s being used for some other purpose),
or the editor/renderer requirements are more complex than can be addressed by this method, a custom cell
editor/renderer will need to be used.

11.10 Using a Custom Cell Editor/Renderer

The supplied editors are shown above. For the case where an editor is needed that is not one of the
supplied ones, the steps for making use of your own TableCellEditor are as shown below. The sample
instructions and properties come from LimitTable.properties and LimitBuilder method
initComponents, from package es.desktop.limit.

Assign a meaningful name Column.columnEditor=AdditionalDataCellRenderer

to the column editor
property.
Get a reference to the editor GenericCellEditorMgr editorMgr =
getPanelItemAsGenericETableMgr( LK_LIMIT_TABLE )
manager.
.getColumnCellEditor( LC_ADDITIONAL_DATA_HEADER );
Get a reference to the GenericCellRendererMgr rendererMgr =
renderer manager. getPanelItemAsGenericETableMgr( LK_LIMIT_TABLE )
.getColumnCellRenderer( LC_ADDITIONAL_DATA_HEADER );
Create the underlying editor GenericETextFieldEditor notAppl
component. The = new GenericETextFieldEditor();
component must implement
the interface
GenericETableEditing.
Other statements related to notAppl.setEditable( false );
the setup of the editor. notAppl.setDefault( CM_ONE_ZERO );
notAppl.reset();
Create the instance of the AdditionalDataCellEditor g
= new AdditionalDataCellEditor( notAppl );
GenericETableCellEditor
editorMgr.addEditor
and add it to the editor ( UI_ADDITIONAL_EDITOR_RENDERER, g );
manager.
Create the instance of the AdditionalDataCellRenderer rendererText
= new AdditionalDataCellRenderer( notAppl );
GenericETableCellRenderer
rendererMgr.addRenderer
and add it to the renderer ( UI_ADDITIONAL_EDITOR_RENDERER, rendererText );
manager.

11.11 Overriding isCellEditable

As mentioned above, column properties columnKeyFieldAccess and columnAccess dictate whether a
cell is editable. The following GenericETableModel methods are provided to allow the developer to
override isCellEditable for a given column.

11-76
public void overrideColumnAccess(int column, String access)
public void overrideColumnKeyFieldAccess(int column, String access)
public void resetOverrideColumnAccess(int column)
public void resetOverrideColumnAccessAll()
public void resetOverrideColumnKeyFieldAccess(int column)
public void resetOverrideColumnKeyFieldAccessAll()

In the Currency Conversion Rate UI, there is a need to have the columnAccess for the first column to be
“RW” when the currency selected is “ANY”, and “RO” at all other times. The following logic can be
found in class CurrencyConvRateComponentBuilder.

getVisibleGenericETableMgr().getGenericETable()
.getMainTableModel().resetOverrideColumnAccessAll();
if ( ((CurrencyConvRateUI)getUIRef()).comboSetToAny() )
{
getUIRef().disableDeleteAction();
getUIRef().setTitleItem( null );
setIsCopyable( false );
getVisibleGenericETableMgr().getGenericETable()
.getMainTableModel().overrideColumnAccess( 1, "RW" );
}

11.12 Hidden Columns

Hidden columns are used when it’s beneficial to use a table approach, but there are too many columns to
make a useful table UI. In this case, the some elements (primarily key elements) can be in the table, and
the rest of the elements (i.e., the hidden columns) in a panel below the table.

Hidden columns are elements that are in the model (i.e., in ScreenData), but not defined as a column in the
table properties (i.e., there is no [Column] definition). The support is provided via the definition of the
[HiddenColumn] section in the table properties. The visual component is in a panel below the table. The
panel below the table is repopulated each time a row is selected. Surcharge Profile and ATM Receipt
Format are two examples of UIs that use hidden columns.

The hidden column section keywords are defined in GenericETableConstants. Refer to the
GenericETableConstants javadoc for information and a usage example of each property.

GenericETableConstants Property

HIDDEN_COLUMN_KEY hiddenColumnKey
HIDDEN_COLUMN_HOLD_KEY hiddenColumnHoldKey
HIDDEN_COLUMN_COMPONENT_KEY hiddenColumnComponentKey
HIDDEN_COLUMN_COMPONENT_TYPE hiddenColumnComponentType
HIDDEN_COLUMN_LABEL_KEY hiddenColumnLabelKey

11-77
11-78
12 UI Constants
The class (it’s actually an interface) that contains the constants for the Training UI is named:

TrainingConstants.java

This interface contains the constants used by the UI. For example, this is where constants are defined for
the property file name and for the security task ID. As a general rule, the developer should define all
constants used by the UI here.

The UI application name value determined above is used as the value for the UI_APP_NAME constant.

public final String UI_APP_NAME = "TrainingManager";

The UI name value and UI list name value determined above is used as the value for the UI_UI_NAME
constant and UI_LIST_NAME constant.

public final String UI_UI_NAME = "TrainingUI";

public final String UI_LIST_NAME = "TrainingUIList";

12-79
13 UIInstanceManager Extension
As of BASE24-eps Version 08.2, UIInstanceManager is a concrete class. Thus, there is no need to
provide a UIInstanceManager extension. In almost all cases, a UIInstanceManager extension will not be
needed. The changes that remove the necessity of a UIInstanceManager extension were introduced in
BASE24-eps Version 08.2, and moved back to all VI Versions (06.2 and forward).

The UIInstanceManager instance(s) are contained by the ESDesktopApplication extension. An

ESDesktopApplication extension will generally contain one or more UIInstanceManager instances.

UIInstanceManager’s main job is to help an ESDesktopApplication with the opening of a UI. Context
and UI to UI associations are primarily what UIInstanceManager deals with. These are factors when one
UI opens/activates another as a result of a user clicking a hyperlink. The rules that UIInstanceManager
uses for determining what to do with context and UI to UI associations are the following:

a. If the requesting UI’s hyperlink has previously been clicked, the target UI instance that was created at
that time will be activated.

b. If a. is true, and there is context involved, when the frame is activated it will be reset to the new
context.

c. If a. and b. are true, and the target UI has been changed, the user will be given a prompt asking if the
current context should be overlaid.

d. If a. is not true, a new instance of the target UI will be created, thus creating a relationship between the
requesting UI and the target UI. If context is provided, the new instance of the target UI will be set to the
supplied context.

13-80
14 ManagedList Extension
Training UI maintains a list of profiles. The ManagedList extension that represents this list is named:

TrainingProfileManagedList.java

ManagedList contains behavior that BASE24-eps UI lists generally need. The ManagedList instance(s)
are contained by the ESDesktopApplication extension. An ESDesktopApplication extension will
generally contain one or more instances of ManagedList.

From a conceptual standpoint a managed list has the following characteristics.

It is owned by a UI. The owning UI has the exclusive ability to add and remove items from the
list. For example, Training UI owns the Training UI Profile List. While other UIs may request a
reference to the list, only Training UI is allowed to update.
All UI instances that have asked for a copy of the list will typically have the same view of the list.
I may have multiple copies of Training UI open, plus have other UIs that use the Training UI
Profile List, but they are all referencing the same java.util.Vector.
The list owning UI must keep the list updated when user updates are performed.
A UI that owns a managed list must maintain listeners that want to be notified when the list
changes. This means there must be a means to allow a listener to add itself and to remove itself.
When the list changes, the UI must notify listeners that the list has changed.
The ability must exist to add to the list, remove from the list, refresh the list, get the list, just to
name a few of the utility methods that are needed.

The ManagedList class was developed to allow these behaviors to be addressed by a reusable class.

ManagedList is abstract. Extensions to ManagedList must implement getListVector and setListVector.

ManagedList provides methods for adding to the list, removing from the list, refreshing the list, adding a
listener, removing a listener, etc. TrainingUI updates TrainingProfileManagedList upon receiving a
successful insert response or a successful delete response.

TrainingProfileManagedList is actually an extension of ManagedStringList. ManagedStringList is

an extension of ManagedList, and is used when the list items are String objects.

ManagedList is used when the list items are of any type other than String. The biggest difference
between ManagedList and ManagedStringList is in methods addList, deleteList, and updateList.
ManagedStringList takes a java.util.Vector of String objects as an argument. ManagedList takes a
java.util.Vector of ManagedListData objects as an argument.

A ManagedListData object is a class that implements the ManagedListData interface. This interface
requires that getKey and getGenericKey be implemented. An example of a class that implements this
interface is RoutingConfigData, which is used by the Routing UI. getKey allows ManagedList objects

14-81
to be inserted in the list in the proper order. It also allows matching ManagedList objects to be identified
(for example when the user has selected a list item to be deleted). getGenericKey allows multiple list
objects to be deleted at once. getKey and getGenericKey from RoutingConfigData are now described
as follows:

The if logic in getKey is needed because RoutingConfigData is the object type for several lists used
by the Routing UI.

public String getKey( String affectedList )

{
String retval = "";
if ( affectedList.equals(
ESDesktopConstants.ROUTING_LIST_ALL ) )
{
retval = getIssRtePrfl()
+ getRteCde()
+ getAcct1Typ()
+ getAcct2Typ()
+ getCustAuthMthd();
}
else if ( affectedList.equals(
ESDesktopConstants.AIRF_LIST ) )
{
retval = getIssRtePrfl()
+ getAcqRtePrfl()
+ getTrnCde();
}
else if ( affectedList.equals(
ESDesktopConstants.ISS_PRFL_LIST ) )
{
retval = getIssRtePrfl();
}
else if ( affectedList.equals(
ESDesktopConstants.ACQ_PRFL_LIST ) )
{
retval = getAcqRtePrfl();
}

return retval;
}

The if logic is less complex in getGenericKey because the generic delete is only used against one type
of Routing UI list.

public String getGenericKey( String affectedList )

{
String retval = "";
if ( affectedList.equals(
ESDesktopConstants.ROUTING_LIST_ALL ) )
{
retval = getIssRtePrfl();
}

14-82
 return retval;

Convention: Whenever possible, ManagedStringList should be used as the model for combo box
components. There are complexities involved in using a model of complex objects that are best avoided.

14-83
15 ESDesktopApplication Extension

15.1 Introduction

This section describes the purpose and extension requirements of ESDesktopApplication. The
ESDesktopApplication extension for the Training UI is:

TrainingManager.java

ESDesktopApplication and it’s extensions have the following responsibilities:

Adds the UI(s) that it owns to the navigation tree.

Containment and management of ManagedList objects. This is discussed in the section titled
ManagedList Extension.

Display and activation management of the UI(s) that it owns. This involves initial display of the
UI(s) that it owns, and activation of existing instances of the UI(s) that it owns when a hyperlink is
performed. This is discussed in the section titled UIInstanceManager Extension.

Manages requests and responses that are exchanged between ESDestkopApplication instances.
The ESDesktopApplication implementation for this behavior is rarely overridden, so this topic is
not discussed. Reference the javadoc for the following methods to get a better understanding of
these requests.

requestRemoveUI
requestIsListInitialized
requestGetListModel
requestGetListVector
requestRefreshList
requestAddListChangedListener
requestRemoveListChangedListener
requestDisplayUI
doRequestResponse
isListInitialized
getListModel
getListVector
refreshList
removeUI
displayUI
addListChangedListener

15-84
 removeListChangedListener

This section contains the following subsections:

Extending ESDesktopApplication. ESDesktopApplication is abstract, so there are method

implementation requirements for the extension.

Implementing getList. ESDesktopApplication extensions that contain a ManagedList must

implement getList.

getNavigationTree Implementation. Method getNavigationTree is implemented by

ESDesktopApplication. The extension has some responsibilities in order for this implementation
to be functional. These responsibilities are discussed in this section.

15.2 Extending ESDesktopApplication

15.2.1 Overview

ESDesktopApplication is an abstract class that extends framework.desktop.DesktopApplication. To

extend ESDesktopApplication you must implement DesktopApplication method getApplicationName,
and you must implement ESDesktopApplication abstract methods getTitle and getErrorTitle.

15.2.2 Class Variables

TrainingManager contains two class variables.

A reference to the ManagedList maintained by the Training UI.

private TrainingProfileManagedList trainingProfileManagedList;

A reference to the UIInstanceManager used to instantiate and activate instances of TrainingUI.

private UIInstanceManager uiInstanceManager;

15.2.3 Constructor

The constructor contains the following statements.

public TrainingManager()

15-85
 {

Every ESDesktopApplication extension will invoke the super with a boolean value of true.
This results in ESDesktopApplication creating an ESNCService instance, which is used by
the UI to exchange messages with the server.

super( true );

Set the appID with the property file name. UI_PROPERTY_FILE comes from the UI
Constants interface.

setLocaleAppID( UI_PROPERTY_FILE );

Creates the UIInstanceManager instance and sets the class variable.

uiInstanceManager = new UIInstanceManager( this );

Creates the ManagedList instance and sets the class variable. The ManagedList constructor
takes as an argument the UI list name constant value.

setTrainingProfileManagedList( new TrainingProfileManagedList

( this,
UI_LIST_NAME ));

Adds the constants for this UI to a common HashMap maintained in class

ESDesktopConstants. This then makes it possible for other UIs to get access to the
ManagedList maintained by the Training UI, and makes it possible for other UIs to
hyperlink to the Training UI.

ESDesktopConstants.addExternalConstant( UI_UI_NAME, UI_APP_NAME);

ESDesktopConstants.addExternalConstant( UI_LIST_NAME, UI_APP_NAME);

15.2.4 Implementation of Abstract Methods

Reference the source for TrainingManager to see the implementation of getTitle and getErrorTitle.

Method getApplicationName is implemented as follows:

public String getApplicationName()

{
return UI_APP_NAME;
}

The UI_APP_NAME constant was defined in the UI Constants step.

15-86
15.3 Implementing getList

Version 5.4 Note: As of version 5.4, method getList is implemented in the super class. The super class
implementation uses the list retrieval properties (see Section 10.15) to format the list request, and process
the list response. The super class implementation is sufficient if the list request and response contain a
single element and if the ManagedList is a ManagedStringList. Due to the super class enhancement, the
discussion that follows is no longer pertinent. The discussion has been left in the document as an example
of a simple getList implementation.

The implementation for retrieving lists from the server resides in the ESDesktopApplication extension.
TrainingManager’s implementation follows.

public String getList( Vector listVector, String affectedList, Vector inputArgs )

{
String stringRetval = CM_EMPTY_STRING;
String startKey = CM_EMPTY_STRING;

This logic completely rebuilds the list so the first step is to remove all of the current items
from the list.

listVector.removeAllElements();
try
{

Thread interrupt logic is in all server request logic.

if (Thread.interrupted())
{
throw new InterruptedException();
}
if ( getESNCServiceReference() == null )
{
return ( getTitle()
+ CM_COLON_SEPARATOR
+ CM_NCSERVICE_NULL );
}

ESData esDataResp = null;

ESData esDataRqst = null;

int loopTest = 1;

The following loop is executed until the server respone status is something other than “OK”.

while ( loopTest == 1 )
{

Create the ESData for the list request.

esDataRqst = new ESData( ET_LIST_RQ );

15-87
Set the value of the start key. The start key allows the server to continue reading from where
the last response left off.

esDataRqst.setValue( EE_PROFILE, startKey );

doESRequest results in a request being sent to the server. The result is an ESData list
response.

esDataResp = getESNCServiceReference().doESRequest( esDataRqst );

Make sure the response isn’t null.

if ( esDataResp == null )
{
loopTest = 0;
return ( CM_LIST_RESPONSE_NULL + affectedList );
}

Status of “OK” and “end of file” are normal responses, and denote that the response may
have list entries to be processed.

else if ( esDataResp.isStatusOK() || esDataResp.isEOF() )

{

Determine how many list entries are in the response.

int arrayLength = esDataResp.getArrayLength( EE_PROFILE );

The following loop adds items to the ManagedList. listVector is an argument supplied to this
method and is the Vector for the ManagedList.

for (int i = 0; i < arrayLength; i++)

{
listVector.addElement( esDataResp.getValue( EE_PROFILE, i ));
}

If the response status is “OK”, all of the items have not been retrieved so we need to revalue
startKey with the value of the last item just received.

if ( esDataResp.isStatusOK() )
{
int lastItem = listVector.size() - 1;
if ( lastItem > -1 )
{
startKey = listVector.get( lastItem ).toString();
}
}

If the response status is “end of file”, we have retrieved all of the list items.

if ( esDataResp.isEOF() )

15-88
 {
esDataResp.setStatus( esDataResp.OPERATION_SUCCESSFUL );
loopTest = 0;
}

If the response status is something other than “OK”, terminate the loop. “dataNotFound” is
considered a normal response since it is possible for the data source used for the list to be
empty.

else
{
loopTest = 0;
if ( esDataResp.isDataNotFound() )
{
esDataResp.setStatus( esDataResp.OPERATION_SUCCESSFUL );
}
}

} // end of while loop

If the response is a normal one, return an empty String, otherwise return a String with a
description of the error. A return value of something other than an empty String denotes
that the getList was not successful.

if ( esDataResp.isStatusOK() )
{
return CM_EMPTY_STRING;
}
else
{
return ( CM_LIST_RESPONSE_ERROR
+ affectedList
+ CM_SPACE_SEPARATOR
+ CM_STATUS_IS
+ esDataResp.getStatus() );
}
}
catch (InterruptedException ie)
{
ESUtilities.getInstance().writeStackTrace( ie );
return ( CM_LIST_RESPONSE_EXCEPTION
+ affectedList
+ CM_COLON_SEPARATOR
+ ie );
}
catch ( ESException ese )
{
ESUtilities.getInstance().writeStackTrace( ese );
return ( CM_LIST_RESPONSE_EXCEPTION
+ affectedList
+ CM_COLON_SEPARATOR
+ ese );
}

15-89
 }

15.4 getNavigationTree Implementation

ESDesktopApplication provides a default implementation for DesktopApplication abstract method

getNavigationTree. The ESDesktopApplication extension has responsibilities in making this
implementation successful. The responsibilities are the following:

1. Implement getNavigationAppID(). Version 5.4 Note: As of version 5.4, getNavigationAppID is

implemented in the super class. It only needs to be implemented in the extension if the return is
something other than the result of getLocaleAppID.
2. Provide the necessary properties. Properties are needed for the following:
a. List of UIs managed by the extension.
b. The root navigation node.
c. Security Task ID.
d. The navigation branches.

The navigation properties are discussed in the UI Properties section.

ESDesktopApplication contains method getUINavigationAction to retrieve the navigation action for the
UI.

protected Action getUINavigationAction( final String uiName )

{
final String UIName = uiName;
Action retval = new AbstractAction()
{
public void actionPerformed( java.awt.event.ActionEvent event )
{
getUiInstanceManager( UIName ).displayUI();
}
};
return retval;
}

This implementation assumes the UI uses a UIInstanceManager to handle the display of the UI. Though
it is discouraged, extensions can override this method. Eventually we want all UIs to be displayed via a
UIInstanceManager. The long term direction is to make this method private so that it can not be
overridden.

15.5 Frequently Overriden Methods

15.5.1 Specify the Name of the ESData Definition File

As of the BASE24-eps Version 06.2, we have added super class logic to build an index which takes the
place of the function previously provided by ESDataConfig.cfg (i.e., mapping an ESData type to a file

15-90
name). This logic works if the UI specific ESData definition (e.g., ActionCode.cfg) matches the app ID
for the UI (e.g., ActionCode). As of the BASE24-eps Version 06.2, we must use the added super class
logic when developing any UI’s that are considered to be Version Independent because the
ESDataConfig.cfg file is not Version Independent. There are two scenarios where the super class logic
won’t work:

If the package has multiple ESData definitions (e.g., package multicurrency has
CurrencyConv.cfg, LinkedCurrency.cfg, and EuroOptedCurrency.cfg).
If the UI specific ESData definition doesn’t match the app ID for the UI (e.g., in the prefixconfig
package the ESData file name is Prefix_Config.cfg, while the app ID is PrefixConfig).

If either of these cases is true, either the types must be defined in ESDataConfig.cfg, or
ESDesktopApplication method getESDataConfigFileNames must be overriden. The override simply
returns the ESData file name(s). Here is the override in CurrencyConvRateManager, package
es.desktop.multicurrency:

protected String[] getESDataConfigFileNames()

{
return new String[] { "LinkedCurrency.cfg",
"EuroOptedCurrency.cfg",
"CurrencyConvRate.cfg"
};
}

15-91
16 ESComponentBuilder Extension

16.1 Introduction

The TrainingUI’s ESComponentBuilder extension is:

TrainingBuilder.java

ESComponentBuilder is a concrete class. However, most UI’s will extend it due to needing to override
one of the methods listed in the section Frequently Overridden Methods. An instance of
ESComponentBuilder is created when the UI initializes. At this point it’s main job is to read the UI
Layout File(s), assemble the defined components into containers (javax.swing.JPanel instances), and
render the components in a java.awt.GridBagLayout.

After the UI is initialized, ESComponentBuilder and it’s extension have some responsibilities for the
actions tied to the visual components. For example, ESComponentBuilder handles the actions tied to
EHyperLinkLabel instances.

16.2 Constructor

The TrainingBuilder constructor, and the invoked method initComponents, follow.

The new instance of TrainingBuilder is created by TrainingUI. The super constructor is called
which results in all of the visual components being instantiated. After the super constructor is
called, any additional initialization related to the visual components is performed.

public TrainingBuilder
( String configFile,
String defaultLocaleKey,
AbstractESApplicationFrame ui)
{
super ( configFile, defaultLocaleKey, ui );
initComponents( ui );
}
public void initComponents( AbstractESApplicationFrame ui )
{

A reference is obtained to the Country Code component defined on the General Information tab,
setLocaleKey is invoked. setLocaleKey results in the list model for this combo box to be assigned to
the localized list “CountryCode” which is defined in the property file named
CommonCodeValues+INTF. The setFullKeys false invocation is always performed for a combo box
that uses a localized list.

16-92
 ((EComboBox)getEComponent( LK_COUNTRY_CODE_LIST )).setLocaleKey
( LC_COUNTRY_CODE_LIST, CommonProperties.COMMON_CODE_VALUES );
((EComboBox)getEComponent( LK_COUNTRY_CODE_LIST )).setFullKeys( false );
}

16.3 Profile Combo Box Actions

ESComponentBuilder and it’s extension, has the responsibility for the actions tied to the visual
components. In the case of the Training UI, there is UI behavior that needs to take place when the user
selects an entry from the Profile combo box, or types in a new entry. The Profile combo box is an
instance of SelectionComboBox, so the actions are filtered and funneled through
SelectionComboBoxUser interface method comboActionFired. ESComponentBuilder is a
SelectionComboBoxUser, and has default implementations for the necessary methods. Generally,
ESComponentBuilder’s implementation for the following methods will be overridden by the extension:

comboActionFired
comboKeyContentsNewValue
comboKeyReleasedChanged

TrainingBuilder’s implementation of comboActionFired follows.

public void comboActionFired

( ActionEvent e, boolean existingValue, String comboID )
{

If the selected item is an existing value, set the title for the UI to reflect the item selected, and
invoke AbstractESApplicationFrameForTable method doServerRequest for the purpose of
doing a view request.
if ( existingValue )
{
getUIRef().setTitleItem( getEComponent( LK_PROFILE_LIST ).getValue() );
getUIRef().doServerRequest( getUIRef().getViewMessageConstant() );
}

If the selected item is a new item (i.e., the user has typed a new item into the combo box), set
the title for the UI to reflect the item entered, and invoke AbstractESApplicationFrame
method setupForNewEntry.

else
{
getUIRef().setTitleItem( getEComponent( LK_PROFILE_LIST ).getValue() );
getUIRef().setupForNewEntry();
}
}

16-93
When the user types data into the Profile combo box, SelectionComboBox invokes method
comboKeyContentsNewValue on the SelectionComboBoxUser. This method deals with
enabling/disabling toolbar actions based on the contents of the combo box editor. TrainingBuilder’s
implementation for this method follows.

public void comboKeyContentsNewValue( boolean hasServerContext,

boolean isNewKey,
String comboID )
{

If the combo box editor contents represents an item for which this UI has server context (i.e.,
it has been viewed), enable the delete action, otherwise disable the delete action.
if ( hasServerContext )
{
getUIRef().enableDeleteAction();
}
else
{
getUIRef().disableDeleteAction();
}

If the combo box editor contents is an existing key, and the UI has server context for this
value, enable the save action. If the item is a new key, enable the save action. For any other
case, disable the save action.
if ( !isNewKey && hasServerContext )
{
getUIRef().enableSaveAction();
}
else if ( isNewKey )
{
getUIRef().enableSaveAction();
}
else
{
getUIRef().disableSaveAction();
}

16.4 GenericETableMgr Events

ESComponentBuilder registers itself as a listener for each instance of GenericETableMgr. The required
methods are implemented by ESComponentBuilder. The ESComponentBuilder extension overrides the
methods that are relevant to the UI. In the case of the Training UI, the ESComponentBuilder
implementation provides the necessary behavior.

An example of a UI that does require override of the behavior is the Limit UI. The following override of
genericETableSelectionOccurred comes from class LimitBuilder. The intent is to populate one of
the table cells when the user performs an insert row.

16-94
 public void genericETableSelectionOccurred( GenericETableEvent evt )
{
super.genericETableSelectionOccurred( evt );
if ( evt.getType() == GenericETableEvent.INSERT_ROW_SELECTED )
{
insertRowSelected();
}
}

16.5 Frequently Overridden Methods

16.5.1 Creating EComponent Instances

There are two scenarios where the the ESComponentBuilder method getNewEComponentInstance
must be overridden.

- When an EComponent instance needs to be created that is outside of the package

framework.desktop.ecomponents and outside of the package es.desktop.
- When an EComponent instance needs to be created with a constructor that is anything other than
the empty argument constructor.

Neither scenario applies to TrainingBuilder.

16.5.2 Creating a GenericETableMgr Extension

Method getNewGenericETableMgrInstance must be overridden if the UI needs to use an extension of

GenericETableMgr. This is discussed in the subsection titled Creating a GenericETableMgr Extension.

16.6 Convenience Methods

The following tables summarize some of the convenience methods provided by ESComponentBuilder.
Refer to the javadoc for additional information.

16.6.1 EComponent Conveniences

Method Name Comment

getEComponentValue( String ) Use this method of all that is needed is the value of
the EComponent.
setEComponentValue( String, String ) Use this method of all that is needed is to set the
value of the EComponent.

16-95
 Method Name Comment
getEComponent( String ) Gets a reference to an EComponent. This is the
preferred means of getting a reference to a visual
component..
getEComponentAsEButton( String ) Gets the EComponent and casts it as an EButton,
then returns the EButton. This method is used if the
caller must make use of EButton specific methods.
getEComponentAsExxxx( String ) One of these methods exists for each type of
EComponent where xxxx is replaced by the
EComponent class name (e.g.,
getEComponentAsEButton). The intent here is to do
the cast in ESComponentBuilder instead of the
extension.

16.6.2 Conveniences Related to SelectionComboBox

Method Name Comment

getEComponentAsSelectionComboBox( String ) Returns the EComponent as a SelectionComboBox.
getEComponentAsSelectionComboBoxNoEdit Returns the EComponent as a
( String )
SelectionComboBoxNoEdit.
getEComponentAsSelectionTextField( String ) Returns the EComponent as a SelectionTextField.
isSelectionComboBoxExistingKey( String ) Returns true if the selected item exists in the list
isSelectionComboBoxNewKey( String ) Returns true if the selected item is a new value.
setSelectionComboBoxNewContext Typically called when the UI is started with
( String, String )
context.

16.6.3 Conveniences Related to GenericETableMgr

Method Name Comment

getPanelItemAsGenericETableMgr( String ) Returns the GenericETableMgr.
getTableRowKey( String, String ) Returns the table row key from the table properties.
isTableLoadRequest( String, String ) Returns true if the supplied value is a table load
request.
isDeleteRowRequest( String, String ) Returns true if the supplied value is a table delete
row request.
doesTableContainDuplicate( String, int[] ) Returns true if the table contains a duplicate.

16-96
resetTable( String ) Resets the table.

16.6.4 Non-EComponent Gets

Method Name Comment

getPanelItemAsJPanel ( String ) Returns the JPanel.
getPanelItemAsJTabbedPane( String ) Returns the JTabbedPane
getPanelItem( String ) Returns an Object.

16.6.5 Higher Level Hierarchy Convenience Gets

These methods cast a component to a higher level in the inheritance hierarchy. To avoid code changes
when the component type changes, it’s best to cast to the highest level in the inheritance hierarchy.

Method Name Comment

getEComponentAsJTextComponent( String ) Returns the EComponent as a JTextComponent.
getEComponentAsJComponent( String ) Returns the EComponent as a JComponent.
getEComponentAsComponent( String ) Returns the EComponent as a Component.
getEComponentAsContainer( String ) Returns the EComponent as a Container.

16.7 Multiple Layout Files

ESComponentBuilder provides a constructor that allows the specification of multiple layout files, and
multiple property files. This is primarily useful when you have a UI that is going to reuse the layout files
of a different UI.

For example, the BIC ISO Interface UI uses InterfaceFrameworkLayout, IfB24Hiso93Layout, plus, the
BIC ISO specific layout file which is named IfBicIsoLayout. The IfBicIsoBuilder constructor is defined
as follows:
public IfBicIsoBuilder (String[] configFileArray,
String[] localeKeyArray,
AbstractESApplicationFrame ui)
{
super( configFileArray, localeKeyArray, ui );

16-97
The instruction in IfBicIsoUI to create the instance of IfBicIsoBuilder is as follows:
setESComponentBuilder( new IfBicIsoBuilder
( new String[] { UI_FRAMEWORK_LAYOUT_FILE, UI_HISO_LAYOUT_FILE, UI_LAYOUT_FILE },
new String[] { UI_FRAMEWORK_PROPERTY_FILE, UI_HISO_PROPERTY_FILE, UI_PROPERTY_FILE },
this ));

When ESComponentBuilder assembles the visual components, it does so in the order of the layout files in
the array. Given the above, the InterfaceFrameworkLayout components will be added first, followed by
the IfB24Hiso93 components, followed by the IfBicIsoLayout components.

The corresponding property file array allows the specification of a property file specific to the
corresponding layout file. This allows the properties for the components of a given layout file to come
from a given property file.

16-98
17 AbstractESApplicationFrameForTable Extension

17.1 Introduction

This section provides instructions and considerations for extending

AbstractESApplicationFrameForTable. AbstractESApplicationFrameForTable is an
ApplicationFrame (actually ESApplicationFrame) implementation specific to ES User Interfaces. The
AbstractESApplicationFrameForTable extension for the Training UI is:

TrainingUI.java

Note: Within this section you will see references to AbstractESApplicationFrame and
AbstractESApplicationFrameForTable. You can think of these as the same class because eventually they
will be merged into one class. For now, all UIs will extend AbstractESApplicationFrameForTable.
This is regardless of whether the UI contains a table.

This section contains the following sub-sections:

A Basic Implementation. Provides the minimum implementation needed by the extension. This section is
designed to allow a simple UI (or mock-up) to be quickly created.

Other Frequently Overridden Methods. Identifies other methods that are frequently overridden.

Override Conveniences. Provides information on the methods that have been added as override
conveniences to the extension (i.e., the extension typically has a need to override in this area). For
example, most UIs will have the need to override some piece of how the ESData requests are formatted
and/or how the visual components are populated.

Actions. Identifies the actions (i.e., toolbar actions) supported by the base class, describes the behavior or
the actions, provides information on how to add additional actions, and provides override information.

Message Types. This section identifies message type specific logic used by the base class. An extension
that requires an action outside of what is supported will often have a need to override some of the message
type specific logic.

Server Context. This is an informational section describing how server context is handled.

Threads and Messaging. This is an informational section that describes the messaging sequence and the
how/when multiple (though sequential) threads are used.

Additional Features. Describes some miscellaneous additional features.

17-99
Summary of Changes from Previous Version of AbstractESApplicationFrame. This section
summarizes the primary differences between extending AbstractESApplicationFrameForTable and
extending AbstractESApplicationFrame (AbstractESApplicationFrameWithTable).

17.2 A Basic Implementation

17.2.1 Constructor and Initialize Method Requirements

As of BASE24-eps Version 08.2, most of the constructor instructions have been moved from the
constructor and placed in a method named initialize. This facilitates CSMs. The constructor for the
TrainingUI follows.

UIInstanceManager invokes the TrainingUI constructor and supplies the TrainingManager

and context as arguments.

public TrainingUI( TrainingManager trainingManager,

String context )
{

PROPERTY_FILE is the constant for the property file for the Training UI. If the toolbar
property prefix is not the same as the property file prefix, it must be specified as the third
argument.

super( trainingManager, UI_PROPERTY_FILE );

initialize( manager, context );
}

The initialize method for the TrainingUI follows.

protected void initialize( TrainingManager manager, String context )
{

try

The actions for this UI are created. The createActions() method uses the values from the
toolbar and popupMenu properties. createActions is implemented by
AbstractESApplicationFrame.
Action actions[] = createActions();

The context class variable (contained by AbstractESApplicationFrame) is set from the

supplied context argument.
setContext( context );

17-100
 Creates the toolbar. The actions that are placed on the toolbar are the ones defined by the
toolbar property. createToolBar is implemented by ESApplicationFrame (the class
AbstractESApplicationFrame extends).
createToolBar( actions );

Set the AbstractESApplicationFrame class variable allElements, then register allElements

with ESDataManager.

These two statements allow the mapping between the visual components and the ESData
objects to occur.

The allElements and esDataManager class variables and accessors are in

AbstractESApplicationFrame.
setAllElements( getESNCService().getNewESData( ET_ALL_ELEMENTS ));
getESDataManager().registerESData( getAllElements() );

Create the ESComponentBuilder extension and set the class variable (contained by
AbstractESApplicationFrame). The first argument is the name of the UI Layout file.
Method createESComponentBuilder was introduced in BASE24-esp Version 08.2 with the
intent of facilitating CSMs.
setESComponentBuilder( createESComponentBuilder
( UI_MAIN_LAYOUT_FILE, UI_PROPERTY_FILE ));

All AbstractESApplicationFrameForTable extension constructors contain this statement.

setScrollBarsEnabled( false );

This statement results in the lists used by this UI to be retrieved. The implementation for
this method is in AbstractESApplicationFrame.
initializeUILists();

Creates the popup menu. The actions that are placed on the popup menu are the ones
defined by the popupMenu property. createPopupMenu is implemented by
ESApplicationFrame (the class AbstractESApplicationFrame extends).

createPopupMenu( actions );

Sets the UI visible.

setVisible(true);
}

Any exception that occurs during the constuctor is handled by method handleException.

catch (java.lang.Throwable ivjExc)

17-101
 {
handleException(ivjExc);
}
}

17.2.2 Mapping the Visual Components

Method getRequests uses helper methods getServerViewRequests, getServerUpdateRequests,

getServerInsertRequests, getServerDeleteRequests and getServerSubmitRequests to gather
information that allows the ESData requests to be created. These methods return a String array that
defines one or more ESData messages that are needed to satisfy the user request.

The String array that is returned will consist of elements that are of two types:

An ESData type. This is used for non-table requests.

The table identification constant plus the table name. This is used to specify that a table be
processed as a result of this user action. The table identification constant is “table.”. The table
name that is specified is the name of the property that defines the table to ESComponentBuilder.

Using the Training UI as an example, the UILayout Property Name for the Acquirer Table is
TrainingAcquirerTable. This is defined in TrainingLayout.cfg. The Training UI doesn’t support a
submit action, so of the five methods mentioned above, the four that will be implemented are as shown
below. Note, for clarity sake the variable names used by the actual methods have been replaced with the
value of the variable names.

protected String[] getServerViewRequest()

{
return new String[] { “TrainViewRq”, “table.TrainingAcquirerTable” };
}

protected String[] getServerUpdateRequest()

{
return new String[] { “TrainUpdateRq”, “table. TrainingAcquirerTable” };
}

protected String[] getServerInsertRequest()

{
return new String[] { “TrainInsertRq”, “table. TrainingAcquirerTable” };
}

protected String[] getServerDeleteRequest()

{
return new String[] { “TrainDeleteRq” };
}

17.2.3 Abstract Methods

17-102
17.2.3.1 getStatusBarMessage

The typical implementation for this method is to return data that describes the current view of the UI. The
TrainingUI returns the value from the Profile combo box with the following two statements:

String messageArg
= getESComponentBuilder().getEComponentValue( LK_PROFILE_LIST );
return new String[] { messageArg };

17.2.3.2 getErrorTitle

Returns an error title. The Training UI returns the error title from the property file.

return
LocaleManager.getStringResource( UI_PROPERTY_FILE, LC_ERROR_TITLE);

17.2.3.3 insertRequest

Invoked by AbstractESApplicationFrame at the time the user performs a save action. The extension
returns true if the action is an insert action, and false if the action is an update action.

The Training UI returns the results of SelectionComboBox method isNewKey performed against the
Profile combo box.

return getTrainingBuilder().isSelectionComboBoxNewKey( LK_PROFILE_LIST );

17.2.3.4 getCanSaveMessage

Returns the variable text to be displayed by the UIF canSave dialogue. Like the getStatusBarMessage
method, the typical implementation for this method is to return data that describes the current view of the
UI. The Training UI uses the same logic that is used for getStatusBarMessage.

17.2.3.5 getCanUpdateMessage

Returns the variable text to be displayed by the UIF canUpdate dialogue. The Training UI uses the same
logic that is used for getStatusBarMessage.

17.2.3.6 getCanDeleteMessage

Returns the variable text to be displayed by the UIF canDelete dialogue. The Training UI uses the same
logic that is used for getStatusBarMessage.

17.3 Other Frequently Overridden Methods

17-103
17.3.1 notifyInitializeComplete

UIs will override this method to invoke a view after the lists have been retrieved as a result of a refresh
request.

The sequence is:

- The user requests a refresh.

- AbstractESApplicationFrame sends list requests for all of the defined lists.
- Once all of the lists have been retrieved, notifyInitializeComplete is invoked.
- At this point, the extension will invoke the view request.

TrainingUI’s implementation for this method:

if ( getRefreshRequested() )
{
if ( getTrainingBuilder().isSelectionComboBoxExistingKey( LK_PROFILE_LIST ) )
{
doServerRequest( getViewMessageConstant() );
}
}

The first if checks to make sure this is a refresh scenario. This method is also invoked at the end of the UI
initialization which is denoted by getInitInProgress() equal to true, so the if statement makes sure this is
the invocation we are looking for.

17.3.2 getPermissionsTaskID

Extensions must provide implementation for this method. The return value is the security task ID.
TrainingUI’s implementation of this method:

public String getPermissionsTaskID()

{
return UI_SECURITY_TASK_ID;
}

17.3.3 activatedWithContext

Extensions that can be hyperlinked to, will override this method. TrainingUI’s implementation of this
method:

setContext( context );
getTrainingBuilder()
.setSelectionComboBoxNewContext( LK_PROFILE_LIST, context );

17-104
The first statement sets the class data variable context with the new context. The second statement deals
with setting the UI to the new context. If the incoming context is valued, and it’s a different value from
the existing context for the UI, a view is invoked.

17.4 Override Conveniences

17.4.1 Formatting the Request ESData

Method extensionLoadSpecial is provided to allow extensions a convenient override to affect the request
ESData. Extensions can override and provide implementation for UI specific ESData value population.
This method is invoked just before the request is sent to the server.

The Training UI table request ESData types, include the element truitsProfile. The mapping logic
that is provided by the base classes can only map elements from the visual table to the ESData. The
element corresponding to truitsProfile is not in the visual table, so it must be handled by the extension.
For this reason, TrainingUI overrides extensionLoadSpecial.

protected void extensionLoadSpecial( ESData esDataRqst, String messageType )

throws ESException
{

Only table requests need special handling. For any other request, we return.

if ( esDataRqst.getDataType().equals( ET_INSERT_RQ )
|| esDataRqst.getDataType().equals( ET_UPDATE_RQ )
|| esDataRqst.getDataType().equals( ET_DELETE_RQ )
|| esDataRqst.getDataType().equals( ET_VIEW_RQ ))
{
return;
}

If the request is an ESData type TrainAcqTblViewRq, set the value of the element truitsProfile
from getMessageArguments. Method getMessageArguments returns the editor value of the Profile
combo box.
if ( getTrainingBuilder().isTableLoadRequest
( LK_ACQUIRER_TABLE, esDataRqst.getDataType() ))
{
esDataRqst.setValue( EE_ACQUIRER_TABLE_PROFILE, getMessageArguments()[0] );
return;
}

At this point, we know we have a table request with one or more instances of row data. The next
statements determine the row key, then calls the method to populate the ESData.
String rowKey = getTrainingBuilder()
.getTableRowKey( LK_ACQUIRER_TABLE, esDataRqst.getDataType() );

17-105
 loadESData( esDataRqst, rowKey );
}

Method loadESData updates the truitsProfile element from the editor contents of the Profile
combo box.
void loadESData( ESData esDataRqst, String requestRowKey )
throws ESException
{
for ( int i = 0; i < esDataRqst.getArrayLength( requestRowKey ); i++ )
{
esDataRqst.setValue( requestRowKey
+ CM_DOT_SEPARATOR
+ EE_ACQUIRER_TABLE_PROFILE,
getMessageArguments()[0],
i );
}
}

17.4.2 Affecting the Visual Components at Response Time

Method extensionUpdateUISpecial is provided to allow extensions a convenient override to do their own

visual component updates. Extensions can override and do UI specific visual component updates. This
method is invoked during response processing for all approved responses.

TrainingUI has no implementation for this method.

17.4.3 Verification of Visual Components

Method extensionVerifyComponents is provided to allow extensions a convenient override to do their

own visual component verification. Extensions can override and do verification that isn’t addressed by
EComponent.verify. The verification of visual components occurs before the message is sent to the
server.

TrainingUI implements this method to check if the table contains any duplicate keys. It invokes the
ESComponentBuilder convenience method doesTableContainDuplicate to determine this.

protected boolean extensionVerifyComponents()

{
boolean retval = true;
if ( getTrainingBuilder()
.doesTableContainDuplicate( LK_ACQUIRER_TABLE, new int[]{ 1 } ))
{
retval = false;
}
return retval;
}

17-106
17.4.4 Resetting Components

Method extensionResetComponents allows extensions to provide their own clear/reset logic. This
method is invoked near the end of resetComponents, but before the change groups are set to unchanged.

TrainingUI has no implementation for this method.

17.4.5 Updating ManagedList Objects

Method extensionUpdateManagedList is provided to allow extensions a convenient override to update

ManagedList objects. This method is invoked before updateUIComponents and before the logic that
determines if there is more data to send. If the extension's ManagedList update logic is dependent on
there not being any more data to send, the extension has to provide the necessary "more data to send"
determination logic.

TrainingUI has the need to update the TrainingProfileManagedList, therefore there is a need to override
this method.

protected void extensionUpdateManagedList( ESDataResponseObject responseObject,

String messageType,
ESData esDataResponse )
throws GenericTableException, ESException
{

We are only interested in delete and insert responses, since these are the only responses that affect the
ManagedList. The reason for the CM_EMPTY_STRING argument is, the second argument is not important
in TrainingManager’s implementation of getManagedList. The ManagedList deleteList and addList
methods take a java.util.Vector as an argument so that a UI can add/delete multiple entries with a single
method invocation. In the case of the Training UI, it is only necessary to add/delete a single entry at a
time.
if ( messageType.equals( getDeleteMessageConstant() ))
{
Vector updateVector = new Vector( 1 );
updateVector.add
( getESComponentBuilder().getEComponentValue( LK_PROFILE_LIST ) );
getESDesktopApplication().getManagedList
( UI_LIST_NAME, CM_EMPTY_STRING )
.deleteList( updateVector );
}
else if ( messageType.equals( getInsertMessageConstant() ))
{
Vector updateVector = new Vector( 1 );
updateVector.add
( getESComponentBuilder().getEComponentValue( LK_PROFILE_LIST ) );
getESDesktopApplication().getManagedList
( UI_LIST_NAME, CM_EMPTY_STRING )
.addList( updateVector );
}
}

17-107
17.5 Actions

AbstractESApplicationFrame method createActions provides implementation for creating standard

actions.

Action Required AbstractESApplicationFrame action

Action performed method.
Name
SaveAction save saveActionPerformed
DeleteAction delete deleteActionPerformed
SubmitAction submit submitActionPerformed
ClearAction clear clearActionPerformed
RefreshAction refresh refreshActionPerformed
InsertRowAction insertRow insertRowActionPerformed
InsertRowBeforeAction insertRowBefore insertRowBeforeActionPerformed
DeleteRowAction deleteRow deleteRowActionPerformed
RevertRowAction undo revertRowActionPerformed
TemplateAction template templateActionPerformed
ClearRowAction clearRow clearRowActionPerformed
CopyRowAction copyRow copyRowActionPerformed
PasteRowAction pasteRow pasteRowActionPerformed
Action is dynamically oltpRebuild The actionPerformed can not be override (it’s
created by ESUtilities. embedded in ESUtilities), however, the
creation of the action can be overriden by
overriding AbstractESApplicationFrame
method createOLTPRebuildAction.

AbstractESApplicationFrame provides default implementation for all actions except TemplateAction.

Method templateActionPerformed is empty.

The toolbar and popupMenu properties must match the action constants defined in the
AbstractESApplicationFrame (identified above as Required Action Name). For example, in Training
UI, these properties are defined as follows:
Training.toolbar=save clear refresh | delete | insertRow deleteRow undo
Training.popupMenu=save clear refresh | delete | insertRow deleteRow undo

Since the names in the properties match the names expected by AbstractESApplicationFrame, Training
UI can use the base class implementation of createActions.

Extensions can override what AbstractESApplicationFrame expects for action names via methods
setSaveActionName, setDeleteActionName, etc.

Convenience and accessor methods are provided for all actions as follows where the Xxxx is replaced by
the action:

17-108
 disableXxxxAction
enableXxxxAction
getXxxxAction
setXxxxAction

setCustomAction can be overridden to allow for actions that are outside of the supported ones.
Alternatively, createActions can be overridden if the extension needs to handle all of the action creation
implementation. For more information regarding custom actions, refer to the section titled Adding an
Action to the Right-Click Menu.

17.6 Message Types

Logic exists in the base class that looks something like the following:

if ( messageType.equals( getViewMessageConstant() )
{
xxxxx;
}
else if ( messageType.equals( getDeleteMessageConstant() )
{
xxxxx;
}
else if ( messageType.equals( getInsertMessageConstant() )
{
xxxxx;
}
else if ( messageType.equals( getSubmitMessageConstant() )
{
xxxxx;
}
else if ( messageType.equals( getUpdateMessageConstant() )
{
xxxxx;
}

The following table summarizes the meaning of the basic message types.

Message Type Non-Table UI Table UI

View View behavior. The table(s) are loaded.
Update Update behavior. All rows that are marked for update, delete, and
insert are sent to the server. Deleted rows are
deleted upon receipt of a successful server
response.
Insert Insert behavior. Same as update.
Submit Behaves like an Same as update.
update.
Delete Delete behavior. All rows in the table are deleted with an allowance
for fixed row tables.

17-109
Both the table and non-table behaviors will occur for UIs containing table and non-table data.

The following table summarizes where this type of logic is used and identifies override considerations if
the UI needs to provide additional basic message types:

Method Description Override Considerations

getActionForMessageFormatter At the time the response is Override
processed, MessageFormatter is getActionForMessageFormatter
used to create the status bar
message. One of the arguments
needed is a generic action.
successfulResponse At the time the response is Override successfulResponse.
processed, successfulResponse
calls the appropriate
successfulXxxx method where
Xxxx is View, Delete, Update,
Submit or Insert.
unsuccessfulResponse On an unsuccessful response, if Override unsuccessfulResponse.
the message is a view type
message, all of the components
are reset.

Note: This behavior may be

removed. There is discussion that
resetting the components on a
denied view is not what we want.
getRequests At the time the request is Override getRequests
processed, getRequests calls the
appropriate
getServerXxxxRequest where
Xxxx is equal to View, Insert,
Update, Submit, or Delete.

17.7 Server Context

Base class handling for non-table server context and fixed row table server context, is handled by the class
data variable named allElements (type ESData). This assumes the extension sets allElements, and
assumes that allElements contains the server context element. If a UI uses multiple server context
elements, the automatic logic will still work if each server context element is a unique element in
allElements. TrainingUI (as will most UIs) sets all elements as part of the constructor.

Base class handling for table server context is handled between GenericETableModel and
GenericETableESDataManager. GenericETableModel maintains original values for each cell and for
each row. GenericETableESDataManager makes use of this data when populating the request ESData.

17-110
17.8 Threads and Messaging

A complete SwingWorker cycle occurs for each message sent to the server. For user requests involving
multiple messages, multiple sequential (synchronous) SwingWorker threads will be created. The flow is
the following:

1. SwingWorker construct results in a request/response exchange with the server.

2. SwingWorker finished invokes processResponse to do response handling. One of the
responsibilities of processResponse is to update the variable moreDataToSend stored in an
instance of MultipleThreadsContext.
3. When processResponse returns to finished, finished checks moreDataToSend to determine if
another thread should be created or if all messages have been sent.

MultipleThreadsContext contains the list of requests needed to satisfy the user request, and an index to
denote the current request. The instance of MultipleThreadsContext created at the time of the first
request is passed to subsequent SwingWorker threads.

The one exception to the above is a table load request. A single SwingWorker thread is used to gather all
of the table data before finished is invoked.

Additionally, the instance of ESDataResponseObject that is created at the time the first request is
created, is passed to subsequent SwingWorker threads. In other words, when all requests have been
processed, the ESDataResponseObject contains data from all of the threads.

17.9 Additional Features

17.9.1 Class Data Variable enableOnView

This variable controls whether the save action is enabled upon a successful view response. The default is
enableOnView = true. UIs that support the precise enable/disable of the save action will specify
setEnableOnView( false ) as part of the constructor.

Convention: The standard is to use the default (enableOnView = true). There is no action on the part of
the extension to use the default.

17.9.2 Class Data Variable keyChangesPartOfUnsaved

This variable controls whether key changes are to be considered when determining unsaved changes. The
default is keyChangesPartOfUnsaved = false. The accessor setKeyChangesPartOfUnsaved can be
used to change this.

17-111
Convention: The standard is to use the default (keyChangesPartOfUnsaved = false). There is no action
on the part of the extension to use the default.

17.9.3 Class Data Variable useConditionalCanDelete

This variable controls whether the framework preference for showing a confirmation prompt on deletes is
honored. If this value is true, the framework preference is honored (i.e., the prompt is displayed or not
based on the preference). If this value is false, the prompt is always displayed. The default value is true.

Convention: The standard is to use the default (useConditionalCanDelete = true). There is no action on
the part of the extension to use the default.

17.9.4 Class Data Variable negativeViewIsInsert

Identifies whether the behavior for a negative view response is to prompt the user to enter new
information. The negative view response status values that result in this behavior are file_exhausted and
not_found. This variable is useful in the case where the key component(s) for the UI is a text field instead
of a list of defined keys (e.g., an ETextField instead of an EComboBox).

If this value is true, the user is prompted to enter new information. If this value is false, the negative view
response behavior is the same as all other negative response behavior (i.e., red status bar message). The
default is false.

Convention: The standard is to use the default (negativeViewIsInsert = false). There is no action on the
part of the extension to use the default.

17.9.5 Class Data Variable insertRowAlwaysEnabled

Denotes that the insert row always remains enabled for this UI. Used by UIs that consist only of a table
(e.g., Linked Currency UI).

If this value is true, the insert row action always remains enabled, otherwise, the action is enabled after a
successful view or at the point the user enters new key values.

Convention: The standard is to use the default (insertRowAlwaysEnabled = false). There is no action on
the part of the extension to use the default.

17.10 Summary of Changes from Previous Version of

AbstractESApplicationFrame

AbstractESApplicationFrameWithTable has been replaced by

AbstractESApplicationFrameForTable. All UIs will extend

17-112
ESTableServerHelper is no longer used. It’s function is now being done by one of the new table
classes, GenericETableESDataManager.

ESTableInformationObject and related method populateESTableInformationObject are no

longer used. This function has been moved to the table property file. In other words, mapping
table requests to ESData objects is now done via property file parameters.

ESTable references have been replaced by GenericETableMgr references.

getServerViewRequest, getServerInsertRequest, getServerUpdateRequest,

getServerDeleteRequest and getServerSubmitRequest are no longer abstract. This was changed
because an extension should only have to implement methods pertaining to the behavior the UI
supports. An additional change related to these methods is that now the extension must specify
whether it’s table(s) are affected by a user action. For example, the implementation of
getServerUpdateRequest must specify which table(s) are to be processed.

notifyInitializeComplete and notifyESListChanged are no longer abstract. These methods

primarily dealt with assigning the list model to combo boxes and to refreshing the combo box
model. AbstractESApplicationFrameForTable methods setModel and refreshModel provide
default implementation for this behavior. These methods can be overridden by the extension if the
default behavior isn’t sufficient. Typically, the default behavior is not sufficient if the combo box
model is not a RefreshComboBoxModel or if the list retrieved from the ManagedList has to be
manipulated in any way.

Abstract methods notifySuccessfulView, notifySuccessfulUpdate, notifySuccessfulInsert,

notifySuccessfulView, and notifySuccessfulSubmit are no longer used. The extension now will
override getStatusBarMessage (abstract) plus one or more of the following to do the extension
specific work at response time:

extensionUpdateManagedList
extensionUpdateTitleItem
extensionUpdateUISpecial

The timing of canUpdate has been moved to after the verify of visual components.

The submit action has been added.

The clearRow action has been added.

17-113
18 GenericETableMgr

18.1 Introduction

This section provides information for using GenericETableMgr and related classes.
GenericETableMgr is the replacement for ESTable.

GenericETableMgr and related classes are all concrete implementations. There are no abstract classes
that must be implemented. There will be occassions where extensions may be needed, and this section of
the document covers how to extend classes that are the most likely extension candidates.

This section contains the following subsections:

Creating a GenericETableMgr Extension. GenericETableMgr is a concrete class, so an extension is not

required. In the event an extension is needed, this section describes what’s required to get
ESComponentBuilder to create an instance of the extension.

Creating a GenericETableESDataManager Extension. GenericETableESDataManager is the class that

deals with mapping the table data to/from an ESData. The class is concrete, but will be occasionally
overridden. This section describes how to instantiate an extension to this class, and describes the override
conveniences that have been provided.

Creating a GenericETableModel Extension. GenericETableModel is the ETableModel extension. It is

a concrete class. In the event an extension is needed, this section describes how to instantiate the
extension.

GenericETableListener Interface. Describes how a class can be notified of events related to a

GenericETableMgr instance.

Convenience Methods provides information on frequently used public methods within

GenericETableMgr.

Overview of the Classes. This section describes all of the classes that have been created as part of the
table rewrite project.

18.2 Creating a GenericETableMgr Extension

GenericETableMgr is a concrete class, thus an extension is not required. If an extension is needed, the
following steps can be followed to create one.

1. In the UILayout definition, specify the extension to GenericETableMgr. Example:

18-114
 ClassName = es.desktop.testui.TableExtension

2. Override method getNewGenericETableMgrInstance in the ESComponentBuilder extension.

Create the instance of the GenericETableMgr extension. A sample of what this method might
look like where the GenericETableMgr extension is named TableExtension.

public GenericETableMgr getNewGenericETableMgrInstance

( String tableDefinitionFileName,
ESAppJStatusBar referenceToStatusBar
JpopupMenu referenceToPopupMenu)
{
TableExtension table = null;
try
{
table = new TableExtension
( tableDefinitionFileName,
referenceToStatusBar,
referenceToPopupMenu );
}
catch (Exception e)
{
Desktop.getDesktop().getLog().error(e);
getUIRef().getStatusBarRef().displayStatus(e.toString(),
es.desktop.ApplicationStatusPane.ERROR);
}

return table;
}

18.3 Creating a GenericETableESDataManager Extension

18.3.1 Creating the Extension

GenericETableESDataManager is a concrete class, so an extension is not required. If an extension is

needed, the following steps can be followed to create one.

1. Create an extension to GenericETableMgr.

2. Override GenericETableMgr method createDataManager.
3. Invoke method setGenericETableDataManager, providing the GenericETableESDataManager
extension as the arugment.

18.3.2 Override Conveniences

Because this class has responsibility for doing the table data/ESData mapping, there may be some need to
create extensions. Several override convenience methods have been supplied to facilitate extension-
specific ESData creation and extension-specific table loading.

18-115
Method moveRowsToScreenSpecial is invoked for each response ESData as rows are being moved from
the response ESData to the screen data.

Method populateESDataSpecial is invoked for each row as table data is being moved to an ESData.

Method populateNonRecurringESDataSpecial is invoked when table data is being moved to an ESData

and the ESData is non-recurring.

Method updateWithResponseDataSpecial is invoked as part of the method that updates the table with
response data. This process primarily deals with updating row server context. Provides the extension
with ability to modify the screen ESData before it is sent to the model. This method is invoked one time
(i.e., not once for each row), just before the screen data is sent to the model.

18.4 Creating a GenericETableModel Extension

GenericETableModel is a concrete class, so an extension is not required. If an extension is needed, the

following steps can be followed to create one.

1. Create an extension to GenericETableMgr.

2. Override GenericETableMgr method assignTableModel.
3. Invoke GenericETable methods setMainTableModel and getMainTable.setModel. The
reference to GenericETable is obtained by accessor getGenericETable.

18.5 GenericETableListener Interface

Classes wishing to listen for GenericETableEvent events will implement the GenericETableListener
interface, and invoke GenericETableMgr method addGenericETableListener to add themselves as a
listener.

GenericETableListener method genericETableEditOccurred( GenericETableEvent evt ) is

invoked when the contents of a cell are changed (when TableModelListener method tableChanged is
invoked).

GenericETableListener method genericETableSelectionOccurred( GenericETableEvent evt ) is

invoked when there is a row selection change. (when ListSelectionListener invokes valueChanged).

18.6 Convenience Methods

GenericETableMgr contains the following frequently used convenience methods. Refer to the javadoc
for this class for additonal information.

18-116
 Method Comment
getTableColumnIndex( String ) Retrieves the index of the table column
corresponding to the provided argument.
getTableColumn( String ) Retrieves the TableColumn corresponding to
the provided argument.
getColumnCellRenderer( String ) Retrieves the GenericCellRendererMgr
corresponding to the provided argument.
getColumnCellRendererEComponent Retrieves the GenericETableEditing
( String, String ) corresponding to the provided arguments.
getColumnCellEditor( String ) Retrieves the GenericCellEditorMgr
corresponding to the provided argument.
getColumnCellEditorEComponent Retrieves the GenericETableEditing
( String, String ) corresponding to the provided arguments.
isTableDataValid() Determines if the table contains edit errors.
checkForEmptyRow() Method used to check if there are any empty
rows present on the table.
retrieveTableStatus( int ) Retrieves rows that match the specified input
arguments.
doDeleteRowAction() Sets the delete row icon for all selected rows.
doInsertRowAction() Adds an empty row and sets the insert row
icon.
insertRowAndChangeSelection() Adds an empty row, sets the insert row icon,
and changes the selection to the last row.
reset() Resets the table manager. For a standard table
(insertable), the behavior is to set the table to
it's initial state (typically a single empty row).
For a fixed row table, the behavior is initialize
all of the cells in the table. Additionally resets
any sorting.
doRevertRowAction() For each selected row, each cell is set to it's
original value.
doesTableContainData() Determines whether any rows in the table have
data.
doesTableContainDuplicate( int[] ) Checks the rows in the table to see if there are
any duplicates. Error notification is performed
for any row determined to be a duplicate.
resetAllCellsToValidState() Resets all cells to a valid state.
changeAllRowsToInserts() For each row in the table, the selection column
is set to the insert icon.
addGenericETableListener Adds the specified GenericETableListener to
( GenericETableListener ) this GenericETableMgr. The listener will
receive selection and editing events.
removeGenericETableListener Removes the specified GenericETableListener
( GenericETableListener )
from this GenericETableMgr.

18-117
18.7 Overview of the Classes

Class Name Description

High Level Classes These classes are concerned with the entire
table. They have high level responsibilities
including property management, initial table
construction, and table/data object (ESData)
mapping.
GenericETableMgr Provides common table behavior. This class
extends JPanel and is a complete self contained
visual table component. From a
conceptual/behavioral view, this class replaces
ESTable.
GenericETable Provides standard table (insertable and deleteable)
behavior. This class wraps the ETable.
GenericETableFixedRow Provides fixed row table behavior. This class
wraps the ETable.
GenericETableBuildPanel This class does the initial rendering of the table and
positions it in the scrollpane/panel.
GenericETableDataManager Abstract class that provides a framework for data
movement between a table and a
GenericTableDataObject object. A
GenericTableDataObject is an interface. An
example of a class that implements this interface is
ESData.
GenericETableESDataManager Provides data movement between a table and an
ESData object.
GenericETablePropMgr Unloads the table definition file into work areas
that are accessible to GenericETableMgr and
related classes.
GenericETableModel Provides ETableModel behavior specific to the
needs of GenericETableMgr and related classes.
GenericETableModelFixedRow Provides fixed row specific GenericETableModel
behavior.
GenericETableModelSortable Provides table model behavior that is specific to a
sortable GenericETableModel.

Low Level Cell and Column These classes focus on managing cell
Editor/Renderer Classes editing/rendering and the actual editing and
rendering of the cells.
GenericCellEditorMgr The primary responsibility of this class consists of
high level cell editor functions.

18-118
 Class Name Description
Instances of this class are assigned as the
TableCellEditor instances, and are returned when
TableColumn.getCellEditor is invoked; however,
the actual editor is a lower level component (e.g.,
GenericEComboBoxEditor).
GenericCellRendererMgr The primary responsibility of this class consists of
high level cell renderer functions.

Instances of this class are assigned as the

TableCellRenderer instances, and are returned
when TableColumn.getCellRenderer is invoked;
however, the actual editor is a lower level
component (e.g., GenericEComboBoxEditor).
GenericETableCellEditor This class contains the lower level cell editor
instance. The lower level cell editors (e.g.,
GenericEComboBoxEditor) must implement the
GenericETableEditing interface. This class
provides the actual cell editor to
GenericCellEditorMgr.
GenericETableCellRenderer This class contains the lower level cell renderer
instance. The lower level cell renderers(e.g.,
GenericEComboBoxEditor) must implement the
GenericETableEditing interface. It provides the
actual cell renderer to GenericCellRendererMgr.
GenericETableEditing An interface that must be implemented by the low
level cell editor/renderer components.
GenericECheckBoxEditor Implements GenericETableEditing and provides
ECheckBox cell editor/renderer behavior.
GenericEComboBoxEditor Implements GenericETableEditing and provides
EComboBox cell editor/renderer behavior.
GenericEComboBoxEditorLocal Implements GenericETableEditing and provides
localized EComboBox cell editor/renderer
behavior.
GenericEReadOnlyRenderer Provides read only renderer behavior.
GenericETextFieldEditor Implements GenericETableEditing and provides
localized ETextField cell editor/renderer behavior.
GenericETextFieldHexEditor Implements GenericETableEditing and provides
localized ETextField cell editor/renderer behavior.
Only hex characters are honored.
GenericETextFieldIntegerEditor Implements GenericETableEditing and provides
localized ETextField cell editor/renderer behavior.
Only numeric characters are honored.
GenericERowHdrColRenderer A special renderer for use by row headers in a fixed
row table.
GenericESelectColRenderer A special renderer used for the selection column.

18-119
 Class Name Description
GenericETableMaskDoc A PlainDocument extension that is used by the
specialized text editors.
GenericETableMaskHex Used in conjunction with GenericETableMaskDoc
to provide masked editing.
GenericETableMaskInt Used in conjunction with GenericETableMaskDoc
to provide masked editing.
GenreicETableMaskType An interface that defines methods required for
editors that use masks.
GenericEComboBoxEditorListData Implements GenericETableEditing and provides
EComboBox cell editor/renderer behavior for an
EComboBox using a list of ManagedListData
objects.
GenericEDateSpinnerEditor Implements GenericETableEditing and provides
EDateSpinner cell editor/renderer behavior.
GenericEDateTextFieldEditor Implements GenericETableEditing and provides
non-editable EDateSpinner cell editor/renderer
behavior.
GenericESpinnerEditor Implements GenericETableEditing and provides
ESpinner cell editor/renderer behavior.
GenericETimeSpinnerEditor Implements GenericETableEditing and provides
ETimeSpinner cell editor/renderer behavior.
GenericETimeTextFieldEditor Implements GenericETableEditing and provides
non-editable ETimeSpinner cell editor/renderer
behavior.
GenericECurrencyFieldEditor Implements GenericETableEditing and provides
EcurrencyField cell editor/renderer behavior.

Miscellaneous/Utility Classes
GenericETableConstants Contains the constants used by GenericETableMgr
and related classes as well as constants for keyword
values used by the table definition file.
GenericTableException An exception of this type is thrown when there is
an error either constructing a GenericETableMgr,
or an error in exchanging data with a
GenericETableMgr.
GenericETableEvent This class encapsulates the selection and editing
events for GenericETableListeners.
GenericETableListener A class that wants to be notified of editing and
selection events in the GenericETableMgr will
implement this interface.
GenericETableSorter Helper class that participates in the sorting
behavior.
GenericETableSortRenderer Used to provide the rendering of the sortable
columns.

18-120
 Class Name Description
GenericETableRow Contains information specific to a row. For
example, original values are kept here which is the
way non-visible fields (e.g., Server Context) are
saved.

18-121
19 Miscellaneous Classes
This section lists classes that have been referenced in this document, but not described.

19.1 SelectionComboBox

SelectionComboBox is an extension of EComboBox. It provides common behavior needed for any

EComboBox that is a selection combo box. A selection combo box is typically used to provide key
selection/entry behavior. Any class using an instance of SelectionComboBox must implement
SelectionComboBoxUser.

SelectionComboBoxNoEdit is provided for a non-editable selection combo box implementation.

Some of the things this class helps with:

- Provides an editor, actionListener, keyListener, and focusListener that forward to the
SelectionComboBoxUser only what is necessary.
- Determines whether the value of the combo box is equal to the server context value. Useful when
determining whether or not to enable/disable toolbar actions.
- Unsaved changes. Within the actionFired logic, this class interacts with the
SelectionComboBoxUser to determine if there are unsaved changes. This class has the logic to
restore the previous value for the CANCEL case.
- Provides the following conveniences:
o A class data member of disregardComboAction.
o A class data member for the initial text (e.g., Select/Enter).
o A class data member for denoting whether to upshift and implementation for upshifting.
o Convenience methods. Refer to the javadoc for the following:
 resetCombo
 setIndexFromCurrentText
 setIndexFromString
 textIsInitialValue
 textIsValued
 hasServerContext
 isNewKey
 isExistingKey
 getEditorText
 setEditorText

19.2 SelectionTextField

SelectionTextField is an extension of ETextField. This class provides common behavior needed for any
ETextField that is a selection text field. A selection text field is typically used to provide key entry
behavior. Any class using an instance of SelectionTextField must implement SelectionComponentUser.

19-122
19.3 RefreshComboBoxModel

Instances of class RefreshComboBoxModel are used as the list model for combo box components that
use a dynamic list that is populated from a server data source. The Training UI Profile combo box uses a
RefreshComboBoxModel.

The ESDesktopApplication method requestGetListModel( String listName ) results in the return

of a new instance of RefreshComboBoxModel constructed with the java.util.Vector from the requested
ManagedList (where the requested ManagedList is determined by the argument listName).
RefreshComboBoxModel provides the behavior of a DefaultComboBoxModel, except that it doesn’t
allow inserts or deletes to/from the data model. The intent is to allow external UIs (i.e., non-owners of the
MangedList) to access the java.util.Vector from the ManagedList, but keep control of inserts and
deletes within the UI that owns the ManagedList.

19-123
20 Source Code for the Training UI
The source code for the Training UI is now maintained within software management. Please refer to the
source code for references.

20-124
21 Using XMLTestHost
XMLTestHost is an internal tool. Since this is an external document, we have removed this section.

21-125
22 FAQs
This section documents responses to developers questions. An effort is made to fit this material into the
main body of the document, but if there is no convenient place to insert the material, it is placed in this
section.

22.1 Adding an Action to the Right-Click Menu

The following steps were followed to add an action to the Training UI. The action shows up on the right-
click menu with the text Test Action. With the logic shown below, the only behavior tied to the action is
to put out a System.out message (shown in step 3 below).

Note: The accelerator only works when the component that is tied to the action is visible. This
means if the action is only on the right-click menu, the accelerator only works if the right-click
menu is showing.

1. Add the option to the property file.

Training.popupMenu=save clear refresh | delete | insertRow deleteRow undo | test

Training.test.Mnu.text=Test Action
Training.test.Mnu.toolTipText=Tool tip text for test action.
Training.test.Mnu.accelerator=control T

All of the rest of the changes are to the AbstractESApplicationFrameForTable extension.

2. Add a class variable and accessors for the new action.

private Action testAction;

protected Action getTestAction()
{
return testAction;
}
protected void setTestAction( Action input )
{
testAction = input;
}

3. Add the action as an inner class.

public class TestAction extends AbstractAction

{
public TestAction( String input )
{
super( input );
}

22-126
 public void actionPerformed( ActionEvent e )
{
System.out.println( "bpmt test action fired:" );
}

} // End of class

4. Override setCustomAction

public void setCustomAction( String action, Vector actionVector )

{
if ( action.equals( "test" ))
{
Action a = new TestAction( action );
actionVector.add( a );
setTestAction( a );
}
}

5. At the end of the UI initialization, set the accelerator. The following logic goes in notifyInitializeComplete. Literals
are shown, but the actual implementation would use constants.

if ( getInitInProgress() )
{
KeyStroke testAccelerator = KeyStroke.getKeyStroke
( LocaleManager.getStringResource
( UI_PROPERTY_FILE, "Training.test.Mnu.accelerator"));
JPanel mainPanel = ((JPanel)getESComponentBuilder().getPanelItem( "MainPanel" ));
mainPanel.getInputMap( WHEN_IN_FOCUSED_WINDOW ).
put( testAccelerator, getTestAction().getValue( Action.NAME ));

mainPanel.getActionMap().put( getTestAction().getValue( Action.NAME ), getTestAction() );

}

22.2 Security Considerations for a Custom UI

The following steps need to be followed to address custom UI security considerations.

1. Override method determineSecurity in the ESDesktopApplication extension. The logic for the Iconnect
Interface custom UI is as follows:

/**
* Determines whether the user has security for the supplied uiName.
* @param uiName The supplied uiName.
* @param navAppID Property file containing the navigation branches.
*/
protected boolean determineSecurity( String uiName, String navAppID )
{
boolean retval = false;
if ( Desktop.getDesktop().getSecurityManager().isTaskAllowed( ICONNECT_INTERFACE_TASKID ) )

22-127
 {
retval = true;
}
return retval;
}

ICONNECT_INTERFACE_TASKID is in the constants interface and is defined as follows.

public static final String ICONNECT_INTERFACE_TASKID = "iConnect";

The value “iConnect” came from the security administrator and is specific to the customer’s environment.

2. Unless it’s being used in the determineSecurity override, the securityTaskID property in the UI property
file isn't used, so it can be removed.

3. Make sure that the value returned by AbstractESApplicationFrameForTable extension method

getSecurityTaskID, is the security task ID. In this case, that is the value “iConnect”.

22.3 Considerations for a Table UI where Details are Outside of the Table

The Surcharge Profile UI and the ATM Receipt Format UI use a table for purposes of displaying/entering
key values, and use visual components outside of the table for display/entry of the detail components.
These UIs are designed this way because to show all of the detail components in the table would have
resulted in a table too wide to be user friendly; however, the table form is the best one to show the key
values.

What follows are the notes sent to the ATM Receipt Format developer to outline what needed to be done
to support this behavior. Packages atmreceiptformat and surcharge contain UIs where this behavior is
implemented.

Note: This section was added prior to the adoption of ES UI Client Coding Standards. therefore, the
implementation examples don’t conform to the standard.

1. Behavior tied to the key component(s).

Currently when a Receipt Profile is selected, you are going to the server with a view request and
populating the table. This is the correct thing to do, but there are some additional things that need to be
done.

a. The view response needs to include all of the data source elements (i.e., it needs rcptFrmtPrntrTypeCd,
rcptFrmtPrntrSubTypeCd, and rcptFrmtTmpltData).

b. The ESData definition ATMReceiptFormatScreenDetails needs to include all of the data source
elements (i.e., it needs rcptFrmtPrntrTypeCd, rcptFrmtPrntrSubTypeCd, and rcptFrmtTmpltData). These
fields won't be visual fields in the table, but by putting them in this definition, the values of these fields
will be stored on the table model along with their respective key fields. This will allow item #2 to be
implemented.

22-128
2. Behavior for when the user selects a table row.

When a row is selected, you need to retrieve values from the table model and populate the bottom panel.

This code fragment comes from CurrencyConvRateComponentBuilder, and is an example of logic that
listens for row selection.

public void genericETableSelectionOccurred(GenericETableEvent evt)

{
if ( evt.getType() == GenericETableEvent.ROW_SELECTION_HAS_OCCURRED )
{
rowSelectionHasOccurred( evt.getSelectedRows(), evt.getSelectedRowIndex() );
}

This is some logic that gives you an idea of what's needed to get data from the table model, and update the
Printer Type Code.

GenericETableModel tableModel =

((GenericETableMgr)getPanelItem( "ATMReceiptFormatTable"
)).getGenericETable().getMainTableModel();

HashMap rowData = tableModel.getRow( evt.getSelectedRowIndex() );

// The next few statements show logic for Printer Type Code. Similar logic will be needed for the other
two fields.
String cellKey = "ATMReceiptFormatScreenDetails.rcptFrmtPrntrTypeCd";
String value =
rowData.get(cellKey) == null ? "" : rowData.get(cellKey).toString();
getPrinterTypeCode().setValue( value );

3. Update Row

When the user changes values in the lower panel, you will need to update the table model with the new
values, and update the selection column for the appropriate row. Here are the impacts that I can see.

a. Method getServerUpdateRequest should only return the table reference. Currently, you are returning
two elements ( return new String[] { UPDATE_RQ, TABLE_NAME };).

b. Updating the table model.

Anytime the user changes any of the lower fields, you need to update the table model. For the two combo
box fields, you will need an action listener that will allow you to know when these values change. As an
example, both the External Connection UI and Listener UI use action listeners on the Protocol Option

22-129
field. For the ETextPane, you will need a KeyListener to allow you to know when the user changes this
field. An example of adding a KeyListener is as follows:

((ETextPane)getEComponent( TEMPLATE_FIELD )).addKeyListener(new java.awt.event.KeyAdapter()

{
public void keyReleased(java.awt.event.KeyEvent e)
{
// Your logic to update the model goes here.
}
});

You will use GenericETableModel method updateRow to update the table model.

GenericETableModel tableModel =
((GenericETableMgr)getPanelItem( "ATMReceiptFormatTable"
)).getGenericETable().getMainTableModel();

HashMap rowData = new HashMap();

int selectedRow =
((GenericETableMgr)getPanelItem( "ATMReceiptFormatTable"
)).getGenericETable().getMainTable().getSelectedRow();

// The next few statements show logic for Printer Type Code. Similar logic will be needed for the other
two fields.
String cellKey = "ATMReceiptFormatScreenDetails.rcptFrmtPrntrTypeCd";
String value = getPrinterTypeCode().getValue();
rowData.put( cellKey, value );
tableModel.updateRow( rowData, selectedRow );

c. Setting the selection column.

When any of the fields in the lower panel change, you need to set the selection column on the appropriate
row to the updated icon. You use GenericETableMgr method setMainTableUpdateIcon to accomplish
this.

int selectedRow =
((GenericETableMgr)getPanelItem( "ATMReceiptFormatTable"
)).getGenericETable().getMainTable().getSelectedRow();

((GenericETableMgr)getPanelItem( "ATMReceiptFormatTable" )). setMainTableUpdateIcon(

selectedRow );

4. Insert Row

22-130
All the notes for update row apply to insert row, except for note c. (Setting the Selection Column). The
selection column doesn't get set in the insert row case.

5. Delete Row

There is nothing special for delete row.

6. Trash Can Delete

A user will use the trash can delete to delete all records associated with a profile. In your UI class
constructor include the statement setUseConditionalCanDelete( false ), so that the user will not be able to
turn off the confirmation (see CurrencyConvRateUI).

Your ESData definition for delete will be non-recurring. Something like the following:

[ATMProfileDeleteRq]
rcptFrmtInstId =es.shared.GenericString,99
rcptFrmtPflTx =es.shared.GenericString,99

[ATMProfileDeleteRs]

7. Copying from one Receipt Profile to another.

This allows the user to take existing records (e.g., Profile6), and copy them to a new Receipt Profile (e.g.,
Profile7). I don't think there is anything you have to do for this. When I test this case with the UI as it
exists today, the rows are changed to insert rows like they should.

8. Revert (Undo) Row

When the user issues a revert (undo) row, we need to revert the fields in the lower panel to their original
values. For example:

- User selects a row in the table. The bottom panel is populated.

- User changes something in the bottom panel.
- User issues the revert (undo) row. The components in the bottom panel should be set back to their
original values.

a. Saving the original values.

To provide this behavior, you are going need to add the following to ATMReceiptFormatScreenDetails
and ATMReceiptFormatViewEntry:

holdRcptFrmtPrntrTypeCd
holdRcptFrmtPrntrSubTypeCd
holdRcptFrmtTmpltData

22-131
In your UI class, you need to override processViewTableResponse. Your implementation will include the
existing instructions, except just before moveDataRowsToScreen is invoked, you will need to alter
memoryData.

int tableAffected = responseObject.getTableAffected().size() - 1;

GenericETableMgr genericETableMgr =
(GenericETableMgr)responseObject.getTableAffected().get( tableAffected );
ESData memoryData =
(ESData)responseObject.getTableLoadResponseESData().get( tableAffected );

// Add logic here to populate the holdXxxx fields in memoryData.

genericETableMgr.getGenericETableDataManager().moveDataRowsToScreen( memoryData );

b. Overriding the revert (undo) row logic.

In your UI class, override method revertRowActionPerformed. Your implementation will do everything

the existing implementation does, except that at the end of the method you will need to update the original
values in the table model from the holdXxxx values. Once you get to this point let me know and I will
help you with the logic.

22.4 Adding a list item to a Combo Box that uses a ManagedList

The UI Property File provides for the ManagedList property. This property allows a developer to link a
ManagedList to a combo box. Due to logic in AbstractESApplicationFrameForTable, there is no
additional work for the developer outside of defining the ManagedList property. Example:

ATMChannel.eats1dRcptPrflTx.managedList=ATMReceiptFormatList

The UI Property File also provides for the ability to add the {none} item to the list. Example:

ATMChannel.ATMReceiptFormatList.managedListNoneOption=true

Lastly, the UI Property File provides for the ability to add the ANY item to the list. No UI currently uses
this feature but an example would be:

xxxx.institutionListFiltered.managedListAnyOption=true

Where xxxx is the property file prefix and institutionListFiltered is the managed list name.

If there is a need to add some other item to the list besides ANY or {none}, the easiest way is to override
the method that add the ANY item, and instead add the required item.

ATM Receipt Format UI has the need to add an “*” item to the Institution ID drop down list. The
implementation steps to accomplish this are the following:

22-132
 1. Define the managedListAnyOption property for the affected list.

ATMReceiptFormat.institutionListFiltered.managedListAnyOption=true

2. In the UI class, override method updateComboWithAnyOption. The following comes from

ATMReceiptFormatUI. The override results in an “*” being added instead of the text “ANY”.

protected void updateComboWithAnyOption( HashMap mapListToComponent,

boolean refreshModelOption )
{
String anyText = "*";
addItemsToManagedList( mapListToComponent,
refreshModelOption,
new String[] { anyText },
0 );
}

Note: To conform to ES UI Client Coding Standards, the literal “*” would be replaced with a constant
name.

22.5 Overriding the Default for a Table Cell ESpinner

The base class implementation default values a table cell Espinner component to the Min Value defined
by the field edit. This didn’t work well for the ATM Channel Admin Hopper Table adjust column,
because the Min Value is –99999.

The following is an e-mail that outlines steps for using 0 as the default value. The final implementation
can be seen in package atmchanneladmin.

Note: This section was added prior to the adoption of ES UI Client Coding Standards. therefore, the
implementation examples don’t conform to the standard.

I used my own editor for the Adjust column. My editor is an instance of GenericESpinnerEditor, with the difference
being, I am overriding setValue and assigning 0 as the default.

Here is the logic I added to initComponents to add my own editor and renderer.

GenericETableMgr hopperTableMgr = ((GenericETableMgr)getPanelItem( "Tab1" ));

TableColumn column = hopperTableMgr.getGenericETable().getMainTable()
.getColumnModel().getColumn( 8 );
GenericCellEditorMgr adjustMgr = (GenericCellEditorMgr)column.getCellEditor();

GenericESpinnerEditor adjustE = new GenericESpinnerEditor()

{
public void setValue(Object pValue)
{
String retval = (String) pValue;

22-133
 retval = retval == null ? "" : retval;

if (retval.trim().length() == 0)
{
retval = "0";
}
super.setValue( (Object)retval );
}
};
adjustE.setMinValue( -99999 );
adjustE.setDefault( "0" );
adjustE.setMaxValue( 99999 );

adjustMgr.addEditor( "AdjustEditor", adjustE );

GenericESpinnerEditor adjustR = new GenericESpinnerEditor()

{
public void setValue(Object pValue)
{
String retval = (String) pValue;
retval = retval == null ? "" : retval;

if (retval.trim().length() == 0)
{
retval = "0";
}
super.setValue( (Object)retval );
}
};
adjustR.setMinValue( -99999 );
adjustR.setDefault( "0" );
adjustR.setMaxValue( 99999 );

GenericCellRendererMgr rendererMgr = (GenericCellRendererMgr)column.getCellRenderer();

GenericETableCellRenderer renderer = new GenericETableCellRenderer( adjustR );
rendererMgr.addRenderer( "AdjustEditor", renderer );

In the table properties, I changed the column editor for the Adjust column.

[Column8]
Column.columnKey=hprAdjust
Column.columnHeaderLocaleKey=ATMChannelAdmin.hprAdjust
Column.columnEditor=AdjustEditor
#Column.columnEditor=eSpinner
Column.columnAccess=rw
Column.columnKeyFieldAccess=rw
Column.columnWidth=90

22.6 Using an ESFindDialog

22-134
The logic and properties samples come from the packages es.desktop.card and es.desktop.atmchannel.
Both of these packages are good examples of using an ESFindDialog. The main difference between the
two is that the Card UI uses two columns in it’s ESFindDialog Results table (Card Number and Member
Number) and the ATM Channel UI uses a single column (Channel ID).

Note: This section was added prior to the adoption of ES UI Client Coding Standards. therefore, the
implementation examples don’t conform to the standard.

22.6.1 Layout Components

The following layout components come from LayoutKeysPanel.cfg.

lblCardNum = framework.desktop.ecomponents.ELabel
txtCardNum = es.desktop.SelectionTextField
btnFindCard = framework.desktop.ecomponents.EButton

The component used for data entry will normally be either a SelectionTextField or an ETextField. As is
the case in the example above (txtCardNum), if the component is a key component it will normally be a
SelectionTextField. If the component is not a key component, it will normally be an ETextField.

The find button is an EButton.

22.6.2 FindDialog Properties

There are several properties that must be defined for the ESFindDialog. The properties for the Card UI
are as follows.

#
# Card - Find Dialog entries
#
CardCnfg.findDialog.listMsgType.text=CardPANListRq
CardCnfg.findDialog.startKey.text=StartKey
CardCnfg.findDialog.endKey.text=EndKey
CardCnfg.findDialog.listResponseRootTag.text=CardList
CardCnfg.findDialog.listResponseTag.0.text=crddPAN
CardCnfg.findDialog.listResponseTag.1.text=crddCardSeqNum
CardCnfg.findDialog.columnHeader.0.text=Card Number
CardCnfg.findDialog.columnHeader.1.text=Member Number
CardCnfg.findDialog.selectionMode=SINGLE_SELECTION

The ESData request and response that play a part in the ESFindDialog are the following:

#=============[ CardPANList ]===============

[CardPANListRq]
crddInstID =es.shared.ESString
StartKey =es.shared.ESString
EndKey =es.shared.ESString

22-135
[CardPANListRs]
CardList ={CardList}+

#=============[ CardList ]===============

[CardList]
crddPAN =es.shared.ESString
crddCardSeqNum =es.shared.ESString

listMsgType When the user clicks Find on the ESFindDialog, a list request
is sent to the server. This property specifies the root name
of the list request.

startKey Specifies the element name in the list request that is the
start key.

EndKey Specifies the element name in the list request that is the
end key.

listResponseRootTag The recurring group element in the list response.

listResponseTag.0 The list response sub element under the group recurring
element.

listResponseTag.1 In the case of Card, there are two sub elements. Typically
there will only be one.

columnHeader.0 On the Find Dialog, you see a Results table. This property
defines the text used for column header (in this case Card
Number).

columnHeader.1 In the case of Card, there are two column headers. Typically
there will only be one.

SelectionMode Dictates how many rows in the Results table the user is able
to select. This will typically be valued with
SINGLE_SELECTION.

22.6.3 Action Tied to the EButton.

When the find button is clicked, the UI needs to display a find dialog. This involves tying the find button
to an action, then handling the action.

I’ve chosen to use package es.desktop.atmchannel for this section because the implementation is more
straightforward.

Tying the Find Button to an Action

The following instructions are in the constuctor of ATMChannelUI.

//
// Retrieve reference to Channel ID Button on Key Panel

22-136
 //
channelIDFindButton = ( ( EButton )getESComponentBuilder()
.getEComponent( KEY_BUTTON_CHANNEL_ID ) );

//
// Instantiate FindActionListenerRetrieve
//
FindActionListener findActionListener = new FindActionListener();

//
// Add listener to Channel ID Button
//
channelIDFindButton.addActionListener( findActionListener );

Defining the ActionListener

The ActionListener is defined as an inner class in ATMChannelUI. When actionPerformed is initiated

(due to the user clicking the find button), method findActionPerformed is invoked.
private final class FindActionListener implements ActionListener
{
public FindActionListener()
{
super();
}

public void actionPerformed( ActionEvent evt )

{
findActionPerformed();
}
} // End of class FindActionListener

Handling the Action

Method findActionPerformed creates the ESFindDialog. A slightly more straightforward creation of the
ESFindDialog would be:

// Instantiate ESFindDialog
findDialog = new ESFindDialog(
Desktop.getDesktop(),
this,
PROPERTY_FILE );

private void findActionPerformed()

{
if ( findDialog == null )
{
// Instantiate ESFindDialog
findDialog = new ESFindDialog(
Desktop.getDesktop(),
getATMChannelUI(),
ATMChannelConstants.PROPERTY_FILE );

22-137
 //
// Place the dialog in the desired location ( relative to the
// Channel ID text field ):
//
Point loc = channelIDField.getLocationOnScreen();
loc.move( ( int )loc.getX(),
( ( int )loc.getY() + channelIDField.getHeight() ) );
findDialog.setLocation( loc );
//
// Set the initial start key field in the dialog
//
findDialog.setStartKey( channelIDField.getText() );
//
// Show the dialog in the desired location
//
findDialog.show();
}
else
{
findDialog.setStartKey( channelIDField.getText() );
findDialog.show();
}
} // findActionPerformed

22.6.4 Implementing receiveSelectedValues

The user submits the find from the ESFindDialog. A list request is sent to the server, and the server
responds with a list response. The results table on the ESFindDialog is populated.

At this point, the user selects an item from the results table, and method receiveSelectedValues is invoked
on the class that is passed to the ESFindDialog as part of the constructor arguments (the second argument
which is type CallBack). This class is usually the same one that constructed the ESFindDialog, which is
normally the AbstractESApplicationFrameForTable extension. Normally, the behavior tied to the user
selecting an item from the results table is to set the value of the component on the main UI, then send a
view request to the server.

ATMChannelUI’s implementation of this method follows. The values argument is a Vector of Vector
objects. It will contain only one occurrence if SINGLE_SELECTION is specified in the SelectionMode
property, and this one occurrence will contain as many elements as there are columns in the ESFindDialog
results table (typically one).

public void receiveSelectedValues( Vector values )

{
if ( values != null )
{
//
// Retrieve selected row data vector from vector of selected values
//
Vector key = ( Vector )values.get( 0 );
//

22-138
 // Retrieve the Channel ID and use it as the start key:
//
startKey = ( String )key.get( 0 );
//
// Set screen fields to user's selection
//
channelIDField.setText( startKey );
//
// Access the Server
//
doServerRequest( getViewMessageConstant() );
}
}

22.6.5 Implementing loadFindDialogRequest

Implementation for this method is only needed if the start key element in the list request is more than one
element. The list request for the ATM Channel UI is as follows. Notice that there is a single element
named StartKey. For this reason, there is no need to implement loadFindDialogRequest.

[ATMChannelListRq]
StartKey =es.shared.GenericString,99
EndKey =es.shared.GenericString,99

The list request for the Card UI contains two elements that make up the start key. The first element is
crddInstID, and the second element is StartKey. For this reason, CardUI does implement
loadFindDialogRequest for the purpose of populating crddInstID.

[CardPANListRq]
crddInstID =es.shared.ESString
StartKey =es.shared.ESString
EndKey =es.shared.ESString

22.7 Dynamically Assigning the Column Editor/Renderer

22.7.1 Overview

There are scenarios where a column editor/renderer needs to be dynamically changed based on the value
of another table column.

The following table shows some examples of where we have used a custom editor/renderer to satisfy this
requirement in other UIs.

UI Column Comments Custom Editor/Renderer

Classes
Card UI, Limits Tab Period Option The editor type for this LimitPeriodOptionsCellEditor
column is one of ESpinner, and

22-139
 UI Column Comments Custom Editor/Renderer
Classes
ETextField, or EComboBox LimitPeriodOptionsCellRenderer
depending on the value of from package es.desktop.
Usage Period.
ATM Receipt Format Printer Sub Type This column uses an AdditionalDataCellEditor and
EComboBox for an editor. AdditionalDataCellRenderer
Though the editor doesn’t from package
change, the list tied to the es.desktop.atmreceiptformat.
editor changes based on the
value of Printer Sub Type.
A custom editor/renderer is
needed to deal with this
situation.
Limit Period Option The editor type for this AdditionalDataCellEditor and
column is one of ESpinner, AdditionalDataCellRenderer
ETextField, or EComboBox from package es.desktop.limit.
depending on the value of
Usage Period.
System Prefix Value The editor type is either an DataSrcIDDataCellEditor and
ETextField or an DataSrcIDDataCellRenderer
EComboBox based on the from package
value of the Type column. es.desktop.systemprefix.

22.7.2 Example

A good example is the Limit UI (package es.desktop.limit) where the Period Option column changes from
one of three editor types based on the value of Usage Period. The three editor types are ETextField,
ESpinner, and EComboBox.

The following sections show the steps involved in using a custom editor/renderer to dynamically change
the column editor/renderer. Portions of the Limit UI are referenced as example implementation.

22.7.2.1 Specifying the Editor Table Property

Choose a name to call your custom editor/renderer. Use this name as your columnEditor specification in
the table.properties file. The following comes from Column5 of LimitTable.properties.

Column.columnEditor=AdditionalDataCellRenderer

22.7.2.2 GenericETableCellEditor Extension

Create a class that extends GenericETableCellEditor. For the Limit UI, this class is
AdditionalDataCellEditor.java.

22-140
This class contains class variables for the different editors needed for this column. The constructor
assigns the class variables to new instances of the appropriate editors. The implementation for method
getTableCellEditorComponent returns the appropriate editor based on the value of the depended on
column. This method also sets the value for the appropriate editor to the value passed to the method.

22.7.2.3 GenericETableCellRenderer Extension

Create a class that extends GenericETableCellRenderer. For the Limit UI, this class is
AdditionalDataCellRenderer.java.

This class also contains class variables for the different renderers needed for this column. It has very
similar logic to the GenericETableCellEditor extension for returning the proper class variable based on the
value of the dependent column.

22.7.2.4 Linking the Column to the Custom Editor/Renderer

The table cell editors for GenericETableMgr columns are instances of class GenericCellEditorMgr. The
table cell renderers are instances of GenericCellEditorRenderer. When a custom editor/renderer is used,
method addEditor and addRenderer must be invoked to make the
GenericCellEditorMgr/GenericCellRendererMgr instances aware of the custom editor/renderer type. The
logic to do this in the Limit UI is in method initComponents of class LimitBuilder.

// Get a reference to the editor manager and renderer manager.

GenericCellEditorMgr editorMgr =
getPanelItemAsGenericETableMgr( LK_LIMIT_TABLE )
.getColumnCellEditor( LC_ADDITIONAL_DATA_HEADER );

GenericCellRendererMgr rendererMgr =
getPanelItemAsGenericETableMgr( LK_LIMIT_TABLE )
.getColumnCellRenderer( LC_ADDITIONAL_DATA_HEADER );

// Setup the default GenericETableEditing instance.

GenericETextFieldEditor notAppl = new GenericETextFieldEditor();
notAppl.setEditable( false );
notAppl.setDefault( CM_ONE_ZERO );
notAppl.reset();

// Add the custom editor and renderer.

AdditionalDataCellEditor g = new AdditionalDataCellEditor( notAppl );
editorMgr.addEditor( UI_ADDITIONAL_EDITOR_RENDERER, g );

AdditionalDataCellRenderer rendererText = new AdditionalDataCellRenderer( notAppl );

rendererMgr.addRenderer( UI_ADDITIONAL_EDITOR_RENDERER, rendererText );

22.7.2.5 Action for Changes in the Dependent On Column

When the user changes the dependent column, generally there is initialization to do in the column that
uses the custom editor/renderer. In the case of Limit, the custom column is initialized to the appropriate
default value when the dependent column changes.

22-141
LimitBuilder method genericETableEditOccurred handles listening for the change in the depended on
column. The specific statement is the following:

if ( evt.getType() == GenericETableEvent.CELL_EDIT_HAS_OCCURRED &&

evt.getColumnChangedIndex() == getUsagePeriodColumnIndex() )
{
usagePeriodChanged( evt, limitsTable );
}

Method usagePeriodChanged determines the value of the dependent column, then sets the value of the
custom editor column using the table model’s setValueAt method.

22-142
23 Utility Classes

23.1 Overview of the Utility Classes

The following table identifies utility classes that exist in package es.desktop. Refer to the javadoc for
more information.

Class Name Description

RecordResponseTime Useful for computing the amount of elapsed time between two
points. The class provides the ability to capture and display the
data.
RecordActivityTrace Records two types of user activity.
1. UI opens and closes.
2. Message types exchanged with the server.
ESUtilities Provides a common method for writing the stack trace.

Provides a debug mechanism that is more focused that the UIF

debug mechnism. This is described in detail in the next section.

23.2 Using the Debug Mechanism

23.2.1 Overview

Class ESUtilities provides a focused debug utility by providing a mechanism for activating debug points.
Once the debug point is activated, future executions result in a debug message being written to System.out
(consequently desktop.log). The net is, debug points can dynamically be turned on and off as needed.

23.2.2 Add the Debug Logic

What follows is an example of specifying the debug data (variable aDebugString), then making the call to
ESUtilities method writeDebug. The writeDebug method takes 2 String arguments. The first one is the
debug ID, and the second one is the debug data. The System.out will be written if the debug ID has been
previously activated (see the next section).

String aDebugString = i + CM_COLON_SEPARATOR

+ selectedRows.length + CM_COLON_SEPARATOR + startRow
+ CM_COLON_SEPARATOR + model.getRowCount()
+ CM_COLON_SEPARATOR + model.getColumnCount()
+ CM_COLON_SEPARATOR + rowstring + CM_COLON_SEPARATOR
+ st1.countTokens() + CM_COLON_SEPARATOR

23-143
 + st2.countTokens() + CM_COLON_SEPARATOR;
ESUtilities.getInstance().writeDebug( “GETMG_PST_RW_LP1”,
aDebugString);

23.2.3 Activate the Debug Point

The call to ESUtilities to activate the debug ID discussed in the previous section is:

ESUtilities.getInstance().setDebugOn( “GETMG_PST_RW_LP1” );

The call to deactivate the debug ID is:

ESUtilities.getInstance().setDebugOn( “GETMG_PST_RW_LP1” );

Once a debug ID is activated, it remains active until it gets deactivated, or until the ACI Desktop is
brought down (i.e., it doesn’t stay active across an ACI Desktop cycle).

There are several approaches to activating a debug ID.

1. The best approach is write a simple UI that allows a developer to activate/deactivate a debug ID
dynamically. This simple UI could have two fields labeled as follows:

Option
Debug ID

Where Option would be a combo box with two items of Active Debug ID and Deactive Debug ID,
and Debug ID would be a text field that allows entry of a Debug ID.

2. A second approach is to add logic that activates the debug ID based on some condition.

3. A third way is to update file ESUtilitiesDebug.cfg. This option requires setting the system variable
ESUtilitiesDebug to true. The required entry in ESUtilitiesDebug.cfg to activate the debug ID
discussed in the previous section is the following:

ESUtilitiesDebug.GETMG_PST_RW_LP1=true

The simples way to set the system variable to true is to specify it in DesktopLauncher.lax:

lax.nl.java.option.additional= -DESUtilitiesDebug=true

The downside to this approach is, the debug ID is always active (i.e., this approach doesn’t allow
you to dynamically activate/deactivate the debug ID).

23-144
23.2.4 Example of the Output

A sample of the output for the debug ID of GETMG_PST_RW_LP1 is as follows:

1:GETMG_PST_RW_LP1:0:1:5:6:5:1113 430.0 USD 2 2:0:4:

The leftmost number is a counter that increments everytime a debug message is written. The
second variable is the debug ID. The rest of the data is the data specified above as aDebugString.

23-145
24 Version Independent Interface Considerations

24.1 Overview of Version Independent Changes

All of the UI applications that are related to the Interchange Interface Configuration UI’s, including the
supporting Interface UI Framework has been relocated to a new directory structure under the ui and
UIServer Synergy/CM projects. A new Release value must be used to modify code in this Version
Independent Interface directory. The directory, …\ui\if\* will be the only location where mandates,
product fixes, new interfaces and new features related to Interfaces are developed. This includes typical
mandate code changes, plus changes to the bit map settings property file (e.g.,
ISOFrameworkCodeValues+BNET, changes to the Instrument Status Mapping property file (e.g.,
InstrumentStatusMappingDefaultMappingValues+VISA), and the action code mapping property file (e.g.,
ActionCodeDefaultMappingValues+BNET).

The …\ui\if\* directory and all subdirectories are version independent, meaning they will not be driven by
version numbering and it would not be subjected to the BASE24-eps software versioning cycle.

When an interface is distributed to a previous version of BASE24-eps, any changes to the interface
framework will be included. In addition, any updates to Processing Codes, Journal TDE’s, Currency
Codes, Country Codes, Transaction Codes, ISO Message Types, Account Types, etc., along with the
associated help map ID’s will be included. The properties that are most often modified during mandate
development are now packaged in a CommonCodeValues property file extension, named
CommonCodeValues+INTF.properties to allow us to roll this property file back into prior BASE24-eps
Versions with limited impacts.

Occasionally, a new feature may require changes to other components. The impacts to previous versions
of BASE24-eps must be assessed and product management must approve the changes to previous
versions. These changes will be made in the same way a Critical/Mandatory fix is retrofitted into a prior
BASE24-eps Version.

24.2 Common UI Property File Changes

24.2.1 CommonCodeValues.properties changes

The properties that are most often modified during Interface Mandate development have been isolated into
a CommonCodeValues property file extension, named CommonCodeValues+INTF.properties. This will
allow us to have a version independent property file that can be used in prior BASE24-eps Versions with
little impact. The properties that are included in this extension property file are shown below.
 Processing Codes
 Country Codes
 Currency Codes
 Transaction Codes
 ISO Message Types
 Journal TDE Object ID’s

24-146
  ISO Response Message Types
 Account Types (includes the following)
o AcctType
o FromAcctTyp
o ToAcctTyp
 Instrument Type/Interchange Relationship Properties
o Association
o AuthMessageType
o AssociationCardType

24.2.2 UISecurityIDs.properties changes

The properties included in the UISecurityIDs property file that are related to the Interface Configuration
UI’s that are now Version Independent have been moved into a UISecurityIDs property file extension,
named UISecurityIDs+INTF.properties. This will allow us to have a version independent property file
that can be used in prior BASE24-eps Versions with little impact.

As of the BASE24-eps Version 06.2, the properties below have been moved from the main UISecurityIDs
property file and included in the UISecurityIDs+INTF property file extension.
 security.ui.taskID.APMS_INTERFACE_CONFIGURATION.text=APMSInterfaceConfiguration
 security.ui.taskID.ATMDH_INTERFACE_CONFIGURATION.text=ATMDHInterfaceConfiguration
 security.ui.taskID.BANKNET_INTERFACE.text=BanknetInterface
 security.ui.taskID.BANKNET_MERCHANT_PROGRAM.text=BanknetMerchantProgram
 security.ui.taskID.B24HISO_INTERFACE_CONFIG.text=B24HISOInterfaceConfig
 security.ui.taskID.B24HISO93_INTERFACE_CONFIG.text=B24HISO93InterfaceConfig
 security.ui.taskID.CONTINGENCY_INTERFACE.text=ContingencyInterface
 security.ui.taskID.EPSNET_INSTITUTION.text=EPSNetInstitution
 security.ui.taskID.EPSNET_INTERFACE_CONFIGURATION.text=EPSNetInterfaceConfiguration
 security.ui.taskID.IFX_HOST_INTERFACE.text=IFXHostInterface
 security.ui.taskID.IFX_HOST_ACTION_CODE.text=IFXHostActionCode
 security.ui.taskID.IMT_INTERFACE.text=IMTInterface
 security.ui.taskID.INSTRUMENT_STATUS_MAPPING_PROFILE.text=InstrStatusMappingProfile
 security.ui.taskID.INSTRUMENT_TYPE_INTERCHANGE_RELATION.text=InstrumentTypeIchgRelation
 security.ui.taskID.INTERFACE_TERMINAL.text=InterfaceTerm
 security.ui.taskID.INTERPAY_INTERFACE.text=InterpayInterface
 security.ui.taskID.LIS5_INTERFACE.text=LIS5Interface
 security.ui.taskID.MAESTRO_DEBIT_SWITCH.text=MaestroDebitSwitch
 security.ui.taskID.REALTIMEFEEDINTERFACE.text=RealTimeFeedInterface
 security.ui.taskID.STAR_INSTITUTION.text=StarInstitution
 security.ui.taskID.STAR_INTERFACE_CONFIGURATION.text=StarInterface
 security.ui.taskID.STAR_NETWORK_ID_RELATIONSHIP.text=StarNetworkIdRelationship
 security.ui.taskID.TERM_LN_FIID_MAP.text=TermLnFiidMap
 security.ui.taskID.VISA_ACQUIRERS.text=VisaAcquirers
 security.ui.taskID.VISA_DPS_ACQUIRERS.text=VisaDPSAcquirers
 security.ui.taskID.VISADPS_INTERFACE.text=VisaDPSInterface
 security.ui.taskID.VISANET_INTERFACE_CONFIGURATION.text=VisanetInterfaceConfig

As of the BASE24-eps Version 06.2, the following Interface Configuration properties are no longer used,
so these have been removed from the UISecurityIDs property file.
 security.ui.taskID.AIB_INTERFACE.text=AIBInterface
 security.ui.taskID.ISO_93_INTERFACE_CONFIGURATION.text=ISO93InterfaceConfiguration
 security.ui.taskID.VISASMS_INTERFACE.text=VisaSMSInterface
 security.ui.taskID.IMT_ATM_TRANS_MAP.text=IMTATMTransactionMapping
 security.ui.taskID.IMT_POS_TRANS_MAP.text=IMTPOSTransactionMapping

24-147
24.3 UI Application Jars

The actual location for the BASE24-eps UI application jars associated with the Version Independent
Interface applications that are being moved to the …\ui\if\… directory will not be changed, as all
BASE24-eps UI application jars will continue to be located in the Repository, under the
…ui\Repository\ES\Desktop\Applications\ directory.

24.3.1 Change to existing UI Application Jars

As of the BASE24-eps Version 06.2, the common property files used in the BASE24-eps UI are
distributed in a new UI application jar, named espropertyDT.jar. In the prior BASE24-eps Versions, the
common property files were included in the esDT.jar.

The new espropertyDT.jar has its own history.txt and manifestDT.txt objects located under the …\ui\
folder along with the common property files shown below.
CommonCodeValues.properties
CommonMessages.properties
CommonUI.properties

The Common property files are no longer packaged within the esDT.jar, and the images used for the
BASE24-eps UI’s are no longer packaged in the esDT.jar. In addition, changes to the installation have
been made whereby the esDT.jar is now found in the Repository under the …\ES\Desktop\Applications\
folder and is no longer required in the CLASSPATH.

24.3.2 New UI Application Jars

During this project, new packaging was done to limit changes that impacted the esDT.jar due to property
file changes and to allow for Version Independent code.

A new BASE24-eps application jar, named espropertyDT.jar, is available with the BASE24-eps 06.2
Version and beyond and contains only the common property files listed below and the images used by the
BASE24-eps UI. This new jar is associated with the history.txt and manifestDT.txt objects that are
located directly under the ui\ folder. This new jar is distributed for all BASE24-eps and TSS installations.
CommonCodeValues.properties
CommonMessages.properties
CommonUI.properties

A new BASE24-eps application jar, named ifDT.jar, is available with the BASE24-eps 06.2 Version and
beyond and contains the Version Independent property files as listed here. This new jar is associated with
the history.txt and manifestDT.txt objects that are located directly under the ui\if\ folder and these files
need to be updated anytime a change is made to one of the property files listed below.
CommonCodeValues+INTF.properties
UISecurityIDs+INTF.properties

24-148
There are no impacts to the installation program due to the creation of the new espropertyDT.jar or
ifDT.jar. These jars are placed in the Repository under the …\ES\Desktop\Applications\ folder.

24.3.3 UI Application Packages Deleted (No Longer Product)

The ISO93 Interface Configuration UI (under Configure – Interface – Network) has been removed, as this
was developed for the IBM Benchmark/Performance testing and is no longer needed. The iso93 package
has been removed from under es\desktop\interfaceconfig\ folder.

24.4 Version Independent …\if\es\desktop\ packages

24.4.1 UI Client Desktop Packages moved to \if\es\desktop\ Directory

The following es.desktop packages have been moved from ui\es\desktop\ to the ui\if\es\desktop\
directory location. This has not impacted the package name inside the actual java classes or the location
where the UI application is stored. This list does not include the new UI applications that were developed
for the BASE24-eps 06.2 Version, only those packages that already existed in 05.4.

 …\es\desktop\epsnetinstitution
 …\es\desktop\ifxhostactioncode
 …\es\desktop\instrumentstatusmapping
 …\es\desktop\instrumenttyperelation

 …\es\desktop\interfaceconfig
 …\es\desktop\interfaceconfig\apms
 …\es\desktop\interfaceconfig\atmiso
 …\es\desktop\interfaceconfig\b24hiso
 …\es\desktop\interfaceconfig\b24hiso93
 …\es\desktop\interfaceconfig\banknet
 …\es\desktop\interfaceconfig\contingency
 …\es\desktop\interfaceconfig\epsnet
 …\es\desktop\interfaceconfig\ifxhost
 …\es\desktop\interfaceconfig\imt
 …\es\desktop\interfaceconfig\interpay
 …\es\desktop\interfaceconfig\lis5
 …\es\desktop\interfaceconfig\mds
 …\es\desktop\interfaceconfig\realtimefeed
 …\es\desktop\interfaceconfig\star
 …\es\desktop\interfaceconfig\visadps
 …\es\desktop\interfaceconfig\visanet

 …\es\desktop\interfaceterminal
 …\es\desktop\starinstitution
 …\es\desktop\starnetwkidrelation
 …\es\desktop\visadpsinstitution
 …\es\desktop\visainstitution

24-149
24.5 User Security Permission Load Script Considerations

The only time this property file should be impacted is when a new Interface Configuration UI is developed
and needs to be retrofitted back to prior BASE24-eps Versions.

This property file is defined during the development of a BASE24-eps Version and then converted to a
DALCI script to load User Security Permissions for the BASE24-eps UI’s. The DALCI script is then
distributed to customers.

In the case of a new Interface Configuration UI being required for all BASE24-eps Versions in a specific
BASE24-eps Release, we would have to update the DALCI update script for the User Security
Permissions in each of the BASE24-eps Versions of that Release.

Another option would be to have multiple DALCI load and update scripts for the installation of BASE24-
eps. One would be for the Interfaces, and the other would be for the rest of the BASE24-eps UI’s. I’m
not sure that this would simplify things, as the more DALCI scripts a customer has to load, the more
confusing it becomes.

For the BASE24-eps 06.2 Version we have modified the appropriate ES_ESF.properties and it’s
associated DALCI load scripts for each BASE24-eps Version required if a new Version Independent UI is
required as part of a mandate. This type of change will follow the standard fix procedures for prior
versions.

24.6 Synergy/CM ui/UIServer Version Independent Check-In Release Value

There is a specific Release value defined by SWM, vi/1.0, that will be required for any Task’s associated
with the objects included under the if directory for both the ui and UIServer projects.

What this means for you is that if you are making a change to any objects that exists under the …\ui\if\
directory or under the UIServer\if\ directory, you must use a task with a vi/1.0 release value. So, if you
have a unit of work that requires changes to some files in directories noted here and some changes to other
areas of the your respective project (ui or UIServer), you must use two different tasks. One should only
contain the version independent changes and have a vi/1.0 release value and the other should have all
other changes with the appropriate BASE24-eps version release value (i.e.ui/06.2, or UIServer/06.2).

Additionally any change made with a vi/1.0 release value will always be automatically uplifted to all
future BASE24-eps versions via Synergy/CM update properties. This is the way to ensure that all
versions of BASE24-eps contain the same versions of the version independent objects. So, there will
never be a need to uplift a vi/1.0 task, as this is done automatically through the update properties of
Synergy/CM.

Please note that when using the vi/1.0 release value on tasks, your projects should still have a BASE24-
eps version release value (i.e. ui/06.2, UIServer/06.2). This will result in a warning when you set your
vi/1.0 task to have the vi/1.0 release value. This is a known warning and there is not a way to eliminate it.

24-150
Details of the warning can be found in the Product Engineering Database entry named Synergy/CM
Warning - Release of current task and project do not match:

24-151
25 Support for Multi-byte

25.1 Introduction

This section provides documentation and considerations for adding support for entering, storing and
displaying of multi-byte character support sets in the Base24-eps UIs.

In Base24-eps version 09.2 a set of User Interfaces were enhanced so that selected fields on each of the
respective UIs support multi-byte representation of the international character sets. The following is a list
of UIs that can be referenced for an example of the multi-byte implementation.

Institution UI
Card UI
Action Code Mapping UI
ATM Channel UI
Merchant UI
Merchant Delivery Channel UI
ATM Consumer Media UI
ATM Receipt UI

For most of the multi-byte support, the multi-byte data is stored in separate binary fields in the datasources
in fields that are double the size of the single-byte fields. The data is stored in a UTF-8 encoding format
to handle all the multi-byte character sets. The xml message exchange and the database storage of the
multi-byte data require the appropriate encoding, “UTF-8” to be configured. Refer to the following
sections for support on configuring the encoding.

Support was added to the common desktop classes and java server classes to automate the handling of the
multi-byte data in the message exchange and database storage to minimize development impacts in the
individual UIs.

The Multi-byte Support was added as a separate licensed product, so the display and handling of the
multi-byte components are controlled by the presence of a Multi-byte Module ID. Support was added to
the common desktop classes to facilitate controlling the display of the multi-byte fields. Refer to the
following sections for this support.

25.2 Checking For Multi-byte Support

Support has been added to the es.desktop.ESDesktopApplication class to check for the Multi-byte
Module ID and set a flag, isMultiByteInUse() to true if the Multi-byte Module ID is present in the
desktop. The UI applications can check this flag in order to perform multi-byte dependent logic.

25-152
25.3 Configuring the Multi-byte Message Encoding

A new UI, Locale Content UI, was developed to configure the required encoding property in both the
APPLCNFG for the Client/Java Server purposes and in the ENVIRONMENT table for the C++ online
code purposes. The encoding property defines the encoding to be used for the message transfers and
database storage for the multi-byte input fields on the UIs. The encoding property,
“MULTIBYTE_ENCODING” is defaulted to “None” in these datasources and must be assigned to
“UTF-8” through the Locale Content UI before multi-byte data is stored. The
“MULTIBYTE_ENCODING” property is suppressed from the Application Configuration UI and
Environment UI to prevent the property from getting out of sync.

Additionally, a java System Property “multibyte.encoding” is assigned in the Client from the
MULTIBYTE_ENCODING APPLCNFG value configured in the Locale Content UI. This
“multibyte.encoding” System Property is used to encode the multi-byte messages in the Base24-eps UI
client and in the UIF for messages containing multi-byte fields. This “multibyte.encoding” System
Property was needed in order for the UIF User Security UI multi-byte input support to have access to the
encoding to be used.

APPLCNFG and Environment Property Value

MULTIBYTE_ENCODING UTF-8

Java System Property Value

multibyte.encoding UTF-8

25.4 Multi-byte Message Support – Client

A new section, [LocaleEncodedMessages] in the UI’s ESData .cfg file is used to identify which
messages contain locale multi-byte data that should be encoded. The following example is from the
Institution Configuration UI.

Example:

[LocaleEncodedMessages]
InstConfigInsertRq
InstConfigUpdateRq
InstConfigViewRs

The common es.shared.ESData class has support to identify the list of messages that are contained in the
LocaleEncodedMessages section from theUI’s ESData .cfg file. The ESNCService class checks if the
message is flagged in the ESData object as a LocaleEncodedMessage and handles encoding the message
based on the System Property “multibyte.encoding”. Refer to method doXMLRequest in the
ESNCService class. For the LocaleEncodedMessages, the message request/response will be performed
with the getBytes() using the “multibyte.encoding” System Property.

25-153
New serviceRequest overload methods were added to the UIF ServiceChannel class for this support. With
the UIF changes, the serviceRequest call for the multi-byte messages were modified to pass in the byte
encoded array and a new argument containing the encoding from the “multibyte.encoding” System
Property.

25.5 Multi-byte Message Support – Java Server

Support for a new column attribute, <multibyte>true</multibyte> was added to the <Data Source>Gen.xml
configuration, example shown below.

When this attribute is used, the generated component code will include specific processing required for the multi-
byte columns in the genDBObject and genRespObject methods, so the individual UIServer’s do not need to
implement UI specific logic for the multi-byte data.

<column>
<colnumber>63</colnumber>
<logicalname>instdContactCommentsMByte2</logicalname>
<physicalname>contact2_comments_mbyte</physicalname>
<javatype>byte[]</javatype>
<sqldefault></sqldefault>
<multibyte>true</multibyte>
<constraint>ES.Std.String.Size.0To100</constraint>
</column>

25.6 Controlling the Display of Multi-byte Components

Multi-byte is a separate licensable product and a separate Module ID is assigned for Multi-byte.

For non multi-byte environments (where the Module ID is not present), the UI multi-byte fields are not
displayed. The following sections document the support that is in place to facilitate controlling the
display of the multi-byte fields in the Base24-eps UIs.

25.6.1 Controlling the display of Multi-byte Tables

For UIs that contain tables with multi-byte data that should only be displayed in a multi-byte environment,
a new CUBS layout configuration entry is available, TableDefinitionFileNameMByte, that can be used
to assign an alternate table configuration file that will be loaded instead when in a multi-byte environment.

The ESComponentBuilder method, createSwingJComponent, has logic to check the new

isMultiByteInUse() flag in the es.deskop.ESDesktopApplication class. If true, it will check for the
existence of a TableDefinitionFileNameMByte entry for the GenericETableMgr entries in the layout file
as shown in bold in the example below and use this configuration instead of the TableDefinitionFileName
entry. This entry is optional and if not found, the TableDefinitionFileName entry will be used.

25-154
 [ActionCodeExternalMappingTable]
ClassName = es.desktop.GenericETableMgr
anchor = West
TableDefinitionFileName = ActionCodeExternalMappingTable.properties
TableDefinitionFileNameMByte =
ActionCodeExternalMappingTableMByte.properties
weighty = 10
TabTitle = panelInboundMapping

25.6.2 Controlling the display of Multi-byte Panels

Support for a new panel layout configuration property to control the display of the multi-byte panels was
added, “Multibyte = Yes”, example shown below.

[AddrPanelMByte]
ConfigFile = LayoutAddrPanelMByte.cfg
Multibyte = Yes

In the ESComponentBuilder class, logic is performed to check for the Multibyte = Yes
Layout property and if present and the isMultiByteInUse() flag in the es.deskop.ESDesktopApplication is
false, then the setVisible(false) will be called on the panel.

25.6.3 Controlling the display of Multi-byte Fields

Support for a new field layout configuration property to control the display of the multi-byte fields and
labels was added, “Multibyte = Yes”, example shown below in bold.

[lblCustIDMByte]
gridy = 1
Multibyte = Yes

[txtCustIDMByte]
ESDataKey=crddCustID
weightx = 1
gridy = 1
Multibyte = Yes

In the ESBuilderCustomPanel class, logic is performed to check for the Multibyte = Yes Layout
property and if present and the isMultiByteInUse() flag in the es.deskop.ESDesktopApplication is false,
then the setVisible(false) will be called on the field or label component.

25-155
25.7 Multi-byte Constant Values

The following new common constants were added for use in the Multi-byte implementation in the client.

es.desktop.CommonConstants Property/Description

CM_MULTIBYTE_MODULE_ID The value for the Multi-byte Module ID

CM_MULTIBYTE_APPCFG_KEY The MULTIBYTE_ENCODING system property
configured through the Locale Content UI and stored in
the APPLCNFG and ENVIRONMENT datasources for
use in encoding the multi-byte data.

es.desktop.ESBuilderConstants Property/Description

TABLE_DEFINITION_FILE_NAME_MBYTE "TableDefinitionFileNameMByte"
MULTIBYTE_INDICATOR "Multibyte";

es.shared. ESConstants Property/Description

SYSTEM_PROP_MULTIBYTE_ENCODING multibyte.encoding
SYSTEM_PROP_MULTIBYTE_DEFAULT None

25.8 Bidirectional Multi-Byte Component Support

The common Bidirectional component classes listed below have been created to support dynamically
setting the component orientation in the multi-byte text components and in the table multi-byte text cells.
They utilize the java.text.Bidi class to inspect the text as it is entered in order to determine the orientation
and then call setComponentOrientation on the component to set the right-to-left (RTL) or left-to-right
(LTR) orientation based on the text entered.

Class Description
es.desktop.BidiTextField Used for bidirectional support in non-table multi-byte
ETextField components. Also includes text zoomer
bidirectional support
es.desktop.BidiTextArea Used for bidirectional support in non-table multi-byte
ETextArea components.
es.desktop.BidiTextZoomer Can be used with the BidiTextArea to provide

25-156
 Class Description
bidirectional text zoomer support

es.desktop.GenericETextFieldBidiEditor Used for automating bidirectional support in a table cell

without text zoomer support. Can be assigned simply
in the UI’s table property file column entry using the
eTextFieldBidi constant.

es.desktop.BidiDataCellEditor.java Used for bidirectional support in a table cell editor that

requires text zooming bidirectional support.

es.desktop.BidiDataCellRenderer.java Used for bidirectional support in a table cell renderer

that requires text zooming bidirectional support.

Non-Table Component Support

For non-table components that require bidirectional ETextField support, the BidiTextField component can
be assigned in the layout configuration file, example shown below.

[PanelComponents]
labelChanDescrMByte = framework.desktop.ecomponents.ELabel
fieldChanDescrMByte = es.desktop.BidiTextField
labelAddr1MByte = framework.desktop.ecomponents.ELabel
fieldAddr1MByte = es.desktop.BidiTextField

For non-table components that require bidirectional ETextArea support, the BidiTextArea component can
be assigned in the layout configuration file, example shown below.

[PanelComponents]
labelNotesMbyte = framework.desktop.ecomponents.ELabel
fieldNotesMByte = es.desktop.BidiTextArea

If the BidiTextArea requires TextZoomer support, then the UI’s Builder class would need to instantiate
and assign a BidiTextZoomer to the BidiTextArea component. Refer to the merchant and
merchantchannel packages for an example of the BidiTextZoomer support.

Table Component Support

For the multi-byte table columns requiring bidirectional support but without the text zooming, UIs can
assign the new table constant, eTextFieldBidi, to automate the table cell renderer/editor support. The

25-157
example below shown in bold is for the Contact Name Multi-byte table column in the Institution
Configuration UI. No additional coding is required in the UI.

[Column1]
Column1.columnKey=instdContactNameMByte
Column1.columnHeaderLocaleKey=InstitutionCnfg.contactNameHdgNewMByte
Column1.columnHeaderPropertyFile=InstitutionCnfg
Column1.columnEditor=eTextFieldBidi
Column1.columnRenderer=eTextFieldBidi
Column1.columnEditorLocaleKey=InstitutionCnfg.contactNameHdgNewMByte
Column1.columnAccess=rw
Column1.columnWidth=120
Column1.columnSort=false
Column1.columnKeyFieldAccess=rwColumn1.columnOptionalInput=r

If text zooming is required, UIs will need to assign a custom editor/renderer constant in the table property
file as shown in bold in the example below. The UI builder class will need to include logic to construct
the es.desktop.BidiDataCellEditor and es.desktop.BidiDataCellRenderer classes and assign them to
the GenericCellEditorMgr and GenericCellRendererMgr for the specific table column. The UI’s must
handle constructing these classes themselves so that they can invoke the close method on these classes
when the UI closes in order to remove the listeners used in the text zoomer support. Refer to the
ActionCodeBuilder initUISpecificComponents method for an example of utilizing these classes. For
more detail information on using custom cell editors/renderers, refer to Section 11.10 in this document.

[Column3]
Column3.columnKey=aceidActCdeExtrnDescrMByte
Column3.columnHeaderLocaleKey=ActionCode.externalActionCodeDescriptionHeaderMByte
Column3.columnEditor=BidiDataCellRenderer
Column3.columnEditorLocaleKey=ActionCode.externalActionCodeDescriptionHeaderMByte
Column3.columnAccess=rw
Column3.columnKeyFieldAccess=rw
Column3.columnOptionalInput=o
Column3.columnWidth=250

In the UI builder class initUISpecificComponents method, instantiate and assign the

es.desktop.BidiDataCellEditor and es.desktop.BidiDataCellRenderer for the custom
BidiDataCellRenderer editor/renderer for the Multibyte table columns.

Add a uiIsClosing() method to the Builder class to call the close() method on the BidiDataCellEditor
and BidiDataCellRenderer and set their references to null. Call the Builder’s uiIsClosing() method
from the UI class’ close() method.

25.9 Font Support for Multi-byte Components

25-158
Support was added to the UIF to be able to specify the Font for the multi-byte components in the
Desktop.properties resource bundle.

A new method was added to the framework.toolbox.Utilities class, getMultibyteFont() that will retrieve
the font name from the Desktop.properties file. A new method was added to the UIF Utility class,
getMultibyteFontSize() that will retrieve the font size from the Desktop.properties file.

Default font and font size entry in Desktop.properties file:

Desktop.multibyte.font=Arial Unicode MS
Desktop.multibyte.fontSize=12

The entry can be overridden with a locale specific entry, example for Arabic (ar) locale:
Desktop.multibyte.ar.font= Lucida Sans

The logic that reads the property will first look for a locale specific property, then failing that, will read
the default property. For example, if the User Preference language is set to Arabic, an attempt will be
made to read property Desktop.multibyte.ar.font first, then failing that, the property
Desktop.multibyte.font will be read.

The ability to set the Font in the Desktop.properties file provides additional flexibility if required for
configuring the display of the multi-byte data without requiring changes to the Java font.properties files.

Multi-byte Font Support Non-Table Components

For non-table components, support was added to the common es.desktop.ESComponentBuilder class to
automatically set the Multi-byte font for the multi-byte components that contain the (Multibyte = Yes)
indicator in the UI’s layout .cfg files.

Multi-byte Font Support For Table Components

For the table components that use the automated eTextFieldBidi bidirectional columnEditor assignment
(Column2.columnEditor=eTextFieldBidi) in the table configuration, support was added to the common
es.desktop table cell manager classes listed below to automatically set the Multi-byte Font in these table
cells.

GenericCellRendererMgr
GenericCellEditorMgr

For the table components that use the custom bidirectional table cell editor/renderers classes listed below,
support was added to automatically set the Multi-byte Font within these classes.

BidiDataCellEditor.java
BidiDataCellRenderer.java

For UIs that require setting the Multibyte Font in the individual UI classes, the UI can access the Font and
Font size properties through the UIF’s Utilities class as shown below and construct the Font object to

25-159
assign to the specific components. Reference ATMDHReceiptFormatComponentBuilder
initUISpecificComponents method for an example.

if (getUIRef().getESDesktopApplication().isMultiByteInUse()) {
int fontSize = Integer.parseInt(Utilities.getMultibyteFontSize());
fn = new java.awt.Font(Utilities.getMultibyteFont(),
Font.PLAIN,
fontSize);
}

Note: The complete list of font names for a given environment can be obtained from the Java
GraphicsEnvironment class:

String[] fontNames = GraphicsEnvironment

.getLocalGraphicsEnvironment().getAvailableFontFamilyNames();

25.10 Multi-byte Length Validation

The ESData ESString,Max Length constraint, example “=es.shared.ESString,Max Length:3” is not

possible to use for multi-byte fields as the length in UTF-8 encoded bytes will vary based on the character
set, example shown below.

Example of Multi-byte Length With Encoded Bytes:

For the following 3 Chinese characters, the UTF-8 value is e5a3b9e5b18be9a082:

壹屋頂

When the ESData Max Length validation is used, it uses the string.length() method which gives
the number of chars in the string which is 3 for the example shown. When actually when you
perform string.getBytes("UTF-8"). Length, it is 9 bytes in length which is the correct length
calculation.

The UIServer validation is used where possible for the multi-byte length validation as it reports the proper
length validation as shown in the example below.

UIServer Length Validation Response Example:

The UIServer reports the Overflow field validation error with the description in the log:
<ErrDescr>The length of the value is 9, but the required maximum is 6.</ErrDescr>

This is due to the UTF-8 encoded value for the 3 Chinese characters displayed is
e5a881e5b0bce696af, which is 9 bytes in length and the storage maximum in the datasource is 6
bytes.

25-160
 <ChannelMessage><ChannelHeader><Type>Response</Type><Host>NSKi092Service</Host><
Service>ESNCService</Service><ServiceAction>InstConfigUpdateRq</ServiceAction><Messag
eID>238362221244656923965</MessageID><ResultCode>-
1</ResultCode><Result>null</Result></ChannelHeader><ServiceDataType>text/xml</ServiceD
ataType><ServiceData><InstConfigUpdateRs
RespStat="Field_Validate_Error"><Error><ErrCode>Overflow</ErrCode><FieldID>instdStateM
byte</FieldID><ErrDescr>The length of the value is 9, but the required maximum is
6.</ErrDescr><ErrIndex>1</ErrIndex></Error></InstConfigUpdateRs></ServiceData></Channel
Message>

There is support for a new es.shared.AbstractDataType extension class, es.shared.ESMultibyte, that

was added that can be used if validation is required in the client to validate the maximum length based on
the length of the encoded bytes. To use this validation, specify es.shared.ESMultibyte class in the
ESData configuration instead of the es.shared.ESString class together with the Max Length, example
shown below. The Common.Overflow.message will be reported if the length in the encoded bytes
exceeds the Max Length specified.

instdAddressLine1MByte =es.shared.ESMultibyte,Max Length:50

25.11 Multi-byte Utilities Support

A new class was added, es.desktop.ESI18nUtil, to the es.desktop package to provide utility support for
internationalization. The class provides an interface into the java internationalization api classes and
provides convenience methods for common tasks.

The method, ESI18nUtil .containsMultibyteText, is utilized in the UI packages that require validating if
multi-byte characters have been entered. The containsMultibyteText is a convenience method that will
return true if the specified string argument contains multi-byte characters. Refer to its usage in the
atmdhconsumermedia, atmdhreceiptformat, and scripting UI packages.

The ESI18nUtil.getHexString method is used to convert a byte array to hex string values. Refer to its
usage in the atmdhreceiptformat package.

Refer to the ESI18nUtil javadocs for information on additional convenience methods available.

The framework.toolbox.Utilities class also contains some new convenience methods that can be used for
UIs that require additional multi-byte support.

The Utilities.getMultibyteEncoding() method will return the value of the System "multibyte.encoding"
property, i.e. UTF-8, that has been configured.

25-161
The Utilities.hexString2Byte(String hexStr) method converts a String containing hex characters into a
byte[] where each 2 hex characters are packed into one element of the byte[]. The
Utilities.byteArrayToString(byte[] input, String charEnc) method converts the input sequence of bytes
into a String based on the supplied character encoding. Refer to the usage of these methods in the
atmdhreceiptformat package for an example.

25-162