Message Broker Dev Guide

2
Message Broker
Developers Guide and API Reference
VERSION 6.0.3
Copyright 2012 by Sybase, an SAP Company. All rights reserved.

This publication pertains to Sybase software and to any subsequent release until
otherwise indicated in new editions or technical notes. Information in this document is
subject to change without notice. The software described herein is furnished under a
license 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 Customer
Fulfillment at (800) 685-8225, fax (617) 229-9845.
Customers in other countries with a U.S. license agreement may contact Customer
Fulfillment via the above fax number. All other international customers should contact
their Sybase subsidiary or local distributor. Upgrades are provided only at regularly
scheduled 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 marks
listed 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. and
other countries. Unicode and the Unicode Logo are registered trademarks of Unicode,
Inc. All other company and product names used herein may be trademarks or
registered trademarks of their respective companies.
Use, duplication, or disclosure by the government is subject to the restrictions set
forth 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 and
retrieval 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
Table of Contents
Introduction .................................................................................................... vii
Intended audience ............................................................................................................. vii
Overview of chapters ...................................................................................................... viii
Related documentation ..................................................................................................... ix
About Sybase ...................................................................................................................... xii
About Sybase Online Banking..................................................................................... xii
About Financial Markets Solutions ............................................................................ xii
Contacting Sybase ............................................................................................................ xiii
Sales and general inquiries.......................................................................................... xiii
Technical support......................................................................................................... xiii
Documentation inquiries ............................................................................................ xiv
Chapter 1
Welcome to Message Broker ...................................................................... 1-1

What is Message Broker? .............................................................................................. 1-1
Features and benefits.................................................................................................. 1-2
Message Broker architecture ........................................................................................ 1-3
What is the design-time phase?................................................................................ 1-4
What is the run-time phase?..................................................................................... 1-5
Understanding messages ................................................................................................ 1-6
What are fields? ........................................................................................................... 1-6
Parsing a message ........................................................................................................ 1-8
Validating a message.................................................................................................... 1-8
Routing a message....................................................................................................... 1-9
Transforming a message ............................................................................................ 1-9
Using API templates ...................................................................................................... 1-10
Using SQL adapter templates ..................................................................................... 1-10
Using flows ...................................................................................................................... 1-11
Chapter 2
Connecting to repositories and running the samples ............................... 2-1

Getting started ................................................................................................................. 2-1
Connecting to repositories ........................................................................................... 2-2
Message Broker Developers Guide and API Reference
Table of Contents
Auto Reconnect........................................................................................................... 2-2

Connecting to a design-time repository ................................................................ 2-3
Connecting to a run-time repository ..................................................................... 2-5
Creating temporary repository connections........................................................ 2-6
Disconnecting from a repository............................................................................. 2-7
Importing the Message Broker samples ..................................................................... 2-7
Importing the sample definitions ............................................................................. 2-7
Deploying, building and running the sample.......................................................... 2-8
Deploying message definitions ................................................................................. 2-9
Reporting problems ........................................................................................................ 2-9
Determining a build number..................................................................................... 2-9
Chapter 3
ii
Using the Message Broker design-time environment .............................. 3-1

Getting started ................................................................................................................. 3-2
Defining message collections ........................................................................................ 3-3
Understanding message sets ......................................................................................... 3-3
What are the message set components? ............................................................... 3-3
About insignificant white space................................................................................ 3-4
Adding message sets ....................................................................................................... 3-5
Adding user-defined message sets........................................................................... 3-5
Adding XML-based message sets............................................................................. 3-8
Adding Java class-based message sets ................................................................... 3-12
Adding SQL-based message sets............................................................................ 3-13
Request/response message model ............................................................................. 3-15
Understanding field elements and properties ......................................................... 3-16
About field definitions .............................................................................................. 3-16
About picture codes................................................................................................. 3-21
About field delimiters and tags............................................................................... 3-22
About enumerations................................................................................................. 3-23
About user-defined types ........................................................................................ 3-24
Defining unknown field handlers............................................................................ 3-25
Reordering fields ....................................................................................................... 3-26
Understanding rules ...................................................................................................... 3-26
Guidelines for writing rules .................................................................................... 3-27
Examples of rules....................................................................................................... 3-28
Defining validation rules ............................................................................................... 3-29
Defining implicit validation ...................................................................................... 3-30
Defining explicit validation ...................................................................................... 3-30
Creating routing rules .................................................................................................. 3-32
Guidelines for routing rules.................................................................................... 3-32
Using routing rule templates .................................................................................. 3-33
Transforming messages ................................................................................................ 3-39
Table of Contents
Table of Contents
Creating transformation rules................................................................................ 3-39

Using header and trailer transformations............................................................ 3-42
Understanding the transformation rules.............................................................. 3-43
Sample transformation rules................................................................................... 3-44
Defining adapter collections ....................................................................................... 3-45
Adding adapter collections and sets ..................................................................... 3-45
Creating SQL adapter templates ........................................................................... 3-46
Understanding SQL file generation ....................................................................... 3-48
Importing and exporting repository information ................................................... 3-50
Specifying the Java class path ...................................................................................... 3-51
Deploying to the run-time repository ...................................................................... 3-51
Chapter 4
Understanding the Message Broker DTD .................................................. 4-1

Getting started ................................................................................................................. 4-1
An introduction to XML ................................................................................................ 4-2
Understanding the Message Broker DTD ................................................................. 4-4
What are message collections? ................................................................................ 4-4
Defining a message set ............................................................................................... 4-5
Routing collections.................................................................................................... 4-11
Chapter 5
Creating API templates ............................................................................... 5-1

Getting started ................................................................................................................. 5-1
What is an API template? .............................................................................................. 5-2
Selecting message types to process ............................................................................ 5-2
Creating an API template .............................................................................................. 5-3
Modifying template properties ..................................................................................... 5-4
Changing API template properties .......................................................................... 5-4
Specifying method implementation patterns ............................................................. 5-6
Deploying a template ...................................................................................................... 5-7
Deploying an EJB template ........................................................................................ 5-7
Deploying an IDL template ....................................................................................... 5-7
Deploying an API template........................................................................................ 5-8
Chapter 6
Using flows ..................................................................................................... 6-1

What is a flow? ................................................................................................................. 6-1
Activities ........................................................................................................................ 6-2
Control links................................................................................................................. 6-2
Sub-flows ....................................................................................................................... 6-2
Loops.............................................................................................................................. 6-3
Forks............................................................................................................................... 6-3
Defining a flow ................................................................................................................. 6-3
iii
Table of Contents
The root of a flow definition .................................................................................... 6-3

A sample flow definition ............................................................................................ 6-7
Using operators ............................................................................................................... 6-9
Internal operators ..................................................................................................... 6-10
Message Broker operators...................................................................................... 6-10
EJB Operators ............................................................................................................ 6-16
Java Operators ........................................................................................................... 6-17
JMS Operators ........................................................................................................... 6-18
Database operators .................................................................................................. 6-23
Creating a flow using the Message Broker Manager ............................................. 6-24
Deploying the flow ........................................................................................................ 6-26
Using the run-time Java API .................................................................................... 6-26
iv
Chapter 7
Using the Message Broker run-time API ................................................... 7-1

Getting started ................................................................................................................. 7-2
Understanding program flow ........................................................................................ 7-3
Connecting to the run-time repository ..................................................................... 7-4
Parsing text-encoded messages .................................................................................... 7-5
Using a handler for unknown fields......................................................................... 7-6
Constructing IDL/Java message instances .................................................................. 7-7
Invoking message validation rules ................................................................................ 7-8
Invoking message routing rules .................................................................................... 7-8
Transforming messages to another format ............................................................... 7-9
Building messages ............................................................................................................ 7-9
Logging, and debugging message contents........................................................... 7-10
Persisting messages using SQL adapter templates ................................................. 7-11
Understanding transactions .................................................................................... 7-11
Sample code................................................................................................................ 7-12
Executing a flow ............................................................................................................. 7-14
Chapter 8
Using Message Broker Server ..................................................................... 8-1

Getting started ................................................................................................................. 8-1
What is the Message Broker Server? ......................................................................... 8-2
Using Message Broker Server .................................................................................. 8-2
Executing flows ............................................................................................................ 8-3
Using Message Broker Manager ................................................................................... 8-4
The Message Broker Server run-time API ................................................................ 8-5
Message Broker Server examples ................................................................................ 8-6
Parse and validate to GlobalFIX............................................................................... 8-6
JMS queue to GlobalFIX .......................................................................................... 8-10
Table of Contents
Table of Contents
Chapter 9
IDL/Java message representation ............................................................... 9-1

Getting started ................................................................................................................. 9-2
Overview ........................................................................................................................... 9-3
Location of generated files ............................................................................................ 9-3
Using generated IDL ................................................................................................... 9-3
Using generated Java................................................................................................... 9-4
Mapping for message bodies, headers, and trailers ................................................. 9-5
IDL definitions for message headers, bodies, and trailers ................................. 9-5
Java classes for message headers, bodies, and trailers........................................ 9-6
Mapping for atomic types .............................................................................................. 9-6
Mapping for enumerations ............................................................................................ 9-7
Using the IDL enumeration representation .......................................................... 9-8
ValueSet<Enumeration> Java class .......................................................................... 9-9
Mapping for composite types ..................................................................................... 9-12
IDL mapping................................................................................................................ 9-12
Java mapping ............................................................................................................... 9-12
Mapping for unions ........................................................................................................ 9-13
Mapping in IDL ........................................................................................................... 9-13
Mapping in Java........................................................................................................... 9-13
Mapping for user-defined types .................................................................................. 9-14
Using optional fields ...................................................................................................... 9-15
Default values ............................................................................................................. 9-15
Mapping of repeated fields .......................................................................................... 9-15
Mapping for SQL Type ................................................................................................. 9-16
Viewing generated Java and IDL code ...................................................................... 9-17
Viewing Java code...................................................................................................... 9-17
Viewing IDL code ...................................................................................................... 9-17
Appendix A
Javadoc .......................................................................................................... A-1

Using the Message Broker API documentation ........................................................A-1
What Financial Fusion provides .............................................................................. A-1
Accessing the API documentation.......................................................................... A-1
Viewing the API documentation ............................................................................. A-2
Index ............................................................................................................IX-1
Reader Comment Form ............................................................................ R-1
Table of Contents
vi
Table of Contents
Introduction
About this
chapter
This chapter describes the intended audience for this guide, a chapter overview, a
description 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 message
formats and applications.This guide is intended for software developers who will
be implementing and customizing Message Broker. The guide provides a closer
look at the Message Broker architecture, the tasks you can perform and a
description of the API.
vii
Overview of chapters
Overview of chapters
This guide includes the following chapters:
Chapter 1
Welcome to Message Broker contains a complete overview of Message
Brokers features and functionalities.

Chapter 2
Connecting to repositories and running the samples describes how to

configure 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 Broker
Manager.
Chapter 4
Understanding the Message Broker DTD discusses the elements of the

Message Broker document type definition (DTD). The Message Broker DTD
enables you to create valid XML documents that contain Message Broker
definitions 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 specify
sequences 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 such
as Enterprise JavaBeans.
Chapter 8
Using Message Broker Server introduces the Message Broker Server and how
it is used to execute flows. It also discusses how to monitor, stop and start
Message Broker Server from the Message Broker Manager. The Message Broker
run-time API is also provided.
viii
Introduction
Related documentation
Chapter 9
Appendix A
IDL/Java message representation discusses how to define message formats,

map for various data types and fields, and view generated Java and IDL code.
Javadoc chapter provides you with information on locating and using the
Message 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 the
straight through processing (STP) requirements of the brokerage industry.
Through its XML-enabled Message Broker component, GlobalFIX facilitates
communication between various message formats and applications, and allows
financial institutions to define messages and rules for industry standard
protocols such as FIX, SWIFT, and STEP. TradeForce GlobalFIX also supports
most in-house proprietary protocols.
GlobalFIX Installation and Configuration Guide for individuals who

install the main compenents of GlobalFIX. This guide includes system and
database prerequisites, as well as the steps required to install and
configure GlobalFIX servers.
GlobalFIX Developers Guide and API Reference for software developers

who implement and customize GlobalFIX. This guide covers the GlobalFIX
architecture, the tasks users can perform, and information about
customization.
GlobalFIX Feature Guide for end users, system administrators, and

purchasing executives who evaluate GlobalFIX to determine the features
and functionality it offers.
GlobalFIX Quick Start Guide for individuals who will be running the
GlobalFIX demo.
Sybase Online Banking Sybase Corporate Online Banking enables you to
administer company accounts with many individual accounts and users per
company client. Sybase Retail Online Banking enables you to manage individual
customer clients. Business Central works dynamically with both Sybase
Corporate Online Banking and Sybase Retail Online Banking, enabling banks
to manage business and consumer accounts, as well as bank employees.
ix
Sybase Retail Online Banking and Sybase Corporate Online Banking

Installation and Configuration Guides for individuals who install the main
components 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 introductory
information about the solution and provides critical information
developers need to start an implementation.
Sybase Corporate Online Banking Developers Guide for software

developers who implement and customize Sybase Corporate Online
Banking. This guide covers the Sybase Corporate Online Banking
architecture, the tasks users can perform, and information about
customization.
Sybase Retail Online Banking Developers Guide for software developers

who implement and customize Sybase Retail Online Banking. This guide
covers the Sybase Retail Online Banking architecture, the tasks users can
perform, and information about customization.
Business Central Developers Guide provides application developers and

IT staff with information about how Business Central works, what
modules and components it is made up of, and how to administer and
customize those components to meet their needs as a financial institution
and to meet their customers needs.
Sybase Corporate Online Banking Feature Guide for end users, system
administrators, and purchasing executives who evaluate Sybase Corporate
Online Banking to determine the features and functionality it offers.
Sybase Retail Online Banking Feature Guide for end users, system
administrators, and purchasing executives who evaluate Sybase Retail
Online 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 determine
the features and functionality it offers.
Business Central Administrators Guide for bank employees and other

administrators who use Business Central to configure and manage
businesses, consumers, and other bank employees.
Sybase Retail Online Banking Localization Guide for developers who

localize Sybase Retail Online Banking. This guide provides the information
needed to successfully localize Sybase Retail Online Banking.
Introduction
Javadoc the Sybase Online Banking API documentation (Javadoc) is

provided 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 information
pertinent 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 Transfer
Warehouse (BPTW) enables a financial institution to control the total

payment processing and warehousing of customer information.
Bill Payment and Transfer Warehouse Developers Guide for software

developers who implement and customize Bill Payment and Transfer
Warehouse. This guide covers the BPTW architecture, the tasks users can
perform, and information about customization.
Bill Payment and Transfer Warehouse Installation and Configuration

Guide 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 tool
that enables you to create, manage, and deliver targeted marketing messages
to customers who use Web transaction products such as online banking and
bill payment software.
One-to-One Marketing Message Manager Users Guide provides users

with the information they require to understand how the One-to-One
Marketing system works, and the steps necessary to use and manage the
Message Manager application.
One-to-One Marketing Technical Reference for individuals who install

One-to-One Marketing. The guide provides information about system and
database prerequisites, installation steps, and post-installation processing
required to run One-to-One Marketing.
Message Broker Message Broker is a toolkit that allows communication
between multiple message formats and applications. Message Broker

components provide message validation, persistence, transformation, routing,
and message processing flow.
xi
About Sybase
Message Broker Installation and Configuration Guide for software

developers who implement and customize Message Broker. This guide
provides information about the Message Broker architecture, installation
steps, and configuration options.
Universal Alerts Engine Universal Alerts Engine (UAE) is a middleware
component used for generating notification messages (alerts) to applications
and end user devices.
Universal Alerts Engine Developers Guide and API Reference for

software developers who implement and customize UAE. This guide
covers the UAE architecture, the tasks the user can perform, and a
description of the API.
Universal Alerts Engine Feature Guide a brief overview of the features

and architecture of the Universal Alerts Engine.
About Sybase
Sybase provides integrated financial solutions to more than 200 of the world's
leading financial institutions. Sybase maintains strategic technology relationships
with BEA, IBM, Microsoft, Sun Microsystems, and SWIFT. We supply service and
support 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 the
financial services industry. Our solutions offer multiple delivery channel services
for consumers, small businesses and large corporate cash management customers.
We support multi-bank environments, banking, imaging, bill payment and
presentment, customer care, and industry protocols.
About Financial Markets Solutions

Sybase solutions for Financial Markets are designed to meet the STP connectivity
and integration requirements of the trading industry. Our solutions provide
processing for transaction intensive trading organizations such as securities and
investment firms, ECNs and network providers. We support FIX, SWIFT, VMUs
and proprietary protocols.
xii
Introduction
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 Road
Concord, MA 01742
Phone:
1-800-842-0885 or 1-978-287-1975
E-mail:
sales@sybase.com
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, call
1-800-8SYBASE and a customer service representative will assist you.
xiii
Contacting Sybase
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, or
e-mail the information to our Technical Publications team using the contact
information below.
Contact information
To contact the Sybase Technical Publications team:
Mailing address:

Attention: Technical Publications
445 Wes Graham Way
Waterloo ON N2L 6R2
Canada
Fax:
(519) 747-4971
E-mail:
pubs@sybase.com
xiv
Introduction
1
Welcome to Message Broker
About this
chapter
This chapter introduces the features, concepts, definitions, and advantages unique
to 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 message
formats 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), inhouse proprietary versions of these protocols, and target applications such as
order management systems, legacy systems, market feeds and more
Message persistence
1-1
What is Message Broker?
Message Broker components provide message validation, persistence,

transformation, routing, and message processing flow functions using a set of builtin and/or user-defined message formats and message processing rules. These
message formats and rules may include functionality such as publish and subscribe,
message auditing, message flow analysis, and message enrichment.
Features and benefits

Message Broker offers the following features and benefits:
100% Java and XML-enabled.
Flexible Message Formats. Message Broker supports a wide variety of
message formats including user-defined, XML, Java class-based and SQL-based
message formats.
Customizable Field Definitions. Message Broker includes three types of
fields: atomic, composite and union fields. In addition, fields can be defined to
be repeating as well as optional.
Extending and distributing message formats. Predefined message formats
can be distributed in the form of XML files that follow the Message Broker
DTD.
Administration GUI. Message Broker Manager is a graphical interface that
facilitates the creation and modification of message definitions in Message
Broker.
Run-time API. The run-time API allows you to develop custom applications
that make use of the Message Broker run-time components (parse, validate,
route, transform, build, flow, persistence).
1-2
Message Broker architecture

Message Broker includes a design-time database repository
where you define and store message collections and rules. This design information
is 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 Java
object 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 Java
object representations back to the message strings
The design-time and run-time phases are shown below.
Figure 1-1:
Message Broker
architecture.
Having separate repositories for the design-time and run-time environments

allows you to continue designing and modifying information in the design-time
environment without affecting the deployed run-time environment.
1-3
Once message sets and rules have been defined in the design-time environment,
they must be transferred to the run-time environment through a deployment
process invoked from the graphical user interface, Message Broker Manager.
During the deployment process, IDL and Java classes are created for the message
sets and rules, and data is transferred from the design-time repository to the runtime repository.
For further details on the design-time and run-time environments, review the
following sections:
What is the design-time phase? on page 1-4
What is the run-time phase? on page 1-5
NOTE: Message Broker requires a JDBC driver to connect to its design-time and runtime repositories. A Sybase jConnect driver and Adaptive Server Anywhere
(ASA) sample database file are provided as part of the Financial Fusion
installation package.
What is the design-time phase?

The design-time environment uses a database repository for storing message sets
and some information pertaining to rules. The run-time repository supports the
following databases:
Sybase ASA
Sybase ASE
Oracle
During the design-time phase, you can define and use the following:
Message sets: These sets contain message definitions that include header,
trailer, message body, and field information. Field information includes field
type and data type. Refer to Understanding messages on page 1-6 for more
information.
Validation rules: These rules enforce message conformance. Refer to
Validating a message on page 1-8 for more information.
Routing rules: These rules specify a Sybase Enterprise Application Server
(EAServer) component, a Java class, or an Enterprise JavaBean (EJB) to which
a message is routed. Refer to Routing a message on page 1-9 for more
information.
1-4
Transformation rules: These rules change an incoming message to a

different message type. See Transforming a message on page 1-9 for more
information.
SQL Adapter Templates: This feature allows you to persist (store)
messages into a database. It also allows you to retrieve, update, and delete
persisted messages. You can specify specific fields in a message as well as
custom data to store separately from the raw, unparsed data. For details, see
Using SQL adapter templates on page 1-10.
Flows: Flows provide a way to specify a sequence of message processing
events, specifically Message Broker operators, in a declarative manner

without having to write code. For details, see Using flows on page 1-11.
You can also create any of the above definitions in an XML file and import them
into the design-time repository.
What is the run-time phase?

Message processing (parse, validate, route, transform, persistence, build, flow
execution) takes place in the run-time environment. The run-time components are
invoked through the Message Broker run-time API.
The run-time environment uses a database repository for storing message sets and
some information pertaining to rules. The run-time repository supports the
following databases:
Sybase ASA
Sybase ASE
Oracle
DB2
You can view deployed sets in the run-time repository and invoke the run-time
test mechanism using the graphical user interface, Message Broker Manager. This
interface can also be used to modify the EJB and EAServer settings for routing sets.
NOTE: Message Broker Manager cannot be used to make any other changes to the
deployed message sets or rules in the run-time environment.
1-5
Understanding messages
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 can
contain multiple fields. The fields comprising a message vary from protocol to
protocol.
A protocol such as SWIFT contains various message sets. Each set contains a
group of messages that has a specific format and performs a specific task. For
example, 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 located
between the header and the trailer. Each message definition shares the header and
trailer 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 are
three 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.
1-6
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.
1-7
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 a
Message Broker instance and call the IParser API, which parses the incoming
message.
To parse a message:
1. Send the unparsed message to the application.
2. The application creates a Message Broker instance (if one is not already
created) 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 message

object 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 meets
the 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 message
definition 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 the
header contains this value as part of implicit validation. No Java code is required
for implicit validation.
Explicit validation
Explicit validation allows you to write validation rules in Java code. These rules are
compiled 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 particular
character 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 would
need to explicitly write code to verify that what they have is an e-mail address.
1-8
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 an
EAServer 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 routes
any 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 Message
Broker 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 by
field, 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 SWIFT
message based on the transformation rules that are stored in the run-time
repository, then forwards the message to the SWIFT server for processing.
1-9
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 for
repeated code elements such as a messages 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 properties
defined in Message Broker Manager. For an IDL template, Message Broker
generates 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 allows
you to retrieve, update, and delete persisted messages. You can specify specific
fields 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 Data
Definition Language (DDL) and Data Manipulation Language (DML) code used to
save messages to a database. Message Broker supports two types of SQL adapter
templates:
Generic templates. Generate a single table that is capable of storing all
message types defined in the message set that is associated with the adapter
set. Generic templates can save the unparsed representation of all messages
within the message set, as well as the values for any fields in the header or
trailer. 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.
1-10
Using flows
Message-specific templates. Generate tables that are capable of storing one

message type in each table. Message-specific templates can save the unparsed
representation 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 explains
how to create SQL adapter templates.
Using flows
Flows are used to perform a sequence of message processing operations. These
operations include invoking the Message Broker run-time API, working with JMS
queues, 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. For
more information on Flows see Chapter 6: Using flows. For details on Message
Broker Server, see Chapter 8: Using Message Broker Server.
1-11
Using flows
1-12
2
Connecting to repositories
and running the samples
About this
chapter
This chapter describes how to configure and connect to the Message Broker
repositories 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 on
page 2-9.
2-1
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 as
the 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, each
database 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 at
installation.
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 before
performing operations which require repository access. If the connection to the
repository has been closed (most often due to a connection timeout from the
database server), Message Broker automatically attempts to reconnect to the
repository. 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 the
connection cannot be automatically re-established, an error is issued informing the
2-2
Connecting to repositories and running the samples
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. For
example, it works in the design-time repository before importing/exporting/
deploying sets, expanding fields, or copying-pasting fields, and in the run-time
repository 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 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 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 samples

subdirectory of your Message Broker installation.
2-3
Starting the sample database

1. Run %MB60INSTALLDIR%\samples\mbdemo.bat on NT, or $MB60INSTALLDIR/
samples/mbdemo on Unix.
NOTE:
NT users can launch the demonstration database from the NT Start menu, for
example, if you installed Message Broker in the default directory, select Start
> Program> Financial Fusion> Message Broker 6.0> Message
Broker Demo database.
2. Select Design-time Repository from the Connect to drop-down list.

3. Select the appropriate database type from the Database Type drop-down
list.
4. Enter the connection information for the database where you want to store
the repository.
5. Enter these values to use the sample ASA database:
User ID: DBA

Password: SQL
Port number: 2638
The user ID and password are case sensitive. To use a different database,
make sure the database is case sensitive for string compares.
You can now use this connection profile to connect to the repository. The first
time you connect to a design-time repository, Message Broker creates the
required database tables.
Connecting to the design-time repository

1. Select the profile you just created and click Connect. A message appears
indicating that there is currently no repository defined in the database.

2. To create a new repository, click Yes.
3. To accept Message Broker as the repository name, click OK. Once the
repository is created, an icon representing it displays in the left frame.

4. Select the repository icon to define message, routing, and transformation
collections.
2-4
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 desired
changes in the design-time repository and redeploy them to the run-time
repository.
NOTE:
To connect to run-time repositories on Oracle via the OCI8 (thick client) driver,
Message Broker supports lookup of database connection parameters from the
TNSNAMES.ORA configuration file. To have Message Broker obtain the
connection information from the TNSNAMES.ORA configuration file, specify
the Oracle SID for the database instance in the database name field and leave
the machine name field blank (the port number field is ignored in this case).
This method of specifying the connection parameters is required for connecting
to 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 Broker
Manager.
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 samples

subdirectory of your Message Broker directory.
2-5
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
Port number: 2638
The 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 to
connect 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 Manager
session.
To temporarily connect to a repository:
1. Select Tools > Connect.
2. Enter the connection information for the repository to which you want to
connect, including the type of repository from the drop-down list.

3. Click OK.
2-6
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 a
good way to become familiar with Message Broker.
The following sections describes how to import these samples into the designtime 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 the
samples 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 Message
Broker Manager:
2-7
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 text
field.
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 for
use.
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 deployed
because 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 executing
run.bat. Run the samples one at a time by using the following batch files:
run FlowTest.bat
runParseBuild.bat
runParsePersist.bat
runParseTransformBuild.bat
runParseValidate.bat
Explanations of the samples are provided via comments in the Java files. The batch
files assume that jConnect is installed and that the MB60JCONNECTDIR
environment variable is set to the jConnect location. The samples assume the use
2-8
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 the
file 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 buffer
which 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 the
Message Broker plug-in.
2-9
Reporting problems
2-10
3
Using the Message Broker
design-time environment
About this
chapter
This chapter discusses the Message Broker design-time configuration tasks that are
performed from Message Broker Manager.
Topics include:
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)
3-1
Getting started
Getting started
To use this chapter effectively, review the following steps:
1. To perform the tasks in this chapter, you must:
Start Message Broker Manager.

Connect to the design-time repository. For more information, see
Chapter 2: Connecting to repositories and running the samples.
2. Define message collections and sets. Message sets contain message definitions
that include header, trailer, message body, and field information. Field
information includes field type and data type. For details, see Defining
message collections on page 3-3 and Understanding message sets on
page 3-3, as appropriate.
3. Review Understanding rules on page 3-26.
4. Define Validation rules. These rules enforce message conformance. For
details, see Defining validation rules on page 3-29.

5. Create routing rules. These rules specify an EAServer component, a Java class,
or an Enterprise JavaBean (EJB) to which a message is routed. Refer to

Creating routing rules on page 3-32.
6. Transform a message. Message Broker allows you to transform a source
message into a target message by specifying transformation rules for the

target message fields. For details, see Transforming messages on page 3-39.
7. Create adapter sets. Adapter sets contain SQL adapter templates that outline
the information needed to generate Data Definition Language (DDL) and

Data Manipulation Language (DML) code used to save messages to a database.
8. If you define many message, routing, or transformation collections you may
find it faster and easier to define them in XML first, then import them into the
design-time repository. For details, see Importing and exporting repository
information on page 3-50.
9. Make sure that the locations of all the extra class files used by your code have
been entered in the repository properties. If classes are missing, you will get
compile errors during deployment. For details, see Specifying the Java class
path on page 3-51.
10. Before you can invoke Message Brokers run-time API, you must deploy the
design-time repository to the run-time repository. See Deploying to the runtime repository on page 3-51.
3-2
Using the Message Broker design-time environment
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 message
collection either by using wizards, by importing them from an XML file, or a
combination of both.
This section discusses how to create message collections using the Message
Broker Manager. For information on importing message collections from an XML
file 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 wizards instructions.
Understanding message sets

The following sections provide details about message sets and how they are used
in 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, but
the 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 message
body 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 include
field definitions and validation rules for your message set. Each message
definition in the set uses the same header and trailer, if defined.
3-3
Understanding message sets
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 Attaching
validation 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 that
it does not recognize. Refer to Defining unknown field handlers on page 325 for more information.
Delimiters: You can define delimiters and pad characters for all fields in all
messages belonging to the message set. You can override these setting at the
field level. Refer to About field definitions on page 3-16 for additional
information.
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/delimited
sibling 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
3-4
Adding message sets
\u001F, unit separator
Adding message sets

Message Broker supports user-defined, XML-based message sets, Java class-based
message 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 do
not 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, add
headers, 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 wizards instructions. When you are prompted for the type of the
message 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 of
the message set header must be ordered. If unordered, the header must contain all
3-5
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 to
see how a message is located from its header when the message-type
indicator is set. You can also specify atomic user data types as messagetype 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 wizards instructions, keeping the following in mind:
a.
When defining a trailer for a message set remember to specify whether

the fields of the message set trailer must be ordered. Fields within the
header/trailer can be optional.
b.
You should also specify whether the trailer is optional. If you select This
trailer 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 wizards instructions as outlined below.
3-6
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 messagetype indicator.
c.
Include the value that you expect in the messageType field for each
message body you create. For example, in the customer sample that
comes with Message Broker, the message-type indicator in the header is
called msgType. The enumeration msgType is defined to accept the values
Add or Del. There is one message body called AddCustomer that
corresponds to the message type Add and a message body called
DeleteCustomer 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 the
figure below, the parser finds the Add Customer message body based on the
Add 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,
3-7
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 field
properties 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 provided
DTD and imports it into the Message Broker design-time repository. Once the
XML-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 this
reason, features such as, drag-and-drop, copy and paste, deleting and creating
new fields are not available.
To add an XML-based message set:

4. Follow the wizards instructions, keeping the following in mind:
a.
3-8
Choose XML-based when asked to specify the type of message set you
want to create.
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 will
also appear on the DOCTYPE line in the message. You must be familiar
with 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 of
any 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 the
design-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 element
to 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 message
definition will contain an instance of the user-defined type with the tag as its
only member.
Content specifications which have elements separated by the | symbol are
made into unions. The following example creates a user-defined type A which
is a union of B and C.
3-9
Adding message sets
<!ELEMENT A (B|C)>
Content specifications not separated by | are made into ordered composites.

Each of the following examples would create a user-defined type which is an
ordered composite:
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
B
C
D
E
(#PCDATA)>
(B)>
(B,C)>
ANY>
#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 followed
immediately 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 instance
of 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 <!ELEMENT F (A?,B+,C*)> the user-defined type F is an
ordered composite where subfield A is optional, subfield B is repeated with a
minimum 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 same
name.
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, for
example, <!ELEMENT G (B)?> would be treated as if it were <!ELEMENT G
((B)?)>.
Any internal set of parentheses becomes a subfield whose name is the name
of the parent subfield plus an underscore, plus a number, for example,
<!ELEMENT H ((B|C),D)> 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 same
name.
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 were
written in an equivalent but different manner. In particular, if a subfield in a
choice can be missing because it has the ? or * modifier, then the subfield is
3-10
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 no
modifier. This is repeated until no subfield of a choice is optional, for example,
<!ELEMENT | (((A|B?)|C)+,D)> 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 the
elements defined in the DTD appear after the #PCDATA. The user-defined
type 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 subfield
called 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 in
the field. Each attribute defined for the element appears as a subfield of the
attributes subfield as illustrated in the following example:
<!ATTLIST A a1 (val1|val2)#REQUIRED>
Attributes which are #IMPLIED are marked as optional atomics. Attributes

which are #FIXED have fixed value atomics. Attributes which are enumerated
have an enumeration created for the values and the enumeration that is
associated with them. Attributes with default values are marked as optional
and 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 not
apply. If the element has attributes defined, the attributes subfield will always
be 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 used
to 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 be
modified 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 file
or attempt to build it by hand because, while the import might succeed, you might
not see the expected results during the parsing and building run time.
Each element in the DTD becomes a user-defined type. Elements specified as root
elements become message definitions with the default name of element-name_msg.
XML-based message sets can be imported by specifying this option.
3-11
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 imported

elements, for example, if your DTD contains:
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
A
B
C
D
E
(
(
(
(
(
#PCDATA
#PCDATA
#PCDATA
#PCDATA
(A,B) |
) >
) >
) >
) >
(C,D?) ) >
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 the
structure of your DTD to know which element is the root. Also, keep in mind
that 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 the
User-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 message
definitions, 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 MB
will represent that class as a user defined type (UDT) with a link to the UDT. If the
public 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.
3-12
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 SQLbased message set to another message set. Using Message Broker, you select a
table 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 wizards 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 key
while clicking individual table names.
e.
Select Map Names and Data types to alter the names and data types of
any fields in the message set, then click. Refer to the guidelines described
in the section on Mapping SQL types to Message Broker field types on
page 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.
3-13
Adding message sets
Mapping SQL types to Message Broker field types

In general, only simple field types require mapping between SQL and Message
Broker. All SQL types are automatically assigned a default Message Broker field
type that you can change at any time. The following table lists the default mappings
of column information:
SQL Type
Message Broker Field Type
BIT
Boolean
TINYINT
32-bit Integer
SMALLINT
16-bit Integer
INTEGER
32- bit Integer
BIGINT
64- bit Integer
FLOAT
32- bit Float
REAL
32- bit Float
DOUBLE
64- bit Double
NUMERIC
64- bit Double
DECIMAL
64- bit Double
CHAR
String
VARCHAR
String
LONGVARCHAR
String
DATE
Date, DATE_YYYYMMDD
TIME
Date, DATE_TIME_TIMEZONE
TIMESTAMP
Date, DATE_YYYYMMDDHHMMSS
BINARY
Bytes
VARBINARY
Bytes
BLOB
Bytes
CLOB
String
If any of these field types can contain a null value in the message definition,
Message Broker marks that field as optional. Also, if you do not supply a value in a
column, a default value is inserted, however, this default value does not affect the
generated field type in Message Broker.
3-14
Request/response message model
Using the Name and Data Type Mapping dialog

You can use the Name and Data Type Mapping dialog to alter the names of the
fields of the imported messages before the import occurs. Altering field names is
useful because:
Message Broker may generate non-intuitive names for subfields
Characters which are valid in XML but are not valid in Java become an
underscore.
The dialog presents a tree view in the left-hand pane that lists all available elements
from the DTD. You can select an element to change its information. The top-level
elements represent the user-defined types for the elements. Under each element
are its subfields. You can also change the name in the subfields. If the subfield is
repeated, you can alter its minimum and maximum repeat count. For atomic
subelements that represent either attributes or #PCDATA you can change the data
type and data format.
Request/response message model

Messages represent a request or response.
A request message is an incoming message which allows a query for specific
data or provides a way to send data for review or storage.
A response message is an outgoing message and is usually associated with a
request message.
For example, if you were to create a message set for a Web page domain
registration about customer satisfaction, you might have a request message called
ReserveWebPage, a response message called WebPageStatus, and another request
message called GiveComments.
The ReserveWebPage message is included, along with the information pertinent to
that message. This might include the desired Web page, name, address, or other
information. If the page is available, the WebPageStatus message would be sent by
the domain registrar to let you know the page is available. If the page is not
available, then the WebPageStatus message would indicate that someone else is
holding that Web page. If you wish to make further comment, you can send a
GiveComments message.
3-15
Understanding field elements and properties

The following sections describe how to use field elements and properties:
About field definitions below.
About picture codes on page 3-21
About field delimiters and tags on page 3-22
About enumerations on page 3-23
About user-defined types on page 3-24
Defining unknown field handlers on page 3-25
Reordering fields on page 3-26
About field definitions

The field definition determines the field properties. Field definitions include the
following:
Field type on page 3-16
Data type on page 3-17
Field length on page 3-19
Leading and trailing pad characters on page 3-20
Repeated and optional fields on page 3-20
Field type
The three field types, atomic, composite, and union, are defined as follows:
Atomic: An atomic field represents some data from the message and does
not have subfields. It can contain only one field as a member and may be
either fixed-length, variable-length, or tagged/delimited.
Composite: A composite field can contain subfields. If a subfield is a
composite, it can also contain subfields. Specify whether the fields within a
composite must be ordered or not. An ordered composite requires that the
message contain the subfields in the order they appear in Message Broker. If a
composite is unordered, the subfields may occur in any order.
NOTE: If a composite is unordered, the parser may perform more quickly if the
subfields are ordered to match the most likely order in a message.
3-16
Union: A union, like a composite, can contain subfields, but only one of the
subfields can be present in the message. Union subfields should be ordered so
that the most likely members appear first.
Data type
If you select atomic as the field type, you must also specify the data type. The
parser uses this information to determine how to read the data and generate the
output.
Incoming field data is read as text and parsed according to the data type you
select. Your output options are strings, bytes, boolean, integers, floats and doubles,
enumerations, and dates.
Strings: If you select this option you can choose a picture code
representation. A picture code allows you to specify the type, number, and
placement of characters in the string. A string must match the picture code to
be valid. Refer to About picture codes on page 3-21 for more information.
Bytes: The parser output is in bytes.
Boolean: The parser output is boolean.
Integers, floats, and doubles: You may choose the format of the integer,
float, or double output.
Enumerations: Select Enumeration from the drop-down list, which will only
contain enumerations whose data type matches the currently selected data
type for the field. The input must be a value of the selected enumeration to be
valid. An enumeration may be associated with a field in two ways.
First, if Represent field data as has anything but Enumeration selected and
an enumeration is selected from the Enumeration drop-down list, then the
field will be represented as the specified type, but the value will be
validated against the values in the enumeration.
Second, if Represent field data as is set to Enumeration and an

enumeration is selected from the Enumeration drop-down list, the value is
validated against the values in the enumeration, but it is represented by an
enumeration class rather than by a primitive type. Refer to Mapping for
enumerations on page 9-7, for more information.
3-17
Dates: The output is in date format and uses the notation identified in the
following table.
Date/Time Element
Format
year
YYYY
month/minutes
MM
day
DD
hours
HH
seconds
SS
milliseconds
XXX
time zone string
TZ
The input is verified to be a valid date format. Message Broker currently

supports the following date formats:
Format
Example
YYYYMMDD
(19990821)
YYYY-MM-DD
(19999-08-21)
YYYYMMDD-HH:MM:SS
(19990821-13:334:57)
MMDD
(0821)
YYMMDD
(990821)
YYYYMMDDHHMMSS
(19990821133457)
YYYYMMDDHHMMSS.XXX
(19990821133457.623)
YYYYMMDDHHMMSS.XXX [GMT
offset: TZ name]
(19990821133457.623 [-5:EST])
HHMMSS.XXX [GMT offset: TZ name] (19990821133457.623 [-5:EST])
The last two options in the table are date/time combinations for the OFX
protocol. These formats have some special cases that allow various parts of
the date and time information to be missing from the right side. For the
3-18
YYYYMMDDHHMMSS.XXX [GMT offset: TZ name] format Message Broker

allows the following:
OFX Date/Time Formats
YYYYMMDDHHMMSS.XXX [GMT offset: TZ name]
YYYYMMDDHHMMSS.XXX [GMT offset]
YYYYMMDDHHMMSS.XXX
YYYYMMDDHHMMSS [GMT offset: TZ name]
YYYYMMDDHHMMSS [GMT offset]
YYYYMMDDHHMMSS
YYYYMMDD [GMT offset: TZ name]
YYYYMMDD [GMT offset]
YYYYMMDD
Similarly for HHMMSS.XXX [GMT offset: TZ name] format Message Broker

allows the following input combinations:
OFX Time Formats
HHMMSS.XXX [GMT offset: TZ name]
HHMMSS.XXX [GMT offset]
HHMMSS>XXX
HHMMSS [GMT offset: TZ name]
HHMMSS [GMT offset]
HHMMSS
Field length
If you select atomic as the field type, you can choose either a fixed length, variablelength, or tagged/delimited field. If you select composite or union, you must use a
tagged/delimited field.
For a fixed field length, enter a number to represent the required (maximum)
length of the field, for example, if you enter 4, the field must contain a maximum of
four characters. Refer to About field delimiters and tags on page 3-22 for more
information.
3-19
If a field is tagged/delimited, then the length of the field is determined by the tags
and delimiters on the current field and also on the fields around it. If the field is
marked as length field indicated, then the length of the field, excluding any tags and
delimiters for the field, is given by the parsed value of the previous field, which
must be a numeric atomic field.
If the field is a variable length then the length of the field is determined by reading
Length bytes before the beginning of the field, interpreting that as a binary
representation of an integer n and using the next n characters for the field.
Leading and trailing pad characters

If you select atomic as the field type and a fixed-length field, you can override
leading and trailing pad characters that were defined for the message set to which
this field belongs.
The parser strips pad characters from the beginning and end of the data for a field,
if the pad characters are present. The builder will pad fields that are too short and
define pad characters, for example, if a field is a fixed length of eight and contains
less than eight characters, the field needs to be padded. It would be an error not
to have defined pad characters in this case.
When Message Broker pads fields, string fields are left justified and numerics are
right justified.
Repeated and optional fields

For all field types, you can specify whether a field is repeatable. If a field is marked
as repeatable, you can then establish a minimum and/or maximum repetition
count. For atomic and composite field types, you can specify whether or not the
field is optional. If an atomic field is optional, you can specify a default value to be
used. A field type of optional also allows the generation of a column definition
which allows a null value.
If the field is marked as repetition field indicated, then the number of repetitions of
the field, excluding any tags and delimiters for the field, is given by the parsed value
of the previous field, which must be a numeric atomic field.
Refer to Optional fields on page 3-27, for more information.
3-20
About picture codes

A picture code is a restricted string that lets you specify valid characters, where
those characters appear, and the length of the string to which the picture code
corresponds. For example, if you define a string that uses a picture code of 9999999, then the string must contain any three digits followed by a dash, followed by
any four digits to be valid. See the following table for valid picture codes.
Element
Description
A letter (as indicated by java.lang.Character.isLetter( ))
Blank space
Floating point number exponent indicator E
+ or - character
Any character
A digit (as indicated by java.lang.Character.isDigit( ))
0 or 1
cs
Currency symbol ($, cent, pound, yen, euro, rupee, baht)
Uppercase letter (as indicated by java.lang.Character.isUpperCase( ))
Uppercase letter or digit (as indicated by

java.lang.Character.isUpperCase( ) and java.lang.Character.isDigit( ))
Character from the SWIFT X character set
Character from the SWIFT Y character set
Character from the SWIFT Z character set
\uXXXX
The character corresponding to the given Unicode escape sequence
\r
Carriage return character
\n
New line character
\t
Tab character
\s
Blank space character
\\
Backslash character
\#
Escaped character # (where # is the escaped character)
NOTE:
Characters other than those listed above represent themselves.
3-21
About field delimiters and tags

This section describes the field delimiters and tags used to define header, trailer,
and message fields. At run time, the parser uses this information to determine the
beginning and end of fields if you are not using a fixed length field. The field
delimiters and tags are as follows:
Begin field delimiter: the character or characters that signify the beginning
of the field or pre-value tag.

End field delimiter: the character or characters that signify the end of the
field or post-value tag.

Begin tag delimiter: the character or characters that precede the pre-value
and post-value tags. If there is no pre-value or post-value tag then the begin
tag delimiter is not added for that tag.
End tag delimiter: the character or characters that follow the pre-value and
post-value tags. If there is no pre-value or post-value tag then the end tag
delimiter is not added for that tag.
Pre-value tag: the tag that precedes the field data.
Post-value tag: the tag that follows the field data.
For example, in a message that contains the field
{MAC:B0E33860}
B0E33860 is the data being parsed. You could define these delimiters and tags:
Begin field delimiter: {
End field delimiter: }
Begin tag delimiter: None
End tag delimiter: :
Pre-value tag: MAC
Post-value tag: None
For the example below the delimiters and tags are defined as follows:
{<foo>data</foo>}
Begin field delimiter: {

End field delimiter: }
Begin tag delimiter: <
End tag delimiter: >
Pre-value tag: foo
Post-value tag: /foo
3-22
About enumerations
An enumeration belongs to a message set and is a list of all allowed values for the
enumeration. An enumeration must match the data type of the field to which it
belongs. At run time, the parser validates an enumeration by checking that a fields
value belongs to its enumeration set, for example, the first field in the header of a
FIX message contains a string that identifies the version, FIX.4.0 or FIX.4.1. You
could do the following:
1. Define an enumeration called fix_version that is a string data type.
2. Add two members to the enumeration, fix_version4_0 with a value of FIX.4.0,
and fix_version4_1 with a value of FIX.4.1.

3. Define a FIX message set and define field one of the header as an enumeration
and select fix_version from the drop-down list of enumerations.

At run time, the parser validates the field by checking for either FIX.4.0 or FIX.4.1
as the field value.
Defining an enumeration
To define an enumeration:
1. Highlight the Enumerations folder from within the message set you want to
add.
2. Double-click the Add Enumeration icon.
3. Follow the subsequent wizard instructions to define your enumeration.
a.
Enter a unique name for the enumeration.
b.
Specify the data type and format of the data.
c.
Define any numeric enumerations. Remember that when defining numeric

enumerations, values such as 1.0, 1, and 01.000 are equivalent.
d.
Add members by entering a symbolic name and a value for the member.
Member names must be unique within an enumeration and correspond to
a valid Java identifier. The value must correspond to the selected data
type.
e.
Use the Add, Modify, and Remove buttons to update enumeration

members.
3-23
Adding a member to an enumeration

To add a member to an enumeration:
1. Highlight the Enumerations folder within the message set.
2. Highlight the existing enumeration to which you are adding a member and
select the Add Member icon.
3. Follow the wizard instructions to add a member to your enumeration, keeping
in mind the following:

a.
Enter a unique member name for the enumeration.
b.
Enter the value for the enumeration member.
c.
Click Finish.
About user-defined types

Message Broker provides a User-defined Types (UDT) folder that contains
reusable fields. If you intend to use a field more than once, create it in the Userdefined Types folder. You can then drag it to the header, trailer, message body,
composite, or union to which you are adding the field. Each message set has its
own User-defined Types folder.
A user-defined type that has been dragged from the User-defined Types folder is
called a user-defined instance and is distinguished by the arrow that appears on the
fields icon.
By creating a user-defined instance of a user-defined type for reusable fields you
can dramatically reduce the number of Java classes that are generated. This greatly
reduces memory requirements.
You can also specify a validation rule on a user-defined type that will be invoked on
each instance rather than duplicating the code for each instance. Using a userdefined type saves time by not having to redefine the same structures, by reducing
the time required to deploy the message set, and by reducing the time required to
import from or export to XML.
NOTE: You can also create a user-defined type by right-clicking on fields (atomic,
composite, or union) and saving the field as a user-defined type. This option is
not available for fields that are found in message definitions that belong to
XML-based message sets because XML-based message sets cannot be
changed. This option is also not available if the field is a user-defined instance
or the child of a user-defined instance because the user-defined type already
exists.
3-24
Overriding user-defined types

The properties of user-defined types are enforced for all instances of the userdefined type. You can override some of these properties, but you cannot override
the structure or data type of a user-defined instance.
To override the properties for a user-defined type:
1. Highlight the instance you want to override.
3. Select the Override default values check box on the General tab.
4. Modify the properties on the desired tabs and select Apply.
NOTE: Avoid overriding fields, if possible, as overriding can cause increased
memory consumption in the run-time environment and performance
degradation in the design-time environment.
Defining unknown field handlers

If your messages contain composite fields, you can define unknown field handlers,
for the message set that enables the parser to call a Java method at run-time, to
handle fields that are not recognized, for example, the FIX protocol allows you to
create your own tags for inserting data. The parser may generate an error when it
encounters these tags. If you install an unknown field handler, the parser calls the
handler instead of generating an error whenever it encounters a field it does not
recognize.
To define an unknown field handler:
1. Select the message set to which you are adding the unknown field handler.
2. Select File> Properties.
3. Select the Unknown Fields tab from the Message Set Properties window.
4. Enter the following properties:
Class name: the name of the Java class to which the handler belongs.
Method name: the unknown field handler method.
Static method: Select this check box if this is a static method.
NOTE: See Using a handler for unknown fields on page 7-6 for information on
coding the unknown field handler.
3-25
Understanding rules
Reordering fields
Message Broker uses drag-and-drop features to reorder fields. The following table
describes each of the drag-and-drop features. You can reorder fields by holding
down the Shift key while dragging a field.
Drag source
Drag target
Key
pressed
Action
User-defined type
Header, trailer, message

body, composite, union
None
Creates a link to
the target field
User-defined type

Ctrl
Creates a copy of
the user-defined
field in the target
Atomic, composite,
union (excluding
user-defined type)

None
Moves the field into

the target
Atomic, composite,
union (excluding
user-defined type)

Ctrl
Creates a copy of
the field in the
target
Atomic, composite,
union
User-defined types
Container
None
Makes the field a

user-defined type,
and changes the
existing field to a
user-defined
instance
Understanding rules
This section describes guidelines for writing rules, defining validation rules, and
user-defined type rules.
Guidelines for writing rules on page 3-27.
Examples of rules on page 3-28.
3-26
Understanding rules
Guidelines for writing rules

The guidelines discussed in this section apply to routing rules, explicit validation
rules, transformation rules, etc.
When writing a condition, you write the body of a Java function, which returns
true or false. You can reference any field in the message by its full name. For
example, suppose you have the message definition:
+ Add Customer
+ CompositeField1
+ AtomicField1
+ AtomicField2
To reference AtomicField1, enter:

AddCustomer.CompositeField1.AtomicField1
To reference the header, enter:

AddCustomer.header
To reference the trailer, enter

AddCustomer.trailer
Optional fields
To check for the existence of an optional field, check a boolean value consisting of
the field name with Exists appended to the end, for example
if (AddCustomer.CompositeField1Exists) {...
Check the Exists field before referencing the field since the data may be invalid. If,
however, the field is an optional atomic with a default value, then the field always
contains valid data and the Exists field indicates whether the data was present
when parsed.
If a rule is established for an optional field, Message Broker checks for the fields
existence before invoking the rule at run time.
Repeated fields
When you are writing a rule for a field that is marked as repeated, the field
variable will be an array holding all repetitions. To validate each repetition, write a
loop to iterate through the repetitions.
For fields that are not marked as repeated, but are contained within a repeated
field, the variable field represents a single instance of the field and Message Broker
takes care of applying the single rule to each repetition instance.
3-27
Understanding rules
Enumeration checking
To write a condition that includes checking a fields value against an enumeration,
invoke the function
ValueSet<EnumerationName>.contains
For example, suppose you have an enumeration named ServiceType, in a condition,

you could write
if ( !ValueSetServiceType.contains ( <fieldName> ) ) {
return false;
}
return true;
Although you can write rules for enumerations, the built-in validation that
enumerations provide is sufficient unless you want to check more than one
enumeration list.
User data
In the condition of a rule, you can reference the predefined userData Java variable.
In your run-time application, you can pass any descendant class of java.lang.Object
to the method that triggers execution of the rules. The object is made available to
the rule code as the predefined userData Java variable.
When routing to an EAServer component or EJB, userData must be of type
TypeUserData.
Examples of rules
This section contains validation rule examples for a repeated composite field and
its member fields. The elements used for the examples are:
+AddCustomer
+CompositeField1[ ]
+AtomicField1
+AtomicField2 ?
This is an example of a validation rule:

CompositeField1[]int sum;
// loop checking the members of all repetitions within
// the repeated composite field
for( int i = 0; i < field.length; i++ )
{sum = field[i].AtomicField1;
// if AtomicField2 was provided,then add the value to the sum
if( field[i].AtomicField2Exists )
3-28
Defining validation rules
{sum += field[i].AtomicField2;
}
// validation fails if the sum of
// the two fields exceeds 100
if( sum > 100 ) {return false;
}
}
return true;
The following is a validation rule for AtomicField1:

// verify that the value is a multiple of 3
return( ( field % 3 ) == 0 );
The following is a validation rule for AtomicField2:

// verify that the value is a multiple of 4
return( ( field % 4 ) == 0 );
AtomicField2 is optional. When attaching a rule to AtomicField2, Message Broker

checks for the existence of the field before executing the rule, so you do not need
to code an existence check. When attaching a rule at the CompositeField1 level,
you must code a check for the existence of AtomicField2.
When attaching rules to the members of a repeated composite, for example,
AtomicField1 and AtomicField2, you do not need to write the loop that iterates
through the repetitions. When writing the rule at the repeated composite level,
you must code the loop.

You define implicit and explicit validation during design time to ensure message
conformance and integrity. Incoming messages must satisfy both the defined
implicit and explicit validation rules. When you deploy to the run-time repository,
the Message Broker parser and builder performs validation based on your implicit
validation definitions. You can also define explicit validation rules consisting of a
Java code fragment that returns true if the message is valid. At run time you must
call the IValidation class methods to execute the explicit validation rules for the
message.
The next sections describe how to perform the following tasks:
Defining implicit validation on page 3-30
Defining explicit validation on page 3-30
3-29
Defining implicit validation

You define implicit validation when you create your header, trailer, and message
fields according to the following criteria:
Minimum, maximum, and fixed value fields
Minimum and maximum length fields
Repetition count
Picture code usage
Enumeration membership
NOTE: No Java code is required for implicit validation.
Defining explicit validation

You can define validation rules by writing Java fragments that return true or false.
Each header, trailer, and message within a message set contains a Validation Rules
folder that contains its validation rules, for example, you might want to check for a
certain character at the beginning or end of a field by writing the following
validation rule:
if ( !field.startsWith( "/")
|| !field.endsWith( "/") {
return false;
}
return true;
For additional guidelines for writing validation rules, refer to Guidelines for
writing rules on page 3-27.
NOTE: To deploy explicit validation rules you need to modify the class path on the
repository. See Specifying the Java class path on page 3-51 for more
information.
3-30
Attaching validation rules to user-defined types

You can attach validation rules to fields and subfields of user-defined types and to
fields and subfields of instances of user-defined types. For a given instance of a field,
all rules applying to it are processed, from general to specific.
For example, suppose you have user-defined field A and definition D that contains
an instance of A (D.A). Both A and D have a validation rule attached. D.A is
validated first by the rule for A and then by the specific rule for D.A.
Defining an explicit validation rule

To define an explicit validation rule:
1. Highlight the Validation Rules folder for the header, trailer, or message for
which you are writing the validation rule.

2. Double-click the Add Validation Rule icon.
3. To add your validation rule, follow the wizard instructions.
Modifying an explicit validation rule

You can use two methods to modify an explicit validation rule.
To use method 1:
1. Highlight the validation rule that you want to modify.
2. Select File> Edit Rule. An edit screen appears with the message definitions
displayed on the left side and the validation condition on the right.
3. Edit the validation condition as required.
4. Make your modifications and click Save. To cancel your changes click Revert.
To use method 2:
2. To view and modify the general properties of the validation rule, select the
Condition tab.
3.
To edit the rule, click Edit.
3-31
Creating routing rules

This section describes how to create routing collections, which contain routing
sets. Routing sets contain your routing rules and routing rule templates. Each
routing rule and routing rule template consists of Java code that returns true or
false, based on the message content and one of the following: the name of an
EAServer component method, a Java class method, or an EJB.
At run time, routing rules and routing rule templates are compiled into Java classes
and stored in the run-time repository. When your application calls the IRouter
class, Message Broker evaluates the condition and calls the target method if the
condition is true.
NOTE: Before deploying the routing collection, make sure the code base for this class
is listed in the classpath setting for the repository properties. Otherwise, the
generated code will not compile.
The next sections describe routing rules and how to use routing rule templates:
Guidelines for routing rules on page 3-32
Using routing rule templates on page 3-33
Guidelines for routing rules

You can create several rules for each message type. Multiple rules for the same
message are executed in ordinal order. Since routing passes the message to a
method, a message object can be passed to more than one routing target. Each
rule must have a name that is unique among the rules in a routing set. Rules consist
of a condition and an action.
Condition: Java code that dictates whether or not the action occurs. The Java
code should return either true or false.
Action: the routing rule that can pass the message to a Java method, an
EAServer component, or an EJB as the action.
3-32
Java class method

A Java class method that is a routing target must have a signature, such as:
public void myMethod( TypeMsgName msg,
java.lang.Object userData);
where MsgName is the name of the message definition. The target method
receives the message instance and the Java object is passed as the userData
parameter to the IRouter.route method.
An EAServer component method that is a routing target must have an IDL
signature, such as:
void myMethod( MsgName::TypeMsgName msg, TypeUserData userData);
where MsgName is the name of the message definition, and TypeUserData

corresponds to a Java class named TypeUserData that you supply.
To route messages to an EAServer component, your application must be
component-based and running in the same server or cluster as the target
component. You must also deploy the IDL types for your message set to the
EAServer repository, as described in the section titled Using generated IDL on
page 9-3.
An EJB method that is a routing target must have a signature, such as,
public void myMethod( TypeMsgName msg,
TypeUserData userData);
where MsgName is the name of the message type and TypeUserData is a Java class
that you supply.
To route to EJBs, you must configure the EJB routing properties to allow
connections to the host EJB server.
Using routing rule templates

Routing rule templates are like routing rules except that routing rule templates can
be used to route all messages in a message set, or just the request or response
messages, where routing rules apply only to a certain message format. Additionally,
the method signature for a routing rule template is user-defined.
As with routing rules, each routing rule template consists of a condition and an
action. Each template must have a name that is unique among the routing rule
templates in a routing set.
3-33
Custom signature
The routing target method signature for a routing rule template is known as the
custom signature. The custom signature must consist of at least one parameter.
The parameters can be of standard Java types or user-defined classes. If userdefined classes are used, the appropriate imports must be set in the routing set
properties. A return type can also be specified for the custom signature.
Message Broker allows you to edit routing rule templates after they have been
created. Like routing rules, routing rule templates fall under the routing set and are
contained within the Routing Rule Templates folders.
IRouter
IRouter contains the following method for routing to a template:
public Object routeToTemplate( IMBMessage msg,
String routingSetName, String routingTemplateName,
Vector parameterList )
throws MBException, Exception;
To route to a template, you call this method, passing in the message instance and
name of the routing set, the routing rule template, and a vector containing the
parameters for the custom signature.
Since a vector contains objects, if the custom signature consists of any primitive
types, such as int, boolean, short, and so on, they must be wrapped in their
respective wrapper classes, that is, Integer, Boolean, Short, and so forth. The
generated code will automatically take care of extracting the primitive type values
from the vector.
The result is that routeToTemplate( ) returns whatever was returned from the
routing target. If the custom signature is defined to return a Java primitive type, the
generated code will automatically wrap the value in the appropriate wrapper class
and return it.
NOTE: You may use substitutions such as #MessageName, #MessageType, #Request
Type, and #ResponseType in the condition code, target method name, and
custom signature.
To add a routing collection:

1. Highlight the Routing Collections folder.
2. Double-click the Add Routing Collection icon.
3. Follow the wizards instructions to create the routing collection.
3-34
To add a routing set:

1. Open the Routing Collections folder.
2. Highlight the routing collection to which you are adding the routing set.
3. Double-click the Add Routing Set icon.
4. Follow the wizards instructions to add the routing set to the routing
collection.
To add a routing rule:
1. Highlight the Routing Rules folder in the routing set to which you are adding
a routing rule.
2. Double-click the Add Routing Rule icon.
3. Follow the wizards instructions to add a routing rule to the routing set,
keeping in mind the following:

a.
Select the message body definition to which the routing rule applies.
b.
Enter a unique name for the routing rule.
c.
Enter the condition for the routing rule and select Next. The condition
must return either true or false.
d.
To enter your condition in a text editor, click Edit. An edit screen

appears with the message definitions displayed on the left side and the
routing condition on the right.
e.
Edit the routing rule as required.
f.
Enter a Java class method, an EAServer component method, or an EJB as

the target of the message.
g.
Click Finish.
NOTE: To reference message fields and elements directly, place your cursor in the
edit screen where you want to place the element, then expand and select
the element of the message definition you want to reference. You can also
drag and drop elements. When you select the element, it appears in the
edit screen.
3-35
There are two methods to modify and existing routing rule. Use method 1 or 2 to
modifying an existing routing rule.
Method 1:
1. Highlight the routing rule you want to modify.
2. Select File > Edit Rule. An edit screen appears with the message definitions
displayed on the left side and the routing condition on the right. Edit the
routing condition as required.
3. Make your modifications and click Save. To cancel your changes, click Revert.
Method 2:
1. Select File > Properties. You can view and modify the general properties of
the routing rule, which include the ordinal (the order in which the rule is
applied), or the name.
2. Edit the rule by selecting the Condition tab and clicking the Edit button.
3. Modify the target by selecting the Routing Target tab.
To specify the user data class:
The user data class is used as the userData variable in the Java code for the routing
rule and you must pass an instance of the class in place of the userData parameter
when calling IRouter.route. The TypeUserData class is also used as a parameter to
the target component or EJB.
To create the TypeUserData class:
1. Create a Java class named TypeUserData.
2. Select the Imports tab in the Routing Set properties dialog box.
3. Check whether the package containing the TypeUserData class is already listed
in the packages to import. If it is not, enter the package name in the Import
field and select Add.
If you are routing to EJBs, you must configure the properties that allow the
Message Broker run-time repository to connect to the server that hosts the EJBs.
To add a routing rule template:
1. Highlight the Routing Rule Templates folder in the routing set to which you
are adding a routing rule template.

2. Double-click the Add Routing Rule Template icon.
3-36
3. Follow the wizards instructions to add a routing rule template to the routing
set, keeping in mind the following:

a.
Enter a unique name for the routing rule.
b.
Specify if the template should be applied to request messages, response

messages, or all messages.
c.
Enter the condition for the routing template and click Next. The
condition must return either true or false.
d.
Click Edit to enter your condition in a text editor. An edit screen appears
with the message definitions displayed on the left side and the routing
condition on the right.
e.
Edit the condition as required. To reference message fields and elements

directly, place your cursor in the edit screen where you want to place the
element, then expand and select the element of the message definition you
want to reference. You can also drag and drop elements. When you select
an element it will appear in the edit screen.
f.
Enter a Java class method, an EAServer component, or an EJB as the

target of the message.
g.
Define the custom signature for the routing target method. The custom
signature must consist of at least one parameter. You may specify standard
Java types or non-standard, user-defined classes for the parameters. You
may also specify a return type for the routing target method.
h.
Click Finish.
To modify an existing routing rule template:

1. Highlight the routing rule template you want to modify.
2. Select File> Edit Rule. An edit screen appears with the message definitions
displayed on the left side and the routing conditions on the right. Edit the
routing condition as required.
3. Make your modifications and click Save to capture your changes or Revert to
cancel any modifications.
3-37
An alternative method for modifying a routing rule template:

2. View and modify the general properties of the routing rule template, which
includes the ordinal (the order in which the rule is applied) or the name.
3. Edit the rule by selecting the Condition tab and clicking the Edit button.
4. Modify the target by selecting the Routing Target tab.
5. Modify the signature of the routing target method by selecting the Custom
Signature tab.
To configure EJB routing properties:
1. Display the EJB Settings in the Routing Set properties dialog box.
2. Configure the fields by providing the following information:
Server URL: the URL to connect to the host server, as would be

specified for the java.naming.provider.url
EJB context property in an EJB client program. See your EJB server
documentation for details on the URL syntax.
Username: the username needed to connect.

Password: the password needed to connect.
JNDI factory class name: the Java class name of the EJB initial context
factory class, for example, com.sybase.ejb.InitialContextFactory
3. Specify any additional EJB context properties as necessary by clicking
Advanced.
3-38
Transforming messages
This section describes the process of transforming messages, headers and trailers,
and specifying transformation rules.
Message Broker allows you to transform a source message into a target message
by specifying transformation rules for the target message fields. When you deploy
to the run-time environment, the transformation rules are compiled.
In run-time applications, call the ITransformation class methods to execute the
transformation rules. Message Broker applies the rules to incoming source
messages, transforming them to the target message format.
NOTE: Implicit validation checking does not occur during transformation, so it is up to
you to ensure that the fields in the transformed message do not violate the
implicit validation rules. It is possible, however, to invoke the builder on the
transformed message to validate it.
The following sections describe how to perform the following tasks:
Creating transformation rules on page 3-39

Using header and trailer transformations on page 3-42
Understanding the transformation rules on page 3-43
Sample transformation rules on page 3-44
Creating transformation rules

To create transformation rules, collections and sets using Message Broker
Manager, review the following sections.
To establish a transformation rule:
1. Define a transformation collection.
2. Define a transformation set. When defining the transformation set, specify a
source and target message set. For example:

SWIFT (source) FIX (target)
3-39
3. Define a transformation, specifying a source and target message. For each field
in the target message, provide a set of rules that indicate how to fill in the
target field, for example, SWIFT to FIX - Target Field: PosDupFlag:
if (MT502.seqA.tag23G.function == NEWM &&
MT502.seqA.tag23G.subfunction == DUP)
FixEnvelope.MessageHeader.PosDupFlag = Y
In this example, the source message is MT502 and the target message is
FixEnvelope. The function and subfunction message fields of the MT502
message definition of the SWIFT message set are the source fields for the
transformation rule. These source fields are applied to the transformed
PosDupFlag field in the FixEnvelope message definition of the FIX message set.
4. Deploy to the run-time repository. When the ITransformation transform
method is called, the transformation rules are applied to the source message.
To add a transformation collection:
1. Highlight the Transformation Collections folder.
2. Double-click the Add Transformation Collection icon.
To add a transformation set:

1. Open the Transformation Collections folder.
2. Highlight the transformation collection to which you are adding the
transformation set.
3. Double-click the Add Transformation Set icon.
4. Follow the wizards instructions to add a transformation set to the
transformation collection, keeping the following in mind:

a.
Select a source message set from the display of available message sets,
then click Next.
b.
Select a target message set for this transformation, then click Next.
c.
Enter a name and comment for this transformation set.
d.
Select Finish.
NOTE: You can only transform messages from existing message sets. In addition,
to add a transformation there must be a message definition for the source
and a target message set.
3-40
To add a transformation:
1. Highlight the transformation set to which you are adding a transformation.
2. Double-click the Add Transformation icon.
3. Follow the wizards instructions to add your transformation, keeping the
following in mind:
a.
Select the message body definition for both the source and target. You
can select from any of the message bodies defined within the source and
target message set.
b.
Enter a name and comment for this transformation.
c.
Click Finish.
Once you have defined source and target message bodies, you can define the
transformation rules.
To define a transformation rule:
1. Highlight the transformation to which you are adding the transformation rule.
2. Select File > Edit Rules. The edit screen appears, along with the source and
target message bodies.

To create a transformation rule in the edit screen:
1. Specify fields in the edit screen.
2. Highlight the target message. Any existing rules for the target are displayed in
the edit screen.

3. Select the source message field that you want to appear in the edit screen.
The field appears in the message screen, for example, if the source message is
AddCustomer and you select the AddCustomer header icon, AddCustomer header
appears in the edit screen.
4. You can also drag and drop source and target message field names or type
directly in the edit screen.

NOTE: Be aware of the order in which target fields are filled in. You can reference
a target field that is not yet filled in. Target fields are filled in the order in
which they were defined.
3-41
Using header and trailer transformations

You may have situations where there are several different message transformations
within a set that all use the same header and trailer transformations. Instead of
writing a header and trailer rule for each transformation, you can write a headerto-header and trailer-to-trailer rule that is used for each message transformation
within a set.
To create a header-to-header or trailer-to-trailer transformation:
1. Highlight the transformation set to which you are adding a header-to-header
or trailer-to-trailer transformation.
2. Double-click the Add Transformation icon.
3. Follow the wizards instructions to add your transformation, keeping the
following in mind:
a.
Choose the header or trailer for both the source and target. The header/
trailer is mapped to the header/trailer of the target message set.
b.
The transformation is labeled header-to-header or trailer-to-trailer in the

Message Broker Manager.
You can supplement or override portions of your header-to-header and trailer-totrailer transformations when you create your message transformation rules. For
example, you may want to override or add one field to the target header for a
particular message.
When all of your transformation rules are written and deployed, they are invoked
in the following order:
1. If a header-to-header transformation exists, the source header is transformed
to the target header.

2. If you have written additional header transformation rules for a particular
message, these additional rules are applied to the target header.

3. If either of the above conditions exists, the message bodies are transformed.
4. If a trailer-to-trailer transformation exists, the source trailer is transformed to
the target trailer.

5. If you have written additional trailer transformation rules for a particular
message, these additional rules are applied to the target trailer.
3-42
Understanding the transformation rules

Message Broker provides the following method-like macros for use in writing
transformation rules.
ASSIGN(sourceField, targetField): This macro assigns member fields of
one composite based on matching the name and data type of the composite
members.
Atomic fields match if they have the same name and data type (int, float, etc.)
and if they are both either repeated or not repeated. If both fields are
repeated, then the target fields maximum repeat count must be greater than
or equal to the source fields maximum repeat count.
Composite fields match if both fields have the same name and their repeats
match as above for atomics.
Unions follow the same matching rules as for composites.
REPEAT(sourceField, targetField, expression): This macro allows you to
get the variable source which represents a repetition instance for the
expression, for example, you could enter:
REPEAT(SourceMsg.list, field, source + 3)
which would take each repetition occurrence

SourceMsg.list[i]
and add 3, placing the result in field [i].
Transformation rule information

When defining transformation rules, you are responsible for the following
information:
Make sure that any field referenced from the source message is present when
the rule is invoked. This means that you need to check Exists booleans for
optional source fields, as well as the presence of union members.
If the transformation rule is set on a repeated field, you are responsible for
allocating an array of the appropriate length and populating it with instances of
appropriate classes.
For rules on optional fields, you get a boolean variable called fieldExists, which
must be set to true if the field is to be treated as present in the message.
For rules on fields which are subfields of unions, you get a boolean variable
called fieldExists. If this is set to true, then the necessary members of the
parent are set to indicate that the target field is the present union member.
For rules on fields under a repeated field, the rule is executed for each
instance under the repeated field.
3-43
If a rule exists on a subfield of a required field, but the required field has no
rule, Message Broker will generate an instance of the required field. If the
required field is repeated, Message Broker generates an array of length 1.
If a rule exists on a subfield of an optional field, no code is generated to
automatically instantiate the field.
There is no need to set the _preValueTag field in unions because the builder
doesnt use this field. This particular field is only meant to be used when the
results from the parser are checked.
NOTE: You can use transformation rules to partially fill in a message, but all nonoptional fields must be filled in before the IMBMessage object is passed to any
other MB run-time interface or a run-time exception will occur.
Sample transformation rules

These examples demonstrate transformation rules for SWIFT and FIX messages.
SWIFT to FIX
If the source message name is MT502, the target message name is FixEnvelope,
and the target field is SenderCompID, the transformation rule would look like the
following:
if(MT502.sequenceB.subseqB2.tag95R.qualifier == BUYR) {
FixEnvelope.MessageHeader.SenderCompID
=MT502.sequenceB.subseqB2.tag95R.proprietary_code
} else {
if(MT502.sequenceB.subseqB2.tag95R.qualifier == INVR) {
FixEnvelope.MessageHeader.SenderCompID
=MT502.sequenceB.subseqB2.tag95R.proprietary_code
}
FIX to SWIFT
If the source message name is NewOrderSingle, the target message name is MT502,
and the target field is SubSeqB2 with the tag 22F, the transformation rule would
look like the following:
if (NewOrderSingle.tag204 != null)
{
MT502.sequenceB.subseqB2.tag22F.qualifier = TRCA;
MT502.sequenceB.subseqB2.tag22F.issuerCode = null;
MT502.subseqB2.tag22F.indicator =
(NewOrderSingle.tag204 == 0) ? AGEN : PRIN;
}
3-44
Defining adapter collections

An adapter collection is a container for adapter sets. Adapter collections allow
you to group related adapter sets together in the design-time repository. You can
create an adapter set by using the wizard, importing them from an XML file, or a
combination of both.
Adapter sets contain SQL adapter templates that outline the information needed
to generate Data Definition Language (DDL) and Data Manipulation Language
(DML) code used to save messages to a database. The DDL code creates the
tables used to store message data in the database. The DML code allows you to
store, retrieve, update, and delete the message data in the database. At run-time,
SQL adapter templates are compiled into Java classes and stored in the run-time
repository.
The following sections describe the following tasks:
Adding adapter collections and sets on page 3-45
Creating SQL adapter templates on page 3-46
Understanding SQL file generation on page 3-48
Adding adapter collections and sets

The following sections describe how to add an adapter collection and an adapter
set.
To add an adapter collection:
1. Highlight the Adapter Collections folder.
2. Double-click the Add Adapter Collection icon.
3. Follow the wizards instructions to create the adapter collection.
To add an adapter set:

1. Open the Adapter Collections folder.
2. Highlight the adapter collection to which you are adding the adapter set.
3. Double-click the Add Adapter Set icon.
4. Select the message set that the adapter set is to be associated with. Any SQL
templates that are created within this adapter set will be able to save
messages in the selected message set.
3-45
5. Enter a unique name for the adapter set. (A default name is provided.)
6. (Optional) Enter a comment for the adapter set.
7. To create the adapter set, click Finish.
Creating SQL adapter templates

SQL Adapter templates outline the information needed to generate Data
Definition Language (DDL) and Data Manipulation Language (DML) code used to
save messages to a database. Message Broker supports two types of SQL adapter
templates:
Generic templates. Generate a single table that is capable of storing all
message types defined in the message set that is associated with the adapter
set. Generic templates can save the unparsed representation of all messages
within the message set, as well as the values for any fields in the header or
trailer. 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.
Message-specific templates. Generate tables that are capable of storing one
message type in each table. Message-specific templates can save the unparsed
representation 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.
You specify the type of template you are creating when defining the template using
the SQL Adapter Template wizard.
Adding a SQL adapter template

To add a SQL adapter template:
2. Highlight the adapter set to which you are adding the adapter template.
3. Double-click the Add SQL Adapter Template icon.
4. Enter a unique template name for the SQL adapter template, then click Next.
5. Use the drop-down list to select the target database type, then click Next.
6. Use the drop-down list to select the raw data column type, then click Next.
The raw data column is used to store unparsed messages.
3-46
7. Select the SQL adapter template type from the drop-down list. To add a
Generic SQL adapter template, proceed to step 8. To add a Message-specific

SQL adapter template, proceed to step 9.
8. If you choose the Generic SQL adapter template, you need to complete
following steps:
a.
Enter the name of the database table, then click Next.
b.
By default, the SQL adapter template will only save unparsed messages to
the database. If you wish to save unparsed messages, click Select Fields...
This option opens the Specify Fields dialog. Here you can select fields in
the header and trailer and add them to the database table.
NOTE: You may only select non-repeated atomic fields.
For each selected field, defaults are provided for the name, as well as the
data type of the column that is generated in the table. You may override
these defaults.
c.
To save your changes and close the Specify Fields dialog, click Save.
d.
Click Next.
e.
Enter any custom columns you want included in the table, then click
Next. For each column, you need to specify the column name and the
column type.
f.
Enter any additional DDL information (such as create index

statements), then click Next. This DDL code is copied into the generated
SQL file after the table definition.
g.
Enter a comment in the template and click Next.
h.
Click Finish.
9. To create a Message-specific SQL adapter template, complete the following
steps:
a.
Select the messages you want to add to the template and click Next.
b.
For each message, enter the name of the database table and click Next.
c.
By default, the SQL adapter template will only save unparsed messages to
the database. If you wish to save unparsed messages, click Select Fields...
This option opens the Specify Fields dialog. Here you can select fields in
the header and trailer and add them to the database table.
3-47
NOTE: You may only select non-repeated atomic fields.
For each selected field, defaults are provided for the name, as well as the
data type of the column that is generated in the table. You may override
these defaults.
d.
To save your changes and close the Specify Fields dialog, click Save.
e.
Click Next.
f.
Enter any custom columns you want included in the table, then click
Next. For each column, you need to specify the column name and the
column type.
g.
Enter any additional DDL information (such as create index

statements), then click Next. This DDL code is copied into the generated
SQL file after the table definition.
h.
Repeat steps a to e for any other selected messages.
i.
Enter a comment in the template and click Next.
j.
Click Finish.
NOTE: If you do not specify column types, Message Broker generates default column
types during deployment. If you want to add a uniqueness constraint to a
column, you need to provide a column type and add the word unique to the
end of the sentence.
Understanding SQL file generation

For each SQL Adapter Template within an Adapter Set, MessageBroker will
generate a SQL file into the following directory:
%MBINSTALLDIR%\generated\<repositoryName>\sql\<adapterSet>\<templateName>.sql
The above script file should be executed on the target database server to create
tables that will be used to persist messages.
NOTE: The Method of SQL script execution is database server specific and should be
described in your DB server documentation.
For a generic SQL adapter template, Message Broker will generate a single table
with the table name provided by the user. For message-specific SQL adapter
templates, Message Broker will generate one table per message definition.
3-48
First column
An id column ("__messageID") will be generated as the first column in each table.
This column holds a unique identifying label for each message. The intent is that
this identifier can be used to retrieve or update the message data. The id column
is the primary key for the table. For flexibility, the type of this column is alphanumeric.
Second column
The second column in the table stores the message name. This is the name that
may need to be passed in order to parse the message (in the case where there is
no message type indicator field). This column is not generated for message-specific
SQL adapter templates since we already know which message type goes into
which table.
Third column
The third column in the table stores the raw data of the message. The name of the
column is "__rawData" and the column type is one of TEXT, VARCHAR, CHAR,
IMAGE, VARBINARY, BINARY, or RAW, depending on the target database type.
The rawData column can be null.
The next set of columns in the table is generated based on the message fields that
have been selected. For example, suppose the following fields have been selected
from the header (selected fields are shown in italic):
Header
Atomic1, String, mandatory
Composite1, mandatory
Atomic2, int32, mandatory
Atomic3, float, optional
Atomic4, date, YYMMDD, mandatory
Then the following table definition would be generated:

create table MyTemplateTableName (
__messageID
varchar(32) primary key,
__messageName char(128) not null,
__rawData
varchar(255) null,
Atomic1
varchar(255) not null,
Atomic2
integer not null,
Atomic3
real null,
Atomic4
varchar(32) not null
);
3-49
Importing and exporting repository information
If you specify any custom columns then they will be generated after the field
columns in the create table statement.
Finally, any additional DDL provided by you will be copied into the generated SQL
file after the table definition. This allows you to add any create index statements
(or any other DDL) that they wish to have included.
Importing and exporting repository information

In addition to creating message, routing, and transformation collections from
Message Broker Manager, you can define and import this information from an XML
file. If you define many message, routing, or transformation collections you may
find it faster and easier to define them in XML first, then import them into the
design-time repository. Once in the design-time repository, you can add to your
definitions, export to an XML file, and deploy to the run-time repository.
NOTE: When exporting and importing XML-based message sets, the generated XML
should not be modified. Modifications can result in run-time errors and
unexplained behavior. For information about creating XML files, refer to
Chapter 4: Understanding the Message Broker DTD.
To import information from an XML file:

1. Highlight the database icon that corresponds to the design-time repository to
which you are connected.

2. Select File > Import.
3. Enter the name of the XML file that stores your definitions and select Import.
When the import is completed, the definition information displays in the

Message Broker Manager. Files are sorted and imported in alphabetical order.
To export information to an XML file:
1. Highlight the database icon that stores the design-time repository from which
you are exporting.

2. Select File > Export.
3-50
Specifying the Java class path
3. Enter the name of the XML file to which you are exporting your design-time
repository. After the export completes you can modify the XML file, or
import it into another design-time repository.
NOTE: You can also right-click on most objects and choose Export to be more
selective about what you are exporting.
Specifying the Java class path

The Java code that executes your validation, transformation, and routing rules may
require classes that are deployed outside of Message Brokers Java code base.
Before deploying, make sure that the locations of all the extra class files used by
your code have been entered in the repository properties. If classes are missing,
you will get compile errors during deployment.
To configure the class path:
1. Display the Repository Properties window by highlighting the repositorys
icon.
2.
Select File > Properties.
3. Select the Class Path tab.

4. Add locations, if necessary, by typing the full code base path in the Item field.
Click Add.
Deploying to the run-time repository

Before you can invoke Message Brokers run-time classes, you must deploy the
design-time repository to the run-time repository. You have the following options:
Deploy the design-time repository to the same database or to a different
database than the run-time repository
Deploy the entire design-time repository or a subset of the repository to the
run-time repository
At deployment time, Message Broker creates IDL modules and Java files from the
design-time information to define the format of messages and fields. Message
Broker then compiles these modules into Java classes that can be manipulated in
3-51
user applications to parse, validate, route and transform incoming messages. For
more information about your deployed message definitions, refer to
Chapter 10: IDL/Java Message Representation.
NOTE: You should first attempt to deploy the parts that need access to user classes,
such as routing templates, before trying to deploy the entire repository. This
approach results in a quicker detection of any problems that may exist with
class paths, package names, or routing targets. If the entire repository is
deployed from the start, errors related to these items may take hours to
discover.
When you deploy a message set, Message Broker automatically generates IDL
modules, API templates, and SQL Adapter templates. You can modify your
deployment options to choose which of these activities occur during deployment.
To modify the IDL and API template deployment options:
2. Open the message collection which stores the message set you want to
modify.
3. Highlight the message set you want to modify.
4. Click File > Properties.
5. Click the Deployment Options tab.
6. Select or de-select the Generate IDL or Generate API Template
checkboxes as necessary.
7. Click Apply, then click OK.
To generate IDL or API templates immediately:

2. Open the message collection which stores the message set for which you
want to generate IDL modules or API templates.

3. Highlight the message set icon.
4. To generate and deploy the IDL, click File > Generate IDL. Or, to generate
the API templates, click File > Generate API Templates.
3-52
To modify the SQL Adapter Template Deployment Options:

2. Open the adapter collection which stores the adapter set you want to modify.
3. Highlight the adapter set you want to modify.
4. Click File > Properties.
1. Click the Deployment Options tab.
2. Select or de-select the Generate SQL Template checkbox as necessary.
If you chose to generate the IDL modules, they are automatically deployed to the
run-time database. If you chose to generate the API templates, you can now
deploy the API templates to the run-time database.
To deploy the Adapter Set:
If you chose to generate the SQL Adapter templates, you can deploy the SQL
Adapter template or the adapter set to the run-time database.
2. Open the adapter collection which stores the adapter set you want to deploy.
3. Highlight the adapter set or template you want to deploy.
4. Click File > Deploy.
5. Enter the User ID and password to connect to the Message Broker run-time
repository, then click OK.
If you chose to generate the SQL Adapter templates, you can deploy the SQL
Adapter template or the adapter set to the run-time database.
To deploy a SQL Adapter template:
2. Open the adapter collection and adapter set which stores the template you
want to deploy.
3. Highlight the adapter set or template you want to deploy.
4. Click File > Deploy.
5. Enter the User ID and password to connect to the Message Broker run-time
repository, then click OK.
3-53
In general, message sets need to be deployed before routing and transformation

sets. Once the necessary message sets have been deployed, then the routing and
transformation sets can be deployed.
To deploy the entire design-time repository:
1. Highlight the Design-time Repository icon.
2. Select File > Deploy.
3. Enter connection information and click OK. This determines where Message
Broker stores the compiled run-time repository.

To deploy a subset of the repository:
After a successful deploy of a part of the repository, the part need not be redeployed unless something has changed.
WARNING: If you deploy a subset, ensure there are no dependencies among the
objects to avoid errors when the router is invoked at run time. If you
modify and deploy a specific object, then you should update and redeploy
any other objects that have dependencies on that object. For example, a
routing set may need updates you have made to the message set, in
which case you must deploy the message set before you deploy the
routing set.
1. Highlight the subset (message collection, message set, routing collection,
routing set, and so on) that you want to deploy.

3. Enter connection information to the run-time repository. Click OK.
If you have defined a connection profile for a run-time repository, you can deploy
to it directly, without having to re-enter connection information.
To deploy to a Connection Profile:
1. Highlight the Design-time Repository icon.
2. Select File > Deploy to Connection Profile.
3. Select a connection profile from the list of defined run-time connection
profiles.
4. Click Connect.
3-54
4
Understanding the Message
Broker DTD
About this
chapter
This chapter discusses the elements of the Message Broker document type
definition (DTD). The Message Broker DTD enables you to create valid XML
documents that contain Message Broker definitions that you can import into the
design-time repository.
Topics include:
An introduction to XML (p. 4-2)
Understanding the Message Broker DTD (p. 4-4)
NOTE: This chapter assumes prior knowledge of XML. For detailed information about
XML, refer to the www.w3c.org Web site or any of the other Web sites and
books on the subject.
Getting started
Depending on the amount of information you need to define, creating and
importing Message Broker definitions from an XML file may be faster and easier
than creating them in the Message Broker Manager. You can modify the imported
definitions from the Message Broker Manager and then deploy to the runtime
repository, or export to another XML file.
To create valid XML files for importing into the Message Broker design-time
repository:
1. You must understand XML. For details, see An introduction to XML on
page 4-2.
4-1
An introduction to XML
2. You must understand Message Broker DTD. The Message Broker DTD is
located in the dtd subdirectory of your Message Broker installation. Some

sample XML files are provided in the samples subdirectory. For details, review
Understanding the Message Broker DTD on page 4-4.
NOTE: The actual DTD and XML files included with Message Broker may be
slightly different than the examples used in this chapter.
An XML document must be valid, well-formed, or both. A valid document must
satisfy a document type definition (DTD), which is a separate document that
defines the tags that are allowed in XML documents, and how those tags can be
used in relation to each other. A well-formed document satisfies a set of generic
syntax rules provided by XML.
Processing well-formed documents is faster than processing valid documents
because the parser does not have to verify against the DTD. When valid
documents are transmitted, the DTD must also be transmitted if the receiver does
not already possess it. Well-formed documents can be sent without any other
information.
XML documents should conform to a DTD if they are going to be used by more
than one application. If they are not valid, there is no way to guarantee that various
applications will be able to understand each other.
The examples in this chapter are valid documents which use the Message Broker
DTD.
NOTE: Generated XML for XML-based message sets should not be modified.
Modification of the XML can result in runtime errors and unexplained
behavior.
The following is an example of an XML document. The formatting has been

modified for readability.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MBR.Repository SYSTEM "file:D:/Messagebroker/dtd/
mbrep40.dtd" >
<MBR.Repository>
4-2
Understanding the Message Broker DTD
<MBR.Repository.ProductVersion/>
<MBR.MessageCollection>
<MBR.MessageCollectionName>People
</MBR.MessageCollectionName>
</MBR.MessageCollection>
<MBR.MessageSet>
<MBR.MessageSetName>Customers
</MBR.MessageSetName>
</MBR.MessageSet>
<MBR.Repository>
Any complete XML document starts with an XML declaration (see the first line in
the example above). The second and third lines define the document type
(MBR.Repository) and provide a path to the DTD which is used to validate the
elements in this XML file. These XML files use forward slashes to locate the DTD
for all operating systems.
If you imported this XML document into Message Broker, a message collection
named People and message set named Customers would be added to the designtime repository.
The Message Broker DTD for documents like this example, contain rules for
defining Message Broker elements, such as message collections, message sets,
routing collections, and so on. This XML file contains:
<MBR.Repository.ProductVersion/>
while the Message Broker DTD contains:

<!ELEMENT MBR.ClassBased EMPTY>
<!ATTLIST MBR.Repository.ProductVersion xmi.value (4.0) "4.0">
The EMPTY attribute signifies that the element MBR.Repository.ProductVersion does

not contain subelements. The default value of 4.0 for the xmi.value attribute is
picked up from the ATTLIST lines reference to 4.0.
Most elements in XML files that use the Message Broker DTD require an entry,
for example, the sample XML file contains:
The DTD contains:

<!ELEMENT MBR.MessageCollectionName (#PCDATA)>
The (#PCDATA) attribute indicates that string data is expected for this element.
The MessageCollectionName element accepts input in the XML file. Like most
entries, there are beginning and ending tags.
4-3

This section defines message and routing collections and describes how the
elements of the Message Broker DTD are used to create XML files that you can
import into Message Broker to populate the design-time repository.
This section describes the following:
What are message collections? on page 4-4
Defining a message set on page 4-5
Routing collections on page 4-11
What are message collections?

Message collections include the message sets and message fields that comprise a
message collection. The following DTD segment contains the rules for creating a
message collection:
<!ELEMENT MBR.MessageCollectionName (#PCDATA)>
<!ELEMENT MBR.Comment (#PCDATA)>
<!ENTITY % MBR.MessageCollectionProperties
'MBR.MessageCollectionName,
MBR.Comment?'>
<!ELEMENT MBR.MessageCollection
(%MBR.MessageCollectionProperties;)>
The DTD entry MBR.MessageCollection contains MBR.MessageCollectionProperties,

which consists of the MBR.MessageCollectionName and MBR.Comment elements,
both of which expect input as indicated by the #PCDATA entry. A question mark at
the end of the entry indicates that this element is optional.
The following XML entry creates a message collection named People:
<MBR.MessageCollection>
</MBR.MessageCollection>
4-4
Defining a message set

The following DTD describes how to add a message set to a message collection:
<!ELEMENT MBR.CharEncoding EMPTY>
<!ATTLIST MBR.CharEncoding
xmi.value (ASCII) "ASCII">
<!ELEMENT MBR.FieldProps (MBR.BeginFieldDelim?,
MBR.EndFieldDelim?,
MBR.BeginTagDelim?,
MBR.EndTagDelim?,
MBR.LeadingPad?,
MBR.TrailingPad?) >
<!ELEMENT MBR.MessageSetName (#PCDATA)>
<!ENTITY % MBR.ValidationRuleProperties
'MBR.ValidateRuleName,
MBR.ValidateCondition'>
<!ELEMENT MBR.ImportStatement (#PCDATA)>
<!ENTITY % MBR.ValidationImportsAssociations
'MBR.ImportStatement+'>
<!ELEMENT MBR.ValidationImports
(%MBR.ValidationImportsAssociations;)>
<!ENTITY % MBR.MessageSetProperties
'MBR.MessageSetName,
MBR.MessageCollectionName,
MBR.CharEncoding?,
MBR.FieldProps?,
MBR.ValidationImports?,
MBR.Comment?'>
<!ELEMENT MBR.MessageSet (%MBR.MessageSetProperties;)>
When you are defining a message set you must include a message set name and a
message collection name, as indicated by the MBR.MessageSetName and
MBR.MessageCollectionName entries above.
4-5
Using optional message set elements

The following elements of the MBR.MessageSetProperties entity are optional. These
elements can define character encoding, field properties, structure options,
validation imports, comments, and changes.
Character encoding. The ATTLIST entry:
<!ATTLIST MBR.CharEncoding xmi.value (ASCII) "ASCII"> indicates that the

attribute list contains only one member, ASCII, which is the default.
Field properties. Define the delimiters and pad characters for all fields within
a message set.
Validation imports. If you have validation rules compiled into Java classes for
use by the runtime APIs, include an import statement that indicates the
location of the compiled validation rules. You can call your own Java classes
from within validation rules. If you do, you need to import those Java classes,
for example, the entry
<MBR.ValidationImports>
<MBR.ImportStatement>com.msgbroker.sample.*
</MBR.ImportStatement>
</MBR.ValidationImports>
imports all the classes in the sample package.

Comments. Enter an optional comment to describe the message set.
The following XML entry creates a message set called Customers that belongs to
the message collection named People.
<MBR.MessageSet>
<MBR.MessageSetName>Customers</MBR.MessageSetName>
</MBR.MessageSet>
NOTE:
4-6
You can change field names and types during DTD import for XML-based
message sets.
Defining a message
This section adds a message definition, AddCustomer, to the Customers
message set created above.
<!ELEMENT MBR.MessageName (#PCDATA)>
<!ELEMENT MBR.MessageTypeValue (#PCDATA)>
<!ENTITY % MBR.MessageProperties
'MBR.MessageName,
MBR.MessageSetName,
MBR.MessageTypeValue,
MBR.Optional?,
MBR.Unordered?,
%MBR.TaggedDelimited;,
MBR.ValidationRules?'>
<!ENTITY % MBR.MessageAssociations
'(MBR.Composite | MBR.Union | MBR.Atomic |
MBR.UserDefinedInstance)+'>
<!ELEMENT MBR.Message (%MBR.MessageProperties;,
%MBR.MessageAssociations;)>
The message is defined by the entities within the MBR.Message element. The
%MBR.TaggedDelimited member can be part of a header, trailer, or message and is
defined as:
<!ENTITY % MBR.TaggedDelimited
'(MBR.BeginFieldDelim?,
MBR.EndFieldDelim?,
MBR.BeginTagDelim?,
MBR.EndTagDelim?,
MBR.PreValueTag?,
MBR.PostValueTag?)?'>
A message can consist of one or more composite, union, or atomic fields. In

addition, the message can be a link to a message if it is a MBR.UserDefinedInstance.
User-defined message fields are stored in the User-defined Types folder in the
Message Broker Manager.
The following XML entry defines a message:
<MBR.Message>
<MBR.MessageName>AddCustomer</MBR.MessageName>
<MBR.MessageTypeValue>add</MBR.MessageTypeValue>
<MBR.EndFieldDelim>\r\n</MBR.EndFieldDelim>
(...section deleted...)
</MBR.Message>
4-7
Adding fields to a message

The AddCustomer message contains four fields. The two atomic field types are
customerName and serviceType. The two user-defined types are shipAddress and
invoiceAddress. Address.serviceType can contain the values established for the
ServiceType enumeration. Refer to About enumerations on page 3-23 and Field
type on page 3-16 for more information.
<MBR.Atomic>
<MBR.FieldName>customerName</MBR.FieldName>
<MBR.MaxLength>20</MBR.MaxLength>
<MBR.String/>
</MBR.Atomic>
<MBR.UserDefinedInstance>
<MBR.ReusableName>Address</MBR.ReusableName>
<MBR.LinkName>shipAddress</MBR.LinkName>
</MBR.UserDefinedInstance>
<MBR.UserDefinedInstance>
<MBR.ReusableName>Address</MBR.ReusableName>
<MBR.LinkName>invoiceAddress</MBR.LinkName>
</MBR.UserDefinedInstance>
<MBR.Atomic>
<MBR.FieldName>serviceType</MBR.FieldName>
<MBR.EnumerationName>ServiceType</MBR.EnumerationName>
<MBR.TrailingPad>\s</MBR.TrailingPad>
<MBR.FixedLength>4</MBR.FixedLength>
<MBR.String/>
</MBR.Atomic>
Using enumerations
The following XML entry creates the enumeration named ServiceType, and two
members, GOLD and STANDARD. The values that GOLD and STANDARD
accept are gold and std respectively. Once an enumeration is defined, you can
add it to a message field.
<MBR.Enumeration>
<MBR.EnumerationName>ServiceType
</MBR.EnumerationName>
<MBR.EnumDataType>
<MBR.StringDataType/>
</MBR.EnumDataType>
<MBR.EnumMember>
<MBR.EnumMemberName>GOLD</MBR.EnumMemberName>
<MBR.EnumMemberValue>gold</MBR.EnumMemberValue>
</MBR.EnumMember>
<MBR.EnumMember>
<MBR.EnumMemberName>STANDARD</MBR.EnumMemberName>
4-8
<MBR.EnumMemberValue>std</MBR.EnumMemberValue>
</MBR.EnumMember>
</MBR.Enumeration>
Defining field types

This section describes how to define the atomic, union, and composite field types.
Notice that an atomic field contains no field members, while a union or composite
can contain fields and subfields.
<!ELEMENT MBR.MessageTypeIndicator EMPTY>
<!ATTLIST MBR.MessageTypeIndicator xmi.value (true | false)
"true">
<!ELEMENT MBR.ReadType EMPTY>
<!ATTLIST MBR.ReadType xmi.value (character) "character">
<!ENTITY % MBR.LengthProps
'((MBR.MinLength?, MBR.MaxLength?)
| MBR.FixedLength)?'>
<!ENTITY % MBR.AtomicProperties
'MBR.FieldName,
MBR.MessageTypeIndicator?,
MBR.EnumerationName?,
MBR.ReadType?,
MBR.Optional?,
MBR.Repeated?,
MBR.LeadingPad?,
MBR.TrailingPad?,
%MBR.LengthProps;,
<!ENTITY % MBR.AtomicAssociations
'(MBR.String
| MBR.Boolean
| MBR.Integer
| MBR.Float
| MBR.Bytes
| MBR.Enum
| MBR.Date)'>
<!ELEMENT MBR.Atomic (%MBR.AtomicProperties;,
%MBR.AtomicAssociations;)>
A composite field can contain subfields. If subfields are composites, they can also
contain subfields. You can repeat fields using the MBR.Repeated element and specify
if the fields within a composite must be ordered by using the MBR.Unordered
element.
<!ELEMENT MBR.Repeated (MBR.RepeatMin?,MBR.RepeatMax?)>
<!ENTITY % MBR.CompositeProperties
'MBR.FieldName,
MBR.Optional?,
MBR.Unordered?,
4-9
MBR.Repeated?,
<!ENTITY % MBR.CompositeAssociations
'(MBR.Composite | MBR.Union | MBR.Atomic |
<!ELEMENT MBR.Composite (%MBR.CompositeProperties;,
%MBR.CompositeAssociations;)>
Like a composite, a union can contain subfields, but only one of the subfields can
be present in the message.
<!ENTITY % MBR.UnionProperties
'MBR.FieldName,
MBR.Optional?,
MBR.Repeated?,
<!ENTITY % MBR.UnionAssociations
'(MBR.Atomic | MBR.Composite |
<!ELEMENT MBR.Union (%MBR.UnionProperties;,
%MBR.UnionAssociations;)>
The XML entry below creates a composite field, Address, that belongs to the Userdefined Types folder in the Customers message set. Address contains the atomic
fields street, city, stateProvince, country, and postalZipCode.
<MBR.UserDefinedType>
<MBR.Composite>
<MBR.FieldName>Address</MBR.FieldName>
<MBR.Atomic>
<MBR.FieldName>street</MBR.FieldName>
<MBR.String/>
</MBR.Atomic>
<MBR.Atomic>
<MBR.FieldName>city</MBR.FieldName>
<MBR.String/>
</MBR.Atomic>
<MBR.Atomic>
<MBR.FieldName>stateProvince</MBR.FieldName>
<MBR.String/>
</MBR.Atomic>
<MBR.Atomic>
<MBR.FieldName>country</MBR.FieldName>
4-10
<MBR.String/>
</MBR.Atomic>
<MBR.Atomic>
<MBR.FieldName>postalZipCode</MBR.FieldName>
<MBR.String/>
</MBR.Atomic>
</MBR.Composite>
</MBR.UserDefinedType>
Routing collections
Routing collections describe how to route a message to a Java class. The following
XML file defines a routing rule for the PeopleRouting set, which is part of the
Demo routing collection. The routing rule is a compiled Java class file that routes a
message to either a Sybase EAServer component, a Java class, or an EJB file if the
message satisfies the routing condition.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MBR.Repository SYSTEM "file:/d:/MBINSTALL/dtd/
mbrep40.dtd">
<MBR.Repository>
<MBR.Repository.ProductVersion xmi.value="4.0"/>
<MBR.ClassPath>
<MBR.ClassPathItem>d:\MBINSTALL\samples
</MBR.ClassPathItem>
<MBR.RoutingCollection>
<MBR.RoutingCollectionName>Demo
</MBR.RoutingCollectionName>
<MBR.Comment><![CDATA[Routing demonstration.]]>
</MBR.Comment>
</MBR.RoutingCollection>
<MBR.RoutingSet>
<MBR.RoutingSetName>PeopleRouting
</MBR.RoutingSetName>
<MBR.RoutingCollectionName>Demo
</MBR.RoutingCollectionName>
<MBR.RoutingImports>
<MBR.ImportStatement>com.ffusion.msgbroker.sample.*
</MBR.ImportStatement>
</MBR.RoutingImports>
</MBR.RoutingSet>
4-11
<MBR.RoutingRules>
<MBR.RoutingSetName>PeopleRouting
</MBR.RoutingSetName>
<MBR.MessageName>AddCustomer
</MBR.MessageName>
<MBR.RoutingRule>
<MBR.RoutingRuleName>TexanBonus
</MBR.RoutingRuleName>
<MBR.RoutingRuleCondition>
<![CDATA[java.lang.String state = new String
(AddCustomer.shipAddress.stateProvince);
return state.equalsIgnoreCase("TX");]]>
</MBR.RoutingRuleCondition>
<MBR.JavaClassTarget>
<MBR.ClassName>com.ffusion.msgbroker.sample.ParseRoute</
MBR.ClassName>
<MBR.MethodName>texanBonus</MBR.MethodName>
<MBR.StaticMethod xmi.value="false"/>
</MBR.JavaClassTarget>
</MBR.RoutingRule>
</MBR.RoutingRules>
<MBR.RoutingTemplates>
<MBR.RoutingSetName>PeopleRouting</MBR.RoutingSetName>
<MBR.RoutingTemplate>
<MBR.RoutingTemplateName>everyone</
MBR.RoutingTemplateName>
<MBR.TemplateMessageType xmi.value="all"/>
<MBR.RoutingRuleCondition><![CDATA[return true;]]></
MBR.RoutingRuleCondition>
<MBR.ClassName>com.ffusion.msgbroker.sample.ParseRoute</
MBR.ClassName>
<MBR.MethodName>bonus#MessageType</
MBR.MethodName>
<MBR.CustomSignature>
<MBR.ReturnType>double</MBR.ReturnType>
<MBR.ParameterType>#MessageType</
MBR.ParameterType>
<MBR.ParameterType>String</MBR.ParameterType>
</MBR.CustomSignature>
</MBR.RoutingTemplate>
</MBR.RoutingTemplates>
4-12
</MBR.Repository>
This XML file uses the following elements to check if a routing condition is met
and then routes it to the appropriate Java method.
The following examples give the code the needed to identify routing, validation, or
transformation rules and the conditions that need to be met for the rules to be
applied.
To indicate the location of any user-defined classes that are invoked from any
validation, routing, or transformation rules use
<MBR.ClassPathItem>d:\MBINSTALL\samples
The import statement that identifies user-defined classes invoked from rules
is
<MBR.ImportStatement>com.ffusion.msgbroker.sample.*
To identify the routing rule use

<MBR.RoutingRuleName>TexanBonus
To identify the condition that triggers the routing rule use

<MBR.RoutingRuleCondition>
<![CDATA[java.lang.String state
= new String(AddCustomer.shipAddress.stateProvince);
return state.equalsIgnoreCase("TX");]]>
</MBR.RoutingRuleCondition>
If this condition is met, the routing rule is applied and the message is sent to
JavaClassTarget.
To identify the class name and method to be applied to any message that
meets the RoutingRuleCondition use
<MBR.ClassName> com.ffusion.msgbroker.sample.ParseRoute
</MBR.ClassName>
<MBR .MethodName>texanBonus</MBR.MethodName>
To describe the custom signature for the routing rule template use:
<MBR.CustomSignature>
<MBR.ReturnType>double</MBR.ReturnType>
<MBR.ParameterType>#MessageType</MBR.ParameterType>
<MBR.ParameterType>String</MBR.ParameterType>
</MBR.CustomSignature>
In this case, the custom signature consists of parameters of type

#MessageType and String, and a return of type double.
4-13
4-14
5
Creating API templates
About this
chapter
This chapter covers the procedures for creating, modifying, and deploying API
templates.
What is an API template? (p. 5-2)
Selecting message types to process (p. 5-2)
Creating an API template (p. 5-3)
Modifying template properties (p. 5-4)
Specifying method implementation patterns (p. 5-6)
Deploying a template (p. 5-7)
Getting started
To use this chapter, review the following steps:
1. For an overview of on API template and how it is used in Message Broker,
review What is an API template? on page 5-2.

2. To learn how to mark messages as requests or responses and identify the
matching request or response message, review Selecting message types to

process on page 5-2.
3. To create a new template using Message Broker Manager, see Creating an
API template on page 5-3.

4. To change the properties of a template, review Modifying template
properties on page 5-4.

5. For information on using macros, see Specifying method implementation
patterns on page 5-6.
5-1
What is an API template?
6. When you have finished creating a template, you need to deploy it. Review
Deploying a template on page 5-7.
What is an API template?

A Message Broker API template specifies an implementation pattern for an API
that processes messages defined in a message set. When defining a template, you
use macros to represent repeated code elements such as a messages name or
data type. When you deploy a message set that contains an API template, Message
Broker generates an interface, local and remote, containing one method for each
message type in the message set. You can also specify that a template applies only
to a specific subset of messages, such as response or request messages.
Templates can also be used to create an Enterprise JavaBean (EJB) or a CORBA
IDL interface. When generating an EJB template, Message Broker uses the
implementation pattern to create the home interface, remote interface, and
implementation class for a stateless session bean, then creates an EJB JAR file. You
can install the EJB into application servers that are compliant with the EJB 1.1 and
EJB 2.0 specification.
When generating an IDL template, Message Broker uses the implementation
pattern to create the IDL for a CORBA interface. You can install the interface in
Sybase EAServer, and create a CORBA C++ or Java component that implements
the interface.
Selecting message types to process

Message protocols may define either request or response messages or both. In a
message definitions properties, you can mark messages as requests or responses
and identify the matching request or response message.
Templates can be applied to generate methods to process all messages in a set,
only messages marked as requests, or only messages marked as responses. When
using the request-only or response-only option, template macros are available to
represent the message that completes the request/response pair. This feature
allows you to easily create templates that process request messages and return the
corresponding response message, or vice-versa.
5-2
Creating an API template
Creating an API template

Templates are associated with a message set and are represented in the Message
Broker Manager by icons in the API Templates folder under each message set.
To create a new API template:
1. Highlight the API Templates folder under the icon for your message set.
2. Double-click the Add API Template wizard in the right pane of Message
Broker Manager. Or, select File > New API Template.
3. Enter a name for the template. This name is used as part of the generated EJB
class or IDL interface name.

4. Specify if the template should generate methods for message definitions or
message fields.
5. Specify if the template should be applied to all messages, request messages, or
response messages.
6. Specify whether the template generates an EJB 1.1, EJB 2.0, or a CORBA
(IDL) component.
7. Enter the code that appears in the beans implementation class outside of the
message-processing methods. You can edit the code again later if necessary.
8. Enter the code pattern for the methods that process messages. You can type
the pattern directly or click Edit to launch the template editor, which contains
icons for each available macro. You can edit the code again later if necessary.
9. Enter an optional comment that describes the intended use of the template.
10. To create a new template with the specified properties, click Finish.
5-3
Modifying template properties

When you highlight the API Templates folder under your message set icon in the
left pane, icons for each API template display in the right pane of the Message
Broker Manager.
To view or modify a templates properties:
1. Highlight the templates icon.
3. In the Properties window, change the template properties as necessary. Refer
to Changing API template properties on page 5-4 for more information

about the template properties.
Changing API template properties

The Properties window consists of two tabs: General and Template, as
discussed in the following sections.
About the General Tab

The General tab properties include the following fields:
Name: Specifies the name of the template.
Generate methods for : Determines which subset the template generates
methods for during deployment. The options include:
Message definitions: Message Broker uses the template to generate an

interface containing one method for a subset of message definitions.
Message fields: Message Broker uses the template to generate an

interface containing one method for a subset of message fields.
Apply template to: Determines the subset of messages to be processed by
methods derived from the template. The options include:
All messages: Message Broker uses the template to generate a method

for each message defined in the template.
Request only: Message Broker generates a method only for messages

marked as a request.
Response only: Message Broker generates a method only for messages

marked as a response.
5-4
API type: Specifies whether the template generates an EJB or a CORBA
component.
Select EJB 1.1 or EJB 2.0 for an Enterprise JavaBean.

Select IDL for a CORBA component.
NOTE: If you change the API type, you must manually change the IDL code syntax
to Java or vice versa.
Comment: Provides an optional description of the API template.
About the Template Tab

The Template tab allows you to view and edit the method template and one-time
declarations that appear in the EJB implementation class. The fields included allow
the selection of one-time code and repeated code.
One-time code: Specifies code that is not repeated in the class definition,
such as variable declarations and one or more ejbCreate methods for an EJB
template. For an IDL template, you can specify #include directives, or declare
data structures that are used in the implementation pattern.
For an EJB template, you must preserve the default EJB template code. Any
code you add must be valid for an EJB stateless session bean. Do not enter
Java import statements here. Instead, specify the Java import statements in the
Message Set Properties dialog box. The default code for a new EJB template
is an ejbCreate method declared as follows:
public void ejbCreate() throws CreateException,
RemoteException
{
}
For an IDL template, there is no default code.

Repeated code: Specifies a code pattern for methods to be generated for
each qualifying message type (all messages, response messages, or request
messages). The default for a new EJB template is as follows:
void process#MessageName ( #MessageType msg )
throws RemoteException
{
};
Edit the return type and parameter definitions as necessary, and add a method
body to fully specify each generated Java methods implementation. For more
information about using macros, refer to Specifying method implementation
patterns on page 5-6 The default for a new IDL template is:
5-5
Specifying method implementation patterns
void process#MessageName( in #MessageType msg );
You can edit the return type and parameter definitions using the macros
described in the next section.
Specifying method implementation patterns

To launch the template editor:
1. Click the Edit button on the Template tab of the Template Properties
dialog box, or highlight a templates icon.

2. Choose File > Edit Template. The template editor provides icons for each
template macro.
3. Double-click the icon to insert a macro. This step is optional.
The following macros are available:

#MessageSetName: The name of the message set that contains the template
definition. For an IDL template, this corresponds to the IDL module name.
For an EJB template, this corresponds to the last part of the following Java
package:
com.ffusion.msgbroker.generated.MessageBroker.api.
MessageSetName.TemplateName
#MessageName: The name of the message being processed, as displayed in
the Message Broker Manager. In code patterns, this macro is typically used in
variable and method names.
#MessageType: The Java or IDL type of the message being processed, as
displayed in the Message Broker Manager. In code patterns, use this macro to
declare variables, parameters, or method return types.
#RequestName: If the messages Request-Response property is Request,
#RequestName has the same value as #MessageName. If the message currently
being processed is a response, then #RequestName represents the name of
the request that is paired with the response.
#RequestType: The Java or IDL type of the #RequestName message.
#ResponseName: If the messages Request-Response property is Response,
#ResponseName has the same value as #MessageName. If the message
currently being processed is a request, then #ResponseName is the response
that is paired with the request.
#ResponseType: The Java or IDL type of the #ResponseName message.
5-6
Deploying a template
You can deploy templates individually or as part of the message set that contains
them. Refer to Deploying to the run-time repository on page 3-51 for
instructions.
Deploying an EJB template

When you deploy an EJB template, Message Broker creates an EJB-JAR file that can
be deployed to application servers that support versions 1.1 and 2.0 of the EJB
specification.
After deployment, you can view the generated Java source code by highlighting the
templates icon and selecting File > View Java.
Message Broker creates the generated beans EJB-JAR file in the runtime
subdirectory of your Message Broker installation directory. The JAR file is named
MessageSetName_TemplateName.jar. MessageSetName is the message set name and
TemplateName is the API template name.
Deploying an IDL template

When you deploy an IDL template, Message Broker generates the following IDL
module containing the generated IDL interface:
com/ffusion/msgbroker/generated/MessageBroker/api/MessageSet/
Template/MessageSetTemplate.id1
MessageSet is the name of the message set and Template is the name of the
template.
After deployment, you can view the generated IDL file by right-clicking File >
View IDL on the template.
5-7
Deploying an API template

Message Broker allows you to deploy a specific API template or all API templates
for a given message set separately from the message set itself. To do this, the
message set must first be deployed.
To deploy an API template:
1. Right-click on the API templates folder under the message set.
2. Highlight the API template icon.
5-8
6
Using flows
About this
chapter
This chapter introduces the concept of Flow and how you can use it to specify
sequences of message processing events without having to code directly to the
API.
Topics include:
What is a flow? (p. 6-1)
Defining a flow (p. 6-3)
Using operators (p. 6-9)
Creating a flow using the Message Broker Manager (p. 6-24)
Deploying the flow (p. 6-26)
What is a flow?
A flow is a sequence of message processing events specified in a declarative
manner. More specifically, a Flow is a set of defined Activities chained together with
Control Links.
A Flow has an execution context. Initially, this context is empty. As the Flow
executes, output from the Activities adds or modifies named objects in the
execution context. Prior to the execution of a Flow, the caller can infuse objects
into the initial execution context through an API.
The following section describe some Flow concepts:
Activities on page 6-2
Control links on page 6-2
Sub-flows on page 6-2
Loops on page 6-3
Forks on page 6-3
6-1
What is a flow?
Activities
Within a flow are Activities. An Activity represents an action that needs to be
performed. These actions are known as operators. There are several ready-to-use
operators for invoking Message Broker functionality (such as parsing, transforming,
and building messages), opening a database connection, and creating, sending, and
receiving messages to and from a JMS queue. In addition, operators are provided
to facilitate calling into user-defined Java classes and EJBs as well as invoking other
flows (known as Sub-Flows). An Activity accepts a sequence of input arguments
for its associated operator and either returns an output or a fault argument.
Two types of Activities include a Start Activity and an End Activity. A Start Activity
is placed at the beginning of a Flow definition and has no incoming Control Links.
An End Activity is an activity with no outgoing Control Links. When an End
Activity is reached, execution along that path stops. Execution of the Flow is
considered complete when all End Activities are completed.
Every Activity has an Exit Condition. An Exit Condition is a Boolean expression
that determines whether an activity has finished. The Exit Condition is optional; if
it is not present, the state defaults to true. A true state indicates that the task
is complete and execution can continue as defined by the Control Links. If the Exit
Condition is false, the Activity is executed again. Typically, an activity would
execute once and have an Exit Condition that was always true.
Control links
Control Links define the sequence in which Activities are executed, and more than
one Control Link can be defined from a given source Activity.
A Boolean Transition Condition associated with the Control Link determines
which of the Control Links are executed. The Transition Condition may reference
any of the named objects in the execution context that have been produced by the
Flow. The Transition Condition is optional; if it is not present, the state defaults to
true.
Sub-flows
Sub-Flows allow you to nest Flows. A Sub-Flow is an Activity representing another
Flow that will execute in its own context. Input can be accepted from and output
returned to the parent Flow. Sub-Flows are executed using the Internal Execute
operator.
6-2
Using flows
Defining a flow
Loops
Looping is controlled via the Exit Condition on an activity - if the Exit Condition
evaluates to false the activity is invoked again. When an Exit Condition is applied
to an activity using the Internal Execute operator it allows a sequence of activities
in a Sub-Flow to be executed in a loop.
Forks
You can create a fork by defining two or more Control Links from a source
Activity to multiple target Activities. The Transition Conditions of more than one
of the Control Links may evaluate to true.
Defining a flow
A Flow is defined in an XML file. The XML conforms to mbflow60.dtd in
%MB60INSTALLDIR%\dtd. You can use any method you are familiar with to create
this file, or you can use the Message Broker Manager. Instructions for using the
Message Broker Manager to define a Flow are found later in Creating a flow using
the Message Broker Manager on page 6-24.
The root of a flow definition

The outline of a Flow looks like this:
<flowModel name=thisFlow>

<!- Service Providers -->
<!- Activities -->
<!- Control Links -->
</flowModel>
The root element of the Flow definition is the flowModel element. The name
attribute names the flow.
The Message Broker Manager includes an Add Flow Definition wizard that walks
you through the steps of naming and describing your Flow and includes an editor
and template that you can use to define your Flow. Step-by-step instructions for
using the wizard are included later in this chapter.
6-3
Defining a flow
The start of a flow

A Flow begins with a flowSource element. The flowSource element is used to
assign names to any input arguments to the Flow. This is done by specifying the
names of the arguments as input elements. The Java type may be specified for
each input item. If the type is not specified, the type is assumed to be String.
Note that the input elements must be object types since primitive types cannot be
stored in the execution context. If primitive types are required by operators being
invoked from the flow, it is expected that their corresponding object types be
specified. When the flow is executed, the object types will be automatically
converted to their corresponding primitive types (ie - "java.lang.Integer" -> "int")
as required by the operator. The following is an example of a flowSource
definition:
<flowSource name=startHere />
<input name=messageString>
<input name=userData type=TypeUserData >
</flowSource>
The end of a flow

Every Flow ends with a flowSink element. The flowSink element can be used
to return any objects from the execution context of the Flow to the caller. This is
done by specifying the name of the objects to be returned as the output element
in the flowSink element:
<flowSink name=endHere>
<output name=myReturnObject />
<output name=myReturnObject2 />
</flowSink>
Activities
As stated earlier, Activities are actions or tasks to be completed. Activities accept
input arguments, perform some task, and then return an output or a fault
argument.
When you define an Activity, you include the names of the objects from the
execution context that should be passed as input arguments. These are specified
using the "<input name=""/>" syntax. The order of the input elements implies
the order of the parameters in the underlying operation.
Constant values can also be passed using the "<input value="" type=""/>"
syntax. You can specify the Java type (i.e. Integer, Boolean, String, etc.) of
the constant value, but this is optional. The Flow uses the following defaults if the
type of the constant value is not specified:
6-4
Using flows
Defining a flow
If the value is null, the default is a null object.

If the value begins with an alphabetic character (isLetter()), the type defaults
to string.
If the value begins with a digit or a plus or minus sign followed by a digit, it will
be checked for valid conversion to integer or double. If the conversion
fails, the value is assumed to be a string.
All other values default to type string.
The return value is added to the execution context using the name supplied in the
output element. If the Activity throws an exception, the exception object is
added to the execution context with the name specified in the fault element.
NOTE: The input and output arguments for activities are always object types. If the
operator method being invoked by the activity has primitive types as its input
and/or output arguments, the necessary object > primitive and primitive
>object type conversions will be performed automatically when the flow is
executed.
The implement element specifies which service provider and operator method
to invoke for this particular activity.
Exit conditions
The Exit Condition, if any, is specified using the exitCondition attribute as shown
in the example below. Note that the Exit Condition could have been omitted in
this instance since the value supplied is true. If no Exit Condition is specified, the
default is true.
<activity name=ValidateMessage exitCondition=true >
<input name=msg/>
<input value=null />
<fault name=mbException />
<implement serviceProviderType=MessageBroker
operation=validate />
</activity>
Control links
Control Links specify the order in which Activities are executed. Each control link
is also associated with two activities - a source activity and a target activity. After
an Activity is completed, all Control Links with the completed Activity as its
source are examined. Control will then go to any target Activity for which the
Transition Condition is true. (The Transition Condition is optional and defaults
to true.)
6-5
Defining a flow
Control links are defined using the controlLink element. The syntax looks like
this:
<controlLink
source=getMessageFromQueue
target=parseMessage
transitionCondition=msReceiveException==null &&
outputMsg != null" />
The source attribute specifies the name of the source Activity, and the target
attribute specifies the name of the target Activity. The transition condition is
specified using the transitionCondition attribute.
Service providers
A Service Provider Type declaration contains information necessary to access an
operator. The syntax looks like this:
<serviceProviderType name="SWIFTAdapter" type="EJB" >
<property name="initialContextFactory"
value="weblogic.jndi.WLInitialContextFactory" />
<property name="serverURL" value="t3://localhost:9101" />
<property name="userName" value="system" />
<property name="password" value="ffsserver" />
<property name="jndiName" value="CASmfAdapter" />
</serviceProviderType>
The following service provider types are supported:

Internal (no serviceProviderType declaration required)
MB (no serviceProviderType declaration required)
EJB
Java
JMS
Database
6-6
Using flows
Defining a flow
A sample flow definition

To help you understand what a Flow looks like, suppose you want to perform the
following operations:
Receive a message from a JMS Queue
Parse the message
Validate the message
Invoke a method on an EJB (in this example, the SWIFT Adapter) using the
validated message
Assume you want to take an Omgeo message object and a user data object and
create the following operator sequence:
ValidateOmgeoObject
BuildOmgeoMessage
SubmitOmgeoMessage
ReturnOmgeoObject
The Flow could be written as follows:
<flowModel name="SWIFTSendFromJMS">
<flowSource name="SWIFTSendFromJMSIn">
</flowSource>
<flowSink name="SWIFTSendFromJMSOut">
</flowSink>

<serviceProviderType name="SWIFTAdapter" type="EJB" >
value="weblogic.jndi.WLInitialContextFactory" />
<property name="serverURL" value="t3://localhost:9101" />
<property name="userName" value="system" />
<property name="password" value="ffsserver" />
<property name="jndiName" value="CASmfAdapter" />
<serviceProviderType name="ffsswiftOutgoingMsgQ"
type="JMS">
value="weblogic.jndi.WLInitialContextFactory"/>
6-7
Defining a flow
<property name="serverURL" value="t3://

localhost:9101"/>
<property name="userName" value="system"/>
<property name="password" value="ffsserver"/>
<property name="connectionFactoryName" value="QF"/>
<property name="queueName"
value="ffsswiftOutgoingMsgQ"/>
<property name="queueUserName" value=""/>
<property name="queuePassword" value=""/>
<property name="transacted" value="false"/>
<property name="acknowledgeMode"
value="Session.AUTO_ACKNOWLEDGE"/>
<property name="messageSelector" value=""/>

<activity name="jmsReceive">
<input value="true" type="Boolean"/>
<input value="3000" type="Integer"/>
<output name="receivedMessage"/>
<fault name="jmsReceiveException"/>
<implement serviceProviderType="ffsswiftOutgoingMsgQ"
operation="receiveString"/>
</activity>
<activity name="parse">
<input name="receivedMessage"/>
<input value="SWIFT"/>
<output name ="parsedMessage"/>
<fault name="parseException"/>
<implement serviceProviderType="MessageBroker"
operation="parse"/>
</activity>
<activity name="validate">
<input name="parsedMessage"/>
<input value="null"/>
<fault name="validateException"/>
operation="validate"/>
</activity>
<activity name="adptSend">
<input name="receivedMessage"/>
<output name="sendResult"/>
<fault name="adptSendException"/>
6-8
Using flows
Using operators
<implement serviceProviderType="SWIFTAdapter"
operation="send"/>
</activity>

<controlLink
source="jmsReceive"
target="parse"
transitionCondition="jmsReceiveException==null &&
receivedMessage!=null"
/>
<controlLink
source="parse"
target="validate"
transitionCondition="parseException==null"
/>
<controlLink
source="validate"
target="adptSend"
transitionCondition="validateException==null"
/>
</flowModel>
Using operators
There are several ready-to-use operators that you can call as activities in a Flow
definition. These operators are:
Internal operators on page 6-10
Message Broker operators on page 6-10
EJB Operators on page 6-16
Java Operators on page 6-17
JMS Operators on page 6-18
Database operators on page 6-23
6-9
Using operators
Internal operators
The single Internal operator is execute.
execute
This operator executes a Sub-Flow. The Flow executes in its own execution
context. The first two input elements specify the Flow Set Name and Flow
Definition name of the Sub-Flow. Any remaining input elements are the arguments
passed to the Sub-Flow (the number of these should match the number of input
elements within the flowSource element of the Sub-Flow). Upon completion of
the Sub-Flow, the output of the Sub-Flow will be added to the execution context
of the parent Flow with the name specified as the output element. If execution
of the Sub-Flow results in an exception, the exception will be added to the
execution context of the parent Flow with the name specified as the fault
element.
The following is an example of how this operator gets associated with an Activity:
<activity name="" >
<input name="flowSetName" />
<input name="flowDefinitionName" />
<input name="flowInput1" />
<input name="flowInput2" />
<output name="subFlowOutput" />
<fault name="mbsException" />
<implement serviceProviderType="Internal"
operation="execute"/>
</activity>
Message Broker operators

The following operators are supported by the Message Broker service:
buildString on page 6-11
buildBytes on page 6-11
parse on page 6-11
transform on page 6-12
validate on page 6-13
route on page 6-13
routeToTemplate on page 6-13
sqlInsert on page 6-14
sqlUpdate on page 6-14
6-10
Using flows
Using operators
sqlSelect on page 6-15

sqlDelete on page 6-15
buildString
Description
Syntax
This operator invokes the Message Broker Builder to produce a string.

public String IBuilder.buildString( IMBMessage msg )
throws MBException;
Here is an example of how this operator gets associated with an Activity:

<activity name="">
<input name="messageObject" />
<output name="messageString" />
<fault name="mbException" />
operation="buildString"/>
</activity>
buildBytes
Description
Syntax
This operator invokes the Message Broker Builder to produce a byte array.
public byte[] IBuilder.buildBytes( IMBMessage msg )
throws MBException;

<activity name="">
<output name="messageBytes" />
operation="buildBytes"/>
</activity>
parse
Description
Syntax
This operator invokes the Message Broker Parser.

public IMBMessage IParser.parseToIDL( byte[] buf, String
msgSetName )
throws MBException;
public IMBMessage IParser.parseToIDL( String string,
String msgSetName ) throws MBException;
public IMBMessage IParser.parseToIDL( byte[] buf,
String msgSetName, String msgName )
throws MBException;
public IMBMessage IParser.parseToIDL( String string,
String msgSetName, String msgName ) throws MBException;
6-11
Using operators
Here are two examples of how this operator can be associated with an Activity:
<activity name="">
<input name="MessageString" />
<input name="msgSetName" />
<output name="MessageObject" />
operation="parse"/>
</activity>
<activity name="">
<input name="MessageBytes" />
<input name="msgSetName" />
<input name="msgName" />
<output name="MessageObject" />
operation="parse"/>
</activity>
transform
Description
This operator invokes the Message Broker Transform.
Syntax
Public IMBMessage ITransformation.transform( IMBMessage

sourceMsg, String transformationSetName, String
transformationName, Object userData)
throws MBException;

<activity name="">
<input name="transformationSetName" />
<input name="transformationName" />
<input name="userDataObject" />
<output name="newMessageObject" />
operation="transform"/>
</activity>
6-12
Using flows
Using operators
validate
Description
Syntax
This operator invokes the Message Broker Validation.

public void IValidation.validate( IMBMessage sourceMsg, Object
userData)
throws MBException;

<activity name="">
</activity>
route
Description
Syntax
This operator performs message routing.

public void IRouter.route( IMBMessage msg, String routingSetName,
Object userData)
throws MBException;

<activity name="">
<input name="routingSetName" />
operation="route"/>
</activity>
routeToTemplate
Description
Syntax
This operator performs message routing.

public Object IRouter.routeToTemplate( IMBMessage msg,
String routingSetName, String routingTemplateName,
Object userData) throws MBException;

<activity name="">
<input name="routingSetName" />
<input name="routingTemplateName" />
6-13
Using operators
operation="routeToTemplate"/>
</activity>
sqlInsert
Description
This operator persists a message to a database using an SQL template. Here is an

example of how this operator gets associated with an Activity:
<activity name="">
<input name="dbConnection" />
<input name="msg" />
<input name="msgID" />
<input name="adapterSetName" />
<input name="sqlTemplateName" />
<input name="rawData" />
<input name="customColumns" />
operation="sqlInsert"/>
</activity>
sqlUpdate
Description
This operator updates a message in a database using an SQL template. Here is an

example of how this operator gets associated with an Activity:
<activity name="">
<input name="msg" />
<input name="rawData" />
<input name="customColumns" />
operation="sqlUpdate"/>
</activity>
6-14
Using flows
Using operators
sqlSelect
Description
This operator selects a message from a database using an SQL template.

Here are two examples of how this operator can be associated with an Activity:
<activity name="">
<output name="sqlMessage" />
operation="sqlSelect"/>
</activity>
<activity name="">
<output name="sqlMessage" />
operation="sqlSelect"/>
</activity>
sqlDelete
Description
This operator deletes a message from a database using an SQL template. Here are
two examples of how this operator can be associated with an Activity:
<activity name="">
operation="sqlDelete"/>
</activity>
<activity name="">
6-15
Using operators

operation="sqlDelete"/>
</activity>
EJB Operators
The EJB Operator allows you to call methods on an EJB. The EJBs being invoked
must be declared in the Flow. To obtain a reference to an EJB, use these values:
initial context factory
server URL
user name
password
JNDI name
An EJB is declared using the serviceProviderType element. The input values in
the example below correspond to the information listed above.
<serviceProviderType name="<EJBName>" type="EJB" >
<property name="initialContextFactory
value="com.sybase.ejb.InitialContextFactory" />
<property name="serverURL" value="iiop://localhost:9009" />
<property name="userName" value="username" />
<property name="password" value="password" />
<property name="jndiName" value="FIX/SendReceive" />
The following is an example of how an EJB Operator gets associated with an

activity. The name of the EJB Operator is declared in the serviceProviderType
attribute of the implement element and the name of the method on the EJB to
call is declared in the operation attribute. The input value(s) correspond to the
parameter(s) of the EJB method.
<activity name="">
<input name="<methodInput>" />
<output name="<methodOutput>" />
<fault name="ejbException" />
<implement serviceProviderType="<EJBName>"
operation="<EJBMethodName>"/>
</activity>
6-16
Using flows
Using operators
When invoking an EJB operator, the type of the output and fault elements must be
specified. Otherwise, the output type will be assumed to be java.lang.String and the
fault type will be assumed to be java.lang.Throwable.
Java Operators
The Java Operator is provided so that you can access Java class methods from a
Flow. Java classes must be declared in the flow, and the fully-qualified name of the
Java class is required.
A Java class is declared using the serviceProviderType element. The values in the
example that follows correspond to the information listed above.
<serviceProviderType name="<JavaName>" type="Java" >
<property name="className"
value="com.ffusion.myProduct.myComponent.myClass" />
The following example shows how a Java class method is associated with an
Activity. The input values correspond to the parameters of the method. The
output and fault names are the names assigned to return and exception values
as they are placed into the execution context. The types of the output and fault
elements must be specified. If they are not specified, the type of the output
defaults to java.lang.String and the type of the fault object defaults to
java.lang.Throwable.
<activity name="">
<input name="myParameter1" />
<input name="myParameter2" />
<output name="myReturnValue" type="int" />
<fault name="adException" />
<implement serviceProviderType="<JavaName>"
operation="<methodName>"/>
</activity>
6-17
Using operators
JMS Operators
JMS Operators are provided so you can access JMS queues from a Flow. JMS
queues must be declared in the Flow. The following information is required in
order to identify a JMS queue:
To locate the QueueConnectionFactory:
initial context factory
server URL
user name
password
JNDI name of queue connection factory
To locate the Queue:
JNDI name of queue
To create a QueueConnection:
user name (optional)
password (optional)
To create a QueueSession:
transacted
acknowledge mode
To create a QueueSender:
no additional information needed
To create a QueueReceiver:
message selector (optional)
A JMS queue is declared using the serviceProviderType element. The input values in
the example that follows correspond to the information listed above.
<serviceProviderType name="<JMSName>" type="JMS" >
value="weblogic.jndi.WLInitialContextFactory"/>
<property name="serverURL" value="t3://localhost:9101"/>
<property name="connectionFactoryName"
value="ConnectionFactoryJNDIName" />
<property name="queueName" value="FIXQueueJNDIName" />
<property name="queueUserName" value="queueUserName" />
<property name="queuePassword" value="queuePassword" />
<property name="transacted" value="false" />
6-18
Using flows
Using operators
value="Session.AUTO_ACKNOWLEDGE" />
<property name=messageSelector" value="JMSType = 'Omgeo'" />
The following operators are supported on a JMS queue:

createStringMessage on page 6-19
createObjectMessage on page 6-20
getMessagePropertyString on page 6-20
receiveMessage on page 6-20
receiveString on page 6-21
receiveObject on page 6-21
send on page 6-22
sendMessage on page 6-22
setMessageProperty on page 6-23
For simple send and receive operations, use:
receiveString or receiveObject
send
For more involved send and receive operations that require access to the JMS
Message properties, use the following:
createStringMessage or createObjectMessage
getMessagePropertyString
receiveMessage
sendMessage
setMessageProperty
createStringMessage
Description
Creates a JMS TextMessage which is used to send a message containing a string.

This operator takes in a single argument which is the string data for the JMS
TextMessage. Here is an example of how this operator is associated with an
Activity:
<activity name="">
<input name="messageString" />
<output name="myMessage"
<fault name="jmsException" />
<implement serviceProviderType="<JMSName>"
operation="createStringMessage"/>
</activity>
6-19
Using operators
createObjectMessage
Description
Creates a JMS ObjectMessage which is used to send a message containing a

serializable object. This operator takes in a single argument which is the object
data for the JMS ObjectMessage. Here is an example of how this operator gets
associated with an Activity:
<activity name="">
<output name="myMessage"
operation="createObjectMessage"/>
</activity>
getMessagePropertyString
Description
Gets the value of a string property on a JMS Message object. The first argument
specifies the JMS Message object to retrieve the property value from and the
second argument specifies the name of the property. Here is an example of how
this operator gets associated with an Activity:
<activity name="">
<input name="jmsMessage" />
<input name="propertyName" />
<output name="propertyValue" />
operation="getMessagePropertyString"/>
</activity>
receiveMessage
Description
Receives a JMS Message from a queue. The first argument specifies whether to
wait, and the second argument specifies how long to wait. If a waiting period of 0
is supplied, then the call waits forever. If the timeout period expires, then the
output argument will be null. If this is the first use of the queue, an initialization
of the queue will be performed.
<activity name="">
<input value="true" />
<input value="100" />
<output name="jmsMessage" />
6-20
Using flows
Using operators
operation="receiveMessage"/>
</activity>
receiveString
Description
Receives a message string from a queue. The first argument specifies whether to
wait, and the second argument specifies how long to wait in milliseconds. If a
waiting period of "0" is supplied, then the call waits forever. If the timeout period
expires, then the "output" argument will be null. If this is the first use of the queue,
an initialization of the queue will be performed.
This operator can only be called if the Message object returned by JMS is of type
TextMessage.
<activity name="">
<output name="messageString" />
</activity>
receiveObject
Description
Receives a message object from a queue respectively. The first argument specifies
whether to wait, and the second argument specifies how long to wait in
milliseconds. If a waiting period of "0" is supplied, then the call waits forever. If the
timeout period expires, then the "output" argument will be null. If this is the first
use of the queue, an initialization of the queue will be performed.
This operator can only be called if the Message object returned by JMS is of type
ObjectMessage.
<activity name="">
<output name="messageObject" />
operation="receiveObject"/>
</activity>
6-21
Using operators
send
Description
Sends a message string or object to a queue. The first argument specifies the
message string or object data, the second argument specifies the delivery mode
(either javax.jms.DeliveryMode.NON_PERSISTENT or
javax.jms.DeliveryMode.PERSISTENT), the third argument specifies the priority (as
an integer), and the fourth argument specifies the lifetime of the message in
milliseconds. If this is the first use of the queue, an initialization of the queue will
be performed. Based on the type of the message data (String or object) the JMS
Message object will be a TextMessage or ObjectMessage. This operator is
equivalent to calling createStringMessage or createObjectMessage (depending on
the type of the message data) and sendMessage in sequence.
<activity name="">
<input name="messageString" />
<input name="deliveryMode" />
<input value="javax.jms.DeliveryMode.NON_PERSISTENT"
type="Integer" />
<input name="priority" />
<input name="timeToLive" />
operation="send"/>
</activity>
sendMessage
Description
Sends a JMS Message object to a queue. The first argument specifies the JMS
Message object, the second argument specifies the delivery mode (either
javax.jms.DeliveryMode.NON_PERSISTENT or
javax.jms.DeliveryMode.PERSISTENT), the third argument specifies the priority (as
an integer), and the fourth argument specifies the lifetime of the message in
milliseconds. If this is the first use of the queue, then the initialization of the queue
is performed. The JMS Message object will be a TextMessage or ObjectMessage.
<activity name="">
<input name="deliveryMode" />
<input name="priority" />
<input name="timeToLive" />
operation="sendMessage"/>
6-22
Using flows
Using operators
</activity>
setMessageProperty
Description
Sets the value of a string property on a JMS Message object. The first argument
specifies the JMS Message object, the second argument specifies the name of the
property, and the third parameter specifies the value of the property. The JMS
Message object will be a TextMessage or ObjectMessage. Only string properties
are supported in this version.
<activity name="">
<input name="propertyName" />
<input name="propertyValue" />
operation="setMessageProperty"/>
</activity>
Database operators
Since database connections cannot be passed via the EJB API, Database Operators
are provided.
Database properties must be declared in the Flow. The following information is
required to identify a database:
database URL of the form jdbc:subprotocol:subname
user name
password
A database connection is declared using the serviceProviderType element. The first
three input values correspond in the following example to the information listed
above.
Any properties other than those listed above will be considered to be named
properties specific to the particular type of database being used.
<serviceProviderType name="<DBConnectionType>" type="Database" >
<property name="databaseURL" value="jdbc:blah:blah" />
<property name="userName" value="sa" />
<property name="password" value="sysadmin" />
<property name="myProperty1" value="xxx" />
<property name="myProperty2" value="yyy" />
6-23
Creating a flow using the Message Broker Manager
The following operators are supported on a database:

connect on page 6-24
disconnect on page 6-24
connect
Description
Establish a connection to the database. Here is how this operator gets associated
with an Activity:
<activity name="">
<output name="dbConnection" />
<fault name="sqlException" />
<implement serviceProviderType="<DBConnectionType>"
operation="connect"/>
</activity>
disconnect
Description
Disconnect from the database. Here is how this operator gets associated with an
Activity:
<activity name="">
<fault name="sqlException" />
<implement serviceProviderType="<DBConnectionType>"
operation="disconnect"/>
</activity>

When you create a flow for the first time using the Message Broker Manager, you
will need to create the following:
a flow collection
a flow set
a flow definition
To create a flow:
1. Start the Message Broker Manager.
6-24
Using flows
2. Connect to your database by right-clicking on the Message Broker icon and

selecting Connect.
NOTE:
You can connect to a database using several methods: right-click on the

icon, as described above; select Connect from the File menu; select
Connect from the Tools menu, or click the Connect icon. You can also
connect through the Connection Profiles window by clicking the
Connection Profiles icon, or by selecting Connection Profiles from
the menu.
3. Right-click on Flow Collection and select New Flow Collection.You can also
click on Add Flow Collection in the right pane or select New Flow
Collection from the File menu.
4. Enter a name for your collection and click Next.
5. Enter a comment describing your flow collection and click Finish.
6. Right-click on your newly created flow collection in the right-hand pane and
select New Flow Set.
7. Enter a name for your flow set and click Next.
8. Enter a comment describing your flow set and click Finish.
9. Right-click on your newly created flow set in the right-hand pane and select
New Flow Definition.
10. Enter a name for your new flow definition and click Next.
11. If you were importing a previously defined flow definition file, you would enter
the name of the file on this screen. Click Next.
12. Click Edit and define your flow.
13. Click Next.
14. Enter a name for your flow definition and click Next.
15. Enter a comment to describe your flow definition and click Finish.
6-25
Deploying the flow
Deploying the flow

You deploy a Flow using the Message Broker Manager just as you would deploy a
Message Set. When you deploy a Flow, Message Broker does the following:
Parses the Flow XML file and generates Java code that is used during
execution of the flow.
Packages the generated code into the run-time Jar file. See Using generated
Java on page 9-4 for the name and location of this Jar file.
Transfers information to the run-time repository about the Flow Sets, Flow
Definitions, and associated code file.
Using the run-time Java API

A Flow may be executed in two ways:
Through a run-time Java API similar to the other Message Broker run-time
APIs (where the caller is in full control of "main" and any threading model).
This process is discussed below.
Through the Message Broker Server. For details, see Chapter 9: IDL/Java
message representation.
To invoke a Flow using the run-time Java API, you first invoke the createFlow ()
method in the IMBInstance interface to obtain a Flow processing object called
IFlow. Once you have an IFlow object, you can invoke the following operations:
infuse objects into the initial context of the Flow
execute the Flow
get the output of the Flow
get the error on the Flow, if one occurred
For example:
IMBInstance mbI =
MBInstanceFactory.createInstanceFromJConnect
// Create a flow executor
IFlow flow = mbI.createFlow();
// Set the inputs to the flow as defined by the flow source
// For this example, the two inputs are the message string
and
// the name of the message set that the message belongs to
Vector input = new Vector();
input.add( msgString );
6-26
Using flows
Deploying the flow
input.add( "Customers" );
flow.setContext( input );
// Execute the flow
HashMap output = flow.execute( "flowSet",
"flowParseBuild"
);
NOTE: For more information on the methods in IFlow, see Chapter 11: Runtime
Application Interfaces.
6-27
Deploying the flow
6-28
Using flows
7
Using the Message Broker
run-time API
About this
chapter
This chapter explains how to use the Message Broker run-time API in stand-alone
Java applications or in server components such as Enterprise JavaBeans.
Topics include:
Understanding program flow (p. 7-3)
Connecting to the run-time repository (p. 7-4)
Parsing text-encoded messages (p. 7-5)
Constructing IDL/Java message instances (p. 7-7)
Invoking message validation rules (p. 7-8)
Invoking message routing rules (p. 7-8)
Transforming messages to another format (p. 7-9)
Building messages (p. 7-9)
Persisting messages using SQL adapter templates (p. 7-11)
Executing a flow (p. 7-14)
For detailed API information, see the following areas of the Javadocs:
Building
Interface
Interface
Interface
com.ffusion.msgbroker.interfaces.IBuilder
com.ffusion.msgbroker.interfaces.IMBInstance
com.ffusion.msgbroker.interfaces.IMBMessage
7-1
Getting started
Getting started
To use this chapter, review the following steps:
1. To learn about Message Broker applications and their components, see
Understanding program flow on page 7-3.

2. To create a connection to the repository to perform parse, build, route,
validation, and transformation operations, see Connecting to the run-time

repository on page 7-4.
3. To parse text-encoded messages into Java classes that can be manipulated by
the application, review Parsing text-encoded messages on page 7-5.

4. To create message objects (IMBMessage instances) directly by constructing an
IDL/Java object to represent the message instance, review Constructing IDL/

Java message instances on page 7-7.
5. To add rules to your message sets to perform explicit, user-defined validation
of a messages content, see Invoking message validation rules on page 7-8.

6. To define rules to forward messages to a Java class method, a Sybase EAServer
component method, or a business method in an Enterprise JavaBean, see

Invoking message routing rules on page 7-8.
7. To create rules to transform the content of a message instance to another
message format, review Transforming messages to another format on

page 7-9.
8. To convert message objects into a data stream, see Building messages on
page 7-9.
9. For information about how Message Broker persists messages in a relational
database, see Persisting messages using SQL adapter templates on page 711.
10. For message data type formats, refer to Chapter 9: IDL/Java message
representation.
7-2
Using the Message Broker run-time API
Understanding program flow
Understanding program flow

Message Broker applications can be either stand-alone Java applications or a
collection of server components, such as Enterprise JavaBeans that run in an
application server.
All Message Broker applications have the ability to do the following:
1. Connect to a run-time repository using the MBInstanceFactory and
IMBInstance classes.
2. Call IMBInstance.disconnect to disconnect from the repository database.
3. Create, parse, and process messages. Applications typically perform one or
more of the following operations:
Parse binary or text-encoded messages with the IParser interface. This

interface reads data from a text string or byte buffer and parses the data
into an IMBMessage instance.
Create messages from uncollected data with the MBMessageFactory class.

Invoke message validation rules with the IValidation interface.
Invoke message routing rules with the IRouter interface.
Transform messages to another format using the ITransformation
interface.
Build binary or text-encoded messages using the IBuilder interface.

Inspect and debug message contents using the IMBMessage interface
methods.
Connecting
Class
com.ffusion.msgbroker.factory.MBInstanceFactory
Disconnecting
Interface
Message
Processing
Package
Class
com.ffusion.msgbroker.interfaces
com.ffusion.msgbroker.factory.MBMessageFactory
7-3

The run-time repository is a database containing information about your message
types, transformation rules, routing rules, and so on.
To connect to the run-time repository, use the IMBInstance interface. There are
several methods available to support different types of databases.
To connect to Sybase ASA/ASE, connections are created using the
MBInstanceFactory.createInstanceFromJConnect method. Alternatively, if your
application uses an ASE high-availability server, use the
MBInstanceFactory.createHAInstanceFromJConnect method to obtain a
connection that supports failover to another server.
To connect using Oracle, use the MBInstanceFactory.createInstanceFromOracle
method.
To connect using DB/2, use the MBInstanceFactory.createInstanceFromDB2
method.
To connect using JDBC URL, use the MBInstanceFactory.createInstanceFromURL
method.
You must have a connection to the repository to perform parse, build, route,
validation, and transformation operations using collections deployed on that
repository. You must connect to the run-time repository where your message,
routing, and transformation collections are deployed. You can connect to multiple
repositories by creating one IMBInstance for each repository.
Each IMBInstance encapsulates one database connection to the repository and a
memory cache for storage of commonly-used repository information. Access to
one IMBInstance is safe from multiple threads or server component instances.
Applications that perform intensive Message Broker operations from multiple
threads or server component instances may benefit from using several
IMBInstance objects that connect to the same repository. Doing so can reduce
contention on shared cache and database resources.
7-4
Connecting
Class
com.ffusion.msgbroker.factory.MBInstanceFactory
Disconnecting
Interface
Parsing text-encoded messages

The IParser interface contains methods to parse text-encoded messages into Java
classes that can be manipulated by the application.
Use the IMBInstance.createParser method to create a parser instance. The
IMBParser.parseToIDL methods parse encoded messages and return an
IMBMessage instance.
There are several variants of IMBParser.parseToIDL with different parameter lists.
If your message set has a header with a message-type indicator field, you can parse
messages by calling any of the IMBParser.parseToIDL variants. If your message set
lacks a message-type indicator, you can use only the IMBParer.parseToIDL variants
that accept a message set name and a message name.
A single parser cannot be used by multiple threads. If you parse messages in server
components, one parser instance can be used by only one component instance.
You can use a parser in multiple components if you use explicit thread
synchronization. However, restricting parser use to one component yields a
simpler application design and better performance.
Reusing an IParser instance rather than always creating a new one can dramatically
improve performance when parsing messages from XML-based message sets.
NOTE:
Message Broker includes a debug version of the parser that outputs a trace of
message fields as they are parsed. The debug parser is useful for
troubleshooting ambiguous parse rules. To create a debug parser instance, call
the IMBInstance.createDebugParser. The debug parser usage is the same as
for regular IParser instances.
Parsing
Interface
Interface
Interface
com.ffusion.msgbroker.interfaces.IMBParser
7-5
Using a handler for unknown fields

When processing the members of an unordered composite, if the parser
encounters a field that it does not recognize, it will check and see if the user has
registered an unknown field handler method in the message set properties in the
Message Broker Manager. If so, then the parser invokes the handler method to
parse unknown fields.
The handler must be a Java method with the following signature:
public int parse( String buffer, int startPosition, Vector
unknowns )
In this signature, buffer is the message content being parsed, startPosition is the
position within the buffer where the unknown data begins, and unknowns is a
java.util.Vector instance where you can append any objects that you wish. Typically,
you will append objects representing parsed fields. The parse method must return
the new buffer position or -1 if the field is not recognized.
The following code shows an example of a parse method:
public int parse( String buffer, int startPosition, Vector unknow
ns )
{
System.out.println( "Custom parse: " + startPosition );
int soh;
int equ;
int newPos = -1;
int tagNum;
String pretag;
// look for the equals sign
equ = buffer.indexOf( '=', startPosition );
if( equ != -1 ) {
// extract the tag
pretag = buffer.substring( startPosition, equ );
// convert to a number and check whether this tag
// is within a known range
tagNum = Integer.parseInt( pretag );
if( tagNum > 1000 ) {
// we have a tag out of range
// look for \u0001
soh = buffer.indexOf( '\u0001', equ + 1 );
if( soh != -1 ) {
// move to just after the SOH
newPos = soh + 1;
// and put the skipped data in the vector
7-6
Constructing IDL/Java message instances
unknowns.addElement(
buffer.substring( startPosition, soh ) );
}
return( newPos );
}
After IMBParser.parseToIDL returns, you can call the

IMBMessage.getUnknownFields method to obtain the java.util.Vector containing
data added by the unknown field handler.
Constructing IDL/Java message instances

In some cases, message data may not be available in a format that can be parsed.
The method MBMessageFactory.createIDLMessage allows you to create message
objects (IMBMessage instances) directly by constructing an IDL/Java object to
represent the message instance. For example, you might need to create messages
that combine data from two data sources. After you initialize the Java/IDL
representation, pass it to the MBMessageFactory.createIDLMessage method,
which returns an IMBMessage instance.
If the message set header has a message-type indicator field, call
IMBMessage.setMessageTypeIndicatorValue to specify the indicator value. This will
ensure that subsequent calls to IMBMessage.getMessageTypeIndicatorValue return
the correct value.
The Java/IDL message representation has a class for the message body, nested
classes for the message header and trailer, and nested classes for the enumeration,
union, and composite fields used by the message format. You must initialize all
nested objects as well as the top level message fields.
For more information, refer to Chapter 9: IDL/Java message representation.
Constructing
Messages
Class
Interface
com.ffusion.msgbroker.factory.MBMessageFactory
7-7
Invoking message validation rules
Invoking message validation rules

You can add rules to your message sets to perform explicit, user-defined validation
of a messages content. Explicit validation rules are not enforced unless you call the
run-time API to execute the explicit validation code.
To create an IValidation instance, call the IMBInstance.createValidation method.
The IValidation.validate method validates the content of a message object
(IMBMessage instance). You can pass objects required by the validation code in the
userData parameter, for example, if the validation code checks field content against
the contents of a remote database, you can pass the database connection as the
userData parameter.
You can use an IValidation instance simultaneously on multiple threads or server
component instances. For information about how to create validation rules in the
Message Broker Manager, refer to Defining validation rules on page 3-29.
Validation
Interface
Interface
Interface
com.ffusion.msgbroker.interfaces.IValidation
Invoking message routing rules

Routing collections allow you to define rules to forward messages to a Java class
method, a Sybase EAServer component method, or a business method in an
Enterprise JavaBean. For example, you might use routing rules to sort transactions
by postal codes. You can define several rules for one message, with a boolean
condition for each that determines whether a message instance should be
forwarded.
If no condition is defined, then it is the same as if a user defined a condition that
always returns true, that is, an unconditional routing. Call the
IMBInstance.createRouter method to create an IRouter instance. The
IRouter.route method looks up routing rules associated with the message type,
evaluates the condition of each rule against a message object and if the condition
holds, takes the action specified in the routing rule.
A single IRouter instance cannot be used by multiple threads or server component
instances. You must create an IRouter instance for each thread or server
7-8
Transforming messages to another format
component instance that invokes routing. For information about how to define
routing rules in the Message Broker Manager, refer to Creating routing rules on
page 3-32.
Routing
Interface
Interface
Interface
com.ffusion.msgbroker.interfaces.IRouter
Transforming messages to another format

Transformation collections allow you to create rules to transform the content of a
message instance to another message format.
Call the IMBInstance.createTransformation method to create an ITransformation
instance. The ITransformation.transform method invokes the transformation rules
in a specified transformation set and returns a new message object encoded in the
destination format.
You can use an ITransformation instance simultaneously on multiple threads or
server component instances. For more information, see Transforming messages
on page 3-39.
Transformation Interface
Interface
Interface
com.ffusion.msgbroker.interfaces.ITransformation
Building messages
Use the IBuilder interface to convert message objects into a data stream; that is,
the encoded message is written to a byte or string buffer. For example, a message
gateway application might parse messages received in one format, transform them
to Java message objects in another format, then use the builder interface to
forward a data stream to another server.
The IMBInstance.createBuilder method returns an IBuilder interface. Call the
IBuilder.buildBytes or IBuilder.buildString method to create a byte or text stream,
in that order. You cannot use a single builder instance simultaneously on multiple
7-9
Building messages
threads. If you use the builder in server components, one builder instance can be
used by one component instance only.
NOTE: You can use an instance in multiple components if you use explicit thread
synchronization; however, restricting use to one component yields better
performance and a simpler application design.
Logging, and debugging message contents

Once you have a message object, you can call IMBMessage methods to inspect the
message contents or print the message contents for debugging or logging
purposes. The following methods allow you to inspect the message contents
programmatically:
IMBMessage.getBodyName: returns the name of the message type.
IMBMessage.getSetName: returns the name of the message set where the
message type is defined.

IMBMessage.getMessageTypeIndicatorValue: returns the value of the
message-type indicator that was read by the parser to determine the message
type.
IMBMessage.getIDLInstance: returns the Java/IDL representation of the
message, allowing you to access the message contents as Java classes.

For logging or debugging purposes, the IMBMessage.print methods allow you to
print the message contents to the console or a specified java.io.Writer or
java.io.OutputStream instance.
NOTE: If your Message Broker application runs as a collection of server components,
the output from the IMBMessage.print method with no parameters is recorded
in the server log file.
Building
7-10
Interface
Interface
Interface
com.ffusion.msgbroker.interfaces.ITransformation
Persisting messages using SQL adapter templates

Adapter collections allow you to define SQL Adapter Templates that can be used
to persist Message Broker messages in a relational database.
When a SQL Adapter template is deployed Message Broker generates two types
of files:
SQL script file. Contains create table statements required to create
database tables needed to persist messages defined in the template. For more
information about the generated SQL script files please see Understanding
SQL file generation on page 3-48.
Java code. Lets you insert, update, select and delete messages from the
database tables created by the above SQL script file.
You can invoke the generated Java code using the ISQLAdapter component. To
obtain a reference to a ISQLAdapter component please call
IMBInstance.createSQLAdapter method. The ISQLAdapter interface contains
methods such as insert, select, update and delete which lets you persist Message
Broker messages encapsulated in an IMBSQLMessage object.
A single ISQLAdapter instance cannot be used by multiple threads or server
component instances. You must create an ISQLAdapter instance for each thread
or server component instance that invokes ISQLAdapter. For more information of
how to use ISQLAdapter component, see sample code at the end of this section.
Understanding transactions
You may want to invoke the persistence methods as part of a larger transaction.
For this reason, the ISQLAdapter interface offers a setCommit method. The
default behavior is that a commit is performed for all database activities (as if
setCommit( true ) was called). If you invoke setCommit( false ), then a
commit will not be issued.
Since you supply the JDBC connection object used by the persistence operator
(via java.sql.Connection parameter of the IMBInstance.createSQLAdapter
method), you can also control the commit behavior by supplying a connection
object for which autoCommit has been turned on. If autoCommit is on, database
activities are implicitly committed, regardless of the setting of
ISQLAdapter.setCommit.
7-11
Sample code
This sample code shows inserting a message:
// User has an MBInstance
IMBInstance mbInst = ;
// User has an open JDBC connection
Java.SQL.Connection conn = ;
// User has a message object to be persisted
IMBMessage msg = ;
// User has a Vector in which the custom column values are held
Vector myCustomColumns;
ISQLAdapter sql;
IMBSQLMessage sqlMsg;
try {
sql = mbInst.createSQLAdapter( conn );
sqlMsg = MBSQLMessageFactory.createSQLMessage( msg, 12345
);
sqlMsg.setCustomColumns( myCustomData );
sql.insert( adapterSetName, sqlAdapterTemplateName, sqlMsg );
} catch( MBException ex ) {
// do error handling
}
This sample code shows selecting a message:

// User has the message id of the message to be selected
String messageID = ABC12345;
ISQLAdapter sql;
try {
sqlMsg = sql.select( adapterSetName, sqlAdapterTemplateName,
msgId );
}
7-12
This sample code shows updating a message:

// User has a message object to be persisted
IMBMessage msg = ;
// User has a Vector in which the custom column values are held
Vector myCustomColumns;
ISQLAdapter sql;
try {
sqlMsg = MBSQLMessageFactory.createSQLMessage( msg, 12345
);
sqlMsg.setCustomColumns( myCustomData );
sql.update( adapterSetName, sqlAdapterTemplateName, sqlMsg );
}
This sample code shows deleting a message:

// User has the message id of the message to be deleted
String messageID = ABC12345;
ISQLAdapter sql;
try {
sql.delete( adapterSetName, sqlAdapterTemplateName, messageID
);
}
7-13
Executing a flow
Executing a flow
The IFlow interface contains methods to execute a flow, retrieve the output of a
flow and retrieve any error that occurs during the execution of a flow.
Use the IMBInstance.createFlow method to create a flow instance.
Flow
7-14
Interface
Interface
com.ffusion.msgbroker.interfaces.IFlow
8
Using Message Broker Server
About this
chapter
This chapter introduces the Message Broker Server and how it is used to execute
flows. It also discusses how to monitor, stop and start Message Broker Server
from the Message Broker Manager. The Message Broker run-time API is also
provided.
Topics include:
What is the Message Broker Server? (p. 8-2)
Using Message Broker Manager (p. 8-4)
The Message Broker Server run-time API (p. 8-5)
Message Broker Server examples (p. 8-6)
Getting started
1. For an overview of Message Broker Server, see What is the Message Broker
Server? on page 8-2.

2. To start and use Message Broker Server from the Message Broker Manager,
review Using Message Broker Manager on page 8-4.

3. For a description of the run-time API, see The Message Broker Server run-
time API on page 8-5.

4. To see samples of the Message Broker Server, see Message Broker Server
examples on page 8-6.
8-1
What is the Message Broker Server?

The Message Broker Server is a run-time environment that you can use to execute
Flows. The Message Broker Server consists of the following components:
Message Broker Server core

An EJB run-time API
A graphical user interface used to start and stop the Message Broker
Server
The following sections discuss how to start Message Broker Server and execute
flows.
Using Message Broker Server on page 8-2

Executing flows on page 8-3

The Message Broker Server runs inside of an EJB application server. Before it can
be used to run flows, the host application server must be started. Once started,
you can begin using Message Broker Server. For details on starting and using the
server see the following sections:
Starting the Message Broker Server below
Executing flows on page 8-3
Starting the Message Broker Server

To start and stop the Message Broker Server, use the following procedures.
NOTE: If you are using WebSphere, consult the readme.txt in
%MB60INSTALLDIR%\MBServer for steps to start and stop the Message
Broker Server.
To start the Message Broker Server:

On the machine that is hosting the server, run:
On Windows:
%MB60INSTALLDIR%\MBServer\bin\startMBServer.bat
On Solaris:
$MB60INSTALLDIR/MBServer/bin/startMBServer.sh
8-2
To stop the Message Broker Server:

On the machine that is hosting the server, run:
On Windows:
%MB60INSTALLDIR%\MBServer\bin\stopMBServer.bat
On Solaris:
$MB60INSTALLDIR/MBServer/bin/stopMBServer.sh
Executing flows
After the host application server is started, you can begin using the Message
Broker Server by invoking methods on the Message Broker Server Admin EJB. For
details, see The Message Broker Server run-time API on page 8-5.
The first step when executing flows is to start the Message Broker Server instance
by calling the startServer() method. The server instance needs to connect to a
Message Broker run-time repository the repository connection information is
specified in the call to startServer(). Once the server instance is started, you call
initializeFlow() to create a flow instance. This method returns a flow instance ID
that you use to reference the flow instance in subsequent API calls. A flow instance
is not bound to a specific flow; it can be used to execute several different flows.
NOTE: A flow instance can only be used by one client at a given time. If several clients
need to execute flows simultaneously, they must each initialize their own flow
instance.
You can now use the flow instance to execute a flow. If the flow requires input
parameters (which are specified by the flowSource element in the flow XML),
then you make a call to setFlowContext() to set the input values. Once these
required inputs have been set, you execute the flow by calling executeFlow() or
executeFlowNoWait(). In the case of executeFlow(), the method blocks until the
flow execution is complete. If the execution completed without error, the method
returns a HashMap containing the output parameters (as specified by the
flowSink element in the flow XML) from the flow.
If executeFlowNoWait() was called, the method returns immediately and you must
call getFlowStatus() to determine when the flow execution has completed. Once
this execution is complete, you can obtain the flow output by calling
getFlowOutput().
8-3
Using Message Broker Manager
A client would call executeFlowNoWait() instead of executeFlow() when there is a

need to execute several flows simultaneously from the same client thread or when
there is a potential for the EJB call to timeout due to long-running flows.
When you use a flow instance to execute the same flow repeatedly, the values in
the flow execution context from the previous execution remain in the context for
the next flow execution. If you want to reset the flow execution context between
flow executions, you should call setFlowContext() before each call to execute the
flow.
Using Message Broker Manager

You can use the Message Broker Manager to monitor, start, and stop Message
Broker Server instances, as described in the sections below.
To connect to a Message Broker Server:
1. Start the Message Broker Manager.
2. Select Tools > Connect. You will be prompted to choose a plug-in for the
connection.
3. Select Message Broker Server.
4. Enter the connection information for the application server that is hosting the
Message Broker Server you want to connect to and click OK.
Once connected to the Message Broker Server you can monitor its status on the
right side of the screen as well as start and stop the server instance.
To start a Message Broker Server:
1. Right-click on the server you wish to start.
2. Select Start and enter the connection information for the Message Broker
run-time repository. Click OK.
To stop a Message Broker Server:

1. Right click on the server you wish to stop.
2. Select Stop.
8-4
The Message Broker Server run-time API
To disconnect from a Message Broker Server:

1. Select Tools > Disconnect.
2. Select the server and click Disconnect.
The Message Broker Server run-time API

The Message Broker Server offers an EJB-based run-time API that allows you to
start and stop the server and execute flows.
For detailed API information, see the following area of the Javadocs:
Message Broker Server
Package
com.ffusion.msgbroker.server.adminEJB
In order to use the Message Broker Server Run-time API, your client application
needs to import the com.ffusion.msgbroker.interfaces and
com.ffusion.msgbroker.server.adminEJB packages. You also need to include the
following in the classpath:
%MB60INSTALLDIR%\server\mbserv60.jar
%MB60INSTALLDIR%\MBServer\<appServer>\client\MBServerAdminClient.
jar
where <appServer> is one of the following: EAServer, WebLogic, or WebSphere.

%MB60INSTALLDIR%\runtime\<repositoryName>.jar
Any application server specific Jar files or classes that are required in order to
connect to the application server.
NOTE: If the repository was deployed from a different machine than the one running
the Message Broker Server, you must manually transfer the run-time Jar file
(%MB60INSTALLDIR%\runtime\<repositoryName>.jar) over to the machine
that is running the Message Broker Server.
8-5
Message Broker Server examples

This section contains two examples on using the Message Broker Server. The first
example demonstrates sending a FIX message to GlobalFIX after it has been
parsed and validated by Message Broker. The second example demonstrates
retrieving a FIX message from a JMS queue and sending it to GlobalFIX. These
examples are described in the following sections:
Parse and validate to GlobalFIX on page 8-6
JMS queue to GlobalFIX on page 8-10
Parse and validate to GlobalFIX

This section shows a sample Flow that takes in a FIX message string as an input
and invokes the Message Broker parse and validate operators on it before sending
it to GlobalFIX. Assume that the Message Broker Server has been started
(through the GUI or through the API) and you have a FIX message string in a
variable called "myMessageString." Further, assume you have a Flow Set defined
called "MyFIXFlowSet" and that defined within that Flow Set is a Flow called
"MyFIXSendFlow."
NOTE: The following is sample code only and does not include checking for errors and
exceptions.
1. Get a reference to the Message Broker Server Admin EJB:

ctx = getInitialContext(url, user, password, jndiFactory);
home = (MBSAdmin) ctx.lookup( "MBServer/MBSAdmin" );
mbsbean = home.create();
2. Invoke the initializeFlow method to create a Flow Instance:

String flowInstanceID = mbsbean.initializeFlow();
3. Infuse the message string into the execution context of the Flow Instance:
sendOptions = new Properties();
sendOptions.setProperty( "sessionID", "Counter-party" );
context = new Vector();
context.add( myMessageString );
context.add( sendOptions );
context.add( "FIX41" );
mbsbean.setContext( flowInstanceID, context );
8-6
4. Execute the Flow and wait for its completion:

HashMap flowOutput;
flowOutput = mbsbean.executeFlow( flowInstanceID, "MyFIXFlowSet",
"MyFIXSendFlow" );
Alternatively, you could execute the Flow without waiting for its execution to
complete. In this case, you would perform the following actions:
1. Get a reference to the MB Server Admin EJB:
ctx = getInitialContext(url, user, password, jndiFactory);
home = (MBSAdmin) ctx.lookup( "MBServer/MBSAdmin" );
mbsbean = home.create();
2. Invoke the initializeFlow method to create a Flow Instance:

String flowInstanceID = mbsbean.initializeFlow();
3. Infuse the message string into the execution context of the Flow Instance:
sendOptions = new Properties();
sendOptions.setProperty( "sessionID", "Counter-party" );
context = new Vector();
context.add( myMessageString );
context.add( sendOptions );
context.add( "FIX41" );
mbsbean.setContext( flowInstanceID, context );
4. Execute the Flow (without waiting for its completion):

mbsbean.executeFlowNoWait( flowInstanceID, "MyFIXFlowSet",
"MyFIXSendFlow" );
5. At this point, you would occasionally poll to see if the Flow has completed.
6. Once complete, retrieve the output of the Flow:
MBSFlowStatusInfo flowStatus;
flowStatus = mbsbean.getFlowStatus( flowInstanceID );
if( flowStatus.flowState == IMBFlowState.MBS_FLOWSTATE_COMPLETED
)
{
// The Flow is done. Get the output.
HashMap flowOutput;
flowOutput = mbsbean.getFlowOutput( flowInstanceID );
}
8-7
The Flow itself would be defined as follows. The Flow parses the message (in
preparation for the next step), validates the message, and then sends the message
to GlobalFIX.
<flowModel name="MyFIXSendFlow">
<flowSource name="ParseFIX">
<input name="fixString">
<input name="sendOptions" type="Properties">
<input name="messageSetName">
</flowSource>
<flowSink name="SendFIX">
<output name="messageReference">
</flowSink>
<serviceProviderType name="GFIX" type="EJB" >
<property name="jndiName" value="FIX/IAdapter" />


<activity name="ParseFIX">
<input name="fixString"/>
<input name="messageSetName"/>
<output name="fixMessageObject"/>
<fault name="mbparseError"/>
operation="parse"/>
</activity>

<activity name="ValidateFIX">
<input name="fixMessageObject"/>
8-8
<fault name="mbValidateError"/>
</activity>

<activity name="SendFIX">
<input name="sendOptions">
<output name="messageReference"/>
<fault name="fixSendError"/>
<implement serviceProviderType="GFIX"
operation="send"/>
</activity>
<controlLink
source="ParseFIX"
target="ValidateFIX">
<controlLink
source="ValidateFIX"
target="SendFIX">
</flowModel>
8-9
JMS queue to GlobalFIX

This section shows a sample Flow that takes messages from a JMS queue and sends
them to GlobalFIX. The APIs used to invoke this Flow are the same as shown in
the previous example. Since loops are implemented as Sub-Flows, two Flows need
to be defined. The first flow is the top-level Flow containing the loop and the
second represents the body of the loop. The loop continues until the body of the
loop encounters an error or there are no messages left to process after a certain
period of time.
<flowModel name="ProcessJMSQueue">
<flowSource name="JMSLoop">
</flowSource>
<flowSink name="JMSLoop">
</flowSink>

<activity name="JMSLoop"
exitCondition="fixString == null" >
<input name="JMSFlowSet" />
<input name="ProcessOneMessage" />
<output name="fixString">
<fault name="mbsException" />
<implement serviceProviderType="Internal"
operation="execute"/>
</activity>
</flowModel>
<flowModel name="ProcessOneMessage">
<flowSource name="ReadJMSQueue">
</flowSource>
8-10
<flowSink name="SendFIXMessage">
<output name="fixString">
</flowSink>
<serviceProviderType name="GFIX" type="EJB" >
<property name="jndiName" value="FIX/IAdapter" />
<serviceProviderType name="myJMSProvider" type="JMS" >
<property name="userName" value="userName" />
<property name="connectionFactoryName"
value="ConnectionFactoryJNDIName" />
<property name="queueName" value="FIXQueueJNDIName" />
<property name="queueUserName" value="queueUserName" />
<property name="queuePassword" value="queuePassword" />
<property name="transacted" value="false" />
value="Session.AUTO_ACKNOWLEDGE" />
<property name=messageSelector" value="JMSType = 'FIX'" />


<activity name="ReadJMSQueue">
<output name="fixString"/>
<fault name="jmsError"/>
<implement serviceProviderType="myJMSProvider"
</activity>
8-11


<activity name="SendFIX">
<output name="messageReference"/>
<fault name="fixSendError"/>
<implement serviceProviderType="GFIX"
operation="send"/>
</activity>
<controlLink
source="ReadJMS"
target="SendFIX"
transitionCondition="fixString != null">
</flowModel>
8-12
9
IDL/Java message
representation
About this
chapter
This chapter discusses how to define message formats, map for various data types
and fields, and view generated Java and IDL code.
Topics include:
Overview (p. 9-3)
Location of generated files (p. 9-3)
Mapping for message bodies, headers, and trailers (p. 9-5)
Mapping for atomic types (p. 9-6)
Mapping for enumerations (p. 9-7)
Mapping for composite types (p. 9-12)
Mapping for unions (p. 9-13)
Mapping for user-defined types (p. 9-14)
Using optional fields (p. 9-15)
Mapping of repeated fields (p. 9-15)
Mapping for SQL Type (p. 9-16)
Viewing generated Java and IDL code (p. 9-17)
9-1
Getting started
Getting started
1. For details of what happens at deployment time, see Overview on page 9-3.
2. For the location of IDL-generated files, see Location of generated files on
page 9-3.
3. To map message bodies, headers and trailers to IDL structures or Java classes,
review Mapping for message bodies, headers, and trailers on page 9-5.
4. For a list of primitive types supported by Message Broker and their
equivalents in IDL and Java, see Mapping for atomic types on page 9-6.
5. For an overview of enumerations, see Mapping for enumerations on page 9-
7.
6. For an overview of composite types and how they group related fields
together, review Mapping for composite types on page 9-12.

7. For an overview of unions, see Mapping for unions on page 9-13.
8. For details on user-defined types, see Mapping for user-defined types on
page 9-14.
9. For information on optional fields, see Using optional fields on page 9-15.
10. To learn about repeated fields, see Mapping of repeated fields on page 9-15.
11. For a list of the data types supported by Message Broker. see Mapping for
SQL Type on page 9-16.

12. To use Message Broker Manager to view the generated code for message
types and fields, review Viewing generated Java and IDL code on page 9-17.
9-2
IDL/Java message representation
Overview
Overview
At run time, Message Broker represents message instances using standard IDL and
Java. At deployment time, Message Broker creates IDL modules to define the
format of messages and fields, then compiles these into Java classes that can be
manipulated in user applications. If you are using EAServer components to process
messages, you can use the generated IDL modules to define the component
interfaces using message objects as parameters and return values.
Message Broker defines message formats using the IDL primitive types, structures,
and enumerations. The Java representation follows the standard IDL/Java type
mappings and applies to parameter and return types in Enterprise JavaBean
methods.
To learn how to deploy message collections to a run-time repository, refer to
Deploying to the run-time repository on page 3-51. You must deploy a
collection to generate the IDL and Java types that represent messages in the
collection.
Location of generated files

When you deploy a message set in the Message Broker Manager, Message Broker
creates IDL and Java source for the message fields, then compiles the Java source.
Using generated IDL

Message Broker creates IDL definitions in the
runtime/MessageBroker directory in your Message Broker installation.
All IDL declarations related to a message set are declared in the IDL module with
the same name as the set, for example, for the message set called Customers,
Message Broker declares a Customers module in the file runtime/MessageBroker/
Customers.idl.
NOTE:
IDL is not generated for message sets marked as recursive because IDL does
not support self-referencing structures.
9-3
Location of generated files
Importing Generated IDL into a Sybase EAServer Installation

The generated IDL must be imported into your EAServer installation if you are
using message types as parameters or return types for EAServer component
methods. After modifying message formats and redeploying from the Message
Broker Manager, you can repeat this procedure to re-import the updated IDL into
EAServer.
To import IDL into Sybase EAServer:
1. Copy the IDL file for your message set into the EAServer repository
subdirectory.
2. Restart the server.
Using generated Java

Java classes for message formats are generated to the following package where Set
is the name of the message set:
com.ffusion.msgbroker.generated.MessageBroker.mdf.Set
Each time you deploy from the Message Broker Manager, Message Broker compiles
the generated classes and adds them to the run-time Java Archive (JAR) file,
runtime/<repositoryName>.jar. (Note that <repositoryName> is a placeholder for
the name of the repository. For example, if the default repository name of
"MessageBroker" is used, the name and location of the Jar file would be runtime/
MessageBroker.jar.) Add this file to the CLASSPATH environment variable for your
applications.
When you define and deploy a SQL Adapter template, Message Broker generates
Java class methods that allow you to insert, select, update, or delete a message.
Message Broker compiles the generated classes and adds them to the run-time
JAR file, runtime/<repositoryName>.jar in the Message Broker installation directory.
9-4
Mapping for message bodies, headers, and trailers
Mapping for message bodies, headers, and trailers

Each message set can have one header definition, one trailer definition, and
multiple message body definitions.
IDL definitions for message headers, bodies, and trailers

Message headers and trailers map to IDL structures named TypeHeader and
TypeTrailer, as in the following example:
struct TypeHeader
{
... header fields ...
};
struct TypeTrailer
{
... trailer fields ...
};
The header and trailer fields follow the mappings for the primitive types,
composite types, unions, and enumerations described in this chapter. A message
body maps to an IDL structure. If the message set has a header, the first field in the
structure refers to the message header. If the message set has a trailer, the next
field refers to the message trailer. The remaining fields follow the mappings for
primitive types, composite types, unions, and enumerations.
The mapping for a message AddCustomer that has both a header and trailer is as
follows:
struct TypeAddCustomer {
TypeHeader header;
TypeTrailer trailer;
... message body fields ...
};
9-5
Mapping for atomic types
Java classes for message headers, bodies, and trailers

Message headers and trailers map to Java classes named TypeHeader and
TypeTrailer, respectively. Each field in the header or trailer maps to a public Java
class member, declared according to the mappings for primitive types, composite
types, unions, and enumerations. The class has a public constructor that takes no
parameters and a public constructor that takes one parameter for each field, in the
ordinal order of the message fields, or example, if the message header has a single
string field named msgType, the generated Java class is as follows:
public class TypeHeader {
public String msgType;
public TypeHeader() { ... }
public TypeHeader(String msgTypeValue) { ... }
}
Mapping for atomic types

The table below lists the primitive types supported by Message Broker and their
equivalents in IDL and Java. For more information on various atomic types,
Mapping SQL types to Message Broker field types on page 3-14.
9-6
Display type
name
IDL type
Java type
string
string
java.lang.String
date
string
java.lang.String
All date values are formatted as strings
according to the format specifier for the field.
You can use the methods in the JDK
java.text.SimpleDateFormat class to convert
java.util.Date instances to formatted strings
and vice-versa.
bytes
sequence <octet>
byte[]
boolean
boolean
boolean
int16
short
short
int32
long
int
int64
long
long
float32
float
float
double64
double
double
Mapping for enumerations

Enumerations in Message Broker specify a value type and a set of allowable values.
An enumeration can be a base-type representation or an IDL enumeration
representation.
Base-type representation: Message Broker uses the base type of the
enumeration to represent the field in the IDL/Java representation, for
example, if the base type of the enumeration is string, the Java representation
uses the class java.lang.String and the IDL representation uses the IDL string
type.
IDL enumeration representation: Message Broker declares an IDL
enumeration and the field in the IDL/Java representation uses the IDL
enumeration type or the equivalent Java class.
The base-type representation is easier to use if your application requires the field
value in its base-type representation. The IDL enumeration representation is
easier to use if your application contains logic to branch to different execution
paths based on the field value, for example, a Java switch statement. For either
representation, Message Broker generates an additional Java class named
ValueSetEnumerationName, where EnumerationName is the name of the Message
Broker enumeration.
The definition of enumerated fields in the Message Broker Manager determines
which representation is used at run time. To use the IDL enumeration
representation, choose Enumeration for the Represent field data as setting. To use
the base-type representation, choose the Represent field data as setting as the
base type for the enumeration. In either case, you must specify the enumeration
name in the Enumeration drop-down list.
9-7
Using the IDL enumeration representation

In IDL, enumerations are represented by an IDL enumeration declaration, for
example, an enumeration named Colors with base type integer has the following
members declared in the Message Broker Manager:
Member name
Value
red
yellow
purple
In IDL, the enumeration is declared as:

enum EnumColors (red, yellow, purple);
In Java, each Message Broker enumeration maps to a class with the following
structure:
public final class EnumEnumeration {
// One pair for each member_name in the IDL enum.
// The integer sequence_value constants have no
// relation to values in the Message Broker
// enumeration.
public static final int _member_name = sequence_value;
public static final Enumeration member_name = new Enumeration
( _member_name );
// Return integer code for current value
public int value() {...}
// Return an enum for a specified sequence_value
public static Enumeration from_int(int sequence_value);
// Constructor is private
private Enumeration(int) { ... }
}
The Java class has the name EnumEnumeration, where Enumeration is the name of
the Message Broker enumeration type. For each member in the enumeration, the
Java class has two members. One refers to the integer constant that corresponds
to the member name, and the other refers to an instance of the enumeration class
9-8
that represents that value, for example, a member named purple in an

enumeration Colors maps to the following declarations:
public static final int _purple = 1;
public static final EnumColors purple = new EnumColors(_purple);
To use enumeration values in switch statements, use the field that is prefixed with
an underscore as shown in the following example:
switch (myEnum.value()) {
case Colors._purple:
... do something ...\
};
To refer to an instance with a specific value, use the field with the same name as
the desired member, for example, the following statement returns an instance of
the Colors enumeration with value purple:
Colors thePurpleOne = EnumColors.purple;
NOTE:
With Enum usage, the integer constant for each member name is determined
when the IDL is compiled into Java. Constants are shown here only for
example. Do not code enumeration constants into your programs. If you do not
have any fields in a message set that use the IDL enumeration, Message
Broker does not generate the EnumEnumeration Java class.
ValueSet<Enumeration> Java class

Whether you are using base-type or IDL enum representation, an additional Java
class is generated that allows you to verify if a value is in the enumerations set of
generated Java values, for example, for an enumeration named Colors with type
string, the class ValueSetColors is generated and contains the following method:
public static boolean contains (String value);
You can call the contains method to check whether a value is in the enumeration's
set of allowable values, for example, the following code might be used in a
validation or routing rule to refer to the value set class generated for an
enumeration named ServiceType:
if( !ValueSetServiceType.contains( theField ) ) {
return false;
}
return true;
9-9
NOTE:
When invoking the parser or builder, Message Broker validates enumerated

fields automatically. You can use code, as shown in the example, to explicitly
validate fields that are not declared to use an enumeration.
Lookup of enumeration member values at run time

The following method in the enumeration ValueSet<Enumeration> class facilitates
retrieval of the value associated with an enumeration member:
public static <enumDataType> getValue( int index );
where <enumDataType> is the base data type of the enumeration, such as string,
16-bit integer, and so on. Invoking getValue (index), where index is the integer
constant associated with the enumeration member, returns the value associated
with that member. The integer constant for the enumeration member can be
retrieved by calling the value( ) method on the Enum<Enumeration> object.
For example, consider the enumeration Colors defined previously of base type
integer with the following member/value pairs:
Member name
Value
red
yellow
purple
After parsing a message containing enumerated atomic fields of type EnumColors,

there will be an EnumColors instance for each of the parsed fields. To find the value
associated with an instance, you need to obtain the integer constant for the
instance and use it to invoke the static getValue( ) method on the ValueSetColors
class:
EnumColors instanceEnumColors = ; //parsed enum instance
int color = ValueSetColors.getValue( instanceEnumColors.value()
);
The variable color would contain one of the values from the Color
enumerations value set {1, 2, 3}.
9-10
Lookup of Enumeration Member Indices at Run Time

The following method in enumeration ValueSet<Enumeration> allows retrieval of
the integer constant associated with an enumeration member, given the value of
the member:
public static int getIndex( <enumDataType> value );
where <enumDataType> is the data type of the enumeration, such as string, 16-bit
integer, and so on. This method performs the opposite functionality to the
ValueSet<Enumeration>.getValue( ) method described previously.
Invoking getIndex(Value), where Value is an entity in the enumerations value set, will
return the integer constant for the enumeration member that is associated with
the given value. Using the integer constant, you can obtain an Enum<Enumeration>
object by calling the static from_int() method on the Enum<Enumeration> class.
The getIndex() method together with getValue() is useful for mapping between two
different enumerations, such as within a transformation.
As an example, consider the previous enumeration Colors of data type integer and
with the following member/value pairs:
Member name
Value
red
yellow
purple
Also consider a second enumeration, RoadsterColors, also of base data type

integer and representing acceptable colors for a fast and flashy roadster:
Member name
Value
RocketRed
MellowYellow
To map from Colors to RoadsterColors, you could use the following code:
EnumColors instanceEnumColors = ; // parsed enum instance
EnumRoadsterColors instanceEnumRoadsterColors =
EnumRoadsterColors.from_int(
ValueSetRoadsterColors.getIndex(
ValueSetColors.getValue(
InstanceEnumColors.value() ) );
9-11
Mapping for composite types
After doing this, you can also find the value associated with the new enumeration
instance as follows:
integer roadsterColor = ValueSetRoadsterColors.getValue
(instanceEnumRoadsterColors.value() );
NOTE:
The value 3 that represents the color purple in the Colors enumeration is not
part of the value set for the enumeration RoadsterColors. Calling getIndex()
with an invalid value such as this will result in a
java.lang.IllegalArgumentException being thrown.
Mapping for composite types

Message Broker composite types group related fields together. For example, you
might define an address type that includes fields for street number, city, state,
postal code, and country.
IDL mapping
In IDL, composite types map to a structure declared as
struct TypeCompositeName {
... field declarations ...
};
In this structure, CompositeName is the name of the composite field or userdefined composite type. The field declarations follow the mappings for primitive
types, composite types, unions, and enumerations. Each field maps to a field of the
same name in the IDL structure.
Java mapping
In Java, each composite type maps to a Java class declared as follows:
public class TypeCompositeName {
public TypeCompositeName();
public TypeCompositeName( Type1 field1, Type2 field2, ... );
}
CompositeName is the name of the composite field or user-defined composite

type. The field declarations follow the mappings for primitive types, composite
types, unions, and enumerations. Each field maps to a public field of the same name
9-12
Mapping for unions
in the Java class. The class has a default constructor and a constructor that takes a
parameter for each field in the composite, in the ordinal order of the composite.
Mapping for unions

Message Broker unions are similar to composite types, but only one field in a
union can be set. Unions are useful when a message field may contain multiple data
types. Unions have an indicator field that specifies which member has been set and
can optionally have a pre-value tag.
Mapping in IDL
In IDL, unions are mapped to a structure with the following fields:
struct TypeUnionName {
string __preValueTag;
string __memberName;
}
UnionName is the name of the union field or user-defined union type. The
_preValueTag field is filled in when the active union member has a pre-value tag
defined in the Message Broker Manager. If the active member does not have a prevalue tag, then the parser will simply leave the field with a null value. The IDL field
holds the corresponding string value for each tag. The __memberName name field
indicates the name of the active union member. The remaining fields follow the
mappings for primitive types, composite types, unions, and enumerations. Each
field in the Message Broker union maps to a field of the same name in the IDL
structure.
Mapping in Java
In Java, unions are mapped to a class with the following declarations:
public class TypeUnionName {
public String __preValueTag;
public String __memberName;
public TypeUnionName();
public TypeUnionName( String preValueTag, String memberName,
type1 field1, type2 field2, ...);
}
9-13
Mapping for user-defined types
UnionName is the name of the union field or user-defined union type. The
_preValueTag field is filled in when the active union member has a pre-value tag
defined in the Message Broker Manager. If the active member has no pre-value tag,
then the parser will leave the field with a null value. The Java field holds the
corresponding string value for each tag. The _memberName field indicates the
name of the active union member.
The remaining fields follow the mappings for primitive types, composite types,
unions, and enumerations. Each field in the Message Broker union maps to a public
field of the same name in the Java class. The class has a default constructor and a
constructor that takes parameters for the pre-value tag, member name field, and
each field in the Message Broker union. You can pass a value for the field being set
and null for all other fields.
NOTE:
For calls to MBMessageFactory.createIDLMessage, or when constructing

or initializing a union in transformation code, you must set the _memberName
field. You dont need to set the _preValueTag field.
Mapping for user-defined types

User-defined types provide an abstraction for another type, similar to typedefs in
C or C++. User-defined types are useful when several message fields have the
same structure and formatting requirements. When a user-defined type is used for
a message or structure field, the mapping depends on the type that is abstracted,
as follows:
If the user-defined type is an abstraction of the atomic types listed in
Mapping for Atomic Types on page 6, the field uses the mapping for the
atomic type, for example, if the user-defined type is a string, the Java class field
is type java.lang.String.
If the user-defined type is an abstraction of an enumeration, the field uses the
mapping for the enumeration. The generated IDL structure and Java class
have the name of the user-defined enumeration, for example,
TypeMyEnumeration, where MyEnumeration is the user-defined enumeration
type.
If the user-defined type is an abstraction for a composite or union, the field
uses the mapping for the composite or union. The generated Java class and
IDL structure have the name of the user-defined type, for example,
TypeMyUnion, where MyUnion is the user-defined type.
9-14
Using optional fields
Using optional fields

For each optional atomic field, Message Broker adds a boolean variable fieldExists
to the Java class that represents the message or composite type, where field is the
name of the optional field.
Default values
If a message or composite field uses an optional field with an atomic data type, you
can specify a default value for the field in the Message Broker Manager. When
parsing messages with optional fields, Message Broker uses the default value when
the field is not present in the message data. To determine whether the value of an
optional field was actually supplied in the message data, test this variable.
Mapping of repeated fields

If a message uses a repeated field, the Java class representing the message type uses
an array to represent the repeated field. The base type of the Java array follows the
mappings for primitive types, composite types, unions, and enumerations.
9-15
Mapping for SQL Type
Mapping for SQL Type

The table below lists the data types supported by Message Broker and their
equivalents in ASA, ASE, Oracle, and DB2.
9-16
MB Data
Type
ASA Type
ASE Type
Oracle Type
DB2 Type
STRING
TEXT if 32767
characters, or
VARCHAR if
not fixed length,
or CHAR if
fixed length. If
length is
unknown,
default to
VARCHAR 255.
TEXT if 255
characters, or
VARCHAR if
not fixed
length, or
CHAR if fixed
length. If length
is unknown,
default to
VARCHAR
255.
CLOB if 2000
characters, or
VARCHAR if
not fixed
length, or
CHAR if fixed
length. If length
is unknown,
default to
VARCHAR
255.
CLOB if 4000
characters, or
VARCHAR if
not fixed
length, or
CHAR if fixed
length. If length
is unknown,
default to
VARCHAR
255.
BYTES
IMAGE if 32767
bytes, or
VARBINAry if
not fixed length,
or BINARY if
fixed length.
IMAGE if 255
bytes, or
VARBINAry if
not fixed
length, or
BINARY if fixed
length.
BLOB if 2000
characters or
RAW.
BLOB
BOOLEAN
SMALLINT
SMALLINT
SMALLINT
SMALLINT
INT16
INTEGER
INTEGER
INTEGER
INTEGER
INT32
INTEGER
INTEGER
INTEGER
INTEGER
INT64
DECIMAL (20,
0)
DECIMAL (20,
0)
DECIMAL (20,
0)
DECIMAL (20,
0)
FLOAT32
REAL
REAL
REAL
REAL
DOUBLE64
DOUBLE
DOUBLE
DOUBLE
DOUBLE
DATE
Same as String
Same as String
Same as String
Same as String
ENUM
SMALLINT
SMALLINT
SMALLINT
SMALLINT
Viewing generated Java and IDL code

You can view the generated code for message types and fields in the Message
Broker Manager. You cannot view generated code unless you have deployed a
message collection at least once.
Viewing Java code

You can view Java code for any entity that maps to a Java class, including message
bodies, message headers, message trailers, composites, unions, and enumerations.
The Message Broker Manager displays the source for the class in a read-only text
viewer.
To view Java code:
1. Highlight the icon for the entity of interest.
2. Choose File > View Java.
NOTE:
For an enumeration, you can also view the Java code for the generated
value set class. Choose File > View Value Set Java.
Viewing IDL code

Each message collection in the Message Broker Manager maps to one IDL module.
To view IDL code:
1. Highlight the icon for the message collection.
2. Choose File > View IDL.
9-17
9-18
A
Javadoc
About this
chapter
This appendix provides you with the information to effectively use the Javadocs for
Message Broker.
Using the Message Broker API documentation

The Message Broker API documentation (javadocs) is provided as HTML files for
online use. The files are available under the /docs directory on your installation CD.
What Financial Fusion provides

Financial Fusion provides API documentation for the Message Broker run-time and
Message Broker Server run-time APIs.
Accessing the API documentation

You can display the Message Broker API documentation by setting up and using a
shortcut to it on your desktop. When you click your shortcut, the API
documentation displays an overview of the Message Broker run-time API and
Message Broker Server run-time API packages.
A-1
Using the Message Broker API documentation
Viewing the API documentation

You can view the Message Broker API documentation in several ways.
Using the left frame
In the left frame, you can select:

All Classes to display the list of all classes
A package to display a list of classes in that package, and then choose one of
those classes for display
Notice that when a class is selected in the left frame, the word Class is selected in
the navigation bar at the top of the right frame.
Using the right frame
In the right frame, you can select items on the navigation bar at the top to see
various views.
A-2
Javadoc
Index
adapter collections
adding 3-45
adapter set
adding 3-45
adding
fields 3-6
members to enumerations 3-24
message sets 3-5
routing collections 3-34
routing rules 3-35
routing set 3-35
transformation collections 3-40
transformation sets 3-40
transformations 3-41
XML-based message sets 3-11
API templates
creating 5-1
deploying 5-7, 5-8
macros 5-6
modifying 5-4
overview of 1-10
properties 5-4
template editor 5-6
APIs
IBuilder 7-9
IMBMessageFactory 7-7
IParser 1-8, 7-5
IRouter 7-8
ITransformation 1-9, 7-9
IValidation 3-29, 7-8

reference pages for 6-27
using 7-1
applications
API usage in 7-1
developing 7-1
specifying message formats for 3-1
assign Java utility
transformation rules 3-43
atomic
field type 3-16
atomic fields
defining 3-16
atomic types
runtime datatypes for 9-6
B
begin field delimiter 3-22
begin tag delimiter 3-22
build number 2-9
C
code, generated
viewing in Sybase Central 9-17
composites
defining 3-16
runtime type mapping for 9-12
Connecting 2-4
connecting
IX - 1
Message Broker runtime repository

2-6
creating
Message Broker repositories 2-2
run-time repository 2-5
temporary repository connections
2-6
D
datatypes
atomic 9-6
composite 9-12
for runtime representation of messages 9-1
IDL 9-1
Java 9-1
mapping dialog 3-15
representing enumerations 9-7
representing unions 9-13
user-defined 9-14
Defining 4-9
defining
enumerations 3-23
explicit validation rules 3-31
field delimiters 3-6
field tags 3-6
headers 3-5
message set 3-3
message type indicator 3-7
messages 1-6, 3-6
trailers 3-6
validation rules 3-29
delimiters
defining 3-6
field 3-22
deploying
design information 1-5
to the runtime repository 2-9, 3-2,
3-51
design repository 2-2
IX-2
Index
disconnecting
Message Broker repositories 2-7
document type definition
DTD 4-1
XML 4-2
drag-and-drop features 3-26
DTD
mapping from 3-9
Message Broker 4-4
overview 4-1
XML 4-2
E
editing
routing rules 3-32
EJB
as a routing rule target 3-38
routing to 3-32
end field delimiter 3-22
enumerations 3-23, 4-8
adding members to 3-24
defining 3-23
guidelines for writing rules for 3-28
message set 3-4
runtime types to represent 9-7
explicit validation rules
defining 3-31
overview of 1-8
exporting
repository information to an XML
file 3-50
F
field characteristics
defining 1-7
field delimiters 3-22
field length
defining 1-6
field tags 3-22
field types
atomic, composite, union 3-16
fields
adding 3-6
adding to a message 4-8
atomic 3-16
composite 3-16
modifying 3-8
optional 9-15
picture code 3-21
union 3-16
fields, atomic
defining 3-16
fields, optional
default values for 9-15
G
generated code
guidelines
for writing rules 3-27
IMBMessageFactory
Java class 7-7
implicit validation rules
explanation of 1-8
importing
repository information from an XML
file 3-50
samples 2-7
insignificant white space
definition of 3-4
IParser
Java class 1-8, 7-5
IRouter
Java class 7-8
ITransformation
Java class 1-9, 3-39, 3-40, 7-9
IValidation
Java class 3-29, 7-8
J
Java
message instances 7-7
See also APIs
types to represent message data 9-1
H
handlers
for unknown fields 7-6
headers
defining 3-5
message set 3-3
run-time type mapping for 9-5
header-to-header
transformations 3-42
I
IBuilder
Java class 7-9
IDL
message instances 7-7
types to represent message data 9-1
IMBInstance
Java class 7-4
M
mapping
from the DTD to Message Broker 39
name and data type mapping dialog
3-15
MBInstanceFactory
Java class 7-4
Message Broker
definition of 1-1
DTD 4-1, 4-4
interface 1-5
samples 2-7
Message Broker Plug-in
registering 2-2
IX-3
message collections 2-2

adding 3-3
examples 4-4
message definition 1-6
message set 3-3
message instances
constructing 7-7
message routing 1-9
message set
adding 3-5
defining 3-3, 4-5
definition of 1-4
enumeration 3-4
header 3-3
message definition 3-3
non-XML based 3-5
trailer 3-3
type 3-5
XML-based 3-8, 3-11
message type indicator
defining 3-7
message validation 1-8
messages
building at runtime 7-7, 7-9
defining 3-6
defining structure of 1-6
parsing 1-8, 7-5
routing rules for 7-8
runtime representation of 9-1
transforming 1-9, 7-9
validating content of 7-8
modifying
fields 3-8
routing rules 3-36
O
optional fields
default values for 9-15
overriding
user-defined types 3-25
IX-4
Index
P
parsing
messages 1-8
runtime API for 7-5
text-encoded messages 7-5
picture code
field 3-21
post-value tag 3-22
pre-value tag 3-22
problems
reporting 2-9
R
registering
Message Broker Plug-in 2-2
repeat Java utility
repeated fields
reporting problems 2-9
repositories
connecting to the design-time repository 2-4
connecting to the runtime repository 2-6, 7-4
disconnecting 2-7
temporary connections 2-6
routing
example of 1-9
messages 1-9
runtime API for 7-8
to an EJB 3-38
adding 3-34
creating 3-32
routing rule 4-11
routing rules
adding 3-35
definition of 1-4
invoking at runtime 3-33, 7-8
modifying 3-36
target method for 3-35

routing set
adding 3-35
defining 3-32
rules
checking for enumerations 3-28
checking for optional fields 3-27
checking for repeated fields 3-27
guidelines 3-27
referencing the user data variable 328
run time
API functions 7-1
characteristics of 1-5
running the sample
building the sample 2-8
runtime
API usage 7-1
runtime environment 1-5
runtime repository 2-2
connecting to 7-4
deploying to 2-9, 3-2, 3-51
S
samples 2-7
building and running 2-8
importing sample definitions 2-7
of transformation rules 3-44
source message
transformation set 3-40
T
tags
defining 3-6
field 3-22
templates
EJB 5-7
IDL 5-7
templates, API
overview of 1-10
temporary
repository connections 2-6

text-encoded messages
parsing 7-5
trailers
body, message
run-time type mapping for 9-5
defining 3-6
message set 3-3
trailer-to-trailer
transformation 3-42
transformation
adding 3-41
header-to-header 3-42
overview 3-39
runtime API for 7-9
trailer-to-trailer 3-42
transformation collections
adding 3-40
transformation rules
assign Java utility 3-43
defining 3-41
definition of 1-5
editing 3-41
explanation of 1-9
invoking at runtime 7-9
repeat Java utility 3-43
sample 3-44
transformation sets
adding 3-40
source message 3-40
types, atomic
runtime datatypes for 9-6
types, composite
runtime type mapping for 9-12
types, user-defined
U
unions
as field type 3-16
defining 3-17
IX-5
unknown field
handler 3-4
unknown fields
handling 7-6
user data
guidelines for writing rules using 328
user-defined types 3-4, 3-24
overriding 3-25
validation rules for 3-31
V
valid documents
XML 4-2
validating
messages 1-8
validation
explicit 1-8
implicit 1-8
runtime API for 7-8
validation rules
defining 3-29
definition of 1-4
for user-defined types 3-31
invoking at runtime 3-29, 7-8
modifying 3-31
W
well-formed documents
XML 4-2
X
XML
document type definitions 4-2
DTD 4-2
importing and exporting from 3-50
importing definitions from 1-5
introduction 4-2
valid documents 4-2
well-formed documents 4-2
IX-6
Index
R
Reader Comment Form
About this form
We welcome your feedback on this publication. Your comments can be of great value
in helping us improve our information products.
Document Title
Version
Date
Please complete the following four steps:

1. Circle the numbers below that best represent your opinion of this
publication.
Ease of use
Accuracy
Clarity
5 = Excellent
Completeness
4 = Good
Organization
3 = Adequate
Appearance
2 = Fair
Examples
1 = Poor
Illustrations
0 = Not applicable
Question resolution
Overall satisfaction
2. Indicate the ways we could improve this publication.

Please provide details in the Comments section on the other side of this form.
Improve the table of contents
Add more/better quick reference aids
Improve the overview/introduction
Add more examples
Improve the organization
Add more illustrations
Improve the index
Add more step-by-step procedures
Make it less technical
Add more troubleshooting information
Make it more concise or brief.
Add more detail
3. Write any additional comments you may have below. If necessary, include
extra sheets with page numbers (where applicable).
4. If we may contact you concerning your comments, please complete the

information below.
Name
E-mail
Company
Address
Phone
Fax
Thank you for your evaluation of this publication. Your feedback is very important to
us. Choose one of the following methods to send us this information:
1. Fax this form to (519) 747-4971.
2. Mail it to:
Attention: Technical Publications

445 Wes Graham Way
Waterloo ON N2L 6R2
Canada
3. Contact Technical Publications by e-mail at: pubs@sybase.com

Message Broker Dev Guide

Uploaded by

Copyright:

Available Formats

Message Broker Dev Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Message Broker Dev Guide

Uploaded by

Copyright:

Available Formats

2

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

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

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

Message Broker Developers Guide and API Reference

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

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

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

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

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

Using flows ..................................................................................................... 6-1

Message Broker Developers Guide and API Reference

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

Using the Message Broker run-time API ................................................... 7-1

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

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

Javadoc .......................................................................................................... A-1

Message Broker Developers Guide and API Reference

Message Broker Developers Guide and API Reference

Welcome to Message Broker contains a complete overview of Message

Brokers features and functionalities.

Connecting to repositories and running the samples describes how to

Using the Message Broker design-time environment discusses the Message

Understanding the Message Broker DTD discusses the elements of the

deploying API templates.

sequences of message processing events without having to code directly to the

IDL/Java message representation discusses how to define message formats,

GlobalFIX Installation and Configuration Guide for individuals who

GlobalFIX Developers Guide and API Reference for software developers

GlobalFIX Feature Guide for end users, system administrators, and

Message Broker Developers Guide and API Reference

Sybase Retail Online Banking and Sybase Corporate Online Banking

components of Sybase Online Banking. These guides include system and

Developer Basics Guide for software developers who implement and

Sybase Corporate Online Banking Developers Guide for software

Sybase Retail Online Banking Developers Guide for software developers

Business Central Developers Guide provides application developers and

Business Central Feature Guide for end users, system administrators,

Business Central Administrators Guide for bank employees and other

Sybase Retail Online Banking Localization Guide for developers who

Javadoc the Sybase Online Banking API documentation (Javadoc) is

Online Help distributed with Corporate Banking, Consumer Banking,

Warehouse (BPTW) enables a financial institution to control the total

Bill Payment and Transfer Warehouse Developers Guide for software

Bill Payment and Transfer Warehouse Installation and Configuration

This guide includes information about system and database prerequisites,

One-to-One Marketing Message Manager Users Guide provides users

One-to-One Marketing Technical Reference for individuals who install

between multiple message formats and applications. Message Broker

Message Broker Developers Guide and API Reference

Message Broker Installation and Configuration Guide for software

Universal Alerts Engine Developers Guide and API Reference for

Universal Alerts Engine Feature Guide a brief overview of the features

About Sybase Online Banking

About Financial Markets Solutions

Sales and general inquiries

Message Broker Developers Guide and API Reference

Reader Comment Form

Sybase, an SAP Company

What is Message Broker?