ETAJ_ValueAddDevGuide ETAJ Value Add Dev Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 173 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Chapter 1 Introduction
Chapter 2 Product Description and Overview
Chapter 3 Building an OMM Consumer
Chapter 4 Building an OMM Interactive Provider
Chapter 5 Building an OMM Non-Interactive Provider
Chapter 6 Reactor Detailed View
Chapter 7 Administration Domain Models Detailed View
Chapter 8 Payload Cache Detailed View
Appendix A Value Added Utilities

We are now Reﬁnitiv, 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.

Document Version: 3.2.2

Date of issue: 8 November 2018

Document ID: ETAJ322UMVAC.180

Transport API Java Edition

V3.2.x

VALUE ADDED COMPONENTS

DEVELOPERS GUIDE JAVA EDITION

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

ETAJ322UMVAC.180

Legal Information

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 3.2.x Java Edition – Value Added Components Developers Guide iii

ETAJ322UMVAC.180

Contents

Chapter 1 Introduction ...................................................................................................................... 1

1.1 About this Manual ........................................................................................................................................... 1

1.2 Audience ......................................................................................................................................................... 1

1.3 Programming Language.................................................................................................................................. 1

1.4 Acronyms and Abbreviations .......................................................................................................................... 1

1.5 Additional References and Resources............................................................................................................ 3

1.6 Documentation Feedback ............................................................................................................................... 3

1.7 Document Conventions................................................................................................................................... 3

1.7.1 Typographic.............................................................................................................................................. 3

1.7.2 Document Structure.................................................................................................................................. 3

1.7.3 Diagrams .................................................................................................................................................. 4

Chapter 2 Product Description and Overview ................................................................................ 5

2.1 What is the Transport API? ............................................................................................................................. 5

2.2 What are Transport API Value Added Components? ..................................................................................... 5

2.3 Transport API Reactor .................................................................................................................................... 6

2.4 OMM Consumer Watchlist .............................................................................................................................. 7

2.4.1 Data Stream Aggregation and Recovery.................................................................................................. 7

2.4.2 Additional Features................................................................................................................................... 7

2.4.3 Usage Notes............................................................................................................................................. 7

2.5 Administration Domain Model Representations .............................................................................................. 8

2.6 Value Added Utilities ....................................................................................................................................... 8

2.7 Payload Cache................................................................................................................................................ 8

Chapter 3 Building an OMM Consumer ........................................................................................... 9

3.1 Overview ......................................................................................................................................................... 9

3.2 Leverage Existing or Create New Reactor...................................................................................................... 9

3.3 Implement Callbacks and Populate Role ........................................................................................................ 9

3.4 Establish Connection using Reactor.connect................................................................................................ 10

3.5 Issue Requests and/or Post Information ....................................................................................................... 10

3.6 Log Out and Shut Down................................................................................................................................ 10

3.7 Additional Consumer Details......................................................................................................................... 11

Chapter 4 Building an OMM Interactive Provider ......................................................................... 12

4.1 Overview ....................................................................................................................................................... 12

4.2 Leverage Existing or Create New Reactor.................................................................................................... 12

4.3 Create a Server............................................................................................................................................. 13

4.4 Implement Callbacks and Populate Role ...................................................................................................... 13

4.5 Associate Incoming Connections Using Reactor.accept............................................................................... 13

4.6 Perform Login Process.................................................................................................................................. 14

4.7 Provide Source Directory Information ........................................................................................................... 14

4.8 Provide or Download Necessary Dictionaries ............................................................................................... 15

4.9 Handle Requests and Post Messages .......................................................................................................... 15

4.10 Disconnect Consumers and Shut Down ....................................................................................................... 16

4.11 Additional Interactive Provider Details .......................................................................................................... 16

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

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

5.2 Leverage Existing or Create New Reactor.................................................................................................... 17

5.3 Implement Callbacks and Populate Role ...................................................................................................... 17

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

ETAJ322UMVAC.180

5.4 Establish Connection using Reactor.connect................................................................................................ 18

5.5 Download the Dictionary ............................................................................................................................... 18

5.6 Provide Content ............................................................................................................................................ 18

5.7 Log Out and Shut Down................................................................................................................................ 19

5.8 Additional Non-Interactive Provider Details................................................................................................... 19

Chapter 6 Reactor Detailed View.................................................................................................... 20

6.1 Concepts ....................................................................................................................................................... 20

6.1.1 Functionality: Transport API Versus Transport API Reactor .................................................................. 21

6.1.2 Reactor Error Handling........................................................................................................................... 22

6.1.3 Reactor Error Info Codes........................................................................................................................ 22

6.1.4 Transport API Reactor Application Lifecycle .......................................................................................... 23

6.2 Reactor Use .................................................................................................................................................. 24

6.2.1 Creating a Reactor.................................................................................................................................. 24

6.2.2 Destroying a Reactor.............................................................................................................................. 25

6.3 Reactor Channel Use.................................................................................................................................... 26

6.3.1 Reactor Channel Roles........................................................................................................................... 27

6.3.2 Reactor Channel Role: OMM Consumer................................................................................................ 29

6.3.3 Reactor Channel Role: OMM Provider ................................................................................................... 31

6.3.4 Reactor Channel Role: OMM Non-Interactive Provider.......................................................................... 32

6.4 Managing Reactor Channels......................................................................................................................... 33

6.4.1 Adding Reactor Channels....................................................................................................................... 33

6.4.2 Removing Reactor Channels.................................................................................................................. 37

6.5 Dispatching Data........................................................................................................................................... 38

6.5.1 Reactor Dispatch Methods ..................................................................................................................... 38

6.5.2 Reactor Callback Methods...................................................................................................................... 40

6.5.3 Reactor Callback: Channel Event........................................................................................................... 41

6.5.4 Reactor Callback: Default Message ....................................................................................................... 44

6.5.5 Reactor Callback: RDM Login Message................................................................................................. 45

6.5.6 Reactor Callback: RDM Directory Message ........................................................................................... 46

6.5.7 Reactor Callback: RDM Dictionary Message.......................................................................................... 48

6.6 Writing Data .................................................................................................................................................. 50

6.6.1 Writing Data using ReactorChannel.submit(Msg…)............................................................................... 50

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

6.7 Creating and Using Tunnel Streams ............................................................................................................. 61

6.7.1 Authenticating a Tunnel Stream ............................................................................................................. 62

6.7.2 Opening a Tunnel Stream....................................................................................................................... 62

6.7.3 Negotiating Stream Behaviors: Class of Service.................................................................................... 64

6.7.4 Tunnel Stream Callback Methods and Event Types............................................................................... 68

6.7.5 Code Sample: Opening and Managing a Tunnel Stream....................................................................... 70

6.7.6 Accepting Tunnel Streams...................................................................................................................... 71

6.7.7 Receiving Content on a TunnelStream................................................................................................... 76

6.7.8 Sending Content on a TunnelStream ..................................................................................................... 76

6.7.9 Closing a Tunnel Stream ........................................................................................................................ 78

6.8 Reactor Utility Methods ................................................................................................................................. 78

6.8.1 General Reactor Utility Methods............................................................................................................. 79

6.8.2 ReactorChannelInfo Class Members...................................................................................................... 79

6.8.3 ReactorChannel.ioctl Option Values....................................................................................................... 79

Chapter 7 Administration Domain Models Detailed View ............................................................ 80

7.1 Concepts ....................................................................................................................................................... 80

7.2 Message Base .............................................................................................................................................. 81

7.2.1 Message Base Members........................................................................................................................ 81

7.2.2 Message Base Method........................................................................................................................... 81

7.2.3 RDM Message Types ............................................................................................................................. 82

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

ETAJ322UMVAC.180

7.3 RDM Login Domain....................................................................................................................................... 83

7.3.1 Login Request......................................................................................................................................... 83

7.3.2 Login Refresh ......................................................................................................................................... 86

7.3.3 Login Status............................................................................................................................................ 93

7.3.4 Login Close............................................................................................................................................. 96

7.3.5 Login Consumer Connection Status....................................................................................................... 96

7.3.6 Login Post Message Use........................................................................................................................ 98

7.3.7 Login Ack Message Use......................................................................................................................... 98

7.3.8 Login Attributes....................................................................................................................................... 98

7.3.9 Login Message ..................................................................................................................................... 100

7.3.10 Login Message Utility Messages .......................................................................................................... 101

7.3.11 Login Encoding and Decoding.............................................................................................................. 101

7.4 RDM Source Directory Domain................................................................................................................... 106

7.4.1 Directory Request................................................................................................................................. 106

7.4.2 Directory Refresh.................................................................................................................................. 108

7.4.3 Directory Update................................................................................................................................... 110

7.4.4 Directory Status .................................................................................................................................... 112

7.4.5 Directory Close ..................................................................................................................................... 114

7.4.6 Directory Consumer Status................................................................................................................... 114

7.4.7 Directory Service .................................................................................................................................. 115

7.4.8 Directory Service Info Filter .................................................................................................................. 116

7.4.9 Directory Service State Filter................................................................................................................ 119

7.4.10 Directory Service Group Filter .............................................................................................................. 120

7.4.11 Directory Service Load Filter ................................................................................................................ 121

7.4.12 Directory Service Data Filter................................................................................................................. 122

7.4.13 Directory Service Link Info Filter........................................................................................................... 123

7.4.14 Directory Service Link........................................................................................................................... 124

7.4.15 Directory Message................................................................................................................................ 125

7.4.16 Directory Message Utility Methods ....................................................................................................... 125

7.4.17 Directory Encoding and Decoding ........................................................................................................ 126

7.5 RDM Dictionary Domain.............................................................................................................................. 132

7.5.1 Dictionary Request ............................................................................................................................... 132

7.5.2 Dictionary Refresh ................................................................................................................................ 133

7.5.3 Dictionary Status................................................................................................................................... 135

7.5.4 Dictionary Close.................................................................................................................................... 135

7.5.5 Dictionary Messages ............................................................................................................................ 136

7.5.6 Dictionary Message: Utility Methods..................................................................................................... 136

7.5.7 Dictionary Encoding and Decoding....................................................................................................... 136

7.6 RDM Queue Messages............................................................................................................................... 142

7.6.1 Queue Data Message Persistence....................................................................................................... 142

7.6.2 Queue Request..................................................................................................................................... 142

7.6.3 Queue Refresh ..................................................................................................................................... 143

7.6.4 Queue Status........................................................................................................................................ 143

7.6.5 Queue Close......................................................................................................................................... 143

7.6.6 Queue Data .......................................................................................................................................... 144

7.6.7 QueueDataExpired ............................................................................................................................... 147

7.6.8 Queue Ack............................................................................................................................................ 148

Chapter 8 Payload Cache Detailed View ..................................................................................... 149

8.1 Concepts ..................................................................................................................................................... 149

8.2 Payload Cache............................................................................................................................................ 150

8.2.1 Payload Cache Management ............................................................................................................... 150

8.2.2 Cache Error Handling ........................................................................................................................... 150

8.2.3 Payload Cache Instances..................................................................................................................... 151

8.2.4 Managing RDM Field Dictionaries for Payload Cache.......................................................................... 152

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

ETAJ322UMVAC.180

8.2.5 Payload Cache Utilities......................................................................................................................... 154

8.3 Payload Cache Entries................................................................................................................................ 155

8.3.1 Managing Payload Cache Entries ........................................................................................................ 155

8.3.2 Applying Data ....................................................................................................................................... 156

8.3.3 Retrieving Data..................................................................................................................................... 157

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

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

ETAJ322UMVAC.180

List of Figures

Contents

Figure 1. Network Diagram Notation .............................................................................................................................. 4

Figure 2. UML Diagram Notation.................................................................................................................................... 4

Figure 3. OMM APIs with Value Added Components .................................................................................................... 5

Figure 4. Transport API Value Added Components ....................................................................................................... 6

Figure 5. Transport API Reactor Thread Model ........................................................................................................... 20

Figure 6. Transport API Reactor Application Lifecycle................................................................................................. 23

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

Figure 8. Tunnel Stream Illustration ............................................................................................................................. 61

Figure 9. Consumer Application using Cache to Store Payload Data for Item Streams ............................................ 149

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

ETAJ322UMVAC.180

List of Tables

Contents

Table 1: Acronyms and Abbreviations .......................................................................................................................... 1

Table 2: Transport API Functionality and Transport API Reactor Comparison........................................................... 21

Table 3: ReactorErrorInfo Members ................................................................................................................... 22

Table 4: Reactor Error Info Codes .............................................................................................................................. 22

Table 5: Class Members............................................................................................................................................ 24

Table 6: Reactor Creation Method ........................................................................................................................... 24

Table 7: ReactorOptions Class Members.............................................................................................................. 24

Table 8: ReactorOptions Utility Method ................................................................................................................. 25

Table 9: Reactor Destruction Method....................................................................................................................... 25

Table 10: ReactorChannel Class Members.............................................................................................................. 26

Table 11: ReactorRole Class Members .................................................................................................................... 27

Table 12: ReactorRoleTypes Enumerated Values................................................................................................... 28

Table 13: ConsumerRole Class Members .................................................................................................................. 29

Table 14: ConsumerRole.dictionaryDownloadMode Enumerated Values.......................................................... 30

Table 15: OMM Consumer Role Watchlist Options ...................................................................................................... 30

Table 16: ConsumerRole Utility Method ..................................................................................................................... 30

Table 17: ProviderRole Class Members .................................................................................................................. 31

Table 18: ProviderRole Utility Method ..................................................................................................................... 31

Table 19: NIProviderRole Class Members.............................................................................................................. 32

Table 20: NIProviderRole Utility Method ................................................................................................................. 32

Table 21: Reactor.connect Method......................................................................................................................... 33

Table 22: ReactorConnectOptions Class Members...................................................................................................... 34

Table 23: ReactorConnectInfo Class Members ..................................................................................................... 34

Table 24: ReactorConnectOptions Utility Method.................................................................................................. 34

Table 25: Reactor.accept Method........................................................................................................................... 36

Table 26: ReactorAcceptOptions Class Members................................................................................................. 36

Table 27: RsslReactorAcceptOptions Utility Method ........................................................................................... 36

Table 28: ReactorChannel.close Function............................................................................................................ 37

Table 29: Reactor Dispatch Methods............................................................................................................................ 38

Table 30: ReactorDispatchOptions Class Members ............................................................................................ 39

Table 31: ReactorDispatchOptions Utility Method................................................................................................ 39

Table 32: ReactorCallbackReturnCodes Callback Return Codes........................................................................ 40

Table 33: ReactorEvent Class Members .................................................................................................................. 40

Table 34: ReactorChannelEvent Class Member..................................................................................................... 41

Table 35: ReactorChannelEventType Enumeration Values................................................................................... 41

Table 36: ReactorChannelEvent Utility Methods .................................................................................................... 42

Table 37: ReactorMsgEvent Class Members............................................................................................................ 44

Table 38: ReactorMsgEvent Utility Method............................................................................................................... 44

Table 39: RDMLoginMsgEvent Class Member ........................................................................................................... 45

Table 40: RDMLoginMsgEvent Utility Method............................................................................................................. 45

Table 41: RDMDirectoryMsgEvent Class Member................................................................................................... 47

Table 42: RDMDirectoryMsgEvent Utility Method.................................................................................................... 47

Table 43: RDMDictionaryMsgEvent Class Member ................................................................................................ 49

Table 44: RDMDictionaryMsgEvent Utility Method.................................................................................................. 49

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

Table 46: ReactorSubmitOptions Class Members................................................................................................. 51

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

Table 48: ReactorRequestMsgOptions Class Members ........................................................................................ 52

Table 49: ReactorSubmitOptions Utility Method.................................................................................................... 52

Table 50: ReactorChannel Buffer Management Methods............................................................................................. 55

Table 51: ReactorChannel.getBuffer Return Values .......................................................................................... 56

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

ETAJ322UMVAC.180

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

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

Table 54: ReactorChannel.packBuffer Method................................................................................................... 58

Table 55: ReactorChannel.packBuffer Return Values ........................................................................................ 59

Table 56: TunnelStreamAuthInfo Members........................................................................................................... 62

Table 57: ReactorChannel.openTunnelStream Method...................................................................................... 62

Table 58: TunnelStreamOpenOptions .................................................... 63

Table 59: ClassOfService.common Members......................................................................................................... 64

Table 60: ClassOfService.authentication Members ....................................................................................... 65

Table 61: ClassOfService.flowControl Members.............................................................................................. 65

Table 62: ClassOfService.dataIntegrity Members ......................................................................................... 66

Table 63: ClassOfService.guarantee Members.................................................................................................. 67

Table 64: Tunnel Stream Callback Methods ................................................................................................................. 68

Table 65: Tunnel Stream Callback Event Types........................................................................................................... 69

Table 66: TunnelStreamRequestEvent Members.................................................................................................. 72

Table 67: ReactorChannel.acceptTunnelStream Method.................................................................................. 72

Table 68: TunnelStreamAcceptOptions Options................................................................................................... 73

Table 69: ReactorChannel.rejectTunnelStream Method.................................................................................. 73

Table 70: TunnelStreamRejectOptions Options................................................................................................... 73

Table 71: Tunnel Stream Buffer Methods ..................................................................................................................... 76

Table 72: Tunnel Stream Submit Method ..................................................................................................................... 76

Table 73: Members...................................................................................................................................................... 77

Table 74: Tunnel Closure Method................................................................................................................................. 78

Table 75: Reactor Utility Methods ................................................................................................................................. 79

Table 76: ReactorChannelInfo Class Members ..................................................................................................... 79

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

Table 78: MsgBase Members ....................................................................................................................................... 81

Table 79: MsgBase Method .......................................................................................................................................... 81

Table 80: Domain Representations Message Types.................................................................................................... 82

Table 81: LoginRequest Members ............................................................................................................................ 83

Table 82: LoginRequest Flags .................................................................................................................................. 85

Table 83: LoginRequest Utility Method ..................................................................................................................... 85

Table 84: LoginRefresh Members ............................................................................................................................ 86

Table 85: LoginRefresh Flags .................................................................................................................................. 88

Table 86: LoginSupportFeatures Members........................................................................................................... 89

Table 87: LoginSupportFeaturesFlags .................................................. 90

Table 88: LoginConnectionConfig Members......................................................................................................... 91

Table 89: LoginConnectionConfig Methods.......................................................................................................... 91

Table 90: ServerInfo Members................................................................................................................................. 92

Table 91: ServerInfo Flags....................................................................................................................................... 92

Table 92: ServerInfo Methods.................................................................................................................................. 92

Table 93: LoginStatus Members .............................................................................................................................. 93

Table 94: LoginStatus Flags..................................................................................................................................... 94

Table 95: LoginClose Member .................................................................................................................................. 96

Table 96: LoginConsumerConnectionStatus Members ....................................................................................... 96

Table 97: LoginConsumerConnectionStatus Flags ............................................................................................. 97

Table 98: LoginWarmStandbyInfo Members........................................................................................................... 97

Table 99: LoginWarmStandbyInfo Methods............................................................................................................ 97

Table 100: LoginAttrib Members .............................................................................................................................. 98

Table 101: LoginAttrib Methods.............................................................................................................................. 100

Table 102: LoginAttribFlags .......................................................... 100

Table 103: LoginMsg Interfaces.................................................................................................................................. 100

Table 104: LoginMsg Utility Methods .......................................................................................................................... 101

Table 105: Login Encoding and Decoding Methods ..................................................................................................... 101

Table 106: DirectoryRequest Members ................................................................................................................. 106

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

ETAJ322UMVAC.180

Table 107: DirectoryRequest Flags........................................................................................................................ 107

Table 108: DirectoryRequest Utility Methods......................................................................................................... 107

Table 109: DirectoryRefresh Members ................................................................................................................. 108

Table 110: DirectoryRefresh Flags........................................................................................................................ 109

Table 111: DirectoryUpdate Members.................................................................................................................... 110

Table 112: DirectoryUpdate Flags.......................................................................................................................... 111

Table 113: DirectoryStatus Members.................................................................................................................... 112

Table 114: DirectoryStatus Flags......................................................................................................................... 113

Table 115: DirectoryStatus Utility Methods ........................................................................................................... 113

Table 116: DirectoryClose Member........................................................................................................................ 114

Table 117: DirectoryConsumerStatus Members .................................................................................................. 114

Table 118: ConsumerStatusService Members....................................................................................................... 114

Table 119: Service Members ..................................................................................................................................... 115

Table 120: Service Flags ........................................................................................................................................... 115

Table 121: Service Utility Methods ............................................................................................................................ 116

Table 122: ServiceInfo Members ............................................................................................................................ 116

Table 123: ServiceInfo Flags.................................................................................................................................. 118

Table 124: ServiceInfo Utility Methods.................................................................................................................... 118

Table 125: ServiceState Members .......................................................................................................................... 119

Table 126: ServiceState Flags ................................................................................................................................ 119

Table 127: ServiceState Utility Methods.................................................................................................................. 119

Table 128: ServiceGroup Members .......................................................................................................................... 120

Table 129: ServiceGroup Flags ................................................................................................................................ 120

Table 130: ServiceGroup Utility Methods.................................................................................................................. 120

Table 131: ServiceLoad Members ............................................................................................................................ 121

Table 132: ServiceLoad Flags................................................................................................................................... 121

Table 133: ServiceLoad Utility Methods.................................................................................................................... 121

Table 134: ServiceData Members ............................................................................................................................ 122

Table 135: ServiceData Flags................................................................................................................................... 122

Table 136: ServiceData Methods.............................................................................................................................. 122

Table 137: ServiceLinkInfo Members.................................................................................................................... 123

Table 138: ServiceLinkInfo Methods..................................................................................................................... 123

Table 139: ServiceLink Members ............................................................................................................................ 124

Table 140: ServiceLink Flags................................................................................................................................... 125

Table 141: ServiceLink Methods.............................................................................................................................. 125

Table 142: DirectoryMsg Interfaces ......................................................................................................................... 125

Table 143: DirectoryMsg Utility Methods.................................................................................................................. 125

Table 144: Directory Encoding and Decoding Methods................................................................................................ 126

Table 145: DictionaryRequest Members ............................................................................................................... 132

Table 146: DictionaryRequest Flag ....................................................................................................................... 132

Table 147: DictionaryRefresh Members ............................................................................................................... 133

Table 148: DictionaryRefreshFlags ...................................................................................................................... 134

Table 149: DictionaryStatus Members ................................................................................................................. 135

Table 150: DictionaryStatus Flags........................................................................................................................ 135

Table 151: DictionaryClose Member ..................................................................................................................... 135

Table 152: DictionaryMsg Interfaces ....................................................................................................................... 136

Table 153: DictionaryMsg Utility Methods ............................................................................................................... 136

Table 154: Dictionary Encoding and Decoding Methods .............................................................................................. 136

Table 155: QueueRequest Members .......................................................................................................................... 142

Table 156: QueueRefresh Members .......................................................................................................................... 143

Table 157: QueueStatus Members ............................................................................................................................ 143

Table 158: QueueClose Members............................................................................................................................... 143

Table 159: QueueData Members................................................................................................................................. 144

Table 160: Queue Data Flag......................................................................................................................................... 144

Table 161: Queue Data Message Timeout Codes........................................................................................................ 145

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

ETAJ322UMVAC.180

Table 162: Queue Data Message Encoding Methods .................................................................................................. 145

Table 163: QueueDataExpired Members...................................................................................................................... 147

Table 164: Queue Data Message Undeliverable Codes............................................................................................... 148

Table 165: Queue Ack Members.................................................................................................................................. 148

Table 166: CacheError Class Members..................................................................................................................... 150

Table 167: CacheError Utility Method........................................................................................................................ 150

Table 168: Methods for Managing Cache Instances..................................................................................................... 151

Table 169: PayloadCacheConfigOptions Members.............................................................................................. 151

Table 170: Methods for Setting Dictionary to Cache..................................................................................................... 152

Table 171: PayloadCache Utility Methods.................................................................................................................. 154

Table 172: Payload Cache Entry Management Methods.............................................................................................. 155

Table 173: Methods for Applying and Retrieving Cache Entry Data............................................................................. 157

Table 174: Methods for Using the Payload Cursor ....................................................................................................... 158

Chapter 1 Introduction

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

ETAJ322UMVAC.180

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

Chapter 1 Introduction

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

ETAJ322UMVAC.180

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

GC 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

ACRONYM MEANING

Table 1: Acronyms and Abbreviations

Chapter 1 Introduction

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

ETAJ322UMVAC.180

1.5 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:

1.7.2 Document Structure

• General Concepts

• Detailed Concepts

• Interface Definitions

• Example Code

/* 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();

Chapter 1 Introduction

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

ETAJ322UMVAC.180

1.7.3 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

Chapter 2 Product Description and Overview

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

ETAJ322UMVAC.180

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.

Chapter 2 Product Description and Overview

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

ETAJ322UMVAC.180

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.

•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. How-

ever, the user, not Thomson Reuters, is responsible for supporting any modifications to the provided source.

Note: If a client customizes a component’s code, the client is responsible for its support and maintenance.

Chapter 2 Product Description and Overview

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

ETAJ322UMVAC.180

2.4 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.

Chapter 2 Product Description and Overview

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

ETAJ322UMVAC.180

2.5 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.

Chapter 3 Building an OMM Consumer

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

ETAJ322UMVAC.180

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.

Chapter 3 Building an OMM Consumer

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

ETAJ322UMVAC.180

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.

Chapter 3 Building an OMM Consumer

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

ETAJ322UMVAC.180

• Shutting down an Reactor is described in Section 6.2.2.

3.7 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.

•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.

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

type.

Chapter 4 Building an OMM Interactive Provider

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

ETAJ322UMVAC.180

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.

Chapter 4 Building an OMM Interactive Provider

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

ETAJ322UMVAC.180

4.3 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:

•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.

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

Available domain-specific callbacks are:

•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 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.

Chapter 4 Building an OMM Interactive Provider

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

ETAJ322UMVAC.180

4.6 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.

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.

Chapter 4 Building an OMM Interactive Provider

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

ETAJ322UMVAC.180

4.8 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.

Chapter 4 Building an OMM Interactive Provider

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

ETAJ322UMVAC.180

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.

•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.

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

type.

Chapter 5 Building an OMM Non-Interactive Provider

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

ETAJ322UMVAC.180

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 non-

interactive 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:

•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.

Chapter 5 Building an OMM Non-Interactive Provider

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

ETAJ322UMVAC.180

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.

Chapter 5 Building an OMM Non-Interactive Provider

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

ETAJ322UMVAC.180

5.7 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.

•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.

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

type.

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

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 non-

interactive 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 user-

implemented 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

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 non-

OMM 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 X X

Programmatic Logging X X

Controlled Fragmentation and Assembly of Large Messages X X

Controlled Locking / Threading Model X X

Controlled Message Buffers with Ability to Change During

Runtime XX

Controlled Message Packing X X

Support for Unified and Segmented Network Connection Types X X

Network Ping Management *** X

Automatic Flushing of Data *** X

User-Defined Callbacks for Data *** X

User Login *** X

Requesting Source Directory *** X

Downloading Field Dictionary *** X

Loading Field Dictionary File *** X

***: 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.1.2 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:

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.

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

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.1.4 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.2 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.

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.

6.2.1.2 ReactorOptions Class Members

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

FUNCTION NAME DESCRIPTION

ReactorFactory.createReactor 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

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.2.1.3 ReactorOptions Utility Method

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

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.

6.2.2.2 Reactor Creation and Destruction Example

Code Example 1: Reactor Creation and Destruction Example

METHOD NAME DESCRIPTION

clear Clears the ReactorOptions class. Useful for object reuse.

Table 8: ReactorOptions Utility Method

METHOD NAME DESCRIPTION

shutdown 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

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);

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.3 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.

The following table describes the members of the ReactorChannel class.

Note: Only Transport API Reactor methods, like those defined in this chapter, should be called on a channel managed by an

Reactor.

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

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:

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.

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

CLASS MEMBER DESCRIPTION

Table 10: ReactorChannel Class Members (Continued)

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.3.1.2 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.3.2 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.

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

• Dictionary messages are described in Section 7.5.

directoryMsgCallback 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.

loginMsgCallback 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.

• Login messages are described in Section 7.3.

rdmDirectoryRequest 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.3.2.2 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.

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.

6.3.2.4 OMM Consumer Role Utility Method

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

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

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

METHOD NAME DESCRIPTION

clear Clears the ConsumerRole object. Useful for object reuse.

Table 16: ConsumerRole Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.3.3 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:

6.3.3.2 OMM Provider Role Utility Function

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

CLASS MEMBER DESCRIPTION

dictionaryMsgCallback 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.

directoryMsgCallback 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.

loginMsgCallback 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.

• Login messages are described in Section 7.3.

listenerCallback 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

FUNCTION NAME DESCRIPTION

clear Clears the ProviderRole object. Useful for object reuse.

Table 18: ProviderRole Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.3.4 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:

6.3.4.2 OMM Non-Interactive Provider Role Utility Method

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

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.

• If this parameter is specified, an rdmDirectoryRefresh is required.

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

loginMsgCallback 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

FUNCTION NAME DESCRIPTION

clear Clears the NIProviderRole object. Useful for object reuse.

Table 20: NIProviderRole Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.4 Managing Reactor Channels

6.4.1 Adding Reactor Channels

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.

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.

Note: A single Reactor can simultaneously manage ReactorChannels from Reactor.connect and Reactor.accept.

METHOD NAME DESCRIPTION

Reactor.connect 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.4.1.2 ReactorConnectOptions Class Members

6.4.1.3 ReactorConnectInfo Class members

6.4.1.4 ReactorConnectOptions Utility Method

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

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

CLASS MEMBER DESCRIPTION

connectOptions 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

FUNCTION NAME DESCRIPTION

clear Clears the ReactorConnectOptions object. Useful for object reuse.

Table 24: ReactorConnectOptions Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.4.1.5 Reactor.connect Example

Code Example 2: 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);

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.4.1.6 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.

6.4.1.7 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 DESCRIPTION

Reactor.accept 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

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

METHOD NAME DESCRIPTION

clear Clears the ReactorAcceptOptions object. Useful for object reuse.

Table 27: RsslReactorAcceptOptions Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.4.1.9 Reactor.accept Example

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.

6.4.2.2 ReactorChannel.close Example

Code Example 4: ReactorChannel.close 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)

FUNCTION NAME DESCRIPTION

ReactorChannel.close 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

ReactorErrorInfo errorInfo = ReactorFactory.createReactorErrorInfo();

/* Can be used inside or outside of a callback */

ret = reactorChannel.close(errorInfo);

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5 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

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.

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.

METHOD NAME DESCRIPTION

Reactor.dispatchAll 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.1.1 Reactor Dispatch Options

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

ReactorChannel.dispatch.

6.5.1.2 ReactorDispatchOptions Utility Function

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

6.5.1.3 ReactorChannel.dispatch Example

Code Example 5: ReactorChannel.dispatch Example

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

METHOD NAME DESCRIPTION

clear Clears the ReactorDispatchOptions object. Useful for object reuse.

Table 31: ReactorDispatchOptions Utility Method

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);

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.2 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:

All events communicated to callback methods have the same base class, the ReactorEvent, which contains information

common to all callback events.

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 domain-

specific callbacks return.

Table 32: ReactorCallbackReturnCodes Callback Return Codes

CLASS MEMBER DESCRIPTION

reactorChannel The ReactorChannel on which the event occurred.

errorInfo The ReactorErrorInfo associated with this event.

Table 33: ReactorEvent Class Members

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.3 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:

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.

6.5.3.2 Reactor Channel Event Type Enumeration Values

reactorChannelEventCallback(ReactorChannelEvent event)

CLASS MEMBER DESCRIPTION

eventType 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

FLAG ENUMERATION MEANING

CHANNEL_DOWN 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.3.3 Reactor Channel Event Utility Methods

6.5.3.4 Reactor Channel Event Callback Example

CHANNEL_READY Indicates that the ReactorChannel has successfully completed any necessary

initialization processes. Where applicable, this includes exchanging any provided

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.

METHOD NAME DESCRIPTION

clear Clears a ReactorChannelEvent object.

Table 36: ReactorChannelEvent Utility Methods

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;

FLAG ENUMERATION MEANING

Table 35: ReactorChannelEventType Enumeration Values (Continued)

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

Code Example 6: Reactor Channel Event Callback Example

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;

}

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.4 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:

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.

6.5.4.2 Reactor Message Event Utility Methods

public int defaultMsgCallback(ReactorMsgEvent event)

CLASS MEMBER DESCRIPTION

transportBuffer 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

METHOD NAME DESCRIPTION

clear Clears a ReactorMsgEvent object.

Table 38: ReactorMsgEvent Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.4.3 Reactor Message Event Callback Example

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:

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.

6.5.5.2 Reactor RDM Login Message Event Utility Method

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());

}

public int rdmLoginMsgCallback(RDMLoginMsgEvent event)

CLASS MEMBER DESCRIPTION

rdmLoginMsg 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

METHOD NAME DESCRIPTION

clear Clears a RDMLoginMsgEvent object.

Table 40: RDMLoginMsgEvent Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.5.3 Reactor RDM Login Message Event Callback Example

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:

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

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());

}

public int rdmDirectoryMsgCallback(RDMDirectoryMsgEvent event)

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.6.1 Reactor RDM Directory Message Event

The RDMDirectoryMsgEvent is returned to the application via the RDMDirectoryMsgCallback.

6.5.6.2 Reactor RDM Directory Message Event Utility Method

CLASS MEMBER DESCRIPTION

rdmDirectoryMsg 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

METHOD NAME DESCRIPTION

clear Clears an RDMDirectoryMsgEvent object.

Table 42: RDMDirectoryMsgEvent Utility Method

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.6.3 Reactor RDM Directory Message Event Callback Example

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:

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

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());

}

public int rdmDictionaryMsgCallback(RDMDictionaryMsgEvent event)

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.5.7.1 Reactor RDM Dictionary Message Event

The RDMDictionaryMsgEvent is returned to the application via the RDMDictionaryMsgCallback.

6.5.7.2 Reactor RDM Dictionary Message Event Utility Method

6.5.7.3 Reactor RDM Dictionary Message Event Callback Example

Code Example 10: Reactor RDM Dictionary Message Event Callback Example

CLASS MEMBER DESCRIPTION

rdmDictionaryMsg 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

METHOD NAME DESCRIPTION

clear Clears an RDMDictionaryMsgEvent object.

Table 44: RDMDictionaryMsgEvent Utility Method

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());

}

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6 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:

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

ReactorChannel.submit(Msg...)

•Takes an Msg object as part of its options; does not

require retrieval of an TransportBuffer from the

channel.

•Must be used when the consumer watchlist is enabled.

ReactorChannel.submit(TransportBuffer...)

•Takes an TransportBuffer which the application

retrieves from the channel.

•More efficient: the application encodes directly into the

buffer, and can use buffer packing.

•Cannot be used when the consumer watchlist is enabled.

METHOD NAME DESCRIPTION

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

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.1.2 Reactor Submit Options

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

6.6.1.3 ReactorChannel.submit(Msg...) Return Codes

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

CLASS MEMBER DESCRIPTION

serviceName 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

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.1.4 ReactorRequestMsgOptions

ReactorRequestMsgOptions provide additional functionality when requesting items. These options are available only when

the consumer watchlist is enabled.

6.6.1.5 ReactorSubmitOptions Utility Method

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

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.

CLASS MEMBER DESCRIPTION

userSpecObj 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

METHOD NAME DESCRIPTION

clear Clears the ReactorSubmitOptions object. Useful for object reuse.

Table 49: ReactorSubmitOptions Utility Method

RETURN CODE DESCRIPTION

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.1.6 ReactorChannel.submit(Msg...) Example

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

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

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);

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.2 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...)

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.2.1 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 DESCRIPTION

getBuffer 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.2.3 Obtaining a Buffer: ReactorChannel.getBuffer Return Values

The following table defines return and error code values that can occur while using ReactorChannel.getBuffer.

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

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.

RETURN CODE DESCRIPTION

Valid buffer returned

Success Case

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 is returned to the user. This value indicates that some type of

general failure has occurred. The ReactorChannel should be closed.

NULL buffer returned

Error Code: INIT_NOT_INITIALIZED

Indicates that the underlying Transport API Transport has not been

initialized. See the ReactorErrorInfo content for more details.

Table 51: ReactorChannel.getBuffer Return Values

METHOD NAME DESCRIPTION

submit 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.2.7 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...).

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...).

RETURN CODE DESCRIPTION

ReactorReturnCodes.SUCCESS 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

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);

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

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

torChannel.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).

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;

}

METHOD NAME DESCRIPTION

ReactorChannel.packBuffer 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.2.12 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

Success Case

The amount of available bytes remaining in the buffer for packing.

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.6.2.13 Example: ReactorChannel.getBuffer, ReactorChannel.packBuffer, and

ReactorChannel.submit(TransportBuffer…)

The following example shows typical use of ReactorChannel.getBuffer, ReactorChannel.packBuffer, and

ReactorChannel.submit(TransportBuffer…).

Code Example 13: Message Packing using ReactorChannel.packBuffer

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);

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.1 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:

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

MEMBER DESCRIPTION

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

Table 56: TunnelStreamAuthInfo Members

METHOD NAME DESCRIPTION

openTunnelStream 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.2.2 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 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.

defaultMsgCallback 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.3 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.

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.

Note: Do not modify the ClassOfService member of the TunnelStream.

MEMBER DEFAULT RANGE/ ENUMERATIONS DESCRIPTION

maxFragmentSize 6144 1 – 2,147,483,647 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.3.2 ClassOfService Authentication Member

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

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 DEFAULT RANGE/ ENUMERATIONS DESCRIPTION

type ClassesOfService.

AuthenticationTypes.

NOT_REQUIRED

ClassesOfService.

AuthenticationTypes.

NOT_REQUIRED == 0,

ClassesOfService.

AuthenticationTypes.

OMM_LOGIN == 1

Indicates the type of

authentication, if any, to

perform on the tunnel stream.

For further details on

authentication, refer to Section

6.7.1.

Table 60: ClassOfService.authentication Members

MEMBER DEFAULT RANGE/ ENUMERATIONS DESCRIPTION

type ClassesOfService.

FlowControlTypes.

NONE

ClassesOfService.

FlowControlTypes.

NONE == 0,

ClassesOfService.

FlowControlTypes.

BIDIRECTIONAL == 1

Indicates the type of flow control (if

any) to apply to the tunnel stream.

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

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.

sendWindowSize None 0 – 2,147,483,647 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.

MEMBER DEFAULT RANGE DESCRIPTION

type ClassesOfService.

DataIntegrityTypes.

BEST_EFFORT

ClassesOfService.

DataIntegrityTypes.

BEST_EFFORT == 0,

ClassesOfService.

DataIntegrityTypes.

RELIABLE == 1

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

MEMBER DEFAULT RANGE/ ENUMERATIONS DESCRIPTION

Table 61: ClassOfService.flowControl Members (Continued)

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.3.5 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 DEFAULT RANGE DESCRIPTION

type ClassesOfService.

GuaranteeTypes.

NONE

ClassesOfService.

GuaranteeTypes.

NONE == 0,

ClassesOfService.

GuaranteeTypes.

PERSISTENT_QUEUE == 1

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.

persistLocally true false, true 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.4 Tunnel Stream Callback Methods and Event Types

6.7.4.1 Tunnel Stream Callback Methods

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 DESCRIPTION

statusEventCallback 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.4.2 Tunnel Stream Callback Event Types

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

EVENT EVENT DESCRIPTION CLASS MEMBER CLASS MEMBER DESCRIPTION

TunnelStreamStatusEvent This event presents the

tunnel stream and its status. tunnelStream Returns the TunnelStream

associated with this event. When the

TunnelStream is initially opened, the

initial instance of the TunnelStream

is made available.

state Indicates status information

associated with the TunnelStream.

For example:

• 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.

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.

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

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.

TunnelStreamQueueMsgEvent This event presents any

queue message content

received on the

TunnelStream.

tunnelStream Returns the TunnelStream

associated with this event.

queueMsg Contains the content being presented

to the user, presented as a queue

message object.

// 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();

EVENT EVENT DESCRIPTION CLASS MEMBER CLASS MEMBER DESCRIPTION

Table 65: Tunnel Stream Callback Event Types (Continued)

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

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.

// 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;

}

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.

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.6.1 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:

For more information on the ProviderRole, refer to Section 6.3.3.

A TunnelStreamRequestEvent is returned to the application via the TunnelStreamListenerCallback.

6.7.6.2 ReactorChannel.acceptTunnelStream Method

listenerCallback(TunnelStreamRequestEvent event);

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

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.6.3 TunnelStreamAcceptOptions

6.7.6.4 ReactorChannel.rejectTunnelStream

6.7.6.5 TunnelStreamRejectOptions

OPTION DESCRIPTION

statusEventCallback 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

METHOD NAME DESCRIPTION

ReactorChannel.rejectTunnelStream 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

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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.6.6 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.

Code Example 15: Accepting a Tunnel Stream Code Example

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

}

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.6.7 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.

Code Example 16: Rejecting a Tunnel Stream Code Example

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

}

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.7 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

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 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

METHOD NAME DESCRIPTION

submit 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

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.8.3 TunnelStream.submit Option

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

option.

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.

Code Example 17: Submitting Content on a Tunnel Stream

MEMBER DESCRIPTION

containerType 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

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;

}

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.7.9 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

6.7.9.2 Closing a Tunnel Stream Sample

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

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.

METHOD NAME DESCRIPTION

close 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

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;

}

Chapter 6 Reactor Detailed View

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

ETAJ322UMVAC.180

6.8.1 General 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.

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.

METHOD NAME DESCRIPTION

info 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.

ioctl Allows the application to change various settings associated with the ReactorChannel. The

available options are defined in Section 6.8.3.

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

CLASS MEMBER DESCRIPTION

channelInfo 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

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 PURPOSE

Dictionary 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.

domain. Use of and support for this domain is required for all OMM applications.

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.2 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:

7.2.2 Message Base Method

MEMBER DESCRIPTION

streamId 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 Non-

Interactive Providers.

streamId is required on all messages.

Table 78: MsgBase Members

METHOD DESCRIPTION

clear() Clears the object for reuse.

Table 79: MsgBase Method

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.2.3 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

(LoginMsg)

Refer to Section 7.3

LoginMsgType.REQUEST LoginRequest

LoginMsgType.REFRESH LoginRefresh

LoginMsgType.STATUS LoginStatus

LoginMsgType.CLOSE LoginClose

LoginMsgType.CONSUMER_CONNECTION_STATUS LoginConsumerConnectionStatus

SOURCE

(DirectoryMsg)

Refer to Section 7.4

DirectoryMsgType.REQUEST DirectoryRequest

DirectoryMsgType.REFRESH DirectoryRefresh

DirectoryMsgType.UPDATE DirectoryUpdate

DirectoryMsgType.STATUS DirectoryStatus

DirectoryMsgType.CLOSE DirectoryClose

DirectoryMsgType.CONSUMER_STATUS DirectoryConsumerStatus

DICTIONARY

(DictionaryMsg)

Refer to Section 7.5

DictionaryMsgType.REQUEST DictionaryRequest

DictionaryMsgType.REFRESH DictionaryRefresh

DictionaryMsgType.STATUS DictionaryStatus

DictionaryMsgType.CLOSE DictionaryClose

Table 80: Domain Representations Message Types

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3 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 Login Request

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 Login Request 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.

MEMBER DESCRIPTION

attrib 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.

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

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

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

Section 7.3.1.2.

Table 81: LoginRequest Members

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

instanceId 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

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.

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

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

userName 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:

•Login.UserIdTypes.NAME = 1

•Login.UserIdTypes.EMAIL_ADDRESS = 2

•Login.UserIdTypes.TOKEN = 3

•Login.UserIdTypes.COOKIE = 4

•Login.UserIdTypes.AUTHN_TOKEN==5

A type of Login.UserIdTypes.NAME typically corresponds to a DACS user name and

can to authenticate and permission a 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.

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

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.

MEMBER DESCRIPTION

Table 81: LoginRequest Members (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.1.2 Login Request Flag Enumeration Values

7.3.1.3 Login Request Utility Method

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

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

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

METHOD NAME DESCRIPTION

initDefaultRequest Clears a LoginRequest object and populates userName, position, applicationId,

and applicationName with default values.

Table 83: LoginRequest Utility Method

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.2 Login Refresh

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 Login Refresh Members

MEMBER DESCRIPTION

attrib 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

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:

• Login.UserIdTypes.NAME = 1

• Login.UserIdTypes.EMAIL_ADDRESS = 2

• Login.UserIdTypes.TOKEN = 3

•Login.UserIdTypes.COOKIE==4

•Login.UserIdTypes.AUTHN_TOKEN==5

A type of Login.UserIdTypes.NAME typically corresponds to a DACS user name and

can be used to authenticate and permission a 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.

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

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.

MEMBER DESCRIPTION

Table 84: LoginRefresh Members (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.2.2 Login Refresh Flag Enumeration Values

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.2.3 Login Support Feature Set Members

For detailed information on posting, batch requesting, dynamic view use, and ‘pause and resume,’ refer to the Transport API

Java Edition Developers Guide.

MEMBER DESCRIPTION

flags 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.2.4 Login Support Feature Set Flag Enumeration Values

For detailed information on batch functionality, posting, ‘pause and resume,’ and views, refer to the Transport API Java Edition

Developers Guide.

supportOMMPost 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.

FLAG ENUMERATION MEANING

LoginSupportFeaturesFlags.HAS_SUPPORT_BATCH_CLOSES 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

MEMBER DESCRIPTION

Table 86: LoginSupportFeatures Members

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.2.5 Login Connection Config Members

7.3.2.6 Login Connection Config Methods

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.

MEMBER 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

METHOD NAME DESCRIPTION

clear Clears a LoginConnectionConfig object for reuse.

copy Performs a deep copy of a LoginConnectionConfig object.

Table 89: LoginConnectionConfig Methods

FLAG ENUMERATION MEANING

Table 87: LoginSupportFeaturesFlags (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.2.7 Server Info Members

7.3.2.8 Server Info Flag Enumeration Values

7.3.2.9 Server Info Methods

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

Table 90: ServerInfo Members

FLAG ENUMERATION DESCRIPTION

ServerInfoFlags.HAS_LOAD_FACTOR Indicates presence of loadFactor information.

ServerInfoFlags.HAS_TYPE Indicates presence of serverType.

Table 91: ServerInfo Flags

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.3 Login Status

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

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 Login Status Members

MEMBER DESCRIPTION

authenticationErrorCode 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.3.2 Login Status Flag Enumeration Values

userNameType 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:

• Login.UserIdTypes.NAME = 1

• Login.UserIdTypes.EMAIL_ADDRESS = 2

• Login.UserIdTypes.TOKEN = 3

• Login.UserIdTypes.COOKIE = 4

• Login.UserIdTypes.AUTHN_TOKEN = 5

A type of Login.UserIdTypes.NAME typically corresponds to a DACS user name

and can be used to authenticate and permission a user.

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.

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.

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.

FLAG ENUMERATION MEANING

LoginStatusFlags.CLEAR_CACHE Indicates whether the receiver of the login status should clear any associated

cache information.

LoginStatusFlags.HAS_AUTHN_ERROR_CO

DE Indicates the presence of authenticationErrorCode.

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

MEMBER DESCRIPTION

Table 93: LoginStatus Members (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

LoginStatusFlags.HAS_USERNAME_TYPE Indicates the presence of userNameType.

If absent a userNameType of Login.UserIdTypes.NAME is assumed.

FLAG ENUMERATION MEANING

Table 94: LoginStatus Flags (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.4 Login Close

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.

7.3.5 Login Consumer Connection Status

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 Login Consumer Connection Status Members

MEMBER DESCRIPTION

rdmMsgType Required. Specifies the login message type (for a login close, this will be

LoginMsgType.CLOSE).

Table 95: LoginClose Member

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.5.2 Login Consumer Connection Status Flag Enumeration Value

7.3.5.3 Login Warm Standby Info Members

7.3.5.4 Login Warm Standby Info Methods

FLAG ENUMERATION DESCRIPTION

LoginConsumerConnectionStatusFlags.HAS_WARM_STANDBY_INFO Indicates presence of warmStandbyInfo.

Table 97: LoginConsumerConnectionStatus Flags

MEMBER DESCRIPTION

action 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

METHOD NAME DESCRIPTION

clear Clears a LoginWarmStandbyInfo object for reuse.

copy Performs a deep copy of a LoginWarmStandbyInfo object.

Table 99: LoginWarmStandbyInfo Methods

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.6 Login Post Message Use

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 Login Ack Message Use

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 Login Attributes

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

preferences between components.

7.3.8.1 Login Attrib Members

The following table lists the elements available on a LoginAttrib.

MEMBER DESCRIPTION

allowSuspectData 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

flags 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.

•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.

singleOpen Optional. Indicates which application the consumer wants to drive stream

recovery.

If present, a flags value of LoginAttribFlags.HAS_SINGLE_OPEN should be

specified.

•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.

supportProviderDictionaryDownload 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.

MEMBER DESCRIPTION

Table 100: LoginAttrib Members (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.8.2 Login Attrib Methods

7.3.8.3 Login Attrib Flag Enumeration Values

7.3.9 Login Message

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.

METHOD NAME DESCRIPTION

clear Clears a LoginAttrib object for reuse.

copy Performs a deep copy of a LoginAttrib object.

Table 101: LoginAttrib Methods

FLAG ENUMERATION 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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.10 Login Message Utility Messages

7.3.11 Login Encoding and Decoding

7.3.11.1 Login Encoding and Decoding Methods

FUNCTION NAME DESCRIPTION

copy Performs a deep copy of a LoginMsg object.

Table 104: LoginMsg Utility Methods

METHOD NAME DESCRIPTION

decode 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.11.2 Encoding a Login Request

Code Example 19: Login Request Encoding Example

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);

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.11.3 Decoding a Login Request

Code Example 20: Login Request Decoding Example

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());

}

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.11.4 Encoding a Login Refresh

Code Example 21: Login Refresh Encoding Example

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);

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.3.11.5 Decoding a Login Refresh

Code Example 22: Login Refresh Decoding Example

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());

}

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4 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 DESCRIPTION

filter 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.1.2 Directory Request Flag Enumeration Values

7.4.1.3 Directory Request Methods

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.2 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 DESCRIPTION

filter 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.2.2 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.3 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 DESCRIPTION

filter 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.3.2 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.4 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 DESCRIPTION

filter 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.4.2 Directory Status Flag Enumeration Values

7.4.4.3 Directory Status Methods

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.5 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.

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

7.4.6.2 Directory Consumer Status Service Members

MEMBER DESCRIPTION

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

rdmMsgBase to DirectoryMsgType.CLOSE.

Table 116: DirectoryClose Member

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

MEMBER DESCRIPTION

action 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.7 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

7.4.7.2 Service Flag Enumeration Values

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.7.3 Service 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

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

MEMBER DESCRIPTION

acceptingConsumerStatus 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

isSource 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.

MEMBER DESCRIPTION

Table 122: ServiceInfo Members (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.8.2 Service Info Flag Enumeration Values

7.4.8.3 Service Info Methods

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.9 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

7.4.9.2 Service State Flag Enumeration Values

7.4.9.3 Service State Methods

MEMBER DESCRIPTION

acceptingRequests 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 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.

status 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

FLAG ENUMERATION DESCRIPTION

ServiceStateFlags.HAS_ACCEPTING_REQS Indicates the presence of acceptingRequests.

ServiceStateFlags.HAS_STATUS Indicates the presence of status.

Table 126: ServiceState Flags

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.10 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

7.4.10.2 Service Group Flag Enumeration Values

7.4.10.3 Service Group Methods

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

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.11 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

7.4.11.2 Service Load Flag Enumeration Values

7.4.11.3 Service Load Methods

MEMBER DESCRIPTION

action 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

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.12 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

7.4.12.2 Service Load Data Enumeration Values

7.4.12.3 Service Data Methods

MEMBER DESCRIPTION

action 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

FLAG ENUMERATION DESCRIPTION

ServiceDataFlags.HAS_DATA Indicates the presence of type, dataType, and data.

Table 135: ServiceData Flags

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.13 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

7.4.13.2 Service Link Info Methods

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.14 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 DESCRIPTION

action 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:

• Directory.LinkStates.DOWN = 0

• Directory.LinkStates.UP = 1

name 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.14.2 Service Link Enumeration Values

7.4.14.3 Service Link 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.

7.4.16 Directory Message Utility Methods

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

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

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

METHOD NAME DESCRIPTION

copy Performs a deep copy of a DirectoryMsg object.

Table 143: DirectoryMsg Utility Methods

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.17 Directory Encoding and Decoding

7.4.17.1 Directory Encoding and Decoding Methods

7.4.17.2 Encoding a Source Directory Request

Code Example 23: Directory Request Encoding Example

METHOD NAME 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

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);

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.17.3 Decoding a Source Directory Request

Code Example 24: Directory Request Decoding Example

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() == MsgClasses.REQUEST)

{

directoryRequest.clear();

directoryRequest.rdmMsgType(DirectoryMsgType.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);

}

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.17.4 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. */

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

Code Example 25: Directory Refresh Encoding Example

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);

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.4.17.5 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())

{

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

Code Example 26: Directory Refresh Decoding Example

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());

}

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5 RDM Dictionary Domain

The Dictionary domain model conveys information needed for parsing published data. Dictionaries provide additional meta-

data, 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

7.5.1.2 Dictionary Request Flag Enumeration Values

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

FLAG ENUMERATION DESCRIPTION

STREAMING 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5.2 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 DESCRIPTION

dataBody 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5.2.2 Dictionary Refresh Flag Enumeration Values

verbosity 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.

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

MEMBER DESCRIPTION

Table 147: DictionaryRefresh Members (Continued)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5.3 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

7.5.3.2 Dictionary Status Flag Enumeration Value

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 DESCRIPTION

flags 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

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

MEMBER DESCRIPTION

rdmMsgBase Required. Specifies the dictionary message type. For a dictionary close, set to

DictionaryMsgType.CLOSE.

Table 151: DictionaryClose Member

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5.5 Dictionary Messages

DictionaryMsg is the base interface for all Dictionary messages. It is provided for use with general dictionary-specific

functionality.

7.5.6 Dictionary Message: Utility Methods

7.5.7 Dictionary Encoding and Decoding

7.5.7.1 Dictionary Encoding and Decoding Methods

INTERFACE DESCRIPTION

DictionaryClose RDM Dictionary Close.

DictionaryRefresh RDM Dictionary Refresh.

DictionaryRequest RDM Dictionary Request.

DictionaryStatus RDM Dictionary Status.

Table 152: DictionaryMsg Interfaces

FUNCTION NAME DESCRIPTION

copy Performs a deep copy of a DictionaryMsg object.

Table 153: DictionaryMsg Utility 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5.7.2 Encoding a Dictionary Request

Code Example 27: Dictionary Request Encoding Example

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);

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5.7.3 Decoding a Dictionary Request

Code Example 28: Dictionary Request Decoding Example

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());

}

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.5.7.4 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);

{

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

Code Example 29: Dictionary Refresh Encoding Example

7.5.7.5 Decoding a Dictionary Refresh

/* (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);

DecodeIterator decodeIter = CodecFactory.createDecodeIterator();

DictionaryRefresh dictionaryRefresh = (DictionaryRefresh)DictionaryMsgFactory.createMsg();

Msg msg = CodecFactory.createMsg();

DataDictionary dataDictionary = CodecFactory.createDataDictionary();

dataDictionary.clear();

int dictionaryTypeForThisStreamId = 0;

{

/* (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)

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

Code Example 30: Dictionary Refresh Decoding Example

{

/* 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());

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.6 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.

If a particular queue stream is no longer needed, the user may delete the persistence file that carries the associated queue

stream’s name.

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.

Note: Thomson Reuters recommends that the ClassOfService.guarantee.persistenceFilePath be set to a local storage

device.

Warning! If you delete a persistence file that stores messages that were not successfully transmitted, the messages

will be lost.

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.6.3 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.

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.

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 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

MEMBER DESCRIPTION

flags 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 Required. Sets the message type. For a queue status, use QueueMsgType.STATUS.

state 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

MEMBER DESCRIPTION

rdmMsgBase Required. Sets the message type. For a queue close, use QueueMsgType.CLOSE.

Table 158: QueueClose Members

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.6.6 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

7.6.6.2 Queue Data Flag

QueueData messages and QueueDataExpired messages use the following flag:

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

FLAG DESCRIPTION

QueueDataFlags.POSSIBLE_DUPLICATE= 0x1 Indicates that the message was retransmitted and that the application

might have already received it.

Table 160: Queue Data Flag

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.6.6.3 Queue Message Timeout Codes

7.6.6.4 Queue Data Encoding

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

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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.6.6.5 Queue Data Message Encoding Code Sample

Code Example 31: Queue Data Message Encoding Example

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;

}

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.6.7 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

Chapter 7 Administration Domain Models Detailed View

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

ETAJ322UMVAC.180

7.6.7.2 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.

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

MEMBER DESCRIPTION

destName 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).

identifier 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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.2 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:

8.2.2.2 Clearing a Cache Error

The following method clears the CacheError.

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

METHOD NAME DESCRIPTION

clear Clears the CacheError object. Use this method prior to passing the object to a cache interface

method.

Table 167: CacheError Utility Method

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.2.3 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

8.2.3.2 Payload Cache Config Options

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

MEMBER DESCRIPTION

maxItems 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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.2.4 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.

8.2.4.1 Setting Functions

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.

METHOD NAME DESCRIPTION

setDictionary 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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.2.4.2 Setting Example

In the following example, two cache instances are created and set to a single, shared field dictionary.

‘

Code Example 32: Creating Cache and Setting to 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();

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.2.4.3 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.

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.

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.

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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.3 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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.3.2 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: " +

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

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.

cacheError.text());

CHK(ret);

}

CHK(ret);

}

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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.3.3.1 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.

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.

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

Chapter 8 Payload Cache Detailed View

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

ETAJ322UMVAC.180

8.3.3.3 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 Example 34: Cache Retrieval with Multi-Part Support

/*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();

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

ETAJ322UMVAC.180

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.

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

ETAJ_ValueAddDevGuide ETAJ Value Add Dev Guide

Navigation menu

Versions of this User Manual:

Views

Navigation