ETAJ_ValueAddDevGuide ETAJ Value Add Dev Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 173

Download
Open PDF In Browser	View PDF

We are now Refinitiv, formerly the
Financial and Risk business of
Thomson Reuters. We’ve set a bold
course for the future – both ours and
yours – and are introducing our new
brand to the world.
As our brand migration will be
gradual, you will see traces of our
past through documentation, videos,
and digital platforms.
Thank you for joining us on our
brand journey.

Transport API Java Edition
V3.2.x

VALUE ADDED COMPONENTS
DEVELOPERS GUIDE JAVA EDITION

Document Version: 3.2.2
Date of issue: 8 November 2018
Document ID: ETAJ322UMVAC.180

Legal Information

© Thomson Reuters 2015 - 2018. All rights reserved.
Thomson Reuters, by publishing this document, does not guarantee that any information contained herein is and will remain accurate or that
use of the information will ensure correct and faultless operation of the relevant service or equipment. Thomson Reuters, its agents and
employees, shall not be held liable to or through any user for any loss or damage whatsoever resulting from reliance on the information
contained herein.
This document contains information proprietary to Thomson Reuters and may not be reproduced, disclosed, or used in whole or part without
the express written permission of Thomson Reuters.
Any Software, including but not limited to, the code, screen, structure, sequence, and organization thereof, and Documentation are protected
by national copyright laws and international treaty provisions. This manual is subject to U.S. and other national export regulations.
Nothing in this document is intended, nor does it, alter the legal obligations, responsibilities or relationship between yourself and Thomson
Reuters as set out in the contract existing between us.

Transport API Java Edition 3.2.x – Value Added Components Developers Guide
ETAJ322UMVAC.180

Contents

Contents
Chapter 1
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.7.1
1.7.2
1.7.3

Chapter 2
2.1
2.2
2.3
2.4
2.4.1
2.4.2
2.4.3
2.5
2.6
2.7

Introduction ...................................................................................................................... 1
About this Manual ...........................................................................................................................................
Audience .........................................................................................................................................................
Programming Language..................................................................................................................................
Acronyms and Abbreviations ..........................................................................................................................
Additional References and Resources............................................................................................................
Documentation Feedback ...............................................................................................................................
Document Conventions...................................................................................................................................
Typographic ..............................................................................................................................................
Document Structure..................................................................................................................................
Diagrams ..................................................................................................................................................

1
1
1
1
3
3
3
3
3
4

Product Description and Overview ................................................................................ 5
What is the Transport API? .............................................................................................................................
What are Transport API Value Added Components? .....................................................................................
Transport API Reactor ....................................................................................................................................
OMM Consumer Watchlist ..............................................................................................................................
Data Stream Aggregation and Recovery ..................................................................................................
Additional Features...................................................................................................................................
Usage Notes .............................................................................................................................................
Administration Domain Model Representations ..............................................................................................
Value Added Utilities .......................................................................................................................................
Payload Cache................................................................................................................................................

5
5
6
7
7
7
7
8
8
8

Chapter 3

Building an OMM Consumer ........................................................................................... 9

3.1
3.2
3.3
3.4
3.5
3.6
3.7

Overview ......................................................................................................................................................... 9
Leverage Existing or Create New Reactor ...................................................................................................... 9
Implement Callbacks and Populate Role ........................................................................................................ 9
Establish Connection using Reactor.connect................................................................................................ 10
Issue Requests and/or Post Information ....................................................................................................... 10
Log Out and Shut Down................................................................................................................................ 10
Additional Consumer Details ......................................................................................................................... 11

Chapter 4
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
4.9
4.10
4.11

Building an OMM Interactive Provider ......................................................................... 12
Overview .......................................................................................................................................................
Leverage Existing or Create New Reactor ....................................................................................................
Create a Server.............................................................................................................................................
Implement Callbacks and Populate Role ......................................................................................................
Associate Incoming Connections Using Reactor.accept...............................................................................
Perform Login Process..................................................................................................................................
Provide Source Directory Information ...........................................................................................................
Provide or Download Necessary Dictionaries ...............................................................................................
Handle Requests and Post Messages ..........................................................................................................
Disconnect Consumers and Shut Down .......................................................................................................
Additional Interactive Provider Details ..........................................................................................................

12
12
13
13
13
14
14
15
15
16
16

Chapter 5

Building an OMM Non-Interactive Provider ................................................................. 17

5.1
5.2
5.3

Building an OMM Non-Interactive Provider Overview ................................................................................... 17
Leverage Existing or Create New Reactor .................................................................................................... 17
Implement Callbacks and Populate Role ...................................................................................................... 17

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

iii

5.4
5.5
5.6
5.7
5.8

Establish Connection using Reactor.connect................................................................................................
Download the Dictionary ...............................................................................................................................
Provide Content ............................................................................................................................................
Log Out and Shut Down................................................................................................................................
Additional Non-Interactive Provider Details...................................................................................................

Chapter 6
6.1
6.1.1
6.1.2
6.1.3
6.1.4
6.2
6.2.1
6.2.2
6.3
6.3.1
6.3.2
6.3.3
6.3.4
6.4
6.4.1
6.4.2
6.5
6.5.1
6.5.2
6.5.3
6.5.4
6.5.5
6.5.6
6.5.7
6.6
6.6.1
6.6.2
6.7
6.7.1
6.7.2
6.7.3
6.7.4
6.7.5
6.7.6
6.7.7
6.7.8
6.7.9
6.8
6.8.1
6.8.2
6.8.3

Chapter 7
7.1
7.2
7.2.1
7.2.2
7.2.3

18
18
18
19
19

Reactor Detailed View.................................................................................................... 20
Concepts .......................................................................................................................................................
Functionality: Transport API Versus Transport API Reactor ..................................................................
Reactor Error Handling ...........................................................................................................................
Reactor Error Info Codes........................................................................................................................
Transport API Reactor Application Lifecycle ..........................................................................................
Reactor Use ..................................................................................................................................................
Creating a Reactor..................................................................................................................................
Destroying a Reactor ..............................................................................................................................
Reactor Channel Use....................................................................................................................................
Reactor Channel Roles...........................................................................................................................
Reactor Channel Role: OMM Consumer ................................................................................................
Reactor Channel Role: OMM Provider ...................................................................................................
Reactor Channel Role: OMM Non-Interactive Provider..........................................................................
Managing Reactor Channels.........................................................................................................................
Adding Reactor Channels.......................................................................................................................
Removing Reactor Channels..................................................................................................................
Dispatching Data...........................................................................................................................................
Reactor Dispatch Methods .....................................................................................................................
Reactor Callback Methods......................................................................................................................
Reactor Callback: Channel Event...........................................................................................................
Reactor Callback: Default Message .......................................................................................................
Reactor Callback: RDM Login Message.................................................................................................
Reactor Callback: RDM Directory Message ...........................................................................................
Reactor Callback: RDM Dictionary Message..........................................................................................
Writing Data ..................................................................................................................................................
Writing Data using ReactorChannel.submit(Msg…) ...............................................................................
Writing Data Using ReactorChannel.submit(TransportBuffer...).............................................................
Creating and Using Tunnel Streams .............................................................................................................
Authenticating a Tunnel Stream .............................................................................................................
Opening a Tunnel Stream.......................................................................................................................
Negotiating Stream Behaviors: Class of Service ....................................................................................
Tunnel Stream Callback Methods and Event Types...............................................................................
Code Sample: Opening and Managing a Tunnel Stream .......................................................................
Accepting Tunnel Streams......................................................................................................................
Receiving Content on a TunnelStream...................................................................................................
Sending Content on a TunnelStream .....................................................................................................
Closing a Tunnel Stream ........................................................................................................................
Reactor Utility Methods .................................................................................................................................
General Reactor Utility Methods.............................................................................................................
ReactorChannelInfo Class Members......................................................................................................
ReactorChannel.ioctl Option Values.......................................................................................................

20
21
22
22
23
24
24
25
26
27
29
31
32
33
33
37
38
38
40
41
44
45
46
48
50
50
54
61
62
62
64
68
70
71
76
76
78
78
79
79
79

Administration Domain Models Detailed View ............................................................ 80
Concepts .......................................................................................................................................................
Message Base ..............................................................................................................................................
Message Base Members ........................................................................................................................
Message Base Method ...........................................................................................................................
RDM Message Types .............................................................................................................................

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

80
81
81
81
82
iv

7.3
7.3.1
7.3.2
7.3.3
7.3.4
7.3.5
7.3.6
7.3.7
7.3.8
7.3.9
7.3.10
7.3.11
7.4
7.4.1
7.4.2
7.4.3
7.4.4
7.4.5
7.4.6
7.4.7
7.4.8
7.4.9
7.4.10
7.4.11
7.4.12
7.4.13
7.4.14
7.4.15
7.4.16
7.4.17
7.5
7.5.1
7.5.2
7.5.3
7.5.4
7.5.5
7.5.6
7.5.7
7.6
7.6.1
7.6.2
7.6.3
7.6.4
7.6.5
7.6.6
7.6.7
7.6.8

Chapter 8
8.1
8.2
8.2.1
8.2.2
8.2.3
8.2.4

RDM Login Domain....................................................................................................................................... 83
Login Request......................................................................................................................................... 83
Login Refresh ......................................................................................................................................... 86
Login Status............................................................................................................................................ 93
Login Close............................................................................................................................................. 96
Login Consumer Connection Status ....................................................................................................... 96
Login Post Message Use........................................................................................................................ 98
Login Ack Message Use ......................................................................................................................... 98
Login Attributes....................................................................................................................................... 98
Login Message ..................................................................................................................................... 100
Login Message Utility Messages .......................................................................................................... 101
Login Encoding and Decoding.............................................................................................................. 101
RDM Source Directory Domain ................................................................................................................... 106
Directory Request ................................................................................................................................. 106
Directory Refresh.................................................................................................................................. 108
Directory Update................................................................................................................................... 110
Directory Status .................................................................................................................................... 112
Directory Close ..................................................................................................................................... 114
Directory Consumer Status................................................................................................................... 114
Directory Service .................................................................................................................................. 115
Directory Service Info Filter .................................................................................................................. 116
Directory Service State Filter ................................................................................................................ 119
Directory Service Group Filter .............................................................................................................. 120
Directory Service Load Filter ................................................................................................................ 121
Directory Service Data Filter................................................................................................................. 122
Directory Service Link Info Filter........................................................................................................... 123
Directory Service Link........................................................................................................................... 124
Directory Message................................................................................................................................ 125
Directory Message Utility Methods ....................................................................................................... 125
Directory Encoding and Decoding ........................................................................................................ 126
RDM Dictionary Domain.............................................................................................................................. 132
Dictionary Request ............................................................................................................................... 132
Dictionary Refresh ................................................................................................................................ 133
Dictionary Status................................................................................................................................... 135
Dictionary Close.................................................................................................................................... 135
Dictionary Messages ............................................................................................................................ 136
Dictionary Message: Utility Methods..................................................................................................... 136
Dictionary Encoding and Decoding....................................................................................................... 136
RDM Queue Messages............................................................................................................................... 142
Queue Data Message Persistence ....................................................................................................... 142
Queue Request..................................................................................................................................... 142
Queue Refresh ..................................................................................................................................... 143
Queue Status........................................................................................................................................ 143
Queue Close......................................................................................................................................... 143
Queue Data .......................................................................................................................................... 144
QueueDataExpired ............................................................................................................................... 147
Queue Ack ............................................................................................................................................ 148

Payload Cache Detailed View ..................................................................................... 149
Concepts .....................................................................................................................................................
Payload Cache............................................................................................................................................
Payload Cache Management ...............................................................................................................
Cache Error Handling ...........................................................................................................................
Payload Cache Instances .....................................................................................................................
Managing RDM Field Dictionaries for Payload Cache..........................................................................

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

149
150
150
150
151
152
v

8.2.5
8.3
8.3.1
8.3.2
8.3.3

Payload Cache Utilities.........................................................................................................................
Payload Cache Entries................................................................................................................................
Managing Payload Cache Entries ........................................................................................................
Applying Data .......................................................................................................................................
Retrieving Data .....................................................................................................................................

154
155
155
156
157

Appendix A Value Added Utilities .................................................................................................... 160

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Contents

List of Figures
Figure 1.
Figure 2.
Figure 3.
Figure 4.
Figure 5.
Figure 6.
Figure 7.
Figure 8.
Figure 9.

Network Diagram Notation .............................................................................................................................. 4
UML Diagram Notation.................................................................................................................................... 4
OMM APIs with Value Added Components .................................................................................................... 5
Transport API Value Added Components ....................................................................................................... 6
Transport API Reactor Thread Model ........................................................................................................... 20
Transport API Reactor Application Lifecycle ................................................................................................. 23
Flow Chart for writing data via ReactorChannel.submit(TransportBuffer...).................................................. 54
Tunnel Stream Illustration ............................................................................................................................. 61
Consumer Application using Cache to Store Payload Data for Item Streams ............................................ 149

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

vii

Contents

List of Tables
Table 1:
Table 2:
Table 3:
Table 4:
Table 5:
Table 6:
Table 7:
Table 8:
Table 9:
Table 10:
Table 11:
Table 12:
Table 13:
Table 14:
Table 15:
Table 16:
Table 17:
Table 18:
Table 19:
Table 20:
Table 21:
Table 22:
Table 23:
Table 24:
Table 25:
Table 26:
Table 27:
Table 28:
Table 29:
Table 30:
Table 31:
Table 32:
Table 33:
Table 34:
Table 35:
Table 36:
Table 37:
Table 38:
Table 39:
Table 40:
Table 41:
Table 42:
Table 43:
Table 44:
Table 45:
Table 46:
Table 47:
Table 48:
Table 49:
Table 50:
Table 51:

Acronyms and Abbreviations .......................................................................................................................... 1
Transport API Functionality and Transport API Reactor Comparison........................................................... 21
ReactorErrorInfo Members ................................................................................................................... 22
Reactor Error Info Codes .............................................................................................................................. 22
Class Members............................................................................................................................................ 24
Reactor Creation Method ........................................................................................................................... 24
ReactorOptions Class Members.............................................................................................................. 24
ReactorOptions Utility Method ................................................................................................................. 25
Reactor Destruction Method....................................................................................................................... 25
ReactorChannel Class Members.............................................................................................................. 26
ReactorRole Class Members .................................................................................................................... 27
ReactorRoleTypes Enumerated Values ................................................................................................... 28
ConsumerRole Class Members .................................................................................................................. 29
ConsumerRole.dictionaryDownloadMode Enumerated Values.......................................................... 30
OMM Consumer Role Watchlist Options ...................................................................................................... 30
ConsumerRole Utility Method ..................................................................................................................... 30
ProviderRole Class Members .................................................................................................................. 31
ProviderRole Utility Method ..................................................................................................................... 31
NIProviderRole Class Members.............................................................................................................. 32
NIProviderRole Utility Method ................................................................................................................. 32
Reactor.connect Method......................................................................................................................... 33
ReactorConnectOptions Class Members
...................................................................................................... 34
ReactorConnectInfo Class Members ..................................................................................................... 34
ReactorConnectOptions Utility Method.................................................................................................. 34
Reactor.accept Method........................................................................................................................... 36
ReactorAcceptOptions Class Members................................................................................................. 36
RsslReactorAcceptOptions Utility Method ........................................................................................... 36
ReactorChannel.close Function ............................................................................................................ 37
Reactor Dispatch Methods
............................................................................................................................ 38
ReactorDispatchOptions Class Members ............................................................................................ 39
ReactorDispatchOptions Utility Method................................................................................................ 39
ReactorCallbackReturnCodes Callback Return Codes........................................................................ 40
ReactorEvent Class Members .................................................................................................................. 40
ReactorChannelEvent Class Member..................................................................................................... 41
ReactorChannelEventType Enumeration Values ................................................................................... 41
ReactorChannelEvent Utility Methods .................................................................................................... 42
ReactorMsgEvent Class Members............................................................................................................ 44
ReactorMsgEvent Utility Method ............................................................................................................... 44
RDMLoginMsgEvent Class Member ........................................................................................................... 45
RDMLoginMsgEvent Utility Method............................................................................................................. 45
RDMDirectoryMsgEvent Class Member................................................................................................... 47
RDMDirectoryMsgEvent Utility Method .................................................................................................... 47
RDMDictionaryMsgEvent Class Member ................................................................................................ 49
RDMDictionaryMsgEvent Utility Method.................................................................................................. 49
ReactorChannel.submit(Msg...) Method .......................................................................................... 50
ReactorSubmitOptions Class Members................................................................................................. 51
ReactorChannel.submit(Msg...) Return Codes ................................................................................ 51
ReactorRequestMsgOptions Class Members ........................................................................................ 52
ReactorSubmitOptions Utility Method .................................................................................................... 52
ReactorChannel Buffer Management Methods............................................................................................. 55
ReactorChannel.getBuffer Return Values .......................................................................................... 56

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

viii

Table 52:
Table 53:
Table 54:
Table 55:
Table 56:
Table 57:
Table 58:
Table 59:
Table 60:
Table 61:
Table 62:
Table 63:
Table 64:
Table 65:
Table 66:
Table 67:
Table 68:
Table 69:
Table 70:
Table 71:
Table 72:
Table 73:
Table 74:
Table 75:
Table 76:
Table 77:
Table 78:
Table 79:
Table 80:
Table 81:
Table 82:
Table 83:
Table 84:
Table 85:
Table 86:
Table 87:
Table 88:
Table 89:
Table 90:
Table 91:
Table 92:
Table 93:
Table 94:
Table 95:
Table 96:
Table 97:
Table 98:
Table 99:
Table 100:
Table 101:
Table 102:
Table 103:
Table 104:
Table 105:
Table 106:

ReactorChannel.submit(TransportBuffer...) Method ................................................................ 56
ReactorChannel.submit(TransportBuffer...) Return Codes ...................................................... 57
ReactorChannel.packBuffer Method ................................................................................................... 58
ReactorChannel.packBuffer Return Values ........................................................................................ 59
TunnelStreamAuthInfo Members........................................................................................................... 62
ReactorChannel.openTunnelStream Method ...................................................................................... 62
TunnelStreamOpenOptions .................................................... 63
ClassOfService.common Members......................................................................................................... 64
ClassOfService.authentication Members ....................................................................................... 65
ClassOfService.flowControl Members.............................................................................................. 65
ClassOfService.dataIntegrity Members ......................................................................................... 66
ClassOfService.guarantee Members .................................................................................................. 67
Tunnel Stream Callback Methods ................................................................................................................. 68
Tunnel Stream Callback Event Types ........................................................................................................... 69
TunnelStreamRequestEvent Members .................................................................................................. 72
ReactorChannel.acceptTunnelStream Method.................................................................................. 72
TunnelStreamAcceptOptions Options................................................................................................... 73
ReactorChannel.rejectTunnelStream Method.................................................................................. 73
TunnelStreamRejectOptions Options................................................................................................... 73
Tunnel Stream Buffer Methods ..................................................................................................................... 76
Tunnel Stream Submit Method ..................................................................................................................... 76
Members...................................................................................................................................................... 77
Tunnel Closure Method................................................................................................................................. 78
Reactor Utility Methods ................................................................................................................................. 79
ReactorChannelInfo Class Members ..................................................................................................... 79
Domains Representations in the Administration Domain Model Value Added Component .......................... 80
MsgBase Members ....................................................................................................................................... 81
MsgBase Method .......................................................................................................................................... 81
Domain Representations Message Types
.................................................................................................... 82
LoginRequest Members ............................................................................................................................ 83
LoginRequest Flags .................................................................................................................................. 85
LoginRequest Utility Method ..................................................................................................................... 85
LoginRefresh Members ............................................................................................................................ 86
LoginRefresh Flags .................................................................................................................................. 88
LoginSupportFeatures Members........................................................................................................... 89
LoginSupportFeaturesFlags .................................................. 90
LoginConnectionConfig Members......................................................................................................... 91
LoginConnectionConfig Methods.......................................................................................................... 91
ServerInfo Members................................................................................................................................. 92
ServerInfo Flags....................................................................................................................................... 92
ServerInfo Methods.................................................................................................................................. 92
LoginStatus Members .............................................................................................................................. 93
LoginStatus Flags..................................................................................................................................... 94
LoginClose Member .................................................................................................................................. 96
LoginConsumerConnectionStatus Members ....................................................................................... 96
LoginConsumerConnectionStatus Flags ............................................................................................. 97
LoginWarmStandbyInfo Members........................................................................................................... 97
LoginWarmStandbyInfo Methods ............................................................................................................ 97
LoginAttrib Members .............................................................................................................................. 98
LoginAttrib Methods.............................................................................................................................. 100
LoginAttribFlags .......................................................... 100
LoginMsg Interfaces .................................................................................................................................. 100
LoginMsg Utility Methods .......................................................................................................................... 101
Login Encoding and Decoding Methods ..................................................................................................... 101
DirectoryRequest Members ................................................................................................................. 106

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Table 107:
Table 108:
Table 109:
Table 110:
Table 111:
Table 112:
Table 113:
Table 114:
Table 115:
Table 116:
Table 117:
Table 118:
Table 119:
Table 120:
Table 121:
Table 122:
Table 123:
Table 124:
Table 125:
Table 126:
Table 127:
Table 128:
Table 129:
Table 130:
Table 131:
Table 132:
Table 133:
Table 134:
Table 135:
Table 136:
Table 137:
Table 138:
Table 139:
Table 140:
Table 141:
Table 142:
Table 143:
Table 144:
Table 145:
Table 146:
Table 147:
Table 148:
Table 149:
Table 150:
Table 151:
Table 152:
Table 153:
Table 154:
Table 155:
Table 156:
Table 157:
Table 158:
Table 159:
Table 160:
Table 161:

DirectoryRequest Flags........................................................................................................................
DirectoryRequest Utility Methods .........................................................................................................
DirectoryRefresh Members .................................................................................................................
DirectoryRefresh Flags........................................................................................................................
DirectoryUpdate Members....................................................................................................................
DirectoryUpdate Flags..........................................................................................................................
DirectoryStatus Members....................................................................................................................
DirectoryStatus Flags.........................................................................................................................
DirectoryStatus Utility Methods ...........................................................................................................
DirectoryClose Member........................................................................................................................
DirectoryConsumerStatus Members ..................................................................................................
ConsumerStatusService Members.......................................................................................................
Service Members .....................................................................................................................................
Service Flags ...........................................................................................................................................
Service Utility Methods ............................................................................................................................
ServiceInfo Members ............................................................................................................................
ServiceInfo Flags..................................................................................................................................
ServiceInfo Utility Methods....................................................................................................................
ServiceState Members ..........................................................................................................................
ServiceState Flags ................................................................................................................................
ServiceState Utility Methods..................................................................................................................
ServiceGroup Members ..........................................................................................................................
ServiceGroup Flags ................................................................................................................................
ServiceGroup Utility Methods..................................................................................................................
ServiceLoad Members ............................................................................................................................
ServiceLoad Flags...................................................................................................................................
ServiceLoad Utility Methods....................................................................................................................
ServiceData Members ............................................................................................................................
ServiceData Flags...................................................................................................................................
ServiceData Methods..............................................................................................................................
ServiceLinkInfo Members....................................................................................................................
ServiceLinkInfo Methods.....................................................................................................................
ServiceLink Members ............................................................................................................................
ServiceLink Flags...................................................................................................................................
ServiceLink Methods..............................................................................................................................
DirectoryMsg Interfaces .........................................................................................................................
DirectoryMsg Utility Methods..................................................................................................................
Directory Encoding and Decoding Methods ................................................................................................
DictionaryRequest Members ...............................................................................................................
DictionaryRequest Flag .......................................................................................................................
DictionaryRefresh Members ...............................................................................................................
DictionaryRefreshFlags ......................................................................................................................
DictionaryStatus Members .................................................................................................................
DictionaryStatus Flags........................................................................................................................
DictionaryClose Member .....................................................................................................................
DictionaryMsg Interfaces .......................................................................................................................
DictionaryMsg Utility Methods ...............................................................................................................
Dictionary Encoding and Decoding Methods ..............................................................................................
QueueRequest Members ..........................................................................................................................
QueueRefresh Members ..........................................................................................................................
QueueStatus Members ............................................................................................................................
QueueClose Members...............................................................................................................................
QueueData Members.................................................................................................................................
Queue Data Flag.........................................................................................................................................
Queue Data Message Timeout Codes
........................................................................................................

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

107
107
108
109
110
111
112
113
113
114
114
114
115
115
116
116
118
118
119
119
119
120
120
120
121
121
121
122
122
122
123
123
124
125
125
125
125
126
132
132
133
134
135
135
135
136
136
136
142
143
143
143
144
144
145
x

Table 162:
Table 163:
Table 164:
Table 165:
Table 166:
Table 167:
Table 168:
Table 169:
Table 170:
Table 171:
Table 172:
Table 173:
Table 174:

Queue Data Message Encoding Methods ..................................................................................................
QueueDataExpired Members......................................................................................................................
Queue Data Message Undeliverable Codes
...............................................................................................
Queue Ack Members
..................................................................................................................................
CacheError Class Members.....................................................................................................................
CacheError Utility Method........................................................................................................................
Methods for Managing Cache Instances.....................................................................................................
PayloadCacheConfigOptions Members ..............................................................................................
Methods for Setting Dictionary to Cache.....................................................................................................
PayloadCache Utility Methods..................................................................................................................
Payload Cache Entry Management Methods..............................................................................................
Methods for Applying and Retrieving Cache Entry Data .............................................................................
Methods for Using the Payload Cursor .......................................................................................................

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

145
147
148
148
150
150
151
151
152
154
155
157
158

Chapter 1

Introduction

Chapter 1 Introduction
1.1

About this Manual

This document is authored by Transport API architects and programmers who encountered and resolved many of the issues
the reader might face. Several of its authors have designed, developed, and maintained the Transport API product and other
Thomson Reuters products which leverage it. As such, this document is concise and addresses realistic scenarios and use
cases.
This guide documents the functionality and capabilities of the Transport API Java Edition. In addition to connecting to itself, the
Transport API can also connect to and leverage many different Thomson Reuters and customer components. If you want the
Transport API to interact with other components, consult that specific component’s documentation to determine the best way
to configure and interact with these other devices.

1.2

Audience

This manual provides information and examples that aid programmers using the Transport API Java Edition Value Added
Components. The level of material covered assumes that the reader is a user or a member of the programming staff involved
in the design, coding, and test phases for applications which will use the Transport API or its Value Added Components. It is
assumed that the reader is familiar with the data types, classes, operational characteristics, and user requirements of real-time
data delivery networks, and has experience developing products using the Java programming language in a networked
environment. Although Transport API Value Added Components offer alternate entry points to Transport API functionality, it is
recommended that users are familiar with general Transport API usage and interfaces.

1.3

Programming Language

The Transport API Value Added Components are written to both the C and Java languages. This guide discusses concepts
related to the Java Edition. All code samples in this document and all example applications provided with the product are
written accordingly.

1.4

Acronyms and Abbreviations

ACRONYM

MEANING

ADH

Advanced Data Hub is the horizontally scalable service component within Thomson Reuters Enterprise
Platform (TREP) providing high availability for publication and contribution messaging, subscription
management with optional persistence, conflation and delay capabilities.

ADS

Advanced Distribution Server is the horizontally scalable distribution component within Thomson
Reuters Enterprise Platform (TREP) providing highly available services for tailored streaming and
snapshot data, publication and contribution messaging with optional persistence, conflation and delay
capabilities.

API

Application Programming Interface

ASCII

American Standard Code for Information Interchange

Table 1: Acronyms and Abbreviations

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 1

ACRONYM

Introduction

MEANING

ATS

Advanced Transformation System

DACS

Data Access Control System

DMM

Domain Message Model

EED

Elektron Edge Device

EMA

Elektron Message API, referred to simply as the Message API

EOA

Elektron Object API, referred to simply as the Object API.

ETA

Elektron Transport API, referred to simply as the Transport API. Formerly referred to as UPA.

EWA

Elektron Web API

Garbage Collection

HTTP

Hypertext Transfer Protocol

HTTPS

Hypertext Transfer Protocol (Secure)

IDN

Integrated Data Network

NIP

Non-Interactive Provider

OMM

Open Message Model

QoS

Quality of Service

RDM

Reuters Domain Model

Reactor

The Reactor is a low-level, open-source, easy-to-use layer above ETA. It offers heartbeat
management, connection and item recovery, and many other features to help simplify application code
for users.

RFA

Robust Foundation API

RMTES

Reuters Multi-Lingual Text Encoding Standard

RSSL

Reuters Source Sink Library

RWF

Reuters Wire Format, a Thomson Reuters proprietary format.

SOA

Service Oriented Architecture

SSL

Source Sink Library

TREP

Thomson Reuters Enterprise Platform

UML

Unified Modeling Language

UTF-8

8-bit Unicode Transformation Format

Table 1: Acronyms and Abbreviations

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 1

1.5

Introduction

Additional References and Resources

1. Transport API Java Edition RDM Usage Guide
2. API Concepts Guide
3. Transport API Java Edition Developers Guide
4. The Thomson Reuters Professional Developer Community

1.6

Documentation Feedback

While we make every effort to ensure the documentation is accurate and up-to-date, if you notice any errors, or would like to
see more details on a particular topic, you have the following options:

•
•

Send us your comments via email at apidocumentation@thomsonreuters.com.
Add your comments to the PDF using Adobe’s Comment feature. After adding your comments, submit the entire PDF to
Thomson Reuters by clicking Send File in the File menu. Use the apidocumentation@thomsonreuters.com address.

1.7
•
•
•

Document Conventions

Typographic
Document Structure
Diagrams

1.7.1

Typographic

•

Java classes, methods, in-line code snippets, and types are shown in orange, Courier New font.

•

Parameters, filenames, tools, utilities, and directories are shown in Bold font.

•

Document titles and variable values are shown in italics.

•

When initially introduced, concepts are shown in Bold, Italics.

•

Longer code examples are shown in Courier New font against an orange background. For example:

/* decode contents into the filter list object */
if ((retVal = filterList.decode(decIter)) >= CodecReturnCodes.SUCCESS)
{
/* create single filter entry and reuse while decoding each entry */
FilterEntry filterEntry = CodecFactory.createFilterEntry();

1.7.2

Document Structure

•

General Concepts

•

Detailed Concepts

•

Interface Definitions

•

Example Code

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 1

1.7.3

Introduction

Diagrams

Diagrams that depict the interaction between components on a network use the following notation:

Figure 1. Network Diagram Notation

Figure 2. UML Diagram Notation

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 2

Product Description and Overview

Chapter 2 Product Description and Overview
2.1

What is the Transport API?

The Transport API is a low-level Transport API that provides the most flexible development environment to the application
developer. It is the foundation on which all Thomson Reuters OMM-based components are built. The Transport API allows
applications to achieve the highest throughput and lowest latency available with any OMM API, but requires applications to
perform all message encoding/decoding and manage all aspects of network connectivity. The Transport API, Elektron
Message API, and the Robust Foundation API (RFA) make up the set of OMM API offerings.

Figure 3. OMM APIs with Value Added Components
The Transport API Value Added Components provide alternate entry points for applications to leverage OMM-Based APIs with
more ease and simplicity. These optional components help to offload much of the connection management code and perform
encoding and decoding of some key OMM domain representations. Unlike older domain-based APIs that lock the user into
capabilities or ease-of-use into the highest layer of API, Value Added components are independently implemented for use with
the Transport API and RFA in their native languages (Example: Transport API in C and Java, RFA in C++ and Java). These
implementations are then shipped with their respective API products as options for the application developer that may want
these additional capabilities.

2.2

What are Transport API Value Added Components?

The Value Added Components simplify and compliment the use of the Transport API. These components (depicted in green in
Figure 4) are offered along side the Transport API to maximize the user experience and allow for more intuitive, straight
forward, and rapid creation of Transport API applications. Applications can write directly to the Transport API interfaces or
commingle some or all Value Added Components. The choice to leverage these components is up to the application
developer; you do not need to use Value Added Components to use the Transport API. Using Transport API Value Added
Components, you can choose and customize the balance between ultra high-performance raw access and ease-of-use
feature functionality. Value Added Components are written to the Transport API interfaces and are designed to work alongside
the Transport API. Their interfaces have a similar look and feel to Transport API interfaces to provide simple migration and
consistent use between all components and the Transport API.
All value added components provide fully supported library files ready to build into new or existing Transport API applications.
Examples and documentation are provided to show the full power and capability of the component.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 2

Product Description and Overview

Some value added components provide buildable source code1 to allow for customization and modification to suit specific user
needs. This source code serves the following purposes:

•

Clients may want to provide their own implementation of the component. Rather than starting from scratch, clients can
modify the component to jump start their development efforts.
Note: If a client customizes a component’s code, the client is responsible for its support and maintenance.

•

Clients might want to build a new component that has similar behaviors to an existing component. Clients can leverage the
code of one component to jump start their development efforts.

•

Clients may want to collaborate in troubleshooting or suggesting improvements to the component for everyone’s benefit.

Figure 4. Transport API Value Added Components

2.3

Transport API Reactor

The Transport API reactor is a connection management and event processing component that can significantly reduce the
amount of code an application must write to leverage OMM in its own functions and to connect to other OMM-based devices.
Consumer, interactive provider, and non-interactive provider applications can use the reactor and leverage it in managing
consumer and non-interactive provider start-up processes, including user log in, source directory establishment, and dictionary
download. The reactor also supports dispatching of events to user-implemented callback functions. In addition, it handles the
flushing of user-written content and manages network pings on the user’s behalf. The connection recovery feature allows the
reactor to automatically recover from disconnects. Value Added domain representations are coupled with the reactor, allowing
domain specific callbacks to be presented with their respective domain representation for easier, more logical access to
content. For more information, refer to Chapter 6, Reactor Detailed View. This component depends on the Value Added
Administration Domain Model Representation component, the Value Added Utilities, Transport API Java Transport Package,
and Transport API Java Codec Package.

1. Thomson Reuters fully supports the use of its pre-built library files. Provided source code can help with user troubleshooting and debugging. However, the user, not Thomson Reuters, is responsible for supporting any modifications to the provided source.
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 2

2.4

Product Description and Overview

OMM Consumer Watchlist

The Reactor features a per-channel watchlist that provides a wealth of functionality for OMM Consumer applications. The
watchlist automatically performs various recovery behaviors for which developers would normally need to account.The
watchlist supports consuming from TCP-based connections (ConnectionTypes.SOCKET).
For details on configuring the Reactor to enable the consumer watchlist, refer to Section 6.3.2.

2.4.1

Data Stream Aggregation and Recovery

The watchlist automatically recovers data streams in response to failure conditions, such as disconnects and unavailable
services, so that applications do not need special handling for these conditions. As conditions are resolved, the watchlist will
re-request items on the application’s behalf. Applications can also use this method to request data before a connection is fully
established.
To recover from disconnects using a watchlist, enable the reactor’s connection recovery. Options to reconnect disconnected
channels are detailed in Section 6.4.1.2.
For efficient bandwidth usage, the watchlist also combines multiple requests for the same item into a single stream and
forwards response messages to each requested stream as appropriate.

2.4.2

Additional Features

The watchlist provides additional features for convenience:
•

Group and Service Status Fanout: The Reactor maintains a directory stream to receive service updates. As group
status messages or service status messages are received, the Reactor forwards the status to all affected streams via
StatusMsgs.

•

QoS Range Matching: The Reactor will accept and aggregate item requests that specify a range of Qos, or requests
that do not specify a Qos. After comparing these requests with the QoS from the providing service, the watchlist uses
the best matching QoS.

•

Support for Enhanced Symbol List Behaviors: The Reactor supports data streams when requesting a Symbol List
item. For details on requesting Symbol list data streams, refer to the Transport API Java Edition RDM Usage Guide.

•

Support for Batch Requests: The Reactor will accept batch requests regardless of whether the connected provider
supports them.

2.4.3

Usage Notes

Applications should note the following when enabling the watchlist:
•

The application must use the ReactorChannel.submit(Msg) and ReactorChannel.submit(MsgBase) methods to
send messages. It cannot use ReactorChannel.submit(TransportBuffer).

•

Only one login stream should be opened per ReactorChannel.

•

To prevent unnecessary bandwidth use, the watchlist will not recover a dictionary request after a complete refresh is
received.

•

As private streams are intended for content delivery between two specific points, the watchlist does not aggregate nor
recover them.

•

The ConsumerRole.dictionaryDownloadMode option is not supported when the watchlist is enabled.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 2

2.5

Product Description and Overview

Administration Domain Model Representations

The Administration Domain Model Representations are RDM-specific representations of the OMM administrative domain
models. This Value Added Component contains classes and interfaces that represent the messages within the Login, Source
Directory, and Dictionary domains. All classes follow the formatting and naming specified in the Transport API Java Edition
RDM Usage Guide, so access to content is logical and specific to the content being represented. This component also handles
all encoding and decoding functionality for these domain models, so the application needs only to manipulate the message’s
class members to send or receive this content. This not only significantly reduces the amount of code an application needs to
interact with OMM devices (i.e., TREP infrastructure), but also ensures that encoding/decoding for these domain models follow
OMM-specified formatting rules. Applications can use this Value Added Component directly to help with encoding, decoding,
and representation of these domain models. When using the Transport API Reactor, this component is embedded to manage
and present callbacks with a domain-specific representation of content. For more information, refer to Chapter 7,
Administration Domain Models Detailed View. This component depends on the Transport API Java Codec Package.

2.6

Value Added Utilities

The Value Added Utilities are a collection of common classes, mainly used by the Transport API Reactor. Included is a
selectable bidirectional queue used to communicate events between the Reactor and Worker threads. Other Value Added
Utilities include a simple queue along with iterable and concurrent versions of it.

2.7

Payload Cache

Applications can leverage the OMM payload cache feature. Using the payload cache, an application can maintain a local store
of the OMM container data it consumes, publishes, or transforms. The cache maintains the latest values of the OMM data
entries: container values update to reflect the most recent refresh and update message payloads whenever the application
receives them. The Transport API retrieves data from the cache entry in the form of an encoded OMM container. The payload
cache is independent of other Value Added components, and only requires the Transport API Java Codec Package. Only
library files are available for the cache component.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 3

Building an OMM Consumer

Chapter 3 Building an OMM Consumer
3.1

Overview

This chapter provides an overview of how to create an OMM Consumer application using the Transport API Reactor and
Administration Domain Model Representation Value Added Components. The Value Added Components simplify the work
done by an OMM consumer application when establishing a connection to other OMM interactive provider applications,
including the Enterprise Platform, Data Feed Direct, and Elektron. After the Reactor indicates that the connection is ready, an
OMM Consumer can then consume (i.e., send data requests and receive responses) and publish data (i.e., post data).
The general process can be summarized by the following steps.

•
•
•
•
•

Leverage existing or create new Reactor
Implement callbacks and populate role
Establish connection using Reactor.connect
Issue requests and/or post information
Log out and shut down

The Consumer example application, included with the Transport API product, provides one implementation of an OMM
consumer application that uses the Transport API Value Added Components. The application is written with simplicity in mind
and demonstrates usage of the Transport API and Transport API Value Added Components. Portions of functionality have
been abstracted and can easily be reused, though you might need to modify it to achieve your own unique performance and
functionality goals.

3.2

Leverage Existing or Create New Reactor

The Reactor can manage one or multiple ReactorChannel objects. This functionality allows the application to associate OMM
Consumer connections with an existing Reactor, having it manage more than one connection, or to create a new Reactor to
use with the connection.
To create a new Reactor, the application must use the ReactorFactory.createReactor method. This will create any
necessary memory and threads that the Reactor uses to manage ReactorChannels and their content flow. If the application is
using an existing Reactor, there is nothing additional to do.
Detailed information about the Reactor and its creation are available in Section 6.2.1.

3.3

Implement Callbacks and Populate Role

Before creating the OMM consumer connection, the application needs to specify callback methods to use for all inbound
content. The callback methods are specified on a per ReactorChannel basis so each channel can have its own unique
callback methods or existing callback methods can be specified and shared across multiple ReactorChannels.
Use of a Reactor requires the use of several callback methods. The application must have the following:

•
•

ReactorChannelEventCallback, which returns information about the ReactorChannel and its state (e.g., connection up)
DefaultMsgCallback, which processes all data not handled by other optional callbacks.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 3

Building an OMM Consumer

In addition to the required callbacks, an OMM Consumer can specify several administrative domain-specific callback methods.
Available domain-specific callbacks include:

•
•
•

RDMLoginMsgCallback, which processes all data for the RDM Login domain.
RDMDirectoryMsgCallback, which processes all data for the RDM Source Directory domain.
RDMDictionaryMsgCallback, which processes all data for the RDM Dictionary domain.

The ConsumerRole object should be populated with all callback information for the ReactorChannel.
The ConsumerRole allows the application to provide login, directory, and dictionary request information. This can be initialized
with default information. The callback methods are specified on the ConsumerRole object or with specific information
according to the application and user. The Reactor will use this information when starting up the ReactorChannel.
Detailed information about the ConsumerRole is in Section 6.3.1. Information about the various callback functions and their
specifications are available in Section 6.5.2.

3.4

Establish Connection using Reactor.connect

After populating the ConsumerRole, the application can use Reactor.connect to create a new outbound connection.
Reactor.connect will create an OMM consumer type connection using the provided configuration and role information.
After establishing the underlying connection, a channel event is returned to the application’s ReactorChannelEventCallback;
this provides the ReactorChannel and the state of the current connection. At this point, the application can begin using the
ReactorChannel.dispatch method to dispatch directly on this ReactorChannel, or use Reactor.dispatchAll to dispatch
across all channels associated with the Reactor.
The Reactor will use the login, directory, and dictionary information specified on the ConsumerRole to perform all channel
initialization for the user. After a user has logged in, received a source directory response, and downloaded field dictionaries, a
channel event is returned to inform the application that the connection is ready.
The Reactor.connect method is described in Section 6.4.1.1. Dispatching is described in Section 6.5.

3.5

Issue Requests and/or Post Information

After the ReactorChannel is established, the channel can be used to request additional content. When issuing the request,
the consuming application can use the serviceId of the desired service, along with the stream’s identifying information.
Requests can be sent for any domain using the formats defined in that domain model specification. Domains provided by
Thomson Reuters are defined in the Transport API Java Edition RDM Usage Guide. This content will be returned to the
application via the DefaultMsgCallback.
At this point, an OMM consumer application can also post information to capable provider applications. All content requested,
received, or posted is encoded and decoded using the Transport API Codec Package described in the Transport API Java
Edition Developers Guide.

3.6

Log Out and Shut Down

When the consumer application is done retrieving or posting content, the consumer can close the ReactorChannel by calling
ReactorChannel.close. This will close all item streams and log out the user. Prior to closing the ReactorChannel, the
application should release any unwritten pool buffers to ensure proper memory cleanup.
If the application is done with the Reactor, the Reactor.shutdown method can be used to shutdown and clean up any
Reactor resources.

•

Closing a ReactorChannel is described in Section 6.4.2.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 3

•

3.7

Building an OMM Consumer

Shutting down an Reactor is described in Section 6.2.2.

Additional Consumer Details

The following locations provide specific details about using OMM consumers, the Transport API, and Transport API Value
Added Components:

•

The Consumer application demonstrates one way of implementing of an OMM consumer application that uses Transport
API Value Added Components. The application’s source code and Javadoc contain additional information about specific
implementation and behaviors.

•
•
•

Chapter 6 provides a detailed look at the Transport API Reactor.

•

The Transport API Java Edition RDM Usage Guide provides specific information about the DMMs used by this application
type.

Chapter 7 provides more information about the Administration Domain Model Representations.
The Transport API Java Edition Developers Guide provides specific Transport API encoder/decoder and transport usage
information.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 4

Building an OMM Interactive Provider

Chapter 4 Building an OMM Interactive Provider
4.1

Overview

This chapter provides a high-level description of how to create an OMM interactive provider application using the Transport
API Reactor and Administration Domain Model Representation Value Added Components. An OMM interactive provider
application opens a listening socket on a well-known port allowing OMM Consumer applications to connect. The Transport API
Value Added Components simplify the work done by an OMM interactive provider application when accepting connections and
handling requests from OMM consumers.
The following steps summarize this process:

•
•
•
•
•
•
•
•
•

Leverage an existing Reactor, or create a new one
Create a Server
Implement callbacks and populate role
Associate incoming connections using Reactor.accept
Perform login process
Provide source directory information
Provide necessary dictionaries
Handle requests and post messages
Disconnect consumers and shut down

Included with the Transport API product, the Provider example application provides one way of implementing an OMM
interactive provider application that uses the Transport API Value Added Components. The application is written with simplicity
in mind and demonstrates the use of the Transport API and Transport API Value Added Components. Portions of the
functionality are abstracted for easy reuse, though you might need to customize it to achieve your own unique performance
and functionality goals.

4.2

Leverage Existing or Create New Reactor

The Reactor can manage one or multiple ReactorChannel objects. This allows the application to choose to associate OMM
provider connections with an existing Reactor, have it manage more than one connection, or create a new Reactor to use
with the connection.
If the application is creating a new Reactor, the ReactorFactory.createReactor method is used. This will create any
necessary memory and threads that the Reactor uses to manage ReactorChannels and their content flow. If the application is
using an existing Reactor, there is nothing additional to do.
Detailed information about the Reactor and its creation are available in Section 6.2.1.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 4

4.3

Building an OMM Interactive Provider

Create a Server

The first step of any Transport API Interactive Provider application is to establish a listening socket, usually on a well-known
port so that consumer applications can easily connect. The provider uses the Transport.bind method to open the port and
listen for incoming connection attempts. This uses the standard Transport API Transport functionality described in the
Transport API Java Edition Developers Guide.
Whenever an OMM consumer application attempts to connect, the provider will use the Server and associate the incoming
connections with a Reactor, which will accept the connection and perform any initialization as described in Section 4.4 and
Section 4.5.

4.4

Implement Callbacks and Populate Role

Before accepting an incoming connection with an OMM provider, the application needs to specify callback methods to use for
all inbound content. Callback methods are specified on a per ReactorChannel basis so each channel can have its own unique
callback methods or existing callback methods can be specified and shared across multiple ReactorChannels.
The following callback methods are required for use with a Reactor:

•
•

In addition to the required callbacks, an OMM provider can specify several administrative domain-specific callback methods.
Available domain-specific callbacks are:

•
•
•

The ProviderRole object should be populated with all callback information for the ReactorChannel.
Detailed information about the ProviderRole is in Section 6.3.1. Information about the various callback methods and their
specifications are available in Section 6.5.2.

4.5

Associate Incoming Connections Using Reactor.accept

After the ProviderRole is populated, the application can use Reactor.accept to accept a new inbound connection.
Reactor.accept will accept an OMM provider connection from the passed-in Server using provided configuration and role
information.
When the underlying connection is established, a channel event is returned to the application’s
ReactorChannelEventCallback; this will provide the ReactorChannel and indicate the current connection state. At this point,
the application can begin using the ReactorChannel.dispatch method to dispatch directly on this ReactorChannel, or
continue using Reactor.dispatchAll to dispatch across all channels associated with the Reactor.
The Reactor will perform all channel initialization and pass any administrative domain information to the application via the
callbacks specified with the ProviderRole.

•
•

For more details on the Reactor.accept method, refer to Section 6.4.1.6.
For more details on dispatching, refer to Section 6.5.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 4

4.6

Building an OMM Interactive Provider

Perform Login Process

Applications authenticate with one another using the Login domain model. An OMM interactive provider must handle
consumer Login request messages and supply appropriate responses. Login information will be provided to the application via
the RDMLoginMsgCallback, when specified on the ProviderRole.
After receiving a Login request, an interactive provider can perform any necessary authentication and permissioning.

•

If the interactive provider grants access, it should send an LoginRefresh to convey that the user successfully connected.
This message should indicate the feature set supported by the provider application.

•

If the interactive provider denies access, it should send an LoginStatus, closing the connection and informing the user of
the reason for denial.

Login messages can be encoded and decoded using the messages’ encode and decode methods. More details and code
examples are in Section 7.3.
All content requested, received, or posted is encoded and decoded using the Transport API Java Codec Package described in
the Transport API Java Edition Developers Guide.
Information about the Login domain and expected content formatting is available in the Transport API Java Edition RDM
Usage Guide.

4.7

Provide Source Directory Information

The Source Directory domain model conveys information about all available services in the system. An OMM consumer
typically requests a Source Directory to retrieve information about available services and their capabilities. This includes
information about supported domain types, the service’s state, the QoS, and any item group information associated with the
service. Thomson Reuters recommends that at a minimum, an interactive provider supply the Info, State, and Group filters for
the Source Directory.

•

The Source Directory Info filter contains the name and serviceId for each available service. The interactive provider
should populate the filter with information specific to the services it provides.

•

The Source Directory State filter contains status information for the service informing the consumer whether the service is
Up (available), or Down (unavailable).

•

The Source Directory Group filter conveys item group status information, including information about group states, as well
as the merging of groups. If a provider determines that a group of items is no longer available, it can convey this
information by sending either individual item status messages (for each affected stream) or a Directory message
containing the item group status information. Additional information about item groups is available in the Transport API
Java Edition Developers Guide.

Source Directory messages can be encoded and decoded using the messages’ encode and decode methods. More details
and code examples are in Section 7.4.
All content requested, received, or posted is encoded and decoded using the Transport API Java Codec Package described in
the Transport API Java Edition Developers Guide.
Information about the Source Directory domain and expected content formatting is available in the Transport API Java Edition
RDM Usage Guide.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 4

4.8

Building an OMM Interactive Provider

Provide or Download Necessary Dictionaries

Some data requires the use of a dictionary for encoding or decoding. The dictionary typically defines type and formatting
information, and tells the application how to encode or decode information. Content that uses the FieldList type requires the
use of a field dictionary (usually the Thomson Reuters RDMFieldDictionary, though it can instead be a user-defined or
modified field dictionary).
The Source Directory message should notify the consumer about dictionaries needed to decode content sent by the provider.
If the consumer needs a dictionary to decode content, it is ideal that the interactive provider application also make this
dictionary available to consumers for download. The provider can inform the consumer whether the dictionary is available via
the Source Directory.
If consuming from an ADH and providing content downstream, a provider application can also download the RWFFld and
RWFEnum dictionaries. Using these dictionaries, the Transport API can retrieve appropriate dictionary information for
providing field list content. A provider can use this feature to ensure they are using the appropriate version of the dictionary or
to encode data. An ADH that supports provider dictionary downloads sends a Login request message containing the
SupportProviderDictionaryDownload login element. The Transport API sends the dictionary request using the Dictionary
domain model. For details on using the Login domain and expected message content, refer to the Transport API Java Edition
RDM Usage Guide.
Dictionary messages can be encoded and decoded using the messages’ encode and decode methods. More details and code
examples are in Section 7.5. Dictionary requests will be provided via the RDMDictionaryMsgCallback, when specified on the
ProviderRole.
Whether loading a dictionary from file or requesting it from an ADH, the Transport API offers several utility functions for
loading, downloading, and managing a properly-formatted field dictionary. The Transport API also has utility functions that help
the provider encode into an appropriate format for downloading or decoding downloaded dictionaries.

•

All content requested, received, or posted is encoded and decoded using the Transport API Java Codec Package
described in the Transport API Java Edition Developers Guide.

•

Information about the Dictionary domain, dictionary utility functions, and expected content formatting is available in the
Transport API Java Edition RDM Usage Guide.

4.9

Handle Requests and Post Messages

A provider can receive a request for any domain, though this should typically be limited to the domain capabilities indicated in
the Source Directory. When a request is received, the provider application must determine if it can satisfy the request by:

•
•
•

Comparing msgKey identification information
Determining whether it can provide the requested QoS
Ensuring that the consumer does not already have a stream open for the requested information

If a provider can service a request, it should send appropriate responses. However, if the provider cannot satisfy the request,
the provider should send an StatusMsg to indicate the reason and close the stream. All requests and responses should follow
specific formatting as defined in the domain model specification. The Transport API Java Edition RDM Usage Guide defines all
domains provided by Thomson Reuters. This content will be returned to the application via the DefaultMsgCallback.
The provider can specify that it supports post messages via the LoginRefresh. If a provider application receives a post
message, the provider should determine the correct handling for the post. This depends on the application’s role in the system
and might involve storing the post in its cache or passing it farther up into the system. If the provider is the destination for the
post, the provider should send any requested acknowledgments, following the guidelines described in the Transport API Java
Edition Developers Guide. Any posted content will be returned to the application via the DefaultMsgCallback.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 4

Building an OMM Interactive Provider

All content requested, received, or posted is encoded and decoded using the Transport API Java Codec Package described in
the Transport API Java Edition Developers Guide.

4.10

Disconnect Consumers and Shut Down

If the Reactor application must shut down, it can either leave consumer connections intact or shut them down. If the provider
decides to close consumer connections, the provider should send an StatusMsg on each connection’s Login stream closing
the stream. At this point, the consumer should assume that its other open streams are also closed.
It can then close the ReactorChannels by calling ReactorChannel.close. Prior to closing the ReactorChannel, the
application should release any unwritten pool buffers to ensure proper memory cleanup.
If the application is done with the Reactor, the Reactor.shutdown method can be used to shutdown and cleanup any
Reactor resources.

•
•

Closing a ReactorChannel is described in Section 6.4.2.
Shutting down a Reactor is described in Section 6.2.2.

4.11

Additional Interactive Provider Details

For specific details about OMM interactive providers, the Transport API, and Transport API Value Added Component use, refer
to the following locations:

•

The Provider application demonstrates one implementation of an OMM interactive provider application that uses
Transport API Value Added Components. The application’s source code and Javadoc have additional information about
specific implementation and behaviors.

•
•
•

Chapter 6 provides a detailed look at the Transport API Reactor.

•

The Transport API Java Edition RDM Usage Guide provides specific information about the DMMs used by this application
type.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 5

Building an OMM Non-Interactive Provider

Chapter 5 Building an OMM Non-Interactive Provider
5.1

Building an OMM Non-Interactive Provider Overview

This chapter provides an overview of how to create an OMM non-interactive provider application using the Transport API
Reactor and Administration Domain Model Representation Value Added Components. The Value Added Components simplify
the work done by an OMM non-interactive provider application when establishing a connection to ADH devices. After the
reactor indicates that the connection is ready, an OMM non-interactive provider can publish information into the ADH cache
without needing to handle requests for the information. The ADH and other Enterprise Platform components can cache the
information and provide it to any OMM consumer applications that indicate interest.
The general process can be summarized by the following steps.

•
•
•
•
•
•

Leverage existing or create new Reactor
Implement callbacks and populate role
Establish connection using Reactor.connect
Perform dictionary download
Provide content
Log out and shut down

The NIProvider example application, included with the Transport API product, provides one implementation of an OMM noninteractive provider application that uses the Transport API Value Added Components. The application is written with simplicity
in mind and demonstrates usage of the Transport API and Transport API Value Added Components. Portions of functionality
have been abstracted and can easily be reused, though you might need to modify it to achieve your own unique performance
and functionality goals.

5.2

Leverage Existing or Create New Reactor

The Reactor can manage one or multiple ReactorChannel objects. This allows the application to choose to associate OMM
non-interactive provider connections with an existing Reactor, having it manage more than one connection, or to create a new
Reactor to use with the connection.
If the application is creating a new Reactor, the ReactorFactory.createReactor method is used. This will create any
necessary memory and threads that the Reactor uses to manage ReactorChannel and their content flow. If the application is
using an existing Reactor, there is nothing more to do.
Detailed information about the Reactor and its creation are available in Section 6.2.1.

5.3

Implement Callbacks and Populate Role

Before creating the OMM non-interactive provider connection, the application needs to specify callback methods to use for all
inbound content. Callback methods are specified on a per ReactorChannel basis so each channel can have its own unique
callback methods or existing callback methods can be specified and shared across multiple ReactorChannels.
A Reactor requires the use of the following callback methods:

•
•

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 5

Building an OMM Non-Interactive Provider

Additionally, an OMM non-interactive provider can specify the administrative domain-specific callback method
RDMLoginMsgCallback, which processes all data for the RDM Login domain.
The NIProviderRole object should be populated with all callback information for the ReactorChannel. NIProviderRole
allows the application to provide login request and initial directory refresh information. This can be initialized with default
information. Callback methods are specified on the NIProviderRole object or with specific information according to the
application and user. The Reactor will use this information when starting up the ReactorChannel.

•
•

For detailed information on the NIProviderRole, refer to Section 6.3.1.
For information on the various callback methods and their specifications, refer to Section 6.5.2.

5.4

Establish Connection using Reactor.connect

After populating the NIProviderRole, the application can use Reactor.connect to create a new outbound connection.
Reactor.connect will create an OMM non-interactive provider type connection using the provided configuration and role
information.
When the underlying connection is established, a channel event will be returned to the application’s
ReactorChannelEventCallback, which provides the ReactorChannel and indicates the current connection state. At this
point, the application can begin using the ReactorChannel.dispatch method to dispatch directly on this ReactorChannel, or
use Reactor.dispatchAll to dispatch across all channels associated with the Reactor.
The Reactor will use the login and directory information specified on the NIProviderRole to perform all channel initialization
for the user. After the user is logged in and has sent a source directory response, a channel event is returned to inform the
application that the connection is ready.

•
•

For further details on the Reactor.connect method, refer to Section 6.4.1.1.
For further details on dispatching, refer to Section 6.5.

5.5

Download the Dictionary

If connected to a supporting ADH, an OMM non-interactive provider can download the RWFFld and RWFEnum dictionaries to
retrieve the appropriate dictionary information for providing field list content. An OMM non-interactive provider can use this
feature to ensure they use the appropriate version of the dictionary or to encode data. To support the Provider Dictionary
Download feature, the ADH sends a Login response message containing the SupportProviderDictionaryDownload login
element. The dictionary request is sent using the Dictionary domain model.
The Transport API offers several utility functions for downloading and managing a properly-formatted field dictionary. The
provider can also use utility functions to encode the dictionary into an appropriate format for downloading or decoding.
For details on using the Login domain, expected message content, and available dictionary utility functions, refer to the
Transport API Java Edition RDM Usage Guide.

5.6

Provide Content

After the ReactorChannel is established, it can begin pushing content to the ADH. Each unique information stream should
begin with an RefreshMsg, conveying all necessary identification information for the content. Because the provider instantiates
this information, a negative value streamId should be used for all streams. The initial identifying refresh can be followed by
other status or update messages.
All content is encoded and decoded using the Transport API Java Codec Package described in the Transport API Java Edition
Developers Guide.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 5

5.7

Building an OMM Non-Interactive Provider

Log Out and Shut Down

When the Consumer application is done retrieving or posting content, it can close the ReactorChannel by calling
ReactorChannel.close. This will close all item streams and log out the user. Prior to closing the ReactorChannel, the
application should release any unwritten pool buffers to ensure proper memory cleanup.
If the application is done with the Reactor, the Reactor.shutdown method can be used to shutdown and cleanup any
Reactor resources.

•
•

For details on closing a ReactorChannel, refer to Section 6.4.2.
Shutting down a Reactor is described in Section 6.2.2.

5.8

Additional Non-Interactive Provider Details

The following locations discuss specific details about using OMM non-interactive providers and the Transport API:

•

The NIProvider application demonstrates one implementation of an OMM non-interactive provider application that uses
Transport API Value Added Components. The application’s source code and Javadoc have additional information about
the specific implementation and behaviors.

•
•
•

Chapter 6 provides a detailed look at the Transport API Reactor.

•

The Transport API Java Edition RDM Usage Guide provides specific information about the DMMs used by this application
type.

Chapter 7 provides more information about Administration Domain Model Representations.
The Transport API Java Edition Developers Guide provides specific Transport API encoder/decoder and transport usage
information.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

Reactor Detailed View

Chapter 6 Reactor Detailed View
6.1

Concepts

The Transport API Reactor is a connection management and event processing component that can significantly reduce the
amount of code an application must write to leverage OMM. This component helps simplify many aspects of a typical
Transport API application, regardless of whether the application is an OMM consumer, OMM interactive provider, or OMM noninteractive provider. The Transport API Reactor can help manage Consumer and Non-Interactive Provider start up processing,
including user log in, source directory establishment, and dictionary download. It also allows for dispatching of events to userimplemented callback functions, handles flushing of user-written content, and manages network pings on the user’s behalf.
Value Added domain representations are coupled with the reactor, allowing domain-specific callbacks to be presented with
their respective domain representation for easier, more logical access to content. For a list and comparison of Transport API
and Transport API Reactor functionalities, refer to Section 6.1.1.
The Transport API Reactor internally depends on the Administration Domain Model Representation component. This allows
the user to provide and consume the administrative RDM types in a more logical format. This additionally hides encoding and
decoding of these domains from the Reactor user, all interaction is via a simple structural representation. More information
about the Administration Domain Model Representation value added component is available in Chapter 7. The Transport API
Reactor also leverages several utility components, contained in the Value Added Utilities. This includes an iterable queue and
a selectable bidirectional queue used to communicate events between the Reactor and Worker threads.
The Transport API Reactor helps to manage the life-cycle of a connection on the user’s behalf. When a channel is associated
with a reactor, the reactor performs all necessary transport level initialization and alerts the user, via a callback, when the
connection is up, ready for use, or is down. An application can simultaneously run multiple unique reactor instances, where
each reactor instance can associate and manage a single channel or multiple channels. This functionality allows users to
quickly and easily horizontally scale their application to leverage multi-core systems or distribute content across multiple
connections.
Each instance of the Transport API Reactor leverages multiple threads to help manage inbound and outbound data efficiently.
The following figure illustrates a high-level view of the reactor threading model.

Figure 5. Transport API Reactor Thread Model
There are two main threads associated with each Transport API Reactor instance. The application thread is the main driver of
the reactor; all event dispatching (e.g., reading), callback processing, and submitting of data to the Transport API is done from
this thread. Such architecture reduces latency and simplifies any threading model associated with user-defined callback
methods – because callbacks happen from the application thread, a single-threaded application does not need to have
additional mutex locking. The Transport API Reactor also leverages an internal worker thread. The worker thread flushes any

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

Reactor Detailed View

queued outbound data and manages outbound network pings for all channels associated with the Reactor. It also attempts to
recover any connections that are lost.
The application drives the reactor with the use of a dispatch method. The dispatch method reads content from the network,
performs some light processing to handle inbound network pings, and provides the information to the user through a series of
per-channel, user-defined callback methods. Callback methods are separated based on whether they are reactor callbacks or
channel callbacks. Channel callbacks are separated by domain, with a default callback where all unhandled domains or nonOMM content are provided to the user. The application can choose whether to dispatch on a single channel or across all
channels managed by the reactor. The application can leverage an I/O notification mechanism (e.g. select, poll) or periodically
call dispatch – it is all up to the user.

6.1.1

Functionality: Transport API Versus Transport API Reactor

FUNCTIONALITY

TRANSPORT API

TRANSPORT API REACTOR

Programmatic Configuration

Programmatic Logging

Controlled Fragmentation and Assembly of Large Messages

Controlled Locking / Threading Model

Controlled Message Buffers with Ability to Change During
Runtime

Controlled Message Packing

Support for Unified and Segmented Network Connection Types

Network Ping Management

***

Automatic Flushing of Data

***

User-Defined Callbacks for Data

***

User Login

***

Requesting Source Directory

***

Downloading Field Dictionary

***

Loading Field Dictionary File

***

***: Transport API users can implement this functionality themselves. They can also use or modify the Transport API Reactor
functionality.
Table 2: Transport API Functionality and Transport API Reactor Comparison

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.1.2

Reactor Detailed View

Reactor Error Handling

The ReactorErrorInfo object is used to return error or warning information to the application. This can be returned from the
various reactor methods as well as part of a callback method.

•
•

If returned directly from a reactor method: an error occurred while processing in that method.
If returned as part of a callback method: an error has occurred on one of the channels managed by the reactor.

ReactorErrorInfo members are as follows:

CLASS MEMBER

DESCRIPTION

code

An informational code about this error. Indicates whether it reports a failure condition or is
intended to provide non-failure-related information to the user. For details on available codes,
refer to Table 8.

error

Returns an Error object (i.e., the underlying error information from the Transport API). Error
includes a pointer to the Channel on which the error occurred, both a Transport API and a
system error number, and more descriptive error text. The Error and its values are described in
the Transport API Java Edition Developers Guide.

location

Provides information about the file and line on which the error occurred. Detailed error text is
provided via the Error portion of this object.

Table 3: ReactorErrorInfo Members

6.1.3

Reactor Error Info Codes

It is important that the application monitors return values from the Reactor callbacks and methods. Error codes indicate
whether the returned ReactorErrorInfo is the result of a failure condition or is simply providing information regarding a
successful operation.
RETURN CODE

DESCRIPTION

SUCCESS

Indicates a success code. Used to inform the user of success and provide additional
information.

FAILURE

A general failure has occurred. The ReactorErrorInfo code contains more information
about the specific error.

WRITE_CALL_AGAIN

This is a transport success code. ReactorChannel.submit is fragmenting the buffer and
needs to be called again with the same buffer. In this case, Write was unable to send all
fragments with the current call and must continue fragmenting content.

NO_BUFFERS

There are no buffers available from the buffer pool. Returned from
ReactorChannel.submit. Use ReactorChannel.ioctl to increase the pool size or wait
for the reactor's worker thread to flush data and return buffers to pool. Use
ReactorChannel.bufferUsage to monitor for free buffers.

PARAMETER_OUT_OF_RANGE Indicates that a parameter was out of range.
PARAMETER_INVALID

Indicates that a parameter was invalid.

Table 4: Reactor Error Info Codes

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.1.4

Reactor Detailed View

Transport API Reactor Application Lifecycle

The following figure depicts the typical lifecycle of an application using the Transport API Reactor, as well as associated
method calls. Subsequent sections in this document provide more detailed information.

Figure 6. Transport API Reactor Application Lifecycle

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.2

Reactor Detailed View

Reactor Use

This section describes use of Reactor. The Reactor manages ReactorChannels (described in Section 6.3). An
understanding of both constructs is necessary for application writers. Reactor uses the class members described in Table 5.

Note: An application can leverage multiple Reactor instances to scale across multiple cores and distribute their
ReactorChannels as needed.

CLASS MEMBER

DESCRIPTION

reactorChannel

The reactor's internal channel used for Reactor specific events to communicate with the
worker thread. The application must register this ReactorChannel’s selectable channel with its
selector if using select notification. All ReactorChannel data event notification occurs on the
ReactorChannel‘s specific selectableChannel, as detailed in Section 6.3.

userSpecObj

A pointer that can be set by the user of the Reactor. This value can be set directly or via the
creation options. This information can be useful for identifying a specific instance of an
Reactor or coupling this Reactor with other user-defined information.

Table 5: Class Members

6.2.1

Creating a Reactor

The lifecycle of a Reactor is controlled by the application, which controls creation and destruction of each reactor instance.
The following sections describe creation functionality in more detail.

6.2.1.1

Reactor Creation

The creation of a Reactor instance can be accomplished through the use of the following method.
FUNCTION NAME
ReactorFactory.createReactor

DESCRIPTION
Creates a Reactor instance, including all necessary internal memory and threads. After
creating the Reactor, ReactorChannels can be associated, as described in Section 6.3.
Options are passed in via the ReactorOptions, as defined in Section 6.2.1.2.

Table 6: Reactor Creation Method

6.2.1.2

ReactorOptions Class Members

CLASS MEMBER

DESCRIPTION

userSpecObj

An object that can be set by the application. This value is preserved and stored in the
userSpecObj of the Reactor returned from ReactorFactory.createReactor. This
information can be useful for identifying a specific instance of a reactor or coupling this
Reactor with other user-created information.

enableXmlTracing

Enables XML tracing for the Reactor. The Reactor prints the XML representation of all
OMM messages when enabled.

Table 7: ReactorOptions Class Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.2.1.3

Reactor Detailed View

ReactorOptions Utility Method

The Transport API provides the following utility method for use with the ReactorOptions.
METHOD NAME

DESCRIPTION

clear

Clears the ReactorOptions class. Useful for object reuse.

Table 8: ReactorOptions Utility Method

6.2.2

Destroying a Reactor

The lifecycle of a Reactor is controlled by the application, which controls creation and destruction of each reactor instance.
The following sections describe destruction functionality in more detail.

6.2.2.1

Reactor Destruction

When the application no longer requires a Reactor instance, it can destroy it using the following method.
METHOD NAME
shutdown

DESCRIPTION
Shuts down and cleans up a Reactor. This also sends ReactorChannelEvents, indicating
channel down, to all ReactorChannels associated with this Reactor.

Table 9: Reactor Destruction Method

6.2.2.2

Reactor Creation and Destruction Example

ReactorOptions reactorCreateOptions = ReactorFactory.createReactorOptions();
reactorCreateOptions.clear();
/* Create the Reactor. */
reactor = ReactorFactory.createReactor(reactorCreateOptions, errorInfo);
/* Any use of the reactor occurs here -- see following sections for all other functionality */
/* Destroy the Reactor. */
reactor.shutdown(errorInfo);

Code Example 1: Reactor Creation and Destruction Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.3

Reactor Detailed View

Reactor Channel Use

The ReactorChannel object is used to represent a connection that can send or receive information across a network. This
object is used to represent a connection, regardless of whether it is an outbound connection or a connection accepted by a
listening socket via a Server. The ReactorChannel is the application’s point of access, used to perform any action on the
connection that it represents (e.g. dispatching events, writing, disconnecting, etc). See the subsequent sections for more
information about ReactorChannel and how to associate with a Reactor.
Note: Only Transport API Reactor methods, like those defined in this chapter, should be called on a channel managed by an
Reactor.
The following table describes the members of the ReactorChannel class.
CLASS MEMBER

DESCRIPTION

hostname

Provides the name of the host to which a consumer or NIP application connects.

majorVersion

When a ReactorChannel is up (ReactorChannelEventTypes.CHANNEL_UP), this is
populated with the major version number associated with the content sent on this connection.
Typically only minor version increases are associated with a fully backward compatible change
or extension.
The Transport API Reactor will leverage the versioning information for any content it is
encoding or decoding. Proper use of versioning should be handled by the application for any
other application encoded or decoded content. For more information on versioning, refer to the
Transport API Java Edition Developers Guide.

minorVersion

When a ReactorChannel is up (ReactorChannelEventTypes.CHANNEL_UP), this is
populated with the minor version number associated with the content sent on this connection.
Typically, a minor version increase is associated with a fully backward compatible change or
extension.
The Transport API Reactor will leverage the versioning information for any content it is
encoding or decoding. Proper use of versioning should be handled by the application for any
other application encoded or decoded content. For more information on versioning, refer to the
Transport API Java Edition Developers Guide.

oldSelectableChannel

It is possible for a selectable channel to change over time, typically due to some kind of
connection keep-alive mechanism. If this occurs, this is typically communicated via a callback
indicating ReactorChannelEventTypes.FD_CHANGE. The previous selectable channel is
stored in oldSelectableChannel so the application can properly unregister and then register
the new selectableChannel with their selector I/O.

protocolType

When a ReactorChannel is up (ReactorChannelEventTypes.CHANNEL_UP), this is
populated with the protocolType associated with the content being sent on this connection. If
the server indicates a protocolType that does not match the protocolType specified by the
client, the connection is rejected.
The Transport API Reactor will leverage the versioning information for any content it is
encoding or decoding. Proper use of versioning should be handled by the application for any
other application encoded or decoded content. For more information on versioning, refer to the
Transport API Java Edition Developers Guide.

Table 10: ReactorChannel Class Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

CLASS MEMBER

Reactor Detailed View

DESCRIPTION

channel

The underlying Channel object, as defined in the Transport API Java Edition Developers
Guide, mainly for reference purposes. All operations should be performed using the Transport
API Reactor functionality; the application should not use this Channel directly with any
Transport functionality.

server

The underlying Server object, as defined in the Transport API Java Edition Developers Guide,
mainly for reference purposes. This is populated only if the channel was created via the
Reactor.accept method, as described in Section 6.4.1.6.

selectableChannel

Represents a selectable channel that can be used in select notification to alert users when
dispatch is required on a specific ReactorChannel. Used to register with a selector.

state

The state of the ReactorChannel.

userSpecObj

An object that can be set by the user of the Channel. This value can be set via the
ReactorConnectOptionss and ReactorAcceptOptions. This information can be useful for
coupling this ReactorChannel with other user-created information.

Table 10: ReactorChannel Class Members (Continued)

6.3.1

Reactor Channel Roles

A ReactorChannel can be configured to fulfill several specific roles, which overlap with the typical OMM application types.
Provided role definitions include:
•

ConsumerRole for OMM Consumer applications

•

ProviderRole for OMM Interactive Provider applications

•

NIProviderRole for OMM Non-Interactive Provider applications

All roles have the same base class, the ReactorRole.

6.3.1.1

ReactorRole Class

ReactorRole contains information and callback methods common to all role types and consists of the following members:

CLASS MEMBER

DESCRIPTION

channelEventCallback

This ReactorChannel‘s user-defined callback method to handle all ReactorChannel specific
events, like ReactorChannelEventTypes.CHANNEL_UP or
ReactorChannelEventTypes.CHANNEL_DOWN. This callback method is required for all role
types. This callback is defined in more detail in Section 6.5.2.

defaultMsgCallback

This ReactorChannel‘s user-defined callback method to handle Msg content not handled by
another domain-specific callback method. This callback method is required for all role types
and is defined in more detail in Section 6.5.2.

type

The role type enumeration value, as defined in Section 6.3.1.2.

Table 11: ReactorRole Class Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.3.1.2

Reactor Detailed View

ReactorRoleType Enumerations

ENUMERATED NAME

DESCRIPTION

CONSUMER

Indicates that the ReactorChannel should act as an OMM Consumer.

NIPROVIDER

Indicates that the ReactorChannel should act as an OMM Non-Interactive Provider.

PROVIDER

Indicates that the ReactorChannel should act as an OMM Interactive Provider.

Table 12: ReactorRoleTypes Enumerated Values

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.3.2

Reactor Detailed View

Reactor Channel Role: OMM Consumer

When a ReactorChannel is acting as an OMM Consumer application, it connects to an OMM Interactive Provider. As part of
this process it is expected to perform a login to the system. Once the login is completed, the consumer acquires a source
directory, which provides information about the available services and their capabilities. Additionally, a consumer can
download or load field dictionaries, providing information to help decode some types of content. The messages that are
exchanged during this connection establishment process are administrative RDMs and are described in the Transport API
Java Edition RDM Usage Guide.
A ReactorChannel in a consumer role helps to simplify this connection process by exchanging these messages on the user’s
behalf. The user can choose to provide specific information or leverage a default populated message, which uses the
information of the user currently logged into the machine running the application. In addition, the Transport API Reactor allows
the application to specify user-defined callback methods to handle the processing of received messages on a per-domain
basis.

6.3.2.1

OMM Consumer Role

When creating a ReactorChannel, this information can be specified with the ConsumerRole object as follows:
CLASS MEMBER

DESCRIPTION

dictionaryDownloadMode

Informs the ReactorChannel of the method to use when requesting dictionaries. Allowable
modes are defined in Section 6.3.2.2.

dictionaryMsgCallback

This ReactorChannel‘s user-defined callback method to handle dictionary message content. If
not specified, all received dictionary messages will be passed to the defaultMsgCallback.

directoryMsgCallback

loginMsgCallback

rdmDirectoryRequest

•

For more details on this callback, refer to Section 6.5.2.

•

Dictionary messages are described in Section 7.5.

This ReactorChannel‘s user-defined callback method to handle directory message content. If
not specified, all received directory messages will be passed to the defaultMsgCallback.
•

For more details on this callback, refer to Section 6.5.2.

•

Directory messages are described in Section 7.4.

This ReactorChannel‘s user-defined callback method to handle login message content. If not
specified, all received login messages will be passed to the defaultMsgCallback.
•

For more details on this callback, refer to Section 6.5.2.

•

The DirectoryRequest (defined in Section 7.4.1) sent during the connection establishment
process. This can be populated with specific source directory request information or invoke the
initDefaultRDMDirectoryRequest method to populate with default information.
•

If this parameter is specified, a rdmDirectoryRequest is required.

•

If this parameter is empty, a directory request is not sent to the system.

rdmLoginRequest

The LoginRequest (defined in Section 7.3.1) sent during the connection establishment
process. This can be populated with a user’s specific information or invoke the
initDefaultRDMLoginRequest method to populate with default information. If this parameter
is empty, a login is not sent to the system; useful for systems that do not require a login.

watchlistOptions

Configurable options for the consumer watchlist. Options are described in more detail in
Section 6.3.2.3.

Table 13: ConsumerRole Class Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.3.2.2

Reactor Detailed View

OMM Consumer Role Dictionary Download Modes

There are several dictionary download options available to a ReactorChannel. The application can determine which option is
desired and specify using the ConsumerRole.dictionaryDownloadMode parameter.
ENUMERATED NAME

DESCRIPTION

FIRST_AVAILABLE

The Reactor will search received directory messages for the
RDMFieldDictionary (RWFFld) and the enumtype.def
(RWFEnum) dictionaries. Once found, the Reactor will
request these dictionaries for the application. After
transmission is completed, the streams are closed because
this content does not update.

NONE

The Reactor will not request dictionaries for this
ReactorChannel. This is typically used when the application
has loaded a file-based dictionary or has acquired the
dictionary elsewhere.

Table 14: ConsumerRole.dictionaryDownloadMode Enumerated Values

6.3.2.3

OMM Consumer Role Watchlist Options

The consumer may enable an internal watchlist and configure behaviors. For more detail on the consumer watchlist feature,
refer to Section 2.4.
OPTION

DESCRIPTION

enableWatchlist

Enables the watchlist.

itemCountHint

Can improve performance when used with the watchlist. If possible, set this to the approximate
number of item requests the application expects to open.

maxOutstandingPosts

Sets the maximum allowable number of on-stream posts waiting for acknowledgment before
the reactor disconnects.

obeyOpenWindow

Sets whether the Reactor obeys the OpenWindow of services advertised in a provider’s
Source Directory response.

postAckTimeout

Sets the time (in milliseconds) a stream waits to receive an ACK for an outstanding post before
forwarding a negative acknowledgment AckMsg to the application.

requestTimeout

Sets the time (in milliseconds) the watchlist waits for a response to a request.

Table 15: OMM Consumer Role Watchlist Options

6.3.2.4

OMM Consumer Role Utility Method

The Transport API provides the following utility method for use with the ConsumerRole.
METHOD NAME
clear

DESCRIPTION
Clears the ConsumerRole object. Useful for object reuse.

Table 16: ConsumerRole Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.3.3

Reactor Detailed View

Reactor Channel Role: OMM Provider

When a ReactorChannel is acting as an OMM provider application, it allows connections from OMM consumer applications.
As part of this process it is expected to respond to login requests and source directory information requests. Additionally, a
provider can optionally allow consumers to download field dictionaries. Messages exchanged during this connection
establishment process are administrative RDMs and are described in the Transport API Java Edition RDM Usage Guide.
A ReactorChannel in an interactive provider role allows the application to specify user-defined callback methods to handle the
processing of received messages on a per-domain basis.

6.3.3.1

OMM Provider Role

When creating a ReactorChannel, this information can be specified with the ProviderRole class, as follows:
CLASS MEMBER
dictionaryMsgCallback

directoryMsgCallback

loginMsgCallback

listenerCallback

DESCRIPTION
This ReactorChannel‘s user-defined callback method to handle dictionary message
content. If unspecified, all received dictionary messages will be passed to the
defaultMsgCallback.
•

For further details on this callback, refer to Section 6.5.2.

•

Dictionary messages are described in Section 7.5.

This ReactorChannel‘s user-defined callback method to handle directory message content.
If unspecified, all received directory messages will be passed to the defaultMsgCallback.
•

For further details on this callback, refer to Section 6.5.2.

•

Directory messages are described in Section 7.4.

This ReactorChannel‘s user-defined callback method to handle login message content. If
unspecified, all received login messages are passed to the defaultMsgCallback.
•

For further details on this callback, refer to Section 6.5.2.

•

This ReactorChannel's user-defined callback for accepting or rejecting tunnel streams.
For further details on this callback, refer to Section 6.7.6.

Table 17: ProviderRole Class Members

6.3.3.2

OMM Provider Role Utility Function

The Transport API provides the following utility function for use with the ProviderRole.
FUNCTION NAME
clear

DESCRIPTION
Clears the ProviderRole object. Useful for object reuse.

Table 18: ProviderRole Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.3.4

Reactor Detailed View

Reactor Channel Role: OMM Non-Interactive Provider

When a ReactorChannel acts as an OMM Non-Interactive Provider application, it connects to an Enterprise Platform ADH and
logs into the system. After login, the non-interactive provider publishes a source directory, which provides information about
the available services and their capabilities. Messages exchanged while establishing the connection are administrative RDMs
and are described in the Transport API Java Edition RDM Usage Guide.
A ReactorChannel in a non-interactive provider role helps to simplify this connection process by exchanging these messages
on the user’s behalf. The user can choose to provide specific information or leverage a default populated message, which
uses the information of the user currently logged into the machine running the application. In addition, the Transport API
Reactor allows the application to specify user-defined callback functions to handle the processing of received messages on a
per-domain basis.

6.3.4.1

OMM Non-Interactive Role Members

When creating a ReactorChannel, this information can be specified with the NIProviderRole class, as follows:
MEMBER

DESCRIPTION

rdmLoginRequest

The LoginRequest, defined in Section 7.3.1, sent when establishing a connection. You can
populate this with a user’s specific information or invoke the initDefaultRDMLoginRequest
method to populate with a default set of information. If empty, a login is not sent to the system;
useful for systems that do not require a login.

rdmDirectoryRefresh

The DirectoryRefresh, defined in Section 7.4.2, sent when establishing a connection. You
can populate this with specific source directory refresh information or invoke the
initDefaultRDMDirectoryRefresh method to populate it with default information.

loginMsgCallback

•

If this parameter is specified, an rdmDirectoryRefresh is required.

•

If this parameter is left empty, a directory request is not sent to the system.

The ReactorChannel‘s user-defined callback method that handles login message content. If
unspecified, all received login messages are passed to the defaultMsgCallback. For further
details on this callback, refer to Section 6.5.2.

Table 19: NIProviderRole Class Members

6.3.4.2

OMM Non-Interactive Provider Role Utility Method

The Transport API provides the following utility method for use with the NIProviderRole.
FUNCTION NAME
clear

DESCRIPTION
Clears the NIProviderRole object. Useful for object reuse.

Table 20: NIProviderRole Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.4

Managing Reactor Channels

6.4.1

Adding Reactor Channels

Reactor Detailed View

A single Reactor instance can manage multiple ReactorChannels. A ReactorChannel can be instantiated as an outbound
client style connection or as a connection that is accepted from a Server. Thus, users can mix connection styles within or
across Reactors and have consistent usage and behavior.
Note: A single Reactor can simultaneously manage ReactorChannels from Reactor.connect and Reactor.accept.

6.4.1.1

Reactor Connect

The Reactor.connect method will create a new ReactorChannel and associate it with a Reactor. This method creates a new
outbound connection. The ReactorChannel is returned to the application via a callback, as described in Section 6.5.2, at
which point it begins dispatching.
Client applications can specify that Reactor automatically reconnect a ReactorChannel whenever a connection fails. To
enable this, the application sets the appropriate members of the ReactorConnectOptions object. The application can specify
that Reactor reconnect the ReactorChannel to the same host, or to one from among multiple hosts.
Consumer applications can combine the reactor connect feature with the watchlist feature to enable recovery of item streams
across connections. For more information on the watchlist feature, refer to Section 2.4.
METHOD NAME
Reactor.connect

DESCRIPTION
Creates a ReactorChannel that makes an outbound connection to the configured host. This
establishes a connection in a manner similar to the Transport.connect method, as described
in the Transport API Java Edition Developers Guide. Connection options are passed in via the
ReactorConnectOptions, as defined in Section 6.4.1.2.
ReactorChannel specific information, such as the per-channel callback functions, the type of
behavior, default RDM messages, and such are passed in via the ReactorRole, as defined in

Section 6.3.1.
Table 21: Reactor.connect Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.4.1.2

Reactor Detailed View

ReactorConnectOptions Class Members

CLASS MEMBER

DESCRIPTION

connectionList

Specifies ReactorConnectInfo as defined in Section 6.4.1.3. When used with
reconnectAttemptLimit, the Reactor attempts to connect to each host in the list with each
reconnection attempt.

reconnectAttemptLimit

The maximum number of times the Reactor attempts to reconnect a channel when it fails. If set
to -1, there is no limit.

reconnectMinDelay

Specifies the minimum length of time the Reactor waits (in milliseconds) before attempting to
reconnect a failed channel. The time increases with each reconnection attempt, from
reconnectMinDelay to reconnectMaxDelay.

reconnectMaxDelay

Specifies the maximum length of time the Reactor waits (in milliseconds) before attempting to
reconnect a failed channel. The time increases with each reconnection attempt, from
reconnectMinDelay to reconnectMaxDelay.

Table 22: ReactorConnectOptions Class Members

6.4.1.3

ReactorConnectInfo Class members

CLASS MEMBER
connectOptions

DESCRIPTION
Specifies information (connectOptions) about the host or network to which to connect, the type
of connection to use, and other transport-specific configuration information associated with the
underlying Transport.connect method.
This is described in more detail in the Transport API Java Developers Guide.

initTimeout

The amount of time (in seconds) to wait to establish a ReactorChannel. If a timeout occurs, an
event is dispatched to the application to indicate that the ReactorChannel is down.

Table 23: ReactorConnectInfo Class Members

6.4.1.4

ReactorConnectOptions Utility Method

The Transport API provides the following utility function for use with the ReactorConnectOptions.
FUNCTION NAME
clear

DESCRIPTION
Clears the ReactorConnectOptions object. Useful for object reuse.

Table 24: ReactorConnectOptions Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.4.1.5

Reactor Detailed View

Reactor.connect Example

ReactorConnectOptions connectOpts = ReactorFactory.createReactorConnectOptions();
ConsumerRole consumerRole = ReactorFactory.createConsumerRole();
/* Configure connection options.*/
connectOpts.clear();
connectOpts.connectOptions.connectionList().get(0).connectOptions().unifiedNetworkInfo().address
("localhost");
connectOpts.connectOptions.connectionList().get(0).connectOptions().unifiedNetworkInfo().serviceName
("14002");
/* Configure a role for this connection as an OMM Consumer. */
consumerRole.clear();
/* Set the methods to which dispatch will deliver events. */
consumerRole.channelEventCallback(channelEventCallback);
consumerRole.defaultMsgCallback(defaultMsgCallback);
consumerRole.loginMsgCallback(loginMsgCallback);
consumerRole.directoryMsgCallback(directoryMsgCallback);
consumerRole.dictionaryMsgCallback(dictionaryMsgCallback);
/* Initialize a default login request. Once the channel is initialized this message will be sent. */
consumerRole.initDefaultRDMLoginRequest();
/* Initialize a default directory request. Once the application has logged in, this message will be
sent. */
consumerRole.initDefaultRDMDirectoryRequest();
/* Add the connection to the Reactor. */
ret = reactor.connect(connectOpts, consumerRole, errorInfo);

Code Example 2: Reactor.connect Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.4.1.6

Reactor Detailed View

Reactor Accept

The Reactor.accept method creates a new ReactorChannel and associates it with an Reactor. This method accepts the
connection from an already running Server. The ReactorChannel will be returned to the application via a callback, as
described in Section 6.5.2, at which point it can begin dispatching on the channel.
METHOD NAME
Reactor.accept

DESCRIPTION
Creates a ReactorChannel by accepting it from a Server. This establishes a connection in a
manner similar to the Server.accept function, as described in the Transport API Java Edition
Developers Guide.
•

Connection options are passed in via ReactorAcceptOptions, as defined in Section
6.4.1.7.

•

ReactorChannel-specific information (such as the per-channel callback functions, the type
of behavior, default RDM messages, and etc.) are passed in via the ReactorRole, as

defined in Section 6.3.1.
Table 25: Reactor.accept Method

6.4.1.7

ReactorAcceptOptions Class Members

CLASS MEMBER

DESCRIPTION

acceptOptions

The AcceptOptions associated with the underlying Server.accept method. This includes an
option to reject the connection as well as a userSpecObject. This is described in more detail in
the Transport API Java Edition Developers Guide.

initTimeout

The amount of time (in seconds) to wait for the successful connection establishment of an
ReactorChannel. If a timeout occurs, an event is dispatched to the application to indicate that
the ReactorChannel is down.

Table 26: ReactorAcceptOptions Class Members

6.4.1.8

ReactorAcceptOptions Utility Function

The Transport API provides the following utility method for use with the ReactorAcceptOptions.
METHOD NAME
clear

DESCRIPTION
Clears the ReactorAcceptOptions object. Useful for object reuse.

Table 27: RsslReactorAcceptOptions Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.4.1.9

Reactor Detailed View

Reactor.accept Example

ReactorAcceptOptions reactorAcceptOpts = ReactorFactory.createReactorAcceptOptions();
ProviderRole providerRole = ReactorFactory.createProviderRole();
/* Configure accept options.*/
reactorAcceptOpts.clear();
reactorAcceptOpts.acceptOptions().userSpecObject(server);
/* Configure a role for this connection as an OMM Provider. */
providerRole.clear();
providerRole.channelEventCallback(channelEventCallback);
providerRole.defaultMsgCallback(defaultMsgCallback);
providerRole.loginMsgCallback(loginMsgCallback);
providerRole.directoryMsgCallback(directoryMsgCallback);
providerRole.dictionaryMsgCallback(dictionaryMsgCallback);
/* Add the connection to the Reactor by accepting it from a Server. */
ret = reactor.accept(server, reactorAcceptOpts, providerRole, errorInfo)

Code Example 3: Reactor.accept Example

6.4.2

Removing Reactor Channels

6.4.2.1

ReactorChannel.close Method

You use the following method to remove a ReactorChannel from a Reactor instance. It can also close and clean up resources
associated with the ReactorChannel.
FUNCTION NAME
ReactorChannel.close

DESCRIPTION
Removes a ReactorChannel from the passed in Reactor instance and cleans up associated
resources. This additionally invokes the Channel.close method, as described in the Transport
API Java Edition Developers Guide, to clean up any resources associated with the underlying
Channel.
This method can be called from either outside or within a callback.

Table 28: ReactorChannel.close Function

6.4.2.2

ReactorChannel.close Example

ReactorErrorInfo errorInfo = ReactorFactory.createReactorErrorInfo();
/* Can be used inside or outside of a callback */
ret = reactorChannel.close(errorInfo);

Code Example 4: ReactorChannel.close Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5

Reactor Detailed View

Dispatching Data

Once an application has a Reactor, it can begin dispatching messages. Until there is at least one associated
ReactorChannel, there is nothing to dispatch. When ReactorChannels are available for dispatching, each channel begins
seeing its user-defined per-channel callbacks being invoked. For more information about available callbacks and their
specifications, refer to Section 6.5.2.
An application can choose to dispatch across all associated ReactorChannels (via Reactor.dispatchAll) or to dispatch on
a particular ReactorChannel (via ReactorChannel.dispatch). If dispatching on a single ReactorChannel, only this channel’s
data is processed and returned via the channel’s callback. If dispatching across multiple ReactorChannels, the Reactor
attempts to fairly dispatch over all channels. In either case, the application can use the dispatch call to specify the maximum
number of messages that will be processed and returned via callback.
Typically, an application registers both the Reactor’s internal ReactorChannel’s selectableChannel and each
ReactorChannel’s selectableChannel with a select notifier. The select notifier can help inform the application when data is
available on particular ReactorChannels or when channel information is available from the Reactor (via its internal
ReactorChannel). An application can also forgo the use of notifiers and instead periodically call the dispatch function to
process data as described in Section 6.5.1.

6.5.1

Reactor Dispatch Methods

Note: Applications should not call Reactor.shutdown, Reactor.dispatchAll, or ReactorChannel.dispatch from within a
callback function. All other Reactor functionality is safe to use from within a callback.
Events received in callback methods should be assumed to be invalid when the callback method returns. For callbacks that
provide Msg, LoginMsg, DirectoryMsg, or DictionaryMsg objects, a deep copy of the object should be made if the application
wishes to preserve it. To copy a Msg, refer to the Msg.copy method in the Transport API Java Edition Developers Guide; for
copying a LoginMsg, DirectoryMsg, or DictionaryMsg object, refer to the copy utility method for the appropriate RDM
message type.
METHOD NAME
Reactor.dispatchAll

DESCRIPTION
This method processes events and messages across the provided Reactor and all of its
associated ReactorChannels. When channel information or data is available for a
ReactorChannel, the channel’s user-defined callback method is invoked.
The application can control the maximum number of messages dispatched with a single call to
Reactor.dispatchAll. This can be controlled through passed-in ReactorDispatchOptions,

as described in Section 6.5.1.1.
ReactorChannel.dispatch

This method processes a specific channel’s events and messages from the Reactor. When
channel information or data is available for a ReactorChannel, the channel’s user-defined
callback method is invoked.
The application can control the maximum number of messages dispatched with a single call to
ReactorChannel.dispatch. This can be controlled through passed-in
ReactorDispatchOptions (for details refer to Section 6.5.1.1).

Table 29: Reactor Dispatch Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.1.1

Reactor Detailed View

Reactor Dispatch Options

An application can use ReactorDispatchOptions to control various aspects of the call to Reactor.dispatchAll and
ReactorChannel.dispatch.
CLASS MEMBER

DESCRIPTION

maxMessages

Controls the maximum number of events or messages processed in this call. If this is larger
than the number of available messages, Reactor.dispatchAll or
ReactorChannel.dispatch will return when there is no more data to process. This value is
initialized to allow up to 100 messages to be returned with a single call to
Reactor.dispatchAll or ReactorChannel.dispatch.

readArgs

The ReadArgs from the underlying Channel.read call.

Table 30: ReactorDispatchOptions Class Members

6.5.1.2

ReactorDispatchOptions Utility Function

The Transport API provides the following utility Method for use with ReactorDispatchOptions.
METHOD NAME
clear

DESCRIPTION
Clears the ReactorDispatchOptions object. Useful for object reuse.

Table 31: ReactorDispatchOptions Utility Method

6.5.1.3

ReactorChannel.dispatch Example

ReactorDispatchOptions dispatchOpts = ReactorFactory.createReactorDispatchOptions();
/* Set dispatching options. */
dispatchOpts.clear();
dispatchOpts.maxMessages(200);
/* Call ReactorChannel.dispatch(). It will keep dispatching events until there is nothing to read or
* maxMessages is reached. */
ret = reactorChannel.dispatch(dispatchOpts, errorInfo);

Code Example 5: ReactorChannel.dispatch Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.2

Reactor Detailed View

Reactor Callback Methods

A series of callback methods returns (to the application) any state information about the ReactorChannel connection as well
as messages for that channel. Each ReactorChannel can define its own unique callback methods or specify callback methods
that can be shared across channels.
There are several values that can be returned from a callback method implementation. These can trigger specific Reactor
behaviors based on the outcome of the callback method. Callback return values are as follows:
RETURN CODE

DESCRIPTION

SUCCESS

Indicates that the callback function was successful and the message or event has been
handled.

FAILURE

Indicates that the message or event has failed to be handled. Returning this code from any
callback function will cause the Reactor to shutdown.

RAISE

Can be returned from any domain-specific callback (e.g., RDMLoginMsgCallback). This will
cause the Reactor to invoke the DefaultMsgCallback for this message upon the domainspecific callbacks return.

Table 32: ReactorCallbackReturnCodes Callback Return Codes
All events communicated to callback methods have the same base class, the ReactorEvent, which contains information
common to all callback events.
CLASS MEMBER

DESCRIPTION

reactorChannel

The ReactorChannel on which the event occurred.

errorInfo

The ReactorErrorInfo associated with this event.

Table 33: ReactorEvent Class Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.3

Reactor Detailed View

Reactor Callback: Channel Event

The Reactor channel event callback communicates ReactorChannel and connection state information to the application. This
interface has the following callback method:

reactorChannelEventCallback(ReactorChannelEvent event)

When invoked, this returns a ReactorChannelEvent object, containing more information about the event.

6.5.3.1

Reactor Channel Event

The ReactorChannelEvent is returned to the application via the ReactorChannelEventCallback.
CLASS MEMBER
eventType

DESCRIPTION
The type of event that has occurred on the ReactorChannel. For a list of
enumeration values, refer to Section 6.5.3.2.

Table 34: ReactorChannelEvent Class Member

6.5.3.2

Reactor Channel Event Type Enumeration Values

FLAG ENUMERATION
CHANNEL_DOWN

MEANING
Indicates that the ReactorChannel is not available for use. This could be a result of
an initialization failure, a ping timeout, or some other kind of connection-related
issue. ReactorErrorInfo will contain more detailed information about what
occurred.
There is no connection recovery for this event.
To clean up the failed ReactorChannel, the application should call
ReactorChannel.close.

CHANNEL_DOWN_RECONNECTING Indicates that the ReactorChannel is temporarily unavailable for use. The Reactor
will attempt to reconnect the channel according to the values specified in
ReactorConnectOptionss when Reactor.connect was called.
This only occurs on client connections because there is no connection recovery for
server connections.
If the watchlist is enabled, requests are recovered as appropriate when the channel
successfully reconnects.
Before exiting the channelEventCallback, the application should release any
resources associated with the channel, such as TransportBuffers, and unregister
its selectableChannel, if valid, from any select notifiers.
CHANNEL_OPENED

Indicates that the watchlist is enabled and that a channel has been created via
Reactor.connect. Though the channel is still not ready for dispatch, the application
can begin submitting request messages, which are sent after the channel
successfully initializes.

Table 35: ReactorChannelEventType Enumeration Values

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

FLAG ENUMERATION
CHANNEL_READY

Reactor Detailed View

MEANING
Indicates that the ReactorChannel has successfully completed any necessary
initialization processes. Where applicable, this includes exchanging any provided
Login, Directory, or Dictionary content.
The application should now be able to consume or provide content.

CHANNEL_UP

Indicates that the ReactorChannel is successfully initialized and available for
dispatching. Where applicable, any specified Login, Directory, or Dictionary
messages are exchanged by the Reactor.

FD_CHANGE

Indicates that a selectable channel change occurred on the ReactorChannel. If the
application is using a select notification mechanism, it should unregister the
oldSelectableChannel and register the selectableChannel, both of which can be
found on the ReactorChannel.

INIT

Channel event initialization value. This should not be used by nor returned to the
application.

WARNING

Indicates that the ReactorChannel has experienced an event that did not result in
connection failure, but may require the attention of the application.
ReactorErrorInfo contains more detailed information about what occurred.

Table 35: ReactorChannelEventType Enumeration Values (Continued)

6.5.3.3

Reactor Channel Event Utility Methods

METHOD NAME
clear

DESCRIPTION
Clears a ReactorChannelEvent object.

Table 36: ReactorChannelEvent Utility Methods

6.5.3.4

Reactor Channel Event Callback Example

public int reactorChannelEventCallback(ReactorChannelEvent event)
{
switch(event.eventType())
{
case ReactorChannelEventTypes.CHANNEL_UP:
// register selector with channel event's reactorChannel
event.reactorChannel().selectableChannel().register(selector, SelectionKey.OP_READ,
event.reactorChannel());
break;
case ReactorChannelEventTypes.CHANNEL_DOWN:
// close ReactorChannel
if (event.reactorChannel() != null)
{
event.reactorChannel().close(errorInfo);
}
break;

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

Reactor Detailed View

case ReactorChannelEventTypes.CHANNEL_READY:
/* Channel has exchanged its initial messages (if any were provided on the role object)
* and is ready for use. */
sendItemRequests(reactorChannel);
break;
case ReactorChannelEventTypes.FD_CHANGE:
/* The descriptor representing this channel has changed. Normally the application only
* needs to update its notification mechanism in response to this event. */
// cancel old reactorChannel select
SelectionKey key = event.reactorChannel().oldSelectableChannel().keyFor(selector);
key.cancel();
// register selector with channel event's new reactorChannel
event.reactorChannel().selectableChannel().register(selector, SelectionKey.OP_READ,
event.reactorChannel());
break;
}
return ReactorCallbackReturnCodes.SUCCESS;
}

Code Example 6: Reactor Channel Event Callback Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.4

Reactor Detailed View

Reactor Callback: Default Message

The Reactor default message callback communicates all received content that is not handled directly by a domain-specific
callback method. This callback is also invoked after any domain-specific callback that returns the
ReactorCallbackReturnCodes.RAISE value. This interface has the following callback method:

public int defaultMsgCallback(ReactorMsgEvent event)

When invoked, this returns a ReactorMsgEvent object, containing more information about the event information.

6.5.4.1

Reactor Message Event

The ReactorMsgEvent is returned to the application via the DefaultMsgCallback. This is also the base class of the
RDMDictionaryMsgEvent, RDMDirectoryMsgEvent, and RDMLoginMsgEvent classes.
CLASS MEMBER
transportBuffer

DESCRIPTION
A TransportBuffer containing the raw, undecoded message that was read and
processed by the callback.
Note: When the consumer watchlist is enabled, a TransportBuffer is not provided,
because the message might not match this buffer, or the message might be internally
generated.

msg

A Msg object populated with message content by calling Msg.decode. If not present, an
error was encountered while processing the information.
Note: When the consumer watchlist is enabled, msg is not provided to callback functions
that provide RDM messages.

streamInfo

Any information associated with a stream (only when the consumer watchlist is enabled).

Table 37: ReactorMsgEvent Class Members

6.5.4.2

Reactor Message Event Utility Methods

METHOD NAME
clear

DESCRIPTION
Clears a ReactorMsgEvent object.

Table 38: ReactorMsgEvent Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.4.3

Reactor Detailed View

Reactor Message Event Callback Example

public int defaultMsgCallback(ReactorMsgEvent event)
{
Msg msg = event.msg();
/* Received a Msg --- or, if the decode failed, an error. */
/* The Msg will have already been passed through Msg.decode. Only the payload requires
additional decoding. */
if (msg != null)
processMsg(msg);
else
System.out.printf("defaultMsgCallback Error: %s(%s)\n", event.errorInfo().error().text(),
event.errorInfo().location());
}

Code Example 7: Reactor Message Event Callback Example

6.5.5

Reactor Callback: RDM Login Message

The Reactor RDM Login Message callback is used to communicate all received RDM Login messages. This interface has the
following callback method:

public int rdmLoginMsgCallback(RDMLoginMsgEvent event)

When invoked, this will return the RDMLoginMsgEvent object, containing more information about the event information.

6.5.5.1

Reactor RDM Login Message Event

The RDMLoginMsgEvent is returned to the application via the RDMLoginMsgCallback.
CLASS MEMBER
rdmLoginMsg

DESCRIPTION
The RDM representation of the decoded Login message. If not present, an error was
encountered while processing the information.
This message is presented as the LoginMsg, described in Section 7.3.

Table 39: RDMLoginMsgEvent Class Member

6.5.5.2

Reactor RDM Login Message Event Utility Method

METHOD NAME
clear

DESCRIPTION
Clears a RDMLoginMsgEvent object.

Table 40: RDMLoginMsgEvent Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.5.3

Reactor Detailed View

Reactor RDM Login Message Event Callback Example

public int rdmLoginMsgCallback(RDMLoginMsgEvent event)
{
LoginMsg loginMsg = event.rdmLoginMsg();
/* Received an RDM LoginMsg --- or, if the decode failed, an error. */
/* The login message will already be fully decoded. */
if (loginMsg != null)
{
switch(loginMsg.rdmMsgType())
{
case REFRESH:
LoginRefresh refresh = (LoginRefresh)loginMsg;
break;
case STATUS:
LoginStatus status = (LoginStatus)loginMsg;
break;
default:
System.out.println("Received unhandled login message.");
break;
}
}
else
System.out.printf("rdmLoginMsgCallback Error: %s(%s)\n",
event.errorInfo().error().text(),
event.errorInfo().location());
}

Code Example 8: Reactor RDM Login Message Event Callback Example

6.5.6

Reactor Callback: RDM Directory Message

The Reactor RDM Directory Message callback is used to communicate all received RDM Directory messages. This interface
has the following callback method:

public int rdmDirectoryMsgCallback(RDMDirectoryMsgEvent event)

When invoked, this will return the RDMDirectoryMsgEvent object, containing more information about the event information.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.6.1

Reactor Detailed View

Reactor RDM Directory Message Event

The RDMDirectoryMsgEvent is returned to the application via the RDMDirectoryMsgCallback.
CLASS MEMBER
rdmDirectoryMsg

DESCRIPTION
The RDM representation of the decoded Source Directory message. If not present,
an error was encountered while processing the information.
This message is presented as the DirectoryMsg, described in Section 7.4.

Table 41: RDMDirectoryMsgEvent Class Member

6.5.6.2

Reactor RDM Directory Message Event Utility Method

METHOD NAME
clear

DESCRIPTION
Clears an RDMDirectoryMsgEvent object.

Table 42: RDMDirectoryMsgEvent Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.6.3

Reactor Detailed View

Reactor RDM Directory Message Event Callback Example

public int rdmDirectoryMsgCallback(RDMDirectoryMsgEvent event)
{
DirectoryMsg directoryMsg = event.rdmDirectoryMsg();
/* Received an RDM DirectoryMsg --- or, if the decode failed, an error. */
/* The directory message will already be fully decoded. */
if (directoryMsg != null)
{
switch(directoryMsg.rdmMsgType())
{
case REFRESH:
DirectoryRefresh refresh = (DirectoryRefresh)directoryMsg;
break;
case UPDATE:
DirectoryUpdate update = (DirectoryUpdate)directoryMsg;
break;
case STATUS:
DirectoryStatus status = (DirectoryStatus)directoryMsg;
break;
default:
System.out.println("Received unhandled directory message.");
}
}
else
System.out.printf("rdmDirectoryMsgCallback Error: %s(%s)\n",
event.errorInfo().error().text(),
event.errorInfo().location());
}

Code Example 9: Reactor RDM Directory Message Event Callback Example

6.5.7

Reactor Callback: RDM Dictionary Message

The Reactor RDM Dictionary Message callback is used to communicate all received RDM Dictionary messages. This
interface has the following callback method:

public int rdmDictionaryMsgCallback(RDMDictionaryMsgEvent event)

When invoked, this will return the RDMDictionaryMsgEvent object, containing more information about the event information.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.5.7.1

Reactor Detailed View

Reactor RDM Dictionary Message Event

The RDMDictionaryMsgEvent is returned to the application via the RDMDictionaryMsgCallback.
CLASS MEMBER
rdmDictionaryMsg

DESCRIPTION
The RDM representation of the decoded Dictionary message. If not present, an error
was encountered while processing the information.
This message is presented as the DictionaryMsg, described in Section 7.5.

Table 43: RDMDictionaryMsgEvent Class Member

6.5.7.2

Reactor RDM Dictionary Message Event Utility Method

METHOD NAME
clear

DESCRIPTION
Clears an RDMDictionaryMsgEvent object.

Table 44: RDMDictionaryMsgEvent Utility Method

6.5.7.3

Reactor RDM Dictionary Message Event Callback Example

public int rdmDictionaryMsgCallback(RDMDictionaryMsgEvent event)
{
DictionaryMsg dictionaryMsg = event.rdmDictionaryMsg();
/* Received an RDM DictionaryMsg --- or, if the decode failed, an error. */
if (dictionaryMsg != null)
{
switch(dictionaryMsg.rdmMsgType())
{
case REFRESH:
DictionaryRefresh refresh = (DictionaryRefresh)dictionaryMsg;
break;
case STATUS:
DictionaryStatus status = (DictionaryStatus)dictionaryMsg;
break;
default:
System.out.println("Received unhandled dictionary message.");
}
}
else
System.out.printf("rdmDictionaryMsgCallback Error: %s(%s)\n",
event.errorInfo().error().text(),
event.errorInfo().location());
}

Code Example 10: Reactor RDM Dictionary Message Event Callback Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6

Reactor Detailed View

Writing Data

The Transport API Reactor helps streamline the high performance writing of content. The Reactor flushes content to the
network so the application does not need to. The Reactor does so through the use of a separate worker thread that becomes
active whenever there is queued content that needs to be passed to the connection.
The Transport API Reactor offers two methods for writing content: ReactorChannel.submit(Msg...) and
ReactorChannel.submit(TransportBuffer...). When writing applications to the Reactor, consider which is most
appropriate for your needs:
ReactorChannel.submit(Msg...)

ReactorChannel.submit(TransportBuffer...)

•

Takes an Msg object as part of its options; does not
require retrieval of an TransportBuffer from the
channel.

•

Takes an TransportBuffer which the application
retrieves from the channel.

•

Must be used when the consumer watchlist is enabled.

More efficient: the application encodes directly into the
buffer, and can use buffer packing.

•

Cannot be used when the consumer watchlist is enabled.

6.6.1

Writing Data using ReactorChannel.submit(Msg…)

ReactorChannel.submit(Msg...) provides a simple interface for writing Msgs. To send a message, the application populates
an Msg object, sets any other desired options on a ReactorSubmitOptions object, and calls
ReactorChannel.submit(Msg...) with the object.

A buffer is not needed to use ReactorChannel.submit(Msg...). If the application needs to include any encoded content, it
can encode the content into any available memory, and set the appropriate member of the Msg to point to the memory (as well
as set the length of the encoded content).

6.6.1.1

ReactorChannel.submit(Msg…) Method

METHOD NAME
ReactorChannel.submit

DESCRIPTION
Encodes and submits a Msg to the Reactor. This method expects a properly populated Msg.

Table 45: ReactorChannel.submit(Msg...) Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.1.2

Reactor Detailed View

Reactor Submit Options

An application can use ReactorSubmitOptions to control various aspects of the call to ReactorChannel.submit.
CLASS MEMBER
serviceName

DESCRIPTION
The application can use this instead of the serviceId member specified on the
MsgKey of a Msg.
When used to open streams via request messages, the Reactor will recover using
this service name.
When used for other message types such as a post or generic message, the
Reactor converts the name to its corresponding ID before writing the message.

Note: This option is supported only when the watchlist is enabled.
requestMsgOptions

Provides additional functionality that may be used when using request messages to
send requests.

writeArgs.bytesWritten

If specified, will return the number of bytes to be written, including any transport
header overhead and taking into account any savings from compression.

writeArgs.flags

Flag values that allow the application to modify the behavior of this
ReactorChannel.submit call. This includes options to bypass queuing or
compression.
More information about the specific flag values is available in the Transport API Java
Edition Developers Guide.

writeArgs.priority

Controls the priority at which the data will be written. Valid priorities are
•

WritePriorities.HIGH

•

WritePriorities.MEDIUM

•

WritePriorities.LOW

More information about write priorities, including an example scenario, is available in
the Transport API Java Edition Developers Guide.
writeArgs.uncompressedBytesWritten If specified, will return the number of bytes to be written, including any transport
header overhead but not taking into account any compression savings.
Table 46: ReactorSubmitOptions Class Members

6.6.1.3

ReactorChannel.submit(Msg...) Return Codes

The following table defines the return codes that can occur when using ReactorChannel.submit(Msg...).
RETURN CODE

DESCRIPTION

ReactorReturnCodes.SUCCESS

Indicates that the ReactorChannel.submit(Msg...) method has succeeded.

ReactorReturnCodes.NO_BUFFERS

Indicates that not enough pool buffers are available to write the message.
The application can try to submit the message later, or it can use
ReactorChannel.ioctl to increase the number of available pool buffers and
try again.

Table 47: ReactorChannel.submit(Msg...) Return Codes

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

RETURN CODE

Reactor Detailed View

DESCRIPTION

ReactorReturnCodes.WRITE_CALL_AGAIN Indicates that buffer created for the Msg is being fragmented and needs to be
called again with the same Msg. This indicates that underlying write was unable
to send all fragments with the current call and must continue fragmenting.
ReactorReturnCodes.FAILURE

Indicates that a general failure has occurred and the message was not
submitted. The ReactorErrorInfo object passed to the method will contain
more details.

Table 47: ReactorChannel.submit(Msg...) Return Codes (Continued)

6.6.1.4

ReactorRequestMsgOptions

ReactorRequestMsgOptions provide additional functionality when requesting items. These options are available only when
the consumer watchlist is enabled.

CLASS MEMBER
userSpecObj

DESCRIPTION
A user-specified object that will be associated with the stream. This object will be
provided in responses to this stream via the WatchlistStreamInfo provided with
each message event.

Table 48: ReactorRequestMsgOptions Class Members

6.6.1.5

ReactorSubmitOptions Utility Method

The Transport API provides the following utility function for use with ReactorSubmitOptions.
METHOD NAME
clear

DESCRIPTION
Clears the ReactorSubmitOptions object. Useful for object reuse.

Table 49: ReactorSubmitOptions Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.1.6

Reactor Detailed View

ReactorChannel.submit(Msg...) Example

The following example shows typical use of ReactorChannel.submit(Msg...).

RequestMsg requestMsg = (RequestMsg)CodecFactory.createMsg();
ReactorSubmitOptions opts = ReactorFactory.createReactorSubmitOptions();
ReactorErrorInfo errorInfo = ReactorFactory.createReactorErrorInfo();
int ret;
requestMsg.clear();
requestMsg.msgClass(MsgClasses.REQUEST);
requestMsg.streamId(2);
requestMsg.domainType(DomainTypes.MARKET_PRICE);
requestMsg.containerType(DataTypes.NO_DATA);
requestMsg.applyStreaming();
requestMsg.applyHasQos();
requestMsg.qos().timeliness(QosTimeliness.REALTIME);
requestMsg.qos().rate(QosRates.TICK_BY_TICK);
requestMsg.msgKey().applyHasName();
requestMsg.msgKey().applyHasServiceId();
requestMsg.msgKey().name().data(“TRI.N”);
requestMsg.msgKey().serviceId(1);
ret = reactorChannel.submit(requestMsg, opts, errorInfo);

Code Example 11: ReactorChannel.submit(Msg...) Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.2

Reactor Detailed View

Writing Data Using ReactorChannel.submit(TransportBuffer...)

The ReactorChannel.submit(TransportBuffer...) method offers efficient writing of data by using buffers retrieved directly
from the Transport API transport buffer pool. It also provides additional features not normally available from
ReactorChannel.submit(Msg...), such as buffer packing. When ready to send data, the application acquires a buffer from
the Transport API pool. This allows the content to be encoded directly into the output buffer, reducing the number of times the
content needs to be copied. Once content is encoded and the buffer is properly populated, the application can submit the data
to the reactor. The Transport API will ensure that successfully submitted buffers reach the network. Applications can also pack
multiple messages into a single buffer by following a similar process as described above, however instead of getting a new
buffer for each message the application uses the reactor’s pack function instead. The following flow chart depicts the typical
write process.

Figure 7. Flow Chart for writing data via ReactorChannel.submit(TransportBuffer...)

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.2.1

Reactor Detailed View

Obtaining a Buffer: Overview

Before you can submit information, you must obtain a buffer from the internal Transport API buffer pool, as described in the
Transport API Java Edition Developers Guide. After acquiring the buffer via ReactorChannel.getBuffer, you can populate
the TransportBuffer.data. If the buffer is not used or the ReactorChannel.submit(TransportBuffer...) method call
fails, the buffer must be released back into the pool to ensure proper reuse and cleanup. If the buffer is successfully passed to
ReactorChannel.submit(TransportBuffer...), the reactor will return the buffer to the pool.
The number of buffers made available to an ReactorChannel is configurable through the ReactorConnectOptions or
ReactorAcceptOptions. For more information about available Reactor.connect and Reactor.accept options, refer to
Section 6.4.1.2 and Section 6.4.1.7.

6.6.2.2

Obtaining a Buffer: ReactorChannel Buffer Management Methods

METHOD NAME
getBuffer

DESCRIPTION
Obtains a buffer of the requested size from the buffer pool.
If the requested size is larger than the maxFragmentSize, the transport will create
and return the buffer to the user. When written, this buffer will be fragmented by the
ReactorChannel.submit(TransportBuffer...) method (for further details, refer to
Section 6.6.2.4).
Because of some additional book keeping required when packing, the application
must specify whether a buffer should be ‘packable’ when calling getBuffer. For
more information on packing, refer to Section 6.6.2.11.
For performance purposes, an application is not permitted to request a buffer larger
than maxFragmentSize and have the buffer be ‘packable.’
If the buffer is not used or the ReactorChannel.submit(TransportBuffer...) call
fails, the buffer must be returned to the pool using releaseBuffer. If the
ReactorChannel.submit(TransportBuffer...) call is successful, the buffer will
be returned to the correct pool by the transport.
This method calls the Channel.getBuffer method which has its use and return
values described in the Transport API Java Edition Developers Guide.

releaseBuffer

Releases a buffer back to the correct pool. This should only be called with buffers
that originate from getBuffer and are not successfully passed to
ReactorChannel.submit(TransportBuffer...).
This method calls the Transport API Channel.releaseBuffer method which has its
use and return values described in the Transport API Java Edition Developers Guide.

bufferUsage

Returns the number of buffers currently in use by the ReactorChannel, this includes
buffers that the application holds and buffers internally queued and waiting to be
flushed to the connection by the Reactor.
This method calls the Channel.bufferUsage method which has its use and return
values described in the Transport API Java Edition Developers Guide.

Table 50: ReactorChannel Buffer Management Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.2.3

Reactor Detailed View

Obtaining a Buffer: ReactorChannel.getBuffer Return Values

The following table defines return and error code values that can occur while using ReactorChannel.getBuffer.
RETURN CODE
Valid buffer returned
Success Case

DESCRIPTION
A TransportBuffer is returned to the user. The
TransportBuffer.length indicates the number of bytes available to
populate and the TransportBuffer.data provides a ByteBuffer for
population.

NULL buffer returned
Error Code: NO_BUFFERS

NULL is returned to the user. This value indicates that there are no
buffers available to the user. See ReactorErrorInfo content for more
details.
This typically occurs because all available buffers are queued and
pending flushing to the connection. The ReactorChannel.ioctl
function can be used to increase the number of
guaranteedOutputBuffers (for details, refer to Section 6.8).

NULL buffer returned
Error Code: FAILURE
NULL buffer returned
Error Code: INIT_NOT_INITIALIZED

NULL is returned to the user. This value indicates that some type of
general failure has occurred. The ReactorChannel should be closed.
Indicates that the underlying Transport API Transport has not been
initialized. See the ReactorErrorInfo content for more details.

Table 51: ReactorChannel.getBuffer Return Values

6.6.2.4

Writing Data: Overview

After a TransportBuffer is obtained from getBuffer and populated with the user’s data, the buffer can be passed to the
ReactorChannel.submit(TransportBuffer...) method. This method manages queuing and flushing of user content. It will
also perform any fragmentation or compression. If an unrecoverable error occurs, any TransportBuffer that has not been
successfully passed to ReactorChannel.submit(TransportBuffer...) should be released to the pool using
releaseBuffer. Section 6.6.2.5 describes the ReactorChannel.submit(TransportBuffer...) method and its associated
parameters.

6.6.2.5

Writing Data: ReactorChannel.submit(TransportBuffer…) Method

METHOD NAME
submit

DESCRIPTION
Writes data. This method expects the buffer to be properly populated. This method
calls the Transport API Channel.write method and also triggers the Channel.flush
method (described in the Transport API Java Edition Developers Guide).
This method allows for several modifications and additional parameters to be
specified via the ReactorSubmitOptions object, defined in Section 6.6.1.2.
For a list of return codes, refer to Section 6.6.2.8.

Table 52: ReactorChannel.submit(TransportBuffer...) Method

6.6.2.6

Writing Data: Reactor Submit Options

For a list of submit options and their descriptions for use with ReactorChannel.submit(TransportBuffer...), refer to
Section 6.6.1.2.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.2.7

Reactor Detailed View

Writing Data: ReactorRequestMsgOptions

For a list of request message options and their descriptions for use with ReactorChannel.submit(TransportBuffer...),
refer to Section 6.6.1.4.

6.6.2.8

Writing Data: ReactorChannel.submit(TransportBuffer…) Return Codes

The following table defines the return codes that can occur when using ReactorChannel.submit(TransportBuffer...).
RETURN CODE
ReactorReturnCodes.SUCCESS

DESCRIPTION
Indicates that the ReactorChannel.submit(TransportBuffer...) method
has succeeded.
The TransportBuffer will be released by the Transport API Reactor.

ReactorReturnCodes.WRITE_CALL_AGAIN Indicates that a large buffer could not be fully written with this
ReactorChannel.submit(TransportBuffer...) call. This is typically due to
all pool buffers being unavailable. The Reactor will flush for the user to free up
buffers. The application can optionally use ReactorChannel.ioctl to
increase the number of available pool buffers. After pool buffers become
available again, the same buffer should be used to call
ReactorChannel.submit(TransportBuffer...) an additional time (using
the same priority level for proper ordering of each fragment). This will continue
the fragmentation process from where it left off.
If the application does not subsequently pass the buffer to
ReactorChannel.submit(TransportBuffer...), the application should
release it by calling ReactorChannel.releaseBuffer.
ReactorReturnCodes.FAILURE

Indicates that a general write failure has occurred. The ReactorChannel
should be closed.
The application should release the TransportBuffer by calling
ReactorChannel.releaseBuffer.

Table 53: ReactorChannel.submit(TransportBuffer...) Return Codes

6.6.2.9

Writing Data: ReactorSubmitOptions Utility Function

For a details on the on the utility method for use with ReactorChannel.submit(TransportBuffer...), refer to Section
6.6.1.5.

6.6.2.10

Example: ReactorChannel.getBuffer and ReactorChannel.submit(TransportBuffer…) Example

The following example shows typical use of ReactorChannel.getBuffer and
ReactorChannel.submit(TransportBuffer...).

TransportBuffer msgBuffer = null;
EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
ReactorSubmitOptions submitOpts = ReactorFactory.createReactorSubmitOptions();
msgBuffer = reactorChannel.getBuffer(1024, false, errorInfo);
encodeIter.clear();
encodeIter.setBufferAndRWFVersion(msgBuffer, reactorChannel.majorVersion(),
reactorChannel.minorVersion());
encodeMsgIntoBuffer(encodeIter, msgBuffer);
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

Reactor Detailed View

submitOpts.clear();
ret = reactorChannel.submit(msgBuffer, submitOpts, errorInfo);
// check return code
switch (ret)
{
case ReactorReturnCodes.SUCCESS:
// successful write, nothing left to do
return ReactorReturnCodes.SUCCESS;
break;
case ReactorReturnCodes.FAILURE:
// an error occurred, need to release buffer
reactorChannel.releaseBuffer(msgBuffer, errorInfo);
break;
case ReactorReturnCodes.WRITE_CALL_AGAIN:
// large message couldn’t be fully written with one call, pass it to submit again
ret = reactorChannel.submit(msgBuffer, submitOpts, errorInfo);
break;
}

Code Example 12: Writing Data Using ReactorChannel.submit, ReactorChannel.getBuffer, and ReactorChannel.releaseBuffer

6.6.2.11

Packing Additional Data into a Buffer

If an application is writing many small buffers, it may be advantageous to combine the small buffers into one larger buffer. This
can increase efficiency of the transport layer by reducing the overhead associated with each write operation, although it may
add to the latency associated with each smaller buffer.
It is up to the writing application to determine when to stop packing, and the mechanism used can vary greatly. A simple
algorithm can pack a fixed number of messages each time. A slightly more complex technique could use the length returned
from ReactorChannel.packBuffer to determine the amount of space remaining and pack until the buffer is nearly full. Both of
these mechanisms can introduce a variable amount of latency as they both depend on the rate of arrival of data (e.g., the
packed buffer will not be written until enough data arrives to fill it). One way of balancing this is to employ a timer, used to limit
the amount of time a packed buffer is held. If the buffer is full prior to the timer expiring, the data is written. However, when the
timer expires the buffer will be written regardless of the amount of data it contains. This can help limit latency by specifying a
limit to the time data is held (via use of the timer).
METHOD NAME
ReactorChannel.packBuffer

DESCRIPTION
Packs the contents of a passed-in TransportBuffer and returns the amount of
available bytes remaining in the buffer for packing. An application can use the length
returned to determine the amount of space available to continue packing buffers into.
For a buffer to allow packing, it must be requested from ReactorChannel.getBuffer
as ‘packable’ and cannot exceed the maxFragmentSize.
ReactorChannel.packBuffer return values are defined in Section 6.6.2.12.

This method calls the Channel.packBuffer method as described in the Transport
API Java Edition Developers Guide.
Table 54: ReactorChannel.packBuffer Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.2.12

Reactor Detailed View

ReactorChannel.packBuffer Return Values

The following table defines return and error code values that can occur when using ReactorChannel.packBuffer.
RETURN CODE

DESCRIPTION

Positive value or ReactorReturnCodes.SUCCESS The amount of available bytes remaining in the buffer for packing.
Success Case
Negative value
Failure Case

This value indicates that some type of failure has occurred. If the
FAILURE return code is returned, the ReactorChannel should be
closed.

Table 55: ReactorChannel.packBuffer Return Values

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.6.2.13

Reactor Detailed View

Example: ReactorChannel.getBuffer, ReactorChannel.packBuffer, and
ReactorChannel.submit(TransportBuffer…)

The following example shows typical use of ReactorChannel.getBuffer, ReactorChannel.packBuffer, and
ReactorChannel.submit(TransportBuffer…).

int remainingLength = 0;
TransportBuffer msgBuffer = null;
EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
ReactorSubmitOptions submitOpts = ReactorFactory.createReactorSubmitOptions();
/* get a packable buffer */
msgBuffer = reactorChannel.getBuffer(1024, true, errorInfo);
encodeIter.clear();
encodeIter.setBufferAndRWFVersion(msgBuffer, reactorChannel.majorVersion(),
reactorChannel.minorVersion());
encodeMsgIntoBuffer(encodeIter, msgBuffer);
/* pack first encoded message into buffer */
remainingLength = reactorChannel.packBuffer(msgBuffer, errorInfo);
encodeIter.clear();
encodeIter.setBufferAndRWFVersion(msgBuffer, reactorChannel.majorVersion(),
reactorChannel.minorVersion());
encodeMsgIntoBuffer(encodeIter, msgBuffer);
/* pack second encoded message into buffer */
remainingLength = reactorChannel.packBuffer(msgBuffer, errorInfo);
encodeIter.clear();
encodeIter.setBufferAndRWFVersion(msgBuffer, reactorChannel.majorVersion(),
reactorChannel.minorVersion());
/* now write packed buffer by passing third buffer to submit */
encodeMsgIntoBuffer(encodeIter, msgBuffer);
submitOpts.clear();
ret = reactorChannel.submit(msgBuffer, submitOpts, errorInfo);

Code Example 13: Message Packing using ReactorChannel.packBuffer

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7

Reactor Detailed View

Creating and Using Tunnel Streams

The Reactor allows users to create and use special tunnel streams. A tunnel stream is a private stream with additional
behaviors, such as end-to-end line of sight for authentication and guaranteed delivery. Tunnel streams are founded on the
private streams concept, and the Transport API establishes them between consumer and provider endpoints (passing through
any intermediate components, such as TREP or EED).
When creating a tunnel, the consumer indicates any additional behaviors to enforce, which is exchanged with the provider
application end point. The provider end-point acknowledges creation of the stream as well as the behaviors that it will enforce
on the stream. After the stream is established, the consumer can exchange any content it wants, though the tunnel stream will
enforce behaviors on the transmitted content as negotiated with the provider.
A tunnel stream allows for multiple substreams to exist, where substreams follow from the same general stream concept,
except that they flow and coexist within the confines of a tunnel stream.
In the following diagram, the orange cylinder represents a tunnel stream that connects the consumer application to the
provider application. Notice that the tunnel stream passes directly through intermediate components: the tunnel stream has
end-to-end line of sight so that the provider and consumer effectively talk to one another directly, though they traverse multiple
devices in the system. Each black line flowing through the cylinder represents a different substream, where each substream
transmits its own independent stream of information. Each substream could communicate different market content; for
example one could be a Time Series request while another could be a request for Market Price content. A substream can also
connect to a special provider application called a Queue Provider. A Queue Provider allows for persistence of content
exchanged over the tunnel stream and substream, and helps provide content beyond the end-point visible to the consumer. To
interact with a Queue Provider, additional addressing information is required, described in more detail in Section 7.6.

Figure 8. Tunnel Stream Illustration

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.1

Reactor Detailed View

Authenticating a Tunnel Stream

Providers might require the consumer to authenticate itself when establishing the tunnel stream. The type of authentication, if
any, is given by the ClassOfService.authentication.type. For more information on class or service, refer to Section 6.7.3.
The ClassOfService.authentication.type may be set to OMM_LOGIN. When an OMM consumer expects this type of
authentication, it should set a LoginRequest message on the TunnelStreamOpenOptions.authLoginRequest member. If the
OMM consumer application does not provide it, the API will use the login request provided on the
ConsumerRole.rdmLoginRequest when the consumer connected (refer to Section 6.3.2). The consumer must provide one of
these for authentication of this type.
The login request will be sent to the provider. When the provider sends a Login response to complete the authentication, the
TunnelStreamStatusEvent event given to the consumer will include an TunnelStreamAuthInfo object with more details.
OMM provider applications will see the login request as a normal message within the TunnelStream and should respond with
a login response message via TunnelStream.submit.
Other types of authentication might be specified, but must be performed by both the provider and consumer applications by
submitting normal TunnelStream messages via TunnelStream.submit.
The TunnelStreamAuthInfo object contains the following member:
MEMBER
loginMsg

DESCRIPTION
The Login message sent by the tunnel stream’s provider application, which resulted in this event.

Table 56: TunnelStreamAuthInfo Members

6.7.2

Opening a Tunnel Stream

The user can create one or more tunnel streams and associate them with any ReactorChannel, which opens the private
stream connection and negotiates any specified behaviors. Prior to opening a tunnel stream, you must implement the
StatusEventCallback, which is described in Section 6.7.4.

6.7.2.1

ReactorChannel.openTunnelStream Method

METHOD NAME
openTunnelStream

DESCRIPTION
Begins the establishment of a tunnel stream. The TunnelStream is returned via the
TunnelStreamStatusEventCallback as specified on the
TunnelStreamOpenOptions. For more details, refer to Section 6.7.2.2.

Table 57: ReactorChannel.openTunnelStream Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.2.2

Reactor Detailed View

TunnelStreamOpenOptions

The TunnelStreamOpenOptions contain event handler associations and options for use in creating a tunnel stream.
CLASS MEMBER

DESCRIPTION

domainType

Indicates the domain for which the tunnel stream is established. Set this to the
domain specified on the service on which the Transport API opens the tunnel stream.

streamId

Indicates the stream ID to use for the tunnel stream. Though substreams will flow
within this stream ID, each will have their own independent stream ID.
For example, a tunnel stream can have an ID of 10. If a substream is opened to
retrieve TRI data, the substream can have a stream ID of 5, though it is encapsulated
in the tunnel stream whose stream ID is 10.

serviceId

Indicates the service ID of the service on which you open the tunnel stream.

userSpecObject

Indicates a user-specified object passed in via these options and then associated
with the TunnelStream.

statusEventCallback

Specifies an instance of the callback for TunnelStreamStatusEvents, which
provides the TunnelStream on initial connection, and after the tunnel stream is
established, communicates the tunnel stream’s state information.
For further details, refer to Section 6.7.4.

queueMsgCallback

defaultMsgCallback

Specifies the instance of the callback used to handle Queue Messages received on
this TunnelStream.
•

For details on the TunnelStreamQueueMsgCallback, refer to Section 6.7.4.

•

For details on various Queue Messages, refer to Section 7.6.

Specifies the instance of the callback that handles all other content received on this
TunnelStream.

For further details, refer to Section 6.7.4.
name

Specifies the tunnel stream name. name cannot be longer than 255 characters.

responseTimeout

Sets the duration (in seconds) to wait for a provider to respond to a tunnel stream
open request. If the provider does not respond in time, a TunnelStreamStatusEvent
is sent to the application to indicate that the tunnel stream was not opened.

guaranteedOutputBuffers

Sets the number of guaranteed output buffers available for the tunnel stream.

authLoginRequest

Specifies the login request to send if ClassOfService.authentication.type is set
to OMM_LOGIN. If absent, the API uses the login request provided on the
ConsumerRole.rdmLoginRequest.

classOfService

The class of service of the tunnel stream to be opened.
For further details on ClassOfService, refer to Section 6.7.3.

Table 58: TunnelStreamOpenOptions

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.3

Reactor Detailed View

Negotiating Stream Behaviors: Class of Service

ClassOfService is used to negotiate TunnelStream behaviors. Negotiated behaviors are divided into five categories:

common, authentication, flow control, data integrity, and guarantee.
•

When an OMM consumer application calls ReactorChannel.openTunnelStream, it sets the
TunnelStreamOpenOptions.classOfService members to manage and control tunnel stream behaviors. The
consumer passes these settings to the connected OMM provider.

•

When the OMM provider application receives an TunnelStreamRequestEvent, the provider calls
TunnelStreamRequestEvent.classOfService to retrieve the behaviors requested by the consumer.

After tunnel stream negotiation is complete, the provider and consumer each receive a TunnelStreamStatusEvent where
each can view the negotiated behaviors on the TunnelStream object.
Note: Do not modify the ClassOfService member of the TunnelStream.
The enumerations given for members described in this section can be found in
com.thomsonreuters.upa.rdm.ClassesOfService.

6.7.3.1

ClassOfService Common Member

Common elements describe options related to the exchange of messages, such as the maximum message size and desired
exchange protocol.
MEMBER
maxFragmentSize

DEFAULT
6144

RANGE/ ENUMERATIONS
1 – 2,147,483,647

DESCRIPTION
The maximum size of message
fragments exchanged on the
tunnel stream.
This value is set only by providers
when accepting a tunnel stream.

maxMsgSize

614400

1 – 2,147,483,647

The maximum size of messages
exchanged on the tunnel stream.
This value is set only by providers
when accepting a tunnel stream.

protocolMajorVersion

Codec.majorVersion()

0 – 255

The major version of the protocol
specified by protocolType.

protocolMinorVersion

Codec.minorVersion()

0 – 255

The minor version of the protocol
specified by protocolType.

protocolType

Codec.protocolType()

0 – 255

Identifies the protocol of the
messages exchanged on the
tunnel stream.

Table 59: ClassOfService.common Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.3.2

Reactor Detailed View

ClassOfService Authentication Member

The authentication member contains options to authenticate a consumer to the corresponding provider.
MEMBER

DEFAULT

type

RANGE/ ENUMERATIONS

ClassesOfService.

AuthenticationTypes.

NOT_REQUIRED

NOT_REQUIRED == 0,
ClassesOfService.
AuthenticationTypes.

DESCRIPTION
Indicates the type of
authentication, if any, to
perform on the tunnel stream.
For further details on
authentication, refer to Section
6.7.1.

OMM_LOGIN == 1
Table 60: ClassOfService.authentication Members

6.7.3.3

ClassOfService Flow Control Members

The flow control member contains options related to flow control, such as the type and the allowed window of outstanding
data.
MEMBER
type

DEFAULT

RANGE/ ENUMERATIONS

ClassesOfService.

FlowControlTypes.

NONE

NONE == 0,

DESCRIPTION
Indicates the type of flow control (if
any) to apply to the tunnel stream.

ClassesOfService.
FlowControlTypes.
BIDIRECTIONAL == 1
recvWindowSize

-1

0 – 2,147,483,647

Sets the amount of data (in bytes) that
the remote peer can send to the
application over a reliable tunnel
stream.
If type is set to NONE, this parameter
has no effect.
-1 indicates that the application wants
to use the default value for the
negotiated flow control type. In this
case, if type is set to
BIDIRECTIONAL, the default is
12288.

Table 61: ClassOfService.flowControl Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

MEMBER

DEFAULT

sendWindowSize None

RANGE/ ENUMERATIONS
0 – 2,147,483,647

Reactor Detailed View

DESCRIPTION
Indicates the amount of data (in bytes)
the application can send to the remote
peer on a reliable tunnel stream.
This value is provided on the
TunnelStream object and does not

need to be set when opening or
accepting a tunnel stream.
This value is retrieved from the remote
end and is informational, as flow
control is performed by the API. When
room is available in the window, the
API transmits more content as
submitted by the application.
If type is set to NONE, this parameter
has no effect.
Table 61: ClassOfService.flowControl Members (Continued)

6.7.3.4

ClassOfService Data Integrity Member

The data integrity member contains options related to the reliability of content exchanged over the tunnel stream.
MEMBER
type

DEFAULT

RANGE

ClassesOfService.

DataIntegrityTypes.

BEST_EFFORT

BEST_EFFORT == 0,
ClassesOfService.
DataIntegrityTypes.
RELIABLE == 1

DESCRIPTION
Sets the level of reliability for
message transmission on the
tunnel stream. If set to
RELIABLE, data is
retransmitted as needed over
the tunnel stream to ensure
that all messages are delivered
in the correct order.
Note: At this time, RELIABLE
is the only supported option.

Table 62: ClassOfService.dataIntegrity Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.3.5

Reactor Detailed View

ClassOfService Guarantee Members

The guarantee member contains options related to the guarantee of content submitted over the tunnel stream.
OMM Consumer applications performing Queue Messaging to a Queue Provider should set the
ClassOfService.guarantee.type to ClassesOfService.GuaranteeTypes.PERSISTENT_QUEUE.
MEMBER
type

DEFAULT

RANGE

ClassesOfService.

GuaranteeTypes.

NONE

NONE == 0,
ClassesOfService.
GuaranteeTypes.
PERSISTENT_QUEUE == 1

persistLocally

true

false, true

DESCRIPTION
Indicates the level of guarantee that will be
performed on this stream.
PERSISTENT_QUEUE is not supported for
provider applications.
Note: If type is set to
PERSISTENT_QUEUE for a consumer
application, the data integrity type must also
be set to RELIABLE and the flow control
type to BIDIRECTIONAL.
Indicates whether messages are persisted
locally on the tunnel stream.
When type is NONE, this member has no
effect.

persistenceFilePath NULL

n/a

File path where files containing persistent
messages may be stored.
If set to NULL, the current working directory
is used.
When type is NONE, or when
persistLocally is set to false, this member
has no effect.

Table 63: ClassOfService.guarantee Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.4

Tunnel Stream Callback Methods and Event Types

6.7.4.1

Tunnel Stream Callback Methods

Reactor Detailed View

The TunnelStream delivers events via the following user-implemented callback methods. These callback methods return
event objects as defined in Section 6.7.4.2.
CALLBACK METHOD
statusEventCallback

DESCRIPTION
Communicates status information about the tunnel stream. Additionally, this
callback delivers the TunnelStream object after the enhanced private stream is
established.
This callback provides a TunnelStreamStatusEvent to the application. Details
about this event are available in Section 6.7.4.2.

defaultMsgCallback

Similar to the ReactorChannel.defaultMsgCallback, content received by the
tunnel stream are returned via this callback if it is not handled by a more specific
content handler, such as the queueMsgCallback.
This callback provides a TunnelStreamMsgEvent to the application. Details about
this event are available in Section 6.7.4.2.

queueMsgCallback

Any queue messages are delivered via this callback and presented to the user in
their native queue message formats. If unspecified, queue messages are
delivered via the defaultMsgCallback; however they are not presented in a
queue message format.
This callback provides a TunnelStreamQueueMsgEvent to the application. Details
about this event are available in Section 6.7.4.2.

Table 64: Tunnel Stream Callback Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.4.2

Reactor Detailed View

Tunnel Stream Callback Event Types

Various tunnel stream callbacks return their information via specific event objects. The following table defines these events.
EVENT
TunnelStreamStatusEvent

EVENT DESCRIPTION

CLASS MEMBER

This event presents the
tunnelStream
tunnel stream and its status.

state

CLASS MEMBER DESCRIPTION
Returns the TunnelStream
associated with this event. When the
TunnelStream is initially opened, the
initial instance of the TunnelStream
is made available.
Indicates status information
associated with the TunnelStream.
For example:

TunnelStreamMsgEvent

This event presents content
received on the
TunnelStream. If a more
specific handler (i.e.,
queueMsgCallback) is also
configured, messages of
that type will go to their
specific handler.

•

A state of OPEN and OK
indicates that the tunnel stream is
established and content should be
flowing as expected.

•

A state of CLOSED_RECOVER
or SUSPECT indicates that the
connection or tunnel stream might
be lost. However, if performing
guaranteed messaging, content
might be persisted by the reactor
and communicated upon recovery
of the tunnel stream.

authInfo

(Consumers only) Provides
information about a received
authentication response.

tunnelStream

Returns the TunnelStream
associated with this event.

msg

Contains the content being presented
to the user.
•

If content is OMM, it is partially
decoded for user convinenence.

•

If content is opaque, a buffer
housing the contents is presented
to the user via this object.

transportBuffer

The transport buffer associated with
this event.

containerType

The container type associated with
this event's transport buffer.

Table 65: Tunnel Stream Callback Event Types

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

EVENT
TunnelStreamQueueMsgEvent

EVENT DESCRIPTION
This event presents any
queue message content
received on the
TunnelStream.

CLASS MEMBER

Reactor Detailed View

CLASS MEMBER DESCRIPTION

tunnelStream

Returns the TunnelStream
associated with this event.

queueMsg

Contains the content being presented
to the user, presented as a queue
message object.

Table 65: Tunnel Stream Callback Event Types (Continued)

6.7.5

Code Sample: Opening and Managing a Tunnel Stream

The following code sample is a basic example of opening a tunnel stream. The example assumes that a Reactor and
ReactorChannel are already open and properly established.

// Basic sample for event handlers
class Sample implements StatusEventCallback, TunnelStreamQueueMsgCallback,
TunnelStreamDefaultMsgCallback
{
ReactorErrorInfo _errorInfo;
// StatusEventCallback
public int statusEventCallback(TunnelStreamStatusEvent event)
{
System.out.println(“Status of Tunnel Stream (“ + event.tunnelStream().streamId() + “) is “ +
event.state());
Return ReactorCallbackReturnCodes.SUCCESS;
}
// TunnelStreamDefaultMsgCallback
public int TunnelStreamDefaultMsgCallback(TunnelStreamMsgEvent event)
{
System.out.println(“Received content on Tunnel Stream (“ + event.tunnelStream().streamId() +
“)”);
Return ReactorCallbackReturnCodes.SUCCESS;
}
// TunnelStreamQueueMsgCallback
public int tunnelStreamQueueMsgCallback(TunnelStreamQueueMsgEvent event)
{
System.out.println(“Received Queue Message on Tunnel Stream (“ +
event.tunnelStream().streamId() + “)”);
Return ReactorCallbackReturnCodes.SUCCESS;
}
}
int openTunnelStream()
{
TunnelStreamOpenOptions _openOptions = RectorFactory.createTunnelStreamOpenOptions();

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

Reactor Detailed View

// populate the options and enable guaranteed delivery for communication with a Queue Provider
_openOptions.streamId(TUNNEL_STREAM_ID);
_openOptions.domainType(DomainTypes.QUEUE_MESSAGING);
_openOptions.serviceId(QUEUE_MESSAGING_SERVICE_ID);
// specify the event handlers
_openOptions.statusEventCallback(this);
_openOptions.TunnelStreamDefaultMsgCallback(this);
_openOptions.queueMsgCallback(this);
if ((reactorChannel.openTunnelStream(_openOptions, _errorInfo)) != ReactorReturnCodes.SUCCESS)
{
System.out.println(“openTunnelStream failed!”);
return ReactorReturnCodes.FAILURE;
}
System.out.println(“openTunnelStream succeeded!”);
return ReactorReturnCodes.SUCCESS;
}

Code Example 14: Opening a Tunnel Stream

6.7.6

Accepting Tunnel Streams

OMM provider applications can accept tunnel streams provided on an ReactorChannel (enabled by specifying a
tunnelStreamListenerCallback on the ProviderRole).
When a consumer opens a tunnel stream, the tunnelStreamListenerCallback receives an TunnelStreamRequestEvent. At
this point, the provider should call TunnelStreamRequestEvent.classOfService to retrieve the ClassOfService requested
by the tunnel stream and ensure that the parameters indicated by the members of that class of service match what the
provider allows. The provider can also check the TunnelStreamRequestEvent.classOfServiceFilter to determine which
behaviors the consumer supports. For more information on this filter, refer to Section 6.7.6.1.
•

To accept a tunnel stream, the provider must call ReactorChannel.acceptTunnelStream with the given
TunnelStreamRequestEvent. Further events regarding the accepted stream are provided in the specified
TunnelStreamAcceptOptions.statusEventCallback.

•

To reject a tunnel stream, the provider calls ReactorChannel.rejectTunnelStream with the given
TunnelStreamRequestEvent. No further events are received for that tunnel stream.

Queue messaging (a ClassOfService.guarantee.type setting of PERSISTENT_QUEUE) is not supported for provider
applications.
The API automatically rejects tunnel streams that contain invalid information. When this happens, the provider application
receives warnings via a ReactorChannelEvent. The type will be set to ReactorChannelEventTypes WARNING and the
ReactorErrorInfo in the event will contain text describing the reason for the rejection.
Warning! Ensure that the provider application calls ReactorChannel.acceptTunnelStream or
ReactorChannel.rejectTunnelStream before returning from the tunnelStreamListenerCallback. If not, the
provider application will receive a warning via an ReactorChannelEvent similar to the above, and the stream will be
automatically rejected.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.6.1

Reactor Detailed View

Reactor Tunnel Stream Listener Callback

OMM providers that want to handle tunnel streams from connected consumers can specify a
TunnelStreamListenerCallback. This callback informs the provider application of any consumer tunnel stream requests.
The provider can specify this callback function on the ProviderRole, which has the following signature:

listenerCallback(TunnelStreamRequestEvent event);

For more information on the ProviderRole, refer to Section 6.3.3.
A TunnelStreamRequestEvent is returned to the application via the TunnelStreamListenerCallback.
MEMBER

DESCRIPTION

reactorChannel

Specifies the ReactorChannel on which the event was received.

streamId

Specifies the stream ID of the requested tunnel stream.

domainType

Specifies the domain type of the requested tunnel stream.

serviceId

Specifies the service ID of the requested tunnel stream.

name

Specifies the name of the requested tunnel stream.

classOfServiceFilter

Sets a filter that indicates which ClassOfService members are present. The
provider can use this filter to determine whether behaviors are supported by the
consumer and if needed, reject the tunnel stream before calling
TunnelStreamRequestEvent.classOfService to get the full ClassOfService.
For enumerations of the flags present in this filter, refer to
com.thomsonreuters.upa.rdm.ClassesOfService.FilterFlags.

classOfService

Specifies the ClassOfService for the requested tunnel stream.

Table 66: TunnelStreamRequestEvent Members

6.7.6.2

ReactorChannel.acceptTunnelStream Method

METHOD NAME

DESCRIPTION

ReactorChannel.acceptTunnelStream Accepts a tunnel stream requested by a consumer. The TunnelStream is returned in
the TunnelStreamStatusEventCallback specified on the
TunnelStreamAcceptOptions.
For more information, refer to Section 6.7.6.3.
Table 67: ReactorChannel.acceptTunnelStream Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.6.3

Reactor Detailed View

TunnelStreamAcceptOptions

OPTION
statusEventCallback

DESCRIPTION
Specifies the instance of the callback for TunnelStreamStatusEvents, which
provides the TunnelStream on initial connection and then communicates state
information about the tunnel afterwards.
For details on the TunnelStreamStatusEventCallback, refer to Section 6.7.4.1.

defaultMsgCallback

Specifies the instance of the callback used to handle all other content received on
this TunnelStream.
For details on TunnelStreamdefaultMsgCallback, refer to Section 6.7.4.1.

userSpecObject

Specifies a user-defined object passed in via these options and then associated with
the TunnelStream.

classOfService

Specifies an ClassOfService with members indicating behaviors that the application
wants to apply to the TunnelStream.
For more information on class of service, refer to Section 6.7.3.

guaranteedOutputBuffers

Sets the number of pooled buffers available to the application when writing content to
TunnelStream.

Table 68: TunnelStreamAcceptOptions Options

6.7.6.4

ReactorChannel.rejectTunnelStream

METHOD NAME
ReactorChannel.rejectTunnelStream

DESCRIPTION
Rejects a tunnel stream requested by a consumer. No further events will be received
for this tunnel stream.
For more information, refer to Section 6.7.6.5.

Table 69: ReactorChannel.rejectTunnelStream Method

6.7.6.5

TunnelStreamRejectOptions

OPTION

DESCRIPTION

state

A State to send to the consumer. The application can use the state.streamState,
state.dataState, and state.text to indicate the nature of the rejection.

expectedClassOfService

An optional ClassOfService to send to the consumer. If rejecting the stream due to
a problem with the ClassOfService parameters from the
TunnelStreamRequestEvent, the provider application should populate this with the
associated parameters.

Table 70: TunnelStreamRejectOptions Options

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.6.6

Reactor Detailed View

Accepting a Tunnel Stream Code Sample

The following code illustrates how to accept a tunnel stream requested by a consumer. The example presumes that a Reactor
and ReactorChannel are already open and properly established.

public int listenerCallback(TunnelStreamRequestEvent event)
{
int ret;
TunnelStreamAcceptOptions acceptOpts = ReactorFactory.createTunnelStreamAcceptOptions();
if (isFilterValid(event.classOfServiceFilter()) &&
isClassOfServiceValid(event.classOfService())
{
acceptOpts.clear();
// set class of service to what this provider supports
acceptOpts.classOfService().dataIntegrity().type(ClassesOfService.DataIntegrityTypes.RELIABLE
);
acceptOpts.classOfService().flowControl().type((ClassesOfService.FlowControlTypes.
BIDIRECTIONAL));
// Set Authentication to match consumer. This provider will perform OMM Login authentication if
// requested.
acceptOpts.classOfService().authentication().type(event.classOfService().authentication().
type());
acceptOpts.statusEventCallback(this);
acceptOpts.defaultMsgCallback(this);
if ((ret = event.reactorChannel().acceptTunnelStream(event, acceptOpts, event.errorInfo()))
< ReactorReturnCodes.SUCCESS)
{
System.out.println("acceptTunnelStream() failed with return code: " + ret + " <" +
event.errorInfo().error().text() + ">");
}
}
return ReactorCallbackReturnCodes.SUCCESS
}

Code Example 15: Accepting a Tunnel Stream Code Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.6.7

Reactor Detailed View

Rejecting a Tunnel Stream Code Sample

The following code illustrates how to reject a tunnel stream requested by a consumer. The example assumes that a Reactor
and ReactorChannel are already open and properly established.

public int listenerCallback(TunnelStreamRequestEvent event)
{
int ret;
/* Now presuming that the application wishes to reject the tunnel stream because the requested
* class of service is invalid. */
if (!isFilterValid(event.classOfServiceFilter()) || !isClassOfServiceValid(event.classOfService())
{
/* Set what the class of service is expected to be. */
ClassOfService expectedCos = ReactorFactory.createClassOfService();
expectedCos.clear()
expectedCos.authentication().type(ClassesOfService.AuthenticationTypes.OMM_LOGIN);
expectedCos.flowControl().type(ClassesOfService.FlowControlTypes.BIDIRECTIONAL);
expectedCos.dataIntegrity().type(ClassesOfService.DataIntegrityTypes.RELIABLE);
/* ... (set additional members, based on what is desired by the provider) */
TunnelStreamRejectOptions rejectOpts = ReactorFactory.createTunnelStreamRejectOptions();
rejectOpts.clear();
rejectOpts.state().streamState(StreamStates.CLOSED);
rejectOpts.state().dataState(DataStates.SUSPECT);
rejectOpts.state().code(StateCodes.NONE);
rejectOpts.state().text().data("Unsupported TunnelStream class of service");
rejectOpts.expectedClassOfService(expectedCos);
if ((ret = event.reactorChannel().rejectTunnelStream(event, rejectOpts, event.errorInfo())) <
ReactorReturnCodes.SUCCESS)
{
System.out.println("rejectTunnelStream() failed with return code: " + ret + " <" +
event.errorInfo().error().text() + ">");
}
}
return ReactorCallbackReturnCodes.SUCCESS
}

Code Example 16: Rejecting a Tunnel Stream Code Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.7

Reactor Detailed View

Receiving Content on a TunnelStream

Invoking the ReactorChannel.dispatch method reads and processes inbound content, where any information received on
this TunnelStream will be delivered to the application via the tunnel stream callback methods specified via openTunnelStream
or ReactorChannel.acceptTunnelStream.
Dispatching this content works in the same manner as dispatching any other content on the reactor.
•

Tunnel stream callback methods are described in Section 6.7.4.

•

Tunnel stream callback methods deliver the events described in Section 6.7.4.2.

6.7.8

Sending Content on a TunnelStream

When you send content on a TunnelStream: get a buffer from the TunnelStream, encode your content into the buffer, and
then use the TunnelStream.submit method to push the content out over the TunnelStream. By obtaining a buffer from the
TunnelStream, the reactor can then properly handle any negotiated behaviors, making this functionality nearly transparent.

6.7.8.1

Tunnel Stream Buffer Methods

METHOD NAME

DESCRIPTION

getBuffer

Obtains a buffer from the TunnelStream. To properly enforce negotiated behaviors
on content in the buffer, the Transport API associates the buffer with the tunnel
stream from which it is obtained.

releaseBuffer

Releases a buffer back to the TunnelStream from which it came. You should release
any buffer that you do not submit. Releasing the buffer ensures it is properly recycled
and can be reused.
Note: If you submit a buffer properly, you do not need to release it, because the
submit method automatically releases it after sending the content on the
TunnelStream.

Table 71: Tunnel Stream Buffer Methods

6.7.8.2

Tunnel Stream Submit

The submit method is used to write content to the TunnelStream. This method also enforces any specified behaviors on
submitted content (e.g., if guaranteed messaging is specified, this content follows all configured persistence options).
METHOD NAME
submit

DESCRIPTION
Use the submit method to pass in opaque or RDM Message content (including
Queue Messages) to be processed and sent over the TunnelStream.
This method has additional options that can be specified via
TunnelStreamSubmitOptions (refer to Section 6.7.8.3).

Table 72: Tunnel Stream Submit Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.8.3

Reactor Detailed View

TunnelStream.submit Option

When calling TunnelStream.submit with a buffer, you can use TunnelStreamSubmitOptions to provide the containerType
option.
MEMBER
containerType

DESCRIPTION
Specifies the type of data in the buffer being submitted.
For example:
•

If the submitted buffer contains a Msg, set containerType DataTypes.MSG.

•

If sending non-RWF data, set containerType to a non-RWF type, such as
DataTypes.OPAQUE.

For more information on possible container types, refer to the Transport API Java
Edition Developers Guide.
Table 73: Members

6.7.8.4

Submitting Content on a Tunnel Stream Code Sample

The following code sample is a basic example of writing opaque content to a tunnel stream. You can combine this example
with the QueueData message samples in subsequent chapters to send content to a Queue Provider.

int submitMessage()
{
TunnelStreamSubmitOptions _submitOpts = ReactorFactory.createTunnelStreamSubmitOptions();
// gets a buffer of 50 bytes to put content into.
TransportBuffer _buffer = tunnelStream.getBuffer(50, _errorInfo);
// put generic content into the buffer
_buffer.data().put(“Hello World!”);
_submitOpts.containerType(DataTypes.OPAQUE);
if ((tunnelStream.submit(_buffer, _submitOpts, _errorInfo)) != ReactorReturnCodes.SUCCESS)
{
System.out.println(“Content submission failed!”);
// Because submission failed, we need to return the buffer to the tunnel stream
tunnelStream.releaseBuffer(_buffer, _errorInfo);
return ReactorReturnCodes.FAILURE;
}
System.out.println(“Content submission succeeded!”);
// Thanks to successful submission, we do not need to release the buffer because the Reactor will.
return ReactorReturnCodes.SUCCESS;
}

Code Example 17: Submitting Content on a Tunnel Stream

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.7.9

Reactor Detailed View

Closing a Tunnel Stream

When an application has completed its use of a TunnelStream, close it using the close method.

6.7.9.1

Tunnel Stream Close
METHOD NAME

DESCRIPTION
Closes a tunnel stream. After you close a tunnel stream, the Transport API cleans up
any data that was stored for guaranteed messaging or reliable delivery.
The finalStatusEvent argument indicates that the application wants to receive a
final TunnelStreamStatusEvent whenever the tunnel stream closes. If this is set to
true, the tunnel stream will be cleaned up after the application receives the final
TunnelStreamStatusEvent event.

Table 74: Tunnel Closure Method

6.7.9.2

Closing a Tunnel Stream Sample

The following code sample illustrates how to close a tunnel stream.

int closeTunnelStream()
{
if ((tunnelStream.close(true,_errorInfo)) != ReactorReturnCodes.SUCCESS)
{
System.out.println(“Closing tunnel stream failed!”);
return ReactorReturnCodes.FAILURE;
}
System.out.println(“Tunnel Stream closed successfully.”);
return ReactorReturnCodes.SUCCESS;
}

Code Example 18: Closing a Tunnel Stream

6.8

Reactor Utility Methods

The Transport API Reactor provides several additional utility functions. These functions can be used to query more detailed
information for a specific connection or change certain ReactorChannel parameters during run-time. These functions are
described in the following Section 6.8.1 - Section 6.8.3.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 6

6.8.1

Reactor Detailed View

General Reactor Utility Methods

METHOD NAME
info

DESCRIPTION
Allows the application to query ReactorChannel negotiated parameters and settings and
retrieve all current settings. This includes maxFragmentSize and negotiated compression
information as well as many other values. For a full list of available settings, refer to the
ReactorChannelInfo object defined in Section 6.8.2.
This method calls the Transport API Channel.info method which has its use and return
values described in the Transport API Java Edition Developers Guide.
Allows the application to change various settings associated with the ReactorChannel. The
available options are defined in Section 6.8.3.

ioctl

This method calls the Channel.ioctl method which has its use and return values described
in the Transport API Java Edition Developers Guide.
Table 75: Reactor Utility Methods

6.8.2

ReactorChannelInfo Class Members

The following table describes the values available to the user through using the ReactorChannel.info method. This
information is returned as part of the ReactorChannelInfo object.
CLASS MEMBER
channelInfo

DESCRIPTION
Returns the underlying Channel information. This includes maxFragmentSize, number of
output buffers, compression information, and more.
The ChannelInfo method object is fully described in the Transport API Java Edition
Developers Guide.

Table 76: ReactorChannelInfo Class Members

6.8.3

ReactorChannel.ioctl Option Values

There are currently no Reactor or ReactorChannel specific codes for use with the ReactorChannel.ioctl. Reactor-specific
codes may be added in the future. The application can still use any of the codes allowed with Channel.ioctl, which are
documented in the Transport API Java Edition Developers Guide.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

Administration Domain Models Detailed View

Chapter 7 Administration Domain Models Detailed View
7.1

Concepts

Administration Domain Model Representations are RDM-specific representations of OMM administrative domain models.
This Value Added Component contains classes and interfaces that represent messages within the Login, Source Directory,
and Dictionary domains (discussed in Table 77). This component also handles all encoding and decoding functionality for
these domain models, so the application needs only to manipulate the message’s object members to send or receive content.
Such functionality significantly reduces the amount of code an application needs to interact with OMM devices (i.e., TREP
infrastructure), and also ensures that encoding/decoding for these domain models follow OMM-specified formatting rules.
Applications can use this Value Added Component directly to help with encoding, decoding, and representation of these
domain models.
Where possible, the members of an Administration Domain Model Representation are represented in the class with the same
DataType that is specified for the element by the Domain Model. In cases where multiple elements are part of a more complex
container such as a Map or ElementList, the elements are represented with Java JDK collections.
The Transport API Java Edition RDM Usage Guide defines and describes all domain-specific behaviors, usage, and details.
DOMAIN
Dictionary

PURPOSE
Provides dictionaries that may be needed when decoding data. Though use of the Dictionary
domain is optional, Thomson Reuters recommends that provider applications support the
domain’s use.
The Dictionary domain is considered an administrative domain. Many Thomson Reuters
components require this content and expect it to follow the domain model definition.
For further details refer to Section 7.5.

Authenticates users and advertises/requests features that are not specific to a particular
domain. Use of and support for this domain is required for all OMM applications.
Login is considered an administrative domain. Many Thomson Reuters components require
this content and expect it to conform to the domain model definition.
For further details refer to Section 7.3.

Source Directory

Advertises information about available services and their state, QoS, and capabilities. This
domain also conveys any group status and group merge information.
Interactive and Non-Interactive OMM Provider applications require support for this domain.
Thomson Reuters strongly recommends that OMM Consumers request this domain.
Source Directory is considered an administrative domain, and many Thomson Reuters
components expect this content and require it to conform to the domain model definition.
For further details, refer to Section 7.4.

Table 77: Domains Representations in the Administration Domain Model Value Added Component

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.2

Administration Domain Models Detailed View

Message Base

MsgBase is the root interface for all Administration Domain Model Representation interfaces. It provides methods for stream

identification as well as methods that are common for all domain representations.

7.2.1

Message Base Members

The MsgBase interface includes the following members and methods:
MEMBER
streamId

DESCRIPTION
Required. A unique signed-integer identifier associated with all messages flowing in the
stream.
•

Positive values indicate a consumer-instantiated stream, typically via a request message.

•

Negative values indicate a provider-instantiated stream, often associated with NonInteractive Providers.

streamId is required on all messages.

Table 78: MsgBase Members

7.2.2

Message Base Method
METHOD

clear()

DESCRIPTION
Clears the object for reuse.

Table 79: MsgBase Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.2.3

Administration Domain Models Detailed View

RDM Message Types

The following table provides a reference mapping between the administrative domain type and the domain representations
provided in this component.

DOMAIN TYPE

DOMAIN REPRESENTATIONS MESSAGE
TYPE

DOMAIN REPRESENTATION
INTERFACE

LoginMsgType.REQUEST

LoginRequest

LoginMsgType.REFRESH

LoginRefresh

Refer to Section 7.3

LoginMsgType.STATUS

LoginStatus

LoginMsgType.CLOSE

LoginClose

LoginMsgType.CONSUMER_CONNECTION_STATUS LoginConsumerConnectionStatus
SOURCE
(DirectoryMsg)

DirectoryMsgType.REQUEST

DirectoryRequest

DirectoryMsgType.REFRESH

DirectoryRefresh

Refer to Section 7.4

DirectoryMsgType.UPDATE

DirectoryUpdate

DirectoryMsgType.STATUS

DirectoryStatus

DirectoryMsgType.CLOSE

DirectoryClose

DirectoryMsgType.CONSUMER_STATUS

DirectoryConsumerStatus

DICTIONARY
(DictionaryMsg)

DictionaryMsgType.REQUEST

DictionaryRequest

DictionaryMsgType.REFRESH

DictionaryRefresh

Refer to Section 7.5

DictionaryMsgType.STATUS

DictionaryStatus

DictionaryMsgType.CLOSE

DictionaryClose

Table 80: Domain Representations Message Types

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3

Administration Domain Models Detailed View

RDM Login Domain

The Login domain registers (or authenticates) a user with the system, after which the user can request1, post2, or provide3
OMM content. A Login request may also be used to authenticate a user with the system.

•
•

A consumer application must log into the system before it can request or post content.
A non-interactive provider (NIP) application must log into the system before providing content. An interactive provider
application must handle login requests and provide login response messages, possibly using DACS to authenticate users.

Section 7.3.1 - Section 7.3.11 detail the layout and use of each message interface in the Login portion of the Administration
Domain Message Component.

7.3.1

A Login Request message is encoded and sent by OMM consumer and OMM non-interactive provider applications. This
message registers a user with the system. After receiving a successful login response, applications can then begin consuming
or providing additional content. An OMM provider can use the login request information to authenticate users with DACS.
The LoginRequest represents all members of a login request message and allows for simplified use in OMM applications that
leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.3.1.1

MEMBER
attrib

DESCRIPTION
Optional. Contains additional login attribute information.
If present, a flags value of LoginRequestFlags.HAS_ATTRIB should be specified.
For further details, refer to Section 7.3.8.1.

authenticationExtended

Optional. If present, a flags value of RDM_LG_RQF_HAS_AUTHN_EXTENDED
should be specified.
When populated, authenticationExtended contains additional content that will be
passed to the token authenticator as an additional means to verifying a user's identity.

downloadConnectionConfig

Optional. If present, a flags value of
LoginRequestFlags.HAS_DOWNLOAD_CONN_CONFIG should be specified. If
absent, a default value of 0 is assumed.
Enabling this option allows the application to download information about other
providers on the network. You can use such downloaded information to load balance
connections across multiple providers.

flags

•

1: Indicates that the user wants to download connection configuration information.

•

0: Indicates that the user does not want to download connection information.

Required. Indicate presence of optional login request members. For details, refer to
Section 7.3.1.2.

Table 81: LoginRequest Members

1. Consumer applications can request content after logging into the system.
2. Consumer applications can post content (similar to contributions or unmanaged publications) after logging into the system.
3. Non-interactive provider applications.
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

MEMBER
instanceId

Administration Domain Models Detailed View

DESCRIPTION
Optional. If present, a flags value of LoginRequestFlags.HAS_INSTANCE_ID
should be specified.
You can use the instanceId to differentiate applications running on the same
machine. However, because instanceId is set by the user logging into the system, it
does not guarantee uniqueness across different applications on the same machine.

password

Optional. If present, a flags value of LoginRequestFlags.HAS_PASSWORD should
be specified. Sets the password for logging into the system.

rdmMsgBase

Required. Specifies the login message type (i.e., LoginMsgType.REQUEST for the
login request).

role

Optional. If present, a flags value of LoginRequestFlags.HAS_ROLE should be
specified. If absent, a default value of Login.Role.CONS is assumed.
Indicates the role of the application logging onto the system.

userName

•

0: Login.Role.CONS, indicates application is a consumer.

•

1: Login.Role.PROV, indicates application is a provider.

Required. Populate this member with the username, email address, or user token
based on the userNameType specification.
If you initialize LoginRequest using initDefaultRequest, it uses the name of the
user currently logged into the system on which the application runs.

userNameType

Optional. If present, a flags value of LoginRequestFlags.HAS_USERNAME_TYPE
should be specified. If absent, a default value of USER_NAME is assumed.
Possible values:
•

•

A type of Login.UserIdTypes.NAME typically corresponds to a DACS user name and
can to authenticate and permission a user.
Login.UserIdTypes.TOKEN is specified when using the AAA (‘triple A’) API. The user
token is retrieved from the Authentication Manager application. To validate users, a
provider application passes this user token to the AAA Gateway. This type of token
periodically changes: when it changes, an application can send a login reissue to pass
information upstream. For more information, refer to documentation specific to the
AAAAPI.
Login.UserIdTypes.AUTHN_TOKEN is specified when using TREP Authentication.
The authentication token should be specified in the userName member. This type of
token can periodically change: when it changes, an application can send a login
reissue to pass information upstream. For more information, refer to the TREP
Authentication User Manual.a
Table 81: LoginRequest Members (Continued)
a. For further details on TREP Authentication, refer to the TREP Authentication User Manual, accessible on Thomson Reuters MyAccount in the DACS
product documentation set.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.1.2

Administration Domain Models Detailed View

FLAG ENUMERATION

MEANING

LoginRequestFlags.HAS_ATTRIB

Indicates the presence of attrib.

LoginRequestFlags.HAS_AUTHN_EXTENDED

Indicates the presence of authenticationExtended.

LoginRequestFlags.HAS_DOWNLOAD_CONN_CONFIG

Indicates the presence of downloadConnectionConfig. If
absent, a value of 0 should be assumed.

LoginRequestFlags.HAS_INSTANCE_ID

Indicates the presence of instanceId.

LoginRequestFlags.HAS_PASSWORD

Indicates the presence of password.

LoginRequestFlags.HAS_ROLE

Indicates the presence of role. If absent, a role of
Login.Role.CONS is assumed.

LoginRequestFlags.HAS_USERNAME_TYPE

Indicates the presence of userNameType. If not present, a
userNameType of Login.UserIdTypes.NAME should be
assumed.

LoginRequestFlags.PAUSE_ALL

Indicates that the consumer wants to pause all streams
associated with the logged in user. For more information on
pause and resume behavior, refer to the Transport API Java
Edition Developers Guide.

LoginRequestFlags.NO_REFRESH

Indicates that the consumer application does not require a
login refresh for this request. This typically occurs when
resuming a stream or changing a AAA token. In some
instances, a provider can still deliver a refresh message,
however if such a message is not explicitly asked for by the
consumer, it is considered unsolicited.

Table 82: LoginRequest Flags

7.3.1.3

METHOD NAME
initDefaultRequest

DESCRIPTION
Clears a LoginRequest object and populates userName, position, applicationId,
and applicationName with default values.

Table 83: LoginRequest Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.2

Administration Domain Models Detailed View

A Login Refresh message is encoded and sent by an OMM interactive provider application and responds to a Login Request
message. A login refresh message indicates that the user’s Login is accepted. An OMM Provider can use information from the
login request to authenticate users with DACS. After authentication, a refresh message is sent to convey that the login was
accepted. If the login is rejected, a login status message should be sent as described in Section 7.3.3.
The LoginRefresh represents all members of a login refresh message and allows for simplified use in OMM applications that
leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.3.2.1

MEMBER
attrib

DESCRIPTION
Optional. Contains additional login attribute information.
If present, a flags value of LoginRefreshFlags.HAS_ATTRIB should be specified.
For details, refer to Section 7.3.8.1.

authenticationErrorCode

Optional. If present, a flags value of
LoginRefreshFlags.HAS_AUTHN_ERROR_CODE should be specified.
authenticationErrorCode is specific to a TREP Authentication environment, where 0
indicates an error-free condition. For further information, refer to the TREP
Authentication User Manual.a

authenticationErrorText

Optional. If present, a flags value of
LoginRefreshFlags.HAS_AUTHN_ERROR_TEXT should be specified.
authenticationErrorText specifies any error text that accompanies an
authenticationErrorCode. For further information, refer to the TREP Authentication

User Manual.a
authenticationExtendedResp

Optional. If present, a flags value of
LoginRefreshFlags.HAS_AUTHN_EXTENDED_RESP should be specified.
authenticationExtendedResp contains additional, customer-defined data associated

with the authentication token sent in the original request. For further information, refer
to the TREP Authentication User Manual.a
authenticationTTReissue

Optional. If present, a flags value of
LoginRefreshFlags.HAS_AUTHN_TT_REISSUE should be specified.
Indicates when a new authentication token needs to be reissued (in UNIX Epoch time).
For more information, refer to the TREP Authentication User Manual.a

connectionConfig

Optional. Indicates the connection configuration that the consumer uses for its
standby servers when setup for Warm Standby.
If present, a flags value of LoginRefreshFlags.HAS_CONN_CONFIG should be
specified.

features

Optional. Indicates a set of features supported by the provider of the login refresh
message.
If present, a flags value of LoginRefreshFlags.HAS_FEATURES should be
specified.
For details, refer to Section 7.3.2.3.

Table 84: LoginRefresh Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

MEMBER

Administration Domain Models Detailed View

DESCRIPTION

flags

Required. Indicate the presence of optional login refresh members. For details, see
Section 7.3.2.2.

rdmMsgBase

Required. Specifies the login message type (i.e., LoginMsgType.REFRESH for login
refresh).

sequenceNumber

Optional. A user-specified, item-level sequence number which can be used by the
application for sequencing messages within this stream.
If present, a flags value of LoginRefreshFlags.HAS_SEQ_NUM should be specified.

state

Required. Indicates the state of the login stream.
Defaults to a streamState of StreamStates.OPEN and a dataState of
DataStates.OK.
For more information on State, refer to the Transport API Java Edition Developers
Guide.

userName

Optional. If present, a flags value of LoginRefreshFlags.HAS_USERNAME should
be specified.
Contains content appropriate to the corresponding userNameType specification. If
populated, this should match the userName contained in the login request.

userNameType

Optional. If present, a flags value of LoginRefreshFlags.HAS_USERNAME_TYPE
should be specified. If absent, a default value of Login.UserIdTypes.NAME is
assumed.
Possible values:
•

•

A type of Login.UserIdTypes.NAME typically corresponds to a DACS user name and
can be used to authenticate and permission a user.
Login.UserIdTypes.TOKEN is specified when using the AAA (‘triple A’) API. The user
token is retrieved from the Authentication Manager application. To validate users, a
provider application passes this user token to the AAA Gateway. This type of token
periodically changes: when it changes, an application can send a login reissue to pass
information upstream. For more information, refer to documentation specific to the
AAAAPI.
Login.UserIdTypes.AUTHN_TOKEN is specified when using TREP Authentication.
The authentication token should be specified in the userName member. This type of
token can periodically change: when it changes, an application can send a login
reissue to pass information upstream. For more information, refer to the TREP
Authentication User Manual.a
Table 84: LoginRefresh Members (Continued)
a. For further details on TREP Authentication, refer to the TREP Authentication User Manual, accessible on Thomson Reuters MyAccount in the DACS
product documentation set.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.2.2

Administration Domain Models Detailed View

FLAG ENUMERATION

DESCRIPTION

LoginRefreshFlags.CLEAR_CACHE

Indicates to clear stored payload information associated with
the login stream. This might occur if some portion of data is
known to be invalid.

LoginRefreshFlags.HAS_ATTRIB

Indicates the presence of attrib.

LoginRefreshFlags.HAS_AUTHN_ERROR_CODE

Indicates the presence of authenticationErrorCode.

LoginRefreshFlags.HAS_AUTHN_ERROR_TEXT

Indicates the presence of authenticationErrorText.

LoginRefreshFlags.HAS_AUTHN_EXTENDED_RESP

Indicates the presence of authenticationExtendedResp.

LoginRefreshFlags.HAS_AUTHN_TT_REISSUE

Indicates the presence of authenticationTTReissue.

LoginRefreshFlags.HAS_CONN_CONFIG

Indicates the presence of connection configuration information
used with warm standby functionality.

LoginRefreshFlags.HAS_FEATURES

Indicates the presence of features. If absent, a value of 0 is
assumed.

LoginRefreshFlags.HAS_SEQ_NUM

Indicates the presence of sequenceNumber.

LoginRefreshFlags.HAS_USERNAME

Indicates the presence of userName.

LoginRefreshFlags.HAS_USERNAME_TYPE

Indicates the presence of userNameType. If absent, a
userNameType of Login.UserIdTypes.NAME should be
assumed.

LoginRefreshFlags.SOLICITED

•

If present, this flag indicates that the login refresh is
solicited (e.g., it is in response to a request).

•

If this flag is absent, this refresh is unsolicited.

Table 85: LoginRefresh Flags

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.2.3

Administration Domain Models Detailed View

For detailed information on posting, batch requesting, dynamic view use, and ‘pause and resume,’ refer to the Transport API
Java Edition Developers Guide.
MEMBER
flags

DESCRIPTION
Required. Indicates the presence of optional login refresh members.
For further flag details, refer to Section 7.3.2.4.

supportBatchCloses

Optional. Indicates whether the provider supports batch close functionality.
•

1: The provider supports batch closing.

•

0: The provider does not support batch reissuing.

If present, a flags value of
LoginSupportFeaturesFlags.HAS_SUPPORT_BATCH_CLOSES should be
specified. If absent, a default value of 0 is assumed.
supportBatchReissues

Optional. Indicates whether the provider supports batch reissue functionality.
•

1: The provider supports batch reissuing.

•

0: The provider does not support batch reissuing.

If present, a flags value of
LoginSupportFeaturesFlags.HAS_SUPPORT_BATCH_REISSUES should be
specified. If absent, a default value of 0 is assumed.
supportBatchRequests

Optional. Indicates whether the provider supports batch request functionality, which
allows a consumer to specify multiple items, all with matching attributes, in the same
request message.
•

1: The provider supports batch requesting.

•

0: The provider does not support batch requesting.

If present, a flags value of
LoginSupportFeaturesFlags.HAS_SUPPORT_BATCH_REQUESTS should be
specified. If absent, a default value of 0 is assumed.
supportEnhancedSymbolList

Optional. Indicates whether the provider supports enhanced symbol list features:
•

1: The provider supports enhanced symbol list features.

•

0: The provider does not support enhanced symbol list features.

If present, a flags value of LoginSupportFeaturesFlags.HAS_SUPPORT_ENH_SL
should be specified. If absent, a default value of 0 is assumed.
supportOptimizedPauseResume

Optional. Indicates whether the provider supports the optimized pause and resume
feature. Optimized pause and resume can pause/resume individual item streams or all
item streams by pausing the login stream.
•

1: The server supports optimized pause and resume.

•

0: The server does not support optimized pause and resume.

If present, a flags value of
LoginSupportFeaturesFlags.HAS_SUPPORT_OPT_PAUSE should be specified. If
absent, a default value of 0 is assumed.
Table 86: LoginSupportFeatures Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

MEMBER
supportOMMPost

Administration Domain Models Detailed View

DESCRIPTION
Optional. Indicates whether the provider supports OMM Posting:
•

1: The provider supports OMM Posting and the user is permissioned.

•

0: The provider supports the OMM Post feature, but the user is not permissioned.

•

If this element is not present, then the server does not support OMM Post feature.

If present, a flags value of LoginSupportFeaturesFlags.HAS_SUPPORT_POST
should be specified. If absent, a default value of 0 is assumed.
supportProviderDictionaryDownload

Optional. Indicates whether the non-interactive provider can request dictionaries from
the ADH:
•

1: The non-interactive provider can request dictionaries from the ADH.

•

0: The non-interactive provider cannot request dictionaries from the ADH.

If present, a flags value of
LoginSupportFeaturesFlags.HAS_SUPPORT_PROVIDER_DICTIONARY_DOWN
LOAD should be specified. If absent, a default value of 0 is assumed.
supportStandby

Optional. Indicates whether the provider supports warm standby functionality. If
supported, a provider can run as an active or a standby server, where the active will
behave as usual. The standby will respond to item requests only with the message
header and will forward any state changing information. When informed of an active’s
failure, the standby begins sending responses and takes over as active.
•

1: The provider supports a role of active or standby in a warm standby group.

•

0: The provider does not support warm standby functionality.

If present, a flags value of
LoginSupportFeaturesFlags.HAS_SUPPORT_STANDBY should be specified. If
absent, a default value of 0 is assumed.
supportViewRequests

Optional. Indicates whether the provider supports dynamic view functionality, which
allows a user to request specific response information.
•

1: The provider supports dynamic view functionality.

•

0: The provider does not support dynamic view functionality.

If present, a flags value of LoginSupportFeaturesFlags.HAS_SUPPORT_VIEW
should be specified. If absent, a default value of 0 is assumed.
Table 86: LoginSupportFeatures Members

7.3.2.4

For detailed information on batch functionality, posting, ‘pause and resume,’ and views, refer to the Transport API Java Edition
Developers Guide.
FLAG ENUMERATION
LoginSupportFeaturesFlags.HAS_SUPPORT_BATCH_CLOSES

MEANING
Indicates the presence of supportBatchCloses.
If absent, a value of 0 is assumed.

LoginSupportFeaturesFlags.HAS_SUPPORT_BATCH_REISSUES

Indicates the presence of supportBatchReissues.
If absent, a value of 0 is assumed.

Table 87: LoginSupportFeaturesFlags

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

FLAG ENUMERATION

Administration Domain Models Detailed View

MEANING

LoginSupportFeaturesFlags.HAS_SUPPORT_BATCH_REQUESTS Indicates the presence of supportBatchRequests.
If absent, a value of 0 is assumed.
LoginSupportFeaturesFlags.HAS_SUPPORT_ENH_SL

Indicates the presence of
supportEnhancedSymbolList.

If absent, a value of 0 is assumed.
LoginSupportFeaturesFlags.HAS_SUPPORT_OPT_PAUSE

Indicates the presence of
supportOptimizedPauseResume.

If absent, a value of 0 is assumed.
LoginSupportFeaturesFlags.HAS_SUPPORT_POST

Indicates the presence of supportOMMPost.
If absent, a value of 0 is assumed.

LoginSupportFeaturesFlags.HAS_SUPPORT_PROVIDER_DICTIO
NARY_DOWNLOAD

Indicates the presence of
supportProviderDictionaryDownload.

If absent, a value of 0 is assumed.
LoginSupportFeaturesFlags.HAS_SUPPORT_STANDBY

Indicates the presence of supportStandby.
If absent, a value of 0 is assumed.

LoginSupportFeaturesFlags.HAS_SUPPORT_VIEW

Indicates the presence of supportViewRequests.
If absent, a value of 0 is assumed.

Table 87: LoginSupportFeaturesFlags (Continued)

7.3.2.5

DESCRIPTION

numStandbyServers

Required. Indicates the number of servers in the serverList that the consumer
can use as standby servers when using warm standby.

serverList

Required. A list of servers to which the consumer may connect when using
warm standby.

Table 88: LoginConnectionConfig Members

7.3.2.6

DESCRIPTION

clear

Clears a LoginConnectionConfig object for reuse.

copy

Performs a deep copy of a LoginConnectionConfig object.

Table 89: LoginConnectionConfig Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.2.7

Administration Domain Models Detailed View

Server Info Members

MEMBER

DESCRIPTION

flags

Required. Indicates the presence of optional server information members. For
details, refer to Section 7.3.2.8.

hostname

Required. Indicates the server’s hostname.

loadFactor

Optional. Indicates the load information for this server. If present, a flags value of
ServerInfoFlags.HAS_LOAD_FACTOR should be specified.

port

Required. Indicates the server’s port number for connections.

serverIndex

Required. Provides the index value to this server.

serverType

Optional. Indicates whether this server is an active or standby server. If present, a
flags value of ServerInfoFlags.HAS_TYPE should be specified, populated by
Login.ServerTypes.

Table 90: ServerInfo Members

7.3.2.8

Server Info Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

ServerInfoFlags.HAS_LOAD_FACTOR

Indicates presence of loadFactor information.

ServerInfoFlags.HAS_TYPE

Indicates presence of serverType.

Table 91: ServerInfo Flags

7.3.2.9

Server Info Methods

METHOD NAME

DESCRIPTION

clear

Clears a ServerInfo object. Useful for object reuse.

copy

Performs a deep copy of a ServerInfo object.

Table 92: ServerInfo Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.3

Administration Domain Models Detailed View

OMM Provider and OMM non-interactive provider applications use the Login Status message to convey state information
associated with the login stream. Such state information can indicate that a login stream cannot be established or to inform a
consumer of a state change associated with an open login stream.
The login status message can also reject a login request or close an existing login stream. When a status message closes a
login stream, any other open streams associated with the user are also closed.
The LoginStatus represents all members of a login status message and allows for simplified use in OMM applications that
leverage RDM. This structure follows the behavior and layout defined in the Transport API Java Edition RDM Usage Guide.

7.3.3.1

MEMBER
authenticationErrorCode

DESCRIPTION
Optional. If present, a flags value of
LoginStatusFlags.HAS_AUTHN_ERROR_CODE should be specified.
authenticationErrorCode is specific to deployments using TREP Authentication,
and specifies an error code. A code of 0 indicates no error condition. For further
information, refer to the TREP Authentication User Manual.a

authenticationErrorText

Optional. If present, a flags value of
LoginStatusFlags.HAS_AUTHN_ERROR_TEXT should be specified.
Specifies any text associated with the specified authenticationErrorCode. For
further information, refer to the TREP Authentication User Manual.a

flags

Required. Indicates the presence of optional login status members. For details, refer
to Section 7.3.3.2.

rdmMsgBase

Required. Specifies the login message type (i.e., LoginMsgType.STATUS for login
status).

state

Optional. If present, a flags value of LoginStatusFlags.HAS_STATE should be
specified.
Indicates the state of the login stream. When rejecting a login the state should be:
•

streamState = StreamStates.CLOSED or StreamStates.CLOSED_RECOVER

•

dataState = DataStates.SUSPECT

•

stateCode = StateCodes.NOT_ENTITLED

For more information on State, refer to the Transport API Java Edition Developers
Guide.
Table 93: LoginStatus Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

MEMBER
userNameType

Administration Domain Models Detailed View

DESCRIPTION
Optional. If present, a flags value of LoginStatusFlags.HAS_USERNAME_TYPE
should be specified. If absent, a default value of Login.UserIdTypes.NAME is
assumed.
Possible values:
•

•

A type of Login.UserIdTypes.NAME typically corresponds to a DACS user name
and can be used to authenticate and permission a user.
Login.UserIdTypes.TOKEN is specified when using the AAA (‘triple A’) API. The
user token is retrieved from the Authentication Manager application. To validate
users, a provider application passes this user token to the AAA Gateway. This type of
token periodically changes: when it changes, an application can send a login reissue
to pass information upstream. For more information, refer to documentation specific
to the AAAAPI.
Login.UserIdTypes.AUTHN_TOKEN is specified when using TREP Authentication.
The authentication token should be specified in the userName member. This type of
token can periodically change: when it changes, an application can send a login
reissue to pass information upstream. For more information, refer to the TREP
Authentication User Manual.a
userName

Optional. If present, a flags value of LoginStatusFlags.HAS_USERNAME should
be specified.
When populated, this should match the userName in the login request.

Table 93: LoginStatus Members (Continued)
a. For further details on TREP Authentication, refer to the TREP Authentication User Manual, accessible on Thomson Reuters MyAccount in the DACS
product documentation set.

7.3.3.2

FLAG ENUMERATION
LoginStatusFlags.CLEAR_CACHE

MEANING
Indicates whether the receiver of the login status should clear any associated
cache information.

LoginStatusFlags.HAS_AUTHN_ERROR_CO Indicates the presence of authenticationErrorCode.
DE
LoginStatusFlags.HAS_AUTHN_ERROR_TE
XT

Indicates the presence of authenticationErrorText.

LoginStatusFlags.HAS_STATE

Indicates the presence of state.
If absent, any previously conveyed state continues to apply.

LoginStatusFlags.HAS_USERNAME

Indicates the presence of userName.

Table 94: LoginStatus Flags

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

FLAG ENUMERATION
LoginStatusFlags.HAS_USERNAME_TYPE

Administration Domain Models Detailed View

MEANING
Indicates the presence of userNameType.
If absent a userNameType of Login.UserIdTypes.NAME is assumed.

Table 94: LoginStatus Flags (Continued)

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.4

Administration Domain Models Detailed View

A Login Close message is encoded and sent by OMM consumer applications. This message allows a consumer to log out of
the system. Closing a login stream is equivalent to a Close All type of message, where all open streams are closed (i.e., all
streams associated with the user). A provider can log off a user and close all of that user’s streams via a login status message,
see Section 7.3.3.
MEMBER
rdmMsgType

DESCRIPTION
Required. Specifies the login message type (for a login close, this will be
LoginMsgType.CLOSE).

Table 95: LoginClose Member

7.3.5

The Login Consumer Connection Status informs an interactive provider of its role in a Warm Standby group, either as an
Active or Standby provider. An active provider behaves normally; however a standby provider responds to requests only with
a message header (allowing a consumer application to confirm the availability of requested data across active and standby
servers), and forwards any state-related messages (i.e., unsolicited refresh messages, status messages). A standby provider
aggregates changes to item streams whenever possible. If a provider changes from Standby to Active via this message, all
aggregated update messages are passed along. If aggregation is not possible, a full, unsolicited refresh message is passed
along.
The consumer application is responsible for ensuring that items are available and equivalent across all providers in a warm
standby group. This includes managing state and availability differences as well as item group differences.
The LoginConsumerConnectionStatus relies on the GenericMsg and represents all members necessary for applications that
leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.3.5.1

MEMBER

DESCRIPTION

flags

Required. Indicate the presence of optional login consumer connection status
members. For details, refer to Section 7.3.5.2.

rdmMsgBase

Required. Indicates the Login Message type (for login connection status, set to
LoginMsgType.CONSUMER_CONNECTION_STATUS).

warmStandbyInfo

Optional. Includes LoginWarmStandbyInfo to convey the state of the upstream
provider. For details, refer to Section 7.3.5.3.
If present, a flags value of
LoginConsumerConnectionStatusFlags.HAS_WARM_STANDBY_INFO should
be specified.

Table 96: LoginConsumerConnectionStatus Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.5.2

Administration Domain Models Detailed View

FLAG ENUMERATION

DESCRIPTION

LoginConsumerConnectionStatusFlags.HAS_WARM_STANDBY_INFO

Indicates presence of warmStandbyInfo.

Table 97: LoginConsumerConnectionStatus Flags

7.3.5.3

MEMBER
action

DESCRIPTION
Required. Indicates how a cache of Warm Standby content should apply this information.
For information on MapEntry actions, refer to the Transport API Java Edition Developers
Guide.

warmStandbyMode

Required. Indicates whether a server is active (Login.ServerTypes.ACTIVE) or standby
(Login.ServerTypes.SERVER).

Table 98: LoginWarmStandbyInfo Members

7.3.5.4

METHOD NAME

DESCRIPTION

clear

Clears a LoginWarmStandbyInfo object for reuse.

copy

Performs a deep copy of a LoginWarmStandbyInfo object.

Table 99: LoginWarmStandbyInfo Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.6

Administration Domain Models Detailed View

OMM consumer applications can encode and send data for any item via Post messages on the item’s login stream. This is
known as off-stream posting because items are posted without using that item’s dedicated stream. Posting an item on its
own dedicated stream is referred to as on-stream posting.
When an application is off-stream posting, msgKey information is required on the PostMsg. For more details on posting, refer to
the Transport API Java Edition Developers Guide.

7.3.7

OMM Provider applications encode and send Ack messages to acknowledge the receipt of Post messages. An Ack message
is used whenever a consumer posts and asks for acknowledgments. For more details on posting, see the Transport API Java
Edition Developers Guide.

7.3.8

On a Login Request or Login Refresh message, the LoginAttrib can send additional authentication information and user
preferences between components.

7.3.8.1

The following table lists the elements available on a LoginAttrib.
MEMBER
allowSuspectData

DESCRIPTION
Optional. Indicates how the consumer application wants to handle suspect data.
•

1: Indicates that the consumer application allows for suspect streamState
information. If absent, a default value of 1 is assumed.

•

0: Indicates that the consumer application wants suspect data to cause the
stream to close with a StreamStates.CLOSED_RECOVER state.

If present, a flags value of LoginAttribFlags.HAS_ALLOW_SUSPECT_DATA
should be specified.
applicationId

Optional. Indicates the application ID.
•

If populated in a login request, applicationId should be set to the DACS
applicationId. If the server authenticates with DACS, the consumer
application may be required to pass in a valid application id. If initializing
LoginRequest using initDefaultRequest, an applicationId of 256 will
be used.

•

If populated in a login refresh, applicationId should match the
applicationId used in the login request.

If present, a flags value of LoginAttribFlags.HAS_APPLICATION_ID should
be specified.
applicationName

Optional. Indicates the application name.
•

If populated in a login request, the applicationName identifies the OMM
consumer or OMM non-interactive provider. If initializing LoginRequest using
initDefaultRequest, the applicationName is set to upa.

•

If populated in a login refresh, the applicationName identifies the OMM
provider.

If present, a flags value of LoginAttribFlags.HAS_APPLICATION_NAME
should be specified.
Table 100: LoginAttrib Members
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

MEMBER
flags

Administration Domain Models Detailed View

DESCRIPTION
Required. Indicates the presence of optional login attribute members.
For details, refer to Section 7.3.8.3.

position

Optional. Indicates the DACS position.
•

When populated in a login request, position should match the position
contained in the login request and the DACS position (if using DACS). If the
server is authenticating with DACS, the consumer application might be
required to pass in a valid position. If initializing LoginRequest using
initDefaultRequest, the IP address of the system on which the application
runs will be used.

•

When populated in a login refresh, this should match the position contained
in the login request

If present, a flags value of LoginAttribFlags.HAS_POSITION should be
specified.
providePermissionExpressions

Optional. Indicates whether the consumer wants permission expression
information. Permission expressions allow for items to be proxy-permissioned by
a consumer via content-based entitlements.
•

1: Requests that permission expression information be sent with responses.
If absent, a default value of 1 is assumed.

•

0: Indicates that the consumer does not want permission expression
information.

If present, a flags value of LoginAttribFlags.HAS_PROVIDE_PERM_EXPR
should be specified.
providePermissionProfile

Optional. Indicates whether the consumer desires the permission profile. An
application can use the permission profile to perform proxy permissioning.
If present, a flags value of
LoginAttribFlags.HAS_PROVIDE_PERM_PROFILE should be specified.

singleOpen

•

1: Indicates that the consumer wants the permission profile. If absent, a
default value of 1 is assumed.

•

0: Indicates the consumer does not want the permission profile.

Optional. Indicates which application the consumer wants to drive stream
recovery.
If present, a flags value of LoginAttribFlags.HAS_SINGLE_OPEN should be
specified.

supportProviderDictionaryDownload

•

1: Indicates that the consumer application wants the provider to drive stream
recovery. If absent, a default value of 1 is assumed.

•

0: Indicates that the consumer application drives stream recovery.

Optional. Indicates whether the interactive provider can request dictionaries
from the ADH:
•

1: The interactive provider can request dictionaries from the ADH.

•

0: The interactive provider cannot request dictionaries from the ADH.

If present, a flags value of
LoginAttribFlags.HAS_PROVIDER_SUPPORT_DICTIONARY_DOWNLOAD
should be specified. If absent, a default value of 0 is assumed.
Table 100: LoginAttrib Members (Continued)

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

Chapter 7

7.3.8.2

Administration Domain Models Detailed View

DESCRIPTION

clear

Clears a LoginAttrib object for reuse.

copy

Performs a deep copy of a LoginAttrib object.

Table 101: LoginAttrib Methods

7.3.8.3

MEANING

HAS_ALLOW_SUSPECT_DATA

Indicates the presence of allowSuspectData. If absent, a value of 1 is
assumed.

HAS_APPLICATION_ID

Indicates the presence of applicationId.

HAS_APPLICATION_NAME

Indicates the presence of applicationName.

HAS_POSITION

Indicates the presence of position.

HAS_PROVIDE_PERM_EXPR

Indicates the presence of providePermissionExpressions. If absent, a value
of 1 is assumed.

HAS_PROVIDE_PERM_PROFILE

Indicates the presence of providePermissionProfile. If absent, a value of 1 is
assumed.

HAS_PROVIDER_SUPPORT_DICTIONA
RY_DOWNLOAD

Indicates the presence of supportProviderDictionaryDownload.

HAS_SINGLE_OPEN

Indicates the presence of singleOpen. If absent, a value of 1 is assumed.

Table 102: LoginAttribFlags

7.3.9

LoginMsg is the base interface for all Login messages. It is provided for use with general login-specific functionality. The

following table summarizes different login messages.
INTERFACE

DESCRIPTION

LoginClose

RDM Login Close.

LoginConsumerConnectionStatus

RDM Login Consumer Connection Status.

LoginRefresh

RDM Login Refresh

LoginRequest

RDM Login Request.

LoginStatus

RDM Login Status.

Table 103: LoginMsg Interfaces

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

100

Chapter 7

7.3.10

Administration Domain Models Detailed View

copy

DESCRIPTION
Performs a deep copy of a LoginMsg object.

Table 104: LoginMsg Utility Methods

7.3.11

7.3.11.1

METHOD NAME
decode

DESCRIPTION
Decodes a Login message. The decoded message may refer to encoded data from the original
message. If you want to store the message, use the appropriate copy method for the decoded

message to create a full copy.
Each login subinterface overrides this method to decode specific login message.
encode

Encodes a Login message. This method takes the EncodeIterator as a parameter into which
the encoded content is populated.
Each login subinterface overrides this method to encode specific login message.

Table 105: Login Encoding and Decoding Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

101

Chapter 7

7.3.11.2

Administration Domain Models Detailed View

Encoding a Login Request

EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
LoginRequest loginRequest = (LoginRequest)LoginMsgFactory.createMsg();
/* Clear the Login Request object. */
loginRequest.clear();
/* Set login message type – required as object created by LoginMsgFactory.createMsg() is generic Login */
/* object. */
loginRequest.rdmMsgType(LoginMsgType.REQUEST);
/* Set stream id. */
loginRequest.streamId(streamId);
/* Set flags indicating presence of optional members. */
loginRequest.applyHasAttrib();
/* Set UserName. */
loginRequest.userName().data("username");
/* Set ApplicationName */
loginRequest.attrib().applyHasApplicationName();
loginRequest.attrib().applicationName().data("upa");
/* Set ApplicationId */
loginRequest.attrib().applyHasApplicationId();
loginRequest.attrib().applicationId().data("256");
/* Set Position */
loginRequest.attrib().applyHasPosition();
loginRequest.attrib().position().data(“127.0.0.1/net");
/* Clear the encode iterator, set its RWF Version, and set it to a buffer for encoding into. */
encodeIter.clear();
ret = encodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Encode the message. */
ret = loginRequest.encode(encodeIter);

Code Example 19: Login Request Encoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

102

Chapter 7

7.3.11.3

Administration Domain Models Detailed View

Decoding a Login Request

DecodeIterator decodeIter = CodecFactory.createDecodeIterator();
LoginRequest loginRequest = (LoginRequest)LoginMsgFactory.createMsg();
Msg msg = CodecFactory.createMsg();
/* Clear the decode iterator, set its RWF Version, and set it to the encoded buffer. */
decodeIter.clear();
ret = decodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Decode the message to a Msg object. */
ret = msg.decode(decodeIter);
if (ret == CodecReturnCodes.SUCCESS && msg.domainType() == DomainTypes.LOGIN && msg.msgClass() ==
MsgClasses.REQUEST)
{
loginRequest.clear();
loginRequest.rdmMsgType(LoginMsgType.REQUEST);
ret = loginRequest.decode(decodeIter, msg);
if(ret == CodecReturnCodes.SUCCESS)
{
/* Print username. */
printf("Username: “ + loginRequest.userName());
if (loginRequest.checkHasAttrib())
{
LoginAttrib attrib = loginRequest.attrib();
/* Print ApplicationName if present. */
if(attrib.checkHasApplicationName())
System.out.println(“ApplicationName: " + attrib.applicationName().toString());
/* Print ApplicationId if present. */
if(attrib.checkHasApplicationId())
System.out.println(“ApplicationId: " + attrib.applicationId().toString());
/* Print Position if present. */
if(attrib.checkHasPosition())
System.out.println(“Position: " + attrib.position().toString());
}
}
}

Code Example 20: Login Request Decoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

103

Chapter 7

7.3.11.4

Administration Domain Models Detailed View

Encoding a Login Refresh

EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
LoginRefresh loginRefresh = (LoginRefresh)LoginMsgFactory.createMsg();
/* Clear the Login Refresh object. */
loginRefresh.clear();
/* Set login message type – required as object created by LoginMsgFactory.createMsg() is generic Login */
/* object.*/
encodeIter.rdmMsgType(LoginMsgType.REFRESH);
/* Set stream id. */
loginRefresh.streamId(streamId);
/* Set flags indicating presence of optional members. */
loginRefresh.applyHasAttrib();
loginRefresh.applyHasUserName();
/* Set UserName. */
loginRefresh.userName().data("username");
/* Set ApplicationName */
loginRefresh.attrib().applyHasApplicationName();
loginRefresh.attrib().applicationName().data("upa");
/* Set ApplicationId */
loginRefresh.attrib().applyHasApplicationId();
loginRefresh.attrib().applicationId().data("256");
/* Set Position */
loginRefresh.attrib().applyHasPosition();
loginRefresh.attrib().position().data(“127.0.0.1/net");
/* Clear the encode iterator, set its RWF Version, and set it to a buffer for encoding into. */
encodeIter.clear();
ret = encodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Encode the message. */
ret = loginRefresh.encode(encodeIter);

Code Example 21: Login Refresh Encoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

104

Chapter 7

7.3.11.5

Administration Domain Models Detailed View

Decoding a Login Refresh

DecodeIterator decodeIter = CodecFactory.createDecodeIterator();
LoginRefresh loginRefresh = (LoginRefresh)LoginMsgFactory.createMsg();
Msg msg = CodecFactory.createMsg();
/* Clear the decode iterator, set its RWF Version, and set it to the encoded buffer. */
decodeIter.clear();
ret = decodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Decode the message to a Msg object. */
ret = msg.decode(decodeIter);
if (ret == CodecReturnCodes.SUCCESS && msg.domainType() == DomainTypes.LOGIN && msg.msgClass() ==
MsgClasses.REFRESH)
{
loginRefresh.clear();
loginRefresh.rdmMsgType(LoginMsgType.REFRESH);
ret = loginRefresh.decode(decodeIter, msg);
if(ret == CodecReturnCodes.SUCCESS)
{
/* Print username. */
if(loginRefresh.checkHasUserName())
printf("Username: " + loginRefresh.userName().toString());
if (loginRefresh.checkHasAttrib())
{
LoginAttrib attrib = loginRefresh.attrib();
/* Print ApplicationName if present. */
if(attrib.checkHasApplicationName())
System.out.println(“ApplicationName: " + attrib.applicationName().toString());
/* Print ApplicationId if present. */
if(attrib.checkHasApplicationId())
System.out.println(“ApplicationId: " + attrib.applicationId().toString());
/* Print Position if present. */
if(attrib.checkHasPosition())
System.out.println(“Position: " + attrib.position().toString());
}
}
}

Code Example 22: Login Refresh Decoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

105

Chapter 7

7.4

Administration Domain Models Detailed View

RDM Source Directory Domain

The Source Directory domain model conveys information about:

•

All available services and their capabilities, their supported domain types, services’ states, QoS, and item group
information (associated with any particular service). Each service is associated with a unique serviceId.

•

Item group status, allowing a single message to change the state of all associated items. Thus, using the Source Directory
domain an application can send a mass update for multiple items instead of sending a status message for each individual
item. The consumer is responsible for applying any changes to its open items. For details, refer to Section 7.4.10.

•

Source Mirroring between an ADH and OMM interactive provider applications. The Source Directory exchanges this
information via a specifically-formatted generic message as described in Section 7.4.6.

7.4.1

Directory Request

An OMM consumer application encodes and sends Directory Request messages to request information from an OMM
provider about available services. A consumer may request information about all services by omitting the serviceId member,
or request information about a specific service by setting it to the ID of the desired service.
The DirectoryRequest represents all members of a directory request message and is easily used in OMM applications that
leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.4.1.1

Directory Request Members

MEMBER
filter

DESCRIPTION
Required. Indicates the service information in which the consumer is interested. The available
flags are:
•

Directory.ServiceFilterFlags.INFO = 0x01

•

Directory.ServiceFilterFlags.STATE = 0x02

•

Directory.ServiceFilterFlags.GROUP = 0x04

•

Directory.ServiceFilterFlags.LOAD = 0x08

•

Directory.ServiceFilterFlags.DATA = 0x10

•

Directory.ServiceFilterFlags.LINK = 0x20

In most cases, you should set the Directory.ServiceFilterFlags.INFO,
Directory.ServiceFilterFlags.STATE, and Directory.ServiceFilterFlags.GROUP.
flags

Required. Indicates the presence of optional directory request members. For details, refer to
Section 7.4.1.2.

rdmMsgBase

Required. Specifies the directory message type (a directory request would be
DirectoryMsgType.REQUEST).

serviceId

Optional.
•

If not present, this indicates the consumer wants information about all available services.

•

If present, this indicates the ID of the service about which the consumer wants information.
Additionally, a flags value of DirectoryRequestFlags.HAS_SERVICE_ID should be
specified.

Table 106: DirectoryRequest Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

106

Chapter 7

7.4.1.2

Administration Domain Models Detailed View

Directory Request Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

DirectoryRequestFlags.HAS_SERVICE_ID

Indicates the presence of serviceId.

DirectoryRequestFlags.STREAMING

Indicates that the consumer wants to receive updates about directory
information after the initial refresh.

Table 107: DirectoryRequest Flags

7.4.1.3

Directory Request Methods

METHOD NAME

DESCRIPTION

clear

Clears a DirectoryRequest object. Useful for object reuse.

copy

Performs a deep copy of a DirectoryRequest object.

Table 108: DirectoryRequest Utility Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

107

Chapter 7

7.4.2

Administration Domain Models Detailed View

Directory Refresh

A Directory Refresh message is encoded and sent by OMM provider and non-interactive provider applications. This message
can provide information about the services supported by the provider application.
The DirectoryRefresh represents all members of a directory refresh message and is easily used in OMM applications that
leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.4.2.1

Directory Refresh Members

MEMBER
filter

DESCRIPTION
Required. Indicates the information being provided about supported services. This should
match the filter of the consumer’s DirectoryRequest. The available flags are:
•

Directory.ServiceFilterFlags.INFO = 0x01

•

Directory.ServiceFilterFlags.STATE = 0x02

•

Directory.ServiceFilterFlags.GROUP = 0x04

•

Directory.ServiceFilterFlags.LOAD = 0x08

•

Directory.ServiceFilterFlags.DATA = 0x10

•

Directory.ServiceFilterFlags.LINK = 0x20

flags

Required. Indicates the presence of optional directory refresh members. Refer to Section
7.4.2.2.

rdmMsgBase

Required. Specifies the type of directory message. For a directory refresh, send
DirectoryMsgType.REFRESH.

sequenceNumber

Optional. If present, a flags value of DirectoryRefreshFlags.HAS_SEQ_NUM should be
specified.
sequenceNumber is a user-specified, item-level sequence number that the application can

use to sequence messages in the stream.
serviceId

Optional. If present, a flags value of DirectoryRefreshFlags.HAS_SERVICE_ID should
be specified, which should match the serviceId of the consumer’s DirectoryRequest.

serviceList

Optional. Contains a list of information about available services.

state

Required. Indicates stream and data state information. For further details on State, refer to
the Transport API Java Edition Developers Guide.

Table 109: DirectoryRefresh Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

108

Chapter 7

7.4.2.2

Administration Domain Models Detailed View

Directory Refresh Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

DirectoryRefreshFlags.CLEAR_CACHE

Indicates that any stored payload information associated with the directory
stream should be cleared. This might happen if some portion of data is known
to be invalid.

DirectoryRefreshFlags.HAS_SEQ_NUM

Indicates the presence of sequenceNumber.

DirectoryRefreshFlags.HAS_SERVICE_ID

Indicates the presence of serviceId.

DirectoryRefreshFlags.SOLICITED

If present, this flag indicates that the directory refresh is solicited (i.e., it is in
response to a request). The absence of this flag indicates that the refresh is
unsolicited.

Table 110: DirectoryRefresh Flags

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

109

Chapter 7

7.4.3

Administration Domain Models Detailed View

Directory Update

A Directory Update message is encoded and sent by OMM provider and non-interactive provider applications. This message
can provide information about new or removed services, or changes to existing services.
The DirectoryUpdate represents all members of a directory update message and allows for simplified use in OMM
applications that leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition
RDM Usage Guide.

7.4.3.1

Directory Update Members

MEMBER
filter

DESCRIPTION
Optional. Indicates what information is provided about supported services. This
should match the filter of the consumer’s DirectoryRequest.
If present, a flags value of DirectoryUpdateFlags.HAS_FILTER should be
specified.
Available flags are:
•

Directory.ServiceFilterFlags.INFO = 0x01

•

Directory.ServiceFilterFlags.STATE = 0x02

•

Directory.ServiceFilterFlags.GROUP = 0x04

•

Directory.ServiceFilterFlags.LOAD = 0x08

•

Directory.ServiceFilterFlags.DATA = 0x10

•

Directory.ServiceFilterFlags.LINK = 0x20

flags

Required. Indicates the presence of optional directory update members. For details
refer to Section 7.4.3.2.

sequenceNumber

Optional. A user-specified, item-level sequence number which the application can
use to sequence messages in this stream.
If present, a flags value of DirectoryUpdateFlags.HAS_SEQ_NUM should be
specified.

serviceId

Optional. This member’s value must match the serviceId of the consumer’s
DirectoryRequest.

If present, a flags value of DirectoryUpdateFlags.HAS_SERVICE_ID should be
specified.
serviceList

Optional. Contains a list of information about available services.

rdmMsgBase

Required. Specifies the message type. For a directory update, send
DirectoryMsgType.UPDATE.

Table 111: DirectoryUpdate Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

110

Chapter 7

7.4.3.2

Administration Domain Models Detailed View

Directory Update Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

DirectoryUpdateFlags.HAS_FILTER

Indicates the presence of filter.

DirectoryUpdateFlags.HAS_SEQ_NUM

Indicates the presence of sequenceNumber.

DirectoryUpdateFlags.HAS_SERVICE_ID Indicates the presence of serviceId.
Table 112: DirectoryUpdate Flags

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

111

Chapter 7

7.4.4

Administration Domain Models Detailed View

Directory Status

OMM provider and OMM non-interactive provider applications use the Directory Status message to convey state information
associated with the directory stream. Such state information can indicate that a directory stream cannot be established or to
inform a consumer of a state change associated with an open directory stream. An application can also use the Directory
Status message to close an existing directory stream.
The DirectoryStatus represents all members of a directory status message and allows for simplified use in OMM
applications that leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition
RDM Usage Guide.

7.4.4.1

Directory Status Members

MEMBER
filter

DESCRIPTION
Optional. If present, a flags value of DirectoryStatusFlags.HAS_FILTER should be
specified. Indicates what information is being provided about supported services. This
should match the filter of the consumer’s DirectoryRequest. The available flags are:
•

Directory.ServiceFilterFlags.INFO = 0x01

•

Directory.ServiceFilterFlags.STATE = 0x02

•

Directory.ServiceFilterFlags.GROUP = 0x04

•

Directory.ServiceFilterFlags.LOAD = 0x08

•

Directory.ServiceFilterFlags.DATA = 0x10

•

Directory.ServiceFilterFlags.LINK = 0x20

flags

Required. Indicates the presence of optional directory status members. For details, refer to
Section 7.4.4.2.

serviceId

Optional. If present, a flags value of DirectoryStatusFlags.HAS_SERVICE_ID should be
specified. This member should match the serviceId of the consumer’s
DirectoryRequest.

state

Optional. Indicates the state of the directory stream.
If present, a flags value of DirectoryStatusFlags.HAS_STATE should be specified.
For more information on State, refer to the Transport API Java Edition Developers Guide.

rdmMsgBase

Required. Specifies the message type. For a directory status, send
DirectoryMsgType.STATUS.

Table 113: DirectoryStatus Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

112

Chapter 7

7.4.4.2

Administration Domain Models Detailed View

Directory Status Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

DirectoryStatusFlags.CLEAR_CACHE

Indicates that any stored payload data associated with the directory stream
should be cleared. This might happen if some portion of data is known to be
invalid.

DirectoryStatusFlags.HAS_FILTER

Indicates the presence of filter.

DirectoryStatusFlags.HAS_SERVICE_ID

Indicates the presence of serviceId.

DirectoryStatusFlags.HAS_STATE

Indicates the presence of state. If not present, any previously conveyed state
should continue to apply.

Table 114: DirectoryStatus Flags

7.4.4.3

Directory Status Methods

METHOD NAME

DESCRIPTION

clear

Clears an DirectoryStatus object. Useful for object reuse.

copy

Performs a deep copy of an DirectoryStatus object.

Table 115: DirectoryStatus Utility Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

113

Chapter 7

7.4.5

Administration Domain Models Detailed View

Directory Close

A Directory Close message is encoded and sent by OMM consumer applications. This message allows a consumer to close
an open directory stream. A provider can close the directory stream via a Directory Status message; for details refer to Section
7.4.4.
MEMBER

DESCRIPTION

rdmMsgBase

Required. Specifies the directory message type. For a Directory Close message, set
rdmMsgBase to DirectoryMsgType.CLOSE.

Table 116: DirectoryClose Member

7.4.6

Directory Consumer Status

The Directory Consumer Status is sent by OMM consumer applications to inform a service of how the consumer is used for
Source Mirroring. This message is primarily informational.
The DirectoryConsumerStatus relies on the GenericMsg and represents all members necessary for applications that
leverage RDM. This structure follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.4.6.1

Directory Consumer Status Members

MEMBER

DESCRIPTION

consumerServiceStatusList

Optional. Contains a list of ConsumerStatusService objects.

rdmMsgBase

Required. Specifies the directory message type. For a directory consumer status, set
rdmMsgBase to DirectoryMsgType.CONSUMER_STATUS.

Table 117: DirectoryConsumerStatus Members

7.4.6.2

Directory Consumer Status Service Members

MEMBER
action

DESCRIPTION
Required. Indicates how a cache of Source Mirroring content should apply this information.
For information on MapEntry actions, refer to the Transport API Java Edition Developers
Guide.

serviceId

Required. Indicates the service associated with this status.

sourceMirroringMode

Required. Indicates how the consumer is using the service. Available enumerations are:
•

Directory.SourceMirroringMode.ACTIVE_NO_STANDBY = 0,

•

Directory.SourceMirroringMode.ACTIVE_WITH_STANDBY = 1,

•

Directory.SourceMirroringMode.STANDBY = 2

Table 118: ConsumerStatusService Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

114

Chapter 7

7.4.7

Administration Domain Models Detailed View

Directory Service

A Service object conveys information about a service. A list of Services forms the serviceList member of the
DirectoryRefresh and DirectoryUpdate messages.
The members of an Service represent the different filters used to categorize service information.

7.4.7.1

Service Members

MEMBER

DESCRIPTION

action

Required. Indicates how a cache of the service should apply this information. For information
on MapEntry actions, refer to the Transport API Java Edition Developers Guide.

data

Optional. Contains data that applies to the items requested from the service and represents
the Source Directory Data Filter. If present, a flags value of ServiceFlags.HAS_DATA should
be specified.

flags

Required. Indicates the presence of optional service members. For details, refer to Section
7.4.7.2.

groupStateList

Optional. Contains a list of elements indicating changes to item groups and represents the
Source Directory Group filter.

info

Optional. Contains information related to the Source Directory Info Filter. If present, a flags
value of ServiceFlags.HAS_INFO should be specified.

link

Optional. Contains information about upstream sources that provide data to this service and
represents the Source Directory Link Filter. If present, a flags value of
ServiceFlags.HAS_LINK should be specified.

load

Optional. Contains information about the service’s operating workload and represents the
Source Directory Load Filter. If present, a flags value of ServiceFlags.HAS_LOAD should be
specified.

serviceId

Required. Indicates the service associated with this Service.

state

Optional. Contains information related to the Source Directory State Filter. If present, a flags
value of ServiceFlags.HAS_STATE should be specified.

Table 119: Service Members

7.4.7.2

Service Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

ServiceFlags.HAS_DATA

Indicates the presence of data.

ServiceFlags.HAS_INFO

Indicates the presence of info.

ServiceFlags.HAS_LINK

Indicates the presence of link.

ServiceFlags.HAS_LOAD

Indicates the presence of load.

ServiceFlags.HAS_STATE

Indicates the presence of state.

Table 120: Service Flags

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

115

Chapter 7

7.4.7.3

Administration Domain Models Detailed View

Service Methods

METHOD NAME

DESCRIPTION

clear

Clears a Service object. Useful for object reuse.

copy

Performs a deep copy of a Service object.

Table 121: Service Utility Methods

7.4.8

Directory Service Info Filter

A ServiceInfo object conveys information that identifies the service and the content it provides. The ServiceInfo object
represents the Source Directory Info filter. More information about the Info filter is available in the Transport API Java Edition
RDM Usage Guide.

7.4.8.1

Service Info Members

MEMBER
acceptingConsumerStatus

DESCRIPTION
Optional. Indicates whether this service supports accepting
DirectoryConsumerStatus messages for Source Mirroring. Available values are:

•

1: The service will accept Consumer Status messages. If not present, a value of 1
is assumed.

•

0: The service will not accept Consumer Status messages.

If present, a flags value of ServiceInfoFlags.HAS_ACCEPTING_CONS_STATUS
should be specified.
action

Required. Indicates how a service info cache should apply this information.
For information on FilterEntryActions, refer to the Transport API Java Edition
Developers Guide.

capabilitiesList

Required. Contains a list of capabilities that the service supports. Populated by
domain types.

dictionariesProvidedList

Optional. Contains a list of elements that identify dictionaries that can be requested
from this service.
If present, a flags value of ServiceInfoFlags.HAS_DICTS_PROVIDED should be
specified.

dictionariesUsedList

Optional. Contains a list of elements that identify dictionaries used to decode data
from this service.
If present, a flags value of ServiceInfoFlags.HAS_DICTS_USED should be
specified.

flags

Required. Indicates the presence of optional service info members.
For details, refer to Section 7.4.8.2.

Table 122: ServiceInfo Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

116

Chapter 7

MEMBER
isSource

Administration Domain Models Detailed View

DESCRIPTION
Optional. Indicates whether the service is provided directly by a source or represents
a group of sources.
•

1: The service is provided directly by a source

•

0: The service represents a group of sources. If absent, a value of 0 is assumed.

If present, a flags value of ServiceInfoFlags.HAS_IS_SOURCE should be
specified.
itemList

Optional. Specifies a name that can be requested on the
DomainTypes.SYMBOL_LIST domain to get a list of all items available from this
service.
If present, a flags value of ServiceInfoFlags.HAS_ITEM_LIST should be specified.

qosList

Optional. Contains a list of elements that identify the available Qualities of Service.
If present, a flags value of ServiceInfoFlags.HAS_QOS should be specified.

serviceName

Required. Indicates the name of the service.

supportsOutOfBandSnapshots

Optional. Indicates whether this service supports making snapshot requests even
when the OpenLimit is reached. Available values are:
•

1: Snapshot requests are allowed. If not present, a value of 1 is assumed.

•

0: Snapshot requests are not allowed.

If present, a flags value of
ServiceInfoFlags.HAS_SUPPORT_OOB_SNAPSHOTS should be specified.
supportsQosRange

Optional. Indicates whether this service supports specifying a range of Qualities of
Service when requesting an item. For further information, refer to the qos and
worstQos members of the RequestMsg in the Transport API Java Edition Developers
Guide. Available values are:
•

1: QoS Range requests are supported.

•

0: QoS Range requests are not supported. If not present, a value of 0 is assumed.

If present, a flags value of ServiceInfoFlags.HAS_SUPPORT_QOS_RANGE
should be specified.
vendor

Optional. Identifies the vendor of the data.
If present, a flags value of ServiceInfoFlags.HAS_VENDOR should be specified.

Table 122: ServiceInfo Members (Continued)

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

117

Chapter 7

7.4.8.2

Administration Domain Models Detailed View

Service Info Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

ServiceInfoFlags.HAS_ACCEPTING_CONS_STATUS

Indicates the presence of acceptingConsumerStatus.

ServiceInfoFlags.HAS_DICTS_PROVIDED

Indicates the presence of dictionariesProvidedList.

ServiceInfoFlags.HAS_DICTS_USED

Indicates the presence of dictionariesUsedList.

ServiceInfoFlags.HAS_IS_SOURCE

Indicates the presence of isSource.

ServiceInfoFlags.HAS_ITEM_LIST

Indicates the presence of itemList.

ServiceInfoFlags.HAS_QOS

Indicates the presence of qosList.

ServiceInfoFlags.HAS_SUPPORT_OOB_SNAPSHOTS Indicates the presence of supportsOutOfBandSnapshots.
ServiceInfoFlags.HAS_SUPPORT_QOS_RANGE

Indicates the presence of supportsQosRange.

ServiceInfoFlags.HAS_VENDOR

Indicates the presence of vendor.

Table 123: ServiceInfo Flags

7.4.8.3

Service Info Methods

METHOD NAME

DESCRIPTION

clear

Clears a ServiceInfo object. Useful for object reuse.

copy

Performs a deep copy of a ServiceInfo object.

Table 124: ServiceInfo Utility Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

118

Chapter 7

7.4.9

Administration Domain Models Detailed View

Directory Service State Filter

A ServiceState object conveys information about service’s current state. It represents the Source Directory State filter. For
more information about the State filter, refer to the Transport API Java Edition RDM Usage Guide.

7.4.9.1

Service State Members

MEMBER
acceptingRequests

DESCRIPTION
Indicates whether the immediate provider (to which the consumer is directly
connected) can handle the request. Available values are:
•

1: The service will accept new requests.

•

0: The service does not currently accept new requests.

If present, flags value of ServiceStateFlags.HAS_ACCEPTING_REQS should be
specified.
action

Required. Indicates how a cache of the service state should apply this information.
For details on FilterEntryActions, refer to the Transport API Java Edition
Developers Guide .

flags

Required. Indicates the presence of optional service state members.
For details refer to Section 7.4.9.2.

serviceState

status

Required. Indicates whether the original provider of the data can respond to new
requests. Requests can still be made if so indicated by acceptingRequests.
Available values are:
•

1: The original provider of the data is available.

•

0: The original provider of the data is not currently available.

This status should be applied to all open items associated with this service.
If present, flags value of ServiceStateFlags.HAS_STATUS should be specified.

Table 125: ServiceState Members

7.4.9.2

Service State Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

ServiceStateFlags.HAS_ACCEPTING_REQS Indicates the presence of acceptingRequests.
ServiceStateFlags.HAS_STATUS

Indicates the presence of status.

Table 126: ServiceState Flags

7.4.9.3

Service State Methods

METHOD NAME

DESCRIPTION

clear

Clears a ServiceState object. Useful for object reuse.

copy

Performs a deep copy of a ServiceState object.

Table 127: ServiceState Utility Methods
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

119

Chapter 7

7.4.10

Administration Domain Models Detailed View

Directory Service Group Filter

A ServiceGroup object is used to convey status and name changes for an item group. It represents the Source Directory
Group filter. For further details about the Group filter, refer to the Transport API Java Edition RDM Usage Guide.

7.4.10.1

Service Group Members

MEMBER

DESCRIPTION

action

Required. Indicates how a cache of the service group should apply this information.
For further details on FilterEntryActions, refer to the Transport API Java Edition
Developers Guide.

flags

Required. Indicates the presence of optional service group members. For details,
refer to Section 7.4.10.2.

group

Required. Identifies the name of the item group being changed.

mergedToGroup

Optional. Specifies the new group name. All items of the specified group are put into
this new group.
If present, a flags value of ServiceGroupFlags.HAS_MERGED_TO_GROUP
should be specified.

status

Optional.Specifies the status to apply to all open items associated with the group
specified by group.
If present, a flags value of ServiceGroupFlags.HAS_STATUS should be specified.

Table 128: ServiceGroup Members

7.4.10.2

Service Group Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

ServiceGroupFlags.HAS_MERGED_TO_GROUP Indicates the presence of mergedToGroup.
ServiceGroupFlags.HAS_STATUS

Indicates the presence of status.

Table 129: ServiceGroup Flags

7.4.10.3

Service Group Methods

METHOD NAME

DESCRIPTION

clear

Clears an ServiceGroup object. Useful for object reuse.

copy

Performs a deep copy of a ServiceGroup object.

Table 130: ServiceGroup Utility Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

120

Chapter 7

7.4.11

Administration Domain Models Detailed View

Directory Service Load Filter

A ServiceLoad object conveys the workload of a service. It represents the Source Directory Load filter. For further details on
the Service Load filter, refer to the Transport API Java Edition RDM Usage Guide.

7.4.11.1

Service Load Members

MEMBER
action

DESCRIPTION
Required. Indicates how a cache of the service load should apply this information.
For information on FilterEntryActions, refer to the Transport API Java Edition
Developers Guide.

flags

Required. Indicates presence of optional service load members.
For details, refer to Section 7.4.11.2.

loadFactor

If present, flags value of ServiceLoadFlags.HAS_LOAD_FACTOR should be specified.
Indicates the current workload on the source that provides data. A higher load factor
indicates a higher workload.
For more information, refer to the Transport API Java Edition RDM Usage Guide.

openLimit

Specifies the maximum number of streaming requests that the service allows.
If present, flags value of ServiceLoadFlags.HAS_OPEN_LIMIT should be specified.

openWindow

Specifies the maximum number of outstanding requests (i.e., requests awaiting a refresh)
that the service allows.
If present, flags value of ServiceLoadFlags.HAS_OPEN_WINDOW should be specified.

Table 131: ServiceLoad Members

7.4.11.2

Service Load Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

ServiceLoadFlags.HAS_LOAD_FACTOR

Indicates the presence of loadFactor.

ServiceLoadFlags.HAS_OPEN_LIMIT

Indicates the presence of openLimit.

ServiceLoadFlags.HAS_OPEN_WINDOW Indicates the presence of openWindow.
Table 132: ServiceLoad Flags

7.4.11.3

Service Load Methods

METHOD NAME

DESCRIPTION

clear

Clears an ServiceLoad object. Useful for object reuse.

copy

Performs a deep copy of a ServiceLoad object.

Table 133: ServiceLoad Utility Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

121

Chapter 7

7.4.12

Administration Domain Models Detailed View

Directory Service Data Filter

An ServiceData object conveys the data to apply to all items of a service. It represents the Source Directory Data filter. For
further details on the Data filter, refer to the Transport API Java Edition RDM Usage Guide.

7.4.12.1

Service Data Members

MEMBER
action

DESCRIPTION
Required. Indicates how a cache of the service data should apply this information.
For further details on FilterEntryActions, refer to the Transport API Java Edition Developers
Guide.

data

Optional. Contains the encoded Buffer representing the data. The type of the data is given by
dataType.
If present, a flags value of ServiceDataFlags.HAS_DATA should be specified.

dataType

Optional. Specifies the DataType of the data. For information on DataTypes, refer to the Transport
API Java Edition Developers Guide.
If present, a flags value of ServiceDataFlags.HAS_DATA should be specified.

flags

Required. Indicates the presence of optional service data members.
For details, refer to Section 7.4.12.2.

type

Optional. Indicates the type of content present in data. Available enumerations are:
•

Directory.DataTypes.TIME = 1

•

Directory.DataTypes.ALERT = 2

•

Directory.DataTypes.HEADLINE = 3

•

Directory.DataTypes.STATUS = 4

If present, flags value of ServiceDataFlags.HAS_DATA should be specified.
Table 134: ServiceData Members

7.4.12.2

Service Load Data Enumeration Values

FLAG ENUMERATION
ServiceDataFlags.HAS_DATA

DESCRIPTION
Indicates the presence of type, dataType, and data.

Table 135: ServiceData Flags

7.4.12.3

Service Data Methods

METHOD NAME

DESCRIPTION

clear

Clears a ServiceData object. Useful for object reuse.

copy

Performs a deep copy of a ServiceData object.

Table 136: ServiceData Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

122

Chapter 7

7.4.13

Administration Domain Models Detailed View

Directory Service Link Info Filter

A ServiceLinkInfo object conveys information about upstream sources that form a service. It represents the Source
Directory Link filter. More information about the Service Link filter content is available in the Transport API Java Edition RDM
Usage Guide.
The ServiceLinkInfo object contains a list of ServiceLink objects that each represents an upstream source.

7.4.13.1

Service Link Info Members

MEMBER

DESCRIPTION

action

Required. Indicates how a cache of the service link information should apply this
information. For further information on FilterEntryActions, refer to the Transport API
Java Edition Developers Guide.

linkList

Optional. Contains a list of ServiceLink objects, each representing a source.

Table 137: ServiceLinkInfo Members

7.4.13.2

Service Link Info Methods

METHOD NAME

DESCRIPTION

clear

Clears a ServiceLinkInfo object. Useful for object reuse.

copy

Performs a deep copy of a ServiceLinkInfo object.

Table 138: ServiceLinkInfo Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

123

Chapter 7

7.4.14

Administration Domain Models Detailed View

Directory Service Link

A ServiceLink object conveys information about an upstream source. It represents an entry in the Source Directory Link filter
and is used by the linkList member of the ServiceLinkInfo object. For further details on Service Link filter content, refer to
the Transport API Java Edition RDM Usage Guide.

7.4.14.1

Service Link Members

MEMBER
action

DESCRIPTION
Required. Indicates how a cache of the service link should apply this information.
For information on MapEntryActions, refer to the Transport API Java Edition Developers
Guide.

flags

Required. Indicates the presence of optional service link members. For details, refer to
Section 7.4.14.2.

linkCode

Optional. Indicates additional information about the status of a source. Available
enumerations are:
•

Directory.LinkCodes.NONE = 0

•

Directory.LinkCodes.OK = 1

•

Directory.LinkCodes.RECOVERY_STARTED = 2

•

Directory.LinkCodes.RECOVERY_COMPLETED = 3

If present, a flags value of ServiceLinkFlags.HAS_CODE should be specified.
linkState

Required. Indicates whether the source is up or down.
Available values are:

name

•

Directory.LinkStates.DOWN = 0

•

Directory.LinkStates.UP = 1

Required. Specifies the name of the source.
Sources with identical names are typically load-balanced sources.

text

Optional. Gives additional status details regarding the source.
If present, a flags value of ServiceLinkFlags.HAS_TEXT should be specified.

type

Optional. Specifies whether the source is interactive or broadcast. Available enumerations
are:
•

Directory.LinkTypes.INTERACTIVE = 1

•

Directory.LinkTypes.BROADCAST = 2

If present, a flags value of ServiceLinkFlags.HAS_TYPE should be specified.
Table 139: ServiceLink Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

124

Chapter 7

7.4.14.2

Administration Domain Models Detailed View

Service Link Enumeration Values

FLAG ENUMERATION

DESCRIPTION

ServiceLinkFlags.HAS_CODE

Indicates the presence of code.

ServiceLinkFlags.HAS_TEXT

Indicates the presence of text.

ServiceLinkFlags.HAS_TYPE

Indicates the presence of type.

Table 140: ServiceLink Flags

7.4.14.3

Service Link Methods

METHOD NAME

DESCRIPTION

clear

Clears a ServiceLink object. Useful for object reuse.

copy

Performs a deep copy of a ServiceLink object.

Table 141: ServiceLink Methods

7.4.15

Directory Message

DirectoryMsg is the general purpose base interface for all directory messages. Different directory messages are summarized
in the following table.

INTERFACE

DESCRIPTION

DirectoryClose

RDM Directory Close.

DirectoryConsumerConnectionStatus

RDM Directory Consumer Status.

DirectoryRefresh

RDM Directory Refresh.

DirectoryRequest

RDM Directory Request.

DirectoryStatus

RDM Directory Status.

DirectoryUpdate

RDM Directory Update.

Table 142: DirectoryMsg Interfaces

7.4.16

Directory Message Utility Methods

METHOD NAME
copy

DESCRIPTION
Performs a deep copy of a DirectoryMsg object.

Table 143: DirectoryMsg Utility Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

125

Chapter 7

7.4.17

Directory Encoding and Decoding

7.4.17.1

Directory Encoding and Decoding Methods
METHOD NAME

Administration Domain Models Detailed View

DESCRIPTION

encode

Encodes a source directory message. This method takes the EncodeIterator as
a parameter into which the encoded content is populated.

decode

Decodes a source directory message. The decoded message may refer to
encoded data from the original message. If the message is to be stored for later
use, use the copy method of the decoded message to create a full copy.

Table 144: Directory Encoding and Decoding Methods

7.4.17.2

Encoding a Source Directory Request

EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
DirectoryRequest directoryRequest = (DirectoryRequest)DirectoryMsgFactory.createMsg();
/* Clear the Directory Request object. */
directoryRequest.clear();
/* Set directory message type – required as object created by DirectoryMsgFactory.createMsg() is generic
Directory object. */
directoryRequest.rdmMsgType(DirectoryMsgType.REQUEST);
/* Set stream id. */
directoryRequest.streamId(streamId);
/* Set flags indicating presence of optional members. */
directoryRequest.flags(DirectoryRequestFlags.HAS_SERVICE_ID | STREAMING);
/* Set Service ID. */
directoryRequest.serviceId(273);
/* Set service filter. */
directoryRequest.filter(Directory.ServiceFilterFlags.INFO | Directory.ServiceFilterFlags.STATE |
Directory.ServiceFilterFlags.GROUP);
/* Clear the encode iterator, set its RWF Version, and set it to a buffer for encoding into. */
encodeIter.clear();
ret = encodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Encode the message. */
ret = directoryRequest.encode(encodeIter);

Code Example 23: Directory Request Encoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

126

Chapter 7

7.4.17.3

Administration Domain Models Detailed View

Decoding a Source Directory Request

DecodeIterator decodeIter = CodecFactory.createDecodeIterator();
DirectoryRequest directoryRequest = (DirectoryRequest)DirectoryMsgFactory.createMsg();
Msg msg = CodecFactory.createMsg();
/* Clear the decode iterator, set its RWF Version, and set it to the encoded buffer. */
decodeIter.clear();
ret = decodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Decode the message to a Msg object. */
ret = msg.decode(decodeIter);
if (ret == CodecReturnCodes.SUCCESS &&
msg.domainType() == DomainTypes.SOURCE && msg.msgClass() ==
{
directoryRequest.clear();
directoryRequest.rdmMsgType(DirectoryMsgType.REQUEST);

MsgClasses.REQUEST)

ret = directoryRequest.decode(decodeIter, msg);
if(ret == CodecReturnCodes.SUCCESS)
{
/* Print if Info filter was requested. */
if ((directoryRequest.filter() & Directory.ServiceFilterFlags.INFO) != 0)
System.out.println("Info filter requested.");
/* Print if State filter was requested. */
if ((directoryRequest.filter() & Directory.ServiceFilterFlags.STATE) != 0)
System.out.println("State filter requested.");
/* Print if Group filter was requested. */
if ((directoryRequest.filter() & Directory.ServiceFilterFlags.GROUP) != 0)
System.out.println("Group filter requested.");
/* Print service ID if present. */
if (directoryRequest.checkHasServiceId())
System.out.println("Service ID: “ + directoryRequest->serviceId);
}
}

Code Example 24: Directory Request Decoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

127

Chapter 7

7.4.17.4

Administration Domain Models Detailed View

Encoding a Source Directory Refresh

EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
DirectoryRefresh directoryRefresh = (DirectoryRefresh)DirectoryMsgFactory.createMsg();
/* Clear the Directory Refresh object. */
directoryRefresh.clear();
/* Set directory message type – required as object created by DirectoryMsgFactory.createMsg() is generic
Directory object. */
directoryRefresh.rdmMsgType(DirectoryMsgType.REFRESH);
/* Set stream id. */
directoryRefresh.streamId(streamId);
/* Set flags for optional members */
directoryRefresh.applySolicited();
/* Set state. */
directoryRefresh.state().streamState(StreamStates.OPEN);
directoryRefresh.state().dataState(DataStates.OK);
directoryRefresh.state().code(StateCodes.NONE);
/* Set filter to say the Info, State, and Group filters are supported. */
directoryRefresh.filter(Directory.ServiceFilterFlags.INFO | Directory.ServiceFilterFlags.STATE |
Directory.ServiceFilterFlags.GROUP);
/* List of services to be used.
* This example will show encoding of one service. Additional services can be set up using the same method
* shown below. */
/*** Create Service ***/
Service service = CodecFactory.createService();
/*** Build Service MY_SERVICE. ***/
service.clear();
/* Set flags to indicate Info and State filter are present. */
service.flags(ServiceFlags.HAS_INFO | ServiceFlags.HAS_STATE);
/* Set action to indicate adding a new service. */
service.info().action(MapEntryActions.ADD);
/* Set flags to indicate optional members. */
service.info().flags(ServiceInfoFlags.HAS_VENDOR | ServiceInfoFlags.HAS_DICTS_PROVIDED |
ServiceInfoFlags. HAS_DICTS_USED | ServiceInfoFlags.HAS_QOS);
/* Set service name. */
service.info().serviceName().data("MY_SERVICE");
/* Set vendor name. */
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

128

Chapter 7

Administration Domain Models Detailed View

service.info().vendor().data("Thomson Reuters");
/* Set capabilities list. */
service.info().capabilitiesList().add(DomainTypes.DICTIONARY);
service.info().capabilitiesList().add(DomainTypes.MARKET_PRICE);
service.info().capabilitiesList().add(DomainTypes.MARKET_BY_ORDER);
/* Set dictionaries provided. */
service.info().dictionariesProvidedList().add("RWFFld");
service.info().dictionariesProvidedList().add("RWFEnum");
/* Set dictionaries used. */
service.info().dictionariesUsedList ().add("RWFFld");
service.info().dictionariesUsedList ().add("RWFEnum");
/* Build QoS list. */
Qos qos1 = CodecFactory.createQos();
qos1.timeliness(QosTimeliness.REALTIME);
qos1.rate(QosRates.TICK_BY_TICK);
Qos qos2 = CodecFactory.createQos();
service.info().qosList().add(qos2);
qos2.timeliness(QosTimeliness.REALTIME);
qos2.rate(QosRates.JIT_CONFLATED);
/* Set QoS list. */
service.info().qosList().add(qos1);
service.info().qosList().add(qos2);
/*** Build Service State for MY_SERVICE ***/
service.state().flags(ServiceStateFlags.HAS_ACCEPTING_REQS);
service.state().serviceState(1);
service.state().acceptingRequests(1);
/*** Finish and encode. ***/
/* Set the list of services on the message.*/
directoryRefresh.serviceList().add(service);
/* Clear the encode iterator, set its RWF Version, and set it to a buffer for encoding into. */
encodeIter.clear();
ret = encodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Encode the message. */
ret = directoryRefresh.encode(encodeIter);

Code Example 25: Directory Refresh Encoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

129

Chapter 7

7.4.17.5

Administration Domain Models Detailed View

Decoding a Source Directory Refresh

DecodeIterator decodeIter = CodecFactory.createDecodeIterator();
DirectoryRefresh directoryRefresh = (DirectoryRefresh)DirectoryMsgFactory.createMsg();
Msg msg = CodecFactory.createMsg();
/* Clear the decode iterator, set its RWF Version, and set it to the encoded buffer. */
decodeIter.clear();
ret = decodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Decode the message to a Msg object. */
ret = msg.decode(decodeIter);
if (ret == CodecReturnCodes.SUCCESS && msg.domainType() == DomainTypes.SOURCE && msg.msgClass() ==
MsgClasses.REFRESH)
{
directoryRefresh.clear();
directoryRefresh.rdmMsgType(DirectoryMsgType.REFRESH);
ret = directoryRefresh.decode(decodeIter, msg);
if(ret == CodecReturnCodes.SUCCESS)
{
/* Print serviceId if present. */
if (directoryRefresh.checkHasServiceId())
System.out.println("Service ID: “ + directoryRefresh.serviceId());
/* Print information about each service present in the refresh. */
for(Service service : directoryRefresh.serviceList())
{
/* Print Service Info if present */
if (service.checkHasInfo())
{
ServiceInfo info = service.info();
/* Print service name. */
System.out.println("Service Name: “ + info.serviceName().toString());
/* Print vendor name if present.*/
if (info.checkHasVendor())
System.out.println("Vendor: " + info.vendor().toString());
/* Print supported domains if present.*/
for(long capability : info.capabilityList())
System.out.println("Capability: " + DomainTypes.toString(capability));
/* Print dictionaries provided if present.*/
if (info.checkHasDictionariesProvided())
{
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

130

Chapter 7

Administration Domain Models Detailed View

for (String dictProv : info.dictionariesProvidedList())
System.out.println("Dictionary Provided: “ + dictProv);
}
/* Print dictionaries used if present. */
if (info.checkHasDictionariesUsed())
{
for (String dictUsed : info.dictionariesUsedList())
System.out.println("Dictionary Used: “ + dictUsed);
}
/* Print qualities of service supported if present. */
if (info.checkHasQos())
{
for (Qos qos : info.qosList())
System.out.println ("QoS: “ + qos.toString());
}
}
if (service.checkHasState())
{
ServiceState state = service.state();
System.out.println(“Service state: “ + state.serviceState());
if(state.checkHasAcceptingRequests())
System.out.println(“Accepting Requests: “ + state.acceptingRequests());
}
}
}
}

Code Example 26: Directory Refresh Decoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

131

Chapter 7

7.5

Administration Domain Models Detailed View

RDM Dictionary Domain

The Dictionary domain model conveys information needed for parsing published data. Dictionaries provide additional metadata, such as that necessary to decode the content of a FieldEntry or additional content related to its fieldId. For more
information about the different types of dictionaries and their usage, refer to the Transport API Java Edition RDM Usage Guide.
This domain’s interface makes it easier to use the existing utilities for encoding, decoding, and caching dictionary information.
For more information on these utilities, see the Transport API Java Edition RDM Usage Guide.

7.5.1

Dictionary Request

A Dictionary Request message is encoded and sent by OMM Consumer applications. This message requests a dictionary
from a service.
The DictionaryRequest represents all members of a dictionary request message and is easily used in OMM applications that
leverage RDM. This object follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.5.1.1

Dictionary Request Members

MEMBER

DESCRIPTION

dictionaryName

Required. Indicates the name of the dictionary being requested.

flags

Required. Indicates the presence of optional dictionary request members. For details,
refer to Section 7.5.1.2.

rdmMsgBase

Required. Specifies the message type (i.e., Dictionary). For a dictionary request, send
DictionaryMsgType.REQUEST.

serviceId

Required. Specifies the service from which to request the dictionary.

verbosity

Required. Indicates the amount of information desired from the dictionary. Available
enumerations are:
•

Dictionary.VerbosityValues.INFO = 0x00: Version information only

•

Dictionary.VerbosityValues.MINIMAL = 0x03: Provides information needed for
caching

•

Dictionary.VerbosityValues.NORMAL = 0x07: Provides all information needed for
decoding

•

Dictionary.VerbosityValues.VERBOSE = 0x0F: Provides all information (including
comments)

Providers are not required to support the MINIMAL and VERBOSE filters.
Table 145: DictionaryRequest Members

7.5.1.2

Dictionary Request Flag Enumeration Values

FLAG ENUMERATION
STREAMING

DESCRIPTION
Indicates that the dictionary stream should remain open after the initial refresh. An open
stream can listen for status messages that indicate changes to the dictionary version.
For more information, see the Transport API Java Edition RDM Usage Guide.

Table 146: DictionaryRequest Flag
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

132

Chapter 7

7.5.2

Administration Domain Models Detailed View

Dictionary Refresh

A Dictionary Refresh message is encoded and sent by OMM provider applications. This message transmits dictionary
content in response to a request.
The DictionaryRefresh represents all members of a dictionary refresh message and is easy to use in OMM applications that
leverage RDM. This object follows the behavior and layout that is defined in the Transport API Java Edition RDM Usage
Guide.

7.5.2.1

Dictionary Refresh Members

MEMBER
dataBody

DESCRIPTION
When decoding, this points to the encoded data buffer with dictionary content. This buffer
should be set on a DecodeIterator and passed to the appropriate decode method
according to the type.
Not used when encoding. The dictionary is retrieved from the DataDictionary.

dictionary

Conditional (required when encoding). Points to an DataDictionary object that
contains content to encode. For more information on the DataDictionary object, refer to
the Transport API Java Edition RDM Usage Guide.
Not used when decoding.

dictionaryName

Required. Indicates the name of the dictionary being provided.

flags

Required. Indicates the presence of optional dictionary refresh members. For details, refer
to Section 7.5.2.2.

rdmMsgBase

Required. Specifies the message type (i.e., dictionary message). For a dictionary refresh,
set to DictionaryMsgType.REFRESH.

sequenceNumber

Optional. A user-specified, item-level sequence number that the application can use to
sequence messages in this stream.
If present, a flags value of DictionaryRefreshFlags.HAS_SEQ_NUM should be
specified.

serviceId

Required. Indicates the service ID of the service from which the dictionary is provided.

startFid

Maintains the state when encoding a dictionary across multiple messages.
Warning! To ensure that all dictionary content is correctly encoded, the application
should not modify this.

state

Required. Indicates the state of the dictionary stream.
Defaults to a streamState of StreamStates.OPEN and a dataState of DataStates.OK.
For more information on State, refer to the Transport API Java Edition Developers Guide.

dictionaryType

Required. Indicates the type of dictionary being provided. The dictionary encoder and
decoder support the following types:
•

Dictionary.VerbosityValues.FIELD_DEFINITIONS = 1

•

Dictionary.VerbosityValues.ENUM_TABLES = 2

Table 147: DictionaryRefresh Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

133

Chapter 7

MEMBER
verbosity

Administration Domain Models Detailed View

DESCRIPTION
Required. Indicates the amount of information desired from the dictionary. Available
enumerations are:
•

Dictionary.VerbosityValues.INFO = 0x00: Provides version information only

•

Dictionary.VerbosityValues.MINIMAL = 0x03: Provides information needed for
caching

•

Dictionary.VerbosityValues.NORMAL = 0x07: Provides all information needed for
decoding

•

Dictionary.VerbosityValues.VERBOSE = 0x0F: Provides all information (including
comments)

Providers do not need to support the MINIMAL and VERBOSE filters.
Table 147: DictionaryRefresh Members (Continued)

7.5.2.2

Dictionary Refresh Flag Enumeration Values

FLAG ENUMERATION

DESCRIPTION

DictionaryRefreshFlags.CLEAR_CACHE Indicates that stored payload information associated with the dictionary stream
should be cleared. This might happen if some portion of data is known to be
invalid.
DictionaryRefreshFlags.HAS_INFO

Indicates the presence of dictionaryType.
Not used when encoding. The encode method adds information to the encoded
message when appropriate.

DictionaryRefreshFlags.HAS_SEQ_NUM Indicates presence of sequenceNumber.
DictionaryRefreshFlags.IS_COMPLETE

Indicates that this is the final fragment and that the consumer has received all
content for this dictionary.
Not used when encoding. The encode method adds information to the encoded
message when appropriate.

DictionaryRefreshFlags.SOLICITED

Indicates that the directory refresh is solicited (e.g., it is a response to a request).
If the flag is not present, this refresh is unsolicited.

Table 148: DictionaryRefreshFlags

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

134

Chapter 7

7.5.3

Administration Domain Models Detailed View

Dictionary Status

OMM provider and non-interactive provider applications use the Dictionary Status message to convey state information
associated with the dictionary stream. Such state information can indicate that a dictionary stream cannot be established or to
inform a consumer of a state change associated with an open dictionary stream. The Dictionary status message can also
indicate that a new dictionary should be retrieved. For more information on handling Dictionary versions, see the Transport API
Java Edition RDM Usage Guide.
The DictionaryStatus represents all members of a dictionary status message and allows for simplified use in OMM
applications that leverage RDM. This object follows the behavior and layout that is defined in the Transport API Java Edition
RDM Usage Guide.

7.5.3.1

Dictionary Status Members

MEMBER
flags

DESCRIPTION
Required. Indicate the presence of optional dictionary status members.
For details, refer to Section 7.5.3.2.

rdmMsgBase

Required. Specifies the dictionary message type. For a dictionary status, set to
DictionaryMsgType.STATUS.

state

Optional. Indicates the state of the dictionary stream. For more information on State, refer
to the Transport API Java Edition Developers Guide.
If present, a flags value of DictionaryStatusFlags.HAS_STATE should be specified.

Table 149: DictionaryStatus Members

7.5.3.2

Dictionary Status Flag Enumeration Value

FLAG ENUMERATION

DESCRIPTION

DictionaryStatusFlags.CLEAR_CACHE

Indicates that any stored payload information associated with the dictionary stream
should be cleared. This might happen if some portion of data is known to be
invalid.

DictionaryStatusFlags.HAS_STATE

Indicates the presence of state. If absent, any previously conveyed state
continues to apply.

Table 150: DictionaryStatus Flags

7.5.4

Dictionary Close

A Dictionary Close message is encoded and sent by OMM consumer applications. This message allows a consumer to close
an open dictionary stream. A provider can close the directory stream via a Dictionary Status message; for details, refer to
Section 7.5.3.
MEMBER
rdmMsgBase

DESCRIPTION
Required. Specifies the dictionary message type. For a dictionary close, set to
DictionaryMsgType.CLOSE.

Table 151: DictionaryClose Member

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

135

Chapter 7

7.5.5

Administration Domain Models Detailed View

Dictionary Messages

DictionaryMsg is the base interface for all Dictionary messages. It is provided for use with general dictionary-specific

functionality.
INTERFACE

DESCRIPTION

DictionaryClose

RDM Dictionary Close.

DictionaryRefresh

RDM Dictionary Refresh.

DictionaryRequest

RDM Dictionary Request.

DictionaryStatus

RDM Dictionary Status.

Table 152: DictionaryMsg Interfaces

7.5.6

Dictionary Message: Utility Methods
FUNCTION NAME

copy

DESCRIPTION
Performs a deep copy of a DictionaryMsg object.

Table 153: DictionaryMsg Utility Methods

7.5.7

Dictionary Encoding and Decoding

7.5.7.1

Dictionary Encoding and Decoding Methods
METHOD NAME

DESCRIPTION

encode

Encodes a dictionary message. This method takes the EncodeIterator as a parameter
into which the encoded content is populated.

decode

Decodes a dictionary message. The decoded message may refer to encoded data from
the original message. If the message is to be stored for later use, use the copy method of
the decoded message to create a full copy.

Table 154: Dictionary Encoding and Decoding Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

136

Chapter 7

7.5.7.2

Administration Domain Models Detailed View

Encoding a Dictionary Request

EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
DictionaryRequest dictionaryRequest = (DictionaryRequest)DictionaryMsgFactory.createMsg();
/* Clear the Dictionary Request object. */
dictionaryRequest.clear();
/* Set dictionary message type – required as object created by DictionaryMsgFactory.createMsg() is
generic Dictionary object. */
dictionaryRefresh.rdmMsgType(DictionaryMsgType.REQUEST);
/* Set stream id. */
dictionaryRefresh.streamId(streamId);
/* Set streaming flag. */
dictionaryRequest.applyStreaming();
/* Set serviceId. */
dictionaryRequest.serviceId(273);
/* Set verbosity. */
dictionaryRequest.verbosity(Dictionary.VerbosityValues.NORMAL);
/* Set dictionary name. */
dictionaryRequest.dictionaryName().data("RWFFld");
/* Clear the encode iterator, set its RWF Version, and set it to a buffer for encoding into. */
encodeIter.clear();
ret = encodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Encode the message. */
ret = dictionaryRequest.encode(encodeIter);

Code Example 27: Dictionary Request Encoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

137

Chapter 7

7.5.7.3

Administration Domain Models Detailed View

Decoding a Dictionary Request

DecodeIterator decodeIter = CodecFactory.createDecodeIterator();
DictionaryRequest dictionaryRequest = (DictionaryRequest)DictionaryMsgFactory.createMsg();
Msg msg = CodecFactory.createMsg();
/* Clear the decode iterator, set its RWF Version, and set it to the encoded buffer. */
decodeIter.clear();
ret = decodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Decode the message to a Msg object. */
ret = msg.decode(decodeIter);
if (ret == CodecReturnCodes.SUCCESS && msg.domainType() == DomainTypes.DICTIONARY && msg.msgClass() ==
MsgClasses.REQUEST)
{
dictionaryRequest.clear();
/* Set dictionary message type – required as object created by DictionaryMsgFactory.createMsg() is
generic Dictionary object. */
dictionaryRequest.rdmMsgType(DictionaryMsgType.REQUEST);
ret = dictionaryRequest.decode(decodeIter, msg);
if(ret == CodecReturnCodes.SUCCESS)
{
if(dictionaryRequest.checkStreaming())
System.out.println(“Request is streaming”);
/* Print serviceId. */
System.out.println ("Service ID: “ + dictionaryRequest.serviceId());
/* Print verbosity. */
System.out.println ("Verbosity: “ + dictionaryRequest.verbosity());
/* Print dictionary name. */
System.out.println ("Dictionary Name: “ + dictionaryRequest.dictionaryName().toString());
}
}

Code Example 28: Dictionary Request Decoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

138

Chapter 7

7.5.7.4

Administration Domain Models Detailed View

Encoding a Dictionary Refresh

EncodeIterator encodeIter = CodecFactory.createEncodeIterator();
DictionaryRefresh dictionaryRefresh = (DictionaryRefresh)DictionaryMsgFactory.createMsg();
/* Clear the Dictionary Refresh object. */
dictionaryRefresh.clear();
dictionaryRefresh.rdmMsgType(DictionaryMsgType.REFRESH);
DataDictionary dataDictionary = CodecFactory.createDataDictionary();
dataDictionary.clear();
ret = dataDictionary.loadFieldDictionary("RDMFieldDictionary", errorText);
/* Clear the Dictionary Refresh object. */
dictionaryRefresh.clear();
/* Set dictionary message type – required as object created by DictionaryMsgFactory.createMsg() is
generic Dictionary object. */
dictionaryRefresh.rdmMsgType(DictionaryMsgType.REFRESH);
/* Set stream id. */
dictionaryRefresh.streamId(streamId);
/* Set state fields to state object managed by dictionary refresh. */
dictionaryRefresh.state().streamState(StreamStates.OPEN);
dictionaryRefresh.state().dataState(DataStates.OK);
dictionaryRefresh.state().code(StateCodes.NONE);
/* Set flags. */
dictionaryRefresh.applySolicited();
/* Set dictionary name. */
dictionaryRefresh.dictionaryName().data("RWFFld");
/* Set dictionary type. */
dictionaryRefresh.dictionaryType(Dictionary.Types.FIELD_DEFINITIONS);
/* Set the dictionary. */
dictionaryRefresh.dictionary(dataDictionary);
/* Set serviceId. */
dictionaryRefresh.serviceId(273);
/* Set verbosity. */
dictionaryRefresh.verbosity(Dictionary.VerbosityValues.NORMAL);
do
{
Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

139

Chapter 7

Administration Domain Models Detailed View

/* (Represents the application getting a new buffer to encode the message into.) */
getNextEncodeBuffer(msgBuffer);
/* Clear the encode iterator, set its RWF Version, and set it to a buffer for encoding into. */
encodeIter.clear();
ret = encodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Encode the message. This will return CodecReturnCodes.DICT_PART_ENCODED if it only a part
* was encoded. We must keep encoding the message until CodecReturnCodes.SUCCESS is returned. */
ret = dictionaryRefresh.encode(encodeIter);
} while (ret == CodecReturnCodes.DICT_PART_ENCODED);

Code Example 29: Dictionary Refresh Encoding Example

7.5.7.5

Decoding a Dictionary Refresh

DecodeIterator decodeIter = CodecFactory.createDecodeIterator();
DictionaryRefresh dictionaryRefresh = (DictionaryRefresh)DictionaryMsgFactory.createMsg();
Msg msg = CodecFactory.createMsg();
DataDictionary dataDictionary = CodecFactory.createDataDictionary();
dataDictionary.clear();
int dictionaryTypeForThisStreamId = 0;
do
{
/* (Represents the application getting the next buffer to decode.) */
getNextDecodeBuffer(msgBuf);
/* Clear the decode iterator, set its RWF Version, and set it to the encoded buffer. */
decodeIter.clear();
ret = decodeIter.setBufferAndRWFVersion(msgBuf,channelMajorVersion, channelMinorVersion);
/* Decode the message to a Msg object. */
sret = msg.decode(decodeIter);
if (ret == CodecReturnCodes.SUCCESS && msg.domainType() == DomainTypes.DICTIONARY && msg.msgClass()
== MsgClasses.REFRESH)
{
dictionaryRefresh.clear();
/* Set dictionary message type – required as object created by DictionaryMsgFactory.createMsg()
is generic Dictionary object. */
dictionaryRefresh.rdmMsgType(DictionaryMsgType.REFRESH);
ret = dictionaryRefresh.decode(decodeIter, msg);
if(ret == CodecReturnCodes.SUCCESS)

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

140

Chapter 7

Administration Domain Models Detailed View

{
/* Print if request is streaming. */
if (dictionaryRefresh.checkSolicited())
System.out.println("Refresh is solicited.");
/* Print info if present. If the dictionary is split into parts, this is normally only
present on the first part. */
if (dictionaryRefresh.checkHasInfo())
{
/* Remember the dictionary type for this stream since subsequent parts will not indicate
it. */
dictionaryTypeForThisStreamId = dictionaryRefresh.dictionaryType();
/* Print version. */
System.out.println("Version: “ + dictionaryRefresh.version.toString());
/* Print dictionary ID. */
System.out.println("Dictionary ID: " + dictionaryRefresh.dictionaryId());
}
/* Print serviceId. */
System.out.println("Service ID: " + dictionaryRefresh.serviceId());
/* Print verbosity. */
System.out.println("Verbosity: " + dictionaryRefresh.verbosity());
/* Print dictionary name. */
System.out.println("Dictionary Name: " + dictionaryRefresh.dictionaryName().toString());
if (dictionaryTypeForThisStreamId == Dictionary.Types.FIELD_DEFINITIONS)
{
/* Decode the dictionary content into the DataDictionary object. */
decodeIter.clear();
ret = decodeIter.setBufferAndRWFVersion(dictionaryRefresh.dataBody(),
channelMajorVersion, channelMinorVersion);
ret = dataDictionary.decodeFieldDictionary(decodeIter,
Dictionary.VerbosityValues.NORMAL, errorText);
}
}
}
} while(!(dictionarRefresh.checkRefreshComplete());

Code Example 30: Dictionary Refresh Decoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

141

Chapter 7

7.6

Administration Domain Models Detailed View

RDM Queue Messages

The Queue Messaging domain model is a series of message constructs that you use to interact with a Queue Provider. A
Queue Provider can persist content for which users want to have guaranteed delivery and can also help send content to
destinations with which users cannot directly communicate.

7.6.1

Queue Data Message Persistence

When opening a queue messaging stream with a queue provider, using a persistence file can guarantee delivery of messages
sent by the OMM consumer on that queue stream. The queue file will be named after the name of the queue stream (as
specified in the QueueRequest message that opened the stream). When the consumer submits QueueData messages, the
consumer stores these messages in the persistence file in case the tunnel stream to the queue provider is lost and
reconnected. As QueueAck messages are received from the queue provider, space in the persistence file is freed for additional
messages. If at any time the application submits an QueueData message but the persistence file has no room for it, the
application receives the ReactorReturnCodes.PERSISTENCE_FULL return code.
The ClassOfService.guarantee.persistLocally option (set when opening the tunnel stream) specifies whether to create
and maintain persistence files. The location for storage of persistent files is specified by the
ClassOfService.guarantee.persistenceFilePath option. For more information on these options, refer to Section 6.7.3.
Note: Thomson Reuters recommends that the ClassOfService.guarantee.persistenceFilePath be set to a local storage
device.
If a particular queue stream is no longer needed, the user may delete the persistence file that carries the associated queue
stream’s name.
Warning! If you delete a persistence file that stores messages that were not successfully transmitted, the messages
will be lost.

7.6.2

Queue Request

The OMM application encodes and sends a Queue Request message to a Queue Provider to open a user queue. By opening
a queue with an QueueRequest, the user receives any content previously sent to and persisted on a Queue Provider. To send
content to another user’s queue, a user must first open their own queue.
MEMBER

DESCRIPTION

rdmMsgBase

Required. Specifies the message type. For a queue request, use QueueMsgType.REQUEST.

sourceName

Required. Specifies the name of the queue you want to open.

Table 155: QueueRequest Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

142

Chapter 7

7.6.3

Administration Domain Models Detailed View

Queue Refresh

A Queue Provider encodes and sends a Queue Refresh message to OMM applications to inform users about queue open
requests and give state information pertaining to specific queue refresh request attempts.
MEMBER

DESCRIPTION

rdmMsgBase

Required. Sets the message type. For a queue refresh, use QueueMsgType.REFRESH.

sourceName

Required. Specifies the name of a queue you want to open.

state

Required. Indicates the state of the queue.
•

States of Open and Ok indicate the queue was successfully opened.

•

Other state combinations indicate an issue, for which additional code and text provide
supplemental information.

For more information on State, refer to the Transport API Java Edition Developers Guide.
queueDepth

Required. Indicates the number of messages remaining in the queue for this stream.

Table 156: QueueRefresh Members

7.6.4

Queue Status

A Queue Provider encodes and sends Queue Status messages to OMM applications, conveying state information about a
user’s queue.
MEMBER
flags

DESCRIPTION
Required. Indicates the presence of optional queue status members.
flags has only one enumeration: HAS_STATE, which indicates the presence of the state
member. If flags is absent (or has no value), any previously conveyed state continues to apply.

rdmMsgBase
state

Required. Sets the message type. For a queue status, use QueueMsgType.STATUS.
Indicates the state of the queue:
•

States of Open and Ok indicate the queue is in a good state.

•

Other state combinations indicate an issue, for which additional code and text provide
supplemental information.

For more information on State, refer to the Transport API Java Edition Developers Guide.
Table 157: QueueStatus Members

7.6.5

Queue Close

An OMM application encodes and sends a Queue Close message to a Queue Provider, closing the user’s queue.
MEMBER
rdmMsgBase

DESCRIPTION
Required. Sets the message type. For a queue close, use QueueMsgType.CLOSE.

Table 158: QueueClose Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

143

Chapter 7

7.6.6

Administration Domain Models Detailed View

Queue Data

Both OMM applications and queue providers can send and receive Queue Data messages, which exchange data content
between queue users and also communicate whether content was undeliverable.

7.6.6.1

Queue Data Members

MEMBER

DESCRIPTION

containerType

Required. Indicates the type of contents in this queue data message.

destName

Required. Specifies the name of the queue to which content is sent.

encodedDataBody

Optional.
•

If sending a message, populate encodedDataBody with pre-encoded content. If sending a
message without pre-encoded contents, you can use the encoding methods described in
Section 7.6.6.4.

•

If receiving a message, encodedDataBody can be used to access payload contents for decoding.

flags

Required. Specifies any flags that indicate more information about this message. For further details
on available flags, refer to Section 7.6.6.2.

identifier

Required. A user-specified unique identifier for the message being sent. identifier is used when
acknowledging this content via a Queue Ack message.

queueDepth

Required. Indicates the number of Queue Data or Queue Data Expired messages still inbound on
this queue stream, following this message.

rdmMsgBase

Required. Sets the message type. For queue data, use QueueMsgType.DATA.

sourceName

Required. Specifies the name of the queue from which content is sourced, which should match the
sourceName specified in the Queue Request for this substream.

timeout

Optional. Specifies the desired timeout for this content (which can be any of the
QueueMsgTimeoutCodes in Section 7.6.6.3 or a specific time interval in milliseconds). If a timeout
value expires during the course of delivery, the content is returned as a QueueDataExpired
message.
If not specified, this defaults to QueueMsgTimeoutCodes.INFINITE (i.e., the content never times
out).

Table 159: QueueData Members

7.6.6.2

Queue Data Flag

QueueData messages and QueueDataExpired messages use the following flag:

FLAG
QueueDataFlags.POSSIBLE_DUPLICATE= 0x1

DESCRIPTION
Indicates that the message was retransmitted and that the application
might have already received it.

Table 160: Queue Data Flag

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

144

Chapter 7

7.6.6.3

Administration Domain Models Detailed View

Queue Message Timeout Codes

ENUMERATION

DESCRIPTION

INFINITE

This message persists in the system for an infinite amount of time.

IMMEDIATE

This message immediately times out if any portion of its delivery path is
unavailable.

PROVIDER_DEFAULT

This message persists in the system for a duration set by the provider.

Table 161: Queue Data Message Timeout Codes

7.6.6.4

Queue Data Encoding

METHOD NAME

DESCRIPTION

encode

When sending no payload or payload content is preencoded and specified on
the QueueData.encodedDataBody buffer, this method encodes the QueueData
message in a single call.

encodeComplete

Completes the content encoding into this QueueData message.

encodeInit

Begins the process of encoding content into this QueueData message. This
method takes an EncodeIterator as a parameter, where the EncodeIterator
is associated with the buffer into which content is encoded.
When this method returns, users should call additional methods required to
encode the content. After all remaining encoding is completed, call the
encodeComplete method.

Table 162: Queue Data Message Encoding Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

145

Chapter 7

7.6.6.5

Administration Domain Models Detailed View

Queue Data Message Encoding Code Sample

EncodeIterator _msgEncIter = CodecFactory.createEncodeIterator();
QueueData _queueData = QueueMsgFactory.createQueueData();
// initialize the QueueData encoding
_queueData.clear();
_queueData.streamId(QUEUE_MSG_STREAM_ID);
_queueData.identifier(124);
_queueData.sourceName().data(“MY_QUEUE”);
_queueData.destName().data(“DESTINATION_QUEUE”);
_queueData.timeout(QueueMsgTimeoutCodes.INFINITE);
_queueData.containerType(DataTypes.FIELD_LIST);
_msgEncIter.clear();
_msgEncIter.setBufferAndRWFVersion(buffer, tunnelStream.classOfService().common().
protocolMajorVersion(), tunnelStream.classOfService().common().protocolMinorVersion());
// begin encoding content into QueueData message
if ((ret = _queueData.encodeInit(_msgEncIter)) < ReactorReturnCodes.SUCCESS)
{
System.out.println("QueueData.encodeInit() failed”);
return;
}
// Start Content Encoding – follow standard field list encoding
// as shown in the Transport API Java Developers Guide examples
// when content encoding is done, complete the QueueData encoding
if ((ret = _queueData.encodeComplete(_msgEncIter)) < ReactorReturnCodes.SUCCESS)
{
System.out.println("QueueData.encodeComplete() failed”);
return;
}

Code Example 31: Queue Data Message Encoding Example

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

146

Chapter 7

7.6.7

Administration Domain Models Detailed View

QueueDataExpired

If queue data messages sent on a queue stream cannot be successfully delivered, the queue provider sends
QueueDataExpired messages on the queue stream to OMM consumer applications.
OMM consumer applications do not send this message.

7.6.7.1

QueueDataExpired Members

MEMBER

DESCRIPTION

containerType

Required. Indicates the type of contents in the message.

destName

Required. destName specifies the name of the queue from which content is sourced (i.e., the
value of sourceName as set in the original QueueData message).

encodedDataBody

Optional. Contains the payload contents (if any) of the original Queue Data message.

flags

Required. flags indicate more information about this message.
For details, refer to Section 7.6.6.2.

identifier

Required. A user-specified, unique identifier for the message (which is the same as the
identifier from the original QueueData message).

queueDepth

Required. Indicates how many Queue Data or Queue Data Expired messages are still inbound
on this queue stream (following this message).

rdmMsgBase

Required. Specifies the queue message type. For expired queue data, use
QueueMsgType.DATAEXPIRED.

sourceName

Required. sourceName specifies the name of the queue to which content was sent (i.e., the
value of destName as set in the original QueueData message).

undeliverableCode

Required. Specifies a code explaining why the content was undeliverable.
For more information on undeliverable codes and their meanings, refer to Section 7.6.7.2.

Table 163: QueueDataExpired Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

147

Chapter 7

7.6.7.2

Administration Domain Models Detailed View

Queue Data Message Undeliverable Codes

ENUMERATION

REASON FOR DELIVERY FAILURE

EXPIRED

Indicates that the timeout value specified for this message has expired.

INVALID_SENDER

Indicates that the sender of this message has now become invalid.

INVALID_TARGET

Indicates that the specified destination of this message does not exist.

MAX_MSG_SIZE

Indicates that the message was too large.

NO_PERMISSION

Indicates that the source/sender of this message is not permitted to send or is
not permitted to send to the specified destination.

QUEUE_DISABLED

Indicates that the specified destination of this message has a disabled queue.

QUEUE_FULL

Indicates that the specified destination of this message has a full queue and
cannot receive any additional content.

TARGET_DELETED

Indicates that the target queue was deleted after sending the message, but
before the message was delivered.

Table 164: Queue Data Message Undeliverable Codes

7.6.8

Queue Ack

A Queue Provider encodes and sends a Queue Ack message to OMM applications, acknowledging that a Queue Data
message is persisted on the Queue Provider. After a Queue Provider acknowledges persistence, the OMM application no
longer needs to persist the acknowledged content.
MEMBER
destName
identifier

DESCRIPTION
Required. Specifies the name of the queue from which content is sourced (i.e., the value of
sourceName as set in the original Queue Data message).
Required. The identifier of the message being acknowledged. This should match the
QueueData.identifier for the message being acknowledged.

sourceName

Required. Specifies the name of the queue to which content was originally sent (i.e., the value of
destName as set in the original Queue Data message).

rdmMsgBase

Required. Sets the message type. For a queue ack, this is set to QueueMsgType.ACK.

Table 165: Queue Ack Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

148

Chapter 8

Payload Cache Detailed View

Chapter 8 Payload Cache Detailed View
8.1

Concepts

The Value Added Payload Cache component provides a facility for storing OMM containers (the data payload of OMM
messages). Typical use of a payload cache is to store the current image of OMM data streams, where each entry in the cache
corresponds to a single data stream. The initial content of a cache entry is defined by the payload of a refresh message. The
current (or last) value of the entry is defined by the cumulative application of all refresh and update messages applied to the
cache entry container. Values are stored in and retrieved from the cache as encoded OMM containers.
A cache is defined as a collection of OMM data containers. An application may create multiple cache collections, or instances,
depending on how it wants to organize the data. The only restriction on cache organization is that all entries in a cache must
use the same RDM Field Dictionary to define the set of field definitions it will use. At minimum, a separate cache would be
required for each field dictionary in use by the application. However, because cache instances can also share the same field
dictionary, partitioning is not restricted to dictionary usage. Some examples of how cache instances can be organized in an
application include: all item streams on a connection; all items belonging to a particular service; all items across the entire
application.
The application is responsible for organizing cache instances, managing the lifecycle of all entries in each cache, and applying
and retrieving data from the cache. Figure 9 shows an example consumer type application which has created two cache
instances to store data from two services on an OMM provider.

Figure 9. Consumer Application using Cache to Store Payload Data for Item Streams

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

149

Chapter 8

8.2

Payload Cache Detailed View

Payload Cache

This section describes how the payload cache is managed (initialization and uninitialization), and how instances of cache
(collections of payload entries) are created and destroyed.

8.2.1

Payload Cache Management

After the first Value Added Payload Cache instance is created, all global static resources used by the cache are initialized.
When the application destroys the last cache instance, the cache releases all the resources it used.

8.2.2

Cache Error Handling

Some of the methods on the payload cache interface use the CacheError object to return error information. This object will be
populated with additional information if an error occurs during the method call. The application should check the return value
from methods. The application can optionally provide the CacheError object to obtain additional information.

8.2.2.1

Cache Error Class Members

The CacheError has the following class members:
CLASS MEMBER

DESCRIPTION

errorId

Specifies an error ID. The range of values is defined by the set of Transport API Codec return
codes (from the CodecReturnCodes enumeration).

text

This String will contain text with additional information when a method call returns a failed
result.

Table 166: CacheError Class Members

8.2.2.2

Clearing a Cache Error

The following method clears the CacheError.
METHOD NAME
clear

DESCRIPTION
Clears the CacheError object. Use this method prior to passing the object to a cache interface
method.

Table 167: CacheError Utility Method

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

150

Chapter 8

8.2.3

Payload Cache Detailed View

Payload Cache Instances

A payload cache instance is a collection of payload data containers. An empty cache instance must be created before any data
can be stored in the cache. When a cache or its entries are no longer needed, it can be destroyed. For methods used to create
and destroy a cache, refer to Section 8.2.3.1.

8.2.3.1

Managing the Payload Cache Instance
METHOD NAME

DESCRIPTION

CacheFactory.createPayloadCache Creates a payload cache instance. Options are passed in via the
PayloadCacheConfigOptions whose member is defined in Section 8.2.3.2.
destroy

Destroys a payload cache instance. Any entries remaining in the cache are also
destroyed at this time.

destroyAll

Destroys all payload cache instances. All entries remaining in the application are also
destroyed at this time.

Table 168: Methods for Managing Cache Instances

8.2.3.2

Payload Cache Config Options

MEMBER
maxItems

DESCRIPTION
Sets the maximum number of entries allowed in the cache. When the maximum number of
items is reached, the cache refuses new entries until existing entries are removed. The
CacheFactory.createPayloadEntry method will return a null PayloadEntry when the
maximum number of items is reached.
When set to zero, the cache allows an unlimited number of items.
Refer to Section 8.3.1.

Table 169: PayloadCacheConfigOptions Members

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

151

Chapter 8

8.2.4

Payload Cache Detailed View

Managing RDM Field Dictionaries for Payload Cache

Each cache instance requires an RDM Field Dictionary, to define the set of fields that may be encoded in the OMM containers
stored in the cache.
A cache is associated with a field dictionary through a setting process, which requires a DataDictionary object loaded with
the field dictionary. The dictionary object can be loaded from a file (using the loadFieldDictionary method) or from an
encoded dictionary message from a provider (using the decodeFieldDictionary method). The cache does not use the
enumerated dictionary content, so loading the enumeration dictionary is not required. For more information on using
DataDictionary, refer to the Transport API Reference Manual.
After the DataDictionary loads, it is set to a cache instance using a key (an arbitrary string identifier assigned by the
application to name the dictionary). The key allows multiple cache instances to share the same dictionary. After the first setting
of a dictionary, it can be set to additional cache instances by simply providing the same key on additional settings. For a list of
methods used in setting a dictionary to a cache, refer to Section 8.2.4.1.
The cache builds its own field definition database from the DataDictionary definitions. After setting, the application does not
need to retain the dictionary object, because the cache does not refer to the DataDictionary used during the setting. In
typical usage, the application will likely retain the dictionary for use with other encoding and decoding operations.
Note: A cache can be set to a dictionary only once during its lifetime. While a cache cannot be switched to a new dictionary,
the dictionary in use can be extended with new definitions. Refer to Section 8.2.4.3.

8.2.4.1

Setting Functions

METHOD NAME
setDictionary

DESCRIPTION
This method sets a DataDictionary to a cache instance. Use this method the
first time a dictionary is set to a cache. The application must provide a key
parameter to this method to name the dictionary for future reference. This key
is used in future setting operations when the application wants to share a
dictionary between cache instances or to extend the definitions in the
dictionary.
The first time a particular key is used with this method will be the initial setting
of that dictionary to a cache. The second time the same key is used in this
method; it will reload the field definitions from the given DataDictionary
object, enabling the dictionary to be extended. Refer to Section 8.2.4.3.

setSharedDictionaryKey

Use this method when sharing a dictionary among multiple caches. This
method sets a cache (identified by the dictionary key name) to a previously set
dictionary (identified by the dictionary key name). To share a dictionary, the
dictionary must have previously had an initial setting to another cache using
the setDictionary method.
This method does not require the DataDictionary object, since that was
already loaded during the initial setting with this dictionary key.

Table 170: Methods for Setting Dictionary to Cache

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

152

Chapter 8

8.2.4.2

Payload Cache Detailed View

Setting Example

In the following example, two cache instances are created and set to a single, shared field dictionary.
‘

PayloadCacheConfigOptions cacheConfig = CacheFactory.createPayloadCacheConfig();
cacheConfig.maxItems(0); /* unlimited */
/* For simplicity in this code fragment, CHK is assumed to be a macro for error handling (performing
cleanup and returning from method). */
/* create cache instances */
CacheError cacheError = CacheFactory.createCacheError();
PayloadCache cacheInstance1 = CacheFactory.createPayloadCache(cacheConfig, cacheError);
if (cacheInstance1 == null)
{
System.out.println("CacheFactory.createPayloadCache failure: " + cacheError.text());
CHK(cacheError.errorId());
}
PayloadCache cacheInstance2 = CacheFactory.createPayloadCache(cacheConfig, cacheError);
if (cacheInstance2 == null)
{
System.out.println("CacheFactory.createPayloadCache failure: " + cacheError.text());
CHK(cacheError.errorId());
}
/* Load an RDM Field Dictionary object from file: set to each cache. */
DataDictionary dataDictionary = CodecFactory.createDataDictionary();
com.thomsonreuters.upa.transport.Error error = TransportFactory.createError();
int ret = dataDictionary.loadFieldDictionary("RDMFieldDictionary", error); CHK(ret);
String dictionaryKey = "SharedKey1";
/* Initial setting of the dictionary to the first cache */
ret = cacheInstance1.setDictionary(dataDictionary, dictionaryKey, cacheError); CHK(ret);
/* Shared setting of the same dictionary to the second cache */
ret = cacheInstance2.setSharedDictionaryKey(dictionaryKey, cacheError); CHK(ret);
/* The dataDictionary can be destroyed after setting, but is typically retained by the application for
encoding and decoding. */
/* Two cache instances are now ready for applying and retrieving data */
/* Cleanup */
cacheInstance1.destroy(); /* destroys all entries and the cache instance */
cacheInstance2.destroy();

Code Example 32: Creating Cache and Setting to Dictionary

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

153

Chapter 8

8.2.4.3

Payload Cache Detailed View

Extending the Cache Field Dictionary

While a cache can only be set to a single dictionary during its lifetime, the set of field definitions defined by the dictionary can
be extended. This is accomplished by reloading the cache field definition database with another call to the setDictionary
method. When extending the field dictionary, the DataDictionary must contain the original field definitions and any new
definitions the application wishes to use. Changes or deletions to the original field definitions are not supported; only additions
are allowed. Using the same PayloadCache instance and dictionary key that were previously set, call the setDictionary
method again with extended dictionary object.
Note: When extending a field dictionary that is shared, all caches sharing that same dictionary key will see the extension with
only a single call to setDictionary. There is no need to set the shared dictionary key again to each cache after a dictionary is
extended.

8.2.5

Payload Cache Utilities

Use the following methods for managing cache instances. These utilities provide a count of the cache entries and a list of
handles to each cache entry.
METHOD NAME

DESCRIPTION

entryCount

Returns the number of item payload entries in this cache instance

entryList

Populates an array list for this cache instance. Because each cache entry is likely
associated with an entry in the application’s item list, an application would typically
manage the entire set of entry instances. This utility provides access to the entire entry
instance list if needed.

clear

Destroys all entries in the cache instance. The empty cache can be reused and
remains bound to it’s data dictionary.

Table 171: PayloadCache Utility Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

154

Chapter 8

8.3

Payload Cache Detailed View

Payload Cache Entries

A payload cache entry stores a single OMM container (whose containers are defined by DataTypes). While a cache entry can
store any arbitrary OMM data, the primary use case is to maintain the last known value of an item data stream by applying the
sequence of refresh and update messages in the stream to the cache entry. Initial data applied to a container must be a
refresh message payload, which will define the container type to be stored (e.g. Map). As refresh and update messages from
the item stream are applied to the cache entry, the cache decodes the OMM data and sets the current value by following the
OMM rules for the container (e.g., adding, deleting, or updating map entries in a Map, or updating fields in a field list). The last
value of the data stream can be retrieved from cache at any time as an encoded OMM container.

8.3.1

Managing Payload Cache Entries

Payload cache entries are created within a cache instance. Use the CacheFactory.createPayloadEntry method to create a
cache entry instance. You cannot move entries between different cache instances, due to their dependency on the field
dictionary set to the cache where they are created.
Cache entries only store the payload container of an item. Maintain other item data (e.g. message key attributes, domain,
state) as needed in an item list managed by the application, which will identify the source or sink associated with the cache
entry data. This item list will likely include the PayloadEntry instance if the payload of the item is cached.
For a list of basic utilities provided by the payload cache to manage the collection of entries in the cache, refer to Section 8.2.5.
Use the following methods to manage cache entries:
METHOD NAME

DESCRIPTION

CacheFactory.createPayloadEntry This method returns a newly created entry in the cache defined by the given
PayloadCache instance.
This method will return a null instance if it cannot create the entry (e.g., if the maximum
number of entries as defined in PayloadCacheConfigOptions would be exceeded).
destroy

This method destroys the cache entry defined PayloadEntry instance and removes it
from its cache.

clear

This method deletes any data in the cache entry instance and returns the entry to its
initial state. The entry itself remains in the cache and can be re-used.

Table 172: Payload Cache Entry Management Methods

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

155

Chapter 8

8.3.2

Payload Cache Detailed View

Applying Data

Data is applied to a cache entry from the payload of an OMM message by using the apply method. The decoded Msg and an
DecodeIterator are passed to the apply method. The iterator (positioned at the start of the encoded payload data
Msg.encodedDataBody) will be used to decode the OMM data so that the cache entry data can be set or updated.
Some caching behaviors are controlled by flags in the Msg. When a RefreshMsg is applied to the cache entry, the following
RefreshMsgFlags take effect:

•

CLEAR_CACHE: Cache entry data will be cleared prior to applying this message.

•

DO_NOT_CACHE: The payload will not be applied to the cache entry.

When an UpdateMsg is applied to cache, the following UpdateMsgFlags take effect:
•

DO_NOT_CACHE: The payload data will not be applied to the cache entry.

•

DO_NOT_RIPPLE: When applying the data, entry rippling is not performed.

The following example demonstrates how to create a payload entry in a cache instance and apply the payload of a Msg to the
cache entry.

/* For simplicity in this code fragment, CHK is assumed to be a macro for error handling (performing
cleanup and returning from method). */
CacheError cacheError = CacheFactory.createCacheError();
PayloadEntry entryInstance = CacheFactory.createPayloadEntry(cacheInstance, cacheError);
if (entryInstance == null)
{
System.out.println("Error " + cacheError.errorId() + " creating cache entry: " + cacheError.text());
CHK(cacheError.errorId());
}
/* Apply buffer containing an encoded Msg to cache entry */
int applyBufferToCache(Channel channel, TransportBuffer buffer, PayloadEntry entryInstance)
{
/* Perform message decoding. */
DecodeIterator dIter = CodecFactory.createDecodeIterator();
dIter.clear();
dIter.setBufferAndRWFVersion(buffer, channel.majorVersion(), channel.minorVersion());
Msg msg = CodecFactory.createMsg();
int ret = msg.decode(dIter);
if (ret < CodecReturnCodes.SUCCESS)
{
System.out.println("Failure decoding message from buffer");
CHK(ret);
}
/* Apply the decoded Msg to cache, with iterator positioned at the start of the payload */
CacheError cacheError = CacheFactory.createCacheError();
ret = entryInstance.apply(dIter, msg, cacheError);
if (ret < CodecReturnCodes.SUCCESS)
{
System.out.println("Error " + cacheError.errorId() + " applying data to cache entry: " +

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

156

Chapter 8

Payload Cache Detailed View

cacheError.text());
CHK(ret);
}
CHK(ret);
}

Code Example 33: Applying Data to a Payload Cache Entry

8.3.3

Retrieving Data

Data is retrieved from a cache entry as an encoded OMM container by using the retrieve method. The application provides
the data buffer (via an EncodeIterator) where the container will be encoded. The retrieve method supports both encoding
scenarios. When using Msg.encodedDataBody, the encoded content retrieved from the cache entry can be set on the Msg data
body. If using encodeInit and encodeComplete encoding, the cache retrieve method can encode the message payload prior
to encodeComplete.
There are two options for using the retrieve method. For single-part retrieval, the buffer provided by the application must be
large enough to hold the entire encoded container. For multi-part retrieval, the application makes a series of calls to retrieve
to get the OMM container in fragments (e.g., a sequence of maps are retrieved which together contain the entire set of map
entries for the OMM container). In this usage, the optional PayloadCursor instance is required to maintain the state of the
multi-part retrieval. Container types FieldList and ElementList cannot be fragmented, so the buffer size must be large
enough to retrieve the entire container.
The following methods describe data-related operations on a cache entry.
METHOD NAME

DESCRIPTION

dataType

Returns the DataType stored in the cache entry instance. When initially created (or after
the entry is cleared), the data type will be UNKNOWN. The data type is defined by the
container type of the first refresh message applied to the entry.

apply

Applies the OMM data in the payload of the Msg to the cache entry instance. The first
message applied must be a refresh message (class REFRESH).

retrieve

Retrieves data from the cache entry by encoding the OMM container into the buffer
provided with the EncodeIterator given by the application. The buffer can be Buffer or
TransportBuffer. For single-part retrieval, the PayloadCursor parameter is optional. For
details on multi-part retrieval, refer to Section 8.3.3.1.

Table 173: Methods for Applying and Retrieving Cache Entry Data

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

157

Chapter 8

8.3.3.1

Payload Cache Detailed View

Multi-Part Retrieval

For data types that support fragmentation, the container can be retrieved in multiple parts by calling retrieve until the
complete container is returned. To support multi-part retrieval, the optional PayloadCursor parameter is required when calling
retrieve. The cursor is used to maintain the position where the next retrieval will resume. The application must check the
state of the cursor after each call to retrieve to determine when the retrieval is complete. The following methods are needed
when using the payload cursor.
METHOD NAME

DESCRIPTION

CacheFactory.createPayloadCursor Creates a cursor for optional use in the retrieve method (required for multi-part
retrieval). Returns the PayloadCursor instance.
destroy

Destroys the cursor instance.

clear

Clears the state of the cursor instance. Whenever retrieving data from a cache entry, the
cursor must be cleared prior to the first call to retrieve. Clearing the cursor also allows
it to be reused with a retrieval on a different container.

isComplete

Returns the completion state of a retrieval where the PayloadCursor instance was
used. The state must be checked after each call to retrieve to determine whether
additional data needs to be encoded for the cache entry container. When the cursor
state is complete, the entire container of the cache entry has been retrieved.

Table 174: Methods for Using the Payload Cursor

8.3.3.2

Buffer Management

In multi-part usage, the size of the buffer used in the calls to retrieve will affect how many fragments are required to retrieve
the entire image of the cache entry. The retrieve method will continue to encode OMM entries from the cache container until it
runs out of room in the buffer to encode the next entry. To progress during a multi-part retrieval, the buffer size must be at least
large enough to encode a single OMM entry from the payload container. For example, if retrieving a map in multiple parts, the
buffer must be large enough to encode at least one MapEntry on each retrieval.
There are three general outcomes when using the retrieve method:
•

Full cache container is encoded into the buffer. This can occur with or without the use of the optional PayloadCursor
instance. If used in this scenario, the cursor state would indicate the retrieval is complete.

•

Partial container encoded into the buffer. This is only possible when using the PayloadCursor instance for container
types that support fragmentation. The application must check the cursor to test whether this is the final part.

•

No data encoded into container due to insufficient buffer size. This can occur with or without the use of the optional
PayloadCursor instance. The application may retrieve again with a larger buffer.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

158

Chapter 8

8.3.3.3

Payload Cache Detailed View

Example: Cache Retrieval with Multi-Part Support

The following example illustrates data retrieval from a cache entry, which supports multi-part encoding of a container.

/*Code fragment showing use of retrieve for multi-part retrieval.*/
com.thomsonreuters.upa.transport.Error error = TransportFactory.createError();
TransportBuffer buffer = channel.getBuffer(DEFAULT_BUFFER_SIZE, false, error);
int ret;
CacheError cacheError = CacheFactory.createCacheError();
PayloadCursor cursorInstance = CacheFactory.createPayloadCursor();
cursorInstance.clear();
EncodeIterator eIter = CodecFactory.createEncodeIterator();
while (!cursorInstance.isComplete())
{
eIter.clear();
eIter.setBufferAndRWFVersion(buffer, channel.majorVersion(), channel.minorVersion());
/* entryInstance created outside the scope of this code fragment */
ret = entryInstance.retrieve(eIter, cursorInstance, cacheError);
if (ret == CodecReturnCodes.SUCCESS)
/* buffer is big enough to hold whole container data. Application can used encoded data, e.g. set the
payload on Msg.encodedDataBody and encode a message to be transmitted. */
else if (ret == CodecReturnCodes.BUFFER_TOO_SMALL)
/* Increase buffer size and reallocate buffer. */
else
/* Handle terminal error condition. See cacheError.text() for additional information. */
}
cursorInstance.destroy();

Code Example 34: Cache Retrieval with Multi-Part Support

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

159

Appendix A Value Added Utilities
Value Added Utilities are a collection of common classes used mainly by the Transport API Reactor. Included is a selectable,
bidirectional queue that can communicate events between the Reactor and Worker threads. Other Value Added Utilities
include a simple queue along with iterable and concurrent versions of it.
The Value Added Utilities are internally leveraged by the Transport API Reactor and cache so applications need not be familiar
with their use.

Transport API 3.2.x Java Edition – Value Added Components Developers Guide
ETAJ322UMVAC.180

160

© 2015 - 2018 Thomson Reuters. All rights reserved.
Republication or redistribution of Thomson Reuters content, including by framing or
similar means, is prohibited without the prior written consent of Thomson Reuters.
'Thomson Reuters' and the Thomson Reuters logo are registered trademarks and
trademarks of Thomson Reuters and its affiliated companies.
Any third party names or marks are the trademarks or registered trademarks of the
relevant third party.

Document ID: ETAJ322UMVAC.180
Date of issue: 8 November 2018

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.6
Linearized                      : No
Author                          : u0116273
Create Date                     : 2018:10:29 12:57:31Z
Modify Date                     : 2018:11:12 10:50:43-06:00
Language                        : en
Tagged PDF                      : Yes
XMP Toolkit                     : Adobe XMP Core 5.4-c006 80.159825, 2016/09/16-03:31:08
Producer                        : Acrobat Distiller 11.0 (Windows)
Creator Tool                    : FrameMaker 2015.1
Metadata Date                   : 2018:11:12 10:50:43-06:00
Format                          : application/pdf
Title                           : ETAJ_ValueAddDevGuide.book
Creator                         : u0116273
Document ID                     : uuid:3dfd018f-1631-48c3-8922-42f90a254a23
Instance ID                     : uuid:a2e9c122-a306-499c-a7cf-ddd0ef58bfc4
Page Mode                       : UseOutlines
Page Count                      : 173

EXIF Metadata provided by EXIF.tools

ETAJ_ValueAddDevGuide ETAJ Value Add Dev Guide

Navigation menu

Versions of this User Manual:

Views

Navigation