Message Broker Dev Guide

8/18/2019 Message Broker Dev Guide

1/196

2

Message Broker Developers Guide and API Reference

VERSION 6.0.3


2/196

Copyright © 2012 by Sybase, an SAP Company. All rights reserved.

This publication pertains to Sybase software and to any subsequent release untilotherwise indicated in new editions or technical notes. Information in this document issubject to change without notice. The software described herein is furnished under alicense agreement, and it may be used or copied only in accordance with the terms of

that agreement.

To order additional documents, U.S. and Canadian customers should call CustomerFulfillment at (800) 685-8225, fax (617) 229-9845.

Customers in other countries with a U.S. license agreement may contact CustomerFulfillment via the above fax number. All other international customers should contact

their Sybase subsidiary or local distributor. Upgrades are provided only at regularlyscheduled software release dates. No part of this publication may be reproduced,

transmitted, or translated in any form or by any means, electronic, mechanical, manual,optical, or otherwise, without the prior written permission of Sybase, an SAP

Company.

Sybase trademarks can be viewed at the Sybase trademarks page. Sybase and the markslisted are trademarks of Sybase, an SAP Company. A® indicates registration in the

United States of America. Java and all Java-based marks are trademarks of Sun Microsystems, Inc. in the U.S. andother countries. Unicode and the Unicode Logo are registered trademarks of Unicode,

Inc. All other company and product names used herein may be trademarks orregistered trademarks of their respective companies.

Use, duplication, or disclosure by the government is subject to the restrictions setforth in subparagraph (c)(l)(ii) of DFARS 52.227-7013 for the DOD and as set forth in

FAR 52.227-19(a)-(d) for civilian agencies.

This work may not be reproduced, in whole or in part, in any way or by any means,electronic or mechanical, including photocopying, recording or through storage andretrieval mechanisms, without prior written consent of Sybase, an SAP Company.

Sybase, an SAP Company.1 Sybase Drive

Dublin, CA 94568 USA

DC38899-01-0603-04


3/196


Table of Contents

Introduction .................................................................................................... vii

Intended audience ............................................................................................................. viiOverview of chapters ...................................................................................................... viii

Related documentation .....................................................................................................ixAbout Sybase ...................................................................................................................... xii

About Sybase Online Banking..................................................................................... xiiAbout Financial Markets Solutions ............................................................................ xii

Contacting Sybase ............................................................................................................xiii

Sales and general inquiries.......................................................................................... xiiiTechnical support......................................................................................................... xiiiDocumentation inquiries ............................................................................................ xiv

Chapter 1 Welcome to Message Broker ...................................................................... 1-1

What is Message Broker? .............................................................................................. 1-1Features and benefits.................................................................................................. 1-2

Message Broker architecture ........................................................................................ 1-3What is the design-time phase?................................................................................ 1-4What is the run-time phase?..................................................................................... 1-5

Understanding messages ................................................................................................ 1-6What are fields? ........................................................................................................... 1-6

Parsing a message ........................................................................................................ 1-8Validating a message.................................................................................................... 1-8Routing a message ....................................................................................................... 1-9

Transforming a message ............................................................................................ 1-9Using API templates ......................................................................................................1-10

Using SQL adapter templates .....................................................................................1-10Using flows ......................................................................................................................1-11

Chapter 2 Connecting to repositories and running the samples ............................... 2-1

Getting started ................................................................................................................. 2-1Connecting to repositories ........................................................................................... 2-2


4/196

Table of Contents

ii Table of Contents

Auto Reconnect........................................................................................................... 2-2

Connecting to a design-time repository ................................................................ 2-3Connecting to a run-time repository ..................................................................... 2-5

Creating temporary repository connections ........................................................ 2-6

Disconnecting from a repository............................................................................. 2-7Importing the Message Broker samples ..................................................................... 2-7

Importing the sample definitions ............................................................................. 2-7Deploying, building and running the sample.......................................................... 2-8Deploying message definitions ................................................................................. 2-9

Reporting problems ........................................................................................................ 2-9Determining a build number..................................................................................... 2-9

Chapter 3 Using the Message Broker design-time environment .............................. 3-1

Getting started ................................................................................................................. 3-2Defining message collections ........................................................................................ 3-3

Understanding message sets ......................................................................................... 3-3What are the message set components? ............................................................... 3-3About insignificant white space ................................................................................ 3-4

Adding message sets ....................................................................................................... 3-5Adding user-defined message sets ........................................................................... 3-5

Adding XML-based message sets............................................................................. 3-8Adding Java class-based message sets ................................................................... 3-12Adding SQL-based message sets............................................................................ 3-13

Request/response message model ............................................................................. 3-15Understanding field elements and properties .........................................................3-16

About field definitions .............................................................................................. 3-16About picture codes................................................................................................. 3-21About field delimiters and tags............................................................................... 3-22

About enumerations................................................................................................. 3-23About user-defined types ........................................................................................ 3-24Defining unknown field handlers............................................................................ 3-25

Reordering fields ....................................................................................................... 3-26Understanding rules ...................................................................................................... 3-26

Guidelines for writing rules .................................................................................... 3-27

Examples of rules....................................................................................................... 3-28Defining validation rules ...............................................................................................3-29

Defining implicit validation ...................................................................................... 3-30Defining explicit validation ...................................................................................... 3-30

Creating routing rules ..................................................................................................3-32Guidelines for routing rules.................................................................................... 3-32

Using routing rule templates .................................................................................. 3-33Transforming messages ................................................................................................3-39


5/196

Table of Contents


Creating transformation rules................................................................................ 3-39

Using header and trailer transformations............................................................ 3-42Understanding the transformation rules.............................................................. 3-43

Sample transformation rules................................................................................... 3-44

Defining adapter collections .......................................................................................3-45Adding adapter collections and sets ..................................................................... 3-45

Creating SQL adapter templates ........................................................................... 3-46Understanding SQL file generation ....................................................................... 3-48

Importing and exporting repository information ...................................................3-50

Specifying the Java class path ......................................................................................3-51Deploying to the run-time repository ......................................................................3-51

Chapter 4 Understanding the Message Broker DTD ..................................................4-1

Getting started ................................................................................................................. 4-1An introduction to XML ................................................................................................ 4-2

Understanding the Message Broker DTD ................................................................. 4-4What are message collections? ................................................................................ 4-4Defining a message set ............................................................................................... 4-5

Routing collections.................................................................................................... 4-11

Chapter 5 Creating API templates ...............................................................................5-1

Getting started ................................................................................................................. 5-1What is an API template? .............................................................................................. 5-2

Selecting message types to process ............................................................................ 5-2Creating an API template .............................................................................................. 5-3

Modifying template properties ..................................................................................... 5-4Changing API template properties .......................................................................... 5-4

Specifying method implementation patterns ............................................................. 5-6

Deploying a template ...................................................................................................... 5-7Deploying an EJB template ........................................................................................ 5-7Deploying an IDL template ....................................................................................... 5-7

Deploying an API template........................................................................................ 5-8

Chapter 6 Using flows .....................................................................................................6-1What is a flow? ................................................................................................................. 6-1

Activities........................................................................................................................ 6-2Control links................................................................................................................. 6-2

Sub-flows ....................................................................................................................... 6-2Loops.............................................................................................................................. 6-3Forks............................................................................................................................... 6-3

Defining a flow ................................................................................................................. 6-3


6/196

Table of Contents

iv Table of Contents

The root of a flow definition .................................................................................... 6-3

A sample flow definition ............................................................................................ 6-7Using operators ............................................................................................................... 6-9

Internal operators ..................................................................................................... 6-10

Message Broker operators...................................................................................... 6-10EJB Operators ............................................................................................................ 6-16

Java Operators ........................................................................................................... 6-17 JMS Operators ........................................................................................................... 6-18Database operators .................................................................................................. 6-23

Creating a flow using the Message Broker Manager .............................................6-24Deploying the flow ........................................................................................................6-26

Using the run-time Java API .................................................................................... 6-26

Chapter 7 Using the Message Broker run-time API ................................................... 7-1Getting started ................................................................................................................. 7-2

Understanding program flow ........................................................................................ 7-3Connecting to the run-time repository ..................................................................... 7-4Parsing text-encoded messages .................................................................................... 7-5

Using a handler for unknown fields......................................................................... 7-6Constructing IDL/Java message instances .................................................................. 7-7

Invoking message validation rules ................................................................................ 7-8Invoking message routing rules .................................................................................... 7-8Transforming messages to another format ............................................................... 7-9

Building messages ............................................................................................................ 7-9Logging, and debugging message contents ........................................................... 7-10

Persisting messages using SQL adapter templates .................................................7-11Understanding transactions .................................................................................... 7-11Sample code................................................................................................................ 7-12

Executing a flow .............................................................................................................7-14

Chapter 8 Using Message Broker Server .....................................................................8-1

Getting started ................................................................................................................. 8-1What is the Message Broker Server? ......................................................................... 8-2

Using Message Broker Server .................................................................................. 8-2Executing flows ............................................................................................................ 8-3

Using Message Broker Manager ................................................................................... 8-4The Message Broker Server run-time API ................................................................ 8-5Message Broker Server examples ................................................................................ 8-6

Parse and validate to GlobalFIX............................................................................... 8-6

JMS queue to GlobalFIX .......................................................................................... 8-10


7/196

Table of Contents


Chapter 9 IDL/Java message representation ...............................................................9-1

Getting started ................................................................................................................. 9-2Overview ........................................................................................................................... 9-3

Location of generated files ............................................................................................ 9-3Using generated IDL ................................................................................................... 9-3Using generated Java................................................................................................... 9-4

Mapping for message bodies, headers, and trailers ................................................. 9-5IDL definitions for message headers, bodies, and trailers ................................. 9-5

Java classes for message headers, bodies, and trailers........................................ 9-6

Mapping for atomic types .............................................................................................. 9-6Mapping for enumerations ............................................................................................ 9-7

Using the IDL enumeration representation .......................................................... 9-8

ValueSet Java class .......................................................................... 9-9Mapping for composite types .....................................................................................9-12

IDL mapping................................................................................................................ 9-12 Java mapping ............................................................................................................... 9-12

Mapping for unions ........................................................................................................ 9-13

Mapping in IDL ........................................................................................................... 9-13Mapping in Java........................................................................................................... 9-13

Mapping for user-defined types ..................................................................................9-14

Using optional fields ...................................................................................................... 9-15Default values ............................................................................................................. 9-15

Mapping of repeated fields ..........................................................................................9-15Mapping for SQL Type .................................................................................................9-16

Viewing generated Java and IDL code ......................................................................9-17Viewing Java code...................................................................................................... 9-17Viewing IDL code ...................................................................................................... 9-17

Appendix A Javadoc .......................................................................................................... A-1Using the Message Broker API documentation ........................................................A-1

What Financial Fusion provides .............................................................................. A-1Accessing the API documentation.......................................................................... A-1

Viewing the API documentation ............................................................................. A-2

Index ............................................................................................................IX-1

Reader Comment Form ............................................................................ R-1


8/196

Table of Contents

vi Table of Contents


9/196


Introduction

About thischapter

This chapter describes the intended audience for this guide, a chapter overview, adescription of the documentation set and how to contact Sybase.

Topics include:

Intended audience (p. vii)

Overview of chapters (p. viii)

Related documentation (p. ix)

About Sybase (p. xii)

Contacting Sybase (p. xiii)

Intended audience

Message Broker is a tool kit that allows communication between multiple messageformats and applications.This guide is intended for software developers who will

be implementing and customizing Message Broker. The guide provides a closerlook at the Message Broker architecture, the tasks you can perform and a

description of the API.


10/196

Overview of chapters

viii Introduction

Overview of chapters

This guide includes the following chapters:

Chapter 1 Welcome to Message Broker – contains a complete overview of Message

Broker’s features and functionalities.

Chapter 2 Connecting to repositories and running the samples – describes how toconfigure and connect to the Message Broker repositories and introduces the

Message Broker samples.

Chapter 3 Using the Message Broker design-time environment – discusses the Message

Broker design-time configuration tasks that are performed from Message BrokerManager.

Chapter 4 Understanding the Message Broker DTD – discusses the elements of theMessage Broker document type definition (DTD). The Message Broker DTD

enables you to create valid XML documents that contain Message Brokerdefinitions that you can import into the design-time repository.

Chapter 5 Creating API templates – covers the procedures for creating, modifying, and

deploying API templates.

Chapter 6 Using flows – introduces the concept of Flow and how you can use it to specifysequences of message processing events without having to code directly to the

API.

Chapter 7 Using the Message Broker run-time API – explains how to use the Message

Broker run-time API in stand-alone Java applications or in server components suchas Enterprise JavaBeans.

Chapter 8 Using Message Broker Server – introduces the Message Broker Server and howit is used to execute flows. It also discusses how to monitor, stop and start

Message Broker Server from the Message Broker Manager. The Message Brokerrun-time API is also provided.


11/196

Related documentation


Chapter 9 IDL/Java message representation – discusses how to define message formats,

map for various data types and fields, and view generated Java and IDL code.

Appendix A Javadoc – chapter provides you with information on locating and using theMessage Broker Javadocs.


This Message Broker Developers Guide and API Reference belongs to both the Sybase

GlobalFIX and Sybase Online Banking documentation sets, which include:

GlobalFIX – TradeForce GlobalFIX provides the complete solution to thestraight through processing (STP) requirements of the brokerage industry.

Through its XML-enabled Message Broker component, GlobalFIX facilitatescommunication between various message formats and applications, and allows

financial institutions to define messages and rules for industry standardprotocols such as FIX, SWIFT, and STEP. TradeForce GlobalFIX also supportsmost in-house proprietary protocols.

• GlobalFIX Installation and Configuration Guide – for individuals whoinstall the main compenents of GlobalFIX. This guide includes system anddatabase prerequisites, as well as the steps required to install and

configure GlobalFIX servers.

• GlobalFIX Developers Guide and API Reference – for software developerswho implement and customize GlobalFIX. This guide covers the GlobalFIX

architecture, the tasks users can perform, and information aboutcustomization.

• GlobalFIX Feature Guide – for end users, system administrators, andpurchasing executives who evaluate GlobalFIX to determine the featuresand functionality it offers.

• GlobalFIX Quick Start Guide – for individuals who will be running theGlobalFIX demo.

Sybase Online Banking – Sybase Corporate Online Banking enables you toadminister company accounts with many individual accounts and users per

company client. Sybase Retail Online Banking enables you to manage individualcustomer clients. Business Central works dynamically with both SybaseCorporate Online Banking and Sybase Retail Online Banking, enabling banks

to manage business and consumer accounts, as well as bank employees.


12/196


x Introduction

• Sybase Retail Online Banking and Sybase Corporate Online BankingInstallation and Configuration Guides – for individuals who install the maincomponents of Sybase Online Banking. These guides include system and

database prerequisites, as well as the steps required to install the banking

suite and its subcomponents.• Developer Basics Guide – for software developers who implement and

customize Sybase Online Banking. This guide provides introductoryinformation about the solution and provides critical informationdevelopers need to start an implementation.

• Sybase Corporate Online Banking Developers Guide – for softwaredevelopers who implement and customize Sybase Corporate OnlineBanking. This guide covers the Sybase Corporate Online Banking

architecture, the tasks users can perform, and information aboutcustomization.

• Sybase Retail Online Banking Developers Guide – for software developerswho implement and customize Sybase Retail Online Banking. This guidecovers the Sybase Retail Online Banking architecture, the tasks users canperform, and information about customization.

• Business Central Developers Guide – provides application developers andIT staff with information about how Business Central works, whatmodules and components it is made up of, and how to administer and

customize those components to meet their needs as a financial institutionand to meet their customer’s needs.

• Sybase Corporate Online Banking Feature Guide – for end users, system

administrators, and purchasing executives who evaluate Sybase CorporateOnline Banking to determine the features and functionality it offers.

• Sybase Retail Online Banking Feature Guide – for end users, systemadministrators, and purchasing executives who evaluate Sybase RetailOnline Banking to determine the features and functionality it offers.

• Business Central Feature Guide – for end users, system administrators,and purchasing executives who evaluate Business Central to determinethe features and functionality it offers.

• Business Central Administrators Guide – for bank employees and otheradministrators who use Business Central to configure and managebusinesses, consumers, and other bank employees.

• Sybase Retail Online Banking Localization Guide – for developers wholocalize Sybase Retail Online Banking. This guide provides the informationneeded to successfully localize Sybase Retail Online Banking.


13/196



• Javadoc – the Sybase Online Banking API documentation (Javadoc) isprovided in HTML format for online use. The files are available under the/docs directory on your installation CD.

• Online Help – distributed with Corporate Banking, Consumer Banking,

and Business Central, online help provides end-users with informationpertinent to the page they are currently working on. Online help provides

conceptual information along with step-by-step instructions.

Bill Payment and Transfer Warehouse – Bill Payment and TransferWarehouse (BPTW) enables a financial institution to control the total

payment processing and warehousing of customer information.

• Bill Payment and Transfer Warehouse Developers Guide – for softwaredevelopers who implement and customize Bill Payment and Transfer

Warehouse. This guide covers the BPTW architecture, the tasks users canperform, and information about customization.

• Bill Payment and Transfer Warehouse Installation and ConfigurationGuide – for individuals who install Bill Payment and Transfer Warehouse.This guide includes information about system and database prerequisites,installation steps, and post-installation processing required to make BPTW

operational.

• Bill Payment and Transfer Warehouse Feature Guide – for end users,system administrators, and purchasing executives who evaluate BPTW to

determine the features and functionality it offers.

One-to-One Marketing – One-to-One Marketing is a marketing message toolthat enables you to create, manage, and deliver targeted marketing messages

to customers who use Web transaction products such as online banking andbill payment software.

• One-to-One Marketing Message Manager Users Guide – provides userswith the information they require to understand how the One-to-OneMarketing system works, and the steps necessary to use and manage theMessage Manager application.

• One-to-One Marketing Technical Reference – for individuals who installOne-to-One Marketing. The guide provides information about system anddatabase prerequisites, installation steps, and post-installation processing

required to run One-to-One Marketing.

Message Broker – Message Broker is a toolkit that allows communicationbetween multiple message formats and applications. Message Broker

components provide message validation, persistence, transformation, routing,and message processing flow.


14/196

About Sybase

xii Introduction

• Message Broker Installation and Configuration Guide – for softwaredevelopers who implement and customize Message Broker. This guideprovides information about the Message Broker architecture, installation

steps, and configuration options.

Universal Alerts Engine – Universal Alerts Engine (UAE) is a middlewarecomponent used for generating notification messages (alerts) to applications

and end user devices.

• Universal Alerts Engine Developers Guide and API Reference – forsoftware developers who implement and customize UAE. This guide

covers the UAE architecture, the tasks the user can perform, and adescription of the API.

• Universal Alerts Engine Feature Guide – a brief overview of the featuresand architecture of the Universal Alerts Engine.

About Sybase

Sybase provides integrated financial solutions to more than 200 of the world'sleading financial institutions. Sybase maintains strategic technology relationships

with BEA, IBM, Microsoft, Sun Microsystems, and SWIFT. We supply service andsupport in 60 countries and are a wholly owned subsidiary of SAP, Inc. (NYSE: SY)

About Sybase Online Banking

Sybase Online Banking is designed to meet the online banking needs of thefinancial services industry. Our solutions offer multiple delivery channel servicesfor consumers, small businesses and large corporate cash management customers.

We support multi-bank environments, banking, imaging, bill payment andpresentment, customer care, and industry protocols.

About Financial Markets Solutions

Sybase solutions for Financial Markets are designed to meet the STP connectivityand integration requirements of the trading industry. Our solutions provide

processing for transaction intensive trading organizations such as securities andinvestment firms, ECNs and network providers. We support FIX, SWIFT, VMUsand proprietary protocols.


15/196

Contacting Sybase


Contacting Sybase

The following sections provide contact information for Sales, Technical Support,

and Technical Publications.

Sales and general inquiries

For sales or general information about Sybase or any of our Banking or Financial

Markets products, contact us:

Web:www.sybase.com

Mail

Sybase, an SAP Company

561 Virginia RoadConcord, MA 01742

Phone:1-800-842-0885 or 1-978-287-1975

E-mail:

[email protected]

Technical support

Sybase uses the Sybase Case Management System to log and track all support

issues. If you have a mysybase account, go to www.sybase.com/support

If you do not have a mysybase account or are uncertain if you do, call1-800-8SYBASE and a customer service representative will assist you.


16/196

Contacting Sybase

xiv Introduction

Documentation inquiries

For documentation issues or concerns, review the following information.

Reader Comment Form

To help us improve our documentation, each guide includes a Reader Comment

Form located at the end of the guide. Please complete this form and fax, mail, ore-mail the information to our Technical Publications team using the contact

information below.

Contact information

To contact the Sybase Technical Publications team:

Mailing address:

Sybase, an SAP Company

Attention: Technical Publications445 Wes Graham WayWaterloo ON N2L 6R2Canada

Fax:

(519) 747-4971

E-mail:

[email protected]


17/196


1

Welcome to Message Broker

About thischapter

This chapter introduces the features, concepts, definitions, and advantages uniqueto Message Broker.

Topics include:

What is Message Broker? (p. 1-1)

Message Broker architecture (p. 1-3)

Understanding messages (p. 1-6)

Using API templates (p. 1-10)

Using SQL adapter templates (p. 1-10)

Using flows (p. 1-11)

What is Message Broker?

Message Broker is a tool kit that allows communication between multiple messageformats and applications. Specifically, Message Broker consists of a series of pure

Java components that run in process to facilitate:

Message definition, parsing and message validation

Enterprise Java bean-based message routing

Message extensibility

Translation between Common Message Protocols (OFX, FIX and SWIFT), in-house proprietary versions of these protocols, and target applications such as

order management systems, legacy systems, market feeds and more

Message persistence


18/196


19/196

Message Broker architecture


Message Broker architecture

Message Broker includes a design-time database repository

where you define and store message collections and rules. This design informationis then deployed to a run-time repository.

The design-time environment is used for defining message sets and rules

The run-time environment uses the defined message sets and rules and

performs the run-time operations of parsing incoming messages into their Javaobject representations, validating message field content, routing messages to

different targets, transforming messages from one format to another,persisting messages to databases, executing flows, and building from the Javaobject representations back to the message strings

The design-time and run-time phases are shown below. Figure 1-1:

Message Brokerarchitecture.

Having separate repositories for the design-time and run-time environments

allows you to continue designing and modifying information in the design-timeenvironment without affecting the deployed run-time environment.


20/196


21/196


22/196

Understanding messages

6 Welcome to Message Broker


A message is a structure that holds information. It can contain a header and a

trailer, as well as the message body. Headers, trailers, and message bodies cancontain multiple fields. The fields comprising a message vary from protocol toprotocol.

A protocol such as SWIFT contains various message sets. Each set contains agroup of messages that has a specific format and performs a specific task. Forexample, the FIX protocol requires a header and trailer for each message. The

header identifies the message type, length, destination, sequence number,origination point, and time.

Other protocols may not require a header, or require headers that contain

different information. You should be familiar with the various protocols that you

are working with to effectively use Message Broker to create message sets,validation rules, routing rules, and other configuration tasks.

The message body, also called the message definition, if it exists, is locatedbetween the header and the trailer. Each message definition shares the header andtrailer of that message set.

The next sections discuss the role of fields in messages and parsing, validating,routing and transforming messages.

“What are fields?” on page 1-6

“Parsing a message” on page 1-8

“Validating a message” on page 1-8

“Routing a message” on page 1-9

“Transforming a message” on page 1-9

What are fields?

Fields contain user data as well as data about the fields themselves. There arethree primary ways to define a field length. You can do any of the following:

Set a field length and define pad characters to add at the beginning or end of

the field if the user data does not equal the defined field length

Define a variable or fixed field and specify the characters or delimiters that

indicate the beginning and end of the field

Define the length of a field through the use of tags and delimiters

The figure below illustrates different approaches for determining field length.


23/196



Figure 1-2:Determining field

length.

At run time, this field information is compiled into message definition classes and

used by the parser to parse the incoming message.

With Message Broker, you can define other field characteristics as well, such as:

the type of data contained in the field

whether or not the field itself can contain “other” fields

whether or not a field is optional or can be repeated

You can also select the data type that the parser outputs. Keep in mind that all

incoming user data is read as characters.


24/196



Parsing a message

When you deploy to the run-time repository, your message definitions are

compiled into message class definitions. From within your application, create aMessage Broker instance and call the IParser API, which parses the incomingmessage.

To parse a message:

1. Send the unparsed message to the application.

2. The application creates a Message Broker instance (if one is not alreadycreated) and calls the parser API.

3. The IParser API parses the incoming message based on the message set

information that is stored in the run-time repository. It creates a messageobject using the message definition classes that were created during deploy

time to hold onto the parsed message data.

4. Pass the message on to other Message Broker APIs.

Validating a message

Message Broker validates incoming messages by verifying that the message meetsthe criteria you have specified for your message definitions. There are two types of

validation: implicit and explicit.

Implicit validation

Implicit validation is specified as part of the field definition. You define the field and

ensure that the incoming message fits the criteria you established in the messagedefinition so that it will be recognized as a valid message. For example, you could

define a fixed value that contains FIX.4.0 in the header. The parser verifies that theheader contains this value as part of implicit validation. No Java code is requiredfor implicit validation.

Explicit validation

Explicit validation allows you to write validation rules in Java code. These rules arecompiled at run time and referenced by the Message Broker IValidation API.Explicit validation provides greater control in verifying message content. For

example, you could write Java code that checks for the existence of a particularcharacter string at the beginning of a field. In the case of an e-mail address, if a user

wanted to verify that a particular field represents an e-mail address, they wouldneed to explicitly write code to verify that what they have is an e-mail address.


25/196



Routing a message

Routing passes a message to business logic whenever a condition is true. You write

a routing condition in Java code that returns either true or false. At run time,Message Broker compiles the routing code and routes a parsed message to anEAServer component, a Java class, or an EJB, if the condition is true. As the figure

below illustrates, you could write a routing rule that checks the header and routesany message that contains the FIX 4.0 string to an EAServer component.

Figure 1-3:Sample routing rule.

Transforming a message

Transformation rules convert a message type to a different message type. For each

destination field in the target message, transformation rules instruct MessageBroker how to fill in the destination field, given the values in the source fields. At

run time, the Message Broker ITransformation API transforms a message, field byfield, from the source message type to the destination message type.

For example, you can define transformation rules that convert FIX messages into

SWIFT messages. The ITransformation API changes the FIX message to a SWIFTmessage based on the transformation rules that are stored in the run-timerepository, then forwards the message to the SWIFT server for processing.


26/196

Using API templates


Using API templates

Templates are useful for defining several methods that share a common

implementation pattern. You can use Message Broker to define an API template for Java methods that process messages. Message Broker provides macros forrepeated code elements such as a message’s name, Java, or Interface Design

Language (IDL) data type.

You can use the template to create an EJB or an IDL interface. For an EJB template,Message Broker generates the home interface, remote interface, and

implementation class for a stateful session bean based on the template propertiesdefined in Message Broker Manager. For an IDL template, Message Brokergenerates a complete IDL interface, and you can define a CORBA component that

implements the interface. Chapter 5: Creating API templates describes how to use

this feature.

Using SQL adapter templates

SQL Adapter templates allow you to store messages into a database. It also allowsyou to retrieve, update, and delete persisted messages. You can specify specificfields in a message as well as custom data to store separately from the raw,

unparsed data.

SQL Adapter templates outline the information needed to generate DataDefinition Language (DDL) and Data Manipulation Language (DML) code used to

save messages to a database. Message Broker supports two types of SQL adaptertemplates:

Generic templates. Generate a single table that is capable of storing allmessage types defined in the message set that is associated with the adapter

set. Generic templates can save the unparsed representation of all messageswithin the message set, as well as the values for any fields in the header ortrailer. In addition, you can define custom columns in the table to store

information that is associated with each message, such as the state

information about the message.


27/196

Using flows


Message-specific templates. Generate tables that are capable of storing one

message type in each table. Message-specific templates can save the unparsedrepresentation of all messages within a message set, as well as the values for

any fields in the message. Similar to generic templates, custom columns can be

defined for each table. “Defining adapter collections” on page 3-45 explainshow to create SQL adapter templates.

Using flows

Flows are used to perform a sequence of message processing operations. Theseoperations include invoking the Message Broker run-time API, working with JMSqueues, creating database connections, and calling into custom Java classes and

EJBs.

Flows are specified in a declarative manner using XML. The format of the XML is

defined by a Flow DTD which is included with Message Broker.

Flows are executed using the run-time API or the Message Broker Server. Formore information on Flows see Chapter 6: Using flows. For details on Message

Broker Server, see Chapter 8: Using Message Broker Server.


28/196

Using flows



29/196


2

Connecting to repositoriesand running the samples

About thischapter

This chapter describes how to configure and connect to the Message Brokerrepositories and introduces the Message Broker samples.

Topics include:

Getting started (p. 2-1)

Connecting to repositories (p. 2-2)

Importing the Message Broker samples (p. 2-7)

Reporting problems (p. 2-9)

Getting started

Before you connect to the repositories and run the samples, review the following

steps:

1. You can create and connect to the repositories supported by Message Broker.For details, see “Connecting to repositories” on page 2-2.

2. To become more familiar with Message Broker, run the samples included with

Message Broker. See “Importing the Message Broker samples” on page 2-7.

3. To contact Financial Fusion with any issues, see “Reporting problems” onpage 2-9.


30/196

Connecting to repositories

2 Connecting to repositories and running the samples


After you have started Message Broker, you can create and connect to the

Message Broker repositories. Message Broker uses the following two repositories: Design-time repository. This repository is a set of database tables where

you can create, modify, or store message, routing, and transformation

collections without affecting the run-time environment.

Run-time repository. The run-time repository can use the same database asthe design-time repository, or it can run on a separate database. When you

deploy the design-time repository to the run-time repository, the message,routing, and transformation collections are compiled into Java classes. These

Java classes are used with the Message Broker run-time APIs to parse, build,

validate, route, and transform incoming messages based on your design-time

definitions.

You can connect to and store your Message Broker repositories in different

databases by creating connection profiles for each repository. However, eachdatabase can contain only one design-time and one run-time repository.

NOTE: This chapter uses the Sybase ASA demonstration database that ships with Message Broker. A connection profile, MBDemo, is automatically created atinstallation.

To connect to the repositories or to perform other tasks, see:

“Connecting to a design-time repository” on page 2-3

“Connecting to a run-time repository” on page 2-5

“Creating temporary repository connections” on page 2-6

“Disconnecting from a repository” on page 2-7

Auto Reconnect

The auto-reconnect feature tests the status of the repository connection beforeperforming operations which require repository access. If the connection to the

repository has been closed (most often due to a connection timeout from thedatabase server), Message Broker automatically attempts to reconnect to therepository. If the connection is re-established, Message Broker proceeds with the

operation and it appears as if nothing out of the ordinary has happened. If theconnection cannot be automatically re-established, an error is issued informing the


31/196



user that the connection to the repository has been lost and that they need to

manually reconnect to the repository and repeat the operation.

The auto-reconnect feature works with design-time and run-time repositories. Forexample, it works in the design-time repository before importing/exporting/

deploying sets, expanding fields, or copying-pasting fields, and in the run-timerepository before loading a message set, routing set, and so on.

Connecting to a design-time repository

To connect to a design-time repository, you must complete the following generalsteps:

“Creating a new connection profile” on page 2-3

“Starting the sample database” on page 2-4

“Connecting to the design-time repository” on page 2-4

Creating a new connection profile

1. Start Message Broker Manager.

2. Select Tools > Connection Profiles.

3. Click New.

4. Enter a name for the connection profile, for example, Demo. Specify that the

profile type is Message Broker and click OK .

5. Enter these values to use the sample ASA database:

• User ID: DBA• Password: SQL• Host machine: localhost• Port number: 2638• Database name: mbdemo

NOTE: For convenience, an empty ASA database is included in the samplessubdirectory of your Message Broker installation.


32/196


33/196



Connecting to a run-time repository

Connecting to a run-time repository allows you to view the deployed design-time

information. The run-time repository is read-only, so you must make any desiredchanges in the design-time repository and redeploy them to the run-timerepository.

NOTE: To connect to run-time repositories on Oracle via the OCI8 (thick client) driver, Message Broker supports lookup of database connection parameters from theTNSNAMES.ORA configuration file. To have Message Broker obtain theconnection information from the TNSNAMES.ORA configuration file, specifythe Oracle SID for the database instance in the database name field and leavethe machine name field blank (the port number field is ignored in this case).This method of specifying the connection parameters is required for connectingto Oracle Parallel Server (OPS).

To connect to a run-time repository, complete the following general steps:

“Creating a new connection profile” on page 2-3

“Starting the sample database” on page 2-4

“Connecting to the design-time repository” on page 2-4

Creating a new run-time repository

1. Select Tools > Connection Profiles from within the Message BrokerManager.

2. Click New.

3. Enter a name for the connection profile, for example, MBView. Make sure the

profile type is Message Broker and click OK .

NOTE: For convenience, an empty ASA database is included in the samplessubdirectory of your Message Broker directory.


34/196



Starting the sample database

1. Select Runtime Repository from the Connect to drop-down list.

2. Select the appropriate database type from the Database Type drop-down

list.3. Enter the connection information for the database where you want to store

the run-time repository. You can use the same database to store the run-time

and design-time repositories.

4. To use the sample database, enter the following values:

• User ID: DBA• Password: SQL• Host machine: localhost• Port number : 2638

• Database name: mbdemoThe user ID and password are case sensitive. To use a different database,make sure the database is case sensitive for string compares.

You have now defined a connection profile that you can use whenever you want toconnect and view the repository.

Connecting to the run-time repository

1. Select the profile.

2. Click Connect.

NOTE: You must deploy to the run-time repository before you can view its contents.

Creating temporary repository connections

You can create temporary connections to design-time and run-time repositories.

Temporary connections are valid for the length of the Message Broker Managersession.

To temporarily connect to a repository:1. Select Tools > Connect.

2. Enter the connection information for the repository to which you want toconnect, including the type of repository from the drop-down list.

3. Click OK .


35/196

Importing the Message Broker samples


Disconnecting from a repository

To disconnect from a repository:

1. Select Tools > Disconnect.

2. Select the repository you want to disconnect from and click Disconnect.

Only repositories with active connections are displayed.

NOTE: You can also right-click the desired repository and select Disconnect.


Message Broker comes with a set of sample definitions in XML format that are agood way to become familiar with Message Broker.

The following sections describes how to import these samples into the design-

time repository and deploy them to the run-time repository:

“Importing the sample definitions” on page 2-7

“Deploying, building and running the sample” on page 2-8

“Deploying message definitions” on page 2-9

NOTE: For the most recent information on the samples, refer to the readme file in thesamples directory of your Message Broker installation.

Importing the sample definitions

1. Locate the .xml files in the samples subdirectory.

2. Highlight the repository icon by clicking it once.

3. Select File > Import.

4. Browse to the files with the .xml extension in the samples directory and select

Import. You can either import all of the XML files at the same time or import MessageSets.xml first if you are importing them one at a time. Message Broker

imports the sample message definitions into the design-time repository.

5. Add a class path to your design-time repository. To do this in the MessageBroker Manager:


36/196



a. Right-click the repository.

b. Select Properties.

c. Click the Class Path tab.

d. Enter the full path of the Message Broker samples directory into the textfield.

e. Click Add.

6. Once you have entered your message definitions in the design-time

repository, deploy them to the run-time repository to make them available foruse.

Deploying, building and running the sample

To deploy, build and run the sample:

1. Deploy the message collection.

a. Expand the repository.

b. Expand the Message Collections folder.

c. Right-click on Message Collection and select Deploy to Connection

Profile from the pop-up menu.

d. Select the MB Demo Run-time connection profile and click Deploy.

2. Build the sample by executing make.bat, located in the samples directory. The

samples can only be built after the message collection has been deployedbecause they depend on the files that are generated by the Message Broker

deployment process.

3. Deploy the routing collection and transformation collection respectively.RoutingCollection can only be deployed after the samples have been built

since it references the RouteTarget class.

4. Make sure the run-time repository database is running before executingrun.bat. Run the samples one at a time by using the following batch files:

run FlowTest.batrunParseBuild.batrunParsePersist.batrunParseTransformBuild.batrunParseValidate.bat

Explanations of the samples are provided via comments in the Java files. The batchfiles assume that jConnect is installed and that the MB60JCONNECTDIR

environment variable is set to the jConnect location. The samples assume the use


37/196

Reporting problems


of ASA and jConnect. If you are using a database other than ASA for the run-time

repository then the Java source files need to be modified accordingly.

Deploying message definitions

To deploy message definitions:

1. Highlight the repository icon.

2. Select File> Deploy to Connection Profile.

3. Select the MB Demo Runtime connection profile.

4. Click Deploy.

Once the deployment is complete, you can use the sample parser and builder on

your compiled message definitions in the run-time environment.

For an example of how to invoke the parser and builder, see the comments in thefile ParseBuild.java in the samples directory. This sample uses the sample definitions

provided in XML format to parse the information in the file and then build a bufferwhich can be viewed as an output file.

Reporting problems

Report any problems with this build to your Financial Fusion representative. Please

have the following information ready before contacting Financial Fusion:

The build number for the version of Message Broker that you are using

The error message given

If possible, a list of steps required to reproduce the problem

Determining a build number

To determine the build number:

1. Start the Financial Fusion Management Console.

2. Select Tools > Plug-ins. The build number is listed under Version for theMessage Broker plug-in.


38/196

Reporting problems



39/196


3

Using the Message Brokerdesign-time environment

About thischapter

This chapter discusses the Message Broker design-time configuration tasks that areperformed from Message Broker Manager.

Topics include:

Getting started (p. 3-2)

Defining message collections (p. 3-3)

Understanding message sets (p. 3-3)

Adding message sets (p. 3-5)

Request/response message model (p. 3-15)

Understanding field elements and properties (p. 3-16)

Understanding rules (p. 3-26)

Defining validation rules (p. 3-29)

Creating routing rules (p. 3-32)

Transforming messages (p. 3-39)

Defining adapter collections (p. 3-45)

Importing and exporting repository information (p. 3-50)

Specifying the Java class path (p. 3-51)

Deploying to the run-time repository (p. 3-51)


40/196


41/196

Defining message collections


Defining message collections

A message collection is a container for message sets. It allows you to group related

message sets together in the design-time repository. You can create a messagecollection either by using wizards, by importing them from an XML file, or acombination of both.

This section discusses how to create message collections using the MessageBroker Manager. For information on importing message collections from an XMLfile see “Importing and exporting repository information” on page 3-50.

To create a message collection:

1. Highlight the Message Collections folder.

2. Double-click the Add Message Collection icon.

3. Follow the wizard’s instructions.

Understanding message sets

The following sections provide details about message sets and how they are usedin Message Broker:

“What are the message set components?” on page 3-3

“About insignificant white space” on page 3-4

What are the message set components?

A message set can consist of the following components:

Header (optional): You can define only one header for each message set, butthe header can contain multiple fields. You can establish a field that is the

message-type indicator, which is used by the parser, to identify a messagebody from this field.

Trailer (optional): You can define only one trailer for each message set. Like

the header, the trailer can contain multiple fields.

Message definitions: This is the body of the message where you can includefield definitions and validation rules for your message set. Each message

definition in the set uses the same header and trailer, if defined.


42/196

Understanding message sets

4 Using the Message Broker design-time environment

Enumerations: You can create and add enumerations used to validate the

header, trailer, and message fields. For details, refer to “About enumerations”on page 3-23.

User-defined Types: You can define fields and data types in the User-defined

Type folder. Refer to “About user-defined types” on page 3-24 and “Attachingvalidation rules to user-defined types” on page 3-31 for more information.

Unknown Field Handler: You can register a Java method that is invoked by

the parser at run time if it encounters an unordered composite member thatit does not recognize. Refer to “Defining unknown field handlers” on page 3-

25 for more information.

Delimiters: You can define delimiters and pad characters for all fields in allmessages belonging to the message set. You can override these setting at the

field level. Refer to “About field definitions” on page 3-16 for additionalinformation.

About insignificant white space

When the “ignore insignificant white space” property is enabled, it is assumed that

the tag and field delimiters that consist of white space characters are not specified.Insignificant white space is defined as follows:

white space before and after the message definition

white space leading and trailing tagged/delimited atomic field values

white space between the tags and delimiters of adjacent tagged/delimitedsibling or parent/child fields

The following Unicode characters are considered insignificant white space:

A Unicode space separator (category “Zs”), but not a no-break space (\u00A0

or \uFEFF)

A Unicode paragraph separator (category “Zp”)

A Unicode line separator (category “Zl”)

\u0009, horizontal tabulation

\u000A, line feed

\u000B, vertical tabulation

\u000C, form feed

\u000D, carriage return

\u001C, file separator

\u001D, group separator

\u001E, record separator


43/196

Adding message sets


\u001F, unit separator

Adding message setsMessage Broker supports user-defined, XML-based message sets, Java class-basedmessage sets, and SQL-based message sets. Review the appropriate section below

for details on adding a specific type of message set:

“Adding user-defined message sets” on page 3-5

“Adding XML-based message sets” on page 3-8

“Adding Java class-based message sets” on page 3-12

“Adding SQL-based message sets” on page 3-13

Adding user-defined message sets

User-defined message sets are defined through Message Broker Manager and donot contain root elements. This allows you to change the structure by copying,

pasting, adding and deleting fields.

The following sections describe how to add a user-defined message set, addheaders, trailers to the message set, define a message and other related tasks.

To add a user defined message set:

1. Open the Message Collections folder.

2. Highlight the message collection to which you are adding the message set.

3. Double-click the Add Message Set icon.

4. Follow the wizard’s instructions. When you are prompted for the type of themessage set, select User defined.

Defining a header

To define a header for a message set:

1. Highlight the message set to which you are adding a header.

2. Double-click the Add Header icon.


When defining the message set header remember to specify whether the fields ofthe message set header must be ordered. If unordered, the header must contain all


44/196

Adding message sets


defined fields. Also specify the delimiters and tags. Refer to “About field delimiters

and tags” on page 3-22 for more information.

NOTE: To use a header field as the message-type indicator select File > Use as

Message-Type Indicator . Refer to “Defining a field” on page 3-6 tosee how a message is located from its header when the message-typeindicator is set. You can also specify atomic user data types as message-type indicators.

Defining a trailer

To define a trailer for a message set:

1. Highlight the message set to which you are adding a trailer.

2. Double-click the Add Trailer icon.

3. Follow the wizard’s instructions, keeping the following in mind:

a. When defining a trailer for a message set remember to specify whetherthe fields of the message set trailer must be ordered. Fields within theheader/trailer can be optional.

b. You should also specify whether the trailer is optional. If you select Thistrailer is optional, messages are considered valid if they do not contain a

trailer, as long as the rest of the message is valid.

c. Also specify the delimiters and tags. Refer to “About field delimiters and

tags” on page 3-22 for additional information.

Adding a field

To add a field to a header, trailer, or message:

1. Highlight the header, trailer, or message to which you are adding a field.

2. Double-click the Add Field icon.


Defining a field

To define a message:

1. Highlight the Message Definitions folder.

2. Double-click the Add Message Definition icon.

3. Follow the wizard’s instructions as outlined below.


45/196

Adding message sets


a. Establish message-type indicator values that inform the parser which

message the header belongs to.

b. Create a header field called messageType and mark it as the message-type indicator.

c. Include the value that you expect in the messageType field for eachmessage body you create. For example, in the customer sample that

comes with Message Broker, the message-type indicator in the header iscalled msgType. The enumeration msgType is defined to accept the valuesAdd or Del. There is one message body called AddCustomer that

corresponds to the message type Add and a message body calledDeleteCustomer that corresponds to Del.

When the parser encounters the message-type indicator, it finds the message

body that corresponds to the value in the message-type indicator. In thefigure below, the parser finds the Add Customer message body based on theAdd message-type value.

d. Specify a request or response message. If you are using the API template

generation feature and if the message is part of a request/response model,


46/196

Adding message sets


select the corresponding check box. Refer to “Request/response message

model” on page 3-15 for more information.

e. Specify whether the fields of the message must be ordered or unordered.

f. Specify the delimiters and tags. Refer to “About field delimiters and tags”on page 3-22 for additional information.

Modifying a field

To modify a field in a header, trailer, or message:

1. Highlight the field you want to modify.

2. Select File > Properties.

3. Modify the field properties as needed. You cannot modify those fieldproperties that are grayed out.

4. Select OK or Apply when finished.

Adding XML-based message sets

When creating an XML-based message set, Message Broker reads the providedDTD and imports it into the Message Broker design-time repository. Once theXML-based message set has been imported there are many more restrictions on

the kinds of field changes that are allowed in an XML-based message set.Specifically, no changes are allowed that would cause the structure in the Message

Broker repository to differ from the structure of the DTD. This means that if the

DTD changes you must delete the message set and re-import the DTD.

NOTE: You cannot change the structure of an XML-based message set. For thisreason, features such as, drag-and-drop, copy and paste, deleting and creatingnew fields are not available.

To add an XML-based message set:




4. Follow the wizard’s instructions, keeping the following in mind:

a. Choose XML-based when asked to specify the type of message set you

want to create.


47/196

Adding message sets


b. Enter the path to the DTD file you wish to import.

c. Click Next. A list of elements defined in the DTD appears.

d. Select at least one element to be the root node.

e. Click Next after you have inserted the root element.

NOTE: A root element appears as the first element in an XML message and willalso appear on the DOCTYPE line in the message. You must be familiarwith the information in the DTD to choose the correct root element.

At this point Message Broker allows you to alter the names and data types ofany fields in the message set to be created.

Changing names and data types

To make changes to names and data types:

1. Select Map names and data types and use the guidelines described in the

section on “Mapping from the DTD to Message Broker” below.

2. Close the dialog when you are satisfied with your mapping. Click Next.

3. Enter a comment.

4. Click Finish.

Message Broker will now complete the process of importing the DTD into thedesign-time repository. This could take some time, depending on the size of the

DTD to be imported.

Mapping from the DTD to Message Broker

In general, there is a simple mapping from the content specification for an elementto the structure created in Message Broker. To perform the mapping successfully,review the following guidelines:

Every element declared in the DTD becomes a user-defined type with the

same name as the tag.

Every element selected as a root element becomes a message definition with

the same name as the tag with _MSG appended to the name. The messagedefinition will contain an instance of the user-defined type with the tag as itsonly member.

Content specifications which have elements separated by the | symbol are

made into unions. The following example creates a user-defined type A whichis a union of B and C.


48/196

Adding message sets


Content specifications not separated by | are made into ordered composites.

Each of the following examples would create a user-defined type which is anordered composite:

#PCDATA becomes an atomic field called data with the data type of String. If#PCDATA is the only content allowed, then the atomic is marked as required

by default, and it would be an error to have markup with an open tag followedimmediately by a close tag with no text between. In the previous example,user-defined type B would have an atomic subfield called data.

If an element is referenced, an instance of a user-defined type is created as a

subfield. In the previous example, user-defined type C would have an instanceof user-defined type B as its subfield.

Modifiers on a field are treated as follows:

? makes the field optional

+ makes the field repeated with a minimum repeat count of 1

* makes the field repeated with a minimum repeat count of 0

For example, in the user-defined type F is an

ordered composite where subfield A is optional, subfield B is repeated with aminimum repeat count of 1, and subfield C is repeated with a minimum repeat

count of 0. A, B, and C are each instances of user-defined types with the samename.

If the top-level content specification has modifiers, it is treated as if there

were an extra set of parentheses around the entire content specification, forexample, would be treated as if it were .

Any internal set of parentheses becomes a subfield whose name is the nameof the parent subfield plus an underscore, plus a number, for example,

would have subfield H_1, which is a union and D,which is an instance of user-defined type D. H_1 in turn would contain two

subfields, B and C, which were instances of the user-defined types of the samename.

In order to properly map the DTD into Message Broker, it is sometimes

necessary for Message Broker to treat the content specification as if it werewritten in an equivalent but different manner. In particular, if a subfield in achoice can be missing because it has the ? or * modifier, then the subfield is


49/196

Adding message sets


made required by removing the ? or changing the * into +. The choice is made

optional by changing its modifier from + to * or by adding ? if there was nomodifier. This is repeated until no subfield of a choice is optional, for example,

would become (((A|B)?|C)+,D) which would then

become (((A|B)|C)*,D). This last stage would be used for the import. If any element has an ANY content specification, a user-defined type called

ANY is created to match the specification (#PCDATA|A|B>>>)* where all theelements defined in the DTD appear after the #PCDATA. The user-definedtype for the element then gets an instance of the ANY user-defined type as a

subfield. In the previous example, user-defined type E would contain a subfieldcalled ANY, which is an instance of the ANY user-defined type.

If there is an attribute declaration for an element, then the element will get a

subfield called elementName_attributes, which appears as the last subfield inthe field. Each attribute defined for the element appears as a subfield of the

attributes subfield as illustrated in the following example:

Attributes which are #IMPLIED are marked as optional atomics. Attributeswhich are #FIXED have fixed value atomics. Attributes which are enumerated

have an enumeration created for the values and the enumeration that isassociated with them. Attributes with default values are marked as optionaland have default values specified. All other attributes are marked as required

strings.

NOTE: The attribute subfield is special in that the normal rules for unions do notapply. If the element has attributes defined, the attributes subfield will alwaysbe present in the message. If the user-defined type for the element is a union,the attributes subfield will be present in addition to the field referred to in _memberName.

XML-based message sets and the design-time repository

Since an XML-based message set follows the structure of the DTD that was usedto create it, there are many restrictions on what may be altered in the property

sheets of an XML-based message set and its subfields. Items that may not bemodified are disabled. It is possible to export the XML-based message set to an

XML file to be imported at a later date. However, you should not modify this fileor attempt to build it by hand because, while the import might succeed, you mightnot see the expected results during the parsing and building run time.

Each element in the DTD becomes a user-defined type. Elements specified as rootelements become message definitions with the default name of element-name_msg .

XML-based message sets can be imported by specifying this option.


50/196

Adding message sets


Importing a message set

To import a message set:

1. Select Import and enter the DTD file that contains your message set

definitions.

2. Select the root element from the list of defined elements. A root element is

required by Message Broker to maintain the structure of your importedelements, for example, if your DTD contains:

then Message Broker will display all elements defined in the DTD and prompt

you for the root element, A, B, C, D, or E. You need to be aware of thestructure of your DTD to know which element is the root. Also, keep in mindthat you can choose multiple root elements.

The DTD file defines the elements and attributes of your message set. When

you import the file, each element and attribute becomes a composite in theUser-defined Types folder. For example, if you import the above elements, A,

B, C, and D become structures in your User-defined Types folder.

For more information, refer to “About user-defined types” on page 3-24 and“Attaching validation rules to user-defined types” on page 3-31.

Adding Java class-based message sets

Java class-based message sets allow you to create class-based message sets by

importing Java classes. The top level classes themselves will become messagedefinitions, in a similar fashion to XML-based message set import. Only public

fields will be represented in the class definition. If a public field is a class, then MBwill represent that class as a user defined type (UDT) with a link to the UDT. If thepublic field is from a java core package, then the field will be ignored.

After a class-based message set has been created, additional java classes can be

added to the set, provided there are no naming conflicts among the class names.


51/196

Adding message sets


Adding SQL-based message sets

SQL-based message sets allow you to define a message set using existing table

definitions. You then use Message Broker to define transformations from the SQL-based message set to another message set. Using Message Broker, you select atable you want to transform into a message definition and select the table columns

you want to transform into fields in the message definition.

To add a SQL-based message set:




4. Follow the wizard’s instructions, keeping in mind the following:

a. Enter the message set name, then click Next.

a. Choose SQL-based when asked to specify the type of message set you

want to create, then click Next.

b. Specify the database connection information, including the database type,user id and password for the database, the host machine, port number,and database name, then click Next.

c. Select one or more tables you want to transform into message definitions,then click Next. To select multiple tables, hold down the CTRL key while

clicking individual table names.

d. Select one or more columns you want to transform into message fields,then click Next. To select multiple columns, hold down the CTRL keywhile clicking individual table names.

e. Select Map Names and Data types to alter the names and data types ofany fields in the message set, then click. Refer to the guidelines described

in the section on “Mapping SQL types to Message Broker field types” onpage 3-14.

f. Click Save to save your changes, then click Close to close the dialog box.

g. Click Next to continue with the wizard.

h. Enter a comment to provide any additional information about the

message set, then click Finish.


52/196

Adding message sets

4 Using the Message Broker design-ti

Documents

Message Broker Dev Guide