Tib Adbt-prod Development

TIBCO ActiveMatrix Binding

Type for Adapters

Binding Development

Software Release 3.2

August 2012

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, The Power of Now, TIBCO Rendezvous, TIBCO Administrator, TIBCO Designer, TIBCO Runtime Agent, TIBCO Hawk, TIBCO Enterprise Message Service, TIBCO ActiveMatrix Service Grid, TIBCO ActiveMatrix Service Bus, TIBCO ActiveMatrix BusinessWorks Service Engine, TIBCO ActiveEnterprise, and TIBCO Business Studio, are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright 2010-2012 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

TIBCO ActiveMatrix Binding Type for Adapters Binding Development

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Changes from the Previous Release of This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

TIBCO ActiveMatrix Binding Type for Adapters Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Terms and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Usability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Transport and Wire Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Message Exchange Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Use Cases and Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 2 Developing an Adapter Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Generating WSDL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Generation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Migrating TIBCO ActiveMatrix 2.x Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Migration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Developing an Adapter Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27


iv | Contents

Creating a Distributed Application Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 3 Deploying the Distributed Application Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Deploying a Distributed Application Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Creating an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Distributing an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Configuring an Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Deploying an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 4 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Prerequisites for Running the Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Working with the Example for Generic Adapter Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Example Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Setting Up the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Deploying and Running the Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Testing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Working with the Example for TIBCO ActiveMatrix Adapter for Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Example Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Setting Up the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Deploying and Running the Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57


Figures | v

Figures

Figure 1 Matrix Publish Inbound (In-Only MEP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 2 Matrix Publish Outbound (In-Only MEP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Figure 3 Matrix Request/Response Inbound (In-Out MEP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Figure 4 Matrix Request-Response Outbound (In-Out MEP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Figure 5 TIBCO Business Studio Workbench Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Figure 6 Import TIBCO Designer Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Figure 7 Project Import Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Figure 8 Create a New Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Figure 9 Container Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Figure 10 Missing Schema or Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Figure 11 Generate WSDL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Figure 12 Import TIBCO ActiveMatrix 2.x Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Figure 13 Project Migration Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Figure 14 Create a Mediation Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Figure 15 Add an Adapter Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Figure 16 Binding Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Figure 17 Endpoint Configuration Details for JMS Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Figure 18 TIBCO ActiveMatrix Administrator Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figure 19 Map Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Figure 20 Properties List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Figure 21 Promoted Service Binding: GenericDemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Figure 22 Service Binding Endpoint Configuration: GenericDemo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Figure 23 Promoted Reference Binding: GenericDemo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Figure 24 Reference Binding Endpoint Configuration: GenericDemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Figure 25 Promoted Service Binding: SalesOrderDemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Figure 26 Service Binding Endpoint Configuration: SalesOrderDemo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Figure 27 Promoted Reference Binding: SalesOrderDemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Figure 28 Reference Binding Endpoint Configuration: SalesOrderDemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54


vi | Figures


Tables | vii

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Table 3 Project Import Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Table 4 Binding Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Table 5 Endpoint Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32


viii | Tables


| ix

Preface

TIBCO ActiveMatrix Binding Type for Adapters is an AMX binding that integrates a

legacy TIBCO adapter with the ActiveMatrix environment.

Topics

Changes from the Previous Release of This Guide, page x

Related Documentation, page xi

Typographical Conventions, page xii

Connecting with TIBCO Resources, page xv


x | Changes from the Previous Release of This Guide

Changes from the Previous Release of This Guide

This section itemizes the major changes from the previous release of this guide.

Add description about binding details including endpoint configuration details. See

Binding Details on page 30.

Update description and procedures about how to create, distribute, configure and

deploy an application. See Creating an Application on page 37.

Add one example for Generic Adapter Configurations. See Working with the Example

for Generic Adapter Configurations on page 45.


Preface | xi

Related Documentation

This section lists documentation resources you may find useful.

TIBCO ActiveMatrix Binding Type for Adapters Documentation

The following documents form the TIBCO ActiveMatrix Binding Type for Adapters

documentation set:

TIBCO ActiveMatrix Binding Type for Adapters Installation Read this manual for

instructions on site preparation and installation.

TIBCO ActiveMatrix Binding Type for Adapters Binding Development Read this

manual to familiarize yourself with the product and its use.

TIBCO ActiveMatrix Binding Type for Adapters Release Notes Read the release notes

for a list of new and changed features. This document also contains lists of known

issues and closed issues for this release.

Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCO products:

TIBCO Adapter SDK

TIBCO Designer

TIBCO ActiveEnterprise

TIBCO ActiveMatrix Administrator

TIBCO ActiveMatrix BusinessWorks

TIBCO ActiveMatrix Service Grid

TIBCO ActiveMatrix Service Bus

TIBCO Business Studio

TIBCO Rendezvous

TIBCO Runtime Agent

TIBCO Enterprise Message Service


xii | Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

ENV_NAME

AMX_HOME

TIBCO products are installed into an installation environment. A product installed into

an installation environment does not access components in other installation

environments. Incompatible products and multiple instances of the same product must be

installed into different installation environments.

An installation environment consists of the following properties:

Name Identifies the installation environment. This name is referenced in

documentation as ENV_NAME. On Microsoft Windows, the name is appended to the

name of Windows services created by the installer and is a component of the path to

the product shortcut in the Windows Start > All Programs menu.

Path The folder into which the product is installed. This folder is referenced in

documentation as TIBCO_HOME.

TIBCO ActiveMatrix installs into a directory within a TIBCO_HOME. This directory is

referenced in documentation as AMX_HOME. The default value of AMX_HOME depends

on the operating system. For example on Windows systems, the default value is

C:\tibco\amx-3.

code font Code font identifies commands, code examples, filenames, pathnames, and output

displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code font Bold code font is used in the following ways:

In procedures, to indicate what a user types. For example: Type admin.

In large code samples, to indicate the parts of the sample that are of particular

interest.

In command syntax, to indicate the default parameter for a command. For example,

if no parameter is specified, MyCommand is enabled:

MyCommand [enable | disable]


Preface | xiii

italic font Italic font is used in the following ways:

To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks

Concepts.

To introduce new terms For example: A portal page may contain several portlets.

Portlets are mini-applications that run in a portal.

To indicate a variable in a command or code syntax that you must replace. For

example: MyCommand PathName.

Key

combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For example:

Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other.

For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example,

an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the

information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss

or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Contd)

Convention Use

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical OR that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3


xiv | Typographical Conventions

{ } A logical group of items in a command. Other syntax notations may appear within each

logical group.

For example, the following command requires two parameters, which can be either the

pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be

either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first

parameter must be param1. You can optionally include param2 as the second parameter. And

the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}

Table 2 Syntax Typographical Conventions

Convention Use


Preface | xv

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident

experts. It is a place to share and access the collective experience of the TIBCO

community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To

register, go to http://www.tibcommunity.com.

How to Access TIBCO Documentation

You can access TIBCO documentation here:

http://docs.tibco.com

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO

Support as follows:

For an overview of TIBCO Support, and information about getting started with

TIBCO Support, visit this site:

http://www.tibco.com/services/support

If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name,

you can request one.


xvi | Connecting with TIBCO Resources


| 1

Chapter 1 Introduction

This chapter gives an overview about TIBCO ActiveMatrix Binding Type for Adapters.

Topics

Overview, page 2

Terms and Terminology, page 3

Features, page 6

Use Cases and Scenarios, page 9


2 | Chapter 1 Introduction

Overview

TIBCO Software Inc. offers TIBCO Adapter applications to facilitate communication and

update business information that originates from diverse sources and resides on diverse

host systems within an organization.

An adapter provides a bridge between an application and the TIBCO integration

environment. Using a no-coding approach, TIBCO adapters enable packaged applications,

databases, and other technologies to participate in the enterprise information flow,

regardless of their data formats or communication protocols. Integration of new

applications does not require programming and does not interfere with existing

infrastructure.

TIBCO ActiveMatrix Binding Type for Adapters bridges TIBCO adapter products with

TIBCO ActiveMatrix components through AE/JMS or AE/Rendezvous transport. By

doing so, the adapter binding makes a Service Component Architecture (SCA) service

accessible through the adapters.

SCA defines a model for developing applications based on Service-Oriented Architecture.

Business function is provided as a set of components assembled into a structure called a

composite. For more information about SCA, see http://www.oasis-opencsa.org/sca.


Terms and Terminology | 3

Terms and Terminology

This section explains the terms used in TIBCO ActiveMatrix environment.

Composites

A composite is a configuration of services comprising an application that conforms to

SOA (Service-Oriented Architecture). A composite contains components, services,

references, the wires that interconnect them, and properties that are used to configure the

components. A root composite equates to an SCA application.

Components

A component is the basic element of business logic. It is defined at design time.

Components are configured instances of implementations. More than one component can

use and configure the same implementation. Components can have services, references,

and properties. All of these can be promoted to the composite level during design time.

Components have different types of dependencies. Components can express dependencies

on product features, custom features, other components, and resources. All of a

component's dependencies must be satisfied for it to be deployed to a node.

Components can be deployed to multiple nodes for fault tolerance or load balancing.

Component Implementations

A component's implementation provides the business function. TIBCO ActiveMatrix

supports several implementation types, for example, Java, Medication, Web application

and Spring. See the TIBCO ActiveMatrix Service Grid documentation for more

information.

Services and References

Applications interact through services and references. Applications offer services and

invoke references to other applications. An application's services and references are

promoted from the services and references of the components it contains.

Component services can be consumed by other components within the composite or be

promoted as composite services for use by consumers outside the composite. A composite

service has an interface and one or more bindings.

Component references consume services provided by other components in the same

composite or services provided outside the composite. A composite reference has an

interface and one binding.



Interfaces

An interface defines the contract for services and references. Services and references can

interact only when they have the same interface. An interface defines one or more

operations and each operation has zero or one request (input) message and zero or one

response (output) message. The request and response messages may be simple types such

as strings and integers or they may be complex types. In the current release, TIBCO

ActiveMatrix supports WSDL 1.1 port type interfaces.

Bindings

A binding specifies how communication happens between a reference and a service. A

service binding describes the mechanism a client uses to access a service. A reference

binding describes the access mechanism a reference uses to invoke a service. References

can have at most one binding.

TIBCO ActiveMatrix supports the following types of bindings: Virtualization, SOAP,

EJB, Adapter, and JMS.

TIBCO ActiveMatrix Binding Type for Adapters supports AE/JMS and AE/Rendezvous

transports, and exposes the adapter as an SCA service.

Promote

Just as components expose services, a composite can also expose services. These services

are implemented by components within the composite. To make them visible to the

outside world, the composites creator can promote those services.

Other Key Terms

The following terms are used in this manual.

A Distributed Application Archive (DAA) is an ActiveMatrix deployment package and

comprises a single SCA application. It contains components and a descriptor that

indicates the component into which each product feature is to be deployed. The

application in a DAA is usually unbound. The binding is carried out by Administrator

at packaging or deployment time. The suffix of a distributed application archive file is

.daa.

The ActiveMatrix services are described in documents expressed in WSDL (Web

Services Description Language). The WSDL documents specify the messages that are

required to access a service.

An endpoint (WSDL 2.0) is a combination of a binding and a network address (the

URL at which a consumer can access a service). An internal endpoint is accessible

only to consumers within an ActiveMatrix environment. An external endpoint has a

binding that provides access to consumers outside the ActiveMatrix environment.


Terms and Terminology | 5

During any service interaction, each service adopts one of two roles: provider or

consumer. A service provider publishes a WSDL document that describes the services

it offers. A service consumer uses the WSDL document to determine the available

services and the messages required to access the services.



Features

TIBCO ActiveMatrix Binding Type for Adapters supports the following features.

Usability

Easy-to-Use GUI

TIBCO ActiveMatrix Binding Type for Adapters provides a custom binding palette that

seamlessly integrates with TIBCO Business Studio. This easy-to-use interface simplifies

the configuration operations.

Transport and Wire Format

For TIBCO ActiveMatrix Binding Type for Adapters, there are two transport types

available.

TIBCO Rendezvous Transport

TIBCO Rendezvous transport uses subject-based addressing to support both multicast or

broadcast and point-to-point communications.

JMS Transport

TIBCO ActiveMatrix Binding Type for Adapters supports configuration of a JMS shared

resource for an adapter binding component. Both Topic and Queue connection factories

are supported.

TIBCO Enterprise Message Service must be installed to use the JMS transport.

XML Message

XML Message is available for both the JMS transport and the TIBCO Rendezvous

transport.

The XML Message wire format conforms to specifically constructed and fully compliant

XML Schema (XSD) based on the existing definition of the ActiveEnterprise schema.

ActiveEnterprise Message

ActiveEnterprise Message is available for both the Rendezvous and JMS transports.


Features | 7

Control information for validation is sent in the message. If no control information is

included, an exception is returned to the subscriber. ActiveEnterprise standard wire format

provides class information and packing rules for the TIBCO Adapter SDK set of data

types. This format allows ActiveEnterprise components to perform extra validation on

messages sent or received.

See TIBCO Adapter SDK Programmers Guide for details about the control information

generated and sent with ActiveEnterprise messages.

Rendezvous Message

Rendezvous Message is available only for the TIBCO Rendezvous transport.

The TIBCO Rendezvous wire format does not include control information in the message.

It should only be used for communicating with applications configured for the TIBCO

environment that do not support the TIBCO ActiveEnterprise wire format.

Quality of Service

TIBCO Rendezvous transport supports two types of QoS:

Certified (RVCM) Guarantees that each certified message reaches its intended

recipient in the order sent. The message can be sent across network boundaries and, if

a network fails, delivery attempt continues until it succeeds or the message times out.

This is called certified message delivery.

Certified (RVCMQ) Allows multiple adapters to distribute the load among the

distributed queue members. The service is used for adapters configured with the

subscription service or request response service to provide process level load

balancing.

Reliable (RV) Ensures that each multicast or broadcast message is received as long as

the physical network and packet recipients are working. It also ensures that the loss of

a message is detected. This choice is appropriate when message delivery is expected

but some loss can be tolerated.

Message Exchange Patterns

A provider generates and responds to messages according to the operations defined in the

interface it offers. The interface is always written from the perspective of the provider.

That is, if an interface says that the messages are input and then output, the provider first

receives a message and then sends a message. A consumer uses a service, and interprets an

interface in order to consume a service. The consumer handles messages in the opposite

direction from the provider.



A message exchange pattern (MEP) defines the sequence and cardinality of messages sent

between the provider and the consumer. TIBCO ActiveMatrix Binding Type for Adapters

supports the following Message Exchange Patterns (MEPs).

One-Way (In-Only MEP)

An external adapter publisher sends a message to an adapter binding. See Figure 1,

Matrix Publish Inbound (In-Only MEP), on page 9.

An adapter binding sends a message to an external adapter subscriber. See Figure 2,

Matrix Publish Outbound (In-Only MEP), on page 10.

Request-Response (In-Out MEP)

An external adapter RPC client sends a request to an adapter binding with an

expectation of a response. See Figure 3, Matrix Request/Response Inbound (In-Out

MEP), on page 11.

A variation of this use case occurs when the adapter RPC client does a one-way

invoke on the adapter binding. In this case, the adapter binding does not send a

response back.

An adapter binding sends a request to an external adapter RPC server with an

expectation of a response. See Figure 4, Matrix Request-Response Outbound (In-Out

MEP), on page 12.

A variation of this use case occurs when the adapter binding does a one-way invoke

on the external adapter RPC server. In this case, the external adapter RPC server does

not send a response back.


Use Cases and Scenarios | 9

Use Cases and Scenarios

TIBCO ActiveMatrix Binding Type for Adapters supports all four types of adapter

services, namely, Publication Service, Subscription Service, Request-Response Service,

and Request-Response Invocation Service.

For Publication Service and Request-Response Invocation Service, the adapter

binding serves as a service binding.

For Subscription Service and Request-Response Service, the adapter binding serves as

a reference binding.

There are four scenarios given for TIBCO ActiveMatrix Binding Type for Adapters, in

accordance with the four types of adapter services.

Matrix Publish Inbound, page 9

Matrix Publish Outbound, page 10

Matrix Request-Response Inbound, page 11

Matrix Request-Response Outbound, page 12

Matrix Publish Inbound

Figure 1 Matrix Publish Inbound (In-Only MEP)

ComponentAdapter

Publisher

Composite

Adapter

Service

Binding

Component

1 2

3

Composite Service

Legend

Component Service Component Reference

Promotion

Component3

Component3



In the publish inbound scenario, the adapter binding receives a message from the adapter

publisher.

1. The adapter publisher publishes a message over TIBCO Rendezvous or JMS transport

to the adapter binding.

2. The adapter binding sends the received message.

3. The message is picked up by the services provided through other TIBCO

ActiveMatrix components.

Matrix Publish Outbound

Figure 2 Matrix Publish Outbound (In-Only MEP)

In the publish outbound scenario, the adapter binding sends a message to the adapter

subscriber.

1. A component generates a message and sends it to the adapter binding.

2. The adapter binding publishes the message over TIBCO Rendezvous or JMS transport

to the external adapter subscriber.

Adapter

Subscriber

Composite

Adapter

Reference

Binding

1ComponentAdapter

Subscriber

Adapter

Subscriber

Legend

Component Service

Component Reference Promotion

Composite Reference

Component

2

2

2


Use Cases and Scenarios | 11

Matrix Request-Response Inbound

Figure 3 Matrix Request/Response Inbound (In-Out MEP)

In the request-response inbound scenario, the adapter client expects a response from the

adapter binding.

1. The adapter client sends a request message over TIBCO Rendezvous or JMS

transport, and invokes a matching adapter binding.

2. The adapter binding relays the request to services provided through other TIBCO

ActiveMatrix components.

3. The other components return a response back to the adapter binding.

4. The adapter binding sends the response back to the adapter client over TIBCO

Rendezvous or JMS transport.

ComponentAdapter

Client

Composite

Adapter

Service

Binding

Component

1 2

Composite Service

Legend

Component Service Component Reference

Promotion

Component

Component

4 3



Matrix Request-Response Outbound

Figure 4 Matrix Request-Response Outbound (In-Out MEP)

In the request-response outbound scenario, the adapter binding expects a response from

the adapter server.

1. A component generates a request and sends it to the adapter binding.

2. The adapter binding relays the request over TIBCO Rendezvous or JMS transport, and

invokes the external adapter server.

3. The external adapter server returns a response back to the adapter binding over

TIBCO Rendezvous or JMS.

4. The response returned by the adapter binding is picked up by the component.

Component

Composite

Adapter

Reference

Binding

2

Component

Legend

Component Service

Component Reference Promotion

Composite Reference

3

2

3

2

3

1

4

Adapter

Server

Adapter

Server

Adapter

Server


| 13

Chapter 2 Developing an Adapter Binding

This chapter describes how to integrate a legacy TIBCO Adapter configuration with the

TIBCO ActiveMatrix through an adapter binding.

Topics

Overview, page 14

Generating WSDL Files, page 15

Migrating TIBCO ActiveMatrix 2.x Projects, page 24

Developing an Adapter Binding, page 27

Creating a Distributed Application Archive, page 33


14 | Chapter 2 Developing an Adapter Binding

Overview

TIBCO ActiveMatrix Binding Type for Adapters integrates legacy adapters, or any

applications built upon TIBCO Adapter SDK, with the TIBCO ActiveMatrix

environment. The endpoints of such legacy adapters or applications dictate the WSDL for

the adapter binding endpoints.

The TIBCO ActiveMatrix development tools consist of TIBCO Business Studio

workbench and a set of TIBCO ActiveMatrix plug-ins. This chapter describes how to

create and configure an adapter binding, as well as how to package it into a distributed

application archive (DAA).

For more information about TIBCO Business Studio, see the Workbench User Guide in

the Workbench online help. To view the online help, select Help > Help Contents.


Generating WSDL Files | 15

Generating WSDL Files


applications built upon TIBCO Adapter SDK, with the TIBCO ActiveMatrix environment

using the WSDL files.

Prerequisites

Before proceeding with the procedures in this chapter, ensure that the legacy adapter

configuration is ready in TIBCO Designer, and that the project is saved.

Generation Steps

To generate the WSDL files, complete the tasks in this section.

Task A Start TIBCO Business Studio

1. Execute one of the following platform-specific commands to start TIBCO Business

Studio:

On Microsoft Windows:

double-click TIBCOBusinessStudio.exe located in the AMX_HOME\studio\3.6\eclipse

directory

or

run the executable from the command line

AMX_HOME\studio\3.6\eclipse\TIBCOBusinessStudio.exe

On Unix:

run AMX_HOME/studio/3.6/eclipse/TIBCOBusinessStudio

2. In the Workspace Launcher, accept the default workspace, or browse to, or create a

new workspace. Click the OK button. The workbench window appears, as shown in

Figure 5.

The first time you run TIBCO Business Studio, it displays a Welcome screen. Dismiss

the screen by clicking the Close button in the title bar.



Figure 5 TIBCO Business Studio Workbench Window

Task B Import an Adapter Designer Project

In the TIBCO Business Studio workbench:

1. From the File menu, select Import. The Import dialog appears.

2. Select TIBCO ActiveMatrix Adapter > Import TIBCO Designer Projects and

click the Next button. The TIBCO Designer Project Import dialog appears, as shown

in Figure 6.



Figure 6 Import TIBCO Designer Projects

3. Choose Select Root Directory or Select Archive File.

4. Click the Browse button, and navigate to the folder where the adapter project or the

archive file is located. Click the OK button.

5. In the Projects pane, check the checkbox for the project you want to import as well as

the services contained in the project.

To import specific adapter services, expand the adapter configuration and select

adapter services.

Selecting the entire project will import all adapter configurations and associated

resources.

Click the Next button. The Project Import Options dialog appears, as shown in

Figure 7.



Figure 7 Project Import Options

6. Specify the import options.

Table 3 describes the project import options.

7. Click the Finish button.

The adapter configuration files from the original TIBCO Designer project are converted

into resource files with the .gac suffix.

Table 3 Project Import Options

OptionDefault Setting?

Description

Write Trace to Platform Log Yes Errors, warnings or information items generated during import are

written to the Business Studio log.

Log Exception Stack Trace No In case of errors or exceptions, full exception trace is generated and

logged.

Print Message Prefix No Errors, message codes associated with errors, warnings or information

items are written to the Business Studio log.

Stop Import on First Error No The project importing process will stop upon first error if this checkbox

is checked. If not selected, errors are logged and import continues until

all project resources are imported.

Stop Autobuild During

Import

No Check this checkbox for large projects to optimize the performance of

the import. If the checkbox is unchecked, import of resources into the

project may trigger building from various builders associated with the

project and may slow down the import operation.



Task C Create an SOA Project in TIBCO Business Studio

In the TIBCO Business Studio workbench, complete the following steps:

1. From the File menu, select New > Project. The New Project dialog appears.

2. Select TIBCO SOA Platform > TIBCO SOA Project and click the Next button.

3. In the Project name field, enter a name for the project. You can use the default location

for the project, or uncheck the Use Default Location checkbox and click the

Browse... button to navigate to your desired location.

Click the Next button, the Asset Type Selection dialog appears.

4. Select the asset types that are required for the project. You can click an assets item in

the Assets panel to view its descriptions in the Description panel on the right.

Click the Next button, the Composite Project dialog appears.

5. Select Basic SOA Project from the Project Types list. The Basic SOA Project

template creates a composite with an abstract component, promoted services, and

references wired to it.

Click the Next button to continue, or click the Finish button to finish creating the

project using the default settings.

6. If you click the Next button in step 5, the Composite Details dialog appears. Specify

the details for the new composite, such as composite file, component name, service

name, and reference name by entering the new names in the corresponding fields.

Click the Next button to continue, or click the Finish button to finish creating the

project using the default settings.

7. If you click the Next button in step 6, the Set Special Folders dialog appears. Specify

folders for the project, including the Service Descriptors folder, the Mediation Flows

folder, the Deployment Artifacts folder, and the Resource Templates folder.


Task D Generate WSDL Files

To generate the WSDL files:

1. Right-click any existing folder inside the SOA project, for example, Service Descriptors,

and select New > Folder. The New Folder dialog appears as shown in Figure 8.



Figure 8 Create a New Folder

2. In the New Folder dialog, the Service Descriptors folder is selected as the parent folder by

default. Type Adapter Resources in the Folder Name field. Click the Finish button. The

Adapter Resources folder is created under the Service Descriptors folder.

Note: You can use the Advanced button to create a virtual or linked folder. See

Workbench Users Guide for more information.

3. In the Project Explorer panel, right-click the adapter configuration file whose services

you want to expose in the SOA Composite. From the pop-up menu, select Generate

Adapter WSDL.

4. In the Container Selection dialog, select the Adapter Resources folder, then click the

OK button.



Figure 9 Container Selection

The adapter configuration is scanned for correctness. If it contains any services that are

invalid for lack of a schema (or class reference), the following dialog appears. Selection of

the schema (or class reference) for the service can be made here.

Figure 10 Missing Schema or Class Reference

If the OK button is enabled, the configuration has a few services that are valid and

a few that arent. Therefore you are provided a choice to fix the invalid ones. You

can click the OK button if you do not wish to fix the schema references for these

services. These services will not be considered for WSDL generation.

If the OK button is disabled, the configuration contains not even a single service

that is valid from the standpoint of having a schema reference. You must make at

least one service valid by choosing the proper schema for it to enable the OK

The original project containing the adapter configuration is not available in the project list

in the Container Selection dialog.



button. If you click the Cancel button, WSDL and other resources will not be

generated.

When the process ends, two folders are generated in the Adapter Resources folder, as shown in

Figure 11.

Figure 11 Generate WSDL Files

schema: this folder contains the adapter XSD schema.

adapterConfiguration_genresources: this folder contains the following artifacts:

adapterConfiguration_number.dat: the internal configuration file that contains

runtime configuration information.

adapterConfiguration_consumer.adendpoints: the adapter service endpoints file that

contains information about the consumer endpoints supported by the adapter. All

Publication Services and Request-Response Invocation Services are in this file.

adapterConfiguration_consumer.wsdl: the generated WSDL file that specifies the

service contract for Adapter Publisher and Request-Response Client exposed in the

When you need to select the missing AE schema class references for the subscription

service endpoint of ActiveMatrix Adapter for Files, you will find the wire schema of the

subscription service is not available and you will need to select the wire schema of the

publication service instead.



SOA composite via adapter service binding. The WSDL contract is intended to be

implemented by other components.

adapterConfiguration_provider.adendpoints: the adapter service endpoints file that

contains information about the provider endpoints supported by the adapter. All

Subscription Services and Request-Response Services are in this file.

adapterConfiguration_provider.wsdl: the generated WSDL file for wiring other

components with adapter services of Request-Response Server or Subscriber via

the adapter reference binding in the SOA composite.

adapterConfiguration.substvar: contains substitution variables that are imported from

the adapter configuration file.

One or more JMS Shared Resources if the original adapter configuration is

JMS-enabled.

One or more JNDI Resources if the original adapter configuration uses JNDI.

One or more Identity Resource if the original adapter configuration uses Identities

directly or through any of its JMS or Rendezvous Sessions.



Migrating TIBCO ActiveMatrix 2.x Projects


applications built upon TIBCO Adapter SDK, with the TIBCO ActiveMatrix

environment. This section demonstrates how to migrate TIBCO ActiveMatrix 2.x projects

to the current TIBCO ActiveMatrix environment.

Prerequisites

Before proceeding with the procedures in this chapter, ensure that the legacy adapter

configuration is ready in TIBCO Business Studio, and that the TIBCO ActiveMatrix 2.x

project is saved.

Migration Steps

To migrate a TIBCO ActiveMatrix 2.x project to the current TIBCO ActiveMatrix

environment, complete the tasks in this section.

Task A Start TIBCO Business Studio

See Start TIBCO Business Studio on page 15.

Task B Import an Adapter Designer Project

See Import an Adapter Designer Project on page 16.

Task C Import a TIBCO ActiveMatrix 2.x Project

To import a TIBCO ActiveMatrix 2.x project:

1. From the File menu, select Import.

2. In the Import dialog, select General > Existing Projects Into Workspace. Click the

Next button.

3. Choose Select Root Directory or Select Archive File.

4. Click the Browse button, and navigate to the folder where the TIBCO ActiveMatrix

2.x project or the archive file is located. Click the OK button.



Migrating TIBCO ActiveMatrix 2.x Projects | 25

Figure 12 Import TIBCO ActiveMatrix 2.x Projects

Task D Generate WSDL Files

To generate the WSDL files:

1. In the Project Explorer panel, right-click the adapter configuration file whose services

you want to expose in the SOA Composite. From the pop-up menu, select Generate

Adapter WSDL.

2. In the Container Selection dialog, select the folder which contains the original WSDL

files as the destination project folder. Click the OK button.

Two folders, schema and adapterConfiguration_genresources, are created. The original

folders are overwritten automatically.

Task E Migrate to TIBCO ActiveMatrix 3.x FormatF

1. In the Project Explorer panel, right-click the 2.x project, and then select Migrate to

AMX 3.x format.

2. In the Project Migration dialog, check the Save a copy of these projects before

migrating checkbox to make a copy of the 2.x project and specify the location. Click

the Next button.



Figure 13 Project Migration Dialog

3. In the Changes to be performed panel, review the changes to be performed. Click the

Finish button.

4. A Migration Results dialog will pop up when the migration is finished. Review the

configurations and resources that have been migrated. Click the OK button.

The original WSDL file is not overwritten automatically when migrating an AMX 2.x

project with mediation flows to AMX 3.x format. You need to recreate the mediation flow

after migrating an AMX 2.x project with mediation flows.


Developing an Adapter Binding | 27

Developing an Adapter Binding

Both Java components and mediation components can be used to implement services in

the TIBCO ActiveMatrix environment.

Java components support service implementation taking advantage of the flexibility

and power of a general purpose programming language. For instructions on how to

use Java components, see the TIBCO ActiveMatrix Service Grid Documentation.

A mediation component shields service consumers from the service providers

physical location at both the design time and runtime. A mediation component is

responsible for delivering requests to a service provider. For more information about

mediation components, see the TIBCO ActiveMatrix Service Grid Documentation.

This section demonstrates how to implement the service using a mediation flow. A

mediation flow is a graphical representation of the business logic for a mediation

component.

Task A Create a Mediation Flow

1. In the Project Explorer, right-click the Mediation Flows folder, then select New >

Mediation Flow.

2. In the Create Mediation Flow dialog, select the Single Empty Mediation Flow radio

button to create an empty mediation flow. Click the Next button.

3. Supply a name in the Mediation Flow field.

4. Click the Finish button. The Mediation Flow Editor opens, as shown in Figure 14.

Figure 14 Create a Mediation Flow



5. Configure the mediation flow in the Mediation Flow Editor.

Define the mediation interface, mediation path, and target interface:

Mediation interfaces are interfaces that expose services to consumers.

Drag the WSDL files generated from adapter Publication Services or

Request-Response Invocation Services from the Project Explorer to the Mediation

Flow Editor to create mediation interfaces.

Target interfaces are interfaces to the actual services that make up the enterprise

application.

Drag the WSDL files generated from adapter Subscription Services or

Request-Response Services from the Project Explorer to the Mediation Flow

Editor to create target interfaces.

Mediation paths are created by dragging and dropping a mediation operation onto

a target operation.

For operations that use the one-way message exchange pattern, there is only an

input path from the mediation operation to the target operation. For operations that

use the request-response message exchange pattern, there is an input path, an

output path, and a fault path.

6. Add tasks to mediation paths as necessary.

According to the requirements of the application, you may need to perform various

types of tasks on mediation paths. Click a task in the Palette, as shown in Figure 14,

and drop it on the mediation paths to add the corresponding task.

For example, Transform tasks are necessary when the schema of the input, output, or

fault message does not match the schema of the message of the expected recipient.

Log tasks allow mediation flows to send data to a log file.

7. Save the configuration.

Task B Create a Composite

An empty composite, SOAProjName.composite, is created by default when a new

ActiveMatrix SOA Project is created. You can either use the default composite or create a

new composite.

If you are going to use the default composite, it is recommended to delete the existing

component, reference, and service of the composite.

To create a new composite:

1. In the Project Explorer, right-click a Composites folder and select New > Composite.

The New Composite dialog appears.

2. Select a folder to contain the composite.



3. In the File name field, type a name for the composite.


Task C Configure the Composite

In the Composite Editor:

1. Select the Mediation element in the Palette.

2. Move the cursor over the canvas and left-click to drop the mediation element on the

canvas.

3. In the Properties view, click the Implementation tab.

4. Click the Not Set link next to the Mediation Flow label, then select the mediation flow

defined in Task A from the Matching items list in the Select a Mediation Flow dialog.

Click the OK button.

5. Right-click the mediation component on the canvas, and select Promote All to

promote the services and references.

Task D Add Adapter Bindings

In the Composite Editor:

1. Choose a starting point and follow the appropriate procedures.

The Add Binding dialog appears, as shown in Figure 15.

Starting Point Procedure

Canvas a. Right-click the service or reference and select Add > Binding... from

the popup menu.

Properties view a. Click the service or reference on the canvas.

b. In the Properties view, click the Bindings tab. Remove existing

bindings if any.

c. Click the Add Binding... button.



Figure 15 Add an Adapter Binding

2. Select Adapter Binding in the List of Bindings. Click the Finish button.

3. Save the configuration.

Binding Details

After you add a binding to a service or a reference, you can view the binding details

(Endpoint and Adapter Configuration) by selecting the binding in the Bindings tab in the

Properties view, as shown in Figure 16.

Figure 16 Binding Details



The fields listed in Figure 16 are the same for a service binding and a reference binding.

Table 4 describes these binding fields.

Select the binding endpoint to view the endpoint configuration details of the binding.

Figure 17 shows the endpoint configuration details for a reference binding using JMS

transport.

Figure 17 Endpoint Configuration Details for JMS Transport

Table 4 Binding Details

Field Read-only? Description

Endpoint

Name No The name of the adapter binding. You can change the binding name here.

Description Not applicable Add description about the adapter binding.

Adapter Configuration

SDK Application

Name

Yes The application name of your SDK adapter.

Configuration URI Yes Location of the adapter instance description object inside the repository used

for configuration.

Repository URI Yes URL of the repository used for the configuration of this adapter instance.



The fields in the endpoint configuration panel vary depending on the transport type.

Table 5 describes the endpoint configuration fields.

Table 5 Endpoint Configuration

Field Read-only? Description

Common Fields for JMS and RV Transport

Endpoint Name Yes The name of the endpoint.

Endpoint Type Yes The type of the endpoint. The value can be publisher, subscriber, server, or

client.

AESchema Class Yes The path to the endpoint class.

Transport Type Yes The type of transport supported by the binding. JMS or RV.

Fields Only Available for JMS Transport

JMS

ConnectionFactory

No A JMS Connection Factory resource instance that represents the Enterprise

Message Service server.

Destination Type Yes The type of JMS destination. Topic or Queue.

Topic Name No The name of the Topic as JMS destination.

Note: It is the same as the destination value defined in the DAT file. If you

edit the value here, the changed value will override the one defined in the

DAT file at runtime.

Fields Only Available for RV Transport

Service No The TIBCO Rendezvous service parameter.

Network No The TIBCO Rendezvous network parameter.

Daemon No The TIBCO Rendezvous daemon parameter which instructs the transport

object how and where to find the Rendezvous daemon and establish

communication.


Creating a Distributed Application Archive | 33

Creating a Distributed Application Archive

The adapter bindings that are developed in the design phase need to be packaged into a

distributed application archive before they can be deployed.

A distributed application archive (DAA) is a package that contains TIBCO ActiveMatrix

Service Grid applications and libraries.

To create a DAA:

1. Right-click the composite file and select Create DAA. The Create Deployment

Archive dialog appears.

2. Accept the default folder to contain the archive.

3. Accept the default file name or type a new name. Click the Next> button.

4. Select the Do not use a distribution file radio button. Click the Next> button.

5. Review the selected resources to be packaged in the archive. Click the Next> button.

The DAA Specification dialog appears.

6. Accept the default settings and click the Finish button.

When the building process is finished, you can find a .daa file and a .daaspec file in the

Deployment Artifacts folder.

The distributed application archive can now be deployed and started using TIBCO

ActiveMatrix Administrator. See Deploying the Distributed Application Archive on

page 35.


| 35

Chapter 3 Deploying the Distributed Application

Archive

This chapter describes how to deploy a distributed application archive (DAA) using

TIBCO ActiveMatrix Administrator.

Topics

Overview, page 36

Deploying a Distributed Application Archive, page 37


36 | Chapter 3 Deploying the Distributed Application Archive

Overview

After the TIBCO ActiveMatrix Binding Type for Adapters component is packaged into a

distributed application archive (DAA), it is deployed, started, and managed using TIBCO

ActiveMatrix Administrator.

Using TIBCO ActiveMatrix Administrator, you can upload the DAA file, deploy the

component on the chosen machine(s), and set runtime options before deployment.

TIBCO ActiveMatrix Administrator consists of the Administrator server, a command-line

interface, and a graphical interface.

For more information about TIBCO ActiveMatrix Administrator, see TIBCO

ActiveMatrix documentation.

Figure 18 TIBCO ActiveMatrix Administrator Graphical Interface


Deploying a Distributed Application Archive | 37

Deploying a Distributed Application Archive

This section describes the tasks performed to configure and deploy a distributed

application archive. These tasks are performed using TIBCO ActiveMatrix Administrator.

Deploying a distributed application archive involves the following activities:

Creating an Application, page 37

Distributing an Application, page 39

Configuring an Application

Deploying an Application, page 41

Creating an Application

To create an application:

1. In the TIBCO ActiveMatrix Administrator graphical interface, click the Applications

tab.

2. Click the button. The New Application dialog appears and the Create tab is

activated.

In version 3.1.2, RV Network is a required property. A DAA file without specifying a

value for RV Network can be deployed successfully in ActiveMatrix 3.1.2 because

ActiveMatrix 3.1.2 does not check whether the required properties have been provided

when deploying a DAA file.

ActiveMatrix 3.2.0 now checks whether the required properties have been provided when

deploying a DAA file. If you deploy a DAA file of version 3.1.2 which does not specify

the RV Network value in ActiveMatrix 3.2.0, an error will be reported. You need manually

add a value for the RV Network property, then you can successfully deploy it.

When you use TIBCO Rendezvous as the transport for communication with adapters, your

system needs to meet certain requirements. See "TIBCO Rendezvous Requirements" in

TIBCO ActiveMatrix Binding Type for Adapters Installation and Configuration for more

information.



Create Tab

1. Select the method for providing the application template and follow the appropriate

procedure.

2. Accept the default value in the Application Name field, or change the application

name. Application names cannot contain the characters \, /, :, *, ?, ", , |,

whitespace, %, #, &, (, ), or comma and they cannot be the same as the node name.

3. In the Environment Name drop-down list, select an environment in which to create the

application.

4. Accept the default root folder to store the application, or change the application

location by clicking the Select button.

5. Optionally add the descriptions of the application in the Description field.

6. Click the Next button. The Distribute tab is activated.

Distribute Tab

1. Select the node you want to deploy your application.

If there is only one node under the environment, the node is selected by default.

If there are multiple nodes under the environment:

You can type a string in the Search text box and click to list all nodes with the

specified string. Then check the checkbox next to a node.

Or you can check the checkbox next to a node from the Node list directly.

Starting Point Procedure

DAA File 1. Select the Create the application from an Application

Artifact file radio button.

2. Click the Browse button, and navigate to a folder containing

a DAA file. Double-click the DAA file. A message appears

indicating the template and version information.

Existing Template 1. Select the Select an existing application template radio

button.

2. Click Show System Application Templates, and a list of

system application templates appears.

2. Type a string (for example: bt) in the Search text box and

click to jump to the TIBCO ActiveMatrix Adapter BT

template. Or, select TIBCO ActiveMatrix Adapter BT in the

application templates list directly.

3. Optionally click and select a template version.



2. Choose one of the following actions:

Save and Exit Saves the setup information and exits the wizard.

The application is added to the Applications list. You need to continue with

Configuring an Application.

Next Saves the setup information and activates the wizards configuration-related

tabs.

Configuration-related Tabs

1. The Reference tab is activated after you click Next in the previous step.

2. Configure the promoted references.

3. Click Next to activate the Shared Resources tab if the template contains shared

resources.

4. Select the resource templates that you want to import.

5. Click Next to activate the Properties tab to continue with the configuration.

6. Supply the Property Value for your application.


Save and Exit Saves the configuration information and exits the wizard.

The application has been configured. You need to continue with Deploying an

Application.

Next Saves the configuration information and activates the wizards Validate and

Deploy tab.

Validate and Deploy Tab

1. The validation message appears after you click Next in the previous step. You can

click the Re-validate button to validate it again.


Deploy Saves the distribution selections, exists the wizard, and deploys and starts

the application.

Save And Exit Saves the distribution selections and exits the wizard.

You need to continue with Deploying an Application.

Distributing an Application

To distribute an application:



1. In the Applications list, select the application.

2. Click the Distribution tab of that application.

3. Select the node that you want to deploy the features to in the Available Nodes list.

Click the right arrow button to move the node to the Selected Nodes list, then click

the Save button, as shown in Figure 19.

Figure 19 Map Node

Configuring an Application

To configure an application, select the application in the Applications list:

Click the Properties tab. The properties list appears, as shown in Figure 20. In the

Property Value column, edit the application and binding property values.



Figure 20 Properties List

Click the Configuration tab. In the Wires view, select the reference and click the Edit

Binding button to edit its properties.

Deploying an Application

A distributed application archive is ready to deploy once it is uploaded and configured.

Before proceed with deploying the distributed application archive, ensure that all the

applications required for deployment are running.

To deploy an application:

1. Select the application of the uploaded distributed application archive.

2. Click the button to deploy the application.

You can select Deploy with Start, Deploy without Start, or More Deploy Options

from the Deploy list.

See TIBCO ActiveMatrix Service Grid Administration for more information.

You need to install the JMS resource instance if the JMS transport is used before

deployment.


| 43

Chapter 4 Tutorials

This chapter demonstrates how to deploy and run the examples distributed with TIBCO

ActiveMatrix Binding Type for Adapters.

Topics

Overview, page 44

Working with the Example for Generic Adapter Configurations, page 45

Working with the Example for TIBCO ActiveMatrix Adapter for Database, page 50


44 | Chapter 4 Tutorials

Overview

TIBCO ActiveMatrix Binding Type for Adapters provides two sets of examples in the

AMX_HOME\amx_bt_adapter\version_number\samples directory: one set for Generic Adapter

Configurations, and another set for TIBCO ActiveMatrix Adapter for Database.

For more information about how to configure TIBCO ActiveMatrix Adapter for Database,

see the TIBCO ActiveMatrix Adapter for Database documentation.

Prerequisites for Running the Examples

Before running the examples, ensure that all the required software has been installed and

is operating correctly. See TIBCO ActiveMatrix Binding Type for Adapters Installation

and Configuration for more information.


Working with the Example for Generic Adapter Configurations | 45

Working with the Example for Generic Adapter Configurations

TIBCO ActiveMatrix Binding Type for Adapters provides four sample projects for

Generic Adapter Configurations:

jmsGenericDemo.designer: a designer project using the JMS transport

jmsGenericDemo: an SOA project using the JMS transport

rvGenericDemo.designer: a designer project using the Rendezvous transport

rvGenericDemo: an SOA project using the Rendezvous transport

Example Description

This example shows how to import the pre-defined rvGenericDemo project into TIBCO

Business Studio, change the configuration as necessary and test the example.

Setting Up the Example

To set up the example, complete the following tasks:

Task A Import the Example Project

1. Start TIBCO Business Studio.


3. In the Import dialog, select General > Existing Projects into Workspace. Click the

Next button.

4. Select the root directory of the sample project. Check the Copy projects into

workspace checkbox. Click the Finish button.

Task B Review the Mediation Flow Configuration

The example defines a mediation component for the composite. To view and configure the

mediation flow:

1. In the Project Explorer, expand the Mediation Flows folder.

2. Double-click the pre-defined mediation flow to launch the Mediation Flow Editor.

3. Click the Transform task on the mediation path. In the Properties view, click the

Input tab and create a mapping between the mediation operation context and the

target operation context.



Task C Review the Composite Configuration

1. In the Project Explorer, expand the Composites folder.

2. Double-click the pre-defined composite to launch the Composite Editor.

3. Select the component on the canvas and view its configuration from the Properties

view.

4. Select the promoted service and view the binding configuration from the Properties

view.

Figure 21 Promoted Service Binding: GenericDemo

5. Select the endpoint of the promoted service and view the endpoint configuration from

the Properties view.

Figure 22 Service Binding Endpoint Configuration: GenericDemo

6. Select the promoted reference and view the binding configuration from the Properties

view.



Figure 23 Promoted Reference Binding: GenericDemo

7. Select the endpoint of the promoted reference and view the endpoint configuration

from the Properties view.

Figure 24 Reference Binding Endpoint Configuration: GenericDemo

8. Save the configuration if any changes are made.

Task D Update the Distributed Application Archive

The adapter bindings that are developed in the design time need to be packaged into a

distributed application archive before they can be deployed.

If you made any changes to the example, regenerate the DAA file in TIBCO Business

Studio:

1. In the Project Explorer, right-click the composite file, select Create DAA.



2. In the Create Deployment Archive dialog, select a parent folder for the .daa file. Click

the Next button.

3. Select the Do Not Use A Distribution File radio button. Click the Next button.

4. Select the resources to package in the archive. All the resources are selected by

default.

5. Click the Finish button to create the DAA.

When the building process is finished, you can find a .daa file and a .daaspec file in the

Deployment Artifacts folder.

Deploying and Running the Example

To deploy and run the example, complete the following tasks:

Task A Set Up the Environment for TIBCO ActiveMatrix

1. Start TIBCO Enterprise Message Service Server 6.x.

2. Start the pre-defined TIBCO host.

Run the executable named tibcohost.exe, which locates in the configuration directory of

TIBCO ActiveMatrix. For example,

configuration_directory_name\tibco\data\tibcohost\TibcohostInstance_name\host\bin.

3. Start TIBCO ActiveMatrix Administrator.

a. Launch a web browser and enter the Administrator URL, for example,

http://host_name:8120/amxadministrator/loginForm.jsp, in the address bar to start the TIBCO

ActiveMatrix Administrator Server.

b. Enter the username and password to login.

Task B Deploy the Distributed Application Archive

In TIBCO ActiveMatrix Administrator graphical interface:

1. Select the Application tab.

2. Click the button to add an application. The New Application dialog appears.



3. In the Create tab:

a. Select the Create the application from an Application Artifact file radio

button.

b. Click the Browse button, and navigate to the .daa file. Double-click the DAA file.

c. Enter a name in the Application Name field. For example, AdapterBTapp.

d. Select the environment. and the application folder location.

e. Optionally add the description in the Description field.

f. Click the Next button. The Distribute tab is activated.

4. In the Distribute tab, select a node from the available nodes in the selected

environment. Click the Next button. The Reference tab is activated.

5. In the Reference tab, configure the promoted references. Click the Next button. The

Properties tab is activated.

6. Review the configuration properties and click the Next button. The Validate & Deploy

tab is activated.

7. Click the Deploy button to deploy the application.

Testing the Example

Before testing the example, ensure that you have opened the rvGenericDemo.designer project in

TIBCO Designer and you have the DAA file of the rvGenericDemo SOA project deployed

and running in TIBCO ActiveMatrix Administrator.

To test the example, complete the following steps:

1. In the Tester panel of TIBCO Designer, click the Start button. The Select Processes to

Load dialog appears.

2. Select the TestClient and TestServer processes, and click the Load Selected button.

3. Select Test/TestClient.process and click the Create a job button.

4. A job is created under the each process. Review the output value of the job under

Test/TestSerer.process.



Working with the Example for TIBCO ActiveMatrix Adapter for

Database

TIBCO ActiveMatrix Binding Type for Adapters provides four sample projects for

TIBCO ActiveMatrix Adapter for Database:

jmsSalesOrderDemo.designer: a designer project using the JMS transport

jmsSalesOrderDemo: an SOA project using the JMS transport

rvSalesOrderDemo.designer: a designer project using the Rendezvous transport

rvSalesOrderDemo: an SOA project using the Rendezvous transport

Example Description

This example shows how to import the pre-defined jmsSalesOrderDemo project into TIBCO

Business Studio and change the configuration as necessary.

Setting Up the Example

To set up the example, complete the following tasks:

Task A Import the Example Project

1. Start TIBCO Business Studio.


3. In the Import dialog, select General > Existing Projects into Workspace. Click the

Next button.

4. Select the root directory of the sample project. Check the Copy projects into

workspace checkbox. Click the Finish button.

Task B Review the Mediation Flow Configuration

The example defines a mediation component for the composite. To view and configure the

mediation flow:

1. In the Project Explorer, expand the Mediation Flows folder.

2. Double-click the pre-defined mediation flow to launch the Mediation Flow Editor.


Working with the Example for TIBCO ActiveMatrix Adapter for Database | 51

3. Click the Transform task on the mediation path. In the Properties view, click the

Input tab and create a mapping between the mediation operation context and the

target operation context.

Task C Review the Composite Configuration

1. In the Project Explorer, expand the Composites folder.

2. Double-click the pre-defined composite to launch the Composite Editor.

3. Select the component on the canvas and view its configuration from the Properties

view.

4. Select the promoted service and view the binding configuration from the Properties

view.

Figure 25 Promoted Se

Documents

Tib Adbt-prod Development