Xstore Pos-170-03-Ftg

Oracle® Retail Xstore Point of Service
Frameworks & Technologies Guide

Release 17.0
E92431-03
October 2019
Oracle® Retail Xstore Point of Service, Frameworks & Technologies Guide, Release 17.0
E92431-03
Copyright © 2019, Oracle and/or its affiliates. All rights reserved.
Primary Author: A. Meske
This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as
expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or
display any part, in any form, or by any means. Reverse engineering, disassembly, or
decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be
error-free. If you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing
it on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated
software, any programs installed on the hardware, and/or documentation, delivered to U.S.
Government end users are “commercial computer software” pursuant to the applicable Federal
Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication,
disclosure, modification, and adaptation of the programs, including any operating system,
integrated software, any programs installed on the hardware, and/or documentation, shall be
subject to license terms and license restrictions applicable to the programs. No other rights are
granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications,
including applications that may create a risk of personal injury. If you use this software or
hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe,
backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its
affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC
International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open
Group.
This software or hardware and documentation may provide access to or information about
content, products, and services from third parties. Oracle Corporation and its affiliates are not
responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services unless otherwise set forth in an applicable agreement between you
and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or
damages incurred due to your access to or use of third-party content, products, or services, except
as set forth in an applicable agreement between you and Oracle.
Value-Added Reseller (VAR) Language
Oracle Retail VAR Applications
The following restrictions and provisions only apply to the programs referred to in this section
and licensed to you. You acknowledge that the programs may contain third party software (VAR
applications) licensed to Oracle. Depending upon your product and its version number, the VAR
applications may include:
(i) the MicroStrategy Components developed and licensed by MicroStrategy Services Corporation
(MicroStrategy) of McLean, Virginia to Oracle and imbedded in the MicroStrategy for Oracle
Retail Data Warehouse and MicroStrategy for Oracle Retail Planning & Optimization applications.
(ii) the Wavelink component developed and licensed by Wavelink Corporation (Wavelink) of
Kirkland, Washington, to Oracle and imbedded in Oracle Retail Mobile Store Inventory
Management.
(iii) the software component known as Access Via™ licensed by Access Via of Seattle, Washington,
and imbedded in Oracle Retail Signs and Oracle Retail Labels and Tags.
(iv) the software component known as Adobe Flex™ licensed by Adobe Systems Incorporated of
San Jose, California, and imbedded in Oracle Retail Promotion Planning & Optimization
application.
You acknowledge and confirm that Oracle grants you use of only the object code of the VAR
Applications. Oracle will not deliver source code to the VAR Applications to you.
Notwithstanding any other term or condition of the agreement and this ordering document, you
shall not cause or permit alteration of any VAR Applications. For purposes of this section,
"alteration" refers to all alterations, translations, upgrades, enhancements, customizations or
modifications of all or any portion of the VAR Applications including all reconfigurations,
reassembly or reverse assembly, re-engineering or reverse engineering and recompilations or
reverse compilations of the VAR Applications or any derivatives of the VAR Applications. You
acknowledge that it shall be a breach of the agreement to utilize the relationship, and/or
confidential information of the VAR Applications for purposes of competitive discovery.
The VAR Applications contain trade secrets of Oracle and Oracle's licensors and Customer shall
not attempt, cause, or permit the alteration, decompilation, reverse engineering, disassembly or
other reduction of the VAR Applications to a human perceivable form. Oracle reserves the right to
replace, with functional equivalent software, any of the VAR Applications in future releases of the
applicable program.
Contents
1 Send Us Your Comments..............................................................1-12
1 Preface............................................................................................1-13
Audience...................................................................................................................... 1-13
Documentation Accessibility .................................................................................. 1-13
Access to Oracle Support.................................................................................... 1-13
Related Documents .................................................................................................. 1-13
Customer Support...................................................................................................... 1-14
Review Patch Documentation ................................................................................. 1-14
Oracle Retail Documentation on the Oracle Technology Network................ 1-14
Conventions ................................................................................................................ 1-14
1 Introduction......................................................................................1-1
Overview ....................................................................................................................... 1-1
Audience........................................................................................................................ 1-1
About This Manual ..................................................................................................... 1-1
2 About Xstore Point of Service Configuration................................2-1

Overview ....................................................................................................................... 2-1
Configuration Path Updates from Xstore Office .............................................. 2-1
XML ......................................................................................................................... 2-1
Java Resource Bundle............................................................................................ 2-2
Java Properties ....................................................................................................... 2-2
Database.................................................................................................................. 2-2
Event Handling...................................................................................................... 2-2
Configuration Priorities ............................................................................................. 2-3
Overriding XML .................................................................................................... 2-3
Overriding Properties ........................................................................................... 2-3
3 Operation Chains.............................................................................3-1
Overview ....................................................................................................................... 3-1
About This Chapter............................................................................................... 3-1
The Operation Chain Framework (OpChains) ...................................................... 3-1
Operation Chain Defined ..................................................................................... 3-1
Operations and Chains ......................................................................................... 3-1
OpChains and Business Logic ............................................................................. 3-2
OpChain Flexibility ............................................................................................... 3-2
OpChain Example: Printing a Receipt................................................................ 3-2
Benefits of Operations Chains .................................................................................. 3-2
Configurability....................................................................................................... 3-2
Extensibility ............................................................................................................ 3-3
4
Reusability .............................................................................................................. 3-3
Modifying OpChains.................................................................................................. 3-3
Adding a New Step to an OpChain .................................................................... 3-3
Changing the Order of Operations in an OpChain .......................................... 3-3
Overriding and Extending Xstore Point of Service Base Functions............... 3-4
OpChainConfig.xml.................................................................................................... 3-5
Sample OpChain........................................................................................... 3-10
Reconfiguring an OpChain ......................................................................... 3-10
4 Data Transfer for Xstore Framework .............................................4-1

Overview ....................................................................................................................... 4-1
Introduction to the Data Transfer for Xstore Framework.................................... 4-2
What is the Data Transfer for Xstore Framework? ........................................... 4-2
Data Transfer for Xstore Supports Xstore Point of Service Extensibility and
Configurability....................................................................................................... 4-2
Data Transfer for Xstore Base Implementation for Data Access .................... 4-2
Data Transfer for Xstore and Data Model Objects............................................ 4-2
Data Transfer for Xstore Functions .......................................................................... 4-3
Distributed Database Support ............................................................................. 4-3
Object Persistence .................................................................................................. 4-3
Projects........................................................................................................................... 4-3
The data2 Project.................................................................................................... 4-3
The Data Transfer for Xstore Project................................................................... 4-4
Data Models and Data Objects ..................................................................... 4-4
Creating Data Transfer for Xstore-Based Data Models for Other Projects ... 4-4
Auto-Generating the Data Model Classes .............................................................. 4-5
Process Overview .................................................................................................. 4-5
Creating the Model Classes With DAOGen ...................................................... 4-5
Working With Data Model Configuration Files: Data Transfer for Xstore and
Data Transfer for Java ........................................................................................... 4-5
Data Transfer for Xstore File Layout .................................................................. 4-6
Sample Data Transfer for Xstore Source File..................................................... 4-7
Developer Guidelines for Manually Created Interfaces .................................. 4-8
The Data Transfer for Xstore File: <DAO> Element Attributes.......................... 4-8
The Data Transfer for Xstore File: <DAO> <field> Element Attributes ............ 4-9
The Data Transfer for Xstore File: <Relationship> Element Attributes.......... 4-11
Loading and Persisting Data Models ............................................................... 4-11
One-One Relationships Between Data Models ............................................... 4-11
One-Many Relationships Between Data Models ............................................ 4-12
Many-Many Relationships Between Data Models ......................................... 4-12
The Data Transfer for Xstore File: <Relationship> <Field> Element Attributes4-13
Parent-to-Child Fields......................................................................................... 4-13
Parent-to-Xref Fields ........................................................................................... 4-13
5
Xref-To-Child Fields............................................................................................ 4-14
The Data Transfer for Xstore File: <InverseRelationship> Element Attributes4-14
The Data Transfer for Java File: Providing Additional Java Code to the Data Model
4-15
Data Transfer for Java Files ................................................................................ 4-15
Overriding Auto-Generated Methods.............................................................. 4-16
Example of an Override .............................................................................. 4-16
Introduction to the Data Model Classes................................................................ 4-17
The Object ID Class ............................................................................................. 4-18
The Model Interface Class .................................................................................. 4-19
General Overview ........................................................................................ 4-19
Interface Extension ....................................................................................... 4-19
The DBA Model Class......................................................................................... 4-20
The DAO Model Class ........................................................................................ 4-20
The Model Class .................................................................................................. 4-20
Property “Getters” and “Setters”............................................................... 4-21
Relationship Access Methods ..................................................................... 4-21
Manually Created Methods ........................................................................ 4-21
Extensions...................................................................................................... 4-21
The Relationship Class........................................................................................ 4-21
Overhead Classes ................................................................................................ 4-21
DataModelFactoryImpl ............................................................................... 4-22
JDBCAdapterMapImpl................................................................................ 4-22
Data Transfer for Xstore Data Management......................................................... 4-22
Data Sources ......................................................................................................... 4-22
Persistence Managers.......................................................................................... 4-22
Data Replication................................................................................................... 4-23
Queries and Object Wrapping ........................................................................... 4-23
5 Data Sources....................................................................................5-1
Overview ....................................................................................................................... 5-1
About this Chapter ................................................................................................ 5-1
DataSourceConfig.xml File........................................................................................ 5-1
DataSourceConfig.xml Example:.............................................................................. 5-5
6 Persistence Mapping Configuration ..............................................6-1

Overview ....................................................................................................................... 6-1
About this Chapter ................................................................................................ 6-1
PmTypeMappingConfig.xml .................................................................................... 6-2
PersistenceManagerConfig.xml ................................................................................ 6-2
PersistenceManagerConfig.xml Example .......................................................... 6-4
6
7 Replication Configuration...............................................................7-1
Overview ....................................................................................................................... 7-1
Enabling and Disabling Replication in Xstore Point of Service ........................ 7-2
DtxReplicationConfig.xml ........................................................................................ 7-2
Queue Configuration (<ReplicationQueue>)..................................................... 7-3
Replication Services (<service>)........................................................................... 7-4
DtxReplicationConfiguration.xml Sample ................................................. 7-6
8 Query Configuration........................................................................8-1
Overview ....................................................................................................................... 8-1
About this chapter ................................................................................................. 8-1
QueryConfig.xml ......................................................................................................... 8-2
Elements and Attributes............................................................................................. 8-2
<Query> Element - Using DTXQL....................................................................... 8-2
<Query> Element - Raw SQL ............................................................................... 8-9
9 DocBuilder Framework ...................................................................9-1

Overview ....................................................................................................................... 9-1
Introduction to the DocBuilder Framework........................................................... 9-1
How DocBuilder Works: Process Overview...................................................... 9-2
Tracing ........................................................................................................................... 9-2
RcptConfig.xml ............................................................................................................ 9-2
Formatter (<Formatter>) .............................................................................................. 9-4
Formatter Example................................................................................................ 9-5
Receipt Copy Rule (<ReceiptCopyRule>) ............................................................... 9-5
Receipt Document (<receipt>) ................................................................................... 9-7
Receipt Document Example................................................................................. 9-8
Tender Franking (<FrankTender>) ........................................................................... 9-9
Append Formattable Text Containing Variable Placeholders
(<ParametrizedFormattable>) ............................................................................ 9-10
Append Formattable Text Output by a Function (<EvaluatedFormattable>)9-11
Section (<section>) ..................................................................................................... 9-11
Apply a Condition (<condition>) ...................................................................... 9-15
Condition Examples..................................................................................... 9-18
Condition Class (class)................................................................................. 9-18
Special Condition Classes ........................................................................... 9-19
The Parent Elements of Conditions ........................................................... 9-20
Text Block with Multiple Lines (<region>) ...................................................... 9-21
Simple <region> Example............................................................................ 9-22
Integer <left_margin> and <right_margin> Example .............................. 9-23
String <left_margin> and <right_margin> Example................................ 9-24
7
Field (<field>) ....................................................................................................... 9-25
Call a Function (method).................................................................................... 9-28
method Example........................................................................................... 9-28
method Chain Example ............................................................................... 9-28
<method_param> Example ......................................................................... 9-28
Looping Iterator (<iterator>) .............................................................................. 9-28
Custom Iterator: Iteration on Multiple Objects and Methods ............... 9-31
Multiple Lines of Text from com_receipt_text (<textblock>) ........................ 9-31
<textblock> Ordering and Formatting....................................................... 9-35
Barcode (<barcode>)..................................................................................... 9-35
Call New Object (<call>) ..................................................................................... 9-36
About Formatters and Custom Fields .............................................................. 9-37
DocBuilder field............................................................................................ 9-37
About Aggregate Fields...................................................................................... 9-38
About Fields Within Fields ................................................................................ 9-39
Method Parameters (<method_param>) .......................................................... 9-40
Other Field Elements........................................................................................... 9-40
Field Style (style) .......................................................................................... 9-40
Field Location (<location>).......................................................................... 9-41
Field Alignment (alignment) ...................................................................... 9-42
Field Priority (<priority>) ............................................................................ 9-43
10 Hardware Configuration & Communication ................................10-1

Overview ..................................................................................................................... 10-1
About this Chapter .............................................................................................. 10-1
JavaPOS (JPOS) Overview....................................................................................... 10-2
JPOS Architectural Components ....................................................................... 10-2
JPOS Layers and APIs......................................................................................... 10-2
Elements of the JPOS APIs ...................................................................................... 10-3
Generalized Sequence for Using a Device ........................................................... 10-3
Xstore Point of Service and JavaComm ................................................................. 10-4
Sample Configuration in jpos.xml: Cash Drawer ........................................... 10-5
Hardware Service in Thin Client............................................................................ 10-7
HwsDevices.properties....................................................................................... 10-7
Examples........................................................................................................ 10-7
HwsFamilyTypes.properties.............................................................................. 10-8
Example ......................................................................................................... 10-8
HwsConfig.properties ........................................................................................ 10-9
SSL Configurations ...................................................................................... 10-9
Appx Configurations ................................................................................... 10-9
HardwareConfig.xml .............................................................................................. 10-11
Device (<Device>) .............................................................................................. 10-13
Sample HardwareConfig.xml .......................................................................... 10-15
Code 93 Barcodes ..................................................................................................... 10-16
8
Device Settings by Category.................................................................................. 10-16
POS Printer Settings - jpos.xml........................................................................ 10-16
Cash Drawer Settings........................................................................................ 10-19
Signature Capture (SigCap) Settings .............................................................. 10-19
MICR Settings .................................................................................................... 10-20
MSR Settings ...................................................................................................... 10-20
PINPad Settings ................................................................................................. 10-21
Ingenico Settings................................................................................................ 10-21
11 Reporting Framework....................................................................11-1
Overview ..................................................................................................................... 11-1
About This Chapter............................................................................................. 11-1
Overview of the Report Creation Process ............................................................. 11-1
Data Templates .................................................................................................... 11-1
SQL Queries.......................................................................................................... 11-2
XML Configuration Files Used in Reporting ....................................................... 11-2
ReportQueryConfig.xml........................................................................................... 11-3
Database-Specific ReportQueryConfig.xml Files............................................ 11-3
12 Forms Framework..........................................................................12-1
Overview ..................................................................................................................... 12-1
About This Chapter............................................................................................. 12-1
FieldDefinitionConfig.xml ...................................................................................... 12-1
Examples............................................................................................................... 12-3
Label Field ..................................................................................................... 12-3
Text Field ....................................................................................................... 12-3
List Field ........................................................................................................ 12-3
GroupingList Field ....................................................................................... 12-3
Image Field .................................................................................................... 12-3
Table Field ..................................................................................................... 12-3
Chart Field ..................................................................................................... 12-4
Anchor Field.................................................................................................. 12-4
ProgressBar Field.......................................................................................... 12-4
Signature Field.............................................................................................. 12-4
MoreAuthInfo Field ..................................................................................... 12-4
FieldLayoutConfig.xml............................................................................................. 12-4
Example................................................................................................................. 12-6
Form Definition Files................................................................................................ 12-7
13 Spring Integration........................................................................13-11
Overview ................................................................................................................... 13-11
Benefits ...................................................................................................................... 13-11
Dependency Injection ....................................................................................... 13-12
9
Spring Beans....................................................................................................... 13-12
Spring Bean Files ........................................................................................ 13-12
Use of the Configurable Annotation and Injection of Fields ......................... 13-13
Example - Operation ......................................................................................... 13-13
Custom Spring Scopes ............................................................................................ 13-14
Application Mode.............................................................................................. 13-14
Training Mode.................................................................................................... 13-14
Transaction .................................................................................................. 13-15
Scoping/Value Keys ................................................................................................ 13-15
DefaultScope ...................................................................................................... 13-16
Use ................................................................................................................ 13-16
Removal of Values...................................................................................... 13-17
TransactionScope............................................................................................... 13-18
Use ................................................................................................................ 13-18
Removal of Values...................................................................................... 13-19
Management of Helpers/Singletons .................................................................... 13-19
Define a helper bean.......................................................................................... 13-20
Use it in a class ................................................................................................... 13-20
Override the helper bean (assume that CstCustomerHelper extends
CustomerHelper) ............................................................................................... 13-20
Management of Services ........................................................................................ 13-20
Service Implementations .................................................................................. 13-20
Service Handlers ................................................................................................ 13-20
Flow Transparency and OpChainConfig.xml Readability.............................. 13-20
New Elements .................................................................................................... 13-21
Op ................................................................................................................. 13-21
ValidationOp............................................................................................... 13-21
PromptOp.................................................................................................... 13-21
WorkerOp.................................................................................................... 13-22
OpChainRoute ............................................................................................ 13-22
14 Internationalization........................................................................14-1
Overview ..................................................................................................................... 14-1
About this Chapter .............................................................................................. 14-1
Internationalization (i18n) ....................................................................................... 14-2
Implementing i18n .............................................................................................. 14-2
Applications of Internationalization in Xstore Point of Service ................... 14-2
Internationalization (i18n) and Localization (L10n) ....................................... 14-3
Multilingualization (m17n) ................................................................................ 14-3
Xstore Point of Service i18n Implementation....................................................... 14-3
Java Standards...................................................................................................... 14-3
Language Codes .................................................................................................. 14-3
Configuring Languages in Xstore Point of Service......................................... 14-4
Sample Entries in LocaleMap.xml: ............................................................ 14-4
10
Language Files ..................................................................................................... 14-4
Individual Customization .................................................................................. 14-5
Translation Resource Bundles ........................................................................... 14-6
Language and Country................................................................................ 14-6
Defining Common Mappings for Different Keys .................................... 14-7
Configuration Accelerators...................................................................................... 14-8
Xstore Office and SystemConfigMetadata.properties........................................ 14-8
Overview .............................................................................................................. 14-8
i18n and the SystemConfigMetadata.properties File ..................................... 14-9
Creating a "Stub" Metadata File for Other Languages............................ 14-9
11
Send Us Your Comments
Oracle welcomes customers' comments and suggestions on the quality and usefulness of
this document.
Your feedback is important, and helps us to best meet your needs as a user of our
products. For example:
• Are the implementation steps correct and complete?
• Did you understand the context of the procedures?
• Did you find any errors in the information?
• Does the structure of the information help you with your tasks?
• Do you need different information or graphics? If so, where, and in what format?
• Are the examples correct? Do you need more examples?
If you find any errors or have any other suggestions for improvement, then please tell us
your name, the name of the company who has licensed our products, the title and part
number of the documentation and the chapter, section, and page number (if available).
Note: Before sending us your comments, you might like to check that
you have the latest version of the document and if any concerns are
already addressed. To do this, access the Online Documentation
available on the Oracle Technology Network Web site. It contains the
most current Documentation Library plus all documents revised or
released recently.
Send your comments to us using the electronic mail address: retail-doc_us@oracle.com

Please give your name, address, electronic mail address, and telephone number
(optional).
If you need assistance with Oracle software, then please contact your support
representative or Oracle Support Services.
If you require training or instruction in using Oracle software, then please contact your
Oracle local office and inquire about our Oracle University offerings. A list of Oracle
offices is available on our Web site at www.oracle.com
12
Preface
This guide describes the programming and configuration frameworks used in the
development of Xstore Point of Service, and the technologies integrated with Xstore
Point of Service.
Audience
This Frameworks & Technologies Guide is for administrators and programmers of
Oracle Retail Xstore Point of Service.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility
Program website at http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=docacc.
Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/
lookup?ctx=acc&id=trs if you are hearing impaired.
Related Documents
For more information, see the following documents in the Xstore Point of Service 17.0
documentation set:
• Xstore Suite Release Notes
• Xstore Suite Oracle Retail Xstore Suite 17.0/Merchandising 16.0.1 Implementation
Guide
• Xstore Point-of-Service User Guide
• Xstore Point-of-Service Mobile User Guide
• Xstore Point-of-Service Reports Guide
• Xstore Point-of-Service Manager's Guide
• Xstore Point-of-Service Shipping, Receiving, and Inventory Guide
• Xstore Office User Guide
• Oracle Retail Xstore Point-of-Service, Lane Checkout User Interface User Guide
• Xstore Suite Implementation and Security Guide
• Xstore Point-of-Service Host Interface Guide
• Xstore Suite Deal Pricing Guide
• Xenvironment User Guide
• Xstore Point-of-Service Services Guide
13
Customer Support
• Xstore Point-of-Service Technical Guide

• Xstore Point-of-Service POS Log Files
• Xstore Point-of-Service Database Dictionary Guide
• Xstore Office Database Dictionary Guide
Customer Support
To contact Oracle Customer Support, access My Oracle Support at the following URL:
https://support.oracle.com
When contacting Customer Support, please provide the following:
• Product version and program/module name
• Functional and technical description of the problem (include business impact)
• Detailed step-by-step instructions to re-create
• Exact error message received
• Screen shots of each step you take
Review Patch Documentation

When you install the application for the first time, you install either a base release (for
example, 13.3) or a later patch release (for example, 13.3.1). If you are installing the base
release or additional patch releases, read the documentation for all releases that have
occurred since the base release before you begin installation. Documentation for patch
releases can contain critical information related to the base release, as well as
information about code changes since the base release.
Oracle Retail Documentation on the Oracle Technology

Network
Documentation is packaged with each Oracle Retail product release. Oracle Retail
product documentation is also available on the following Web site:
http://www.oracle.com/technology/documentation/oracle_retail.html
(Data Model documents are not available through Oracle Technology Network. These
documents are packaged with released code, or you can obtain them through My Oracle
Support.)
Documentation should be available on this Web site within a month after a product
release.
Conventions
Navigate: This is a navigate statement. It tells you how to get to the start of the procedure
and ends with a screen shot of the starting point and the statement “the Window Name
window opens.”
This is a code sample
It is used to display examples of code
14
Conventions
15
1
Introduction
Overview
This guide has been designed to provide the reader with a basic understanding of Xstore
Point of Service and the technology underlying its design. This guide is not intended as a
complete technical guide to every facet of Xstore Point of Service; however, it includes
information to provide a better understanding of the technology and methodology used
in the design of Xstore Point of Service.
Audience
This guide is intended for technical personnel working with Xstore Point of Service. This
can include anyone responsible for altering or creating process flows, configuring Xstore
Point of Service, or looking for a more fundamental understanding of Xstore Point of
Service and the concepts used in its design and creation.
About This Manual

• Chapter 2, “About Xstore Point of Service Configuration” briefly describes Xstore
Point of Service configuration formats, and explains the benefits and restrictions of
each format.
• Chapter 3, “Operation Chains” describes how Operation Chains work and how they
are used in Xstore Point of Service.
• Chapter 4, “Data Transfer for Xstore Framework” describes DTX and its underlying
concepts and technologies.
• Chapter 5, “Data Sources” describes how data sources are configured and accessed
in Xstore Point of Service.
• Chapter 6, “Persistence Mapping Configuration” describes how to map data sources
to Java objects in Xstore Point of Service.
• Chapter 7, “Replication Configuration” explains how replication is enabled and
configured in Xstore Point of Service.
• Chapter 8, “Query Configuration” explains how database queries are created,
configured, and used by Xstore Point of Service.
• Chapter 9, “DocBuilder Framework” explains the various documents created by
Xstore Point of Service and how they are configured.
• Chapter 10, “Hardware Configuration & Communication” describes how Xstore
Point of Service communicates with hardware attached to the system and how to
configure Xstore Point of Service to connect to it.
Introduction 1-1
About This Manual
• Chapter 11, “Reporting Framework” explains how reports are created and run in
Xstore Point of Service.
• Chapter 13, “Spring Integration” describes Xstore Point of Service’s integration with
the Spring framework.
• Chapter 14, “Internationalization” describes how internationalization (i18n) is
implemented in Xstore Point of Service.
1-2 Frameworks & Technologies Guide

2
About Xstore Point of Service Configuration
Overview
Configurations are generally more flexible, manageable, extensible, and easily deployed
than code-based modifications. Xstore Point of Service supports several configuration
formats, each with their own benefits and restrictions. The following formats are briefly
explained below: XML, Java Resource Bundle, Java Properties, and Database.
Note: Many of the configurations in Xstore Point of Service can be set

through Xstore Office.
Configuration Path Updates from Xstore Office

A configuration in system.properties determines whether or not Xstore Point of
Service checks Xstore Office for updates to the configuration path.
dtv.update.configpath.from.Xcenter=true
- When enabled (default), Xstore Point of Service will check Xstore Office at
startup to see if any changes were made to the configuration path. If so, the
configuration path will be updated in system.properties and loaded during
the startup process.
- When disabled, Xstore Point of Service will not check Xstore Office for updates.
This option is available for retailers who choose to continue to define the
configuration path manually.
Note: See the Xstore Point of Service Technical Guide and Xstore Office

User Guide for more information.
XML
XML (Extensible Markup Language) is the most versatile and common means of
configuring Xstore Point of Service. Xstore Point of Service application of XML makes
use of hierarchies and explicit data typing to assign runtime parameters or build
equivalent object structures.
XML is used where parent/child-based hierarchies must be supported. The
configurations are implemented in the various XML files corresponding to specific
functional or technical domains.
About Xstore Point of Service Configuration 2-1

Overview
Java Resource Bundle

Resource Bundles are nothing more than localized Properties objects. They are the
principal means by which localized text, numerical formats, and other information that
can be internationalized is configured. Unlike Properties, which support chaining only
programmatically, Resource Bundles support chaining directly via their file names.
Resource Bundle files, which also end with a .properties extension, are suffixed with
an ISO code indicating the language and, possibly, country they represent.
A Resource Bundle is used where the data being configured is localized.
Note: In this situation a database may be used; however, this is less

common than the Resource Bundle implementation.
Java Properties
A .properties file contains string-key-to-string-value mappings. Its equivalent Java
representation is called a Properties object. Unlike XML, Properties configurations do
not support hierarchies or non-string data types. When manipulated programmatically,
Properties objects may be “chained” to form an arbitrarily deep extension hierarchy.
Outside of code, however, there are no real or implied relationships between
.properties files. Therefore, Properties objects are extensible, but .properties files
are not.
A Properties object is usually employed where the data being configured is naturally a
collection of simple key-value pairs.
Database
This data can be updated via downloads, which makes it slightly less static and slightly
easier to maintain as a result. The set of reason codes for returning an item is an example.
Xstore Point of Service can reference such configurations via its Persistence framework.
Database configuration is used where the data is, or may be part of, a download
interface between the home office and the application clients.
Event Handling
Events are defined methods by which a user can interact with Xstore Point of Service.
Xstore Point of Service is a highly interactive application. Examples of Events include
selecting a key, selecting a combination of keys, or entering text from the keyboard.
Mouse activities such as clicking and selecting an item from a list are also Events.
Xstore Point of Service can be described as an Event-driven application. It provides
“listeners” that detect Events, then Xstore Point of Service responds to them accordingly.

Configuration Priorities
The configuration framework supports a mechanism for ranking configurations by
priority. Higher-priority configurations extend or override equivalent, lower-priority
configurations. Configuration priorities are determined by the configuration path which
determines the locations of all client configuration resources, and is mapped to the VM
parameter dtv.config.path.
All base configuration resources, which have the lowest priority, are located in the
classpath-accessible directory dtv/res/config.
Overriding XML
• The lowest-priority level declaration of an element determines that element’s
ancestral context.
• In order to describe an override, the element to be overridden must be identified by
both its ancestral context and name/ID.
• Siblings and ancestors will be unaffected by overrides resolved for elements not
belonging to an undifferentiated collection.
• Overriding any member of an undifferentiated collection results in the substitution
of all members of that collection with those specified in the overriding configuration.
Overriding Properties
• For the purposes of conflict detection, property entries are identified by their keys
and the name of the file in which they are declared.
• Overriding a property entry requires mapping a new value to the key to be
overridden in a file with the same name as that overridden key.
• All configuration path-based overrides are processed against a set of properties
before any programmatic hierarchies are enforced.
• The value of a property that is deeper in its programmatic hierarchy than another,
higher-priority (per the configuration path) property will still take precedence in a
lookup operation.
About Xstore Point of Service Configuration 2-3


3
Operation Chains
Overview
This chapter describes what Operation Chains (OpChains) are, what they do, and how
they are configured. Because Xstore Point of Service builds standard functionality using
OpChains, an understanding of this software design and implementation method will
help you understand Xstore Point of Service more fully. In addition, this will allow you
to see how flexible Xstore Point of Service can be.
About This Chapter

This chapter contains the following information:
• The Operation Chain Framework (OpChains) provides an overview of Operation
Chains, what they are, what they do, and how they are used in Xstore Point of
Service.
• Benefits of Operations Chains describes why Xstore Point of Service is built using
Operation Chains and the benefits that this design has for the software.
• Modifying OpChains explains how OpChains can be modified.
• OpChainConfig.xml describes the structure of the file OpChainConfig.xml, which
configures the process flow of each OpChain.
The Operation Chain Framework (OpChains)

Operation chains provide business logic for various functions throughout Xstore Point of
Service. This section describes how they work, defines the elements within an OpChain,
and explains how you may configure them to meet your business needs.
Operation Chain Defined

An operation chain is a configurable sequence of operations (tasks) that comprise a
logical process or workflow. The term operation chain is often shortened to just
“OpChain”. In Xstore Point of Service, the file OpChainConfig.xml defines the
operation chains used by the system.
From the perspective of an Xstore Point of Service user, an operation chain closely
resembles a unit of work that performs a functional process. In the retail environment,
for example, functions like selling an item or adding a tender have operation chains.
Operations and Chains

The Operation Chain Framework is comprised of two entities: operations (what you
want done) and chains (a sequential arrangement of operations that are related to a
Operation Chains 3-1

Benefits of Operations Chains
function). All Xstore Point of Service application functions are implemented by the use
of operation chains.
OpChains and Business Logic

Business processing logic is executed by the Operation Chain Framework in Xstore Point
of Service. What you want done (an operation) and the order in which it is done is most
often handled by an OpChain.
The standard operation chain is executed sequentially, starting with the first operation
and executing in top-to-bottom order, as the operations are listed. Each subsequent
operation (or chain) is executed after the current operation is completed.
OpChain Flexibility
While most processing will follow a “straight-through” flow, the OpChain Framework
has the flexibility to accommodate new types of operation chains created for special
processing needs.
OpChain Example: Printing a Receipt

Receipt printing is a common procedure used in many kinds of retail processes. A
simplified process flow for printing a receipt is illustrated in the figure below. The actual
operations are defined in a structured XML document.
PRINT_RECEIPTS OpChain
Wait for
Build Email Print Save Print Fiscal
Receipts to
Receipts Receipts Receipts Receipts Receipts
Print
Figure 3-1: Sample Process Flow in an OpChain
Each Operation Chain must have a unique identifying name (such as

PRINT_RECEIPTS) which enables it to be referenced by other OpChains. The contents
of the XML include all of the operations in the order in which they will be performed. An
operation may be either a Java class or another OpChain. Iterative operations, such as
prompting a user for a code, may be included when “straight-through” processing does
not work.
Benefits of Operations Chains

Three key benefits are derived from the Operation Chain Framework, and they set
Xstore Point of Service apart from other POS applications. The three benefits are:
• Configurability
• Extensibility
• Reusability
Configurability
The Operation Chain Framework gives you the ability to customize Xstore Point of
Service to meet your specific business requirements without having to modify source
code. Operation chains are contained within files that are easily accessible and editable.

Modifying OpChains
Extensibility
The Operation Chain Framework allows you to define and implement new business
logic that may not be available in the base version of Xstore Point of Service. This can
also be done without touching source code.
Reusability
Operation chains typically contain operations and other chains. The ability to reuse an
existing chain is useful for logical flows that are common across multiple functions. For
example, after defining an OpChain for receipt printing, it could be easily inserted into
other OpChains such as those for a layaway sale, a special order sale, or a regular retail
sale.
Modifying OpChains
This section describes how OpChains may be modified by adding or deleting steps,
changing the sequence of steps, and how base functions can be overridden.
Adding a New Step to an OpChain

From time to time you may need to modify an Operation Chain. It’s simply a matter of
editing the XML file and inserting the new operation in the correct order. The new step
may be another OpChain or a Java class.
The figure below shows the operation chain for a PRINT_RECTIPTS OpChain in which
a reference to the Print Receipts In Back Office OpChain has been inserted.
Of course, any OpChain may also be easily modified by editing the XML file and
deleting any unwanted operations or Java classes.
Wait for
Build Email Print Save Print Fiscal
Receipts to
Print
Print
Receipts in
Back Office
Figure 3-2: Inserting an OpChain Illustrates Reusability Feature
Changing the Order of Operations in an OpChain

Rearranging the order in which processing occurs is just a matter of changing the order
in which the operations or Java classes are listed in the OpChain. For example, in the
previous figure, the system emailed receipts before printing them. As seen in Figure 3-3,
the order is reversed and the system prints receipts first.

Modifying OpChains
By editing the OpChain XML file, you have complete control over the order in which
operations are executed.
Wait for
Build Print Email Save Print Fiscal
Receipts to
Print
Print
Receipts in
Back Office
Figure 3-3: Reordering the Execution Order in an OpChain
Note: This example is provided for illustration purposes only and

may not represent a valid operation order.
Overriding and Extending Xstore Point of Service Base Functions

Overriding an operation refers to the capability of completely replacing a base operation
with a customized one. When you override a base function, your new operation takes
precedence over the base operation. The base operation still exists, but it is dormant and
will not be processed.
Extending, on the other hand, refers to the capability of an operation to “inherit” the
properties of its parent operation and further enhance them. This is typically done by
extending an existing Java class. In this way, the instructions in both the parent operation
and in the extended operation are processed.
Build
Receipts PRINT_RECEIPTS OpChain
Email
W ait for
Custom Print Receipts Save Print Fiscal
Receipts to
Receipts Receipts Receipts Receipts
… and send Print
Messages
Overriding an Print
operation Receipts in
Back Office
Extending an
operation
Figure 3-4: Overriding and Extending Operations in an OpChain
In Figure 3-4, the operation Custom Receipts replaces the base operation Build
Receipts, and the original operation is ignored during processing.
Furthermore, ...and send Messages extends the capabilities of Email
Receipts—its parent—and enhances the operation’s functionality. As long as the
programming interface (the API) does not change, the customized operation will
function properly even if the Xstore Point of Service application is updated. The parent,
or original operation, will be distributed with updates.

OpChainConfig.xml
OpChainConfig.xml
The file OpChainConfig.xml defines the structure and process flows for all the
OpChains used in Xstore Point of Service.
This file has the following organization:
<OpChainSet> Element:
xmlns:xsi Attribute
xsi:noNamespaceSchemaLocation Attribute
<OpChain> Element:
name Attribute
signal Attribute
contextKey Attribute
rollbackChainKey Attribute
rollbackLevel Attribute
<Op> Element:
class Attribute
required Attribute
breakpoint Attribute
longRunning Attribute
contextKey Attribute
<Parameter> Element:
dtype Attribute
name Attribute
value Attribute
ref Attribute
<value> Element:
dtype Attribute
<entry> Element:
dtype Attribute
key Attribute
value Attribute

OpChainConfig.xml
<OpChainRoute> Element:
chainKey Attribute
chainType Attribute
condition Attribute
<Choice> Element:
chainKey Attribute
condition Attribute
chainType Attribute
<Condition> Element:
class Attribute
dtype Attribute
name Attribute
value Attribute
ref Attribute
<value> Element:
dtype Attribute
<entry> Element:
dtype Attribute
key Attribute
value Attribute
<PromptOp> Element: (Sub-type of <Op>)
key Attribute
validationsBean Attribute
<WorkerOp> Element: (Sub-type of <Op>)
workersBean Attribute
<ValidationOp> Element: (Sub-type of <Op>)
validationsBean Attribute
• <OpChainSet> - This element contains all the OpChains defined in the file.
- xmlns:xsi - The XML schema definition.
- xsi:noNamespaceSchemaLocation - The name of the .xsd file associated
with the XML file.
• <OpChain> - This element defines an OpChain and its process flow. This element
has the following attributes:
- name - This attribute uniquely identifies a chain. This name is used to refer to
the <OpChain> in other <OpChain> elements, or in other files.
- signal - This attribute identifies the action that will be performed when the
chain completes. The most common values are:

OpChainConfig.xml
* TransactionModified - Xstore Point of Service recalculates the monetary

totals.
* TransactionCancelled or TransactionComplete - Xstore Point of
Service clears the transaction scope.
- contextKey - This attribute links the <OpChain> to a key with the same name
in the file ContextConfig.xml. This context sets up the environment in which
an operation will run (used mainly with UI configurations).
Note: This includes the help information displayed when the user
presses the F1 key.
- rollbackChainKey - This attribute refers to the <OpChain> to run if the

current <OpChain> is cancelled prior to completing processing. For example, if
the user escapes out of tender processing prior to completing tendering, Xstore
Point of Service calls the <OpChain> named in the rollbackChainKey
attribute for the <OpChain> used for tender processing.
- rollbackLevel - This attribute defines an integer value that identifying a
chain as a stopping point when backing up. You can have multiple rollback level
active at one time on nested chains, as long as the value of the levels increase as
you go into chains.
Note: A rollback level declares a Chain as a “fallback position”

during a reversal, just like a breakpoint declares an Op as a fallback
position. (See breakpoint below). Rollback levels only come into play
when there are no more breakpoints in the current chain to fall back to.
• <Op> - This element specifies the fully-qualified name for a Java class run as part of
the chain. (Note: <Operation> has been deprecated.) Any number of <Op> tags
can be included within an <OpChain> element. This element has the following
attributes:
- class - This attribute specifies the fully-qualified name of the Java class
implementing this operation.
- required - This attribute specifies whether or not the operation is required to
complete successfully in order for its parent chain to continue. An <Op> defaults
to “True” (required) unless this attribute is set to “False”.
- breakpoint - This attribute marks an escape point from the current operation.
This provides the ability to control the flow of operations. An enabled
breakpoint indicates that its parent Op should be re-run after a reversal if:
* it exists in the currently-running Chain
* it has previously completed
- contextKey - This attribute sets a context key for a specific operation at the
<Op> level.
- longRunning - This attribute is used to tag an operation that has a large
amount of background processing. This triggers the “Please Wait” message in

OpChainConfig.xml
• <Parameter> - This element is used to send a parameter value to the Java class
called in the <Op> element.
Note: This element can be the child of many different elements in the
OpChain configuration format.
- name - The name of the parameter. This attribute performs the same function as
the <param_name> element.
- value - The value that is sent in the parameter. If the value attribute is used,
the parameter is sent as a String. If the parameter being sent has a different data
type (such as Boolean or Class), the <param_value> sub-element must be
used, with the dtype attribute indicating the type of data being sent.
• <value> - This element contains the value sent in the named <Parameter>. This
element allows a value that is not a String to be sent as a parameter.
- dtype - This attribute indicates the type of data contained in the
<param_value> element.
• <OpChainRoute> - Routes processing to a specified <OpChain>. A condition can
be specified to determine the next chain to run (optional). When no condition is
specified, the chain always runs.
- chainKey - This attribute specifies the name used to refer to the included
<OpChain>.
- chainType - This attribute determines the chain type: STACK (default) or
START. When no chainType is specified, assumes STACK type.
* STACK (default) - Once the called chain completes, processing is returned to
the referring chain.
* START - Once the called chain completes, processing does not return to the
referring chain.
- condition - A class that implements the run chain condition interface to
determine if the specified chainKey will run. If no condition is specified, the
chain always runs.
Note: A “!” before the class will invert the results of the condition by
setting the invert parameter behind the scenes.
• <Choice> - A tag element (container) for chainKey and chainType. The first
choice that has the condition satisfied will be run and all others will be ignored.
- dtype - Data type.
- chainKey - The name used to refer to the included <OpChain>.
- condition - A class that implements the run chain condition interface to
determine if the specified chainKey will run. If no condition is specified, the
chain always runs.
A “!” before the class will invert the results of the condition by setting the invert
parameter behind the scenes.
Example:

OpChainConfig.xml
<Choice chainKey="SHIPPING_PRINT_GENERIC_LABEL" condition=

"!dtv.pos.inventory.ship.label.LabelServiceNeeded"/>
Note: Conditions can be specified as attributes like this, or with a

nested <Condition> element.
- chainType - Determines the chain type: STACK (default) or START. When no

chainType is specified, assumes STACK type.
* STACK (default) - Once the called chain completes, processing is returned to
the referring chain.
* START - Once the called chain completes, processing does not return to the
referring chain.
• <Condition> - This element specifies a class that implements the run chain
condition interface to determine if the specified chainKey will run. If no condition
is specified, the chain always runs.
- class - This attribute specifies the fully-qualified name of the Java class
implementing the command.
Note: Conditions can be specified using an element like this, or with a

nested condition attribute.
• <PromptOp> - Sub-type of <Op> element. Provides clarity to indicate the user will
be prompted for something.
Note: Class is optional. If not specified, defaults to the operation

PromptOp. Class must implement the IPromptOp interface.
- key - The prompt key (only specified on an exception basis). Overrides the
default value in the operation.
- validationsBean - A reference to the bean that defines the list of validation
rules to apply on the prompt if applicable. Optional on the <PromptOp>.
• <WorkerOp> - Sub-type of <Op> element. Runs the list of workers.
Note: Class is optional. If not specified, defaults to the operation

SimpleDoWorkOp.
- workersBean - A reference to the bean that defines the list of workers to be run.
Any class using this tag must implement the IWorkerOp interface.
• <ValidationOp> - Sub-type of <Op> element. Runs the validation rules.
Note: Class is optional. If not specified, defaults to

ValidationWithoutPromptOp. Class must implement the
IValidationOp interface.
- validationsBean - A reference to the bean that defines the list of validation

rules to apply. Required on the <ValidationOp>.

OpChainConfig.xml
Sample OpChain
<OpChain name="REFUND_MISC" contextKey="REFUND_TENDER_EMPTY_MENU_OPTION">

<PromptOp class="dtv.pos.tender.misc.PromptMiscTenderOp">
<Parameter name="TenderStatus" value="Refund" />
</PromptOp>
<PromptOp class="dtv.pos.tender.PromptCustAsscRequiredForTenderOp" />
<Op class="dtv.pos.tender.check.PromptIdentityVerificationOp" />
<PromptOp class="dtv.pos.tender.misc.PromptMiscTenderNumberOp"
validationsBean="serialNumberRules" />
<PromptOp class="dtv.pos.tender.PromptTenderAmtOp"
validationsBean="tenderAmountRules" />
<Op class="dtv.pos.tender.AddTenderToSaleTranOp" />
<Op class="dtv.pos.tender.rounding.UpdateTransactionRoundedAmountOp" />
<OpChainRoute chainKey="CHECK_SALE_COMPLETE" chainType="START" />
</OpChain>
Reconfiguring an OpChain
Note: The examples shown here are provided for illustration
purposes only and may not represent a valid operation order.
OpChains are easily reconfigured by editing the XML file. In the first example below, the
system first prompts for a reason (following bolded comment) and then prompts for a
comment (following bolded comment) during a No Sale transaction.
Example 1: OpChain Before Reconfiguration

<OpChain name="NO_SALE_MANUAL">
<Command class="dtv.pos.register.SaleItemCmd" />
<Op class="dtv.pos.nosale.CreateNoSaleTransactionOp" />
<!- Prompt for a REASON for the no sale transaction -->

<Op class="dtv.pos.nosale.LookupManualNoSaleReasonCodeOp" />
<!- Prompt for a COMMENT about the no sale transaction -->

<Op class="dtv.pos.nosale.LookupManualNoSaleCommentOp" />
<Op class="dtv.pos.nosale.CompleteNoSaleTransOp" />
...
</OpChain>
Example 2: OpChain After Reconfiguration

After reconfiguration, the system prompts for a comment first and then prompts for the
No Sale reason. The order of the two prompts has been reversed. If you decide that a

OpChainConfig.xml
comment is not necessary, that operation could be marked as a comment or deleted from
the file.
<OpChain name="NO_SALE_MANUAL">
<Command class="dtv.pos.register.SaleItemCmd" />
<Op class="dtv.pos.nosale.CreateNoSaleTransactionOp" />
<!- Prompt for a COMMENT about the no sale transaction -->

<Op class="dtv.pos.nosale.LookupManualNoSaleCommentOp" />
<!- Prompt for a REASON for the no sale transaction -->

<Op class="dtv.pos.nosale.LookupManualNoSaleReasonCodeOp" />
<Op class="dtv.pos.nosale.CompleteNoSaleTransOp" />
...
</OpChain>

OpChainConfig.xml

4
Data Transfer for Xstore Framework
Overview
This chapter describes the Data Transfer for Xstore (DTX) Framework, what it does, how
it is used by Xstore Point of Service, and the files that are used in its configuration.
Because DTX is used as an interface between Xstore Point of Service and some of its
external data sources, an understanding of DTX allows you to understand how many
disparate data sources are managed.
The use of DTX for data transfer and translation can allow disparate data sources to be
seamlessly managed in Xstore Point of Service through a consistent interface. Xstore
Point of Service simply makes requests for information or data propagation, while DTX
handles the details of connecting with the data source and moving data from place to
place.
About This Chapter

• Introduction to the Data Transfer for Xstore Framework provides an overview of the
DTX Framework and its functions.
• Data Transfer for Xstore Functions describes the functions performed by the DTX
Framework.
• Projects provides an overview of DTX Projects.
• “Auto-Generating the Data Model Classes” describes the DAOGen process, which
creates data models for DTX.
• “The Data Transfer for Xstore File: <DAO> Element Attributes” describes each of the
attributes of the <DAO> element for the .dtx files.
• “The Data Transfer for Xstore File: <DAO> <field> Element Attributes” describes
each of the attributes of the <DAO> element’s <field> sub-element.
• “The Data Transfer for Xstore File: <Relationship> Element Attributes” describes
each of the attributes of the <Relationship> element for the .dtx files.
• “The Data Transfer for Xstore File: <Relationship> <Field> Element Attributes”
describes each of the attributes of the <Relationship> element’s <Field> sub-
element.
• “The Data Transfer for Xstore File: <InverseRelationship> Element Attributes”
describes each of the attributes of the <InverseRelationship> element for the
.dtx files.
• “The Data Transfer for Java File: Providing Additional Java Code to the Data Model”
provides an overview of .dtj files.
Data Transfer for Xstore Framework 4-1

Introduction to the Data Transfer for Xstore Framework
• “Introduction to the Data Model Classes” provides an overview of the six data
model classes generated when DAOGen processes the DTX and DTJ configuration
files.
• “Data Transfer for Xstore Data Management” provides an overview of DTX data
management and describes where to find more information about certain areas of
DTX.
Introduction to the Data Transfer for Xstore Framework

This section provides a brief overview of DTX and the underlying concepts and
technologies that make it both powerful and flexible.
What is the Data Transfer for Xstore Framework?

The acronym DTX means “Data Translation for Xstore Point of Service”. DTX provides a
common mechanism through which specific data access implementations can be built
for Java Database Connectivity (JDBC), servlets, web servers, and applications. These
implementations retrieve, persist, and replicate data between local, remote, and external
sources through DTX.
Data Transfer for Xstore Supports Xstore Point of Service Extensibility

and Configurability
DTX supports the Xstore Point of Service “extension layer”, where new functionality can
be added and existing functionality can be modified. It does this in two ways:
• First, DTX can be used to generate custom data models that meet a customer’s
unique business requirements.
• Second, DTX can connect to a variety of data sources through configurable
implementations for JDBC, servlets, web servers, and applications.
Note: To accommodate customer extensions without affecting the

base (in terms of inheritance or anything else), each data object exposes
a method of the form "get*Ext()" where * is the data object name. For
example, in the case of Item, this method would be getItemExt(). By
default, these extension methods are not used in the base Xstore
application.
Data Transfer for Xstore Base Implementation for Data Access

DTX uses Java Database Connectivity (JDBC) to connect to data sources. Any JDBC-
compliant driver can be used. Standard SQL statements such as SELECT, INSERT,
UPDATE, and DELETE are then used to access and modify data.
Data Transfer for Xstore and Data Model Objects

The data model object is a fundamental concept in object-oriented programming
languages like Java. Data model objects are related in parent-child relationships through
which a child data model inherits the properties of the parent data model. DTX loads
and manages the relationships among data objects (object/relational mapping) so that
the Xstore Point of Service application does not need to.
The DTX Framework is specifically designed to work with data model objects. In DTX,
every database table has a number of corresponding data model classes. Xstore Point of
Service uses these data model classes to generate data objects during transactions.

Data Transfer for Xstore Functions
Data Transfer for Xstore Functions

This section describes the critical data-related functions performed by DTX, and how the
functions are implemented.
When accessing the DataFactory, class dtv.data2.access.DataFactory is the
“gatekeeper” for all of the activities that are involved in data access, manipulation, and
persistence. The DataFactory class and its methods are called whenever Xstore Point of
Service retrieves or persists data to or from any data source.
Distributed Database Support

The DTX Framework is able to persist data to any specified database location. Each data
model has its own persistence manager type, which is then associated with a persistence
strategy, which in turn determines its origin and destination database location(s). All
communication with the database is handled by DTX; the Xstore Point of Service
application is unaware of the data source location.
DTX can serve as an alternative to native database replication or third-party replication
products. Data may also be centralized in a single location, making it available for
functions such as chain-wide validation of returns, or tracking store-to-store transfers.
Object Persistence
Data is packaged in units called objects. Every object is constructed according to its data
model, which acts as a template for the object. A data model describes the properties of
an object, and provides methods (typically Java language “getters” and “setters”) for
accessing it. For example, items, customers, and prices are different types of data, each of
which has its own model. An unlimited number of data types may be defined.
An object must be persisted (saved) so that it can be accessed whenever it is needed. The
persistence process is accomplished via a variety of mechanisms including, but not
limited to, serialization into an XML representation of the object which is transmitted to
a servlet; translation to database table rows; and translation into SOAP-based web
service calls. The DTX Framework handles the process of persisting objects, even across
distributed storage locations.
Projects
A Project is a logical grouping of files that are related to a single technology, framework,
or function of an application. For example, the DTX Project includes all of the files that
are needed to support base Xstore Point of Service data models. This includes both
source files and generated output files. Another example is the data2 Project, which
includes all of the files that generate or perform the data persistence function within the
DTX Framework.
In the development environment, a Project is typically organized into a logically
arranged folder structure so that all of the related files are grouped together.
The output of a Project is a .jar file that is packaged as a component of the application.
The dtv-dtx.jar file and the dtv-data2.jar file are, respectively, products of the
dtx and data2 projects. They are both found in the lib folder for the Xstore Point of
Service application.
The data2 Project

The data2 creates the dtv-data2.jar file. This Java archive contains the files that are
used to access and manipulate data in the different data sources.

Projects
There are four major functions performed by the data2 Project:

• Generating data model classes: Creating data models from configuration files (see
Auto-Generating the Data Model Classes). These data models are like templates
from which objects are generated at run time.
• Loading data: Translating data files from external sources and loading them into an
Xstore Point of Service database.
Note: See the Xstore Point of Service Host Interface document for more

information about the DataLoader.
• Persisting data: Accessing and manipulating data from a data source.

• Replicating data: Copying existing data to other locations (see Data Replication).
To perform these functions, the data2 Project includes the DataFactory class
dtv.data2.access.DataFactory. Xstore Point of Service calls this class and its
methods any time that it communicates with an external database.
The Data Transfer for Xstore Project

The DTX Project creates the file dtv-dtx.jar. This Java archive contains the files that
bind the data in Xstore Point of Service to the data models created by the data2 Project.
Business logic can then operate on an object to access the Xstore Point of Service
database.
Data Models and Data Objects

The DTX Project manages data through data models and data objects. Each data model
represents a database table and each data object, created using the data model as a
template, contains a record from that table.
Creating Data Transfer for Xstore-Based Data Models for Other Projects
If you need to create data models for other Projects that also use DTX configuration files,
the following sample XML statements from build.xml can be a useful template. The
file build.xml is in the root of the DTX project in SVN (Subversion). Edit the
parameters to indicate the source folders for your new Project.
<target name="generation" depends="-init">
<taskdef classpathref="libs" name="dao-generation"
classname="dtv.data2.access.impl.daogen.DAOGenAnt"/>
<dao-generation dest="${gen}" dir="${config}"
modeldir="${src}"
genmodels="false">
</target>

Auto-Generating the Data Model Classes

This section describes the DAOGen process. This process generates data model classes
for DTX.
Process Overview
The DTX Framework automatically generates six classes which are used to work with
data objects. These classes are generated at build time, and must be created before the
DTX Framework can use them. In the data2 Project (dtv-data2.jar) there is a method
named dtv.data2.access.impl.daogen.DAOGen. It processes two XML-style
configuration files and creates the classes from which the data objects are derived.
Creating the Model Classes With DAOGen

For developers, the files that create the model classes and the dtv-dtx.jar are in the
DTX repository in SVN (Subversion). The model classes are automatically generated by
running DAOGen as an Ant task. The Ant task is invoked using parameters in a
build.xml file and processes files with extensions of .dtx and .dtj (see Data Transfer
for Xstore File Layout below, and “Data Transfer for Java Files” for the layout of these
files).
Note: The fully-qualified name of DAOGenAnt is

dtv.data2.access.impl.daogen.DAOGenAnt; it extends
org.apache.tools.ant.Task. The logic in DAOGenAnt instantiates and
runs the logic in DAOGen.
Working With Data Model Configuration Files: Data Transfer for Xstore
and Data Transfer for Java
To create the data models, DAOGen processes two types of configuration files from the
DTX Project: DTX files and Data Transfer for Java (DTJ) files:
• A DTX file has the file extension .dtx and it defines the fields that are included in a
data model. This file also defines the relationships between columns in a database
table and fields in other data models.
• A DTJ file has the file extension .dtj and it contains any special Java code that must
be added to the generated data model.

Data Transfer for Xstore File Layout

Every DTX source file has two major section tags: a DAO section and a Relationship
section:
• The <DAO> section contains the <field> elements that define the associations
between data model properties and database fields.
• The <Relationship> section defines the relationships between different data
model properties.
The sections of a DTX file are outlined below. Detailed descriptions of each section are
found on the following pages.
<DAO> Element:
name Attribute
package Attribute
table Attribute
implements Attribute
code Attribute
extensible Attribute
extends Attribute
model-generator Attribute
<Field> Element:
name Attribute
column Attribute
type Attribute
key Attribute
export Attribute
incrementField Attribute
defaultValue Attribute
suppress-event Attribute
<Relationship> Element:
name Attribute
type Attribute
child Attribute
export Attribute
table Attribute
element-name Attribute
dependent Attribute
useParentPm Attribute

<Field> Element:
parent Attribute
child Attribute
value Attribute
xref-field Attribute
export Attribute
shared Attribute
<InverseRelationship> Element:
name Attribute
parent Attribute
Sample Data Transfer for Xstore Source File

The .dtx source file below for “AwardAccount” shows many of the attributes that may be
used in the <DAO> and <Relationship> sections. The fields that are included in the
data model are listed, as well as the relationships between columns in this table and
other tables.
<DAOMapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../../../../../data2/config/
dtv/res/config/xmlschema/dtx.xsd">
<DAO name="AwardAccount" package="dtv.xst.dao.cat"
table="cat_award_acct"
implements="dtv.xst.dao.cat.IAwardAccountModel">

<field name="organizationId" column="organization_id"
type="Long" key="true"/>
<field name="cardNumber" column="cust_card_nbr"
type="String" key="true"/>
<field name="accountId" column="acct_id" type="String"
key="true"/>

<field name="createDate" column="create_date" type="Date"
export="false"/>
<field name="createUserId" column="create_user_id"
type="String" export="false"/>
<field name="updateDate" column="update_date" type="Date"
export="false"/>
<field name="updateUserId" column="update_user_id"
type="String" export="false"/>

</DAO>


The Data Transfer for Xstore File: <DAO> Element Attributes
<InverseRelationship name="parentCard"
parent="CustomerLoyaltyCard"/>
<Relationship name="awardCoupons" type="One-Many"
child="AwardAccountCoupon">
<field parent="organizationId" child="organizationId"/>
<field parent="cardNumber" child="cardNumber"/>
<field parent="accountId" child="accountId"/>
</Relationship>
</DAOMapping>
Developer Guidelines for Manually Created Interfaces

• A manually created interface must extend dtv.data2.access.IDataModel.
• Only method signatures (declarations) that are not auto-generated should appear in
the interface.
• The implementation of these methods must appear in the DTJ file. The DTJ file is
explained later in this document.
• Standard naming conventions should be used. For Xstore Point of Service, the
interface is stored in the same package as the value in the “package” attribute. See
“The Data Transfer for Xstore File: <DAO> Element Attributes”.
These rules should be followed when naming an interface:
- The interface name starts with an “I” (capital letter I).
- The letter “I” is followed by the value in the “name” attribute.
- The name attribute is followed by the word “Model”. In the example for the
“Party” model, the interface would be named
dtv.xst.dao.crm.IPartyModel.
• The fully-qualified name for the manually created interface should appear in the
implements attribute in the DTX file. See The Data Transfer for Xstore File: <DAO>
Element Attributes below.
The Data Transfer for Xstore File: <DAO> Element Attributes

Each DTX File has a <DAO> tag that identifies the “Data Access Object” section of the file.
This section lists the properties of a data model that are set by the attributes of the <DAO>
tag.
• name - This attribute defines the name of the data model. This name is recorded in
the names of the auto-generated classes. Therefore, it is important to pick a name
that makes logical sense.
• package - This attribute identifies the name of the package that contains the auto-
generated classes. All of the classes are in this package, or in a subclass in an “Impl”
package.
• table - This attribute lists the name of the database table to which the model
corresponds.
• implements - This attribute indicates the interface that is implemented by the data
model. If the data model does not contain any non-generated methods, this should
be set to the default interface, dtv.data2.access.IDataModel.

The Data Transfer for Xstore File: <DAO> <field> Element Attributes
If this data model implements additional methods, those method signatures (or
declarations) must appear in an additional, manually-created interface. This
additional interface must be stored in the Project that contains the data models (see
“Projects”). For example, the DTX Project contains all of the data models for Xstore
Point of Service.
• code - If this attribute is present, and it is set to “true”, the data model represents a
code. Access to additional methods is available in the auto-generated data model.
• extensible - If this attribute is present, and it is set to “true”, the data model that
is auto-generated may be extended by other data models.
• extends - If the data model is an extension of another data model, the name of the
parent data model is indicated by this attribute.
Generally, only the name of the parent data model appears in this attribute. The
parent data model's package should not be assigned in this attribute, unless it is
generated outside of the main DTX project.
If the data model does not extend another data model, the extends attribute should
not be included.
• model-generator - If this attribute is present, it determines the custom class used
to generate the data model.
The Data Transfer for Xstore File: <DAO> <field> Element

Attributes
Within the <DAO> element, there is one <field> tag for every property/database field
combination. Ideally, each database field should have its own property in the data
model.
Each <field> tag may contain several attributes used by DAOGen when it builds the
data models. In addition to attributes, any text contained between the <field> and </
field> tags will be inserted into the auto-generated Javadoc comments in the model's
interface.
• name - This attribute contains the name that is assigned to this property in the data
model. Standard Java “getters” and “setters” are auto-generated based on the value
of this attribute. For example, if this attribute is called partyId, then the “getter”
and “setter” will be named getPartyId() and setPartyId() respectively.
• column - The name of the database column assigned to the property is defined by
this attribute.
• type - This attribute specifies the data type that is assigned to the property/database
column. The type attribute must have one of the following values:
- String
- Date
- Integer
- Long
- BigDecimal
- Boolean
- Object (i.e. a “Blob”, binary large object)
- Clob (character large object)

The Data Transfer for Xstore File: <DAO> <field> Element Attributes
- Class - The data model's class name is recorded in this field. This is useful
when a database row has a field indicating which subclass to use. An example is
the itm_item.dtv_class_name field in the Xstore Point of Service database,
where there are different kinds of items such as physical, non-physical, and
work orders.
• key - The key attribute indicates if the field is part of the primary key. This attribute
must be present and set to “true” to include this field in the primary key.
• export - If this attribute is not present, or is present and set to “true”, the “getters”
and “setters” are included in the code generated from the DTX file. This is typically
done if additional tasks must be performed before “getting” or “setting” a property.
The alternative “getters” and “setters” appear in the DTJ file. If this attribute is
present and set to “false”, the code is not included.
• incrementField - This attribute is included when updates to the database are to
be performed using the data model. If the incrementField attribute is present
and set to “true”, the DTX Framework determines the difference between the
original and current value when an UPDATE query is run for the data model. The
difference is passed into the UPDATE query's parameters.
The UPDATE query then performs the update using syntax like that shown in the
following example:
UPDATE tsn_session_tndr SET create_date = ?, create_user_id = ?,
update_date = ?, update_user_id = ?, actual_media_amt =
actual_media_amt + ?, actual_media_count = actual_media_count + ?
WHERE organization_id = ? AND rtl_loc_id = ? AND session_id = ?
AND tndr_id = ?
In this example, the actual_media_amt and actual_media_count fields are
not simply overwritten. Instead, the amount that represents the difference between
them is passed in, and the query updates the value using that difference.
Note: This is useful if there are multiple instances of the same

application that may update the same fields at the same time. For
example, in the Xstore Point of Service application, multiple registers
may update the Store Bank Session (session #0) at the same time. If this
happens, it is important to increase the actual_media_amt and
actual_media_count fields by the adjustment amount at each
register. This avoids a situation where adjustments to one register
might be overwritten by adjustments from a different register.
• defaultValue - When reading in a row from the database, if a field is set to “null”,
then the value assigned to this attribute is recorded in the data model property.
• suppress-event - If true, causes events to not be posted to the rest of the
application when the field is modified.
• sensitive - If true, data in this field will not be included in log files.
• encrypt - The name of an encryption key. If this attribute is set, the data in the
database field will be encrypted using the named encrypted key.

The Data Transfer for Xstore File: <Relationship> Element Attributes
The Data Transfer for Xstore File: <Relationship> Element

Attributes
Data models often have relationships between their own fields and fields in other data
models. The purpose of these relationships is to enable access to relevant, related data
that is stored in multiple tables.
Three types of relationships may exist between data models:
• One-One: one parent column in one table is related to one child column in a second
table.
• One-Many: one parent column in one table is related to child columns in several
different tables.
• Many-Many: a parent column may be related to child columns in several different
tables and a child column may be related to parent columns in several different
tables. A cross-reference table is used to access all of the child columns from the
second table that are related to the parent columns in the first table.
The structure of the <Relationship> section may vary, depending on the type of
relationship being configured.
The <Relationship> element contains <field> sub-elements that further define the
data relationships. See “The Data Transfer for Xstore File: <Relationship> <Field>
Element Attributes” for more information.
Loading and Persisting Data Models

A data model and all of its children and relationships are loaded simultaneously.
Likewise, when a data model is persisted, all of its relationships and children are also
persisted.
Persisting data includes inserting new rows into a table, updating existing rows in a
table, and deleting existing rows in a table.
Note: Data is rarely deleted via Xstore Point of Service. Obsolete

records are instead marked as “void”.
The DTX Framework does not offer “lazy loading”, in which the child columns are
loaded only when they are needed. Nor does the DTX Framework persist a parent
column without persisting its children. Because of this, the overhead resources required
for relationships have the potential to become prohibitively large. Be careful when
assigning relationships to data models.
Note: In an inverse relationship (see “The Data Transfer for Xstore

File: <InverseRelationship> Element Attributes”), a parent data model
is not automatically loaded or persisted along with the child.
One-One Relationships Between Data Models

A One-One relationship between columns in different data models includes the
following attributes in the <Relationship> tag:
• name - The name of the relationship.
• type - The type of relationship. In this case, it is set to “One-One”.

The Data Transfer for Xstore File: <Relationship> Element Attributes
• child - The name of the child data model. The child’s package does not appear in
this attribute.
• export - Indicates whether the methods to access the relationship on the parent
object are made available in the generated code. If this attribute is present and it is
set to “false”, then the methods that permit access to the relationship will not be
available in the data model’s interface. Defaults to “true” if not specified.
• dependent - When true, the child object is meaningless without the parent object.
• useParentPm - When true, use the same lookup rules as the parent object.
A sample One-One relationship from a DTX file is shown below.
<Relationship name="privilege" type="One-One"
child="Privilege">
<field parent="privilegeType" child="privilegeType"/>
</Relationship>
One-Many Relationships Between Data Models

The structure for One-Many relationships is like the structure for One-One relationships
with one difference: the type attribute in the <Relationship> tag must be set to
“One-Many”.
A One-Many relationship between columns in different data models includes the
following attributes in the <Relationship> tag:
• type - The type of relationship. In this case, it is set to “One-Many”.
this attribute.
A sample One-Many relationship from a DTX file is shown below.
<Relationship name="compatibleDiscounts" type="One-Many"
child="DiscountCompatability">
<field parent="discountCode" child="primaryDiscountCode"/>
</Relationship>
Many-Many Relationships Between Data Models

The structure for Many-Many relationships differs somewhat from One-One and One-
Many relationships. The <Relationship> tag includes the following attributes:
• type - The type of relationship. In this case, it is set to “Many-Many”.
this attribute.

The Data Transfer for Xstore File: <Relationship> <Field> Element Attributes
• table - The mapping table that is used to link the parent object and the child object.
Note that the mapping table does not need a data model object.
• element-name - The name used in the code for a relationship with a child object.
When a parent has multiple Many-Many relationships with children of the same
type, this element differentiates the relationships in the generated code.
The <field> tags for a Many-Many relationship fall into two categories. The first
category links the parent to the mapping table. The second category links the
mapping table to the child. The attributes assigned to each <field> tag may vary,
depending on the tag’s category. For more information on <field> tags, see “The
Data Transfer for Xstore File: <Relationship> <Field> Element Attributes”.
A sample Many-Many relationship from a DTX file is shown below.
<Relationship name="includedItems" type="Many-Many" child="Item"
table="dsc_discount_item_inclusions" element-name="includeItem">
<field parent="discountCode" xref-field="discount_code"/>
<field parent="organizationId" xref-field="organization_id"/>
<field xref-field="organization_id" child="organizationId"/>
<field xref-field="item_id" child="itemId"/>
</Relationship>
The Data Transfer for Xstore File: <Relationship> <Field>

Element Attributes
There must be one <field> tag for each property linking the parent data model to the
child data model. The structure of the <Relationship> section may vary, depending
on the type of relationship being configured.
Parent-to-Child Fields
If the mapping is for a One-One relationship (see “One-One Relationships Between Data
Models”) or a One-Many relationship (see “One-Many Relationships Between Data
Models”), the <field> tag maps the parent to a child. In this relationship, the field tag
may have the following attributes:
• parent - The name of the property in the parent data model. Note that the parent
data model is the DTX file currently being edited.
• child - The name of the corresponding property in the child data model.
Parent-to-Xref Fields
If the mapping is for a Many-Many relationship (see “Many-Many Relationships
Between Data Models”), a <field> tag is used to map the parent to the mapping table.
In this relationship, the <field> tag has the following attributes:
• parent - The name of the property in the parent data model. Note that the parent
data model is the DTX file currently being edited.

The Data Transfer for Xstore File: <InverseRelationship> Element Attributes
• xref-field - The name of the corresponding database column in the mapping

table. Note that, unlike the parent attribute, the xref-field contains a database
column, not a data model property.
Xref-To-Child Fields
If the mapping is for a Many-Many relationship (see “Many-Many Relationships
Between Data Models”), a <field> tag is used to map the mapping table to the child. In
this relationship, the <field> tag has the following attributes:
• xref-field - The name of the corresponding database column in the mapping
table. Note that, unlike the child attribute, the xref-field contains a database
column, not a data model property.
• child - The name of the corresponding property in the child data model.
The Data Transfer for Xstore File: <InverseRelationship>

Element Attributes
Inverse Relationships are used when the DTX file needs to define a relationship to a
parent data model. Inverse relationships are generally used to create a reference back to
the parent in a One-Many relationship.
Typically, the parent's DTX file defines the relationship to the child. By using an
<InverseRelationship> tag, the child data model can refer back to a parent without
creating a circular reference.
While the DTX Framework does support circular references, their use is discouraged.
Unless the circular reference is absolutely necessary, the <InverseRelationship>
should be used to refer a child back to its parent.
When a child is loaded, the parent is not automatically loaded at the same time. It is
assumed that the client application will assign the parent. Likewise, if the child is
persisted, then the parent will not be persisted. It is assumed that the client application
will persist the parent if it is necessary.
An InverseRelationship has the following attributes:
• parent - The name of the parent data model. The parent’s package does not appear
in this attribute.
A sample inverse relationship in a DTX file is shown below.
<InverseRelationship name="parentCard"
parent="CustomerLoyaltyCard"/>

The Data Transfer for Java File: Providing Additional Java

Code to the Data Model
This section provides a detailed description of the functions performed by DTJ files in
generating data models. This includes examples of code in various DTJ files.
Data Transfer for Java Files

The DTJ file is a text file that contains additional Java code. When DAOGen auto-
generates the data models, it appends the contents of this file at the end of the data
model. This gives Xstore Point of Service the ability to record non-generated code in the
data model. This is useful if the client application is to perform additional functionality
in the data models, such as performing calculations.
An example of a DTJ file is shown below. Note that it simply contains various Java
methods.
public java.math.BigDecimal getExtendedAmount() {
return (getAmount() != null) ?
getAmount().multiply(getParentLineItem().getQuantity())
: dtv.util.NumberUtils.ZERO;
}
public String getDisplayDescription() {

if (getDescription() != null) {
return getDescription();
}
else {
return getDiscount().getDescription();
}
}
public java.math.BigDecimal getPercentForRcpt() {

java.math.BigDecimal displayPercent = new
java.math.BigDecimal(0);
displayPercent = getAmount().multiply(new
java.math.BigDecimal(100));
return displayPercent;
}
The DTJ file must be in the same location as its corresponding DTX file. Other than the
extension, both filenames must be identical.
When the data model is auto-generated, the commented text shown below appears in
the data model before the logic from the DTJ file. These comments help the developer
recognize where the auto-generated code ends and the DTJ code begins.

/* * * * * * * * * * * * * * * * * * * * * * * * * * * **/
/* * WARNING WARNING WARNING WARNING WARNING WARNING * */
/* * * */
/* * CUSTOM CODE BELOW THIS POINT. EDIT IN APPROPRIATE DTJ * */
/* * * */
/* * WARNING WARNING WARNING WARNING WARNING WARNING * */
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
Overriding Auto-Generated Methods

Sometimes the client application may need to run specific code in the data model before
it runs the auto-generated code. However, the client application may also need to use the
auto-generated method's signature. These requirements are met by overriding auto-
generated methods.
To override an auto-generated method, write the new method in the DTJ code that
overrides the old method, with the following comment added before the code:
/*
* {OVERRIDE GENERATED METHOD}
*/
When DAOGen sees this comment, it looks for the auto-generated method with the
same method signature. DAOGen then changes the auto-generated method’s scope to
“protected” and appends the word Impl to the end of the method name. The method in
the DTJ file is then appended to the end of the data model.
Note: Manually-written code should always call the auto-generated

method when it is ready to assign an object to a relationship. To call the
auto-generated code from the manually-written code in the DTJ file,
call the method by its new name.
Example of an Override
Assume that DAOGen auto-generated a method with the following signature:
public void addTransactionNotes(dtv.xst.dao.trn.ITransactionNotes
argNote)
However, the client application sets the noteSequence property in the
dtv.xst.dao.trn.ITransactionNotes object before performing this addition.
Therefore, the developer writes another method with the same signature in the DTJ file,
as in the following example:
/* {OVERRIDE GENERATED METHOD} */
public void addTransactionNotes(dtv.xst.dao.trn.ITransactionNotes
argNote) {
argNote.setNoteSequence(this.getTransactionNotes().size() + 1);
addTransactionNotesImpl(argNote);
When DAOGen sees this comment, it looks for the auto-generated public void
addTransactionNotes(dtv.xst.dao.trn.ITransactionNotes argNote)

Introduction to the Data Model Classes
method signature. Then it changes the auto-generated method's scope to “protected”

and adds the word Impl to the end of the method name. The new signature for the auto-
generated method is:
protected void
addTransactionNotesImpl(dtv.xst.dao.trn.ITransactionNotes
argNote)
Note that the method in the DTJ is calling addTransactionNotesImpl(argNote).
This executes the auto-generated logic that adds the ITransactionNotes object to the
relationship.

When DAOGen processes the DTX and DTJ configuration files, it generates six classes
from which the data model objects are derived. At build time, the six classes are stored in
the dtv-dtx.jar file. Each of the six classes has its own standard naming convention.
Table 4-1: Data Model Naming Conventions
Class Naming Convention
Object ID Name is derived from the id attribute in the DTX file immediately
followed by “Id”
Model Interface “I” is always the first letter, followed by name of the data model
DBA Class Name is the same as the name of the data model, followed by “DBA”
DAO Class Name is the same as the name of the data model, followed by
“DAO”
Model Class The assigned name of the class followed by the word “Model”
Relationship Class The name of the data model, followed by the name of the
relationship, followed by “RelationshipDBA”
The table below provides an overview of the six data model classes. More details about
each of them are provided in the following pages.
Table 4-2: Data Model Classes
Class Brief Description Sample Item: “Item”
Object ID Contains all of the properties that ItemId.class

make up the primary key for a
model.
Model Interface The method signatures, or IItemModel.class

declarations, for all auto-generated
methods in the model class.
DBA Class Contains the SQL queries used when ItemDBA.class

Xstore Point of Service wants to
perform a query against a data
source; has one property for every
<Field> tag in the corresponding
DTX file.

Table 4-2: Data Model Classes (continued)
Class Brief Description Sample Item: “Item”
DAO Class Provides “getter” and “setter” ItemDAO.class

methods for all properties specified
in <field> tags in DTX file.
Model Class The class used by Xstore Point of ItemModel.class

Service; “getters” and “setters” in the
model class directly call the DAO
model class’s “getters” and “setters”.
Relationship Class One relationship class created for ItemParentItemRelationshipDBA

every relationship specified in the .class
DTX file; contains the SELECT query
needed to load the model’s children.
Two “overhead” classes are also automatically created at the same time as the six model
classes. These two classes are used in the persistence process when the data models are
loaded.
Table 4-3: Auto-Generated Overhead Classes
Overhead Class Fully-Qualified Name Description
DataModelFactoryImpl dtv.data2.access.impl.DataModelFactory Methods for loading

Impl data models
JDBCAdapterMapImpl dtv.data2.access.impl.jdbc.JDBCAdapter Methods for loading

MapImpl data models
The Object ID Class

The Object ID class contains all of the properties that make up the primary key for a data
model. All of the <field> tags in the DTX file that have their key attribute set to “true”
are included in the Object ID class.
Each property has a standard Java “getter” and “setter” method.
Auto-generated implementations of the equals(), hashCode(), and toString()
methods are also included in the Object ID class.
The auto-generated toString() method returns the values of each property in a single
String. Each value is separated by a “::” sequence. The example below shows how it
works:
dtv.xst.dao.crm.PartyId has two properties with the following values:
* organizationId = 1
* partyId = 27000100000073
The toString() method returns the following String: "1::27000100000073".
Note: Order is critical. The order in which values are listed in the
String must match the order of the <field> tags in the DTX file.
This class extends the abstract dtv.data2.access.AbstractObjectId superclass.

The ID is derived from the DTX name and package.

The Model Interface Class

This section provides a description of the Model Interface class and the interface
extension.
General Overview
The Model Interface class contains the method signatures (or declarations) for all of the
auto-generated methods in the Model class (see The Model Class).
The auto-generated interface is in the package specified in the package attribute in the
DTX file.
Interface Extension
The auto-generated interface extends the interface that is specified in the implements
attribute in the DTX file.
If there are no additional manually created methods for the data model (in the DTJ file),
the implements attribute should be set to dtv.data2.access.IDataModel.
If there are additional manually created methods in the DTJ file, those method
signatures should appear in a manually created interface. The implements attribute in
the DTX file should contain the name of this manually created interface. This causes the
auto-generated interface to extend the manually generated interface.
The following rules should be followed for manually created interfaces:
• The manually created interface must always extend
dtv.data2.access.IDataModel.
• If the data model extends another data model, the manually created interface should
extend the parent model's auto-generated interface.
• Other interfaces may also be extended. For example, in the Xstore Point of Service
application, some manually created interfaces extend
dtv.data2.access.ICodeInterface.
• By convention, the manually created interface should reside in the same package as
the auto-generated interface.
• The name of the manually created interface should start with an “I”, followed by the
name of the Data Model, followed by the word “Model”. For example, if the data
model's name is Party, then the manually created interface should be named
IPartyModel.
• Manually created interfaces should be stored in the src folder of the DTX Project for
Xstore Point of Service. Auto-generated interfaces are stored in the gen folder of the
DTX Project.
• Manually created interfaces for future projects should be stored in a different folder
from the auto-generated interfaces.

The DBA Model Class

The DBA class contains the various SELECT, INSERT, UPDATE, and DELETE queries for
the data model. These queries are used whenever the client application performs an
operation against a JDBC data source.
This class has one property for every <field> tag in the DTX file. However, the
standard Java “getter” and “setter” methods are not auto-generated.
The client application never communicates directly with the DBA class.
The DBA Model resides in the impl package. The value in the package attribute in the
DTX file is retrieved, and an additional package level of impl is added to the retrieved
value. The DBA class will be in this package. For example, if the package attribute is set
to dtv.xst.dao.crm, the DBA class will be in the dtv.xst.dao.crm.impl
package.
The name of the DBA class is composed of the Data Model name, followed by the letters
“DBA”. For example, if the Data Model name is Party, the DBA class will be named
PartyDBA.
The DBA class implements the
dtv.data2.access.impl.jdbc.IJDBCTableAdapter interface.
The DAO Model Class

The DAO class provides “getter” and “setter” methods for all of the properties specified
in the <field> tags in the DTX file.
The properties in the DAO class are populated by the DBA class when operations are
performed on a JDBC data source. As with the DBA class, the DAO class is in the impl
package.
The client application never communicates directly with the DAO class.
The name of the DAO class is composed of the name of the data model followed by the
letters “DAO”. For example, if the Data Model's name is Party, then the DAO class will
be named PartyDAO.
The DAO class extends the dtv.data2.access.impl.AbstractDAOImpl abstract
superclass.
The Model Class

The Model class is used by the client application via the Model Interface Class. Like the
DBA and DAO classes, the Model class is in the impl package.
The name of the Model class is composed of the name of the data model followed by the
word “Model”. For example, if the Data Model's name is Party, then the DBA class is
named PartyModel.
Each Model has a private transient dtv.event.Eventor object. This gives the client
application the ability to register “listeners” with various properties or relationships.
When the properties or relationships are modified, the appropriate events then occur.
The model always implements the interface that is specified in the implements
attribute in the DTX file. The model also implements the
dtv.data2.access.IHasObjectId interface.
Each method in the Model can be placed into one of the following four categories:
• Property “Getters” and “Setters”
• Relationship Access Methods

• Manually Created Methods
Property “Getters” and “Setters”

Standard Java “getters” and “setters” are auto-generated for all of the properties in the
DAO file. All of the Model's “getters” and “setters” directly call the underlying DAO
class's “getters” and “setters”. None of the property values are stored in the Model itself.
Relationship Access Methods

The Model contains auto-generated access methods for the relationships that are
specified in the data model DTX configuration files. A “getter” and “setter” method is
always provided. For ONE-MANY and MANY-MANY relationships, “add”, “set list”
and “remove” methods may also be auto-generated.
Manually Created Methods

Manually created methods are read in from the DTJ configuration file. The client
application has the ability to override auto-generated methods with manually created
ones (see “Overriding Auto-Generated Methods”).
Extensions
The Model Class always extends a superclass. DAOGen follows these steps to determine
which superclass to extend:
• The value in the extends attribute in the DTX file is checked. This attribute is used
when a Data Model is an extension of another Data Model. If the extends attribute
in the DTX file has a value, the Model will extend the class specified in this attribute.
• If the DTX file has its has-properties attribute set to “true”, the model extends
dtv.data2.access.impl.AbstractDataModelWithPropertyImpl.
• If the code attribute in the DTX file is set to “true”, the Model extends
dtv.data2.access.impl.AbstractCodeImpl.
• If none of the first three conditions are satisfied, the Model extends
dtv.data2.access.impl.AbstractDataModelImpl, which is the default
abstract superclass. Most models extend this class.
The Relationship Class

A Relationship class is created for every relationship that is defined in the DTX file. This
class contains the SELECT query that is needed to load children of the data model.
Like the DAO, DBA, and Model classes, the Relationship class is in the impl package.
The name of the Relationship class consists of several parts. The class name begins with
the name of the data model. The data model name is followed by the name of the
relationship. The class names ends with “RelationshipDBA”. For example, if the
Party data model has a relationship named customerGroups, then the class will be
named PartyCustomerGroupsRelationshipDBA.
The Relationship Class implements the
dtv.data2.access.impl.jdbc.IJDBCRelationshipAdapter interface.
Overhead Classes
Two additional classes are auto-generated by DAOGen. These two classes are used
during the Persistence process when loading the data models. The client application
should never have to use these classes directly.

Data Transfer for Xstore Data Management
DataModelFactoryImpl
The dtv.data2.access.impl.DataModelFactoryImpl class contains three
methods that are used when loading Data Models:
• getRelationshipsImpl() – This method returns the Relationship classes for a
given DAO class.
• getModelForDAOImpl() – This method returns the Model for a given DAO class.
• getModelForInterface() – This method returns the Model for a given auto-
generated interface.
JDBCAdapterMapImpl
The dtv.data2.access.impl.jdbc.JDBCAdapterMapImpl class also contains
three methods that are used when loading Data Models:
• getTableAdapterImpl() – This includes two method signatures:
- One accepts the ID Object.
- The other accepts a Class object.
However, regardless of which one is called, they both return the DBA class for the
Object or Class passed in. If a Class is passed in, it must represent a DAO, Object ID,
or auto-generated interface.
• getRelationshipAdapterImpl() – This method returns the Relationship class
for a given Class and relationship name. The Class object must represent a DAO
Object.

Before DTX can begin working with data models, the data for those models must be
retrieved from the sources where it is stored. And, once new data has been created, it
must be persisted back to the data sources where the information is stored. These data
operations are managed through configuration files that DTX uses to determine where
the data is found and where it is sent.
Data Sources
For data to be persisted, replicated, or retrieved, DTX must know where and how to
open the source(s) where the data will be read and/or written. This information is
configured in the DataSourceConfig.xml file, which provides technical information
about the data sources used by DTX.
Note: See Chapter 5, “Data Sources” for more information about data
sources and configuring access to them through the
DataSourceConfig.xml file.
Persistence Managers
Every data model must be associated with a Persistence Manager Type (a “PM Type”)
and every PM Type is associated with a data source. These two associations ensure that
each type of data (as defined by its model) is stored in the proper data source location,
since data can be stored in various places, depending upon business or other
requirements.
Persistence Managers are configured in two files:

• PMTypeMappingConfig.xml - If the data being handled is based on a data model,

this configuration file is used to associate the model with a PM Type.
• PersistenceManagerConfig.xml - This configuration file associates a PM Type
with a data source.
Note: Chapter 6, “Persistence Mapping Configuration” for more

information about Persistence Mapping and the files
PMTypeMappingConfig.xml and
PersistenceManagerConfig.xml.
Data Replication
Data replication is part of the DTX Persistence Framework. Data must be persisted to a
data source before it can be replicated. As data is persisted, it is offered to the replication
framework for examination. Based on configuration, data may be replicated to any
number of other destinations, depending on what conditions are present. For example,
data may be conditionally persisted based on the type of data and the data source that is
targeted.
Replication can be configured to meet diverse needs. For example, replication can be
used to ensure that all store data is persisted to a central database, even when availability
of that data source is limited. Replication can also be configured to keep certain
databases synchronized with each other, or to ensure that all data generated by a register
is available on the local database as well as the central database.
Depending on configuration, delivery of replication data can be “guaranteed”. If some
data cannot be replicated immediately upon request, the replication framework will
queue up that data in its local data store for later delivery. Optionally, expiration times
can be specified on a guaranteed delivery. The replication queue features a “relegation”
strategy that tracks the number of attempts to replicate a piece of data and will gradually
retry replication less frequently as its failure count rises. The number of replication
attempts and the failure count values are configurable.
Note: See Chapter 7, “Replication Configuration” for more

information about Data Replication and the
Queries and Object Wrapping

When the Xstore Point of Service application needs to return data in the form of a
“wrapped object” rather than a data model, DTX uses the QueryConfig.xml file to
build a database query. The wrapped object returns the data in a way that the database
interface is hidden from the client application (i.e. Xstore Point of Service) that receives
the retrieved data.
Wrapped objects may be necessary for a variety of reasons; but they are commonly
implemented when two classes have incompatible interfaces. Also, by using a query, the
returned data can be filtered to retrieve only the data that is actually needed, rather than
all the data available in all the rows and columns in the database table(s).
Note: See Chapter 8, “Query Configuration” for more information

about queries and the QueryConfig.xml file.


5
Data Sources
Overview
Data sources are configured in the DTX Framework through the file
DataSourceConfig.xml. For a data source to be available to Xstore Point of Service
for persisting, retrieving, replicating, or backing up data, the data source must be
configured in the DataSourceConfig.xml file.
Each data source has a number of crucial parameters, including:
• A unique name.
• Whether it should be considered enabled at runtime.
• If necessary, a URL defining the location of the data source.
• If necessary, a network scope to determine the color of the database availability
indicator when the data source goes offline.
• The strategy defining the protocol by which object-to-database interactions (and vice
versa) are performed.
• If necessary, a set of key-value pairs parameterizing the strategy and/or connection.
• If necessary, a datasource ping by which a data source is considered to be online or
offline.
Data sources are not referenced programmatically, they are instead identified by one or
more persistence managers.
About this Chapter

• DataSourceConfig.xml File describes the elements and attributes for the
• DataSourceConfig.xml Example: shows sample xml from a
DataSourceConfig.xml File
This section describes the elements and attributes for the DataSourceConfig.xml file,
which configures data sources for the DTX Framework. The file has the following
organization:
<DataSourceSet> Element:
xmlns:xsi Attribute
Data Sources 5-1

<DataSource> Element:
name Attribute
HighAvailability Attribute
<Enabled> Element
<NetworkScope> Element
<Strategy> Element
<Property> Element:
key Attribute
value Attribute
<value> Element:
dtype Attribute
cipher Attribute
encrypted Attribute
<Ping> Element:
<ClassName> Element:
dtype Attribute
<Property> Element:
key Attribute
value Attribute
• <DataSourceSet> - (ROOT ELEMENT) The element containing the set of all Data
Sources configured in the DataSourceConfig.xml file. This element contains as
many <DataSource> elements as necessary. This element contains the following
attributes:
with the XML file.
• <DataSource> - This element defines a data source that is available to Xstore Point
of Service. Each <DataSource> element contains attributes and sub-elements that
describe how the application accesses the data source. This element has the
following attributes:
- name - Contains the name of the data source.
- enabled - This element indicates whether the data source may be accessed.
This element has the following possible values:
Note: This attribute can be used instead of the <Enabled> element.
* true - The data source is available to the application.

* false - The data source is not available to the application and it will not
attempt to contact it.

- strategy - The name of the bean used to implement the persistence strategy
for the data source. There are several strategies available in the DTX Framework,
all of which are part of the DTX Persistence Project.
Note: This attribute can be used instead of the <Strategy> element.
* concurrentWritePersistenceStrategy - Performs remote data

access using a concurrent write strategy.
* jdbcPersistenceStrategy - Directly accesses a DBMS through JDBC.
* servletPersistenceStrategy - Performs remote data access through
DTX.
* loadBalancePersistenceStrategy - Selects from a list of strategies
associated with it.
* operaPersistenceStrategy - Used when communicating with Opera.
* relatePersistenceStrategy - Used when communicating with Relate.
* serenadePersistenceStrategy - Used when communicating with
Serenade.
- networkScope - This element determines the color of the database availability
Note: This attribute can be used instead of the <Strategy> element.
* LAN - Red indicator
* WAN - Yellow indicator
Note: If there are both LAN and WAN data sources offline, the
database indicator turns red.
- highAvailability - This attribute indicates whether the system will be

marked as offline if the application is disconnected from the database. This
attribute is required to be set to “true” in the <DataSource> element for the
replication data source.
This attribute has the following possible values:
* true - The database will not be marked as offline if it is disconnected from
the system. Instead, the application will retry the data source on the next
request and continue to try to access the data source on any following
requests. This setting is used when it would be unusual or unexpected for
the system to lose contact with the database.
* false - (DEFAULT) The database will be marked as offline if it is
disconnected from the system.
Data Sources 5-3

• <Enabled> - This element indicates whether the data source may be accessed. This
element has the following possible values:
Note: This attribute can be used instead of the enabled attribute.
- true - The data source is available to the application.

- false - The data source is not available to the application and it will not
attempt to contact it.
• <NetworkScope> - This element determines the color of the database availability
Note: This attribute can be used instead of the networkScope

attribute.
- LAN - Red indicator
- WAN - Yellow indicator
Note: If there are both LAN and WAN data sources offline, the
database indicator turns red.
• <Strategy> - This element contains the name of the bean used to implement the
persistence strategy for the data source. There are several strategies available in the
DTX Framework, all of which are part of the DTX Persistence Project:
Note: This attribute can be used instead of the strategy attribute.
* concurrentWritePersistenceStrategy - Performs remote data

access using a concurrent write strategy.
* jdbcPersistenceStrategy - Directly accesses a DBMS through JDBC.
* servletPersistenceStrategy - Performs remote data access through
DTX.
* loadBalancePersistenceStrategy - Selects from a list of strategies
associated with it.
* operaPersistenceStrategy - Used when communicating with Opera.
* relatePersistenceStrategy - Used when communicating with Relate.
* serenadePersistenceStrategy - Used when communicating with
Serenade.
• <Property> - Each <Property> element sets a property for the data source; there
can be many <Property> elements within a <DataSource> element. This element

DataSourceConfig.xml Example:
- key - This attribute indicates the property key that is being configured. The
exact property keys that are available may vary, depending on the driver being
used. The four most common keys for JDBC data sources are:
* ConnectionDriverName - The name of the driver.
* ConnectionURL - The data source's connection string.
* ConnectionUserName - The User ID used when making the connection.
* ConnectionPassword - The Password used when making the connection.
- value - This attribute indicates the value assigned to the property key. For a
value that requires encryption, the value is assigned through a <value>
element (see below).
- <value> - This element can be used in place of the value attribute. This element
contains data that has been encrypted (such as User IDs and Passwords). This
element has the following attributes:
* dtype - The type of data contained in the <value> element. The only
possible value for this attribute is “EncryptedString”.
* cipher - The cipher used to encrypt the data.
* encrypted - The encrypted value of the property.
• <Ping> - Defines the rules used when pinging a remote data source.
- <ClassName> - This element contains the name of the class that is used to
perform the ping. This element has the following attribute:
* dtype - Indicates the type of information contained within the element. The
only possible value for this attribute is “Class”.
- <Property> - This element is used to define the network properties of the
location being pinged. This element contains the following attributes:
* key - This attribute indicates the property key that is being configured. The
most common values for this attribute are:
Host - The name of the host server that is being pinged.
Port - The port on the host server that is being pinged.
Timeout - The amount of time, in milliseconds, to wait for a response from
the host server.
* value - This attribute indicates the value assigned to the property key.
<DataSourceSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../../../pos/config/dtv/res/config/
DataSourceConfig.xsd">
<DataSource name="Relate" networkScope="WAN">
<Enabled dtype="Boolean">true</Enabled>
<Strategy dtype="String">relatePersistenceStrategy</Strategy>
<Ping>
<ClassName dtype="Class">dtv.data2.access.impl.SocketPing</
ClassName>
<Property key="Host" value="xxxxxxxxxx"/>
Data Sources 5-5

<Property key="Port" value="xxxx"/>

<Property key="Timeout" value="5000"/>
</Ping>
</DataSource>
...
<DataSource highAvailability="true" name="Replication" networkScope="LAN">
<Enabled dtype="Boolean">true</Enabled>
<Strategy dtype="String">jdbcPersistenceStrategy</Strategy>
<Property key="ConnectionDriverName"
value="com.microsoft.sqlserver.jdbc.SQLServerDriver"/>
<Property key="ConnectionUserName">
<value cipher="config" dtype="EncryptedString"
encrypted="xxxxxxxxxxxxxxxxxxxxxxxxxxx"/>
</Property>
<Property key="ConnectionPassword">
<value cipher="config" dtype="EncryptedString"
encrypted="xxxxxxxxxxxxxxxxxxxxxxxxxxx"/>
</Property>
<Property key="ConnectionURL" value="jdbc:sqlserver://
localhost;databaseName=xstorereplication;sendStringParametersAsUnicode=false"
/>
<Ping>
<ClassName dtype="Class">dtv.data2.access.impl.SocketPing</
ClassName>
<Property key="Host" value="localhost"/>
<Property key="Port" value="xxxx"/>
<Property key="Timeout" value="1000"/>
</Ping>
</DataSource>
...
</DataSourceSet>

6
Persistence Mapping Configuration
Overview
Once the DTX data sources have been configured, DTX must know how Java objects are
mapped to data sources. These mappings are created through two files,
PmTypeMappingConfig.xml and PersistenceManagerConfig.xml.
These two files use Persistence Mapping (PM) Types to map Java objects to data sources.
The file PmTypeMappingConfig.xml maps Java objects to PM Types and the file
PersistenceManagerConfig.xml maps the PM Types to data sources. This allows
several different but related Java objects to be mapped to data sources in the same
manner.
For example, if there are several Java objects related to customer accounts, all of these
Java objects should access the same data sources. By using PM Types, these Java objects
can all be mapped to one PM Type. Then if there are changes to the data sources used for
customer accounts, changes do not need to be made for every Java object. Instead, the
changes can be made only for the one PM Type.
About this Chapter

• PmTypeMappingConfig.xml describes the PmTypeMappingConfig.xml file and
the elements and attributes used to configure the one-to-many relationships between
PM Types and Java objects.
• PersistenceManagerConfig.xml describes the PersistenceManagerConfig.xml
file and the elements and attributes used to configure the relationships between PM
Types and data sources.
Persistence Mapping Configuration 6-1

PmTypeMappingConfig.xml
PmTypeMappingConfig.xml
This file maps Java objects to Persistence Manager (PM) Types. These mappings create
one-to-many relationships between PM Types and Java objects. This organizes the Java
objects into logical, intuitively named groups, and allows multiple Java objects to be
configured to access the same data sources.
<PmTypeMapping> Element:
ObjectId Attribute
PmType Attribute
The following elements and attributes are used in this file:

• <PmTypeMappingSet> - (ROOT ELEMENT) Contains the set of all Persistence
Manager Type mappings. Contains as many <PmTypeMapping> sub-elements as
necessary.
• <PmTypeMapping> - Maps Java objects to PM Types. Each mapping contains the
following attributes:
- ObjectId - The fully-qualified class name of the data model ID object.
- PmType - The PM Type assigned to the data model referenced in the ObjectId
tag.
- LoadProperties - The method used to load property relationships for a given
type.
After the DTX Framework selects a PM Type for the data model, it uses the
PersistenceManagerConfig.xml file to look up the proper data source details.
<PmTypeMappingSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PmTypeMappingConfig.xsd">
<PmTypeMapping ObjectId="dtv.xst.dao.com.TransactionPropertyPromptId"
PmType="REGISTER_CORE"/>
<PmTypeMapping ObjectId="dtv.xst.dao.ctl.EventLogEntryId"
PmType="EVENT_LOG_ENTRY"/>
<PmTypeMapping ObjectId="dtv.xst.dao.cwo.CategoryServiceLocationId"
PmType="CODES"/>
<PmTypeMapping ObjectId="dtv.xst.dao.cwo.InvoiceId" PmType="CUSTOMER_ACCOUNT"/
>
<PmTypeMapping ObjectId="dtv.xst.dao.cwo.InvoiceLineItemId"
PmType="CUSTOMER_ACCOUNT"/>
PersistenceManagerConfig.xml
This configuration file associates a PM Type with a data source defined in the file
DataSourceConfig.xml (see DataSourceConfig.xml File in Chapter 5, “Data Sources”
for more information). Note that the DTX Framework supports multiple data sources.
• <PersistenceManagerTypeSet> - (ROOT ELEMENT) The element containing the
set of all PM types. Contains the <PersistenceManagerType> sub-elements. This
element contains the following attributes:
- xsi:noNamespaceSchemaLocation - The name of the schema .xsd file
associated with the XML file.

• <PersistenceManagerType> - The individual PM Type. Contains the

<Online>, <Offline>, and <Training> sub-elements for the PM Type.
- name - The name of the PM Type. This PM Type is mapped to a Java object in the
file PMTypeMappingConfig.xml (see PmTypeMappingConfig.xml).
- ref - Inheritance mechanism used to inherit all the properties for the specified
ref value.
- sync - When true, allows data to be managed in two places, ensuring both data
sources get an update.
The following outline describes the structure of the <PersistenceManagerType>
elements. Descriptions of each element and attribute follow the outline.
<PersistenceManagerType> Element:
name Attribute
ref Attribute
sync Attribute
<Online> Element:
dtype Attribute
<LookupLocation> Element:
<dataSourceName> Attribute
<PersistenceLocation> Element:
<Offline> Element:
dtype Attribute
<Training> Element:
dtype Attribute
• <Online> - The data source used when Xstore Point of Service is online. It may
contain as many <LookupLocation> and <PersistenceLocation> sub-
elements as necessary.
- dtype - The type of data defined within the element.
• <LookupLocation> - For all elements with this name, this element defines the data
source used when retrieving data. The <Online>, <Offline>, and <Training>
elements all contain a sub-element with this name. For multiple
<LookupLocation> elements, the order in the file is respected.
Persistence Mapping Configuration 6-3

- dataSourceName - This attribute contains the data source that is assigned in

DataSourceConfig.xml.
• <PersistenceLocation> - For all elements with this name, this is the data source
used when persisting data. It contains the dataSourceName attribute which is used
in the same way as within the <LookupLocation> element (see above). For
multiple <LookupLocation> elements, the order in the file is respected.
- dataSourceName - This attribute contains the data source that is assigned in
DataSourceConfig.xml.
• <Offline> - The data source used when Xstore Point of Service is offline. It may
contain as many <LookupLocation> and <PersistenceLocation> sub-
elements as necessary.
• <Training> - The data source used when Xstore Point of Service is being used in
Training mode. It may contain as many <LookupLocation> and
<PersistenceLocation> sub-elements as necessary.
PersistenceManagerConfig.xml Example
<PersistenceManagerType name="EMPLOYEE" ref="STORE_STANDARD" sync="true">
<Online dtype="LocationGroup">
<LookupLocation dataSourceName="StorePrimary"/>
<LookupLocation dataSourceName="Local"/>
<LookupLocation dataSourceName="Xcenter"/>
<PersistenceLocation dataSourceName="StorePrimary"/>
</Online>
</PersistenceManagerType>

7
Replication Configuration
Overview
Xstore Point of Service replication is controlled through two files, system.properties
and DtxReplicationConfig.xml. The file system.properties provides an
option to turn replication on and off, while DtxReplicationConfig.xml is used to
configure the options and data sources used when replication is turned on.
This chapter does not describe the configuration of data sources. However, replication
configuration does use the data sources configured in the file
DataSourceConfig.xml. For more information describing data sources and data
source configuration, see Chapter 5, “Data Sources”.
About This Chapter

• Enabling and Disabling Replication in Xstore Point of Service below describes how
to turn replication on or off through an option in the system.properties file.
• DtxReplicationConfig.xml describes replication configuration in the file
DtxReplicationConfig.xml.
Replication Configuration 7-1

Enabling and Disabling Replication in Xstore Point of Service
Enabling and Disabling Replication in Xstore Point of Service

Data replication’s default state is off. Replication must be turned on in the file
system.properties for it to be available in Xstore Point of Service. If the setting
dtv.data2.replication.enabled does not exist in the system.properties file,
replication is turned off in Xstore Point of Service.
The two supported configuration values are ON and OFF:
dtv.data2.replication.enabled=ON
dtv.data2.replication.enabled=OFF
DtxReplicationConfig.xml
There are two main sections in the DtxReplicationConfig.xml file:
• The first section defines the rules used when retrying a failed replication attempt.
This section uses a <ReplicationQueue> element for each data source (see Queue
Configuration (<ReplicationQueue>)).
• The second section describes the replication services that are provided. The tag
associated with this section is <service> and each service must have a name. The
<service> tag also has a number of sub-elements that provide the details needed
to implement the service (see Replication Services (<service>)).
The file DtxReplicationConfig.xml has the following organization:
<ReplicationQueue> Element:
dataSource Attribute
cycleInterval Attribute
workstationStart1 Attribute
workstationEnd1 Attribute
maxRecsPerCycle Attribute
errorNotificationCycles Attribute
<relegationLevel> Element:
failedAttempts Attribute
retryAfterCycles Attribute

<service> Element:
name Attribute
enabled Attribute
expireAfter Attribute
<condition> Element:
class Attribute
<conditionParam> Element:
key Attribute
value Attribute
<destination> Element:
type Attribute
dataSourceName Attribute
destinationService Attribute
dataSourceList Attribute
<subscriber> Element:
exclude Attribute
name Attribute
1.Supports replication for multiple registers in mobile configura-

tions.
Queue Configuration (<ReplicationQueue>)

The purpose of the <ReplicationQueue> section is to define how “guaranteed
delivery” operates in the queue for a named data source. The elements in the
<ReplicationQueue> section are described below.
• <ReplicationQueue> - This element defines the rules for retrying failed
replication attempts. It includes a <relegationLevel> sub-element for each level
of replication retries. This element includes the following attributes:
- dataSource - This attribute determines which data source is assigned to this
replication queue. The data source must use the JDBCPersistenceStrategy.
(This should be the most stable and available datasource.)
- cycleInterval - This attribute specifies the amount of time (in milliseconds)
that the replication queue daemon thread will “sleep” before doing more work;
i.e. the amount of time between sweeps of the replication queue.
Note: The next cycle cannot fire until the process is idle. For example,
with a 30 second cycle, cycle #2 cannot fire unless the replication
process has been idle for at least a full cycle interval (i.e., 30 seconds).
So if cycle #1 begins at 0:30 and ends at 0:31, cycle #2 will NOT execute
at 1:00 because 30 seconds have not yet elapsed since 0:31. Instead,
cycle #2 will run at 1:30.

- maxRecsPerCycle - This attribute specifies the maximum number of queue

entries that are processed for each cycle.
- errorNotificationCycles - This attribute controls how many cycles must
elapse before an error notification is sent to Xadmin’s event log. Controlling the
frequency at which event log entries for a register's replication queue status are
generated prevents the central database from being flooded with too much data.
• <relegationLevel> - This element specifies how often and how frequently
replication will be attempted when replication fails. Multiple relegation levels may
be established in order to decrease the frequency of attempts as the number of
failures rises. If attempts to replicate continue to fail, the number of additional
attempts are adjusted as each relegation level ends and a new relegation level
begins.
It is recommended that the values for failedAttempts and retryAfterCycles
be increased with each successive relegation level to ensure that data replication will
eventually succeed.
- failedAttempts - The number of failures necessary to move to the next
relegation level in the list. For example: secondary_reg --> primary_reg -->
home_office.
- retryAfterCycles - The number of cycles (a time period defined in the
cycleInterval attribute above) between each retry attempt in the relegation
level.
<ReplicationQueue dataSource="Replication" cycleInterval="30000"

maxRecsPerCycle="50" errorNotificationCycles="60">
<relegationLevel failedAttempts="3" retryAfterCycles="30"/>
</ReplicationQueue>
All replication requests are written to the database table ctl_replication_queue for
processing. After a replication transaction is successful or expires, it is removed from this
table.
Replication Services (<service>)

The <service> elements in the file DtxReplicationConfig.xml describe the
replication services used in replicating data. A replication service is like a log4j logger/
category. A replication service acts on a piece of data when all of the specified conditions
are met.
• <service> - This element defines the replication service. Utilizes the
<condition>, <destination>, and <subscriber> sub-elements to define the
service. This element includes the following attributes:
- name - Unique name for the replication service. It is recommended that you use
a descriptive name for this attribute.
- enabled - Indicates whether the replication service is enabled. Regardless of
any other conditions, replication will not occur unless it is enabled. The default
state is true (service is enabled). If this attribute is set to “false”, the service is
disabled and replication will not occur.

- expireAfter - Defines the amount of elapsed time (in milliseconds) within

which delivery is guaranteed. Values may be the number of milliseconds before
expiration, or one of the following two options:
* never - Stipulates guaranteed delivery, replicate regardless of the time
required.
* immediately - Instructs the replication framework to discard the
replication data if it cannot be immediately replicated. Useful for less critical
data.
• <condition> - This element specifies the conditions that must resolve to “true” as
a requirement for activating this replication service. Contains as many
<conditionParam> sub-elements as necessary. This element includes the
following attribute:
- class - The condition class that must resolve to “true” for the replication
service to be activated. Any implementation of
AbstractReplicationCondition can be used as a condition. This includes
the ability to reflectively inspect the field values in a data object as a condition
for replication.
• <conditionParam> - This element defines any parameters that are sent to the
condition class as part of its processing.
- key - The key used for the condition parameter.
- value - The value to which the key is set.
• <destination> - Defines the target to which the data will be replicated. This is a
data source defined in DataSourceConfig.xml (e.g. JDBC data source, app
server, servlet, etc.) and can be easily expanded to support other types of
destinations for the data.
- type - Indicates the type of destination for the service. The following values are
valid destination type values:
* DataSource - The destination is a data source. The destination element
uses the dataSourceName attribute to determine the name of the data
source used by the service.
* DataSourceList - Multiple data sources are destinations for the service.
The destination element uses the dataSourceList attribute to determine
the names of the data sources used by the service.
Note: Success on any data source constitutes complete success. To

replicate to multiple destinations, MICROS recommends using
multiple services instead of the DataSourceList.
* DataSourceForwarding - Sends replication data to the primary register's

replication log with the intent of that data being replicated to the home
office. Uses the dataSourceName attribute to determine the name of the data
source used by the service and the destinationService attribute to
determine the name of the service used as a destination.
- dataSourceName - The name of the destination data source. Defined in the file
DataSourceConfig.xml. See Chapter 5, “Data Sources” for more
information.

- dataSourceList - A semicolon-separated list of the names of the destination

data sources. Defined in the file DataSourceConfig.xml. See Chapter 5,
“Data Sources” for more information.
- destinationService - The name of the destination service specific to
DataSourceForwarding.
• <subscriber> - Defines the type of data that is eligible for a replication service and
the type of data that is excluded from a service. Subscriber names are hierarchies
similar to log4j. As long as data meets the requirements of any of the subscriber
patterns, the data is eligible or ineligible (if excluded) for replication.
- name - The name of the type of data that is eligible for replication.
- exclude - Indicates whether the data is excluded from replication through this
service. If exclude is set to “true”, the data is excluded from replication. The
default is “false”.
The following examples illustrate some subscriber patterns that may be used to define
types of data that will be replicated:
Replicate only store/register opens and session data:
<subscriber name="dtv.xst.dao.loc"/>
<subscriber name="dtv.xst.dao.tsn"/>
Replicate timecard data, but not timecard journal data:

<subscriber name="dtv.xst.dao.thr.impl.TimecardEntryComment"/>
<subscriber name="dtv.xst.dao.thr.impl.TimecardEntry"/>
<subscriber exclude="true" name="dtv.xst.dao.thr.impl.TimecardJournal"/>
Replicate all data, but not inventory count data:

<subscriber name="dtv.xst.dao" />
<subscriber exclude="true" name="dtv.xst.dao.inv.impl.InventoryCount" />
DtxReplicationConfiguration.xml Sample
The example below shows a sample configuration for data replication.
<DtxReplicationConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="DtxReplicationConfig.xsd">
<ReplicationQueue dataSource="Replication" cycleInterval="30000"
maxRecsPerCycle="50" errorNotificationCycles="60">
</ReplicationQueue>
...
<service name="Local->Xcenter" expireAfter="never">
<condition
class="dtv.data2.replication.dtximpl.condition.CurrentDataSourceCondition">

<conditionParam key="currentDataSource" value="Local" />

</condition>
<destination type="DataSource" dataSourceName="Xcenter" />
<subscriber name="dtv.xst.dao" />
<subscriber exclude="true" name="dtv.xst.dao.ctl.impl.EventLogEntryDAO" />
<subscriber exclude="true" name="dtv.xst.dao.inv.impl.InventoryCount" />
<subscriber exclude="true" name="dtv.xst.dao.tsn.Session" />
<subscriber exclude="true" name="dtv.xst.dao.tsn.TenderRepositoryDAO" />
<subscriber exclude="true" name="dtv.xst.dao.itm.impl.ItemLabelBatchDAO" />
</service>
<service name="EventLogReplicationCritical" expireAfter="never">

<condition
class="dtv.data2.replication.dtximpl.condition.MethodCallResultCondition">
<conditionParam key="methodName" value="getCriticalToDeliver" />
<conditionParam key="result" value="true" />
</condition>
<destination type="DataSource" dataSourceName="Xcenter" />
<subscriber name="dtv.xst.dao.ctl.impl.EventLogEntryDAO" />
</service>
...
</DtxReplicationConfig>


8
Query Configuration
Overview
This chapter describes the QueryConfig.xml file, which is used for the creation and
configuration of queries used by Xstore Point of Service. These queries are used by the
Persistence Framework when retrieving data from data sources.
Note: The structures of other query files—such as

PreFlightQueryConfig.xml, ReportQueryConfig.xml, and
SchedulingQueryConfig.xml—use the same XML structure as
QueryConfig.xml.
Query Configuration is designed around the object-oriented principles of keeping data

close together and defined in single units, rather than spread out. The advantages
include both a smaller configuration file size and improved readability.
There are many XML elements and attributes that can be used instead of properties to
define a query to be used in Xstore. The XML elements used to configure a query, along
with their corresponding property names, are defined in Elements and Attributes.
About this chapter

• QueryConfig.xml provides an overview of the QueryConfig.xml file.
• Elements and Attributes defines the elements and attributes in the file
QueryConfig.xml.
Query Configuration 8-1

QueryConfig.xml
QueryConfig.xml
To run a query, Xstore Point of Service sends a query request to the Persistence
Framework. This request includes the query name and the parameters for the query. The
Persistence Framework then searches through the QueryConfig.xml file for a query
that matches the query name provided in the request. Once that query is located,
Persistence Framework uses the query information in a call to the method
DataFactory.getObjectByQuery().
The QueryConfig.xml file has the following structure:
<QuerySet> Root Element:
xmlns:xsi Attribute
<Queries> Element:
<Query> Element
<Subqueries> Element:
<Query> Element
Elements and Attributes

• <QuerySet> (ROOT ELEMENT) - The set of all queries in the QueryConfig.xml file.
- xsi:noNamespaceSchemaLocation - The name of the schema .xsd file
associated with the XML file.
• <Queries> - An element to contain one or more <Query> elements (see <Query>
Element - Using DTXQL or <Query> Element - Raw SQL). Parent Element:
<QuerySet>.
• <Subqueries> - An element to contain one or more <Query> elements (see
<Query> Element - Raw SQL). Parent Element: <QuerySet>.
<Query> Element - Using DTXQL

Xstore Point of Service can now use DTXQL to configure configuring queries. This
method uses XML elements to configure elements of a query. This method for
configuring SQL is more modular and more secure and is the preferred method for
creating queries in Xstore Point of Service.
When defining the elements of a query through DTXQL, the <Query> element has the
following structure:
<Query> Element:
name Attribute
pmType Attribute
root Attribute
<QueryHandler> Element:
dtype Attribute

<ResultFilter> Element:
dtype Attribute
<ResultClass> Element:
dtype Attribute
<ResultField> Element:
name Attribute
type Attribute
order Attribute
function Attribute
<Select> Element:
from Attribute
distinct Attribute
<ResultField> Element
<Join> Element:
left Attribute
right Attribute
type Attribute
<On> Element:
operand Attribute
parameter Attribute
ignoreCase Attribute
literal Attribute
left Attribute
right Attribute
<Where> Element:
name Attribute
type Attribute
order Attribute
<Suffix> Element:
dtype Attribute
<Sort> Element:
field Attribute
order Attribute
required Attribute

<Having> Element:
<TestExpression> Element
dtype Attribute
<Condition> Element
dtype Attribute
<Parameter> Element
name Attribute
<Property> Element:
<Key> Element
<Value> Element
• <Query> - An element to contain the configuration for a single query. Parent
Element: <Queries> or <Subqueries>.
- name - The name of the query. This is the name used to refer to the query.
[Required]
- pmType - Specifies the Persistence Manager Type of the query. [Optional].
If this attribute is not set, the Persistence Manager Type will be determined by
the query's "FROM" object mapping in the PmTypeMappingConfig.xml file.
A sample query is shown below. Descriptions for each element and attribute in
QueryConfig.xml follow the sample.
<Query name="CUSTOMER_ACCOUNT_DETAIL_LOOKUP">
<ResultClass dtype="String">
dtv.xst.query.results.CustAccountSearchResult</ResultClass>
<Select from="CustomerAccount" distinct="true">
<ResultField name="organizationId" type="Long"/>
<ResultField name="custAccountId" type="String"/>
<ResultField name="custAccountCode" type="String"/>
<ResultField name="Party.firstName" type="String"/>
<ResultField name="Party.lastName" type="String"/>
<ResultField name="accountBalance" type="BigDecimal"/>
<ResultField name="CustomerItemAccount.activeAccountTotal"
type="BigDecimal"/>
<ResultField name="accountSetupDate" type="Date"/>
<ResultField name="custAccountStateCode" type="String"/>
</Select>
<Join right="CustomerItemAccount" left="CustomerAccount"/>
<Join right="CustomerItemAccountDetail"
left="CustomerItemAccount"/>
<Join right="Party" left="CustomerAccount">
<On right="partyId" left="partyId"/>
<On right="organizationId" left="organizationId"/>
</Join>
<Where>
<Required field="custAccountCode"/>
<Required field="organizationId"/>
<Required field="retailLocationId"/>
<Optional field="custAccountId"/>

<Optional field="accountPurchaseOrderNumber"
ignoreCase="true" parameter="argPoNumber" operand="EQUALS"/>
<Optional field="Party.customerId" ignoreCase="false"
operand="EQUALS"/>
<Optional field="partyId"/>
<Optional field="CustomerItemAccountDetail.stateCode"
ignoreCase="false" parameter="argDetailStatus"
operand="EQUALS"/>
</Where>
<Sort field="accountSetupDate"/>
</Query>
• <QueryHandler> - Defines the query handler to be used for this query. Must be
DtxQueryHandler when building a query through XML. Parent Element: <Query>.
Note: If this element is not specified, DTXQL queries will use the
class dtv.data2.access.query.DtxQueryHandler. Otherwise,
queries that use raw SQL will use the class
dtv.data2.access.query.SQLQueryHandler.
- dtype - Defines the type of the element. [Optional]

For a query that uses DTXQL, there is only one valid value for the
<QueryHandler> element:
Note: Xstore Point of Service will throw an error if a DTXQL query is

configured to use the SQLQueryHandler.
* dtv.data2.access.query.DtxQueryHandler - DtxQueryHandler
should be used when a query returns data directly in a Data Model object.
When this data handling class is called, the handler returns the data in a
Collection, even if only one match is found.
• <ResultFilter> - Specifies the Spring bean name of a filter that will filter the
results of the query. [Optional]
- dtype - Defines the type of the element. [Required]
• <ResultClass> - Defines the result class to store result of the query in. Parent
Element: <Query>. For queries using the DtxQueryHandler, this class should be
the ID class of the DTX object storing the result (for example, PartyId).
Note: If no <ResultClass> is specified, the application will return

DTX IDataModel objects based upon the name of the DTX object in
the from attribute of the <Select> element.
If an IQueryResult type is specified, the <ResultField> elements

should be specified to populate the result.

• <ResultField> - Represents an individual field out of all of the fields being

returned by the query. Parent Element: <Query>.
Note: Only used when the query populates a result class object that is
not a DTX object.
- name - The name of the field. Required when a result class is defined (for
queries using the SQL handler). The name should match the accessor method
names in the result class. [Required]
- type - The data type being stored in the result field. [Optional]
- order - The order that this field belongs in. [Optional] DEFAULT=Natural
ordering.
- function - The function performed on the data for this field. [Optional].
This attribute can have the following value:
* SUM - Sum of all the values.
• <Select> - Defines the SELECT statement for the SQL. Parent Element:
<Query>.
- from - Name of the DTX object from which the data is queried. [Required]
- distinct - Indicates whether the select statement should only return distinct
rows. [Optional] DEFAULT=false
• <Join> - Defines the JOIN statement for the SQL. Parent Element: <Query>.
- left - Name of the DTX object on the left. [Required]
- right - Name of the DTX object on the right. [Required]
- type - Type of join to perform. [Optional] DEFAULT=INNER
This attribute must have one of the following values:
* INNER
* LEFT
* LEFT OUTER
* RIGHT
* FULL
• <On> - Defines the fields on which the tables are joined. Parent Element: <Join>.
Note: If no <On> elements are specified, the DTX objects are joined
on the primary key fields.
- operand - Operand used to compare the field values. [Optional]

DEFAULT=EQUALS
* EQUALS
* GREATER_THAN
* GREATER_THAN_EQUALTO

* LESS_THAN
* LESS_THAN_EQUALTO
* IS
* LIKE
* EXISTS
- parameter - Name of the parameter. [Optional] DEFAULT=argX, where X is
the capitalized field name.
- ignoreCase - Indicates whether to compare strings without considering
case. [Optional] DEFAULT=false
- literal - Literal value of a field. Must be included if either the left or
right attribute is not included.
- left - Name of the field on the left. If this attribute is not included, the right
and literal attributes must be included.
- right - Name of the field on the right. If this attribute is not included, the
left and literal attributes must be included.
• <Where> - Defines the WHERE clause for the SQL. Parent Element: <Query>.
• <Required> - Defines a field that must either have a query parameter included,
or must have a literal value defined. Parent Element: <Where> or <Or>.
DEFAULT=EQUALS
* EQUALS
* GREATER_THAN
* LESS_THAN
* LESS_THAN_EQUALTO
* IS
* LIKE
Note: You may include a wildcard (%) on either side of the field
name when using the operand LIKE.
* EXISTS
- literal - Literal value of a field. [Optional]
- field - Name of the field. [Optional]
- columnRef - Name of a column in the form <Table>.<Field> where <Table> is
the name of the table and <Field> is the name of the field in the table. [Optional]

- queryRef - Name of a <Query> in the <Subqueries> element. [Optional]

• <Optional> - Defines a field that will only be included in the WHERE clause if
the matching query parameter is provided. Element. Parent Element: <Where>.
DEFAULT=EQUALS
* EQUALS
* GREATER_THAN
* LESS_THAN
* LESS_THAN_EQUALTO
* IS
* LIKE
Note: You may include a wildcard (%) on either side of the field
name when using the operand LIKE.
* EXISTS
Note: The system assumes this argX parameter name if the

configuration doesn't provide one.

• <Or> - Defines a set of <Required> fields among which at least one query
parameter must be included. Parent Element: <Where>.
• <Sort> - Defines a field to sort the results off of, and optional sort order. Parent
Element: <Query>.
- field - DESCRIPTION: The field to sort off of. This can be a literal field to sort
off of or it can be a parameter that is passed in through the application.
[Required]
- order - DESCRIPTION: The order in which to sort the field. This is a parameter
only. [Optional]
- required - Used to specify whether the sort for the query is required.
DEFAULT=true.
- CORRESPONDING PROPERTY: Sort, Sort.Order

Example:
<Sort field="argSortBy" required="false"/>
• <Key> - Defines the type of information being configured. Parent Element:

<Property>.
• <Value> - The actual information described by the <Key> element. Parent
Element: <Property>.
<Query> Element - Raw SQL

Though DTXQL is the preferred method for creating queries in Xstore Point of Service,
there are some circumstances DTXQL cannot create an SQL statement properly. When
this is necessary, Xstore Point of Service provides the option to create a query using
standard SQL.
When defining a query using raw SQL, the <Query> element has the following
structure:
<Query> Element:
name Attribute
pmType Attribute
root Attribute
<QueryHandler> Element:
dtype Attribute
<ResultFilter> Element:
dtype Attribute
<ResultClass> Element:
dtype Attribute
<ResultField> Element:
name Attribute
type Attribute
order Attribute
function Attribute

<SQL> Element:
required Attribute
order Attribute
<Statement> Element
dtype Attribute
<WhereClause> Element
dtype Attribute
<Parameter> Element
name Attribute
<Expression> Element
trigger Attribute
parameters Attribute
<Suffix> Element:
dtype Attribute
<Sort> Element:
field Attribute
order Attribute
required Attribute
<Having> Element:
<TestExpression> Element
dtype Attribute
<Condition> Element
dtype Attribute
<Parameter> Element
name Attribute
<Property> Element:
<Key> Element
<Value> Element
• <Query> - An element to contain the configuration for a single query. Parent
Element: <Queries> or <Subqueries>.
- name - The name of the query. This is the name used to refer to the query.
[Required]
- pmType - Specifies the Persistence Manager Type of the query. [Optional]
If this attribute is not set, the Persistence Manager Type will be determined by
the query's "FROM" object mapping in the PmTypeMappingConfig.xml file.

A sample query is shown below. Descriptions for each element and attribute in
QueryConfig.xml follow the sample.
<Query name="SERVICE_LOC_LOOKUP" pmType="CODES">

<QueryHandler dtype="Class">dtv.data2.access.query.SqlQueryHandler</
QueryHandler>
<ResultClass
dtype="String">dtv.xst.query.results.ServiceLocationSearchResult</
ResultClass>
<ResultField name="ServiceLocationId"/>
<ResultField name="Description"/>
<ResultField name="Address1"/>
<ResultField name="Address2"/>
<ResultField name="City"/>
<ResultField name="Territory"/>
<ResultField name="PostalCode"/>
<SQL>
<Statement dtype="String"><![CDATA[
select sl.service_loc_id, sl.description, ad.address1,
ad.address2, ad.city, ad.territory, ad.postal_code
from cwo_service_loc sl
left join com_address ad on sl.address_id = ad.address_id
and sl.organization_id = ad.organization_id
where sl.organization_id = ?
]]></Statement>
<Parameter name="argOrganizationId"/>
<Expression trigger="argName"
parameters="argName%"><![CDATA[sl.description like ?]]></Expression>
<Expression trigger="argNumber"><![CDATA[sl.service_loc_id = ?]]></
Expression>
<Expression trigger="argAddressNotNull"
parameters=""><![CDATA[sl.address_id is not null]]></Expression>
</SQL>
<Suffix dtype="String"><![CDATA[ORDER BY sl.description]]></Suffix>
</Query>
• <QueryHandler> - Defines the query handler to be used for this query. Must be
DtxQueryHandler when building a query through XML. Parent Element: <Query>.
Note: If this element is not specified, DTXQL queries will use the
class dtv.data2.access.query.DtxQueryHandler. Otherwise,
queries that use raw SQL will use the class
dtv.data2.access.query.SQLQueryHandler.
- dtype - Defines the type of the element. [Optional]

There are two valid values for the <QueryHandler> element:
* dtv.data2.access.query.DtxQueryHandler - DtxQueryHandler
should be used when a query returns data directly in a Data Model object.
When this data handling class is called, the handler returns the data in a
Collection, even if only one match is found.
* dtv.data2.access.query.SqlQueryHandler - SqlQueryHandler
should be used when a query returns data in a "wrapped" object. This differs

from the DtxQueryHandler discussed above which returns Data Models

as opposed to "wrapped" objects. When this data handling class is called, the
handler returns the data in a wrapped object. A Collection is only returned if
more than one match is found.
• <ResultFilter> - Specifies the Spring bean name of a of filter that will filter the
results of the query.
• <ResultClass> - Defines the result class to store result of the query in. Parent
Element: <Query>. For queries using the SqlQueryHandler, this class should
extend AbstractQueryResult. For queries using the DtxQueryHandler this
class should be the id class of the DTX object storing the result (ex: PartyId).
• <ResultField> - Represents an individual field out of all of the fields being
returned by the query. Parent Element: <Query>.
- name - The name of the field. Required when a result class is defined (for
queries using the SQL handler). The name should match the accessor method
names in the result class. [Required]
- type - The data type being stored in the result field. [Optional]
- order - The order that this field belongs in. [Optional] DEFAULT=Natural
ordering.
- function - The function performed on the data for this field. [Optional].
This attribute can have the following value:
* SUM - Sum of all the values.
• <Required> - Defines a field that must either have a query parameter included,
or must have a literal value defined. Parent Element: <Where> or <Or>.
DEFAULT=EQUALS
* EQUALS
* GREATER_THAN
* LESS_THAN
* LESS_THAN_EQUALTO
* IS
* LIKE
* EXISTS


• <Optional> - Defines a field that will only be included in the WHERE clause if a
query parameter is provided. Element. Parent Element: <Where>.
DEFAULT=EQUALS
* EQUALS
* GREATER_THAN
* LESS_THAN
* LESS_THAN_EQUALTO
* IS
* LIKE
* EXISTS
• <Or> - Defines a set of <Required> fields among which at least one query
parameter must be included. Parent Element: <Where>.
• <SQL> - Wraps the necessary configuration for a block of SQL including the SQL
to execute, necessary parameters, and optional expressions. Parent Element:
<Query>.
Optional SQL Blocks
For multi-part SQL statements there is a boolean attribute that can be set on the SQL
elements called "required" that will allow the system to optionally include a block of
sql based on whether or not the required parameters are present at the time of
constructing the query. This flag is optional, and if it's not set then the SQL block will
always be required.
- required - Used to specify whether this query is required when in a multi-
part SQL statement. [Optional] DEFAULT=true.
- order - Used to specify the order to append this block of SQL in for multi-
part SQL statements. [Optional] DEFAULT: The natural order of the SQL elements
is respected.

• <Statement> - Used to store the base SQL query to be executed. Parent Element:
<SQL>.
- CORRESPONDING PROPERTY: SQL, SQL1, SQL2, …
• <WhereClause> - Used to store the base WhereClause for DTX queries. Parent
Element: <SQL>.
- CORRESPONDING PROPERTY: WhereClause
Example:
<SQL>
<WhereClause dtype="String"><![CDATA[
WHERE t.organization_id = ?
AND t.cust_acct_id = ?
AND t.cust_acct_code = ?
AND t.invoice_balance > 0
order by t.invoice_date asc
]]></WhereClause>
<Parameter name="argOrganizationId"/>
<Parameter name="argAcctId"/>
<Parameter name="argAcctCode"/>
</SQL>
Note: The framework always interprets the "t" alias to mean “the
primary table”.
• <Parameter> - Used to specify a required parameter for the parent SQL element.
Parent Element: <SQL, Having>.
- name - The name of the required parameter. [Optional]
- CORRESPONDING PROPERTY: Parameters
• <Expression> - An optional expression to append to the where clause portion of
a SQL statement. Parent Element: <SQL>
- trigger - The parameter name to trigger the addition of this optional
expression. [Required]
- parameters - The required parameters for this optional expression.
[Optional] DEFAULT=The parameter name specified in the trigger attribute.
- CORRESPONDING PROPERTY: SQL.<ParameterName> and
Parameters.<ParameterName>
Example:
<Expression trigger="argStartTime" parameters="argStartTime,

argEndTime"><![CDATA[t.begin_time_int between ? and ?]]></Expression>
• <Suffix> - Specifies the last line to be appended to a SQL statement. Parent

Element: <Query>.

- CORRESPONDING PROPERTY: Suffix

Example:
<Suffix dtype="String"><![CDATA[ORDER BY t.begin_datetime DESC]]></Suffix>
• <Sort> - Defines a field to sort the results off of, and optional sort order. Parent
Element: <Query>.
- field - DESCRIPTION: The field to sort off of. This can be a literal field to sort
off of or it can be a parameter that is passed in through the application.
[Required]
- order - DESCRIPTION: The order in which to sort the field. This is a parameter
only. [Optional]
- required - Used to specify whether the sort for the query is required.
DEFAULT=true.
- CORRESPONDING PROPERTY: Sort, Sort.Order
Example:
<Sort field="argSortBy" required="false"/>
• <Having> - A configuration wrapper for optional having clauses. Parent Element:

<Query>.
- CORRESPONDING PROPERTY: NA
Example:
<Having>
<TestExpression dtype="String">COALESCE(SUM(CASE WHEN TSL.return_flag='0'
THEN TSL.net_amt END),0)</TestExpression>
<Condition dtype="String">BETWEEN ? AND ?</Condition>
<Parameter name="startAmtPurchased"/>
<Parameter name="endAmtPurchased"/>
</Having>
• <TestExpression> - The expression that is being tested. Parent Element:

<Having>.
- CORRESPONDING PROPERTY: Having.Field
Example:
<TestExpression dtype="String">COALESCE(SUM(CASE WHEN TSL.return_flag='0'

THEN TSL.net_amt END),0)</TestExpression>
• <Condition> - The condition that is applied to the test expression. Parent

Element: <Having>.
- CORRESPONDING PROPERTY: Having
Example:
<Condition dtype="String">BETWEEN ? AND ?</Condition>

Note: There are many XML elements and attributes that can be used
instead of properties to define a query to be used in Xstore as
described in the sections above. However, there are some instances
where a property is required.
• <Property> - Defines a property of the of the query. These configurations rely

entirely upon the <Key> and <Value> sub-elements. Parent Element: <Query>.
Example:
<Property>
<Key dtype="String">QueryType</Key>
<Value dtype="String"><![CDATA[Procedure]]></Value>
</Property>
• <Key> - Defines the type of information being configured. Parent Element:

<Property>.
• <Value> - The actual information described by the <Key> element. Parent
Element: <Property>.
- dtype - Defines the type of the element.

9
DocBuilder Framework
Overview
This chapter describes the DocBuilder Framework, which is used to create documents
that are printed on the receipt printer. This includes both receipt printing and frankings
that are performed on tenders.
Note that report creation is not configured through the DocBuilder Framework. Reports
are configured through the Reporting Framework, which is described in Chapter 11,
“Reporting Framework”.
About This Chapter

• Introduction to the DocBuilder Framework provides a general overview of the
DocBuilder Framework.
• Tracing describes tracing and how to turn it on and off in Xstore Point of Service.
• RcptConfig.xml provides a general overview of the different areas of the file
RcptConfig.xml and what these areas configure.
• Formatter (<Formatter>) describes the formatters defined within the <Formatter>
element in the file RcptConfig.xml.
• Receipt Copy Rule (<ReceiptCopyRule>) describes the receipt copy rules defined
within the <ReceiptCopyRule> element in the file RcptConfig.xml.
• Receipt Document (<receipt>) describes the receipts defined within the <receipt>
• Tender Franking (<FrankTender>) describes the tender frankings defined within the
<FrankTender> element in the file RcptConfig.xml.
• Section (<section>) describes the document elements defined within the <section>
Introduction to the DocBuilder Framework

The DocBuilder Framework provides mechanisms that generate two specific types of
documents in the Xstore Point of Service application. The types of documents generated
using the DocBuilder Framework are:
- Receipts
- Tender Frankings
DocBuilder Framework 9-1

Tracing
How DocBuilder Works: Process Overview

A document is assembled one section at a time until all sections have been completed.
The DocBuilder Framework lays out each section of each document according to the
rules defined in certain configuration files.
The file RcptConfig.xml defines the layout for all output from the receipt printer,
including both receipts and tender frankings.
The definition of a document includes instructions for (1) obtaining and processing its
content (such as methods, iterators, parameters and conditions) and for (2) organizing
and formatting the content (sections, rows, regions, formatting styles, etc.).
After the DocBuilder Framework completes the document, it may be persisted (receipts)
or printed (receipts and tender frankings). However, printing and persisting are
accomplished by methods that are not part of the DocBuilder Framework.
Tracing
Tracing is a helpful tool for debugging receipt and log configurations when something
unexpected happens. It can help you identify the configuration that caused a problem
with a particular part of a receipt or log.
Enable tracing for receipt building: Set the following system property to “true” in the
file system.properties:
dtv.hardware.rcptbuilding.RcptElementFactory.trace=true
The section name and source file name and line number will be included in the
generated document at the start of each section. With this information you can find the
part of the configuration that produces each part of the receipt.
RcptConfig.xml
The RcptConfig.xml file defines all aspects of the receipts and tender frankings that
are printed in the receipt printer. These are constructed through document sections that
can be additionally formatted through special formatters. In addition, receipts are given
copy rules that affect the number and type of receipts printed for different transaction
types.
The file RcptConfig.xml is organized as follows:
<ReceiptDefinitions> Element:
xmlns:xsi Attribute
<FormatterMap> Element:
<Formatter> Element:
See Formatter (<Formatter>) for the organization of this element.
<ReceiptCopyRules> Element:
<ReceiptCopyRule> Element:
See Receipt Copy Rule (<ReceiptCopyRule>) for the organization of
this element.

RcptConfig.xml
<receipts> Element:
<receipt> Element
See Receipt Document (<receipt>) for the organization of this element.
<FrankTenders> Element:
<FrankTender> Element
See Tender Franking (<FrankTender>) for the organization of this
element.
<sections> Element:
<section> Element:
See Section (<section>) for the organization of this element.
• <ReceiptDefinitions> - This element contains all the configurations for the

documents printed on the receipt printer.
with the XML file.
• <FormatterMap> - Contains the set of all named output format definitions. These
formats both standardize and simplify access to additional formatting capabilities
for receipts. If you need to format a field using custom rules, you may define a
custom formatter in the FormatterMap section of the config. This links input to a
class that formats it.
- <Formatter> - This element defines a named method for formatting receipt
output. See Formatter (<Formatter>) for more information about this element.
• <ReceiptCopyRules> - Contains the rules used when printing multiple copies of
a receipt For example, the customer and store copies of a credit card receipt. (A copy
rule defines an interface to a simple class you write that determines which receipts you need
for a transaction and how many of each.)
- <ReceiptCopyRule> - This element defines a named rule for creating receipt
copies. See Receipt Copy Rule (<ReceiptCopyRule>) for more information about
this element.
• <receipts> - Contains the receipt document definitions, which include printing
information and the <section> used to print the receipt.
- <receipt> - This element defines the receipt document, including the name
used to identify it, where it is printed, and the building blocks from which it is
created. See Receipt Document (<receipt>) for more information about this
element.
• <FrankTenders> - Contains the tender franking definitions.
- <FrankTender> - This element defines a tender franking for a certain tender
that is either being issued or received. See Tender Franking (<FrankTender>) for
more information about this element.
• <sections> - Contains the set of all named receipt section definitions. These
receipt sections are combined to create each receipt.
- <section> - This element defines a named area of a document that presents
defined content used as a building block for a receipt. This content often
encompasses multiple rows. See Section (<section>) for more information about
this element.

Formatter (<Formatter>)
Formatter (<Formatter>)
A Formatter provides additional formatting capabilities beyond those available from an
object, or through the configuration options available in a <section> element.
The <Formatter> element has the following organization:
<Formatter> Element:
name Attribute
class Attribute
ctx Attribute
force Attribute
formatterType Attribute
includeCurrencySymbol Attribute
format Attribute
length Attribute
<Class> Element
name Attribute
value Attribute
<param_value> Element:
dtype Attribute
• name - This attribute defines the name of the <Formatter>. This name is used by a
<field> element’s formatter attribute to call the <Formatter>.
• class - Contains the fully-qualified name of the Java class that formats the output.
This Java class must implement dtv.pos.docbuilding.format.IFormatter.
• ctx - Defines the output context for the content: Document, View, or Receipt
(default). This attribute allows information to be formatted based on the output
context.
• <Class> - Contains the fully-qualified name of the Java class that formats the
output. This Java class must implement
dtv.pos.docbuilding.format.IFormatter.
called in the <Class> element.
- name - The name of the parameter.
• <param_value> - This element contains the value sent in the named
<Parameter>. This element allows a value that is not a String to be sent as a
parameter.

Receipt Copy Rule (<ReceiptCopyRule>)
Formatter Example
<Formatter name="TimeclockEntryType"
class="dtv.pos.i18n.format.CodeDescriptionFormatter" ctx="RECEIPT">
<Parameter name="setCodeClass">
<param_value
dtype="Class">dtv.pos.timeclock.TimeClockEntryType</param_value>
</Parameter>
</Formatter>

A Receipt Copy Rule is a configurable piece of logic that determines the number and
type of receipt(s) generated by a transaction.
This element has the following organization:
<ReceiptCopyRule> Element:
name Attribute
document Attribute
additive Attribute
copies Attribute
enabled Attribute
<enabled> Element:
dtype Attribute
<Rule> Element:
class Attribute
type Attribute
excludeType Attribute
tenderId Attribute
state Attribute
inverted Attribute
value Attribute
code Attribute
length Attribute
<Class> Element
name Attribute
value Attribute
dtype Attribute

document_id Element:
dtype Attribute
copy_count Element:
dtype Attribute
additive Element:
dtype Attribute
• name - The name of the <ReceiptCopyRule>. This name is used to call the
<ReceiptCopyRule>.
• document - Defines the <receipt> document type called by the
<ReceiptCopyRule> when all of the <Rule> conditions are met.
• additive - Indicates whether additional <ReceiptCopyRule> elements may be
processed alongside this <ReceiptCopyRule>, or if no other
<ReceiptCopyRule> should be processed for the transaction.
• copies - Indicates the number of receipt copies that are created by the
<ReceiptCopyRule> when the conditions specified by the rule are met.
• enabled - Determines whether the <ReceiptCopyRule> is currently in use.
• <enabled> - This element determines whether the <ReceiptCopyRule> is
currently in use.
- dtype - Indicates the type of data contained in the element. The only valid value
for this attribute is “Boolean”. This element has the following values:
* true - The <ReceiptCopyRule> is currently in use.
* false - The <ReceiptCopyRule> is not currently in use.
• <Rule> - This element defines a rule for the Receipt Copy Rule. If the conditions for
the <Rule> are met, processing of the <ReceiptCopyRule> continues. If the
conditions are not met, processing stops in the <ReceiptCopyRule> and no
document is printed.
If there are multiple <Rule> elements in a <ReceiptCopyRule>, then all of the
<Rule> conditions must be met.
• class - Contains the fully-qualified name of a Java class that determines whether
the conditions for a <Rule> have been met. This class must implement the
dtv.pos.hardware.rcptbuilding.copyrules.IRcptCopyRule class.
• <Class> - This element contains the fully-qualified name of a Java class that
determines whether the conditions for a <Rule> have been met. This class must
implement the
dtv.pos.hardware.rcptbuilding.copyrules.IRcptCopyRule class.
called in the <Class> element.

Receipt Document (<receipt>)
• <param_value> - This element contains the value sent in the named

<Parameter>. This element allows a value that is not a String to be sent as a
parameter.
• <document_id> - This element defines the <receipt> document type called by
the <ReceiptCopyRule> when all of the <Rule> conditions are met.
for this attribute is “String”.
• <copy_count> - This element indicates the number of receipt copies that are
created by the <ReceiptCopyRule> when the conditions specified by the rule are
met.
for this attribute is “Integer”.
• <additive> - This element indicates whether additional <ReceiptCopyRule>
elements may be processed alongside this <ReceiptCopyRule>, or if no other
<ReceiptCopyRule> should be processed for the transaction.
* true - Additional <ReceiptCopyRule> elements may be valid alongside
this one.
* false - No other <ReceiptCopyRule> elements are to be processed.
Receipt Copy Rule Example
<ReceiptCopyRule name="LAYAWAY_MERCH_TICKET" document="LAYAWAY_MERCH_TICKET">

<Rule class="dtv.pos.hardware.rcptbuilding.copyrules.LayawayTicketRule"
type="LAYAWAY"/>
<Rule
class="dtv.pos.hardware.rcptbuilding.copyrules.CustomerItemAccountStateRule">
<Parameter name="state" value="NEW"/>
<Parameter name="state" value="OPEN"/>
</Rule>
<Rule
class="dtv.pos.hardware.rcptbuilding.copyrules.AnyCustomerAccountDetailStateR
ule" state="NEW"/>
<Rule class="dtv.pos.hardware.rcptbuilding.copyrules.ReturnRule"
inverted="true"/>
</ReceiptCopyRule>

A receipt document creates one named document entity with a printing location, and a
reference to its content.

This element has the following organization:

<receipt> Element:
document Attribute
sectionref Attribute
email Attribute
<document_id> Element:
dtype Attribute
<printer> Element:
dtype Attribute
<printer_backup> Element:
dtype Attribute
<email_copy> Element:
dtype Attribute
<sectionref> Element
• document - Defines the name for the <receipt>.

• sectionref - Determines the <section> that defines the content for the
<receipt>. See Section (<section>) for more information about the <section>
element.
• email - Indicates whether the receipt should be included as part of an email receipt
delivery.
• <document_id> - This element defines the name for the <receipt>. This name is
used to refer to the <receipt>.
- dtype - This attribute indicates the type of data contained in the element. The
only valid value for this attribute is “String”.
• <printer> - This element defines the primary destination printer for the
<receipt>.
• <printer_backup> - This element defines the backup destination printer for the
<receipt>.
• <sectionref> - This element determines the <section> that defines the content
for the <receipt>. See Section (<section>) for more information about the
<section> element.
Receipt Document Example
<receipt document="WARRANTY_RECEIPT" sectionref="WARRANTY_RECEIPT"

email="true"/>
<receipt document="CUSTOMER" sectionref="CustomerCopy" email="true"/>

Tender Franking (<FrankTender>)
<receipt document="CUSTOMER_TENDER_EXCHANGE"
sectionref="CUSTOMER_TENDER_EXCHANGE_COPY"/>
<receipt document="GIFT" sectionref="GiftReceipts" email="true"/>

A Tender Franking is a document that, rather than printing a receipt, franks a tender in
the receipt printer. Tender Franking can be used to endorse a check, issue a gift
certificate, redeem a travelers check, or any of a number of other functions related to
tenders and tendering.
The <FrankTender> element has the following organization:
<FrankTender> Element:
type Attribute
action Attribute
post_void Attribute
enabled Element:
dtype Attribute
printer Element:
dtype Attribute
printer_backup Element:
dtype Attribute
<ParametrizedFormattable> Element:
See Append Formattable Text Containing Variable Placeholders
(<ParametrizedFormattable>) for the organization of this element.
<EvaluatedFormattable> Element:
See Append Formattable Text Output by a Function
(<EvaluatedFormattable>) for the organization of this element.
• type - This attribute indicates the tender type for which this <FrankTender> is
used.
• action - This attribute indicates whether this <FrankTender> is used when the
tender is being issued (ISSUED) or redeemed (REDEEMED).
• post_void - This attribute indicates whether the <FrankTender> is used during a
post void transaction. This attribute has the following valid values:
- true - This <FrankTender> is used for a post void of a transaction in which
the tender_type was issued_or_redeemed.
- false - This <FrankTender> is used for a non-post void transaction in which
the tender_type is being issued_or_redeemed
• <enabled> - This element determines whether the <FrankTender> is currently in
use.
* true - The <FrankTender> is currently in use.

* false - The <FrankTender> is not currently in use.

• <printer> - This element defines the primary destination printer for the
<FrankTender>.
• <printer_backup> - This element defines the backup destination printer for the
<FrankTender>.
• <sectionref> - This element calls the section containing output that is sent to the
receipt printer. See Section (<section>) for more information.
• <ParametrizedFormattable> - This element builds formattable text output
using a translation key that contains variable placeholders. The output of this
element is printed in the franking. See Append Formattable Text Containing
Variable Placeholders (<ParametrizedFormattable>) for more information about this
element.
• <EvaluatedFormattable> - This element creates formattable text output using
the output from a function. The output of this element is printed in the franking. See
Append Formattable Text Output by a Function (<EvaluatedFormattable>) for more
information about this element.
Append Formattable Text Containing Variable Placeholders

(<ParametrizedFormattable>)
The <ParametrizedFormattable> element builds formattable text output using a
translation key that contains variable placeholders. This element can contain as many
sub-elements as necessary for the number of variable placeholders in the translation key.
The <ParametrizedFormattable> element has the following organization:
<ParametrizedFormattable> Element:
key Attribute
See Append Formattable Text Output by a Function
(<EvaluatedFormattable>) for the organization of this element.
• key - This attribute contains a preconfigured text variable used to display text in the
output. Contents determined by text variables use translation keys and ITranslator to
determine the text displayed.
• <EvaluatedFormattable> - This element creates formattable text output using
the output from a function. The output of this element replaces one of the variable
placeholders from the <TranslationKey>. See Append Formattable Text Output
by a Function (<EvaluatedFormattable>) for more information about this element.
<ParametrizedFormattable> Example
The following <ParametrizedFormattable> element may be used in franking a
check tender:
<ParameterizedFormattable key="_frankCheckDescription">
<EvaluatedFormattable method="getTender.getDescription"/>
<EvaluatedFormattable method="getCheckSequenceNumber"/>

Section (<section>)
<EvaluatedFormattable method="getAmount" formatter="MONEY"/>

</ParameterizedFormattable>
In this example, assume that the key _frankCheckDescription outputs the

following value:
{0} {1} in the amount of {2}
This key contains three variable placeholders: {0}, {1}, and {2}. There are three
<EvaluatedFormattable> elements, each of which uses the output of a function to
replace — in order of appearance — a variable placeholder.
- {0} is replaced by the output of the function getTender.getDescription.
In this example, the output is “Check”.
- {1} is replaced by the output of the function getCheckSequenceNumber. In
this example, the output is “123”.
- {2} is replaced by the output of the function getAmount once it has been
formatted by the Money formatter. In this example, the output is “$55.66”.
In this example, the output from the <ParametrizedFormattable> element is the
following:
Check 123 in the amount of $55.66
Append Formattable Text Output by a Function (<EvaluatedFormattable>)

This element creates formattable text output using the output from a function.
The <EvaluatedFormattable> element has the following organization:
method Attribute
formatter Attribute
• method - This attribute contains the name of the function that is performed on the
current object.
• formatter - This attribute determines the name of the formatter that is used to
format the output. See Formatter (<Formatter>) for more information.
Section (<section>)
A section, defined by a <section> element, is a named area of a document that is used
as a building block of the document. These building blocks can be constructed from
individual elements, multiple elements, repeating elements, or combinations of elements
and other sections. A section may contain one or more conditions that are used to
evaluate the current object and determine if the section should be built or skipped.
Sections may be referenced from many different locations and references may be
embedded as deeply as necessary. A section reference is used to simplify a configuration
and reuse a section of a document in more than one place or in more than one type of
document. A section reference contains only the name of another section. (The name is
case-sensitive, just like Java.)
Note: Be careful to avoid circular references. A circular reference

typically causes a StackOverflowError.

Section (<section>)
The <section> element has the following organization:

<section> Element:
name Attribute
dbRef Attribute
See Apply a Condition (<condition>) for the organization of this
element.
<row> Element:
style Attribute
charsize Attribute
align Attribute
n Attribute
sp Attribute
See Apply a Condition (<condition>) for the organization of this
element.
<field> Element:
See Field (<field>) for the organization of this element.
<region> Element:
See Text Block with Multiple Lines (<region>) for the organization of
this element.
<iterator> Element:
See Looping Iterator (<iterator>) for the organization of this element.
<textblock> Element:
See Multiple Lines of Text from com_receipt_text (<textblock>) for the
organization of this element.
<call> Element:
method Attribute
<method_param> Element:
dtype Attribute
<condition> Element
The following sub-elements of the <call> element are identical to
those of the <section> element:
<row> Element
<iterator> Element
<region> Element
<call> Element
<barcode> Element:
See Barcode (<barcode>) for the organization of this element.

Section (<section>)
<horizontal_rule> Element:
style Attribute
<field> Element:
<picture> Element:
filename Attribute
preload Attribute
<signature> Element:
<field> Element:
<pagebreak> Element:
• name - This attribute is used to apply a name to the section. This name can then be
used to reference the section through a <sectionref> element.
• dbRef - This attribute specifies that the contents for this section will be obtained
from the COM_RECEIPT_TEXT table. The date retrieved from the specified method
is evaluated against COM_RECEIPT_TEXT.EFFECTIVE_DATE and
COM_RECEIPT_TEXT.EXPIRATION_DATE to determine if the receipt text should be
included. The format of this field is
<<TEXT_CODE>>::<<TEXT_SUBCODE>>::<<DATE_METHOD_TO_CALL>> where
<<TEXT_CODE>> will match the value from COM_RECEIPT_TEXT.TEXT_CODE,
<<TEXT_SUBCODE>> will match the value from
COM_RECEIPT_TEXT.TEXT_SUBCODE, and <<DATE_METHOD_TO_CALL>> will be
a method to call via reflection on the current target object.
Example value: CUSTOMER_COPY_HEADER::DEFAULT::getBusinessDate
Note: The current target object is typically a retail transaction model

object which has a getBusinessDate() method.
• <sectionref> - This element references another <section> by name. When the

<sectionref> sub-element is called within a <section> (the current
<section>), the data within the named <section> is included as part of the
current <section>. This allows a document section to be reused in more than one
place and in more than one type of document. Note that the named <section>
runs in the same context, with the same current object as the current <section>.
• <condition> - This element uses configurable logic to determine whether to
include data in a document. If this condition returns a “true” value, then the data is
displayed. If this condition returns a “false” value, the data is not displayed. See
Apply a Condition (<condition>) for a full description of the <condition> element
and its structure.
• <row> - This element is a collection of field definitions that is followed by a line
break.
- style - This attribute determines the style of the text. The following values are
preconfigured for this attribute:

Section (<section>)
* BOLD - The field is printed using bold text.

* UNDERLINE - The field is printed with underlined text.
* STRONGUNDERLINE - The field is printed with text that is both bold and
underlined.
* ITALICS - The field is printed in italics.
* REVERSE - The field is printed with colors reversed. For example, the field is
printed with white text on a black background, rather than black text on a
white background.
- charsize - This attribute determines the size of the characters in the text. The
following values are preconfigured for this attribute:
* NORMAL - The characters are of normal size.
* DOUBLEHIGH - The characters are of normal width and double height.
* DOUBLEWIDE - The characters are of normal height and double width.
* DOUBLEHIGHDOUBLEWIDE - The characters are of both double height and
double width.
- align - This attribute determines the horizontal alignment of the text. The
following values are preconfigured for the attribute:
* L (LEFT) - Text is justified on the left edge (default).
* R (RIGHT) - Text is justified on the right edge.
* C (CENTERED) - Text is centered.
- n - This attribute indicates the number of times the row contents should be
repeated. This is primarily useful for allowing multiple empty rows to be
configured using a compact syntax.
• <field> - This element defines a portion of the document that is reserved for a
specific piece of data. See “Field (<field>)” for more information.
• <region> - This element defines an area of the document that can contain multiple
lines of text. Text-wrapping rules are automatically applied to text defined in a
<region>. See “Text Block with Multiple Lines (<region>)” for more information.
• <iterator> - This element processes a collection of data returned by a <method>.
Rather than examining the collection as a whole, the <iterator> allows processes
to be performed on each item in the collection. See “Looping Iterator (<iterator>)” for
more information.
• <textblock> - Like the <region> element, this element defines an area of the
document that can contain multiple lines of text. Text-wrapping rules are
automatically applied to text defined in a <textblock>. However, a <textblock>
element accesses text from the com_receipt_text table in the database. See
“Multiple Lines of Text from com_receipt_text (<textblock>)” for more information.
• <call> - This element changes the current object. By calling a <method> (and its
associated <method_param> elements) on the object that is presently the current
object, the result of the <method> becomes the current object within the <call>
element. This new current object is also the current object for all sub-elements of the
<call> element. See the examples in “Call New Object (<call>)” for examples of the
<call> element.
current object.

Section (<section>)
• <method_param> - This element defines a parameter that is passed to the function

called in the <method> element.
- dtype - This attribute indicates the type of data contained in the parameter.
• <barcode> - This element defines a barcode created on the document. See “Barcode
(<barcode>)” for more information.
• <horizontal_rule> - This element defines a horizontal line is drawn across the
document. If this element contains a <field> sub-element, the data in the <field>
sub-element is the prefix for the horizontal line. This element has the following
attributes:
- style - This attribute indicates the style of the line to be drawn. This attribute
has the following preconfigured values:
* Normal - Normal line drawn across the bottom of the text row (default)
* Strong - Thick line drawn across the bottom of the text row
* Mid - Line drawn in the middle of the text row
* High - Line drawn at the top of the text row
* Double - Double line
If a non-configured style is specified, the String entered for this attribute is used
to create the horizontal rule. For example, style=”*” prints a row of asterisks
across the page.
• <picture> - This element calls an image file that is displayed in the section. This
element has the following attributes:
- filename - This attribute indicates the path for the image file. This path is
relative to the program directory.
- preload - This attribute indicates whether the image file is preloaded into the
memory of the receipt printer, or if the file is loaded from disk every time it is
needed. The possible values for this attribute are:
* true - The image is loaded into the memory of the receipt printer the first
time it is printed, and the image is kept in memory from then on. Up to two
images can be preloaded. If more than two images are set for preloading,
only the first two images printed are kept in memory; the rest are loaded
from disk every time they are called.
* false - The image is loaded from disk every time it is called. (default)
• <signature> - This element displays a signature that was captured electronically.
• <pagebreak> - This element defines the location where a new page begins. On a
receipt printer, this is the location where the paper is cut. If the receipt printer does
not have a paper knife, a message displays, indicating that the cashier should
remove the printed receipt.
Apply a Condition (<condition>)

The <condition> element uses configurable logic that determines whether data is
included in a document. If the logic in a <condition> returns a “true” value, then the
data associated with the <condition> is displayed. If the <condition> returns a
“false”, the data is not displayed.
The <condition> element can be associated with a <section>, or many of the sub-
elements of a <section>. When a <condition> evaluates to “true”, the section or

Section (<section>)
section sub-element is printed on the document. When the <condition> evaluates to

“false”, the section or section sub-element is not printed on the document.
The <condition> element has the following organization:
class Attribute
method Attribute
comparison Attribute
inverted Attribute
type Attribute
tenderId Attribute
value Attribute
method_param Attribute
name Attribute
value Attribute
dtype Attribute
• class - This attribute contains the fully-qualified Java class name used to return a
condition result, or examine the current object.
current object. The data returned is converted to a String and the results are
compared against a value defined in the comparison attribute. If the method
returns a NULL value, the value is appended as a zero-length string.
• comparison - This attribute defines the comparison performed between the data
from the method and a certain, defined value.
• inverted - Indicates whether the Boolean result of the condition should be
inverted.
• method_param - This attribute defines a parameter that is passed to the function
called in the method attribute.
called in the <Class> element, or define the comparison value for the comparison
attribute.
- value - The value that is sent in the parameter. Only used when passing a
parameter to a <Class>. If the value attribute is used, the parameter is sent as
a String. If the parameter being sent has a different data type (such as Boolean),
the <param_value> sub-element must be used, with the dtype attribute
indicating the type of data being sent.

Section (<section>)
Comparison Condition
A simple condition defines a method of the current object to be examined (method), a
comparison to perform (comparison), and—depending on the comparison—a
comparison value (param_value).
The definitions and usage of both the “method” and the “method parameters” elements
are identical to those in any other method field. See “Call a Function (method)” for more
information.
The comparison Attribute defines the comparison to be applied to the method results.
The following values are valid for the comparison attribute:
• EQUAL - The value returned equals another value.
• NOT_EQUAL - The value returned does not equal another value.
• IS_NULL - The value returned by the method is null.
• NOT_NULL - The value returned by the method is not null.
• IS_BLANK - The string returned by the method is blank.
• NOT_BLANK - The string returned by the method is not blank.
• IS_EMPTY - The list returned by the method is empty.
• NOT_EMPTY - The list returned by the method is not empty.
• LESS_THAN - The value returned is less than another value.
• GREATER_THAN - The value returned is greater than another value.
• GREATER_THAN_ZERO - The value returned is positive in sign.
• LESS_THAN_ZERO - The value returned is negative in sign.
• LESS_THAN_OR_EQUAL - The value returned is less than or equal to another value.
• GREATER_THAN_OR_EQUAL - The value returned is greater than or equal to another
value.
• TRUE - The method returned a value of “true”.
• FALSE - The method returned a value of “false”.
The comparison values NULL, NOT_NULL, IS_BLANK, NOT_BLANK, IS_EMPTY,
NOT_EMPTY, TRUE, and FALSE do not require a condition parameter to compare the
value against. All other <comparison> values require a condition parameter to
compare against; the comparison parameter is defined by the <param_value> sub-
element of the <Parameter> element.

Section (<section>)
Condition Examples
The following example shows a condition that checks whether the value returned by
getAmount is greater than zero:
<condition method="getAmount" comparison="GREATER_THAN_ZERO"/>
Another example shows a condition that checks whether the value returned by
getCardType is not equal to the debit value on the card.
<condition method="getCardType" comparison="NOT_EQUAL">

<Parameter name="value" value="DEBIT [60]"/>
</condition>
Example
<condition>
<method dtype="String">getAmount</method>
<comparison dtype="String">GREATER_THAN</comparison>
<Parameter name="VALUE">
<param_value dtype="BigDecimal">0</param_value>
</Parameter>
</condition>
<condition method="getSignature.getSignature"
comparison="NOT_NULL"/>
Condition Class (class)

A class attribute specifies the fully-qualified Java class name used for the condition.
This condition performs comparison operations against the current object or transaction.
The class specified must implement
dtv.pos.docbuilding.conditions.IDocBuilder.
The Java class returns a “true” or “false” value that is used as the value for the
<condition>. If the Java class returns “true”, then the element containing the
<condition> is displayed, while a “false” value means that the element is not
displayed.
In the following example, the condition returns a value of “true” if the transaction
includes a credit card tender:
<condition
class="dtv.pos.docbuilding.conditions.IncludeTenderTypeCondition"
type="CREDIT_CARD"/>

Section (<section>)
This following example returns "true" if the line item tender is a non-foreign travelers
check.
<section name="travelers_check_tender">
<condition
class="dtv.pos.docbuilding.conditions.LineTenderTypeCondition"
value="TRAVELERS_CHECK"/>
<row>
<field method="getTender.getDescription"/>
<field method="getAmount" formatter="Money" loc="-3"/>
</row>
</section>
Multiple Conditions
When there is more than one <condition> for an element, all of the <condition>
sub-elements associated with an element must be met for the element to appear. In other
words, there is an AND operator between the <condition> elements. If any one
<condition> for an element returns a “false” value, the element is not displayed.
Special Condition Classes

There are some special condition classes that examine the current object. The following
list of special condition classes includes a description of the comparison performed by
the class:
• dtv.pos.docbuilding.conditions.InstanceOfCondition - This class
checks whether the current object is an instance of the class or interface specified in
the value attribute.
• dtv.pos.docbuilding.conditions.NotInstanceOfCondition - This class
checks whether the current object is not an instance of the class or interface specified
in the value attribute.
• dtv.pos.docbuilding.conditions.SystemPropertyExistsCondition -
This class checks a specified system property to determine if a value has been set for
it.
• dtv.pos.docbuilding.conditions.VoidedLineCondition - This class
evaluates whether a line item has been voided:
- If the value for the <condition> is set to “true”, the <condition> returns
“true” for voided line items.
- If the value for the <condition> is set to “false”, the <condition> returns
“true” for non-voided line items.
- If no value is set, the <condition> returns “true” for non-voided line items.
The example below shows the use of the InstanceOfCondition class:
<condition
class="dtv.pos.docbuilding.conditions.InstanceOfCondition"
value="dtv.xst.dao.ttr.ICreditDebitTenderLineItem"/>

Section (<section>)
The example below shows the use of the NotInstanceOfCondition class:

<condition>
<Class>dtv.pos.docbuilding.conditions.NotInstanceOfCondition</Class>
<Parameter name=”VALUE”>
<param_value dtype="Class">
dtv.pos.dai.ttr.IForeignTenderLineItem</param_value>
</Parameter>
</condition>
The example below shows the use of VoidedLineCondition in a receipt:

<condition>
<Class>dtv.pos.docbuilding.conditions.VoidedLineCondition</Class>
<Parameter name="VALUE">
<param_value dtype="Boolean">false</param_value>
</Parameter>
</condition>
The example below shows the use of the SystemPropertyExistsCondition class:

<condition>
<Class>dtv.pos.docbuilding.conditions.SystemPropertyExistsCondition
</Class>
<Parameter name="VALUE" value="Store.RegisterConfig.Location.Address2" />
</condition>
The Parent Elements of Conditions

When a <condition> sub-element is placed within different elements, the
<condition> tests are performed in different ways and produce different outputs. The
following list shows each of the elements for which a <condition> can be a sub-
element, and describes how the <condition> is processed within each element:
• <call> - The <method> within the <call> is performed only if the <condition>
returns “true”. This only affects the <call> itself, not the rest of the <section>.
• <iterator> - The data for each iteration is displayed only if the <condition>
returns “true” for that iteration. The value returned by the <condition> in one
iteration does not affect the whether the data for any other iteration is displayed.
Nor does it affect the rest of the <section>.
• <region> - The <region> is displayed only if the <condition> returns “true”.
This only affects the <region> itself, not the rest of the <section>.
• <row> - The <row> is displayed only if the <condition> returns “true”. This only
affects the <row> itself, not the rest of the <section>.
• <section> - The <section> is displayed only if the <condition> returns “true”.
• <textblock> - The <textblock> is displayed only if the <condition> returns
“true”. This only affects the <textblock> itself, not the rest of the <section>.

Section (<section>)
Text Block with Multiple Lines (<region>)

A <region> element formats a block of text that spans multiple lines on a document.
For example, a region can be used to put a paragraph describing the store’s return policy
on a receipt. By using a <region>, line-wrapping rules are applied to the output.
The contents of the field are wrapped at the end of each line using the following order of
preference:
1. An existing line break character in the field.
2. Any whitespace character, as defined by Java (tab, space, etc.).
3. After any character at the end of the line.
The <region> element has the following organization:
<region> Element:
left_margin Attribute
right_margin Attribute
style Attribute
charsize Attribute
align Attribute
alignment Attribute
<condition> Element
<left_margin> Element:
dtype Attribute
<right_margin> Element:
dtype Attribute
<field> Element:
See “Field (<field>)” for the structure and organization of this element.
• <left_margin> - This element determines the width and style of the left margin.
- dtype - This attribute indicates the type of data used for the element, which
affects the margin created. This following values are valid for this attribute:
* Integer - When the dtype attribute is set to this value, the number in the
element defines the number of spaces in the left margin.
* String - When the dtype attribute is set to this value, the string in the
element is used as the actual text in the left margin.
The left_margin attribute performs the same function as the <left_margin>
element. However, by using this attribute, the dtype is interpreted rather than
explicitly set, as it is with the <left_margin> element.
• <right_margin> - This element determines the width and style of the right
margin.
affects the resulting margin. This following values are valid for this attribute:
element defines the number of spaces in the right margin.

Section (<section>)
element is used as the actual text in the right margin.
The right_margin attribute performs the same function as the <right_margin>
element. However, by using this attribute, the dtype is interpreted rather than
explicitly set, as it is with the <right_margin> element.
• style - This attribute determines the style of the text. The following values are
- BOLD - The field is printed using bold text.
- UNDERLINE - The field is printed with underlined text.
- STRONGUNDERLINE - The field is printed with text that is both bold and
underlined.
- ITALICS - The field is printed in italics.
- REVERSE - The field is printed with colors reversed. For example, the field is
printed with white text on a black background, rather than black text on a white
background.
• charsize - This attribute determines the size of the characters in the text. The
- NORMAL - The characters are of normal size.
- DOUBLEHIGH - The characters are of normal width and double height.
- DOUBLEWIDE - The characters are of normal height and double width.
- (X2HW) DOUBLEHIGHDOUBLEWIDE - The characters are of both double height
and double width.
• align (alignment) - The attribute determines the horizontal alignment of the
text. The following values are preconfigured for the attribute:
- (L) LEFT - Field information begins on the left edge of the field. (default)
- (R) RIGHT - Field information begins on the right edge of the field.
- (C) CENTERED - Field information is centered within the field.
displayed. If this condition returns a “false”, the data is not displayed. See “Apply a
Condition (<condition>)” for a full description of the <condition> element, its use,
and its structure.
• <field> - This element determines the contents displayed in the <region>. See
“Field (<field>)” for more information.
Simple <region> Example

An example of a simple <region> is shown here:
<region>
<field formatter=”RCPTTRANSLATOR”>
<text dtype=”String”>_creditCardPurchaseTerms</text>
</field>
</region>

Section (<section>)
If the key _creditCardPurchaseTerms is defined as:

_creditCardPurchaseTerms =000000000111111111122222222223333333333412345678901
23456789012345678901234567890\n\nCardholder will pay card issuer above amount
pursuant to Cardholder Agreement\n\nLe Titulaire versera ce montant a
L'émetteur conformement au contrat adhérant.
The sample <region> defined above would produce the following output:
0000000001111111111222222222233333333334
1234567890123456789012345678901234567890
Cardholder will pay card issuer above

amount pursuant to Cardholder Agreement
Le Titulaire versera ce montant a

L'émetteur conformement au contrat
adhérant
Integer <left_margin> and <right_margin> Example

A sample <region> element with Integer margins is shown below.
<region align="C" left_margin="2" right_margin="2">

<field text="_loyaltyCardInvalidMsg"/>
</region>
If the key _loyaltyCardInvalidMsg is defined as:
_loyaltyCardInvalidMsg=**NOTICE**\nThis loyalty card has expired or has one

or more expired accounts.
The sample <region> defined above would produce the following output:
**NOTICE**
This loyalty card has expired or has one or more
expired accounts.

Section (<section>)
The sample <region> with Integer margins produces the following results:
000000000111111111122222222223333333
333412345678901234567890123456789012
34567890
Cardholder will pay card issuer

above amount pursuant to Cardholder
Agreement
Le Titulaire versera ce montant a

L'émetteur conformement au contrat
adhérant
String <left_margin> and <right_margin> Example

An example of a <region> with String margins is shown below.
<region>
<left_margin dtype=”String”><![CDATA[* ]]></left_margin>
<right_margin dtype=”String”><![CDATA[ *]]></right_margin>
<field formatter=”RCPTTRANSLATOR”>
<text dtype=”String”>_creditCardPurchaseTerms</text>
</field>
</region>
The sample <region> with String margins produces the following results:
* 000000000111111111122222222223333333 *
* 333412345678901234567890123456789012 *
* 34567890 *
* *
* Cardholder will pay card issuer *
* above amount pursuant to Cardholder *
* Agreement *
* *
* Le Titulaire versera ce montant a *
* L'émetteur conformement au contrat *
* adherent *

Section (<section>)
Field (<field>)
This section describes several different types of fields and how they are used. A field
may have a Formatter associated with it that will change the way the field is displayed.
There are four different types of fields that can be configured. These field types are
configured through the inclusion of certain sub-elements of the <field> element. There
can be only one of these sub-elements in each <field> element. These field types and
their associate sub-elements are the following:
• Text - A field that displays pre-defined text. Uses a <text> element or text
attribute.
• Method - A field that displays the output of a function. Uses a method attribute.
• System Property - A field that displays the value of a system property. Uses a
systemproperty attribute.
• Aggregate - A field that calls a Java class that then retrieves information from
multiple locations. Uses an <aggregate> element.
The <field> element has the following organization:
<field> Element:
formatter Attribute
text Attribute
style Attribute
align Attribute
loc Attribute
method Attribute
systemproperty Attribute
<text> Element:
dtype Attribute
<aggregate> Element:
class Attribute
contents Attribute
• <text> - This element contains either a CDATA string or a preconfigured text

variable to display text in the generated document. Contents determined by text
variables use translation keys and ITranslator to determine the text displayed. Can
also be an attribute.
* dtype - Indicates the type of information that is displayed. The only valid
value for this attribute is “String”.
• <aggregate> - This element is used to call a class that then retrieves information
from multiple locations.
* class - This attribute contains the fully-qualified Java class name that is
called from within the <aggregate> element.
* contents - This attribute defines the text string that is passed to the Java
class in the class attribute. The String can be either a CDATA string, or a

Section (<section>)
preconfigured text variable. Contents defined by text variables use

translation keys and ITranslator to determine the text displayed.
• formatter - This attribute determines the name of the <Formatter> that is used
to format the output. See “Formatter (<Formatter>)” for more information about the
<Formatter> element.
• style - This attribute determines the font style used when printing the output. The
underlined.
background.
• align - The attribute determines the horizontal alignment of the text. The following
values are preconfigured for the attribute:
- (L) LEFT - Field information begins on the left edge of the field (default when
no <location> is specified).
- (R) RIGHT - Field information begins on the right edge of the field.
- (C) CENTERED - Field information is centered within the field.
• loc - This attribute determines the horizontal placement of a field, as measured by
the number of character positions from the left or right margin. If this attribute is
included in the <field>, the align attribute is not needed.
The horizontal placement and alignment of the text depends upon whether the value
for the loc attribute is positive or negative.
- If the value is positive, the number indicates how many characters from the left
margin that the field is positioned. The field is left-aligned.
- If the previous field is so long that this position causes an overlap with the
previous field in the row, the field is placed in the next available position from
left to right.
- If the value is negative, the number indicates how many characters from the
right margin that the field is positioned. The field is right-aligned.
- If this position causes an overlap with the previous field in the row, the field is
placed in the next available position from right to left.
current object. The data returned is converted to a String and appended to the
<field>. If the method returns a NULL value, the value is appended as a zero-
length string. See “Call a Function (method)” for more information.
• method_param - This attribute defines a parameter that is passed to the function
called in the method attribute.
• systemproperty - This attribute retrieves the value for the named system
property and outputs that value. Values can be accessed from master, store, or
station configurations using the full xpath of the configured value.

Section (<section>)
• <priority> - This element determines which fields may overtype other fields. If a
field overlaps another field, the <priority> tag is used to determine which field is
displayed in the overlapping area. The values of the <priority> elements are
compared, and the <field> with the higher <priority> value is displayed.
When two fields have equal priorities, the field that appears later in the definition is
given a higher priority.
The default <priority> for each <field> is zero.
for this attribute is “Integer”.
PRIORITY EXAMPLE
If the receipt printer has 40 characters per line and the description field exceeds 20 characters, the quantity
field overtypes it. This would occur because the description field does not have a defined priority (it
defaults to zero) but the quantity field has a defined priority of “1”.
If the extended price is more than 10 characters wide, it will overtype the quantity since they both have a
defined priority of 1, but the extended price field is defined after the quantity field.
<row>
<field>
<priority dtype=”Integer”>0</priority>
<method dtype="String">getItem.getDescription</method>
</field>
<field>
<location dtype="Integer">-20</location>
<priority dtype="Integer">1</priority>
<method dtype="String">getQuantity</method>
</field>
<field>
<method dtype="String">getExtendedPrice</method>
</field>
</row>

Section (<section>)
Call a Function (method)

The method attribute can be an attribute of the <condition> and <field> elements.
It is used to call a function that is then performed on the current object. The data
returned is converted to a String and either compared to another value, or used as
output for the receipt printer. If the method returns a NULL value, the value is appended
as a zero-length String.
method Example
In the following example, the method getTransactionSequence is invoked on the
current object. Because no iterators are encountered, the object should implement
IPosTransaction. This method returns a long value which is converted to a String
and appended to the receipt document.
<field method="getTransactionSequence"/>
method Chain Example

Methods may be chained to access lower-level objects. In the following example, the
method attribute first calls the function getOperatorParty on the object
implementing IPosTransaction. This function returns an object implementing
IParty. This object is then passed to the function getEmployeeId, which returns a
String. The String is then appended to the document.
<field method="getOperatorParty.getEmployeeId"/>
<method_param> Example
Some functions called by the method attribute may require parameters to be sent to
them. The <method_param> element is used to send these parameters to the called
function.
<call method="getTaxModifiers">
<call method="get">
<method_param dtype="Integer">0</method_param>
<sectionref>SINGLE_TAX_SUBSECTION</sectionref>
</call>
</call>
Looping Iterator (<iterator>)

The iterator element is used on a collection of data returned by a method. Rather than
examining the collection as a whole, the <iterator> allows processes to be performed
on each item in the collection in turn. The <iterator> performs one iteration loop for
each data item in the collection. The output of each <iterator> loop is appended to
the document being created.
The <iterator> element has the following organization:
<iterator> Element:
method Attribute
dtype Attribute

Section (<section>)
See “Apply a Condition (<condition>)” for the organization of this
element.
<item_comparator> Element:
dtype Attribute
The following sub-elements of <iterator> are identical to those in
the <section> element. See “Section (<section>)” and, if available, the
element-specific section for more information on the organization of
the sub-elements listed below.
<iterator> Element:
As described in this section.
<row> Element
<region> Element:
See “Text Block with Multiple Lines (<region>)” for the organization of
this element.
See “Multiple Lines of Text from com_receipt_text (<textblock>)” for
the organization of this element.
<call> Element
<barcode> Element:
See “Barcode (<barcode>)” for the organization of this element.
<picture> Element
<horizontal_rule> Element
<signature> Element
<pagebreak> Element:
<percent_width> Element
current object. The data returned by the method function is a collection of data, a
subtype of a collection, or an array of any type. The <iterator> loops once for
each data item in the collection. If the method returns a NULL value, the
<iterator> loop does not perform any processing.
called in the method. Can also be an attribute.
process the current data item from the collection. If this condition returns a “true”
value, then the <iterator> processes the data in the current data item. If this
condition returns a “false”, the data item is not processed and the <iterator> loop
continues with the next data item in the collection. See “Apply a Condition
(<condition>)” for a full description of the <condition> element and its structure.
• <item_comparator> - This element specifies the fully-qualified class used to sort
the data collection created by the method. This class implements the
java.util.Comparator class.

Section (<section>)

<item_comparator> element. The only valid value for this attribute is
“Class”.
• <iterator> - This element processes a collection of data returned by a method.
Rather than examining the collection as a whole, the <iterator> allows processes
to be performed on each item in the collection. An <iterator> element can be
nested within another <iterator>.
• <row> - This element is a collection of field definitions that is followed by a line
break.
• <region> - This element defines an area of the document that can contain multiple
lines of text. Text-wrapping rules are automatically applied to text defined in a
<region>. See “Text Block with Multiple Lines (<region>)” for more information.
• <textblock> - Like the <region> element, this element defines an area of the
document that can contain multiple lines of text. Text-wrapping rules are
automatically applied to text defined in a <textblock>. However, a <textblock>
element accesses text from the com_receipt_text table in the database. See
“Multiple Lines of Text from com_receipt_text (<textblock>)” for more information.
• <call> - This element changes the current object. By calling a method (and its
associated <method_param> elements) on the object that is presently the current
object, the result of the method becomes the current object within the <call>
element. This new current object is also the current object for all sub-elements of the
<call> element. See the examples in “Call New Object (<call>)” for examples of the
<call> element.
• <sectionref> - This element references another <section> by name. When the
<sectionref> sub-element is called within a <section> (the current
<section>), the data within the named <section> is included as part of the
current <section>. This allows a document section to be reused in more than one
place and in more than one type of document. Note that the named <section>
runs in the same context with the same current object as the current <section>.
• <picture> - This element calls an image file that is displayed in the section. This
element has the following attribute:
- filename - This attribute indicates the path for the image file. This path is
relative to the program directory.
• <horizontal_rule> - This element indicates that a horizontal line is drawn across
the document. If this element contains a <field> sub-element, the data in the
<field> sub-element is the prefix for the horizontal line. (See <horizontal_rule>.)
• <signature> - This element displays a signature that was captured electronically.
• <pagebreak> - This element defines the location where a new page begins. On a
receipt printer, this is the location where the paper is cut. If the receipt printer does
not have a paper knife, a message displays, indicating that the cashier should
remove the printed receipt.
• <percent_width> - This element indicates the percentage width of the paper that
is cut. This element is only valid on receipt printers that support partial cuts. On
receipt printers that do not support partial cuts, the width is always 100%. Default
value is 100%.

Section (<section>)
Custom Iterator: Iteration on Multiple Objects and Methods

In some cases there may be items that must be iterated but are not available from a single
method on a single object. A custom iterator implementation can be created to handle
that kind of situation.
Processing tax exempt modifiers presents such a situation. Modifiers can be spread
across all of the item lines in a transaction. Typically, each exempted tax should be
reported only once, not multiplied by the number of items that use those taxes.
A custom class was created that extends dtv.docbuilding.DocBuilderIterator:
dtv.pos.register.tax.TaxModifierIterator
The custom iterator overrides the iterate (IPosDocument, IDocElementFactory, Object)

method. Within this method, a collection is created that collects only the objects that
must be iterated. This collection is then passed to the iterateCollection (IPosDocument,
Collection, IDocElementFactory) method.
The example below shows a custom iterator implementation for tax modifiers:
<iterator>
<impl dtype="Class">dtv.pos.register.tax.TaxModifierIterator</impl>
<!—contents of the iterator would be configured here-->
</iterator>
Multiple Lines of Text from com_receipt_text (<textblock>)

A <textblock> element is similar to a <region> element, in that they both define an
area that contains multiple lines of text, and they both automatically apply text-
wrapping rules. Unlike the <region> element, the <textblock> element accesses text
from the com_receipt_text table in the database. Uses of this element include credit
or return terms, disclosures, warranty information, and other information that is
condition or date sensitive. The table includes effective and expiration dates for the text
used. See the Xstore Point of Service Database Dictionary for more information about the
com_receipt_text table.
The <textblock> element has the following organization:
dateMethod Attribute
style Attribute
charsize Attribute
alignment Attribute
See “Apply a Condition (<condition>)” for the organization of this
element.
<left_margin> Element:
dtype Attribute
<right_margin> Element:
dtype Attribute

Section (<section>)
<DateMethod> Element:
dtype Attribute
<code> Element:
dtype Attribute
method Attribute
text Attribute
<text> Element:
dtype Attribute
<method> Element:
dtype Attribute
dtype Attribute
<systemproperty> Element:
dtype Attribute
<Class> Element
<contents> Element:
dtype Attribute
<subcode> Element:
dtype Attribute
text Attribute
method Attribute
<text> Element:
dtype Attribute
<method> Element:
dtype Attribute
dtype Attribute
<systemproperty> Element:
dtype Attribute
<Class> Element
<contents> Element:
dtype Attribute
• dateMethod - This attribute contains the name of the function that is run to
determine the current date. This date is used to evaluate effective and expiration
dates configured for the text in the com_receipt_text table.

Section (<section>)
• <code> - This element determines the text_code value searched for by the
database query.
- method - This attribute contains the name of the function that is performed on
the current object. The data returned is converted to a String and entered into
the query. If the method returns a NULL value, the value is entered as a zero-
- text - This attribute contains either a CDATA string or a preconfigured text
variable that determines the text for the query. Contents determined by text
variables use translation keys and ITranslator to determine the query text.
• <subcode> - This element is used to determine the text_subcode value searched
for by the database query.
- method - This attribute contains the name of the function that is performed on
the current object. The data returned is converted to a String and entered into
the query. If the method returns a NULL value, the value is entered as a zero-
- text - This attribute contains either a CDATA string or a preconfigured text
variable that determines the text for the query. Contents determined by text
variables use translation keys and ITranslator to determine the query text.
• style - This attribute determines the style of the text. The following values are
underlined.
background.
• charsize - This attribute determines the size of the characters in the text. The
- NORMAL - The characters are of normal size.
- DOUBLEHIGH - The characters are of normal width and double height.
- DOUBLEWIDE - The characters are of normal height and double width.
- DOUBLEHIGHDOUBLEWIDE - The characters are of both double height and
double width.
• alignment - The attribute determines the horizontal alignment of the text. The
- LEFT - Field information begins on the left edge of the field. (default)
- RIGHT - Field information begins on the right edge of the field.
- CENTERED - Field information is centered within the field.
displayed. If this condition returns a “false”, the data is not displayed. See “Apply a

Section (<section>)
Condition (<condition>)” for a full description of the <condition> element, its use,
and its structure.
• <left_margin> - This element determines the width and style of the left margin.
affects the margin created. This following values are valid for this attribute:
element defines the number of spaces in the left margin.
element is used as the actual text in the left margin.
• <right_margin> - This element determines the width and style of the right
margin.
affects the resulting margin. This following values are valid for this attribute:
element defines the number of spaces in the right margin.
element is used as the actual text in the right margin.
• <DateMethod> - This element contains the name of the function that is run to
determine the current date. This date is used to evaluate effective and expiration
dates configured for the text in the com_receipt_text table.
- dtype - This attribute indicates the type of data returned by the method. The
• <code> - This element determines the text_code value searched for by the
database query.
• <text> - This element contains either a CDATA string or a preconfigured text
variable that determines the text for the query. Contents determined by text variables
use translation keys and ITranslator to determine the query text.
- dtype - Indicates the type of information for the query. The only valid value for
this attribute is “String”.
• <method> - This element contains the name of the function that is performed on the
current object. The data returned is converted to a String and entered into the query.
If the method returns a NULL value, the value is entered as a zero-length string. See
“Call a Function (method)” for more information.
- dtype - This attribute indicates the type of data that is returned by the function.
The only valid value for this attribute is “String”.
called in the <method> element.
• <systemproperty> - This attribute retrieves the value for the named system
property and returns that value for the query. Values can be accessed from master,
store, or station configurations using the full xpath of the configured value.
- dtype - This attribute indicates the type of data returned from the property.
• <aggregate> - This element is used to call a class that then retrieves information
from multiple locations.

Section (<section>)
• <Class> - This element contains the fully-qualified Java class name that is called
from within the <aggregate> element.
• <contents> - This element defines the text string that is passed to the Java class in
the <Class> element. The String can be either a CDATA string, or a preconfigured
text variable. Contents defined by text variables use translation keys and ITranslator
to determine the text displayed.
- dtype - This attribute indicates the type of data being sent by the <contents>
element. The only valid value for this attribute is “String”.
• <subcode> - This element is used to determine the text_subcode value searched
for by the database query.
<textblock> Ordering and Formatting

The receipt text from the com_receipt_text table is retrieved by a query that uses the
store’s Organization ID and Region, and the values retrieved through the datemethod
attribute and the <code>, and <subcode> elements. The query retrieves the
receipt_text field from each matching, currently valid record.
The records from the DEFAULT region and the store’s specific region are retrieved and
placed in order of text_seq. If any records from the DEFAULT region and the store’s
region have matching text_seq fields, the region-specific record is kept and the
DEFAULT region’s record is removed. The receipt_text values are combined into a
single string, with spaces added between separate records.
The assembled string is output to the receipt printer, with line-wrapping rules applied in
the following order of preference:
1. An existing line break character in the field.
2. Any whitespace character, as defined by Java (tab, space, etc.).
3. After any character at the end of the line.
Barcode (<barcode>)
A <barcode> element is used to print a value as a barcode.
The <barcode> element has the following organization:
<barcode> Element:
symbology Attribute
textposition Attribute
<field> Element:
See “Field (<field>)” for the organization of this element.
• symbology - This attribute defines the type of barcode displayed.

The symbology attribute supports the following values:
Codabar EAN 8 with supplemental barcode
Code 39 EAN 13
Code 93 EAN 13 with supplemental barcode
Code 128 EAN-128
MAXICODE UPC-A

Section (<section>)
POSTNET UPC-A with supplemental barcode
PLANET UPC-E
Standard 2 of 5 UPC-E with supplemental barcode
Interleaved 2 of 5 UPC-D1
OCR "A" UPC-D2
OCR "B" UPC-D3
PDF 417 UPC-D4
EAN 8 UPC-D5
• textposition - This attribute defines the location of barcode text in relation to the
barcode itself. This element has the following possible values:
* ABOVE - The text is placed above the barcode.
* BELOW - The text is placed below the barcode.
* NONE - There is no barcode text.
• <field> - This element defines the portion of the document that is reserved for the
barcode. See “Field (<field>)” for more information. The output of the <field> is
then formatted into a barcode.
Call New Object (<call>)

A call is a means to change the current object within a <call> element. A <method>
called on the current object changes the current object to a new object. This makes
<method> chains more manageable when several chains are required, and it allows the
use of <sectionref> elements calling sections that implement different objects.
The example below shows a full customer name without a call.
<row>
<field>
<method dtype=”String”>getCustomerParty.getFirstName</method>
</field>
<field>
<text dtype=”String”><![CDATA[ ]]></text>
</field>
<field>
<method dtype=”String”>getCustomerParty.getLastName</method>
</field>
</row>

Section (<section>)
The example below shows a full customer name that begins with a call to
getCustomerParty.
<call>
<method dtype=”String”>getCustomerParty</method>
<row>
<field>
<method dtype=”String”>getFirstName</method>
</field>
<field>
</field>
<field>
<method dtype=”String”>getLastName</method>
</field>
</row>
</call>
The example below shows the use of nested <call> elements to implement sections
through <sectionref>:
<call method="getRetailTransactionLineItems">
<call method="get">
<method_param dtype="Integer">0</method_param>
<sectionref>SINGLE_TAX_EXEMPT</sectionref>
<sectionref>MULTIPLE_TAX_EXEMPT</sectionref>
</call>
</call>
About Formatters and Custom Fields

When creating a new DocBuilder field, always make a call to the formatter when
outputting its results. This guarantees that the display and formatting of the result text is
customizable and consistent with other fields.
DocBuilder field
<field formatter="Quantity">
<aggregate class="dtv.pos.common.rcpt.SoldItemsCountDocBuilderField"/>
</field>

Section (<section>)
About Aggregate Fields

There are several special cases where the information that constitutes a field must be
accessed from multiple locations in an object graph. For those cases the aggregate field
type may be used.
An aggregate field is created by writing a class that implements
dtv.pos.docbuilding.IDocBuilderField and has a constructor with a method
signature (String, String, int, int, IFormatter).
public AbstractDocBuilderField(
String argContents, String argStyle, Integer argLocation,
DocBuilderAlignmentType argAlignment, int argPriority,
IOutputFormatter argFormatter)
In the following example, a TranBarcodeDocBuilderField object is instantiated and

the current transaction is passed to it when the field is reached during the building of the
document. This custom field is able to access the business date, store number, register
number, and transaction sequence from the transaction, transform them into a custom
compact format, and return the value to the barcode element that encloses it. The
barcode element can then render the field as a barcode in Code 93 format. The example
below shows a Transaction Barcode accessed from multiple methods.
<barcode symbology="Code 93">

<field>
<aggregate class="dtv.hardware.barcode.TranBarcodeDocBuilderField"/>
</field>
</barcode>

Section (<section>)
About Fields Within Fields

A field may be comprised of other fields. Placing multiple fields inside another field
allows fields to be grouped for alignment or formatting purposes. When a document is
built with this type of field, the contained fields are evaluated and appended to form the
contents of the parent field. Any alignment or style specified on a contained field is
ignored. A separator can be configured as a field with a tag name of separator. The
result of this field is placed between each of the other fields.
The example below shows a field that contains three other fields and a separator field.
<region>
<field>
<field>
<text dtype=”String”><![CDATA[You have earned]]></text>
</field>
<field>
<method dtype=”String”>getPoints</method>
</field>
<field>
<text dtype=”String”><![CDATA[points with this purchase.]]> </text>
</field>
<separator dtype=”Field”>
</separator>
</field>
</region>

Section (<section>)
Method Parameters (<method_param>)

When a field is a “method field”, method parameters may also be defined. Any number
of parameters may be specified for a method call. If the method definition is a list of
methods, the parameters are used only on the first method in the list.
The data type (dtype) of the “method_param” element determines the data type of the
parameter. In the following example, the method getLineItemsByTypeCode is called
(with a single parameter type of “String”) and the parameter “TENDER” is passed to it.
In the example below, a receipt that contains a method parameter is shown.
Method dtype=”String”>getLineItemsByTypeCode</method>
Method_param dtype=”String”>TENDER<method_param>
Figure 9-1: Sample Method Parameter in a Receipt
The valid “dtype” values for a method parameter are the configuration types that
implement dtv.pos.framework.config.IReflectionParameterCapable. The values are:
• String
• Boolean
• Integer
• PositiveInteger
• Class
• Color
• Date
• DoubleArray
• Float
• Icon
• IntegerArray.
Other Field Elements

A field may have one or more elements that describe its formatting and appearance in
the document. Those other field elements are:
• Field Style
• Field Location
• Field Alignment
• Field Priority
Field Style (style)

The field style can be one of the following options:
• BOLD: indicates that the field should be printed using a heavier weight font than
normal.
• UNDERLINE: indicates that the field should be printed with a normal weight
underline.

Section (<section>)
• UNDERLINESTRONG: indicates that the field should be printed with a stronger

than normal weight underline. On some printers this may appear the same as
UNDERLINE.
• ITALICS: indicates that the field should be printed using an italicized font.
• REVERSE: indicates that the field should be printed using reversed video (that is,
white on black instead of black on white).
Note: “Normal” is the default value for the printer. The actual value
can be found in the manufacturer’s guide for the specific device.
Field Location (<location>)

Location indicates the placement of a field as measured by the number of character
positions from either the left or right margin.
• If a positive location is selected, the number indicates how many characters from
the left margin the left edge of the field should be positioned. (If the previous field is
so long that this position causes an overlap with the previous field in the row, the
field is placed in the next available position from left to right.)
• If a negative location is selected, the number indicates how many characters from
the right margin the right edge of the field should be positioned. (Again, if this
position causes an overlap with the previous field in the row, the field is placed in
the next available position from left to right.)
In the following example, four fields in the first row define the column headers on a
receipt. The first field has no location specified, but since it is the first field in the row, it
has an implicit location of “1” and starts in the first column of the line. The next field has
a location of “14”, so it starts on the 14th column of the line.
The next field has a location of “-13”, so it is right-aligned and it ends in the 13th column
from the right margin. The location of the last field is “-1”, so it is right aligned and it
ends in the last column of the line.
On a receipt printer with 44 characters per line, the line would look like the following
example.
+00000000011111111112222222222333333333344444+
+12345678901234567890123456789012345678901234+
-44444333333333322222222221111111111000000000-
-43210987654321098765432109876543210987654321-
Item Qty Price Amount

Section (<section>)
The example below shows the configuration of an item header in a receipt.

<row style=”STRONGUNDERLINE”>
<field formatter=”RCPTTRANSLATER”>
<text dtype="String">_item</text>
</field>
<field formatter="RCPTTRANSLATER">
<location dtype="Integer">14</location>
<text dtype="String">_qty</text>
</field>
<text dtype="String">_price</text>
</field>
<text dtype="String">_amount</text>
</field>
</row>
Field Alignment (alignment)

Field alignment is used only in conjunction with a field location and it is an optional
element. The options for field alignment are:
• LEFT
• RIGHT
• CENTERED
If no field alignment is defined, alignment defaults to either LEFT or RIGHT.
If no location or a positive location is specified, LEFT alignment is used.
If a negative location is defined, the default alignment is RIGHT.
When left alignment is specified, the field location is where the left edge of the field
begins.
When right alignment is specified, the field location is where the right edge of the field
begins.
When center alignment is specified, the field location is used as the center of the field.

Section (<section>)
Field Priority (<priority>)

A field priority (<priority>) determines which fields may “overtype” other fields. For
example, if the receipt printer has 40 characters per line and the “description” field
exceeds 20 characters, the “quantity” field overtypes it. That would occur because the
description field does not have a defined priority (it defaults to zero) but the quantity
field has a defined priority of “1”.
When fields have equal defined priorities, the field that appears later in the definition
obtains a higher functional priority. For example, if the extended price were more than
10 characters wide, it would overtype the quantity since they both have a defined
priority of 1, but the extended price field is defined after the quantity field. Usage of this
tag is optional.
A field priority example is shown below.
<row>
<field>
<priority dtype=”Integer”>0</priority>
<method dtype="String">getItem.getDescription</method>
</field>
<field>
<method dtype="String">getQuantity</method>
</field>
<field>
<method dtype="String">getExtendedPrice</method>
</field>
</row>

Section (<section>)

10
Hardware Configuration & Communication
Overview
This chapter describes how hardware is configured and communication is handled in
Xstore Point of Service. This includes an overview of JavaPOS, the application interface
used by Xstore Point of Service, and a description of the files that configure each
peripheral in Xstore Point of Service.
About this Chapter

• “JavaPOS (JPOS) Overview” provides a general overview of JavaPOS.
• “Elements of the JPOS APIs” describes the three basic elements of JavaPOS
interfaces.
• “Generalized Sequence for Using a Device” describes the steps performed when an
application uses a hardware device.
• “Xstore Point of Service and JavaComm” lists the software components that enable
communication between POS hardware devices and the Xstore Point of Service
application.
• “Sample Configuration in jpos.xml: Cash Drawer” shows a sample configuration of
a hardware device through the file jpos.xml.
• “HardwareConfig.xml” describes the elements and attributes used to configure
peripherals in the file HardwareConfig.xml.
• “Code 93 Barcodes” describes the necessity for a barcode printer that can print Code
93 barcodes.
• “Device Settings by Category” lists device categories and the configurable settings in
each of them.
Hardware Configuration & Communication 10-1

JavaPOS (JPOS) Overview
JavaPOS (JPOS) Overview

JavaPOS (JPOS) is an architectural specification for applications that are developed in a
Java environment. It is an implementation of UPOS (Unified Point of Service) which sets
up application interfaces to point-of-sale devices in a retail environment. JavaPOS
defines common ways of working with retail hardware peripheral devices.
JPOS Architectural Components

A Java application such as Xstore Point of Service uses JPOS to interact with hardware
peripherals, including printers, cash drawers, scanners, magnetic stripe readers (MSRs),
and many other devices. These general types of hardware are organized into “device
categories” in the JPOS application programming interface (API), a collection of
interfaces that allow a Java-based application to communicate and interact with a device.
The Java application manipulates a physical device by calling the JPOS APIs that are
available to the device.
A JPOS device includes two components: a device control and a device service.
• JPOS Device Control: the interface between the Java application (Xstore Point of
Service) and the device category (printer, cash drawer, etc.).
• JPOS Device Service: a Java class that implements functionality for a physical
device. Called by the device control through the device service interface.
Figure 10-1: JPOS Architecture Components
JPOS Layers and APIs

Within the JPOS architecture are additional layers and APIs. JPOS uses two packages:
• JPOS Configuration/Loader (JCL): This enables a JPOS device control to bind to the
correct JPOS service control, which in turn provides the functionality for a device.
In Xstore Point of Service, the manager bootstrap class for the JCL is specified in the
file jpos.properties. The manager bootstrap class implements the interface
jpos.loader.JposServiceManager.
• Communications Port API (such as JavaComm API): This enables the Java
application to access devices that use communication methods such as serial,
parallel, and USB.
In Xstore Point of Service, the file jpos.properties specifies a fully qualified
class name that implements the interface jpos.config.JposRegPopulator. This

Elements of the JPOS APIs
enables the application to register the “listeners” that it needs to receive information
from a physical device.
Figure 10-2: Additional JPOS Layers
Elements of the JPOS APIs

JPOS is the collection of interfaces or APIs that enable a Java application, like Xstore
Point of Service, to communicate and interact with a physical device. The various APIs
are comprised of three basic elements:
• Properties: These are the characteristics or settings of a device. Each property is
associated with a type such as Boolean or String. An application may retrieve the
value of a property and set a value for a writable property.
• Methods: These are called by the application to perform or initiate an activity on a
device. A method may require parameters to send or return additional information
to or from a device.
• Events: These enable a device to send a notification back to an application. The
application itself is required to register “listeners” for each type of event notification
that it needs to receive from a device.
Generalized Sequence for Using a Device

Although there may be variations from one application to another, and from one device
to another, the following list represents a typical sequence of steps performed when an
application uses a hardware device.
1. Obtain a device control reference.
2. Register for events (add listeners).
3. Call the open method to instantiate a device service and link it to the device control.
4. If the device requires “exclusive use”, call the claim method.
5. Set the DeviceEnabled property to “true” to make the physical device operational.
6. Use the device.

Xstore Point of Service and JavaComm
7. Set the DeviceEnabled property to “false” to disable the physical device.

8. Call the release method to release exclusive access to the physical device.
9. Call the close method to unlink the device service from the device control.
10. Unregister from events (remove listeners).

Xstore Point of Service is a Java-based application and communicates with hardware
devices via JavaComm, the Java Communications API. The table below lists the software
components that enable communication between POS hardware devices and the Xstore
Point of Service application.
Table 10-1: Xstore Point of Service JavaComm Files
File Name and Location Function and Description
HardwareConfig.xml Lists all of the hardware devices that are

actually being used and assigns a name to
\xstore\lib\config.jar\dtv\res\c each of them; may include other
onfig\ information such as a usage, device type,
and/or assigned port. Each listed device
Or in a configuration path such as must have a corresponding entry in
\xstore\lib\xst-pos.jar\version1\ jpos.xml unless it does not use JavaPOS.
jpos.xml Defines a logical name and the

operational properties for each hardware
\xstore\config\dtv\res\config device that is potentially available to
Or in a configuration path such as: Xstore Point of Service; the actual
properties vary by device, manufacturer
\xstore\cust_config\version1 and model.
If a device has a JavaPOS driver, it will
have an entry in jpos.xml which defines
properties and implementation classes for
that particular piece of hardware. It is also
referenced at the application level in
HardwareConfig.xml which drives it
from the POS level.
jpos.properties Contains the JCL properties options. By

editing this file, you may customize
\xstore\lib\config.jar\jpos\res\ functionality. For example, you can
jpos.properties specify options for selecting a registry
populator class that populates the “entry
registry” and specifies tracing options.
This file also specifies the manager
bootstrap class for the whole JCL.
jpos113.jar This .jar file contains the Java classes that

provide functionality to the various types
\xstore\lib\ext\jpos113.jar of hardware devices, such as printers,
(The number in the filename may change based on the scanners, MSRs, displays, cash drawers,
JPOS version.) etc.

Table 10-1: Xstore Point of Service JavaComm Files (continued)
File Name and Location Function and Description
RXTX.jar This .jar file comprises the classes that are

part of javax.comm, otherwise known as
\xstore\lib\ext\RXTXcomm.jar the Java Communications API, and also
the driver classes—such as
win32driver.class—that enable the
Java application to communicate with the
Windows environment.
Note: The original comm
implementation was preserved for
backward compatibility purposes.
This can be found at
\xstore\lib\windows\comm.jar
or /xstore/lib/linux/comm.jar
javax.comm.properties This .properties file specifies the Java

driver class that is loaded when the Java
\jre\lib\javax.comm.properties application is initialized. The driver class
that is referenced in Windows,
Win32Driver.class, can be found in
the comm.jar file. The driver class that is
referenced in Linux,
com.sun.comm.LinuxDriver, can be
found in the comm.jar file.
win32com.dll This library contains the routines that

enable Java to communicate with serial
\xstore\windows\lib\win32com.dll (COM) ports in the Windows operating
system.
/xstore/linux/lib/
libLinuxSerialParallel
Sample Configuration in jpos.xml: Cash Drawer

The file jpos.xml configures attribute values for hardware devices. These
configurations are specific to the particular vendor device and model number of the
device. The values for these configuration options must be defined in this file.
The file contains both user-specific configurable elements (options that are not
determined by the technical requirements of the system) and system-specific elements.
The configuration information is used internally by Xstore Point of Service to complete a
required task.
<JposEntry logicalName="Epson-TM88IV-Drawer1-USB">
<creation
factoryClass="jp.co.epson.uposcommon.creator.EpsonJposServiceInstanceFactory
" serviceClass="jp.co.epson.upos.core.v1_13_0001.drw.StandardService"/>
<vendor name="SEIKO EPSON" url="http://www.epson.com"/>
<jpos category="CashDrawer" version="1.13"/>
<product description="EPSON Standard CashDrawer Device Service"
name="EPSON Services for JavaPOS(TM) Standard" url="http://www.epson.com"/>

<prop name="OutputTimeout" type="String" value="500"/>
<prop name="epson.trace.file" type="String" value="trace.log"/>
<prop name="OutputBufferSize" type="String" value="65536"/>

<prop name="PinNumber" type="String" value="0"/>

<prop name="ConfigurationFile" type="String" value="epson/xml/Setting/TM-
T88IVSetting.xml"/>
<prop name="WriteThreadInterval" type="String" value="-1"/>
<prop name="TransmitRetryTime" type="String" value="100"/>
<prop name="DeviceID" type="String" value="32"/>
<prop name="SupportStatistics" type="String" value="1"/>
<prop name="QueuingOfflineTimeout" type="String" value="1000"/>
<prop name="MultiDrawerStatusSupport" type="String" value="0"/>
<prop name="EPurasSupport" type="String" value="TRUE"/>
<prop name="ReceiveRetryTime" type="String" value="25"/>
<prop name="TransmitTimeout" type="String" value="5000"/>
<prop name="MemorySwitch" type="String" value="0"/>
<prop name="InputTimeout" type="String" value="100"/>
<prop name="PulseOFFTime" type="String" value="400"/>
<prop name="LogicalPortName" type="String" value="ESDPRT001"/>
<prop name="StatusThreadInterval" type="String" value="100"/>
<prop name="DefaultSlpClampTime" type="String" value="0"/>
<prop name="LogicalPortInterfaceName" type="String" value="EPuras"/>
<prop name="OfflineRetryIntervalTime" type="String" value="25"/>
<prop name="PortNameType" type="String" value="0"/>
<prop name="PortType" type="String" value="2"/>
<prop name="OfflineCount" type="String" value="2"/>
<prop name="InitializeThreadTime" type="String" value="1000"/>
<prop name="PhysicalPrinterName" type="String" value="TM-T88IV"/>
<prop name="PortInterfaceName" type="String" value="USB"/>
<prop name="LogObject" type="String" value=""/>
<prop name="PulseONTime" type="String" value="100"/>
<prop name="InPipe" type="String" value="1"/>
<prop name="ForceSend" type="String" value="0"/>
<prop name="PulseStep" type="String" value="100"/>
<prop name="DeviceDesc" type="String" value="EPSON Standard CashDrawer"/>
<prop name="PortName" type="String" value="TM-T88IV"/>
<prop name="OpenPulseLevel" type="String" value="1"/>
<prop name="ReceiveTimeout" type="String" value="1000"/>
<prop name="OpenWaitTimeout" type="String" value="5000"/>
<prop name="InitializeResponseTimeout" type="String" value="1000"/>
<prop name="InputBufferSize" type="String" value="4096"/>
<prop name="PhysicalDevice" type="String" value="Standard"/>
<prop name="OutPipe" type="String" value="0"/>
<prop name="ReadThreadInterval" type="String" value="-1"/>
<prop name="Upos.Spec_c" type="String" value="false"/>
<prop name="epson.tracing" type="String" value="false"/>
<prop name="epson.trace.max.size" type="String" value="1000"/>
<prop name="DeviceType" type="String" value="1"/>
<prop name="Upos.USB_Serial" type="String" value="false"/>

<prop name="dtvCashdrawerOpenWaitSeconds" type="Integer" value="1"/>
<prop name="dtvDrawerId" type="String" value="1"/>
<prop name="dtvcert" type="Boolean" value="true"/>
<prop name="dtvBeepTimeout" type="Integer" value="30000"/>
<prop name="dtvBeepFrequency" type="Integer" value="1000"/>
<prop name="dtvBeepDuration" type="Integer" value="1000"/>
<prop name="dtvBeepDelay" type="Integer" value="1000"/>
</JposEntry>

Hardware Service in Thin Client

The Xstore Point of Service Mobile hardware service is a Java application that runs as a
separate process on the Xstore Point of Service Mobile thin-client system. This hardware
service is responsible for the JavaPOS hardware interface. It uses a WebSocket
connection to communicate with the Xstore Point of Service Mobile server.
HwsDevices.properties
The HwsDevices.properties file stores configurations for all devices that are
enabled and are used by the hardware service. Each configuration has the following
format:
<JPosEntry name> <FamilyType>:<Usage Code>[,<Usage
Code>][:<Implementation Class on mobile server>]
Where:
• <JPosEntry name> is the name of the JPOS device in the jpos.xml file.
• <FamilyType> is the family of devices to which it belongs (for example,
CashDrawer or MICR). This is the same family type used in the
HardwareConfig.xml file.
This configuration has the following possible values:
- Scanner
- POSPrinter
- CashDrawer
- MICR
- FiscalPrinter
- ElectronicJournal
- LineDisplay
- Biometrics
• <Usage Code>[,<Usage Code>] is a comma-separated list of codes identifying
the uses for the device. These is the same usage codes used in the
HardwareConfig.xml file.
• <Implementation Class on mobile server> is the full name of the class
used to interface with the device.
Examples
• Epson-TMH6000III-Drawer1-USB CashDrawer:CASHDRAWER
• Epson-TMH6000III-Printer-USB POSPrinter:RECEIPT,VALIDATION
• Epson-TMH6000III-MICR-USB MICR:MAIN_MICR
• Zebra-Scanner-USB Scanner:BARCODE_SCANNER
• Crossmatch-FingerprintReader-USB BIOMETRIC:FINGERPRINT:
dtv.hardware.biometric.crossmatch.CrossmatchBiometricDevice
• EftLink-LineDisplay-Proxy ServerSideCustomerDisplay:
CUST_DISPLAY2:dtv.hardware.eftlink.custdisplay.
EftLinkCustDisplay

HwsFamilyTypes.properties
The HwsFamilyTypes.properties file defines the default device handler class and
JavaPOS category mapping configurations for known hardware family types.
Note: This file usually does not need to be modified.
Each configuration has the following format:

<Handler name> <Handler class>,<JPos device>,<JPos category>,
[<Additional constructor parameter>]
where:
• <Handler name> is the name of the device family type.
• <Handler class> is the fully-qualified class name for the device handler.
• <JPos device> indicates whether it is a JPos device.
• <JPos category> indicates the JPos category for the device.
• <Additional constructor parameter> is an additional string value to pass as
a parameter to the device handler class’s constructor.
Example
Scanner oracle.retail.xstore.hardware.service.scanner.Scanner,
true,Scanner
ServerSideScanner java.lang.Object,true,Scanner
POSPrinter
oracle.retail.xstore.hardware.service.posprinter.PosPrinter,true,
POSPrinter
ServerSidePOSPrinter java.lang.Object,true,POSPrinter
CashDrawer
oracle.retail.xstore.hardware.service.cashdrawer.CashDrawer,true,
CashDrawer
ServerSideCashDrawer java.lang.Object,true,CashDrawer
MICR oracle.retail.xstore.hardware.service.micr.Micr,true,MICR
ServerSideMICR java.lang.Object,true,MICR
FISCAL
oracle.retail.xstore.hardware.service.fiscalprinter.FiscalPrinter
,true,FiscalPrinter
ServerSideFISCAL java.lang.Object,true,FiscalPrinter
ElectronicJournal
oracle.retail.xstore.hardware.service.electronicjournal.
ElectronicJournal,true,ElectronicJournal
ServerSideElectronicJournal java.lang.Object,true,POSPrinter
CustomerDisplay
oracle.retail.xstore.hardware.service.linedisplay.LineDisplay,
true,LineDisplay
ServerSideCustomerDisplay java.lang.Object,true,LineDisplay

BIOMETRIC
oracle.retail.xstore.hardware.service.biometrics.Biometrics,
true,Biometrics
ServerSideBIOMETRIC java.lang.Object,true,Biometrics
ServerSideLabelPrinter java.lang.Object,true,POSPrinter
HwsConfig.properties
The HwsConfig.properties file defines the general configuration of the hardware
service and connection details:
This file contains the following configurations:
• SSL Configurations
• Appx Configurations
SSL Configurations
The SSL prefixed keys configure the security for the connection between the hardware
service and the Xstore Point of Service Mobile server. Each key value is entered into a
setter method for the Jetty SslContextFactory. All values are of boolean type (true/
false) and are false by default.
• SSL.ValidatePeerCerts: Determines whether the hardware service will validate SSL
certificates of the peer (default: false).
• SSL.ValidateCerts: Determines whether the hardware service will validate SSL
certificates (default: false).
• SSL.NeedClientAuth: Determines whether the hardware service requires client
authorization (default: false).
• SSL.WantClientAuth: Determines whether the hardware service wants client
authorization (default: false).
• SSL.EnableOCSP: Determines whether CRL Distribution Points Support is enabled
(default: false).
• SSL.TrustAll: Determines whether the hardware service trusts all SSL certificates
when there is no keystore or truststore (default: false).
Note: If set to true, client-side certificate validation is essentially

disabled.
Appx Configurations
The Appx keys determine where the hardware service finds the configuration file
containing the server connection information. This connection information is written by
the Xstore Point of Service Mobile client. It is stored in a subdirectory of the Xstore Point
of Service Mobile client installation.
Note: Because the client is a sandboxed Universal Windows Platform

(UWP) application, it cannot write files outside its installation
directory.
Configuration File
The configuration file is found at:

${Appx.AppData}\${Appx.Triggerfile}
where:
• Appx.AppData: Directory where the configuration file can be found (default:
${LOCALAPPDATA}\\Packages\\${appx.appid}\\LocalState)
where:
- LOCALAPPDATA: An environment variable (present on all Windows 10
systems) pointing to the users application data directory.
- Appx.AppId: Application identifier for the mobile client UWP app. This is a
unique ID of the form:
<Component_Id>_<Vendor_Id_Hash>
where:
* <Component_Id> is the is the fully-qualified class name for the client
application (see Appx.ComponentPrefix). This value is largely constant.
* <Vendor_Id_Hash> is a hash of the Vendor ID. This is unique to each
customer.
For example, the base version of mobile client uses
com.oracle.retail.xstore_f4h6hw8hbrhzm, where f4h6hw8hbrhzm is
a hash for Oracle.
• Appx.TriggerFile: Name of the configuration file (default:
mobileappdata.properties).
Registry
The hardware service is able to retrieve the correct application ID from the Windows
registry. This avoids the need for each configuration to configure the correct application
ID. To do that, it searches for the value of the Appx.ComponentPrefix setting in the
following registry path:
${Appx.RegistryRoot}\\${Appx.RegistryPath}
where:
• Appx.ComponentPrefix: The family name prefix of the mobile application, which is
also the fully-qualified class name for the client application. (default:
com.oracle.retail.xstore). This is used to look up the family name in the
registry.
• Appx.RegistryRoot: The registry root in which to look up the application family
name (default value is blank, which searches all the roots).
Possible values:
- HKCU
- HKLM
- HKCR
• Appx.RegistryPath: The registry path where the family name is set. (default:
SOFTWARE\\Classes\\Local Settings\\Software\\Microsoft\\
Windows\\CurrentVersion\\AppModel\\Repository\\Families)

HardwareConfig.xml
HardwareConfig.xml
The file HardwareConfig.xml lists the devices that are available to the Xstore Point of
Service system, their usages, and the hardware options that are configurable.
The HardwareConfig.xml file has the following organization:
<Hardware> Element:
xmlns:xsi Attribute
<PlaySounds> Element:
dtype Attribute
<ForceDrawerClose> Element:
dtype Attribute
<ShowPrinterDialog> Element:
dtype Attribute
<RemotePrintPort> Element:
dtype Attribute
<PrintTargetFromRemote> Element:
dtype Attribute
<Device> Element:
See “Device (<Device>)” for the organization of this element.
<DeviceList> Element:
type Attribute
use Attribute
<DeviceRef> Element:
use Attribute
translationkey Attribute
literal Attribute
• <Hardware> - This element defines the hardware and hardware options used by
Xstore Point of Service, including definitions for peripheral devices. This element
- dtype - This attribute defines the type of data contained in the element. The
only valid value for this attribute is “Hardware”.
with the XML file.
• <PlaySounds> - This element determines whether Xstore Point of Service uses the
system sound card. This element has the following attribute:
only valid value for this attribute is “Boolean”.

HardwareConfig.xml
* true - Xstore Point of Service uses a sound card.

* false - Xstore Point of Service does not attempt to use a sound card,
disabling all audible alerts and alarms.
• <ForceDrawerClose> - This element determines whether the cash drawer must
be closed before any further processing is permitted. This includes new transactions.
This element has the following attribute:
* true - The cash drawer must be closed before any further processing is
permitted.
* false - Further processing is permitted with the cash drawer open.
• <ShowPrinterDialog> - This element determines whether the Print dialog
window opens when a report printer is used to print a report or a receipt. This
* true - The Print dialog window opens when printing a document on a
receipt printer.
* false - The document is printed immediately after the system receives a
print command. The Print dialog window does not open.
• <RemotePrintPort> - This element defines a network port that is used for receipt
printer sharing. This allows a register to share a printer (determined by the element
<PrintTargetFromRemote>) with a register with a malfunctioning printer. This
only valid value for this attribute is “Integer”.
• <PrintTargetFromRemote> - This element determines which printer is used for
remote printer sharing. This element contains the name of a printer device defined in
a <Device> element in the HardwareConfig.xml file. This element has the
following attribute:
- dtype - This attribute defines the type of data contained in the element.
• <Device> - This element defines the peripheral devices available to Xstore Point of
Service. For more information about this element, see “Device (<Device>)”.
• <DeviceList> - This element, if specified, defines a selection list of devices to
choose from in a given context. Each device in the <DeviceList> selection list is
defined by a <DeviceRef> element. The selection list defined is displayed to the
user, who then chooses the device to use.
For example, if a user is performing transactions on a handheld running Xstore Point
of Service, a <DeviceList> could be used to create a list in which the user would
select a receipt printer from a list of possible printers.
This element has the following attributes:
- type - This attribute indicates the type of peripherals contained in the
<DeviceList>.

HardwareConfig.xml
- use - This attribute indicates the manner in which the peripherals are used.
• <DeviceRef> - This element refers to a <Device> by its use. The hardware
peripheral indicated by the <Device> is then included in the selection list defined
by the <DeviceList> of which the <DeviceRef> is a sub-element. This element
- use - This attribute refers to a <Device> by the use value of the <Device>
included in the <DeviceList>.
- translationkey - This attribute contains a preconfigured, translatable text
variable used to display text in the output. The translated output uses
translation keys and internationalization settings to determine the text
displayed. The output of this element is displayed as the device name in the
device list.
- literal - This attribute contains a string that is displayed as the name of the
device in the device list.
Device (<Device>)
The <Device> element defines the properties of the peripheral hardware devices used
by Xstore Point of Service. These devices include hardware such as customer displays,
cash drawers, handhelds, pinpads, printers, scanners, and magnetic stripe readers.
These devices can be directly connected to the Xstore Point of Service system, or they can
be accessed through the network.
The <Device> element has the following organization:
<Device> Element:
type Attribute
use Attribute
<name> Element:
dtype Attribute
<host> Element:
dtype Attribute
<OpenPulseLevel> Element:
dtype Attribute
<Enabled> Element:
dtype Attribute
<RemoteHost> Element:
dtype Attribute
<RemotePort> Element:
dtype Attribute
<PollInterval> Element:
dtype Attribute
<impl> Element:
dtype Attribute
• <Device> - This element defines the peripheral devices available to Xstore Point of
Service. The element has the following attributes:

HardwareConfig.xml
- type - This attribute indicates the type of peripheral that is being configured.
- use - This attribute indicates the manner in which the peripheral is used.
• <name> - This element defines the name used to refer to the device. For example,
this is the name used to configure the JPOS interface in the jpos.xml file. This
• <host> - Overrides the “host” property (<prop name=”host” .../>) for the
device in the jpos.xml file. This element overrides this specific hardware setting on
a per-device basis. (vendor/driver specific)
• <OpenPulseLevel> - Overrides the “OpenPulseLevel” property (<prop
name=”OpenPulseLevel” .../>) for the device in the jpos.xml file. This
element overrides this specific hardware setting on a per-device basis. (vendor/driver
specific)
• <Enabled> - This element determines whether the device is enabled for access. This
* true - The device is enabled for access.
* false - The device is not enabled and Xstore Point of Service will not
attempt to access it.
• <RemoteHost> - This element defines the host to connect to when accessing a
network device, such as a remote printer. (vendor/driver specific)
• <RemotePort> - This element defines the port to connect to on the <RemoteHost>
when accessing a network device. (vendor/driver specific)
• <PollInterval> - This element defines the polling frequency used in the
connection to a <RemoteHost>. (vendor/driver specific)
• <impl> - This element defines the fully-qualified name for the Java class used to
implement the device. This element has the following attribute:
only valid value for this attribute is “Class”.

HardwareConfig.xml
Sample HardwareConfig.xml
<Hardware xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="HardwareConfig.xsd">
<PlaySounds dtype="Boolean">true</PlaySounds>
<ForceDrawerClose dtype="Boolean">true</ForceDrawerClose>
<ShowPrinterDialog dtype="Boolean">false</ShowPrinterDialog>
<RemotePrintPort dtype="Integer">${dtv.hardware.remotePrintPort}</
RemotePrintPort>
<PrintTargetFromRemote dtype="String">RECEIPT</PrintTargetFromRemote>
<Device type="POSPrinter" use="RECEIPT">
<name dtype="String">Generic-Printer-Log4j</name>
</Device>
<Device type="POSPrinter" use="RECEIPT_BACKUP">
<name dtype="String">Generic-Printer-Laser</name>
</Device>
<Device type="POSPrinter" use="RECEIPT1">
</Device>
</Device>
</Device>
</Device>
<DeviceList type="POSPrinter" use="RECEIPT">
<DeviceRef use="RECEIPT1" translationkey="_RcptPrinter1"/>
</DeviceList>
<Device type="PinPad" use="MAIN_PINPAD">
<name dtype="String">Ingenico-65XX-PINPad-RS232</name>
<impl dtype="Class">dtv.hardware.ingenico.jpos.Ingenico65xxFormDevice</
impl>
<portName dtype="String">/dev/ttyS0</portName>
</Device>
.....
</Hardware>

Code 93 Barcodes
Code 93 Barcodes
The ability to produce “Code 93” barcode format is an important feature in Xstore Point
of Service. Receipt printers and barcode scanners must be able to use this code because it
is the format used for transaction barcodes that are printed on a receipt. A receipt printer
must be able to print a Code 93 barcode that is 21 characters wide
Selecting a printer without sufficient Code 93 support may impose limitations. For
example, transaction sequence numbers may be limited to a maximum of 9999, register
numbers may be limited to a maximum of 99, and there may be other types of
undesirable restrictions.
Device Settings by Category

This section lists device categories and the configurable settings in each of them.
POS Printer Settings - jpos.xml

Table 10-2: POS Printer Settings (Sheet 1 of 3)
Setting Type Default Description
dtvCapPapercut Boolean true If true, the

jpos.POSPrinter.cutPaper
method will be used for page breaks.
Otherwise, a prompt to “Tear the
receipt” is displayed.
dtvCharacterSet Integer none If a value is configured for

dtvCharacterSet, the
jpos.POSPrinter.
setCharacterSet method is called
with this value. Note: the available
character sets are logged from
dtv.hardware.posprinting.
DtvPosPrinter at the INFO level at
device startup.
dtvFrankingPadLines Integer 0 Number of lines that should be

added to advance before franking a
check or other document in the
printer's validation station.
dtvFrankingPadSpace Integer 12 How many spaces should be added

s to each line when franking a check or
other document in the printer's
validation station.
dtvHorizontalRuleCh String none The character defined here will be

arDouble used in combination with
dtvHorizontalRuleFormatting
Double when a double horizontal
rule needs to be printed.

arHigh used in combination with
High when a high horizontal rule
needs to be printed.

Table 10-2: POS Printer Settings (Sheet 2 of 3) (continued)

arMid used in combination with
Mid when a mid horizontal rule
needs to be printed.

arNormal used in combination with
Normal when a normal horizontal

arStrong used in combination with
Strong when a strong horizontal
dtvHorizontalRuleFo String none The formatting codes defined here

rmatting will be used in combination with
dtvHorizontalRuleCharDouble
Double
when a double horizontal rule needs
to be printed.

dtvHorizontalRuleCharHigh
High
when a high horizontal rule needs to
be printed.

dtvHorizontalRuleCharMid
Mid
when a mid horizontal rule needs to
be printed.

dtvHorizontalRuleCharNormal
Normal
when a normal horizontal rule needs
to be printed.

dtvHorizontalRuleCharStrong
Strong
when a strong horizontal rule needs
to be printed.
dtvRcptLetterQualit Boolean none If configured, this value will be

y passed to jpos.POSPrinter.
setRcptLetterQuality.
dtvRcptPaperCutFeed Integer 0 The number of lines to inject after

After calling
jpos.POSPrinter.cutPaper on
the receipt station.

Table 10-2: POS Printer Settings (Sheet 3 of 3) (continued)
dtvRcptPaperCutFeed Integer 0 The number of lines to inject before

Before calling
jpos.POSPrinter.cutPaper on
the receipt station.
dtvRcptSpacing Integer none If configured, this value will be

passed to jpos.POSPrinter.
setRcptLineSpacing. This value
is the spacing of a single-high print
line, including both the line height
and the whitespace between each
pair of lines. The units used will
depend on driver's default
“MapMode” setting. (Units could be
DOTS, TWIPS (1/1440 inch),
thousandths of an inch, or
hundredths of a millimeter.)
dtvSignatureScaleWi Integer 450 This is the number of pixels to use for

dth the width when generating a
printable image from signature data.
dtvSlipSpacing Integer 0 If configured, this value will be

passed to jpos.POSPrinter.
setSlipLineSpacing. This value
is the spacing of a single-high print
line, including both the line height
and the whitespace between each
pair of lines. The units used will
depend on driver's default MapMode
setting. (Units could be DOTS,
TWIPS (1/1440 inch), thousandths of
an inch, or hundredths of a
millimeter.)
dtvRcptSaveBitmaps Boolean false
dtvcert Boolean false This value is used to give a startup

warning if none of the “dtv”
properties have been configured.

Cash Drawer Settings

Table 10-3: Cash Drawer Settings
dtvDrawerId String 1 This value is used as the ID when

dealing with more than one
cashdrawer.
dtvCashdrawerOPenWait Integer 10 This value is used when there is a

Seconds delay between asking the
cashdrawer to open and being able
to detect that the cashdrawer did
open. This could be due to a
cashdrawer that is physically slow
to open or because of a JPOS driver
that doesn't immediately update
the status.

dtvBeepTimeout Integer 30000 The number of milliseconds to wait

before an alert beeper sounds.
dtvBeepFrequency Integer 1000 Audio frequency of the alert

beeper in hertz.
dtvBeepDuration Integer 1000 Number of milliseconds that the

beep tone will sound.
dtvBeepDelay Integer 1000 Number of milliseconds between

the sounding of beeper tones.
Signature Capture (SigCap) Settings

Table 10-4: SigCap Settings
dtvFlipHorizontal Boolean false Used to indicate the signature should

be flipped on the horizontal axis.
dtvFlipVertical Boolean false Used to indicate the signature should

be flipped on the horizontal axis.
dtvSignatureMessage Integer 1
DirectIOCommand

dtvCapItemDisplay Boolean true Determines whether the SigCap

device will only display line items.
This setting is only used by Ingenico
devices.

MICR Settings
Table 10-5: MICR Settings
dtvHoldChecksFor Boolean true When true, a check will be retained

Franking after reading the MICR so that it can
be franked. If the check needs to be
flipped, but the device cannot flip the
check on its own, this value should
be set to false.
dtvParseData Boolean true When true, Xstore Point of Service's

MICR parsing will be used.
Otherwise, the driver's built-in
parsing will be relied upon.

MSR Settings
Table 10-6: MSR Settings
dtvTracksInclude Boolean true Set to false if the driver does not

DiscretionaryData include the discretionary data in
the reported track data. (Should
normally be true.)
dtvDiscretionaryData Boolean true Set to false if the driver doesn't

IncludesServiceCode include the service code in its
discretionary data fields.
(Should normally be true.)
dtvSetTracksToReadBefore Boolean true Set to true if the driver doesn't

Enable allow the tracksToRead to be
changed after enabling the
device.
dtvTracksToRead String 1,2,3,4 A comma separated list of tracks

to enable on the jpos.MSR
control.
dtvTracksToReport String the value A comma separated list of tracks

for that should be forwarded to the
dtvTracks POS business logic.
ToRead
dtvTypeMap String none Used for RFID/MSR readers that

change the physical name of the
MSR, based on the type of input
read.
dtvcert Boolean false This value is used to give a

startup warning if none of the
“dtv” properties have been
configured.

PINPad Settings
Table 10-7: PINPad Settings
dtvTransactionHost Integer 1 Used to select which key stored on a

PINpad should be used.
dtvMinimumPINLength Integer none If set, will be passed along to

jpos.PINPad.setMinimumPINLength.
dtvMaximumPINLength Integer none If set, will be passed along to

jpos.PINPad.setMaximumPINLength.
dtvEnterPINPrompt Integer none If set, will be passed along to

jpos.PINPad.setPrompt to display an
internal message asking the customer to
enter their PIN.
dtvcert Boolean false This value is used to give a startup warning

if none of the “dtv” properties have been
configured.
Ingenico Settings
Table 10-8: Ingenico Settings
dtvCapItemDisplay Boolean true Indicates that the device can display

items.
dtvFlipHorizontal Boolean false Used to indicate the signature should be

flipped on the horizontal axis.
dtvFlipVertical Boolean false Used to indicate the signature should be

flipped on the vertical axis.

warning if none of the “dtv” properties
have been configured.


11
Reporting Framework
Overview
The Xstore Point of Service Reporting Framework provides users with an easy-to-use
method for retrieving information relevant to their business, and presenting that
information in a consistently formatted, concise, easily understood document. The
Reporting Framework does this through tools that build, process, and format the reports
that are then displayed or printed through Xstore Point of Service.
About This Chapter

• “Overview of the Report Creation Process” explains the process by which reports
are created in Xstore Point of Service.
• “XML Configuration Files Used in Reporting” describes the XML files that are used
in accessing, running, and creating reports.
• “ReportQueryConfig.xml” describes the ReportQueryConfig.xml file, which
configures the queries used in report creation.
Overview of the Report Creation Process

Xstore Point of Service uses Oracle Business Intelligence Publisher to create reports,
forms, and other documents. Reports are designed using rich text format (RTF) files that,
at runtime, a Business Intelligence Publisher API coverts to a formatting language that
describes the visual appearance of the generated report. This final formatting language
is XSL Formatting Objects (XSL-FO) markup language.
XSL-FO is part of the Extensible Stylesheet Language (XSL), which is designed for the
transformation and formatting of XML data. In an Xstore Point of Service BI Publisher
report, the XML Data defines all of the contents of a report, including all static and
dynamic text, numbers, and symbols.
Xstore Point of Service uses BI Publisher's FO Processing Engine to transform the XML
Data into a PDF document, formatted according to the report's XSL-FO. Xstore Point of
Service then converts the PDF document into an image for display in the Xstore Point of
Service user interface.
Data Templates
Data Templates are XML files that define:
• any prompts displayed in Xstore's UI when displaying a report
• any static text used in reports that comes from resource bundles
Reporting Framework 11-1

XML Configuration Files Used in Reporting
• any SQL Queries used in a report

• any in-memory java objects used in a report
• the XML structure of dynamic report content when generated as an XML Data Set
By convention, Data Templates are given the .xdt file extension. XDT Data Template
files were created specifically for Xstore Point of Service; they are not a BI Publisher file
format.
Static text used in Xstore Point of Service’s reports, such as titles and column headings,
primarily comes from resource bundles. XDT Data Templates reference keys used to
look up property values from translation.properties.
SQL Queries
SQL Queries referenced in XDT Data Templates are defined in the
ReportQueryConfig.xml files. XDT Data Templates can reference zero or more
named queries.
XML Configuration Files Used in Reporting

In addition to the .xdt files used to create and format reports, there are several
configuration files within Xstore Point of Service that are related to reports and
reporting. These configuration files tell Xstore Point of Service where to find reports,
how and when to run them, and how they are accessed by users.
• config/config/dtv/res/config/spring/report-beans.xml: Contains
one Spring bean for each report. Each bean is a ReportDefinition that references a
Data Template (xdt file) and a Layout Template (rtf file).
• config/config/report/base/<folder>/*.xdt: Defines the UI report
Prompts. References SQL, resource bundle keys, and in-memory objects. Defines the
structure and content of the XML data set that is the report content.
• config/config/report/base/<folder>/*.rtf: Defines the visual layout of
a report.
Note: The .rtf files are created and modified using Microsoft Word
and a BI Publisher MS Word plug-in: BI Publisher Desktop.
The BI Publisher Desktop can be obtained from:

http://www.oracle.com/technetwork/middleware/bi-publisher/downloads/
• config/config/dtv/res/config/query/ReportQueryConfig.xml:
Defines the queries referenced in the Data Template files.
• config/config/dtv/sql/mssql/query/ReportQueryConfig.xml: Defines
MS SQL Server-specific queries referenced in the Data Template.
• config/config/dtv/res/config/translations.properties: Static text
used in report UI prompts and the generated report.
• config/config/dtv/res/config/OpChainConfig.xml: References the
Report Definition's bean ID used in report-beans.xml.
• config/config/dtv/res/config/ActionConfig.xml: References keys in
translation.properties for report menu titles.

ReportQueryConfig.xml
• xcenter-admin/src/main/SQL/data/xcenter_admin/dataupdate-
all.sql: Defines Viewer Menu Items.
• xcenter-admin/src/main/resources/xcenter/
translations.properties: Static text displayed in Xadmin report viewer
summarizing report's purpose.
Queries must be defined within the file ReportQueryConfig.xml. A query in the
ReportQueryConfig.xml is referred to by the name assigned to it within the file.
The organization of the file ReportQueryConfig.xml is identical to that of the file
QueryConfig.xml. See QueryConfig.xml in Chapter 8, “Query Configuration” for
more information about this file.
Database-Specific ReportQueryConfig.xml Files

The file ReportQueryConfig.xml is located in config.jar. In fact, there are two
files with the name ReportQueryConfig.xml. Each of them is assigned to a different
path and is associated with a different kind of database. The table below lists each of the
files and their locations.
Table 11-1: ReportQueryConfig.xml in config.jar
Filename Database Path
ReportQueryConfig.xml Default \xstore\lib\config.jar\dtv

\res\config\query\
ReportQueryConfig.xml MS-SQL Server- \xstore\lib\config.jar\dtv

specific \sql\mssql\query\
configurations
If you add a new report query in ReportQueryConfig.xml, or if you modify an

existing query, be sure to make the changes in the correct file. Otherwise, the report
output will not reflect the changes you have made to the query.
If your database type is different from the two shown in the preceding table, you must
create a new XML file with the name ReportQueryConfig.xml, enter the query, add
the file to the config.jar file and assign a path to it. The folder name where the file
will exist should reflect the name of the database type.
Reporting Framework 11-3


12
Forms Framework
Overview
The Xstore Point of Service Forms Framework allows users to create and configure forms
that can be used in the desktop version of Xstore Point of Service, Xstore Point of Service
Mobile on a handheld device, and Xstore Point of Service Mobile on a tablet.
About This Chapter

• FieldDefinitionConfig.xml describes the configuration of individual form fields.
• FieldLayoutConfig.xml describes the configuration of layouts that are used to build
forms.
• Form Definition Files describes the configuration of forms from layouts and action
buttons.
FieldDefinitionConfig.xml
The FieldDefinitionConfig.xml file defines the fields that are used in the forms.
These field definitions are used to build layouts in FieldLayoutConfig.xml. The fields are
configured within a <FieldSet> element with the following structure.
<Field> Element:
name Attribute
type Attribute
resource Attribute
text Attribute
dataFieldRef Attribute
formatterRef Attribute
name Attribute
value Attribute
dtype Attribute
• <FieldSet> - (ROOT ELEMENT) Contains the set of all Field Definitions. Contains as
many <Field> sub-elements as necessary.
• <Field> - Defines one field. Each field can contain the following attributes:
Forms Framework 12-1

- name - Unique name used to refer to the field.

- type - Type of field. This attribute can have the following values:
* Label - A text label. Can be static or dynamic.
* Text - Text entry field.
* TextArea - Multi-line text field.
* ComboBox - Combo box field.
* List - Drop-down list.
* GroupingList - A grouping list. This is a special type of list where a
programmer can define an intermediate header where data will be grouped
based upon this field.
* CheckBox - Check box.
* Image - Displays an image.
* Table - Displays data in a table format.
* MoreAuthInfo - A field which dynamically generates itself based upon the
authorization response.
* Chart - Displays a chart.
* Anchor - A clickable link.
* ProgressBar - A progress bar.
* Signature - Displays the user signature received by a signature capture
device.
- resource - ID of the resource used to dynamically retrieve data for this field.
For example, if the attribute is set to “address1”, the field will contain data
retrieved by the getAddress1 method.
- text - ID of the translation text used to populate this field.
Note: The resource and text attributes are mutually exclusive. If

both attributes are set, the text attribute will be used.
- dataFieldRef - Restriction on the data that can be entered into the field. For
example, if this attribute is set to “Numeric”, the field will only accept
numbers.
Note: The valid values for this attribute are configured in the
DataFieldConfig.xml file.
- formatterRef - Defines the way the data in the field is presented. For
example, if this attribute is set to “DateMedium”, the field will display the data
as a date.
• <Parameter> - Defines additional configurations for the field.
- name - Name of the parameter.
- value - Value of the parameter.

Examples
Label Field
<Field type="Label" name="apartmentLabel" text="_aptLabel"/>
Text Field
<Field resource="address1" type="Text" name="address1"
dataFieldRef="Address"/>
List Field
<Field name="activityStream" type="List" resource="activityStream" >

<Parameter name="ColumnHeaderType" value="CUSTOMER_ACTIVITY_STREAM"
/>
<Parameter name="CellType" value="CUSTOMER_ACTIVITY_STREAM" />

<Parameter name="ListSelectionMode" value="NO_SELECTION" />
</Field>
GroupingList Field
<Field name="customerPurchaseHistoryList" type="GroupingList"

resource="custHistoryListModel">
<Parameter name="ColumnHeaderType" value="CUSTOMER_HISTORY_HEADER" /
>
<Parameter name="GroupingHeaderType"
value="CUSTOMER_HISTORY_GROUP_HEADER" />
<Parameter name="CellType" value="CUSTOMER_HISTORY_GROUP_ITEM" />
</Field>
Image Field
<Field name="grayLineSeparator" type="Image"

text="_imageGraySeparator">
<Parameter name="stretch" value="true" dtype="boolean" />
</Field>
<Field name="loyaltyBadgeImage" type="Image"

resource="loyaltyBadgeIcon">
<Parameter name="scale" value="true" dtype="boolean" />
</Field>
Table Field
<Field name="itemGrid" type="Table" resource="itemGrid">

<Parameter name="CellType" value="ITEM_GRID_CELL" />

FieldLayoutConfig.xml
<Parameter name="AlternateCellType" value="ITEM_GRID_CELL_ALTERNATE"

/>
<Parameter name="RowHeaderType" value="ITEM_GRID_ROW_HEADER" />
<Parameter name="ColumnHeaderType" value="ITEM_GRID_COLUMN_HEADER" /
>
<Parameter name="UpperLeftCellType"
value="ITEM_GRID_UPPER_LEFT_CORNER" />
</Field>
Chart Field
<Field name="salesTrendGraph" type="Chart"

resource="salesTrendChartModel" formatterRef="DateMonthNameDay" />
Anchor Field
<Field name="productDetailsUrl" type="Anchor"

resource="productDetailsURL">
<Parameter name="displayText" value="_itemUrlClickInfo" />
</Field>
ProgressBar Field
<Field name="authorizationProgressBar" type="ProgressBar"

resource="percentComplete" />
Signature Field
<Field name="signature" type="Signature" resource="signature" />
MoreAuthInfo Field
<Field name="moreAuthInfo" type="MoreAuthInfo" resource="moreAuthInfo"

dataFieldRef="ID" />
The FieldLayoutConfig.xml file defines how fields (defined in
FieldDefinitionConfig.xml) are placed into rows and columns within a layout. These
layouts are then used by Form Definition Files to create pages that are displayed in
Xstore Point of Service. The fields are configured within a <FieldLayoutSet> element
with the following structure:
<FieldLayout> Element:
type Attribute
name Attribute

<Row> Element:
name Attribute
type Attribute
<Column> Element:
fill Attribute
start Attribute
width Attribute
fieldRef Attribute
verticalAlignment Attribute
horizontalAlignment Attribute
required Attribute
refreshOnChange Attribute
fontRef Attribute
visibilityGroup Attribute
fieldSubmitPriority Attribute
• <FieldLayoutSet> - (ROOT ELEMENT) Contains the set of all Field Layouts.
Contains as many <FieldLayout> sub-elements as necessary.
• <FieldLayout> - Defines one layout. Each layout includes the following attributes:
- name - Unique name used to refer to the layout.
- type - Type of layout. This attribute can have the following values:
* ListLayout - A layout that can contain one or more columns within each
row, with a defined width for each column.
* SimpleLayout - A layout that always has two dynamically-sized, equal-
width columns.
• <Row> - Defines one row within the layout.
For SimpleLayout layouts, this element will include two <Column> elements. For
<ListLayout> layouts, this element will include as many <Column> elements as
necessary.
- fill - Indicates whether the row should fill all available space in the form.
Default=false
- type - Type of layout. This attribute can have the following values:
* ListLayout - A layout that can contain one or more columns within the
row, with a defined width for each column.
* SimpleLayout - A layout that always has two dynamically-sized, equal-
width columns.
• <Column> - Defines one column within a row. This element includes the following
attributes:
- fill - Indicates whether the column should fill all available space in the form.
Default=false

- start - Starting point of the field within the layout. This is a numerical
percentage (0 to 100).
- width - Width of the field within the layout. This is a numerical percentage (0 to
100).
- fieldRef - The name of the field definition (from FieldDefinitionConfig.xml)
to insert into the layout.
- verticalAlignment - Vertical alignment of the field within the row. This
attribute can have the following values:
* Left
* Right
* Center
- horizontalAlignment - Horizontal alignment of the field within the column.
This attribute can have the following values:
* Top
* Bottom
* Center
- required - If this field is set to true, user must enter a value in the field.
- refreshOnChange - If this field is set to true, Xstore Mobile will send a
notification to the server when a user changes the value in the field.
- fontRef - Defines the font for the field (refers to a font defined in
FontConfig.xml).
- visibilityGroup - Refers to a condition that determines whether or not to
show the field within the layout.
- fieldSubmitPriority - Determines the order in which form fields are
processed in Xstore Point of Service Mobile. This is used to ensure that auto-
populated fields are handled properly. Default=0
Example
<FieldLayout name="customerMaintHeader" type="ListLayout">

<Row>
<Column start="0" width="20" fieldRef="customerName"
verticalAlignment="Center" fontRef="whiteColorFont" />
<Column start="20" width="18" fieldRef="customerIdLabelFull"
verticalAlignment="Center" horizontalAlignment="Right"
fontRef="fullScreenFormHeaderLabel" />
<Column start="38" width="20" fieldRef="customerIdLabelValue"
verticalAlignment="Center" fontRef="whiteColorFont" />
<Column start="58" width="17" fieldRef="customerSinceLabel"
verticalAlignment="Center" horizontalAlignment="Right"
fontRef="fullScreenFormHeaderLabel" />
<Column start="75" width="15"
fieldRef="customerAnniversaryDateLabel" verticalAlignment="Center"
horizontalAlignment="Left" fontRef="whiteColorFont" />
</Row>
</FieldLayout>

Form Definition Files
<FieldLayout name="custPersonalInformationLayout" type="SimpleLayout">

<Row>
<Column start="0" width="30" fieldRef="anniversaryDateLabel"
horizontalAlignment="Right" />
<Column start="30" width="50" fieldRef="anniversaryDate" />
</Row>
<Row>
<Column start="0" width="30" fieldRef="birthDateLabel"
<Column start="30" width="50" fieldRef="birthDate" />
</Row>
<Row>
<Column start="0" width="30" fieldRef="genderLabel"
<Column start="30" width="50" fieldRef="gender" />
</Row>
<Row>
<Column start="0" width="30" fieldRef="personalTaxIdLabel"
visibilityGroup="fiscalCodeVisibility"
<Column start="30" width="50" fieldRef="personalTaxId"
visibilityGroup="fiscalCodeVisibility" />
</Row>
<Row>
<Column start="0" width="30" fieldRef="nationalTaxIdLabel"
visibilityGroup="taxCodeVisibility"
<Column start="30" width="50" fieldRef="nationalTaxId"
visibilityGroup="taxCodeVisibility" />
</Row>
</FieldLayout>

Each form is defined within its own form definition file. The name of the form is the
name of the form definition XML file. For example, the CUSTOMER_MAINTENANCE
form is defined by the CUSTOMER_MAINTENANCE.xml file.
The form is configured within a <FormSet> element with the following structure:
<Form> Element:
type Attribute
name Attribute
FormLayoutRef Attribute
<Header> Element:
viewAction Attribute
editAction Attribute

<Panel> Element:
startX Attribute
width Attribute
startY Attribute
height Attribute
FieldLayoutRef Attribute
padding Attribute
verticalAlignment Attribute
horizontalAlignment Attribute
<Page> Element:
name Attribute
text Attribute
displayOrder Attribute
<Panel> Element:
startX Attribute
width Attribute
startY Attribute
height Attribute
fieldLayoutRef Attribute
padding Attribute
<ActionGroups> Element:
view Attribute
edit Attribute
<ActionGroup> Element:
name Attribute
<Action> Element
• <FormSet> - (ROOT ELEMENT) Contains one <Form> sub-element that defines the
form.
• <Form> - Defines the form that is displayed on the screen. Contains one or zero
<Header> elements, as many <Page> elements as necessary, and as many
<ActionGroup> elements as necessary. Each form includes the following
attributes:
- name - Name of the form.
- type - Type of form. This attribute can have the following values:
* MULTI_PURPOSE_VIEW - A full-screen form.
* POPUP_VIEW_PANEL - A form that appears as a pop-up window.
* MESSAGE_AREA - A form in the message area of Xstore Point of Service.
* TRANSACTION_LIST_AREA - A form in the transaction area of Xstore Point
of Service. That is, it displays details of line items added to a transaction.

- formLayoutRef - Refers to a form layout (defined in

FormLayoutConfig.xml) used for the form.
• <Header> - Defines the header for the form. Contains as many <Panel> elements
as necessary. This element has the following attributes:
- viewAction - The action (defined in ActionConfig.xml) performed when a
user touches the header while the form is in view mode.
- editAction - The action (defined in ActionConfig.xml) performed when a
user touches the header while the form is in edit mode.
• <Page> - Defines a page on the screen. If there is more than one <Page> in a form,
the form will be a tabbed form. Contains as many <Panel> elements as necessary.
This element has the following attributes:
- name - Unique name of the page within the form.
- text - Reference to the translation key used on the tab (only used when a form
has mroe than one <Page> element).
- displayOrder - Order in which the tab is displayed (only used when a form
has more than one <Page> element).
• <Panel> - Defines the location of the field layout (see FieldLayoutConfig.xml) in the
page. Used by both <Header> and <Page> elements. This element has the following
attributes:
- startX - Horizontal starting point for the layout. This is a numerical percentage
(0 to 100).
- width - Width of the layout. This is a numerical percentage (0 to 100).
- startY - Vertical starting point for the layout. This is a numerical percentage (0
to 100).
- height - Height of the layout. This is a numerical percentage (0 to 100).
- fieldLayoutRef - Reference to the name of the layout (configured in
FieldLayoutConfig.xml) to include in the form.
- padding - Determines the space around the element. The format of the padding
setting is top, right, bottom, left. Each number represents the number
of pixels of space in each direction.
• <ActionGroups> - The action groups used by the page.
- view - Actions available in view mode.
- edit - Actions available in edit mode.
• <ActionGroup> - A collection of actions available as buttons. Contains as many
<Action> elements as necessary. This element has the following attribute:
- name - Unique name used to refer to the action group.
• <Action> - Defines a button and its actions when selected. This element refers to an
action defined in the ActionConfig.xml file, or it can be defined in-line.
- ref - This attribute refers to the name of an action in an ActionConfig.xml
file.
- When defining an in-line action, the configurations for this element are the same
as those for <Action> elements in an ActionConfig.xml file.


13
Spring Integration
Overview
The Xstore Point of Service framework refactoring effort is a movement to make Xstore
Point of Service easier to understand and develop, and also to better promote shared
code with other Xstore Suite components (like Xstore Office) and other applications (like
Xstore for Grocery). As Xstore Point of Service evolves and its developer base grows, it's
more important than ever to embrace the use of established, standard technologies like
Spring while streamlining development patterns as much as possible. This will help on-
board and train new developers, reuse foundational Xstore Point of Service classes for
new development projects and software applications, and extend Xstore Point of
Service's lifespan as a relevant and major force in the retail POS market.
Benefits
Using the Spring framework in Xstore Point of Service has the following benefits for
developers:
• Exorcise the command framework. A Spring-backed, global scoping mechanism
allows developers to avoid excessive casting of variables, makes it easier to access
scoped data outside of operations and allows operations to be transposed between
OpChains. It also makes code more readable and streamlines classes like validation
and visibility rules.
• Use Spring for singleton management. By leveraging Spring beans for management
of singleton classes, Xstore Point of Service helpers are easier to read and extend,
and will no longer require static code to load instance specifiers from system
properties. All helpers and manager implementation classes are cleanly defined in a
single configuration file and accessed consistently from any other classes in the
application.
• Use Spring for services framework. Spring will streamlines the Xstore Point of
Service services framework for implementing web service clients in a more standard
way and make services easier to configure and use.
• Make Xstore Point of Service's workflow more transparent. Configuration-based
routing rules and conditions make it easier to understand the flow of an OpChain by
simply reading the OpChainConfig.xml file. See Chapter 3, “Operation Chains”
for more information about OpChains and the OpChainConfig.xml file.
• Separate flow and business logic to promote code reuse. Separating workers (as
business logic providers) from operations (as flow control mechanisms) promotes
more streamlined feature implementations whose core logic can be more easily
transferred between applications and components in the Xstore Suite.
Spring Integration 13-11

Benefits
Dependency Injection
Any XML file that lists fully-qualified class names that are reflectively instantiated in the
code and can be overridden at different points on the configuration path are attempts at
providing some sort of dependency injection. Spring simplifies dependency injection
across the application by providing a standard method for injecting dependencies,
rather than requiring developers to create their own processes.
Note: When using dependency injection, a class that is injected

should always have a scope that is equal to or broader than the class
that is receiving the injection. Another way to put this is never inject
something that is not a singleton into a singleton.
Spring Beans
Xstore Point of Service uses Spring's XML-driven bean configurations to manage the
definition of all managed classes. The Spring XML files that are to be loaded by Xstore
Point of Service are governed by Xstore Point of Service's configuration path. This
approach makes the most sense for Xstore Point of Service, because developers are
already familiar with the concept of the configuration path, and it allows overrides of
base Spring files to be performed in the same manner as other XML files.
• The location of the files can be thought of as being similar to directory-based
configuration files. All files ending with .xml within a spring directory anywhere
in the configuration path will be processed and loaded.
• The name of each Spring bean file does not matter, with the exception that each file
should have a unique name.
Important: If two Spring bean files share the same name, the one that
comes later in the configuration path will completely replace the
earlier one. This will cause to Spring ignore all bean definitions in the
earlier one.
Spring Bean Files

The following Spring bean files are defined in base Xstore Point of Service.
• spring.xml - General file that defines the primary, application-driving beans that
do not fall into a more specific category. This includes the primary application
control beans such as the mode controller and its dependencies, as well as singletons
and helper-type classes that have been converted to being Spring-managed.
• validations.xml - Contains the definition of all validation rule and validation
rule list beans in base Xstore Point of Service. Validation rules will only be added
through this file. All validation rule beans should be assigned a "prototype" scope.
Note: This file replaces ValidationRuleConfig.xml.
• workers.xml - Contains the definition of all worker and worker list beans. All
worker beans should be assigned a "prototype" scope.

Use of the Configurable Annotation and Injection of Fields
• services.xml - Contains beans that identify the services available to Xstore Point
of Service using the service framework.
Note: This file replaces several classes and system.properties

entries that were previously necessary for defining a service.
• services-relate.xml - Contains the bean definitions for all Oracle Retail

Customer Engagement Cloud Service services. The contents of this file are a
replacement for the <ServiceHandler> elements in the Customer Engagement
Cloud Service ServiceHandlers.xml file.
• services-locate.xml - Contains the bean definitions for all Oracle Retail Order
Broker Cloud Service services. The contents of this file are a replacement for the
<ServiceHandler> elements in the Oracle Retail Order Broker Cloud Service
ServiceHandlers.xml file.
• services-opera.xml - Contains the bean definitions for all Opera services. The
contents of this file are a replacement for the <ServiceHandler> elements in the
Opera ServiceHandlers.xml file.
Overriding Files
In theory, a customer overlay may only need one Spring bean file that contains all of the
necessary overrides from across the base files and any additions. To ensure file names
remain unique, all customer Spring bean file names should start with the customer's 3-
character ID.
Note: Files should be named according to their purpose.
Use of the Configurable Annotation and Injection of Fields

Many classes that are not Spring-managed will have Spring-managed beans injected into
them. To do this a Spring annotation, @Configurable, is added to classes that are not
Spring-managed that allows the class to be manually instantiated with the "new"
operator, reflectively instantiated, or deserialized and still have any injected fields
processed and satisfied. This annotation on a class is recognized in subclasses, so it
needs to appear only once in an object hierarchy.
Example - Operation
A good example of the use of this annotation is on the Operation class. Operation is
not managed by Spring, but the class still needs injections processed. The Operation
class is annotated with @Configurable, so no classes that extend Operation need the
annotation. They all will be processed because the ancestor is annotated. Operation,
validation rule, visibility rule, worker, and run condition classes all have the annotation
specified on the abstract ancestor class, so they are all immediately available to have
injections processed.
@Configurable
public abstract class Operation
implements IOperationImpl, IDebuggable {
@Inject

Custom Spring Scopes
private DefaultScope _defaultScope;
@Inject
protected TransactionScope _transactionScope;
}
Custom Spring Scopes

Spring includes two usable scopes in desktop (that is, non-web-enabled) applications.
Those are singleton and prototype. It is left to the reader to read the Spring
documentation for information on those scopes.
Note: Spring scopes are not to be confused with the classes

DefaultScope and TransactionScope, which are managed by Xstore
Point of Service code and should be considered to be “Xstore Point of
Service scopes”.
Spring also allows developers to define custom scopes by implementing a particular

interface and registering the scope with Spring. In custom Spring scopes, the values in
the scope are managed by Spring. No one ever puts values into a Spring scope, the beans
are created and made available by the scope. The Spring scope must also be registered
with Spring as a custom scope. The similarity between Xstore Point of Service and
custom Spring scopes is that the clearing mechanism must be implemented for each of
them.
The custom Spring scopes in Xstore Point of Service are:
Application Mode
The name of this scope is applicationMode. It is used for beans that have an instance
tied to a particular application mode of Xstore Point of Service. The standard modes that
everyone knows to exist in Xstore Point of Service are Register and Back Office.
Any class that is assigned an application mode scope will have one managed instance
per application mode that is started. There are only two classes in Xstore Point of Service
that have application mode as their scope and there should not need to be many more. It
only exists because of the ability to jump directly into the register from within a back
office function.
Due to the nature of what classes with this scope represent, when injecting them into
classes in Xstore Point of Service, they should be wrapped in a Provider.
Training Mode
Officially named maybeTrainingMode, this scope is used for beans that represent the
implementations of service providers. Given how training mode works in Xstore Point of
Service, this scope is used to determine if the real implementation bean or a training
substitute bean should be provided when injection is requested. Since a number of
singleton helpers inject service interfaces (not really ideal, maybe this can be addressed
in the future) and whether or not you are in training mode can change on the fly when
Xstore Point of Service is running, each injection of a bean that is assigned to this scope
should be wrapped in a Provider.

Scoping/Value Keys
Transaction
The name of this scope is transaction. The difference between this and the use of the
TransactionScope class that you inject in various places in Xstore Point of Service is
in how the object gets into scope. Because this is a Spring-managed scope, any beans
assigned to it are created by Spring.
The references are held for as long as TransactionScope holds them (see
“TransactionScope”). Beans that are assigned to this scope are things that you simply
want to be instantiated the first time they are requested and then referenced for the
duration of the transaction. The ReturnManager class is a good example of this. It
simply needs to exist and it is only relevant for as long as a sale transaction is in process.
Scoping/Value Keys
The primary use of a command in Xstore Point of Service is to temporarily hold onto a
value so that it can be accessed within different parts of an operation and across multiple
operations. Countless guessing at which command interface is relevant for your
operation and then casting to that interface to call a particular method that holds a
desired value has caused many issues over Xstore Point of Service's life and has severely
increased the complexity and decreased the ability to understand with any level of
confidence what will happen at any point. It has also made things such as validation
rules (both input driven and non-input driven) more complex than necessary, with
developers having to be aware of particular indices within an array in which a particular
value exists, based on the operation that put them there, and then casting the value in
that index to a particular class. The whole notion is fraught with fragility and nuances
and limits the usefulness and usability of validation rules.
With the advent of Xstore Point of Service, version 7.0, use of IXstCommand and all of its
extensions and implementations have been deprecated in favor of an all-new, Spring-
managed, scoped-value management mechanism. At its core it is a two-part system that
involves a scoped value container and a key for storing and accessing the contained
values. The intent is that common values, such as an item ID entered by a user,
regardless of where they are used within the application, can be accessible and
referenced in a consistent way across the application.
By having one means of getting a scoped value, developers can rely on it and not have to
guess about which value to get out of scope depending on what feature is currently
being used. The same value can be accessed in the same way from operations, validation
rules, visibility rules, etc., thereby increasing ease of use and understanding of these
concepts.
The design of the scoped value container is technically inspired by the concept of the
type-safe heterogenenous container. The key that is used to store and retrieve values
from the container is parameterized with the type of object that is being stored. Only
objects of a type matching the key may be put into the container using that key and the
values retrieved from the container will always be of the type on the key used to do the
retrieval. Therefore, you can always be sure of the type of an object and just use it the
way that it was intended. There is no more guessing what is the type of an object
represented by a key or casting an Object to a specific type.
The key to all of the this is a class called ValueKey. Any value that is that is put into
scope or retrieved from scope must use a ValueKey to do so. Every ValueKey that is
defined should be defined as a constant and placed in the same file. For ease of reference,
all of the ValueKey instances in base Xstore Point of Service are grouped together based
on the container in which they are used. This makes it easy for developers to determine
if a usable key already exists for a value that they want to store or retrieve before they go
and create a new one.

Scoping/Value Keys
There are two different classes that define ValueKey instances in base Xstore Point of
Service, as there are two different containers that are based on different scoping
mechanisms. Any values that are to be used within the DefaultScope container are
defined in the ValueKeys class. Any values that are to be used within the
TransactionScope container are defined in the TransactionScopeKeys class.
There are comments that are invaluable to a developer in the ValueKeys class in base
Xstore Point of Service that contains rules for naming, use, and so on. At the risk of
duplicating and having to maintain the same information twice, that information is
excluded here. However, those comments should be read and committed to memory
absolutely by any developer who is programming Xstore Point of Service.
ValueKey instances that are created in a customer overlay should follow a similar
pattern as the base. They all should be defined as constants in a class that is named with
the 3-character customer code plus "ValueKeys" or "TransactionScopeKeys", depending
on their use. For instance, if the customer code is CST, then the class would be
CstValueKeys.
As briefly mentioned above, there are two containers that manage scoped values. The
general behavior of each is the same. They share a means of setting and retrieving values
and they both use ValueKey to do so. The difference is in the scope management and
when managed values are removed from the container. What follows is a description of
each value management container.
DefaultScope
This is the primary scope management class for any values that need to be held
temporarily for use within one or more operations and their corresponding validation
rules. As a general rule, only operations should ever put values into default scope. The
reason is that values in DefaultScope are most often values that were input by a user,
were selected by a user, or were derived from input by a user and this type of input
comes from operations. An example would be an item ID that was entered by a user.
Whether it was entered manually or via scanner, it will be put into default scope as the
entered item ID by the operation that captured the input. After it is put into scope (using
the ValueKeys.ENTERED_ITEM_ID key, by the way), it will be accessible to any other
class that needs to reference it.
As mentioned above, all ValueKey instances that are used with DefaultScope are
defined in base Xstore Point of Service in the ValueKeys class. Customer overlay
projects should define a CstValueKeys class to hold all of the customer-specific
ValueKey instances, where "Cst" is the customer's 3-character code.
Use
In most cases, the DefaultScope class does not need to be accessed directly. In the
aforementioned abstract classes that have the @Configurable annotation,
DefaultScope is also injected into them. Each of these ancestor classes has a
getScopedValue() method that can be used as a convenience for retrieving values
from DefaultScope. In addition, Operation also has a
setScopedValue(ValueKey) that is used to be put values into scope. When
available, these methods should be used to access DefaultScope and it should not be
accessed directly.
In classes where these methods are not available, direct injection and access of
DefaultScope is acceptable. Although the DefaultScope class can be injected
anywhere, it should not be injected or referenced in a singleton or a helper class. It is
only meant for use within temporary objects that are created and thrown away after they
have been used. This is in line with the type of values that it holds.

Scoping/Value Keys
Use DefaultScope directly in a class

@Inject
private DefaultScope _defaultScope;
...
String itemId =
_defaultScope.getValue(ValueKeys.ENTERED_ITEM_ID);
Use DefaultScope in an operation

BigDecimal setPrice = new BigDecimal(25);
setScopedValue(ValueKeys.ENTERED_ITEM_PRICE, setPrice);
BigDecimal itemPrice =
getScopedValue(ValueKeys.ENTERED_ITEM_PRICE);
Removal of Values
In most cases, values that are put into DefaultScope do not need to be removed from it
manually. There is an auto-clearing mechanism in place that removes values from scope
when it has been determined that they are no longer necessary.
The removal of values revolves around the notion of default chains. Whenever a default
chain starts, the rollback level of it is captured. Any value that is set in DefaultScope is
associated with the current rollback level until another default chain starts, at which
point any new values set into DefaultScope will be associated with the new level.
Each time a default chain starts, the values in DefaultScope are examined and any
values that are associated with a rollback level that is greater than or equal to the
rollback level of the default chain that is starting will be removed. Any values that are
associated with a rollback level that is less than that of the default chain that is starting
will remain.
In some more rare cases, it is necessary to remove a value from DefaultScope
manually. These cases should be considered to be the exception. Normal functionality
should not manually remove values from any kind of scope. The most likely case for
manually removing a value from DefaultScope is when an operation is reversing. At
these times, the operation may want to remove values that it put into scope, if their
existence will not be cleaned up automatically, or if they will cause other issues by being
in scope when they should not be. For this purpose, there is
clearScopeValue(ValueKey) method on the Operation class.
Operation classes should be the only things that ever manually remove values from
DefaultScope. Unless there is an incredibly compelling reason that is documented in
the code that does it, the only place within operations where values should be removed
from DefaultScope is in the handleOpReverse() method.
Note: Do not call setScopedValue(ValueKey<T>, T) with a null

value. Always call clear-ScopedValue(ValueKey).
Example
1. The SHIPPING chain is a default chain with a rollback level of 30. This is the initial
chain for the shipping feature that contains the functionality to select a document to
process. The document is put into DefaultScope at level 30.
2. The LINE_SHIPPING chain is a default chain with a rollback level of 50. When the
LINE_SHIPPING chain starts the first time, everything that was put into

Scoping/Value Keys
DefaultScope in the SHIPPING chain will remain since its rollback level (30) is
less than the LINE_SHIPPING (50). Every value that is put into scope in the
LINE_SHIPPING chain will be associated with level 50.
3. When the LINE_SHIPPING chain completes, it starts again. When it starts, any
values that were put into DefaultScope during its last run are removed since the
rollback level of the chain and the values are equal.
4. When backing up out of shipping to the main menu, the rollback level of the main
menu (12) is less than that of the SHIPPING chain (30), so any values in
DefaultScope that were associated with the SHIPPING chain's rollback level (30)
will be removed.
TransactionScope
This class is meant for holding values that should be available for the entire duration of a
transaction. The primary example is the POS transaction itself. There are many fewer
cases where the need exists to store thing in TransactionScope. For most cases,
DefaultScope should be preferred. As mentioned above, any ValueKey instances
that are used to access TransactionScope are defined in TransactionScopeKeys
class in base Xstore Point of Service. Customer overlay projects should define a
CstTransactionScopeKeys class to hold all of the customer-specific ValueKey
instances that are used to access TransactionScope, where "Cst" is the customer's 3-
character code.
Use
The TransactionScope class can be injected anywhere that it is needed and its
methods for getting and setting values are always directly referenced. The most
important value that is stored in TransactionScope is the POS transaction itself.
Putting the current transaction into scope happens rather automatically, unless you take
explicit steps to prevent it. When using the TransactionHelper class to create a
transaction (as all transactions should do), the default behavior is to put the created
transaction into TransactionScope right after it has been created. Only one
transaction can be in scope at any time.
For the few cases in Xstore Point of Service where a transaction that is being created
should be not be placed into TransactionScope (for example, when it is a secondary
transaction that is created in the middle of a primary transaction, such as a.manual no
sale), a parameter can be passed to the TransactionHelper that can indicate not to
put the transaction being created into TransactionScope. Care should be taken when
using this parameter, as only the transaction in scope will be persisted when using the
standard PersistCurrentTransactionOp or
PersistCurrentTransactionWorker.
There are two convenience methods on the TransactionScope class that wrap the
getValue(ValueKey) method and provide the current transaction ValueKey. Both
are the intended method of retrieving the current transaction. The current transaction
should always be retrieved using these methods and directly using
getValue(ValueKey) to get the current transaction should be avoided.
• The getTransaction() method simply returns the current transaction as an
IPosTransaction. This method can be used when you simply want the current
transaction and you are indifferent to the type of transaction.
• The getTransaction(TransactionType) method accepts an additional
parameter that allows the user to specify the type of transaction that should be
retrieved from scope. This method can be used when you are interested in a
particular type of transaction.

Management of Helpers/Singletons
- If a transaction of the type specified is in scope, it will be returned as the specific

type.
- If no transaction is in scope or if a transaction of a different type is in scope, then
no transaction will be returned. This is done to provide a convenient and more
fail-safe way of dealing with the current transaction.
For example:
1. A call is made to
TransactionHelper.createTransaction(TransactionType.RETAIL_SAL
E) and the created transaction is put into TransactionScope.
2. An operation makes a call to
TransactionScope.getValue(TransactionType), passing
TransactionType.RETAIL_SALE.
3. The operation returns an IRetailTransaction object, because that type of
transaction is in scope.
4. The next operation makes a call to
TransactionScope.getValue(TransactionType).
5. Although a transaction is in scope, the operation does not return it because it is not
of the requested type.
Removal of Values
As a general rule, values should not be removed from TransactionScope manually
unless some explicit, well-documented case requires otherwise. The POS transaction
value should never be removed from TransactionScope manually. You should
always rely on the inherent clearing mechanism to remove it at the appropriate time. The
removal of values from TransactionScope is being on the notion of transaction
completing. More specifically, it is based on the reception of events from the
OpChainProcessor that indicate that a transaction has terminated. When an OpChain
completes that has a signal on it with a value of TransactionComplete or
TransactionCancelled, the TransactionScope will pick up the signal event and
remove all of the current values. No value in TransactionScope remains after one of
these events has been processed. This signal should placed on OpChain that contain the
operation that persists the current transaction. The removal of values is based on the
completion of the chain instead of persistence itself because there are some things within
the chain that still need to be able to reference transaction-scoped values after the current
transaction has been persisted.
Note: Do not call setScopedValue(ValueKey<T>, T) with a null

value. This will generate an IllegalArgumentException when
called on TransactionScope.
Management of Helpers/Singletons
Classes that are deemed to be helpers should be defined as singleton-scoped Spring
beans (Spring beans are singletons by default) and a reference to the helper class should
be injected anywhere that it is necessary using the standard Inject annotation.
To override the bean class in a customer overlay, put a bean configuration in the Spring
file in the customer overlay that defines a bean with the same ID as the base but with
your extended class instead of the base class. Below are examples of how to define and
use helper beans in Xstore Point of Service.

Management of Services
Define a helper bean

<bean id="customerHelper" class="dtv.pos.customer.CustomerHelper"
/>
Use it in a class
@Inject
private CustomerHelper _customerHelper;
...
_customerHelper.searchForCustomers(...
Override the helper bean (assume that CstCustomerHelper extends

CustomerHelper)
<bean id="customerHelper"
class="cst.pos.customer.CstCustomerHelper" />
Management of Services
The use of Spring-configured beans in Xstore Point of Service simplifies the creation of
new services.. When it comes to Spring service configurations, there are two types of
beans that are now configured.
Service Implementations
Beans that represent the actual service implementations are defined in the
services.xml Spring file. The service implementation to use when in training mode
also appears in this file. All service implementation beans that are defined should be
assigned to the maybeTrainingMode scope. In order to add a new service, simply create
the interface and implementation class for it, configure the bean in a Spring XML file
(services.xml in the base) and inject the interface with a Provider in any class where
it is needed.
To override a service implementation, configure a bean in the Spring file in a customer
overlay to have the same ID as the base bean and provide a different class. For service
implementations, the implementation override class does not need to extend the base
implementation class, it only needs to implement the service interface. Injections of
services into Xstore Point of Service client-side classes should reference the service
interface and never an implementation class.
Service Handlers
The configuration of ServiceHandlers is managed through Spring configuration files.
There is one Spring services-XXX.xml file for each service provider, where XXX
identifies the provider. See the Xstore Point of Service Services Guide for more information.
The ServiceHandlers.xml file maintains connection information (for example,
WSDL location) and parameters such as timeout values.
Flow Transparency and OpChainConfig.xml Readability

This section will identifies new elements available in the OpChainConfig.xml file.

New Elements
As part of the Spring refactoring, several new elements have been added to
OpChainConfig.xml to improve the readability of the file and provide a better
understanding of the flow of Xstore Point of Service and what is happening at each step.
Some elements replace old ones and some are enhancements to existing ones.
Op
This element is replaces the Operation element.
ValidationOp
A validation operation is an operation that does not prompt the user for any input, but
validates against currently known data using the standard validation rule mechanism in
The ValidationOp element include a new validationsBean attribute that identifies
the Spring bean containing the list of validation rules to apply. Along with the new
element come new rules for when to use it and what using it means.
• An operation class that implements IValidationOp directly (that is, not through
an extension interface like IPromptOp) should be configured with a
ValidationOp element.
• A ValidationOp is required to specify a validationsBean attribute, which
identifies the Spring bean that contains the list of validation rules to apply.
• No class needs to be specified for a ValidationOp if no custom logic is required
and validation rules only need to be applied against currently known data. If no
class is specified, then class that will be used is ValidationWithoutPromptOp.
This class is the old AbstractValidationWithoutPromptOp, now made
concrete due to the new way that validation rules work with Spring and
DefaultScope.
PromptOp
A prompt operation is an operation that prompts the user for one piece of data, whether
it is entered in a text field, selected from a list, or the confirmation from a button press. A
prompt operation has the ability to specify the prompt with which the user should be
presented and an optional set of rules to validate what was entered/selected.
The PromptOp element extends ValidationOp and introduces one additional key
attribute, which is used to override the default prompt key. With the Spring integration,
a set of rules exists for defining a prompt operation.
• A prompt operation should only prompt for one piece of data.
• A prompt operation class should implement the IPromptOp interface. All prompt
operations should extend AbstractPromptOp somewhere in the hierarchy. It has
all of the necessary underpinnings for the use of standard, accepted prompt
functionality.
• If a class attribute is not specified for a PromptOp element, then the class
PromptOp will be used.
• The validationsBean attribute determines the rules to apply to the PromptOp.
The value of this attribute indicates the ID of a Spring that defines the list of
validation rules that will be injected into the operation. The validationsBean
attribute is optional.

• A prompt operation always needs to define a default prompt key within the prompt
operation class using the method getDefaultPromptKey(). If the default prompt
key is not sufficient for a particular occurrence of the operation in
OpChainConfig.xml, an override can be specified on the PromptOp element
using the key attribute. This should always be configured by exception.
• The PromptKey parameter is deprecated and should not be used.
• The ValidationRuleSet parameter is deprecated and should not be used.
• The ValidationRuleConfig.xml file is also deprecated. A prompt operation
that needs to perform validation against input will have the list rules injected into
the operation.
WorkerOp
A worker operation is an operation whose primary purpose is to trigger running a
worker (or a list of workers via a Spring bean that itself is a worker). The WorkerOp
element extends the Op element and adds one attribute named workersBean, used to
specify the ID of the Spring bean that is either a worker or is a list of workers that should
be injected into the operation.
A worker operation should implement the IWorkerOp interface, which provides the
facility for allowing a worker to be injected. The workersBean attribute is required to
be present on a WorkerOp. No class needs to be specified for a WorkerOp if the only
desired functionality is to run the workers identified by the workersBean attribute. If
no class is specified, then the class that will be used is SimpleDoWorkOp.
OpChainRoute
The OpChainRoute directive both introduces conditional chain routing functionality in
its more complex forms, and replaces old standards like OpChainReference and
OpChainLink in its simpler forms.
The OpChainRoute_Type schema definition

<xs:complexType name="OpChainRoute_Type">
<xs:sequence>
<xs:element name="Choice" type="OpChainChoice_Type"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="dtype" type="xs:string"
fixed="OpChainRoute" />
<xs:attribute name="chainKey" type="xs:string" />
<xs:attribute name="condition" type="xs:string" />
<xs:attribute name="chainType" type="xs:string" />
</xs:complexType>
<xs:complexType name="OpChainChoice_Type">
<xs:sequence>
<xs:element name="Condition" type="Condition_Type"
minOccurs="0">
<xs:annotation>
<xs:appinfo>

<jaxb:property name="ConditionElement" />

</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute name="dtype" type="xs:string"
fixed="OpChainChoice" />
<xs:attribute name="chainKey" type="xs:string" use="required" /
>
</xs:complexType>
<xs:complexType name="Condition_Type">
<xs:sequence>
<xs:element name="Parameter" type="Parameter_Type"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="class" type="xs:string"/>
</xs:complexType>
To explain the details of this type of element, it is broken down into pieces with each
piece being explained separately.
<xs:complexType name="OpChainRoute_Type">
The OpChainRoute element itself indicates that flow may be transferred to another
chain, if conditions are right.
<xs:sequence>
<xs:element name="Choice" type="OpChainChoice_Type"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="dtype" type="xs:string" fixed="OpChainRoute"
/>
<xs:attribute name="chainKey" type="xs:string" />
The chainKey attribute is shorthand for configuring a Choice child element with a
chainKey attribute.
If there is only one choice, then it is recommended that this shorthand form be used to
increase readability. If there are multiple choices, then it is recommended that each
choice be defined as an element and that no shorthand is used. If a shorthand choice is
intended to be used, then this attribute must be populated. That is, if you populate any
of the other attributes on the OpChainRoute element, then you must populate this one
as well. See the chainKey attribute on the Choice element for additional details.

The use of the condition attribute is shorthand for configuring a Choice element with
a condition attribute or a Condition element. If this attribute is present, then the
chainKey attribute is required.
choice be defined as a Choice element and that no shorthand is used. See the
condition attribute on the Choice element for additional details.
The use of the chainType attribute is shorthand for configuring a Choice element with
a chainType attribute.
choice be defined as an element and that no shorthand is used. See the chainType
attribute on the Choice element for additional details.
</xs:complexType>
<xs:complexType name="OpChainChoice_Type">
An element defined as an OpChainChoice_Type (the Choice element on
OpChainRoute) defines one possible path to take when evaluating an OpChainRoute.
There should always be at least one choice for each OpChainRoute element. If there is
only one simple choice, then it is recommended that the attributes on the
OpChainRoute element be used to define the choice.
<xs:sequence>
<xs:element name="Condition" type="Condition_Type" minOccurs="0"
/>
See the description of Condition_Type for details on the Condition element.
</xs:sequence>
<xs:attribute name="dtype" type="xs:string" fixed="OpChainChoice"
/>
<xs:attribute name="chainKey" type="xs:string" use="required" />
The "chainKey" attribute specifies the Op chain that is to be run, if the conditions are
right. This attribute is required on the Choice element.
The condition attribute specifies the fully qualified class name of the class that is used
to determine if the chain specified by the chainKey attribute should be run.
When using this attribute, a special shorthand notation can be applied to it to indicate to
invert the result of the condition. This is done by specifying an exclamation point ( ! ) as
the first character in the attribute value, then appending the condition's class name to it.
This attribute is always optional. If no condition is specified, then a default condition
that indicates to always run the chain will be used.
The chainType attribute indicates the type of chain action to use when running the
chain. This is always an optional attribute. The normally accepted values are:
• STACK [DEFAULT]
• START

</xs:complexType>
<xs:complexType name="Condition_Type">
Using an element to specify a condition is done when the condition class that is being
configured needs to have parameters configured on it. Any conditions that do not
require parameters should be defined using the condition attribute on the Choice
element.
<xs:sequence>
<xs:element name="Parameter" type="Parameter_Type" minOccurs="0"
maxOccurs="unbounded"/>
This element specifies the name and value of a parameter that is to be set on the
configured condition class.
</xs:sequence>
<xs:attribute name="class" type="xs:string"/>
This attribute specifies the fully-qualified class name of the condition class.
</xs:complexType>
To summarize, using the OpChainRoute element, you can now specify within
OpChainConfig.xml an Op chain to run based on a certain condition. The first choice
that has its condition satisfied is the chain that will be run. Any choices following the
accepted choice will be skipped. In a case with many choices, the "catch all" choice, if one
exists, should be configured as the last one. An OpChainRoute can end up not routing
anywhere if no choice has a condition that is satisfied. Examples of OpChainRoute are
abundant in the base OpChainConfig.xml files.
• Replacing an OpChainReference element with an OpChainRoute
<OpChainReference chainKey="PRINT_RECEIPTS" />
becomes
<OpChainRoute chainKey="PRINT_RECEIPTS" />
• Replacing an OpChainLink element with an OpChainRoute
<OpChainLink chainKey="BACK_OFFICE_LOGIN" />
becomes
<OpChainRoute chainKey="BACK_OFFICE_LOGIN" chainType="START" /
>
Configuring an OpChainRoute with a shorthand inverted condition

<OpChainRoute chainKey="PRE_TRANS_COMMISSIONED_ASSOCIATES"
condition="!dtv.pos.commission.CommissionByItem" />
Configuring an OpChainRoute with multiple, complex conditions. This particular

one replaced the RouteSaleItemOp
<OpChainRoute>

<Choice chainKey="SALE_ITEM_FINISH"
condition="dtv.pos.register.IsPhysicalItem" />

<Choice chainKey="SALE_VOUCHER_START">
<Condition class="dtv.pos.register.IsNonPhysicalItem">
<Parameter name="ItemType" value="VOUCHER"/>
</Condition>
</Choice>
<Choice chainKey="CREDIT_PAYMENT">
<Parameter name="ItemType" value="CREDIT_PAYMENT" />
</Condition>
</Choice>
<Choice chainKey="SALE_WARRANTY">
<Parameter name="ItemType" value="WARRANTY"/>
</Condition>
</Choice>
<Choice chainKey="SALE_WARRANTY_GIFT">
<Parameter name="ItemType" value="WARRANTY_GIFT"/>
</Condition>
</Choice>
<Choice chainKey="SALE_WARRANTY_RENEW">
<Parameter name="ItemType" value="WARRANTY_RENEWAL"/>
</Condition>
</Choice>
<Choice chainKey="SALE_NON_PHYSICAL_FINISH"
condition="dtv.pos.register.IsNonPhysicalItem" />
</OpChainRoute>

14
Internationalization
Overview
This chapter provides a general overview of internationalization, localization, and
multilingualization, and describes how these concepts are implemented and configured
in Xstore Point of Service.
Internationalization is a general term used to describe the ability of a software
application to be customized for use in different locations by people from different
cultures who speak different languages. The implementation of internationalization in
Xstore Point of Service allows it to be quickly customized to almost any language, even
though the developers may not know any language other than their own native
language.
Note: The Arial MS Unicode font is packaged and deployed with

Xstore Point of Service to ensure that register systems render all
languages correctly.
About this Chapter

• Internationalization (i18n) provides a general overview of internationalization,
multilingualization, and localization. This sections also provides a general
description of the implementation of these concepts in Xstore Point of Service.
• Xstore Point of Service i18n Implementation provides a more extensive description
of the technologies and methods used to implement internationalization in Xstore
Point of Service.
• Translation Resource Bundles describes the files that contain the text translations
used in Xstore Point of Service, how they are located by the software, and how
Xstore Point of Service determines file priority.
Internationalization 14-1
Internationalization (i18n)
Internationalization (i18n)
Internationalization refers to the process and methods that enable an application to be
used in a variety of geographic locations that have different languages and cultural
requirements. Although the source code is developed in one language, such as English,
the user interface is presented in the local language with sensitivity to cultural
requirements.
The abbreviation “i18n” is frequently used to signify internationalization, with the “18”
in the middle of “i18n” signifying the number of letters that were removed.1
Implementing i18n
Xstore Point of Service delivers the benefits of internationalization without requiring
changes to the source code. Through various files that contain “key/translation” pairs,
language-specific translations can be implemented in software created by a developer
who is not multilingual.
Each pair consists of a text key in the developer’s language followed by the translated
word or phrase in a different language. The key is a unique identifier used by Xstore
Point of Service to access the corresponding translation. Xstore Point of Service accesses
the correct translation at runtime.
Note: In Xstore Point of Service, all translation keys must begin with
the underscore (_) character.
The translation key is identical in all of the language-specific translation properties files,
but its corresponding translation varies by language. Each language has its own file with
all of the required key/translation pairs.
Applications of Internationalization in Xstore Point of Service

i18n is widely used in Xstore Point of Service. It has applications across many functional
areas and is used in many ways that enhance the application’s ability to be used
throughout the world. The following list identifies some areas where i18n is used in
Xstore Point of Service:
• Keystroke mapping
• Screen prompts and system messages
• Menu texts
• Reports titles, headers, and parameters
• Franking messages
• IPC Messages from Xstore Point of Service Environment
• Device names
• Function-oriented terms
1. From the I18nGuy™ Web Site

Xstore Point of Service i18n Implementation
Internationalization (i18n) and Localization (L10n)

Localization, or “L10n”, is the process by which internationalized software is customized
to match the locale where the software will be used. While i18n provides software with
the ability to be useful in any locale, L10n is the method by which the software is readied
for use in a specific locale.
Multilingualization (m17n)
In cases where several languages and character sets are required, multilingualization, or
“m17n”, is required. This methodology makes several different character sets from
several different languages available to users. Implementing m17n typically requires the
software to use Unicode or UTF-8 character sets.

This section describes the implementation of i18n in Xstore Point of Service, including
language options and character encoding.
Java Standards
Xstore Point of Service uses several Java standards in its implementation of i18n. Locales
are used to designate the language and country in which the application is to be used,
and Xstore Point of Service uses the language and country code standards defined by
Java. Xstore Point of Service also uses standard Java i18n methods and libraries.
Language Codes
Xstore Point of Service language codes combine an ISO-639-1 language code and an ISO-
3661-1 country code to identify the specific language files for the user interface. Samples
of some of the codes are specified in the table below:
Table 14-1: Sample Language Codes
Language and Country Language Code
English (US) en_US
French (France) fr_FR
Japanese ja_JP
Chinese zh_CN
Configuring Languages in Xstore Point of Service

Different areas of Xstore Point of Service may have their own language configurations,
which are designated in the file LocaleMap.xml. In this configuration file, each
MapEntry element has a key attribute that specifies an area of Xstore Point of Service,
and a corresponding value attribute that specifies the default language that it uses.
Sample Entries in LocaleMap.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Root dtype="Map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xsi:noNamespaceSchemaLocation="LocaleMap.xsd">
<MapEntry key="Document" value="en_US"/>
<MapEntry key="PoleDisplay" value="en_US"/>
<MapEntry key="Receipt" value="en_US"/>
<MapEntry key="View" value="en_US"/>
<MapEntry key="Error" value="en_US"/>
<MapEntry key="Log" value="en_US"/>
</Root>
The key attribute settings for each <MapEntry> element in the file LocaleMap.xml are
explained in the following table:
Table 14-2: MapEntry Keys for Areas of Xstore Point of Service
Key Xstore Point of Service Area
Document Hard copy documents
PoleDisplay Customer display device
Receipt Printed receipts
View Xstore Point of Service on-screen user interface
Error Error messages
Log Log files
Language Files
For each language available in Xstore Point of Service, there is one corresponding file
that contains all the text items that a user will see. This includes all messages and
prompts in the system. Each text item in the file is indexed so that different translations
of the same message are found in a consistent manner.
Each language translation file is named using the format shown below. The file extension
indicates that the file is a “properties” file.
translations_[language code].properties

The designation of [language code] is replaced by the proper language code as

shown in the table below. Samples of translations that use the same character data are
also shown. Xstore Point of Service uses the UTF-8 standard to encode character data.
Table 14-3: Sample Translations
File Sample Entry
translations_en.properties _pleaseWait=Please Wait
translations_fr.properties _pleaseWait=Attendre svp
translations_ja.properties _pleaseWait= \u304a\u5f85\u3061

\u304f\u3060\u3055\u3044
Note: The key (_pleaseWait) associated with each section of text does
not change. The Japanese translation file does not show actual
characters themselves, but lists the UTF-8 codes that correspond to the
Japanese characters.
Individual Customization
In addition to setting a default language for the Xstore Point of Service system, the
language can also be configured for each individual user. When a user logs in, the
interface’s language can be adjusted to match the needs or desires of that user. For
example, if a French-speaking Canadian were working in the United States, the system
could display prompts in French instead of the system’s default English language.
Note: To configure the language for a user, set the preferred locale for
an employee in the preferred_locale column in the crm_party table.
Also, verify the locale is listed in the AvailableLocales.xml file.
In Xstore Point of Service, you can set up an employee’s preferred
locale in the Employee Maintenance General tab, Language field.
Translation Resource Bundles

Resource bundles are properties files grouped together by a common base name, but
with a different locale suffix. This enables different properties to be used by Xstore Point
of Service dependent on the user's locale settings. Resource bundles are managed by the
configuration path.
Note: Resource-bundle-specific system.properties paths have been

eliminated. All bundles are now managed via the existing
dtv.config.path properties (whether obtained from Xadmin or
otherwise) so that profile groups/elements can be leveraged.
The following resource-bundle-specific system.properties paths found
in earlier Xstore Point of Service versions were eliminated:
dtv.pos.i18n.translation= dtv/i18n/
translations;cust/translations;cust/loyalty/
translations;cust/loyalty/award/translations;order/
translations
dtv.pos.i18n.hardware= dtv/i18n/hardware
dtv.pos.i18n.keyboard= dtv/i18n/keyboard
dtv.pos.i18n.phone= dtv/i18n/PhoneNumbers
dtv.pos.i18n.help= dtv/i18n/help
dtv.pos.i18n.emailTemplate= dtv/i18n/emailTemplate
Language and Country

The file translations_[locale].properties is an example of a resource bundle.
In the file name, “[locale]” represents a 2-letter code for the language used in a
geographic location/locale—”en” for English, “fr” for French, “zh” for Chinese, etc. A
capitalized 2-letter code indicates a country—CA for Canada, JA for Japan, etc.—in
which there may be variations of a specified language. The file name may include both a
locale and a country designation. The file contains the actual text strings that will be
substituted for a corresponding translation key whenever the application encounters
that key.
Translation Key Examples

_return=Return (from translations_en.properties for English)
_return=Retour (from translations_fr_CA.properties for French-
Canadian)
_return=\u8fd4\u5374 (Unicode, from translations_ja.properties
for Japanese)
Translations for English are in the file translations_en.properties, and
translations for French (as spoken in France) are in translations_fr.properties.
If the language has variations, depending on the country in which it is spoken, that may
be expressed in the file name. For example, translations_fr_CA.properties
would contain the translation for French as it is spoken in Canada.

Multi-Path Search Order for Translating a Key Into French-Canadian

This example uses the two search paths for translations defined in the preceding sample
directory path. The following table indicates the order in which the paths and the
translation files in those paths will be searched.
Table 14-4: Search Order for a Multi-Path Translation
Search Path (in Order) Comment
...version1/ the most specific locale; highest-

translations_fr_CA.properties priority search path.
...version1/ a less-specific locale; highest-priority

translations_fr.properties search path.
...version1/translations_[default the default locale; highest-priority

locale].properties search path.
...\dtv\res\config\translations_fr_CA the most-specific locale; lower-

.properties priority search path.
...\dtv\res\config\translations_fr.pr a less-specific locale; lower-priority

operties search path.
...\dtv\res\config\translations_[defa the default locale; lower-priority

ult locale].properties search path.
The first translations file that contains the requested key also contains the corresponding
translation string that will be used as the resulting output in the application. If there is
no corresponding key mapping in any of the translation files that is searched, a string in
the form “mr@[invalid translation key]” is used as the output.
Note: “mr” is an abbreviation for “missing resource”.
Defining Common Mappings for Different Keys

Each localized element in Xstore Point of Service should be assigned a unique key. Even
if the label “name” on a customer search form and the same label “name” on an
employee search form are intended to display the same text (e.g. “Name”), each of them
should be assigned a unique key (e.g. _customerSearchName and
_employeeSearchName). This policy enables similar translations to be differentiated
in the future (e.g. changing the “name” label on the employee search form to “Employee
Name”) without having to change the code or configuration sources from which the
keys are derived.
However, this policy would require a good deal of duplication in each translation file. In
the previous example, each locale-specific file would require a mapping for both
_customerSearchName and _employeeSearchName, even though both might
resolve to the identical localized value. When language translation providers charge per
word, the monetary cost of that duplication can be significant.
To ease the difficulty of managing a large number of keys with translated values that are
common across the application (name, city, state, country, etc.), the file
translations.map.properties is helpful to the application developer. Instead of
specifying key-to-translated value associations, the file
translations.map.properties enumerates a set of key-to-key pairings.
Configuration Accelerators
When the application tries to convert a translation key into a locale-specific literal string,
it first consults translations.map.properties to determine the correct key to use.
If such an entry exists, the searched-for key in the locale-specific translations files will be
used as the mapped key rather than the one identified by the application. If no such
entry exists, then the application-specified key will serve as the effective key for
translation lookup purposes.
Example in translations.map.properties
_customerSearchName=_commonName
_employeeSearchName=_commonName
Example in translations_en.properties
_commonName=Name
Example in translations_es_MX.properties
_commonName=Nombre
In the preceding example, the principle of unique keys is preserved, but only a single
translation must be performed for each supported locale. Any number of labels, such as
“Name”, can similarly be accommodated by mapping their unique keys to the
_commonName effective key without requiring any additional translation work in any
language.
Whenever a divergent translation is needed for any of the commonly mapped keys,
those keys can be remapped in, or removed from, the
translations.map.properties file. If necessary, a new entry might also need to be
added to each locale-specific translation file.
Configuration Accelerators
For information about configuration accelerators (localization packs), including
procedures for applying them, see the Xstore Point of Service Configuration Accelerator
Guide. This document is available on My Oracle Support, Doc ID 1944671.1.
Xstore Office and SystemConfigMetadata.properties

Note: For developer-level technical details, see the "base" copy of
dtv/res/config/SystemConfigMetadata.properties, which
contains extensive documentation in comments at the top of the file.
Overview
The SystemConfigMetadata.properties file contains critical information needed
by the Xstore Office System Config GUI. It is a counterpart to Xstore Point of Service
SystemConfig.xml file, which is the main file for storing system configuration
settings.
As there are multiple copies of SystemConfig.xml in Xstore Point of Service which
support base configurations and customer overrides (through the Xstore Point of Service
configuration path system), there are also multiple
SystemConfigMetadata.properties files. However, unlike SystemConfig.xml,
these metadata files are not governed/configurable by the configuration path. In fact,
there will only ever be exactly two copies of SystemConfigMetadata.properties:

• dtv/res/config/SystemConfigMetadata.properties - the base definition

found in config.jar, and companion to SystemConfig.xml in the same location
• version1/SystemConfigMetadata.properties - the Operations team's
"overrides", typically found in the customer jar. All customer-specific overrides for
metadata must be put into this file.
i18n and the SystemConfigMetadata.properties File

The SystemConfigMetadata.properties file is used in two different ways by
Xstore Office. First, it is used by custom code which parses all of the properties and
dynamically constructs the System Config GUI using its information in combination
with the contents of SystemConfig.xml. Also, it is separately loaded using the
DtvResourceBundle library, and its contents are treated as Xstore Point of Service-
style i18n translations.
If you look at a SystemConfigMetadata.properties file, you will notice that some
of the properties keys are prefixed with an underscore ("_"); any such property can and
will be treated as a translatable i18n resource. This allows an exhaustive amount of
System Configuration information to be fully internationalized.
SystemConfigMetadata.properties File Example

_Store---SystemConfig---EmployeeSale---AllowSelfSale.label=Allow
User To Ring His/Her Own Sale?
_Store---SystemConfig---EmployeeSale---
AllowSelfSale.description=Determines whether or not the system
allows employees to ring retail transactions for themselves.
Store---SystemConfig---EmployeeSale---AllowSelfSale.datatype=Bool
Store---SystemConfig---EmployeeSale---
AllowSelfSale.category=_sales
Store---SystemConfig---EmployeeSale---AllowSelfSale.order=0
AllowSelfSale.tag.1=_register
AllowSelfSale.tag.2=_security
Store---SystemConfig---EmployeeSale---AllowSelfSale.tag.3=_sale
Creating a "Stub" Metadata File for Other Languages

Since a SystemConfigMetadata.properties file doubles as an i18n resource
bundle file, the easiest way to create a "stub" for a language translation is to "grep" the
base file for all lines which start with an underscore. Here's an example of a Unix
command which will filter out all of the i18n keys, and strip out certain items (the "do
not translate" ones), and create a stub for the French language:
grep ^_ SystemConfigMetadata.properties | grep -v "**DO NOT
TRANSLATE**" > SystemConfigMetadata.properties_fr_FR

Xstore Pos-170-03-Ftg

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Xstore Pos-170-03-Ftg

Uploaded by

Copyright:

Available Formats

Oracle® Retail Xstore Point of Service

Frameworks & Technologies Guide

2 About Xstore Point of Service Configuration................................2-1

4 Data Transfer for Xstore Framework .............................................4-1

6 Persistence Mapping Configuration ..............................................6-1

9 DocBuilder Framework ...................................................................9-1

10 Hardware Configuration & Communication ................................10-1

Send your comments to us using the electronic mail address: retail-doc_us@oracle.com

Access to Oracle Support

• Xstore Point-of-Service Technical Guide

Review Patch Documentation

Oracle Retail Documentation on the Oracle Technology

About This Manual

1-2 Frameworks & Technologies Guide

Note: Many of the configurations in Xstore Point of Service can be set

Configuration Path Updates from Xstore Office

Note: See the Xstore Point of Service Technical Guide and Xstore Office

About Xstore Point of Service Configuration 2-1

Java Resource Bundle

Note: In this situation a database may be used; however, this is less

2-2 Frameworks & Technologies Guide

About Xstore Point of Service Configuration 2-3

2-4 Frameworks & Technologies Guide

About This Chapter

The Operation Chain Framework (OpChains)

Operation Chain Defined

Operations and Chains

Operation Chains 3-1

OpChains and Business Logic

OpChain Example: Printing a Receipt

Figure 3-1: Sample Process Flow in an OpChain

Each Operation Chain must have a unique identifying name (such as

Benefits of Operations Chains

3-2 Frameworks & Technologies Guide

Adding a New Step to an OpChain

Figure 3-2: Inserting an OpChain Illustrates Reusability Feature

Changing the Order of Operations in an OpChain

Operation Chains 3-3

Figure 3-3: Reordering the Execution Order in an OpChain

Note: This example is provided for illustration purposes only and

Overriding and Extending Xstore Point of Service Base Functions

Figure 3-4: Overriding and Extending Operations in an OpChain

3-4 Frameworks & Technologies Guide

Operation Chains 3-5

3-6 Frameworks & Technologies Guide

* TransactionModified - Xstore Point of Service recalculates the monetary

- rollbackChainKey - This attribute refers to the <OpChain> to run if the

Note: A rollback level declares a Chain as a “fallback position”

Operation Chains 3-7

3-8 Frameworks & Technologies Guide

<Choice chainKey="SHIPPING_PRINT_GENERIC_LABEL" condition=

Note: Conditions can be specified as attributes like this, or with a

- chainType - Determines the chain type: STACK (default) or START. When no

Note: Conditions can be specified using an element like this, or with a

Note: Class is optional. If not specified, defaults to the operation

Note: Class is optional. If not specified, defaults to the operation

Note: Class is optional. If not specified, defaults to

- validationsBean - A reference to the bean that defines the list of validation

Operation Chains 3-9

<OpChain name="REFUND_MISC" contextKey="REFUND_TENDER_EMPTY_MENU_OPTION">

Example 1: OpChain Before Reconfiguration

<!- Prompt for a REASON for the no sale transaction -->

<!- Prompt for a COMMENT about the no sale transaction -->