TIBCO Adapter™ for EJB · TIBCO Adapter™ for EJB User’s Guide Software Release 5.3 December...

TIBCO Adapter™ for EJB

User’s GuideSoftware Release 5.3December 2006

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 TIBCO ADAPTER FOR EJB USER’S GUIDE). 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.

TIB, TIBCO, Information Bus, The Power of Now, TIBCO Adapter, TIBCO Rendezvous, TIBCO Designer, TIBCO ActiveEnterprise, TIBCO Administrator, TIBCO Hawk, and TIBCO Enterprise are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

EJB, J2EE, JMS 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. Please see the readme.txt 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 © 1999-2006 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviTIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Chapter 1 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Adapter Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2TIBCO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Adapter Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Connector Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Code Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Support Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Adapter and Application Server Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Outbound Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Inbound Communication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Subscription Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Request-Response Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Adapter Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Preparing your Environment for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Operating System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Application Server Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

TIBCO Adapter for EJB User’s Guide

iv | Contents

Pre-Installation Worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Adapter Machine Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Application Server Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Application Server Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Installer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Upgrading an Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Uninstalling the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Installation Registry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Installation History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Adapter Components and Compatible Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Adapter Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Required and Optional TIBCO Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Installing on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Installing on Microsoft Windows 2000 and 2003 Terminal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Installing the Adapter on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Combining Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Installing the Adapter to Connect to Multiple Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Installing the Adapter on a Machine other than the Application Server Machine. . . . . . . . . . . . . . . . . . . . . . 39Post-Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Installing on UNIX Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Installing the Adapter on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Combining Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Installing the Adapter to Connect to Multiple Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Installing the Adapter on a Machine other than the Application Server Machine. . . . . . . . . . . . . . . . . . . . . . 45Post Installation Tasks on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Migrating a 4.x Repository for Use with TIBCO Designer 5.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Migrating an Adapter Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Migrating Multiple Adapter Instances Simultaneously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Migrating Remote or Server Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Installation FAQs and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Running Out of Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Installation Errors on HP-UX 11.00 64 bit Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Configuring TIBCO Hawk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Cannot Install the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Chapter 3 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Scenario Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Connections to the Application Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59


Contents | v

Other Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Create the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Define the Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Define Application Server Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Configure the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Configure the Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Configure the Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Export the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Generate the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Compile the Generated Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Prepare the Code for Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Deploy the Connector Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Deploy the Name Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Write the RMI Client Program for the Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Create the TRA Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Start the Adapter Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Test the Adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Chapter 4 Preparing EJB Application Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Supported Connection Management Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Access to TIBCO Repository over HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Preparing BEA WebLogic Application Server 7.0/BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, SP6, and SP7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Preparation on Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Preparation on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Preparing BEA WebLogic Application Server 8.1/BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5 or SP6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Manually Deploying the Connector on Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Automatically Deploying the Connector on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . 109Manually Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Automatically Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Preparing BEA WebLogic Application Server 9.0, 9.1, and 9.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Manually Deploying the Connector on Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Automatically Deploying the Connector on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . 119Manually Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Automatically Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Preparing IBM WebSphere 5.1.0 Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128


vi | Contents

Manually Deploying the Connector on Microsoft Windows and UNIX Platforms . . . . . . . . . . . . . . . . . . . . . 128Automatically Deploying the Connector on Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . 131Automatically Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Preparing IBM WebSphere 6.0 Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Manually Deploying the Connector on Microsoft Windows and UNIX Platforms . . . . . . . . . . . . . . . . . . . . . 136

Preparing IBM WebSphere 6.0.2 and 6.1 Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Manually Deploying the Connector on Microsoft Windows and Unix Platforms. . . . . . . . . . . . . . . . . . . . . . 140Automatically Deploying the Connector on Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . 140Automatically Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Preparing the Sun Java System Application Server Platform Edition 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Preparing the Sun Java System Application server Platform Edition 8.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Configuring the Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Deploying the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Preparing the Oracle 9i Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Preparation on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Preparation on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Preparing the Oracle 10g Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Preparation on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Preparation on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Preparing the JBoss 3.2.3 Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Preparation on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Preparation on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Preparing the JBoss Application Server 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4 Application Servers . . . . . . . . . . . 167Manually Deploying the Connector on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Automatically Deploying the Connector on Microsoft Windows Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . 169Manually Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Automatically Deploying the Connector on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Chapter 5 Adapter Instance Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Adapter Instance Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Configuration Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Run-time Connection Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Logging Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Startup Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Monitoring Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Adapter Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Publication Service Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187


Contents | vii

Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Code Generator Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Subscription Service Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Connection Info Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Code Generator Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Request-Response Service Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Connection Info Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Code Generator Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Request-Response Invocation Service Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Transport Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Schema Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Code Generator Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Chapter 6 Deploying and Starting an Adapter Using TIBCO Administrator. . . . . . . . . . . . . . 215

Create an EAR File in TIBCO Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Deploy the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Start or Stop the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Monitor the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Chapter 7 Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Defining a TIBCO Hawk Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Changing Global Variable Values at Runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Setting Encoding Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Running the Adapter and Application Server on Different Machines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Configuration Changes Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Making Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Running the Subscription and Request-Response Server Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Running the Publication and Request-Response Invocation Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . 237


viii | Contents

Returning System Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Configuring the Connector Using the Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Deploying Connectors in a Clustered Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241For BEA WebLogic Application Server 8.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241For WebSphere Application Server 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Converting the Sequence Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Chapter 8 Monitoring the Adapter Using TIBCO Hawk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Starting TIBCO Hawk Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

The Auto-Discovery Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Available Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Chapter 9 Code Generator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Necessity of Code Generator or Glue Beans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Code Generator Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Code Generator Outputs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Directory Structure and Class Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Dependent Classes and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Deployment Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Generating Glue Beans to Enable Inbound Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Generating Glue Beans for the Subscription Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Glue Beans for the Request-Response Server Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Generating Glue Beans to Enable Outbound Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Glue Beans for the Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Glue Beans for the Request-Response Invocation Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Using the Generated Glue Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Using the Generated Glue Beans with the Publication Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Using the Generated Glue Beans with the Subscription Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Using the Generated Glue Beans with the Request-Response Invocation Service . . . . . . . . . . . . . . . . . . 321Using the Generated Glue Beans with the Request-Response Server Service . . . . . . . . . . . . . . . . . . . . . 322

Appendix A Trace Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Trace Message Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Status Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331New Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Old Status Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362


Contents | ix

Status Messages for the Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Appendix B Bean Programming Guide for Request-Response Invocation and Publication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Programming Using the Connector API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Accessing the Connection Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Creating a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Creating an Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Using an Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379TIBCO Connector Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382Information on Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Custom Exception Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

RPC Support Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

Publish Support Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Deployment Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

Appendix C Bean Programming Guide for Request-Response and Subscription Services 407

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

Writing Request-Response Server Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Matching Method Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Entering Complex Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Handling Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

Writing Subscriber Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

Custom Exception Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Appendix D TIBCO ActiveEnterprise to J2EE Connector Mapping . . . . . . . . . . . . . . . . . . . . 415

ActiveEnterprise to J2EE Connector Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

ActiveEnterprise to J2EE Connector Name Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

Appendix E Uninstalling an Existing Connector and Glue Beans for your Application Server . 423

Undeploying the Connector for BEA WebLogic Application Server 8.1/BEA WebLogic Application Server 8.1 with SP1, SP2, SP3 or SP4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Uninstalling the Connector and Glue Beans on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . 424Uninstalling the Connector and Glue Beans on UNIX platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Undeploying the Connector for IBM WebSphere 5.1.x Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 426Uninstalling the Connector and Glue Beans on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . 426Uninstalling the Connector and Glue Beans on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427


x | Contents

Undeploying the Connector for JBoss 4.0.0, 4.0.1, 4.0.2, and 4.0.3 Application Servers. . . . . . . . . . . . . . . . . . 429Uninstalling the Connector and Glue Beans on Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . 429Uninstalling the Connector and Glue Beans on UNIX Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

Appendix F Regeneration and Incremental Deployment of Glue Beans for Automatic Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Regenerating Glue Beans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

Incremental Deployment of New Glue Beans Using Ant Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433BEA WebLogic Application Server 8.1 and BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5, or SP6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433BEA WebLogic Application Server 9.0, 9.1, and 9.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434JBoss 4.0.x Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434IBM WebSphere Application Server 5.1.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435IBM WebSphere Application Server 6.0.2 and 6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Appendix G Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467


| xi

Figures

Figure 1 Adapter Components and their Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Figure 2 Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Figure 3 Typical Publication Service Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Figure 4 Typical Subscription Service Flow with Standalone Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Figure 5 Typical Subscription Service Flow with JCA 1.5-Compliant Adapter . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 6 Typical Request-Response Service Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 7 Typical Request-Response Invocation Service Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Figure 8 Inbound Communication with Standalone Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Figure 9 Inbound Communication with JCA 1.5-compliant Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Figure 10 Outbound Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13


xii | Figures


| xiii

Tables

Table 1 Supported application servers and JVM libraries on Microsoft Windows and UNIX systems . . . . 19

Table 2 TIBCO Adapter components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Table 3 Required and Optional TIBCO Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Table 4 Supported platforms, package names and disk space for Microsoft Windows . . . . . . . . . . . . . . . 34

Table 5 Supported platforms, package names, patches and disk space for UNIX systems. . . . . . . . . . . . 41

Table 6 Connection management features that are tested for the available application servers . . . . . . . . 98

Table 7 Application servers that support the HTTPS protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Table 8 The jar files required to run the adapter with TIBCO Administrator Enterprise Edition . . . . . . . . 218

Table 9 Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Table 10 Locations of JAR files for the supported application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Table 11 Locations of the Example Stubs files for the application servers . . . . . . . . . . . . . . . . . . . . . . . . . 237

Table 12 Standard Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Table 13 Class Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Table 14 Tracing Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Table 15 Constructor for the AEResourceException class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Table 16 Methods for the AEResourceException class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Table 17 TIBCO ActiveEnterprise to J2EE Connector Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

Table 18 TIBCO ActiveEnterprise to J2EE Connector Name Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . 418


xiv |


| xv

Preface

TIBCO Adapter™ for EJB software is a bi-directional gateway between Enterprise Java Beans (EJB) and TIBCO-enabled applications. It allows you to exchange real-time business data across various systems, which include application servers and external business partners.

This document describes overall architecture, supported features, installation, configuration, deployment, and status messages.

Topics

• Related Documentation, page xvi

• How to Contact TIBCO Customer Support, page xix


xvi | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Product DocumentationThe following documents form the TIBCO Adapter for EJB documentation set:

• TIBCO Adapter Concepts: Read this manual to gain an understanding of adapters in general. You can apply concepts learned from this manual while using adapters.

• TIBCO Adapter for EJB User’s Guide: This manual explains concepts relating to the adapter and the application with which it interacts. Installation, configuration and deployment information is included in this manual.

• TIBCO Adapter for EJB Examples Guide: Read this manual to work through the examples provided with the adapter.

• TIBCO Adapter for EJB Release Notes: Read this document for information about new features, deprecated features, and open and closed issues.

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products. Note that only books that relate to adapters are listed. Each of the books is available from the doc directory in the product’s installation area.• TIBCO BusinessWorks™ Software

— TIBCO BusinessWorks Concepts

— TIBCO BusinessWorks QuickStart

— TIBCO BusinessWorks Business Palette Reference

— TIBCO BusinessWorks Process Design Guide

— TIBCO BusinessWorks Error Codes

— TIBCO BusinessWorks Release Notes

• TIBCO Designer™ software:

— TIBCO Designer User’s Guide

— TIBCO Designer Palette Reference

— TIBCO Designer Release Notes


Preface | xvii

• TIBCO Administrator™ software:— TIBCO Administrator User’s Guide

— TIBCO Administrator Server Configuration Guide

— TIBCO Administrator Release Notes

• TIBCO IntegrationManager™ software:

— TIBCO IntegrationManager Concepts

— TIBCO IntegrationManager Administrator’s Guide

— TIBCO IntegrationManager Process Design Guide

— TIBCO IntegrationManager Reference

— TIBCO IntegrationManager Release Notes

• TIBCO Rendezvous™ software:

— TIBCO Rendezvous Concepts

— TIBCO Rendezvous Administration

— TIBCO Rendezvous Configuration Tools

• TIBCO Enterprise Message Service™ software:

— TIBCO Enterprise Message Service User’s Guide

— TIBCO Enterprise Message Service Installation

— TIBCO Enterprise Message Service Application Integration

— TIBCO Enterprise Message Service Release Notes

• TIBCO Hawk® software:

— TIBCO Hawk Installation and Configuration

— TIBCO Hawk Administrator’s Guide

• TIBCO Adapter SDK

— TIBCO Adapter SDK Concepts

• TIBCO Runtime Agent

— TIBCO Runtime Agent Release Notes

— TIBCO Runtime Agent Installation

— TIBCO Runtime Agent Domain Utility User’s Guide

— TIBCO Runtime Agent Upgrading to Release 5.4


xviii | Related Documentation

Third Party DocumentationSeveral products from Sun Microsystems, Inc. (Sun) are used in TIBCO Adapter for EJB. For information on EJB, J2EE, and JRE, see relevant documents provided by Sun (http://www.java.sun.com).

Additionally, if you have installed any third-party application server, you must obtain the relevant installation, configuration, usage documentation from that third-party.


Preface | xix

How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support Services as follows.

• For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site:

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

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

http://support.tibco.com

Entry to this site requires a username and password. If you do not have a username, you can request one.


xx | How to Contact TIBCO Customer Support


| 1

Chapter 1 Concepts

This chapter explains the architecture of the TIBCO Adapter for EJB system and how the adapter interacts with EJB applications.

Topics

• Adapter Overview, page 2

• Adapter Components, page 3

• Adapter and Application Server Interaction, page 5

• Adapter Services, page 7

• Adapter Features, page 11


2 | Chapter 1 Concepts

Adapter Overview

This section provides an overview of the TIBCO infrastructure, EJBs, and adapter.

TIBCOTIBCO provides a robust, multi-platform framework that consists of TIBCO Runtime Agent, TIBCO Designer, TIBCO IntegrationManager, and other software for integrating enterprise applications. The backbone of this framework is the messaging transport, which allows one-way (publish or subscribe) or two-way (request-response) messages to be exchanged between applications. TIBCO-enabled applications use messaging transport to send and receive data.

EJBEJB is a set of component-based technologies for developing and deploying server-side Java applications. Application developers write EJBs according to the EJB specification, and then deploy these applications into EJB containers provided by EJB server vendors.

AdapterTIBCO Adapter for EJB enables the integration of EJBs deployed in application servers with TIBCO-enabled applications. This adapter currently supports version 1.4 of the Java 2 Platform, Enterprise Edition (J2EE) specification. It also supports version 1.0 and 1.5 of the J2EE Connector API. For details on EJB or J2EE, see the documentation provided by Sun Microsystems, Inc. (http://www.java.sun.com).

The J2EE Connector Architecture (JCA) 1.0-compliant adapter consists of two separate, distinct components — the connector and the adapter process. The adapter process is a Java application that runs as a separate process. The connector is a JCA 1.0 compliant-resource adapter that runs within the application server.

The JCA 1.5-compliant adapter can consist of two distinct components, which are the same as that of JCA 1.0-compliant adapter. It can be also a single resource adapter that is deployed into the application server. You can deploy this adapter just as an inbound connector, outbound connector, or both.


Adapter Components | 3

Adapter Components

This section outlines the main components that comprise the TIBCO Adapter for EJB and the interaction of these components.

AdapterAn independent executable component that runs external to the application server in a separate JVM. The adapter processes messages that originate from TIBCO-enabled applications and delivers them to EJBs deployed in application servers (this mode of communication is called Inbound). The adapter is implemented in the class com.tibco.ejb.adapter.EjbAdapter and is archived in the EjbAdapter.jar file. This is inbound communication. Also the same functionality can be achieved using JCA 1.5-compliant connector library as described in the following section.

Connector LibraryJCA 1.0-Compliant Connector—An independent resource adapter that runs within the application server, in the latter's JVM. The connector processes messages originating from EJBs in the application server and delivers them to TIBCO applications (this mode of communication is called Outbound). This facilitates outbound communication from an EJB client bean to the TIBCO-enabled application.

JCA 1.5-Compliant Connector—Processes messages originating from EJBs in the application server and delivers them to TIBCO applications (this mode of communication is called Outbound). Also, it can get the messages from the TIBCO applications and delivers it to the Message-driven beans (MDB) (this mode is called inbound communication).

The connector library for both the connector variants are provided as a resource archive format (AeConnector.rar) as well as a standard Java archive file (AeConnector.jar).

Code GeneratorA Java library that runs as part of the adapter's palette. The code generator accepts inputs that describe legacy EJBs deployed in the application server and generates beans that enable communications between the legacy and either the adapter or the connector. The generated beans called glue beans, serve as a bridge between legacy EJBs and the adapter when they are deployed in the application server.



Code Generator also generates MDBs. These are used by JCA 1.5-compliant connector library. The MDBs act as a bridge between legacy EJBs and the connector library in the application server for inbound communication.

Support LibraryThe GlBeansSupport.jar file provides the RPCSupport and PublishSupport wrapper classes, which are used by the code generator to generate beans that assist in enabling request-response invocation and publication services. These classes can be used directly in your EJB programs.

The following figure shows the interaction of the adapter components.

Figure 1 Adapter Components and their Interaction

TIBC

O M

essa

ging

Support Library

Legacy Bean

Connector Bean

GLUE BEAN

Sta

ndal

one

Adap

ter

Application Server

Code Generator

Library

Outbound

Inbound

Indicates ‘data flow’

Indicates ‘generates’

Indicates ‘uses’

Legend:


Adapter and Application Server Interaction | 5

Adapter and Application Server Interaction

Communication parameters, error-logging parameters, and many other parameters can be configured for the adapter using TIBCO’s configuration tool, TIBCO Designer. The adapter has two basic kinds of communication. These scenarios are named based on the direction of data flow in relation to the application server:

• Outbound Communication — Data flows out from an EJB in the application server, through the connector, and in to a TIBCO-enabled application.

• Inbound Communication — Data flows in to an EJB in the application server from a TIBCO-enabled application, through the adapter.

The inbound and outbound scenarios are handled differently. Outbound communications from an EJB are handled by the connector, which is an implementation of the J2EE Connector API that runs within the Java virtual machine of the EJB server. Inbound communications are handled by the adapter, which is an external process that converts the TIBCO messages to RMI calls.

Outbound CommunicationOutbound communication is the flow of data from an EJB that is deployed in an application server, into the connector and out to a TIBCO-enabled application.

The connector is therefore, the intermediate component (a negotiator, mediator, or translator) in the communication between an EJB and the TIBCO-enabled application.

It works as a library that is loaded into the EJB container's Java Virtual Machine (JVM). There are two ways in which this library can be accessed:• As a resource archive (.rar) file conforming to the J2EE Connector

specification — The installation of the adapter supplies a resource archive file that conforms to or implements the J2EE Connector specification API. TIBCO's implementation of the J2EE Connector specification API uses TIBCO messaging to communicate with the Enterprise world as shown in Figure 10 on page 13. The Enterprise world might typically consist of an EIS application such as SAP, and a remote adapter, such as TIBCO Adapter for R/3. Messaging allows a single Connector to be used to communicate with multiple different back-end EIS’.

• As a regular Java archive (.jar) file — For non-Connector-aware application servers, a standard Java archive file is supplied with the installation of the adapter. This jar file gives access to almost the same capabilities that the Connector has, but will work with standard EJB version 1.1 specification compliant servers. The only difference between using the Connector and



using the jar file is the way in which the EJB initially accesses the Connection Factory. See Accessing the Connection Factory on page 377 for details.

The adapter also supports asynchronous publication of data to the TIBCO messaging transport. This is not a standard feature of the Connector architecture.

Inbound CommunicationInbound communication is the flow of data from a TIBCO-enabled application into the adapter process, and then into an EJB deployed in an application server.

JCA 1.0

The adapter is therefore, the intermediate component (a negotiator, mediator, or translator) in the communication between the TIBCO-enabled application and an EJB.

The adapter supports activation of an EJB both in response to a request-response invocation and in response to an incoming asynchronous message initiated from the TIBCO environment. In the former, the request-response invocation request is mapped to an analogous EJB method. In the latter (asynchronous subscription), the incoming message is delivered to a subscribe method in the EJB.

The EJB specification version 1.1 does not support activation of an EJB deployed in a container, from a message. The solution adopted in the adapter is to use an external adapter process to handle inbound communication. This allows inbound message handling to be supported even in EJB 1.1 servers. The same approach will also work in EJB 2.0 servers. EJB 2.0 users can also use JMS to call a message-driven bean.

The inbound adapter process is multi-threaded to achieve improved performance.

JCA 1.5

The adapter is the intermediate component (a negotiator, mediator, or translator) in the communication between the TIBCO-enabled application and an MDB.

The adapter supports activation of an MDB both in response to a request-response invocation and in response to an incoming asynchronous message initiated from the TIBCO environment. In the former, the request-response invocation request is mapped to an analogous MDB method. In the latter (asynchronous subscription), the incoming message is delivered to a subscribe method in the MDB.


Adapter Services | 7

Adapter Services

The adapter supports the following services:

• Publication Service

• Subscription Service

• Request-Response Service

• Request-Response Invocation Service

The interaction between the different adapter services is shown in the next figure.

Figure 2 Adapter Services

Publication ServiceIn this service, the connector gets a message from an EJB application and sends (publishes) the message to the TIBCO environment.

For example, the publication service (connector), can be used to publish stock quotes in a real-time environment. As EJB deployed in an application server reads stock quotes from a backend system, such as a database and pushes the quotes to the connector. The connector in turn, transforms the data and publishes the quotes to the TIBCO environment.

TIBCOAdapter forEJB

SubscriptionService

Request-ResponseService

Connector

PublicationService

Request-ResponseInvocation Service

Outbound Communication Inbound Communication



Figure 3 Typical Publication Service Flow

Subscription ServiceUsing Standalone Adapter

In this service, the adapter gets (subscribes to) a message from the TIBCO environment, and sends the message to an EJB application.

For example, the subscription service (adapter) can be used to subscribe to stock quotes in a real-time environment. An application may be pushing stock quotes to the TIBCO environment (see the Publication service). The adapter subscribes to the stock quotes, transforms the data and pushes the quotes to an EJB deployed in an application server. Several clients may then be able to pull the data from the application server.

Figure 4 Typical Subscription Service Flow with Standalone Adapter

Using JCA 1.5-compliant Connector Library

In this service, the adapter gets (subscribes to) a message from the TIBCO environment, and sends the message to an MDB application.

TIBCO Environment

App

licat

ion

Serv

er

Con

nect

or

EJB

Stock Database

TIBCO Environment

Client

Client

Appl

icat

ion

Ser

ver

EJB

Stock Database

TIB

CO

A

dapt

er fo

r EJ

B

Client


Adapter Services | 9

Figure 5 Typical Subscription Service Flow with JCA 1.5-Compliant Adapter

Request-Response ServiceUsing Standalone Adapter

The adapter gets a request from the TIBCO-enabled application and sends the request to an EJB application. When a response is returned to the adapter from the EJB application, the adapter sends the response to the TIBCO-enabled application.

Figure 6 Typical Request-Response Service Flow

The adapter supports request response scenarios with an RPC server. When the adapter receives a request, it takes the raw requested data, converts it into a formatted EJB schema, and sends it to the EJB application by using a designated EJB interface.

Using JCA 1.5-compliant Connector Library

In this service, the adapter gets (subscribes to) a message from the TIBCO environment, and sends the message to an MDB application.

TIBCO Environment

Client

Client MD

B

Stock Database

Client

TIBC

O

Adap

ter f

or

EJB

Application Server

TIBCO Environment

RequestMessage

ResponseMessage

EJBApplication

TIBCO Adapterfor EJBClient



Request-Response Invocation ServiceThe connector gets a request from an EJB application and sends the request through the TIBCO-enabled application. When a response is returned from the TIBCO-enabled application, the connector sends the response back to the EJB application.

Figure 7 Typical Request-Response Invocation Service Flow

TIBCO Environment

ResponseMessage

EJBApplicationConnecto

r

RequestMessage

Server


Adapter Features | 11

Adapter Features

The following features are described in detail throughout this manual.

Easy-to-Use GUI

The adapter is configured using TIBCO Designer, which provides an easy-to-use graphical user interface that allows you to quickly specify operational parameters or change them as needed.

Supported Communication Paradigms

There are four main scenarios supported by the adapter:

• Outbound broadcast publication of data from an EJB to one or more TIBCO-enabled applications.

• Outbound synchronous request-response invocation communication, sends the request through the TIBCO-enabled application and receives the response from a TIBCO-enabled application.

• Inbound activation of an EJB or MDB on receipt of a broadcast message published from a TIBCO-enabled application.

• Inbound synchronous request-response communication, in which an EJB or MDB receives and processes the request initiated by an external application. An EJB or MDB sends the response through the TIBCO-enabled application.

J2EE Integration

There are two main J2EE scenarios supported by the adapter:

Inbound — The following figure shows how an Enterprise Information System (EIS) uses TIBCO-enabled applications, including the adapter, to communicate with an EJB deployed in a Java 2 Platform, Enterprise Edition application server. The EJB in turn, communicates with a client, such as a hand-held device.



Figure 8 Inbound Communication with Standalone Adapter

Figure 9 Inbound Communication with JCA 1.5-compliant Adapter

Outbound — The following figure shows how a client, such as a hand-held device, uses an EJB deployed in a Java 2 Platform, Enterprise Edition application server and TIBCO-enabled applications, including the EJB connector, to communicate with an EIS.

TIBC

O M

essa

ging

TIBCO-enabled

ApplicationsTIBC

O

Ada

pter

for

EJB

DBMSsEIS Tier

ERP Systems

WWW

Device

Application Server

CONTAINER

EJB

EJB

GLUE

BEANS

TIBC

O M

essa

ging

T IBCO-enabled

Applications

DBM SsEIS T ier

ERP System s

WWW

D evice

Application Server

C O NTAIN ER

M DB

M D B

TIBCO Adapter for EJB



Figure 10 Outbound Communication

Data Type Translation

TIBCO Adapter for EJB performs a mapping of TIBCO ActiveEnterprise data types to standard Java and J2EE Connector data types. Therefore, a session bean deployed in the application server can receive a Remote Method Invocation (RMI) call from the adapter with parameters that are one of the following:

• Primitive Java data types (such as String)

• Java 2 container classes (such as Map or List)

• J2EE Connector data types such as javax.resource.cci.MappedRecord and javax.resource.cci.IndexedRecord, since these implement Map and List, respectively

The TIBCO-to-Java data type translation ensures that an EJB programmer does not have to use TIBCO-specific classes in the bean implementation. Similarly, it ensures that the TIBCO-enabled applications can use TIBCO ActiveEnterprise data types and do not have to translate the message into the J2EE data types.

Rapid Code Development

The adapter includes a code generation tool, which can speed up the process of producing session beans that communicate with a TIBCO ActiveEnterprise service, such as the adapter or connector. The code generator has some useful features and can:

• Seamlessly integrate with the custom palette

TIBC

O M

essa

ging

TIBCO-enabled

Applications

DBMSsEIS Tier

ERP Systems

WWW

Device

Application Server

CONTAINER

MDB

MDB

TIBCO Adapter for EJB



• Generate a packaged EJB that includes the jar/rar file and deployment descriptor

• Generate skeleton EJBs that do not contain the business logic

Multi-threaded Capabilities

In the multithreaded mode, the adapter can listen for multiple concurrent messages published by other applications.

Support for JCA 1.5 Work-management Contract

For inbound communication, the adapter supports JCA 1.5 Work-management Contract, which lets it hand over the inbound message to application server thread. The contract lets the adapter to process the work (MDBs) either asynchrounously. Thus it improves the adapter’s performance.

Schema Support

The adapter uses schema to describe the data that it receives from or sends to the TIBCO-enabled application. For example, if you want to ensure the veracity of the data that an adapter sends, you can define a schema in the repository, then point the adapter to that schema. The adapter will then check whether the schema of the outgoing data conforms to the referenced schema in the respository.

Schemas are useful in a variety of situations, for example:

• Where several programmers collaborate on an adapter application, a specification document normally defines the data model for several related adapter applications. Instead, inside the TIBCO framework, you can define a schema to serve as the data model and update it as needed.

• When the data model of the adapter application changes, you do not have to redesign the adapter. Instead, you simply import the new schema and reconfigure the adapter.

• As a corollary, you can use the same adapter in different business situations by using different schema.

Distributed Queue Support

A distributed queue is a group of cooperating transport objects, each in a separate process. Each transport object is called a member. To balance the transmission load among servers, the adapter can use distributed queues for one-of-n delivery of messages to a group of servers. Each member of a distributed queue must listen



for the same subject using the TIBCO Rendezvous Distributed Queue listener objects. Even though many members listen for each inbound message (or task), only one member processes the message. For details on distributed queues, see TIBCO Rendezvous Concepts.

In the queue mode within TIBCO Enterprise Message Service, each listener is a single receiver of a point-to-point message. However, the listeners can be configured as a set of receivers, each of which receives a fraction of the messages. For details on TIBCO Enterprise Message Service distributed queues, see the TIBCO Enterprise Message Service User’s Guide.

Load balancing for the processing of TIBCO Rendezvous or JMS certified messages is supported using distributed queuing. The messages from TIBCO Rendezvous or TIBCO Enterprise Message Service are distributed equally among all instances that belong to the same group. This distributes the data load over several adapter instances. However, the order in which the data is sent to the application server is not guaranteed.

Scalability and Fault Tolerance

Since the adapter is multithreaded, a single message being processed by the adapter does not become a bottleneck for subsequent messages. Simultaneous processing of messages results in high throughput and performance benefits. The TIBCO Distributed Queue and TIBCO Enterprise Message Service queue protocols for messaging allow peak load balancing between different instances of the same adapter configuration (subscription and request-response services) and also offers fault tolerance. In fault tolerance, when one listener fails, other listeners take over.

Improved Exception Handling and Errors Tracing

If you have configured one or more custom exceptions in the repository, the code generator component of the adapter can read these exceptions from the repository and convert them into Java exception classes. These classes can then be used both by the adapter and by the EJB for enhanced error handling.

Multi-byte Data

The adapter provides support for multi-byte data. This ensures that the adapter can understand and transform data containing multi-byte characters, such as S-JIS (Japanese), EUC-CN (Chinese), EUC_KR (Korean), and so on.

Support for Dual Message Transports

The adapter supports the following message transports:



• TIBCO Rendezvous transport — This transport uses subject-based addressing to provide support for both multicast or broadcast and point-to-point communications. You can configure the delivery modes of the messages and specify the wire format to be used when you configure the adapter service.

• JMS transport — TIBCO Enterprise Message Service must be installed to use the JMS transport. The JMS administration interfaces allow you to create and manage administered objects such as Connection Factories, Topics, and Queues. JMS clients can retrieve references to these objects by using Java Naming and Directory Interface (JNDI). Creating static administered objects allows clients to use these objects without having to implement the object within the client. When a JMS client starts, it performs a JNDI lookup for the connection factories that it needs. For details on JNDI, see TIBCO Enterprise Message Service User’s Guide. You can specify the connection factory type and the delivery mode to be used when you configure the adapter service.

Internationalization Support

TIBCO Adapter for EJB provides internationalization support based on the Unicode support provided by the TIBCO Adapter SDK. Support is provided for string data only. Schema, metadata, error messages, and all other non-string information do not support extended character sets. Currently, the valid input encoding types are ASCII, LATIN_1, and UTF-8.


| 17

Chapter 2 Installation

This chapter explains how to install the adapter on Microsoft Windows and UNIX systems.

Topics

• Preparing your Environment for Installation, page 18

• Pre-Installation Worksheet, page 24

• Installer Overview, page 26

• Installation Registry, page 29

• Adapter Components and Compatible Software, page 32

• Installing on Microsoft Windows, page 34

• Installing on UNIX Systems, page 41

• Migrating a 4.x Repository for Use with TIBCO Designer 5.x, page 47

• Installation FAQs and Troubleshooting, page 51

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. Please see Table 4 on page 34 and Table 5 on page 41 for the availability of this software version on a specific operating system platform.


18 | Chapter 2 Installation

Preparing your Environment for Installation

The most time-consuming part of an adapter installation is the collection of environment information and parameters. This section helps you complete this process. It provides a check list of parameters you should obtain from various system administrators within your organization before installing the adapter. Note that obtaining an application server account can take some time depending on your corporate policies — so plan in advance!

Operating System RequirementsObtain the following information from the administrator of the machine on which you plan to install the adapter:

Username and password to access the system and run the adapter:

Do you have the required credentials to run the installer?

• On Microsoft Windows, administrator privileges are required to install.

• On UNIX systems, you can install as root or a regular user. See Installer Account on page 35 for details.

• Note that the TIBCO Runtime Agent (TRA) must be installed prior to installing the adapter and the adapter installation always places files under the TIBCO root directory that was set when the TRA was installed.

Is there enough space on that disk or partition to install the adapter? The adapter needs space in your temp area and the directory where it is installed.

• See Installation Registry on page 29 for details about temp folder space requirements on Microsoft Windows and UNIX systems.

• See Table 4 on page 34 for Microsoft Windows installations

• See Table 5 on page 41 for UNIX System installations.

System name:

System IP address:

Username:

Password:


Preparing your Environment for Installation | 19

You must have write permissions to these directories to install the adapter. In addition, on UNIX systems certain other permissions must be set to run the adapter. See Permission Requirements on UNIX Systems on page 46 for details.

• To run the adapter you must have permissions to access the project where the adapter configuration is stored.

• Depending on whether TIBCO Administrator is used to set access permissions, you may need an account identified by Administrator. See the TIBCO Administrator User’s Guide for details.

Determine how the adapter installation files are to be transferred to this system. The installation files can be downloaded from download.tibco.com (if you have an account setup to download). Do you plan to use FTP, NFS, HTTP, or install from a CD?

Application Server RequirementsDetermine which application server versions are supported. The following table lists the available application servers:

Table 1 Supported application servers and JVM libraries on Microsoft Windows and UNIX systems

Application Server OS JVM Example

BEA WebLogic Application Server 7.0, BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, SP6, and SP7

Microsoft Windows

BEA JVM 1.3.1_03 or Sun JVM 1.3.1_03

C:/bea/jdk131/jre/bin/hotspot/jv

m.dll

Solaris BEA JVM 1.3.1_03 or Sun JVM 1.3.1_03

/usr/bea/jdk131/jre/lib/sparc/ho

tspot/libjvm.so

HP-UX BEA JVM 1.3.1_03 or Sun JVM 1.3.1_03

/usr/bea/jdk131/jre/lib/PA_RISC2

.0/hotspot/libjvm.sl

Linux BEA JVM 1.3.1_03 or Sun JVM 1.3.1_03

/usr/bea/jdk131/jre/lib/i386/cli

ent/libjvm.so

AIX BEA JVM 1.3.1_03 or Sun JVM 1.3.1_03

/home/tibuser/jdk131/jre/sh/classic/libjvm.a



BEA WebLogic Application Server 8.1, BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5, or SP6

Microsoft Windows

BEA JVM 1.4.2_05 or Sun JVM 1.4.2_05

C:/bea/jdk142/jre/bin/client/jvm

.dll



tspot/libjvm.so






ent/libjvm.so



BEA WebLogic Application Server 9.0, 9.1, and 9.2

Microsoft Windows

BEA JVM 1.4.2_05 or Sun JVM 1.4.2_05

C:/bea/jdk142/jre/bin/client/jvm

.dll



tspot/libjvm.so






ent/libjvm.so



IBM's WebSphere Application Server 5.1

Microsoft Windows

IBM WebSphere JVM

C:/AppServers/websphere/jdk/jre/

bin/classic/jvm.dll

Solaris IBM WebSphere JVM

/AppServers/websphere/java/jre/l

ib/sparc/libjvm.so

HP-UX IBM WebSphere JVM


ib/sparc/libjvm.sl

Linux IBM WebSphere JVM


ib/sparc/libjvm.so

AIX IBM WebSphere JVM





IBM's WebSphere Application Server 6.0, 6.0.2, and 6.1

Microsoft Windows

IBM WebSphere JVM

C:/AppServers/websphere/jdk/jre/

bin/classic/jvm.dll

Solaris IBM WebSphere JVM


ib/sparc/libjvm.so

HP-UX IBM WebSphere JVM


ib/sparc/libjvm.sl

Linux IBM WebSphere JVM


ib/sparc/libjvm.so

AIX IBM WebSphere JVM


JBoss Application Server 3.2.3

Microsoft Windows

Sun JVM 1.4.1 C:/jdk1.4.1/jre/bin/hotspot/jvm.

dll

Solaris Sun JVM 1.4.1 /solaris/java/1.4.1/jre/lib/spar

c/client/libjvm.so

HP-UX Sun JVM 1.4.1 /hp/java/1.4.1/jre/lib/sparc/PA_

RISC/hotspot/libjvm.sl

Linux Sun JVM 1.4.1 /linux/java/1.4.1/jre/lib/i386/c

lient/libjvm

AIX Sun JVM 1.4.1 /home/tibuser/jdk141/jre/sh/classic/libjvm.a

JBoss Application Server 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4

Microsoft Windows

Sun JVM 1.4.2_06 C:/jdk1.4.2/jre/bin/client/jvm.dll

Solaris Sun JVM 1.4.2_06 /solaris/java/1.4.2/jre/lib/sparc/client/libjvm.so

HP-UX Sun JVM 1.4.2_06 /hp/java/1.4.2/jre/lib/sparc/PA_RISC/hotspot/libjvm.sl

Linux Sun JVM 1.4.2_06 /linux/java/1.4.2/jre/lib/i386/client/libjvm

AIX Sun JVM 1.4.2_06 /home/tibuser/jdk142/jre/sh/classic/libjvm.a




Oracle 9i Application Server 9.0.3

Microsoft Windows

Sun JVM 1.3.1 C:/jdk1.3/jre/bin/hotspot/jvm.dl

l

Solaris Sun JVM 1.3.1 /export/home/ejb/j2sdk1_3_0_1/jr

e/lib/sparc/hotspot/libjvm.so

HP-UX Sun JVM 1.3.1 /export/home/ejb/j2sdk1_3_0_1/jr

e/lib/sparc/hotspot/libjvm.sl

Linux Sun JVM 1.3.1 /export/home/ejb/j2sdk1_3_0_1/jr



Oracle 10g Application Server 9.0.4, 10.1.2 and 10.1.3

Microsoft Windows

Sun JVM 1.4.2 C:/jdk1.4/jre/bin/hotspot/jvm.dll

Solaris Sun JVM 1.4.2 /export/home/ejb/j2sdk1_4_0_2/jre/lib/sparc/hotspot/libjvm.so

HP-UX Sun JVM 1.4.2 /export/home/ejb/j2sdk1_4_0_2/jr

e/lib/sparc/hotspot/libjvm.sl

Linux Sun JVM 1.4.2 /export/home/ejb/j2sdk1_4_0_2/jr



Sun Java System Application Server Platform Edition 7 and 8.1

Microsoft Windows

Sun JVM 1.4.0 C:/jdk1.4/jre/bin/hotspot/jvm.

dll

Solaris Sun JVM 1.4.0 /usr/jdk1.4/jre/lib/PA_RISC2.0/c

lient/libjvm.so

HP-UX Sun JVM 1.4.0 /usr/jdk1.4/jre/lib/PA_RISC2.0/c

lient/libjvm.sl

Linux Sun JVM 1.4.0 /usr/jdk1.4/jre/lib/PA_RISC2.0/c

lient/libjvm.so





Obtain the following information from your application server administrator. This is a list of application server parameters that you will need to configure the adapter, along with the application server credentials that the adapter requires.

Note that the parameters listed here use application server terminology. This is the information that you would typically be prompted for during an application server installation.

Application Server User Information

Obtain the following information for the account you will use to access the application server. The default username and password to access an application server is sadmin/sadmin.

Sun Java System Application server Platform Edition 8.1 and 8.2

Microsoft Windows

Sun JVM 1.4.2_05 C:/jdk1.4.2_05/jre/bin/client/jvm.dll

Solaris Sun JVM 1.4.2_05 /usr/ jdk1.4.2_05/jre/lib/PA_RISC2.0/client/libjvm.so

HP-UX Sun JVM 1.4.2_05 /usr/ jdk1.4.2_05/jre/lib/PA_RISC2.0/c lient/libjvm.sl

Linux Sun JVM 1.4.2_05 /usr/ jdk1.4.2_05/jre/lib/PA_RISC2.0/client/libjvm.so

AIX Sun JVM 1.4.2_05 /home/tibuser/jdk142/jre/sh/clas

sic/libjvm.a


Username:

Password:



Pre-Installation Worksheet

Use this form to capture the information you will need to collect before starting installing the adapter

Adapter Machine Information

Field Name Field Description Field Value

Hostname

(Example: adapter1.tibco.com)

Name of the machine on which the adapter is being installed.

IP address

(Example: 192.168.12.12)

IP address of the machine on which the adapter is being installed.

User account

(Example: administrator)

User account to be used for the installation.

User domain (if Microsoft Windows)

(Example: ENGR2)

Network domain to which the user belongs.

User password

Disk and path on which to install adapter

(Example: C:\tibco)

How will machine be accessed

[ ] directly [ ] terminal server [ ] xterm [ ] telnet

[ ] other: ………………………

How will installation files be transferred to machine

[ ] CD-drive [ ] internet download [ ] FTP to machine

[ ] network disk mounting


Pre-Installation Worksheet | 25

Application Server Information

Application Server SoftwarePlease specify where software for the application server can be found within your organization:

[ ] It's already installed on adapter machine.

Location on disk: ………………………….

[ ] Installation files are available via:

FTP (Server: ………… User: ………… Password: ……… )

Disk mount (full path: ………………………………………..)

CD provided during install by (name/extension): ………………………..

Field Name Field Description Field Value

User account

(Example: jsmith)

User account to be used for the installation.

User password

Application server hostname

(Example: adapter1.tibco.com)

Port

Application server home Location of the application server installation.



Installer Overview

The installer allows you to run it in different modes. Each mode is supported on all platforms.

• GUI mode

• Console mode

• Silent mode

GUI Mode

In GUI mode, the installer presents panels that allow you to make choices about product selection, product location, and so on. When you invoke the installer by double-clicking the icon, GUI mode is used.

Console Mode

Console mode allows you to run the installer from the command prompt or terminal window. This is useful if your machine does not have a Windows environment.

Silent Mode

Silent mode either installs using default settings or uses a response file that was saved during an earlier installation. Silent mode installs without prompting you for information.

• If no response file has been recorded earlier and you invoke the installer with the -silent argument, the default installation parameters are used.

• If a response file exists, and the installer is started with -options <responseFileName> as an argument, the installer uses the values specified by the user when the response file was generated.

Upgrading an AdapterSoftware from TIBCO uses three numbers to indicate whether the release is major, minor, or a patch. For example, 5.0.0 indicates a major release, 5.1.0 indicates a minor release and 5.1.1 indicates a patch release. The installer for a patch release performs an automatic upgrade. For example, the installer automatically upgrades TRA 5.0.0 to 5.0.1 by overwriting the contents of the 5.0 directory.


Installer Overview | 27

For a major and minor release, the installer prompts whether you wish to upgrade, and informs you if incompatible products are on your system. If you proceed, major or minor releases are installed under a new directory that is named using the major or minor release numbers.

For example, if you have installed the 5.0.0 release and are upgrading to a 5.1.0 minor release, it will be installed under the 5.1 directory. This allows both the 5.0 and 5.1 releases to coexist on the same machine.

If you are upgrading the adapter, or reinstalling a clean version of the software, you may uninstall the product first or allow the installer to perform the upgrade or reinstall.

Uninstalling the AdapterIf another product is dependent on the product you wish to uninstall, you are informed that you must uninstall the other product first.

Microsoft Windows

Use one of the following options to uninstall the Adapter from the Microsoft Windows platform:

• Click Start>Programs>TIBCO><Adapter>Uninstall

• Navigate to the _uninst directory located in the Adapter installation directory and invoke the Tibuninstall.exe program.

• Click Start>Programs>TIBCO>TIBCO Installation Manager

• Use Add/Remove Programs from the Control Panel.

UNIX

Use one of the following options to uninstall the Adapter from the supported UNIX platform:



• Navigate to the _uninst directory located in the Adapter installation directory and invoke the Tibuninstall.bin program.

• Run TIBCO Installation Manager which is located in the <install-path>/tibco/TibcoInstallationManager.bin.

Uninstallation of the adapter on AIX platform

To uninstall the adapter on AIX:

1. Under the folder <ADEJB_HOME>/_uninstall, create a blank file with the name Tibuninstall.ja.

2. Open the file and enter –Xmx192m.

3. Save and close the file.

4. Run the Tibuninstall.bin program.


Installation Registry | 29

Installation Registry

The installer maintains an installation registry. The registry location depends on platform. This section explains where the registry files are located. The files have vpd as a prefix, which stands for Vital Product Database. Note that the installer does not recognize TIBCO ActiveEnterprise 4.x products.

Microsoft Windows PlatformsActiveEnterprise 5.x products maintain the installation registry in the SystemDrive:\WINDOWS directory. The following files represent the installation registry:

SystemDrive:\WINDOWS\vpd.propertiesSystemDrive:\WINDOWS\vpd.properties.tibco.systemName

Installer Disk Space Requirements in Temporary Area

The entire package is extracted into a temp folder, typically SystemDrive:\Temp or SystemDrive:\Documents and Settings\<user_name>\Local Settings\Temp.

The installer requires 200 MB of free space in the temp directory.

UNIX PlatformsIf installation is performed by a regular user (non-root), the installation registry is maintained in the following files in the user's home directory:

User_Home_Directory/vpd.propertiesUser_Home_Directory/vpd.properties.tibco.systemName

If installation is performed by super-user (root), the installation registry is maintained as follows:

• On Solaris, HP-UX, and AIX in the root user’s home directory (which is /) as two vpd files.

• On Linux, in the /root directory as two vpd files.

Do not edit, modify, rename, move, or remove any of the registry vpd files.



Installer Disk Space Requirements in Temporary Area

The installer launcher first extracts a Java Virtual Machine (JVM) in a temporary directory and uses this JVM to launch itself. The size of the extracted JVM differs from platform to platform.

On UNIX platforms the following disk space is required in the temporary area:

• On Solaris, 50 MB of free disk space in /var/tmp

• On HP-UX, 85 MB of free disk space in /var/tmp

• On AIX, 100 MB of free disk space in /var/tmp

Verify the name of the temporary folder.

• On Linux, 50 MB of free disk space in /tmp

If your system does not have sufficient free disk space in the above temporary area, you can still run the installer with a different temporary area by using the following option when starting the installer:

<install_package_name>.bin -is:tempdir /new_tmp

where /new_tmp has sufficient free disk space.

Disk Space Requirement in User's Home Directory

On UNIX platforms when a regular (non-root) user installs a TIBCO 5.x product, the installation registry (two vpd files) is maintained in the user's home directory. As more products are installed, entries are added into these vpd files.

The user's home directory must at least have 500 KB of free disk space.

Installation HistoryThe installer and uninstaller creates a file called TIBCOInstallationHistory.xml in the same location where the installation registry is created. Each time an installation and uninstallation is performed, entries are appended to the file.

On Microsoft Windows: SystemDrive:\WINDOWS\TIBCOInstallationHistory.xml

On UNIX: Users_Home_Directory/TIBCOInstallationHistory.xml

The file TIBCOInstallationHistory.xml therefore contains the record of all installation and uninstallation activities of all products, features and components.


Installation Registry | 31

Do not edit, modify, rename, move, or remove the TIBCOInstallationHistory.xml file.



Adapter Components and Compatible Software

You can install different adapter components on different machines. For example, you can run the run-time adapter on one machine and install the design-time components on another machine. This allows you to configure an adapter on one machine and run it on another.

Adapter ComponentsTable 2 describes the adapter components in the adapter installation package.

Required and Optional TIBCO ProductsDepending on the tasks you wish to perform, you must install one or more other TIBCO products. The next table describes required and optional products and their purpose.

Table 2 TIBCO Adapter components

Component Description

Run-time adapter This process does the actual work of passing and converting data to and from the vendor application. Parameters of data exchanges are stored in projects created using the adapter palette.

Adapter executable

This is a component of the run-time adapter. It is included as part of the EjbAdapter.jar file, and handles inbound communications.

Connector library This is component of the run-time adapter. It is included as part of the AeConnector.rar or AeConnector.jar files, and handles outbound communications.

Adapter palette Adapter-specific GUI that is loaded in TIBCO Designer (see next section for details) at configuration time.


Adapter Components and Compatible Software | 33

Table 3 Required and Optional TIBCO Products

Component Purpose

TIBCO Runtime Agent Required. TIBCO Runtime Agent supplies a number of TIBCO and third-party libraries used by the adapter and other TIBCO products both at design-time and run-time. This includes, for example, TIBCO Rendezvous software.

You must install TIBCO Runtime Agent on each machine that hosts an adapter. TIBCO Runtime Agent must be installed before you install the adapter.

TIBCO Administrator Required. TIBCO Administrator includes the following modules:

• User Management. Management of authentication, roles and users, that is, connecting roles (groups) and users to access control lists (ACLs). This includes security for server-based projects at design-time and for deployed applications at runtime.

• Resource Management. Monitoring of machines and of all running applications in a TIBCO administration domain. Alerts can be created, for example, to notify an administrator if the number of processes or disk usage exceed a certain number.

• Application Management. Uploading of Enterprise Archive (EAR) files, creation, configuration, deployment, and monitoring of applications. This console is also used to start and stop applications.

TIBCO Administrator is available as a separate installation and can be installed after installing the adapter.

Note: If you use JCA 1.5-compliant adapter, TIBCO Administrator is not required.

TIBCO BusinessWorks Optional. TIBCO BusinessWorks is a scalable, extensible, and easy to use integration platform that allows you to develop integration projects. TIBCO Adapters are typically part of integration projects created using TIBCO BusinessWorks.

TIBCO BusinessWorks is available as a separate installation and can be installed after installing the adapter.

For release versions of optional and required software, see the TIBCO Adapter for EJB Readme.txt file.



Installing on Microsoft Windows

Before starting the installation procedure, review the topics in this section to determine that your system meets the basic requirements and that you have the prerequisite software installed.

The following is a list of prerequisites for installing the adapter on Microsoft Windows systems. See Installer Disk Space Requirements in Temporary Area on page 29 for additional disk space requirements.

The following table also lists the platform-specific installation packages, where <version_num> is the Adapter release number. For example, the installation package name for the TIBCO Adapter for EJB 5.3 on the Microsoft Windows 2000 platform is TIB_adejb-simple_5.3.0_w32.exe.

Supported Application Servers

Before proceeding to adapter installation, ensure you can connect to the target application using the vendor client.

The adapter works with the following:

• BEA WebLogic Application Server 7.0 and BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, SP6, and SP7

The standalone adapter can run on any of the platforms listed below, while the connector component always runs within the application server.

Table 4 Supported platforms, package names and disk space for Microsoft Windows

Platform Hardware Platform Package Names Disk Space

(MB)

Microsoft Windows 2000 x86

TIB_adejb-simple_<version_num>_w32.exe

30

Microsoft Windows XP Professional

x86 30

Microsoft Windows Server 2003

x86 30

The following application servers are supported by the adapter on the platforms listed in this readme if those application servers are supported on that platform by the application server vendor.


Installing on Microsoft Windows | 35

• BEA WebLogic Application Server 8.1 and BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5, and SP6

• BEA WebLogic Application Server 9.0, 9.1, and 9.2

• IBM WebSphere Application Servers 5.1, 6.0, 6.0.x, and 6.1.

• JBoss Application Server 3.2.3

• JBoss Application Server 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4

• Oracle 9i Application Server 9.0.3

• Oracle 10g Application Server 9.0.4, 10.1.2 and 10.1.3

• Sun Java System Application Server Platform Edition 7

• Sun Java System Application server Platform Edition 8.1

Table 1 on page 19 shows the supported application servers and the JVM libraries used. While installing the adapter, you must specify the following for the application server that you will use:

• The location of the application server installation.

• JVM library file location. Select the JVM library file depending on the selected application server.

• JDK_HOME—Set the value of this variable, which is the name of the directory in which you have installed JDK. The value is used by the installer when you install the adapter.

TIBCO Runtime Agent Must be Installed Before the Adapter

Before you can install the adapter, you must install the TIBCO Runtime Agent. If you use the Typical installation, the installer places all libraries and other products required by the adapter into the TIBCO HOME directory.

During installation, the adapter installer checks for the availability of all dependent products in the target system. If any of the dependencies are not available, the installer will immediately exit. Otherwise, installation will proceed.

Installer Account

You must have administrator privileges for the machine on which the adapter is installed.

If you do not have administrator privileges, the installer will exit. You must then log out of the system and log in as a user with the required privileges, or request your system administrator to assign the privileges to your account.



Installing from Network Drive

If you intend to install the product on a network drive, you must ensure that the account used for installation has permission to access the network drive.

Installing on Microsoft Windows 2000 and 2003 Terminal ServerThere are two modes in Microsoft Windows Terminal Server: Execute and Install. Users are logged on by default in the Execute mode, which allows them to run applications. To install an adapter so that everyone can use it, log on as administrator in the Install mode. When the adapter is installed in the Install mode, the installation registry is maintained in SystemDrive:\WINDOWS\.

The best way to install the adapter on Microsoft Windows Terminal Server is to use the Add/Remove Programs control panel applet. This automatically sets your mode to Install during the installation and then back to Execute afterwards. Alternatively, you can manually change your mode to Install before starting the installation by typing the following at a command prompt:

C:\> change user /install

Change back to Execute mode after installation is complete by typing:

C:\> change user /execute

To check your current mode, type the following:

C:\> change user /query

Installing the Adapter on Microsoft WindowsYou can either download the adapter package or install the package from a CD. The installer prompts you to accept the license agreement, then to choose to perform a typical install or custom install.

• A typical install has minimal prompts and installs standard components in default locations.

• A custom install prompts you to choose which components of the product suite to install and installs only those components.

Microsoft Windows Terminal Server must be running in the remote admin mode, not application sharing mode. The adapter is not supported if installed on a machine that is using Microsoft Windows Terminal Server in the application sharing mode.



The installer checks your system for the installation home directory that was established when TIBCO Runtime Agent was installed. The adapter is installed under the installation home directory.

Use one of the following modes to install the software. The examples assume you are installing TIBCO Adapter for EJB 5.3 on a Microsoft Windows 2000 platform.

Install Using GUI Mode

GUI Mode allows you input values in panels. Type the following at the command prompt:

TIB_adejb-simple_<version_num>_w32.exe

Install Using Console Mode

Console mode allows you to install the software in a non-windows environment. The installer will prompt you for values. Type the following at the command prompt:

TIB_adejb-simple_<version_num>_w32.exe -is:javaconsole -console

When running in console mode you can move through the installation process as described next:

Enter Key = Moves forward in the installer2 = Goes back to previous screen3 = Cancels the Wizard and exits the installation or uninstallation4 = Redisplays the current screen

Install Using Silent Mode

Silent mode allows you to install the software without prompts. Type the following at the command prompt:

TIB_adejb-simple_<version_num>_w32.exe -silent

Install and Generate a Response File

You can generate a response file during installation which you can later use to invoke the installer with the selected values as default values (GUI mode) or as selected values (silent mode).

To install and generate a response file, type the following at the command prompt:



TIB_adejb-simple_<version_num>_w32.exe -options-record C:\directory\<responseFile>

Install Using a Response File

You can use a previously generated response file for installation. For non-silent modes, the response file determine the defaults that are presented. For silent mode, the response file determines what will be installed.

To install using a response file, type the following at the command prompt: TIB_adejb-simple_<version_num>_w32.exe -options

C:\directory\<responseFileName>

Combining OptionsYou can combine the different available options. For example, to install in silent mode using a response file, use: TIB_adejb-simple_<version_num>_w32.exe -silent -options <responseFileName>

To install using Console mode and generate a response file, use: TIB_adejb-simple_<version_num>_w32.exe -is:javaconsole -console -options-record <responseFileName>

Installing the Adapter to Connect to Multiple Application ServersThe adapter can be installed without selecting any application server during the installation. The adapter services can later be configured to connect to different application servers, through the adapter palette in TIBCO Designer.

To install the adapter for connecting to multiple application servers, select Custom installation, and then Multiple Application Servers on the following screen.

The response file does not record selections at the component level. It does record all other selections, for example, which products you wished to install.



While installing the adapter, you must specify only the JDK location. Use JDK version 1.4.2 if you wish to use this feature.

Post-Installation

The .tra files shipped with the adapter do not contain the application servers’ client libraries in the CLASSPATH. Therefore, after installation, add the jar file(s) to the tibco.env.CUSTOM_CP_EXT variable for the application server you will be using.

See Table 10, Locations of JAR files for the supported application servers, on page 235 for the list of jar files that should be added to the CLASSPATH, for each application server.

Installing the Adapter on a Machine other than the Application Server MachineWhile installing the adapter, you must specify the correct JDK location and a directory that contains application server installation, as the application server home directory. This directory should be accessible to the adapter runtime as well.

The tra files shipped with the adapter refer to the application server's J2EE implementation jar file. While installing the adapter, the entries in the tra files are updated to use the specified application server home directory.

Post-InstallationAfter installing the TIBCO Adapter for EJB software on Microsoft Windows, make sure that the environment variables have been set prior to using the software.

Configuring adapter instances where the service(s) connect to the IBM WebSphere application server as well as to other application servers is not recommended.

Creating a separate adapter instance is recommended for services that connect to the IBM WebSphere application server(s). Also, in the .tra file used by the adapter process to start these services, the variables tibco.env.TIB_JAVA_HOME, tibco.env.JVM_LIB_DIR, and tibco.env.JVM_LIB_PATH must be modified to point to IBM java.

The client libraries of all the application servers to which the adapter services are connecting, must be added to the CLASSPATH (tibco.env.CUSTOM_CP_EXT variable in the .tra files).

For details on running various services using this configuration, see Running the Adapter and Application Server on Different Machines on page 234.



Setting the Environment Variables

The CLASSPATH environment variable must include the location of the Java Runtime Environment rt.jar file.

Make sure that the system variables listed in the following table are set:

Internationalization Support

To enable internationalization support for the adapter, the following must be set:

• The international version of the JRE is installed and used by the adapter.

• The repository server repo.encoding parameter specifies the character encoding for repository communication with the adapter. This parameter must be set to UTF-8.

See the TIBCO Repository Installation and Administration Guide for more information about Unicode support.

System Variable Name Description

TIBCO_TRA_HOME Location of TIBCO Runtime Agent installa-tion.

Example: C:\tibco\tra\5.3

TIBCO_ADEJB_HOME TIBCO Adapter for EJB installation direc-tory.

Example:C:\tibco\adapter\adejb\5.3

TIBCO_EXTERNAL This variable is used to locate the j2ee.jar file. This jar contains the Connector class files, which are required only for Java 2 Platform, Enterprise Edition application servers. You need to supply the full path along with the jar file name.

Example:C:\j2sdkee1.3.1\lib\j2ee.jar

TIBCO_JAVA_HOME JRE home directory.

Example:C:\TIBCO\tra\5.3\jre\1.4.1


Installing on UNIX Systems | 41

Installing on UNIX Systems

Your operating system must meet the minimum patch requirements listed next. See Installer Disk Space Requirements in Temporary Area on page 30 for additional disk space requirements.

The following table also lists the platform-specific installation packages, where <version_num> is the Adapter release number. For example, the installation package name for the TIBCO Adapter for EJB 5.3.0 on the HP-UX 11.0 platform is TIB_adejb-simple_5.3.0_h7_110.bin.

The standalone adapter can run on any of the platforms listed below, while the connector component always runs within the application server.

Table 5 Supported platforms, package names, patches and disk space for UNIX systems

Platform Hardware Package NamesDisk Space (MB)

Solaris 8 SPARC TIB_adejb-simple_<version_num>_sol7_sparc.bin

30 MB

Solaris 9

Solaris 10

HP-UX 11.0 PA-RISC TIB_adejb-simple_<version_num>_hpux111_hppa.bin

30 MB

HP-UX 11i

HP-UX 11i V2

IA64 Itanium

TIB_adejb-simple_<version_num>_hpux112_ia64.bin

30 MB

Red Hat Linux 3.0

x86 TIB_adejb-simple_<version_num>_linux24gl23_x86.bin

30 MB

Red Hat Linux 4.0

AIX 5.2 POWER TIB_adejb-simple_<version_num>_aix52_power.bin

30 MB

AIX 5.3



Supported Application Servers

Before proceeding to adapter installation, ensure you can connect to the target application using the vendor client.

The adapter works with the following:

• BEA WebLogic Application Server 7.0 and BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, SP6, and SP7

• BEA WebLogic Application Server 8.1 and BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5, or SP6

• BEA WebLogic Application Server 9.0, 9.1, and 9.2

• IBM WebSphere Application Servers 5.1, 6.0, 6.0.x, and 6.1.

• JBoss Application Server 3.2.3

• JBoss Application Server 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4

• Oracle 9i Application Server 9.0.3

• Oracle 10g Application Server 9.0.4, 10.1.2 and 10.1.3

• Sun Java System Application Server Platform Edition 7

• Sun Java Application server Platform Edition 8.1

Table 1 on page 19 shows the supported application servers and the JVM libraries used. While installing the adapter, you must specify the following for the application server that you will use:

• The location of the application server installation.

• JVM library file location. Select the JVM library file depending on the selected application server.

• JDK_HOME—Set the value of this variable, which is the name of the directory in which you have installed JDK. The value is used by the installer when you install the adapter.

TIBCO Runtime Agent Must be Installed Before the Adapter

Before you can install the adapter, you must install the TIBCO Runtime Agent. If you use the Typical installation, the installer places all libraries and other products required by the adapter into the TIBCO HOME directory.

The following application servers are supported by the adapter on the platforms listed in this readme if those application servers are supported on that platform by the application server vendor.



Installer Account

TIBCO 5.x products can be installed by a regular (non-root) user and super-user (root). Different users can install the same product at different locations.

Product dependencies at install time are resolved at user level through the installation registry maintained at user's home directory. See Installation Registry on page 29 for more information.

Windows Environment

A window environment such as CDE (i.e. X Windows) is required to run the installer in GUI mode. It is not required for a console installation.

Installing the Adapter on UNIXAfter unpacking the software and accepting the license agreement, you can choose to perform a typical install or custom install.

• A typical install has minimal prompts and installs standard components in default locations.

• A custom install prompts you to choose which pieces of the product suite to install and installs only those components.

The installer checks your system for the installation home directory that was established when TIBCO Runtime Agent was installed. The adapter is installed under the installation home directory.

Use one of the following modes to install the software. The examples assume you are installing the adapter on Solaris 8.

Install Using GUI Mode

GUI Mode allows you input values in panels. Type the following in a terminal window:

% ./TIB_adejb-simple_<version_num>_s4_57.bin

Install Using Console Mode

Console mode allows you to install the software in a non-Windows environment. The installer will prompt you for values. Type the following in a terminal window:

% ./TIB_adejb-simple_<version_num>_s4_57.bin -is:javaconsole -console



When running in console mode you can move through the installation process as described next:

Enter Key = Moves forward in the installer2 = Goes back to previous screen3 = Cancels the Wizard and exits the installation or uninstallation4 = Redisplays the current screen

Install Using Silent Mode with Default Values

Silent mode allows you to install the software without prompts using default values. Type the following in a terminal window:

% ./TIB_adejb-simple_<version_num>_s4_57.bin -silent

Install and Generate a Response File

You can generate a response file during installation which you can later use to invoke the installer with the selected values as default values (GUI mode) or as selected values (silent mode).

To install and generate a response file, type the following at the command prompt:

% ./TIB_adejb-simple_<version_num>_s4_57.bin -options-record /dir/<responseFile>

Install Using a Response File

You can use a previously generated response file for installation. For non-silent modes, the response file determine the defaults that are presented. For silent mode, the response file determines what will be installed.

To install using a response file, type the following at the command prompt: % ./TIB_adejb-simple_<version_num>_s4_57.bin -options /dir/<responseFileName>

Combining OptionsYou can combine the different available options. For example, to install in silent mode using a response file, use: % ./TIB_adejb-simple_<version_num>_s4_57.bin -silent -options <responseFileName>

To install using Console mode and generate a response file, use:

The response file does not record selections at the component level. It does record all other selections, for example, which products you wished to install.



% ./TIB_adejb-simple_<version_num>_s4_57.bin -is:javaconsole -console -options-record <responseFileName>

Installing the Adapter to Connect to Multiple Application ServersThe adapter can be installed without selecting any application server during the installation. The adapter services can later be configured to connect to different application servers, through the adapter palette in TIBCO Designer.

To install the adapter for connecting to multiple application servers, select Custom installation, and then Multiple Application Servers on the following screen.

While installing the adapter, you must specify only the JDK location. Use JDK version 1.4.2 if you wish to use this feature.

Post-Installation

The .tra files shipped with the adapter do not contain the application servers’ client libraries in the CLASSPATH. Therefore, after installation, add the jar file(s) to the tibco.env.CUSTOM_CP_EXT variable for the application server you will be using.

See Table 10, Locations of JAR files for the supported application servers, on page 235 for the list of jar files that should be added to the CLASSPATH, for each application server.

Installing the Adapter on a Machine other than the Application Server MachineWhile installing the adapter, you must specify the correct JDK location and a directory that contains application server installation, as the application server home directory. This directory should be accessible to the adapter at runtime as well.

Configuring adapter instances where the service(s) connect to the IBM WebSphere application server as well as to other application servers is not recommended.

Creating a separate adapter instance is recommended for services that connect to the IBM WebSphere application server(s). Also, in the .tra file used by the adapter process to start these services, the variables tibco.env.TIB_JAVA_HOME, tibco.env.JVM_LIB_DIR, and tibco.env.JVM_LIB_PATH must be modified to point to IBM java.

The client libraries of all the application servers to which the adapter services are connecting, must be added to the CLASSPATH (tibco.env.CUSTOM_CP_EXT variable in the .tra files).



The tra files shipped with the adapter refer to the application server's J2EE implementation jar file. While installing the adapter, the entries in the tra files are updated to use the specified application server home directory.

Post Installation Tasks on UNIXAfter the adapter installation, you must set the permission requirements.

Permission Requirements on UNIX Systems

All adapter users must have read, write, and execute permissions for the following directories:

$TIBCO_HOME/adapter/adejb/<version_num>/bin $TIBCO_HOME/adapter/adejb/<version_num>/logs$TIBCO_HOME/tra/<version_num>/logs$TIBCO_HOME/logs

For example, if the adapter has been installed in /opt/tibco, the user who installed the adapter can make these directories writable for all other users by executing the following commands:

% chmod a+w /opt/tibco/adapter/adejb/<version_num>/bin/% chmod a+w /opt/tibco/adapter/adejb/<version_num>/bin/logs% chmod a+w /opt/tibco/tra/<version_num>/logs

For details on running various services using this configuration, see Running the Adapter and Application Server on Different Machines on page 234.

The TIBCO Rendezvous daemon inherits the WebLogic application server port. On HP-UX, you will not be able to restart the application server until you terminate the daemon.

The Resource Adapter (AeConnector.rar) uses adejb and adejb as username and password respectively.


Migrating a 4.x Repository for Use with TIBCO Designer 5.x | 47

Migrating a 4.x Repository for Use with TIBCO Designer 5.x

You can use the adapter migration tool to migrate a 4.x repository to TIBCO Designer 5.x.

You can use the migrate tool for the following tasks:

• Migrating an Adapter Instance

• Migrating Multiple Adapter Instances Simultaneously

Migrating an Adapter InstanceYou can migrate an adapter instance by modifying the migrate.tra file located in the <ADEJB_HOME>\bin directory.

To migrate an adapter instance using the migrate.tra file, update the application.args property to include the -i or -f options and the -m option as follows:

application.args [[-i <configURL>] -i...] [-f <configURL file>] [-m "markerstring"] <dat file>

For example:

application.args -i /tibco/private/adapter/Connector/RPC/Publisher

-m adejb

d:/tibco/adapter/adejb/<version_num>/examples/data/ejb_sample.dat

After modifying the migrate.tra file:

1. In a command window, go to the <ADEJB_HOME>\bin directory.

2. Run the following command:migrate

The following message is displayed:Sucessfully inserted "markerstring" marker in all specified instances in <dat file path and name>

For example, if you have modified the application.args property in the migrate.tra file as specified above, the following message is displayed:Successfully inserted adejb marker in all specified instances in d:/tibco/adapter/adejb/<version_num>/examples/data/ejb_sample.dat

Make a backup of the project you are migrating to TIBCO ActiveEnterprise 5.x before starting the migration process.



Migrating Multiple Adapter Instances SimultaneouslyYou can migrate multiple adapter instances simultaneously:

• Using Individual Configuration URLs

• Using a Configuration URL File

• Using the migrate.tra File

Using Individual Configuration URLs

If you use this option, you must provide multiple configuration URLs to the migration tool.

For example, the following command uses -i and will simultaneously migrate the specified instances in the ejb_sample.dat local repository using the adejb marker:

migrate -i /tibco/private/adapter/EJB/RPC/Subscriber -i /tibco/private/adapter/EJB/RPC/RPC -i /tibco/private/adapter/Connector/RPC -i /tibco/private/adapter/Connector/Publisher -i /tibco/private/adapter/EXAMPLE_SAP/SampleSubscriber -i /tibco/private/adapter/EXAMPLE_SAP/SamplePublisher -i /tibco/private/adapter/EXAMPLE_SAP/SampleRPCClient -i /tibco/private/adapter/EXAMPLE_SAP/SampleRPCServer -m "adejb" ejb_sample.dat

Using a Configuration URL File

You can use a configuration URL file with the -f option. Create a text file called myinstances.txt that contains the instances to be migrated. Include one instance per line, as follows:

/tibco/private/adapter/EJB/RPC/Subscriber/tibco/private/adapter/EJB/RPC/RPC/tibco/private/adapter/Connector/RPC/tibco/private/adapter/Connector/Publisher/tibco/private/adapter/EXAMPLE_SAP/SampleSubscriber/tibco/private/adapter/EXAMPLE_SAP/SamplePublisher/tibco/private/adapter/EXAMPLE_SAP/SampleRPCClient/tibco/private/adapter/EXAMPLE_SAP/SampleRPCServer

After you have created the file with the configuration URLs, run the following command in the <ADEJB_HOME>\bin directory:migrate -f myinstances.txt -m "adejb" ejb_sample.dat


Migrating a 4.x Repository for Use with TIBCO Designer 5.x | 49

Using the migrate.tra File

You can modify the migrate.tra file located in the <ADEJB_HOME>\bin directory and update the application.args property to include the -i or -f options and the -m option as follows:application.args [[-i <configURL>] -i...] [-f <configURL file>] [-m "markerstring"] <dat file>

For example:

application.args -i /tibco/private/adapter/EJB/RPC/Subscriber -i /tibco/private/adapter/EJB/RPC/RPC -i /tibco/private/adapter/Connector/RPC -i /tibco/private/adapter/Connector/Publisher -i /tibco/private/adapter/EXAMPLE_SAP/SampleSubscriber -i /tibco/private/adapter/EXAMPLE_SAP/SamplePublisher -i /tibco/private/adapter/EXAMPLE_SAP/SampleRPCClient -i /tibco/private/adapter/EXAMPLE_SAP/SampleRPCServer -m "adejb" ejb_sample.dat

After modifying the migrate.tra file:

1. In a command window, go to the <ADEJB_HOME>\bin directory.

2. Run the following command:migrate

The following message is displayed:Sucessfully inserted "markerstring" marker in all specified instances in <dat file path and name>

For example, if you have modified the application.args property in the migrate.tra file as specified above, the following message is displayed:Successfully inserted adejb marker in all specified instances in ejb_sample.dat

Migrating Remote or Server RepositoriesYou can migrate remote or server repositories by specifying tibcr@<repofilename>.

In the examples shown previously:

• For migrating an adapter instance, replace the dat file name and path with tibcr@<repofilename>.

For example, in -i /tibco/private/adapter/Connector/RPC/Publisher

-m adejb d:/tibco/adapter/adejb/<version_num>/examples/data/ejb

_sample.dat, replace D:/tibco/adapter/adejb/<version_num>/examples/data/ejb_sample.d

at with tibcr@ejb_sample.



• For migrating multiple adapter instances simultaneously, replace the dat file name with tibcr@<repofilename>. For example, in the command migrate -f myinstances.txt -m "adejb" ejb_sample.dat or in the application.args property, replace ejb_sample.dat with tibcr@ejb_sample.


Installation FAQs and Troubleshooting | 51

Installation FAQs and Troubleshooting

This section lists some common errors along with their causes and solutions.

Frequently Asked Questions

Where is the installation log file located?

Install and uninstall log files are created in the TIBCO_HOME\log directory.

What should I do, if JVM crashes when I run the installer?

The installer first extracts the bundled JVM into a temporary area and then uses it to launch itself. If for some reason, the JVM crashes, you could still run the installer using another JVM, preferably JVM 1.4.2 or higher. The syntax is:

TIB_adejb-simple_<version_num>_w32.exe -is:javahome C:\j2sdk1.4.2TIB_adejb-simple_<version_num>_s4_57.bin -is:javahome /opt/jre142

The javahome directory must contain bin/java.exe or bin/java.

The installer will use the externally supplied JRE to launch itself.

Will 5.1 installer recognize a 3.x or 4.x installation?

TIBCO products follow a three digit release numbering scheme:

Major.Minor.Maintenance

Product releases that differ in either Major or Minor numbers will be a separate installation, and will not recognize the old installation. In this case, 5.1 is a major release and hence will not recognize either 3.x or 4.x product installations.

Why and how should I set the DISPLAY variable on UNIX platforms for GUI mode?

The installer on UNIX, must open an additional window, generally for graphics. It uses the DISPLAY environment variable to tell it on what computer to open the window. If the environment variable is not set, the installer will either wait or abort after displaying:

InstallShield WizardInitializing InstallShield Wizard...Preparing Java(tm) Virtual Machine.........................................................................



........

The DISPLAY variable must be set to the IP address or name of the computer (on which the installer graphics window are to be displayed), followed by a screen address, which can be :0.0. For example:

# Bourne shellDISPLAY=<ip_address>:0.0; export DISPLAY

# Korn shellexport DISPLAY=<ip_address>:0.0

# C-shellsetenv DISPLAY <ip_address>:0.0

For example, consider a scenario where you need to install the adapter on a remote HP-UX machine (named itaska). Because you have a Solaris 5.6 machine (named alaska) that has a video card and monitor installed, you can run an X-window application on it. So you decide to telnet to itaska from alaska.

When you telnet to itaska, you will not get access to itaska's monitor and will be unable to display an X-window application. That is why you must set the DISPLAY variable, which instructs the X-server to redirect all windows to the computer set in the variable. Before doing so, the computer (specified in the DISPLAY variable) must give permissions to share its monitor.

alaska> xhost + # give permission for all to its share monitoralaska> telnet itaskaWelcome to HPUX itaska 11.00User:Password:itaska> export DISPLAY=alaska:0.0 # set display on alaskaitaska> TIB_adejb-simple_<version_num>_odbc_h7_110.bin

What is uninst2 directory?

If the original uninstall directory is in use at uninstall time, it cannot be removed by the installer program. The installer then creates a second uninstall directory for the second installation. To remove the second installation, you must invoke the uninstall program from the second uninstall directory. The original uninstall directory can also be manually removed, if empty.

Running Out of Disk SpaceThe installer calculates the disk space required in product home location, for the selected components. The calculation is done before the actual installation (copying of files to system) begins. The installer will proceed only if sufficient free disk space is available in product home location.



However, if disk space is consumed by another process while the installer is copying the files, and if the required disk space is thereby reduced, the installer may fail and will then give a failure message.

Solution

While performing installation, avoid running other processes that consume disk space in product home location.

Installation Errors on HP-UX 11.00 64 bit Platform

Error message

Installation on a HP-UX 11.00 64 bit system may crash with the following error message:

Pid nnn killed due to trashed stack.Pid nnn was killed due to failure in writing the signal context.

This happens only on HP-UX 11.00 64 bit systems. It does not happen on HP-UX 11.00 32 bit system and HP-UX 11.11 (or 11.i) system.

To determine the OS version on your system, run:

uname -a

To determine the kernel bits on your system, run:

getconf KERNEL_BITS

Resolution

HP-UX kernel patch PHKL_27282, resolves the above crash.

To determine if your system has the kernel patch, run:

/usr/sbin/swlist -l product PHKL_27282

or

what /stand/vmunix | grep PHKL_27282

If your system is an HP-UX 11.00 64 bit system and it does not have the patch, first install HP-UX kernel patch PHKL_27282 and then proceed with the installation. Installation of patch PHKL_27282, will reboot your system.



Configuring TIBCO Hawk

Error

TIBCO Runtime Agent includes the TIBCO Hawk Agent only. If you install the full TIBCO Hawk package after installing TIBCO Runtime Agent and do not have a Java Runtime Environment (other then the TIBCO JRE) installed, the TIBCO Hawk Configuration tool is unable to determine the Java home location and the JVM executable. The TIBCO Hawk services will not start correctly and you will be unable to start the TIBCO Hawk Display.

Resolution

1. Start the TIBCO Hawk Configuration tool. For example, on Microsoft Windows:

Start > TIBCO > TIBCO Hawk > Hawk Configuration

2. Under the General tab, click Advanced.

3. In the Java Home Directory field, provide the path to Java. For example:

C:\tibco\jre\1.4.2

4. In the JVM Executable field, provide the JVM executable. For example:

java.exe

The services will start properly and the TIBCO Hawk Display will run.

Cannot Install the AdapterOn HP-UX platforms, even though the correct version of TIBCO Runtime Agent version is already installed on the system, installation of an adapter that depends on TIBCO Runtime Agent may fail in the dependency resolution.

The TIBCO product installer maintains the registry information in the vpd.properties.tibco.systemName file. The value for systemName is determined by InetAddress.getLocalHost().getHostName(). However, the method getHostName(), returns different values based on the JRE versions used. Therefore, the installer is not able to load the correct registry file.

Resolution

On Unix platforms, the installer registry file vpd.properties.tibco.systemName is located in the user's home directory.

Case 1: If the vpd.properties.tibco.systemName file exists:



$ cd user's_home_directory$ ln -s vpd.properties.tibco.systemName

vpd.properties.tibco.systemName.domainName

For example:$ cd ~$ ln -s vpd.properties.tibco.upside vpd.properties.tibco.upside.tibco.com

where upside is systemName, and tibco.com is domainName

Case 2: If the vpd.properties.tibco.systemName.domainName file exists:

$ cd user's_home_directory$ ln -s vpd.properties.tibco.systemName.domainName vpd.properties.tibco.systemName

For example:

$ cd ~$ ln -s vpd.properties.tibco.upside.tibco.com vpd.properties.tibco.upside

where upside is systemName, and tibco.com is domainName.




| 57

Chapter 3 Getting Started

This chapter presents examples that demonstrate key adapter features. Work through these examples to get a hands-on understanding of how the adapter works.

Topics

• Prerequisites, page 58

• Create the Project, page 61

• Define the Schema, page 63

• Define Application Server Settings, page 66

• Configure the Adapter, page 67

• Configure the Publication Service, page 69

• Configure the Subscription Service, page 71

• Export the Project, page 73

• Generate the Code, page 74

• Compile the Generated Code, page 77

• Prepare the Code for Deployment, page 78

• Deploy the Connector Component, page 80

• Deploy the Name Beans, page 82

• Write the RMI Client Program for the Publication Service, page 83

• Create the TRA Files, page 86

• Start the Adapter Services, page 93

• Test the Adapter, page 94

• Stop the Adapter, page 95


58 | Chapter 3 Getting Started

Prerequisites

Before starting the configuration exercise, ensure that all required software has been installed and is operating correctly. For a list of required software, see the installation instructions in Chapter 2, Installation, on page 17.

You should know how to drag and drop icons in TIBCO Designer and be familiar with saving projects. If you are not familiar with these topics, refer to the TIBCO Designer User’s Guide, which is available by clicking Help > Designer Help in TIBCO Designer.

Scenario OverviewThe example in this chapter involves a Name object that consists of the FirstName and LastName attributes. The publisher client will publish an ActiveEnterprise object and the subscription service will subscribe to the same object.


Prerequisites | 59

The following figure depicts how the example works

Connections to the Application ServerYou must ensure the adapter to application server connections are in place. See Chapter 4, Preparing EJB Application Interfaces, on page 97 for details.

Other ExamplesA set of examples are included online in the examples directory. The examples/publish folder includes examples for the publication service. The examples/subscribe folder includes examples for the subscription service.

TIBCO Messaging

Publisher+Glue Bean

ConnectorBean

Subscriber+ GlueBean

TIBCO Adapterfor EJB

Application Server

Code Generator

Request-ReponseInvocation

Service

Java



Adapter examples use the TIBCO Rendezvous ticket from the PATH variable that points to you TRA location. This ticket expires after a set duration (1 hour). For details on the License Expiry message, see Appendix A in TIBCO Rendezvous Concepts.

If you have a permanent TIBCO Rendezvous license, make sure this ticket file is in your path. To upgrade your temporary TIBCO Rendezvous license, see Licensing Information in the TIBCO Rendezvous Administration Guide.


Create the Project | 61

Create the Project

The TIBCO Designer GUI is used to configure adapter instances. When starting Designer, you must create or select a project. A project contains the configuration files that define options used by a run-time adapter. After a project is configured, it is converted to a repository file and available for use by the run-time adapter.

To create a project:

1. Start TIBCO Designer by executing the following command, depending on your operating system.

On Microsoft Windows, select: Start > Programs > TIBCO > TIBCO Designer 5.3 > Designer 5.3

On UNIX, from a command window change directory to the <install-path>/tibco/designer/5.3/bin directory and type ./designer

2. In the TIBCO Designer dialog, click New empty project.



3. In the Save Project dialog, select Multi-File Project (if it is not selected) and save the project as test in a temporary location.

4. Click OK.

The next figure shows the TIBCO Designer GUI with the test project defined.

Project panel

Palette panel

Design panel

Configuration panel


Define the Schema | 63

Define the Schema

You can create the schema that will be used by the adapter services. For the subscription service, the adapter subscribes to messages that follow the semantics of the defined schema and for the publication service, the connector publishes messages that follow the semantics of the defined schema.

To define a schema:

1. Double-click the AESchemas folder in the project panel and drag the Folder icon from the palettes panel to the design panel.

2. Type ejb in the Name field and click Apply.

3. Double-click the ejb folder in the project panel and drag the AESchema icon from the palettes panel to the design panel.



4. Enter TestSchema in the Name field and click Apply.

5. Double-click the TestSchema folder in the project panel.

6. Double-click the Classes folder in the project panel. Drag the Generic Class icon from the palettes panel to the design panel.

7. Select Schema from the Class Type drop-down list under the Configuration tab. Click Apply.

8. Enter Name in the Name field under the Configuration tab and click Apply.


Define the Schema | 65

9. Double-click Name under the Classes folder.

10. Click Scalar Types in the palettes panel and drag the Generic Scalar icon from the palettes panel to the design panel.

11. Enter FirstName in the Name field and click Apply.

12. Click Name under the Classes folder in the project panel and drag a Generic Scalar icon from the palettes panel to the design panel.

13. Enter LastName in the Name field and click Apply. Then, click Project > Save.



Define Application Server Settings

You can create application server settings that will be used and shared by different adapter services. The application server settings resource helps in defining connection properties for a specific application server. This palette resource is used by different adapter services (subscription and request-response server) of the same adapter instance to connect to different application servers.

To define application server settings:

1. Drag the Application Server Settings icon from the palettes panel to the design panel. This creates a resource named by default, ApplicationServerSettings. The name can be changed, but in this exercise, names assigned by TIBCO Designer will be used.

2. Specify Weblogic in the Name box. Select the application server, Weblogic 8.1, from the drop-down. The JNDI context, JNDI url, and JNDI packages (if required) boxes, are populated with default values. If necessary, make changes to the JNDI context factory class and JNDI url according to your application server configuration. Click Apply to save.

The Application Server Settings resource is available only if the adapter was installed for multiple application server support.


Configure the Adapter | 67

Configure the Adapter

An adapter instance can contain publication services, subscription services, or request-response services. Options for logging, startup, and monitoring are set on the adapter instance. In this exercise, default values are used for these options.

To configure the adapter instance:

1. Drag the EJB Adapter Configuration icon from the palettes panel to the design panel. This creates an adapter named by default, EjbAdapterConfiguration. The name can be changed, but in this exercise, names assigned by TIBCO Designer will be used.

2. Click the Logging tab to identify the file log options.

The Log File field lists the global variables that are used to define the log file path and name. The DirTrace and Deployment variables are set using global variables. You can click the Global Variable tab to display the variables in the project panel. The default settings will be used in this example. The



InstanceId variable need not be set. The variable automatically substitutes the adapter name at run-time.


Configure the Publication Service | 69

Configure the Publication Service

This section explains how to configure an adapter with a publication service that publishes messages using the schema defined. You must:

• Configure the Transport Information

• Configure Schema Definitions

Task A Configure the Transport Information

1. In the project panel, expand the EjbAdapterConfiguration icon, then highlight the Adapter Services folder to access the Publication Service icon. Drag the icon from the palette panel to the design panel.

2. Click the Transport tab and enter EJB.TEST.PUBLISH in the Message Subject field.

3. Select Reliable as the Quality of Service and ActiveEnterprise Message as the wire format. Click Apply.

Task B Configure Schema Definitions

1. Click the Schema tab and click the Browse Resources button.

2. Click test > AESchemas > ejb > TestSchema > Classes > Name in the Select a Resource dialog box and click OK.



3. Click Project > Save to save the project.


Configure the Subscription Service | 71

Configure the Subscription Service

This section explains how to configure a subscription service to receive a message and invoke an enterprise bean with the message. The exercise assumes you have completed the previous exercise, Configure the Publication Service on page 69, and uses ActiveEnterprise classes created during the exercise. You must use the same project created in the previous exercise. In this exercise, you must:

• Configure the Transport Information

• Configure Schema Definitions

Task A Configure the Transport Information

1. In the project panel, expand the EjbAdapterConfiguration icon, then select the Adapter Services folder to access the Subscription Service icon. Drag the icon from the palette panel to the design panel.

2. Click the Transport tab and enter EJB.TEST.PUBLISH in the Message Subject field.

3. Select Reliable as the Quality of Service and ActiveEnterprise Message as the wire format. Click Apply.

Task B Configure Schema Definitions

1. Click the Schema tab and click the Browse Resources button.



2. Click test > AESchemas > ejb > TestSchema > Classes > Name in the Select a Resource dialog box and click OK.

3. Click the Connection Info tab and enter Subscribe_NameBean in the JNDI Provider Url field.

4. Enter com.tibco.ejb.TestSchema.Subscribe_NameHome in the Ejb Home Interface field. Click Apply.

5. Click the Browse Resources button for the Application Server Connection field. This field is available only if the adapter is installed for multiple-application server. Select the resource /Weblogic from the resource selection window.

6. Click Apply.

7. Click Project > Save to save the project.


Export the Project | 73

Export the Project

After you have configured the services, you must export the project.

To export the project:

1. Select Project > Export Full Project in the Project window. The Export Project dialog box is displayed.

2. Select the Local Repository tab in the Export Project dialog box if it is not already selected.

3. Enter test in the Project Name field.

4. In the Dir Name field:

— On Microsoft Windows, enter <ADEJB_HOME>\examples\start

— On UNIX, enter <ADEJB_HOME>/examples/start

The Export Project dialog box is displayed.

5. Click OK to export the project.



Generate the Code

After configuring the services, you must generate the code for the configured adapter services. The steps in this exercise are:

• Generate Code for the Publication Service

• Generate Code for the Subscription Service

Task A Generate Code for the Publication Service

1. Click test > EjbAdapterConfiguration > PublicationService and click the Code Generator tab.

a. Select 2.0 from the EJB Spec Version drop-down list.

b. Click Browse to select <ADEJB_HOME>\examples\start as the bean output directory and <ADEJB_HOME>\examples\start\META-INF2 as the deployment descriptor output directory. If the META-INF2 folder does not exist, create it.

c. Enter com.tibco in the Package Root field.

d. Select Use Resource Reference and enter tibco/aeconnector in the Resource Reference field.

e. Enter 4 in the Indent Level field.

f. Click Apply and then click Generate Code.


Generate the Code | 75

2. Verify that the code is generated in the <ADEJB_HOME>\examples\start\com\tibco\ejb\TestSchema directory.

The generated code consists of the following files:

— Name.java

— Publish_Name.java

— Publish_NameBean.java

— Publish_NameHome.java

Task B Generate Code for the Subscription Service

1. Click test > EjbAdapterConfiguration > SubscriptionService and click the Code Generator tab.

a. Select 2.0 from the EJB Spec Version drop-down list.

b. Click Browse to select <ADEJB_HOME>\examples\start as the bean output directory and <ADEJB_HOME>\examples\start\META-INF as the

TIBCO strongly recommends saving the generated glue bean code for later use if you want to continue deploying new beans incrementally, after the initial adapter deployment using the automatic deployment feature. This will help package the new glue beans with the old glue beans in one deployable archive.

If you are regenerating the glue bean code to take advantage of the automatic deployment feature of the adapter, see Regenerating Glue Beans on page 432 for more details on code regeneration.

If you have already deployed the connector and glue beans to your application server and are generating additional glue beans to be deployed, see Incremental Deployment of New Glue Beans Using Ant Script on page 433, for more information.



deployment descriptor output directory. If the META-INF folder does not exist, create it.

c. Enter com.tibco in the Package Root field.

d. Enter 4 in the Indent Level field.

e. Click Apply and then click Generate Code.

2. Verify that the code is generated in the <ADEJB_HOME>\examples\start\com\tibco\ejb\TestSchema directory.

The generated code consists of the following files:

— Name.java

— Subscribe_Name.java

— Subscribe_NameBean.java

— Subscribe_NameHome.java

— AttributeDetails.java

3. Edit the Subscribe_NameBean.java file to add the following code to the subscribe method. This code is used for the implementation of the subscribe method.

System.out.println("Received message:");System.out.println("First Name: "+subscribeObj.getFirstName());System.out.println("Last Name: "+subscribeObj.getLastName());System.out.println("invocation ok");


Compile the Generated Code | 77

Compile the Generated Code

After you have generated the code for the publication and subscription services, you must compile the generated code.

To compile the generated code:

1. Verify that the following files are included in the CLASSPATH environment variable:

— <Application Server_HOME>\lib\weblogic.jar

— <ADEJB_HOME>\lib\EjbSupport.jar

— <ADEJB_HOME>\lib\GlBeansSupport.jar

— <ADEJB_HOME>\lib\AeConnector.jar

2. Go to the <ADEJB_HOME>\examples\start\com\tibco\ejb\TestSchema directory.

3. Run the following command:

— On Microsoft Windows, javac -d <ADEJB_HOME>\examples\start *.java

— On UNIX, javac -d <ADEJB_HOME>\examples\start *.java



Prepare the Code for Deployment

After you have compiled the generated code, you must prepare the code for deployment.

To prepare the code for deployment:

1. Modify the contents of the ejb-jar.xml file in the <ADEJB_HOME>\examples\start\META-INF directory so that it contains entries for the glue beans of the publication and subscription service. The deployment descriptor file that should be used is as follows:

<?xml version="1.0"?>

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://java.sun.com/dtd/ejb-jar_2_0.dtd">

<ejb-jar><description /><display-name>TIB Integration Server Beans</display-name><small-icon /><large-icon /><enterprise-beans>

<session><description>Subscriber to TIBCO AE Class

/tibco/public/class/ejb/TestSchema/Name</description><display-name>Subscribe_NameBean</display-name><small-icon></small-icon><large-icon></large-icon><ejb-name>Subscribe_NameBean</ejb-name><home>com.tibco.ejb.TestSchema.Subscribe_NameHome</home>

<remote>com.tibco.ejb.TestSchema.Subscribe_Name</remote><ejb-class>com.tibco.ejb.TestSchema.Subscribe_NameBean</ejb-class>

<session-type>Stateless</session-type><transaction-type>Bean</transaction-type>

</session>session>

<description>EJB publisher for TIBCO AE Class /tibco/public/class/ejb/TestSchema/Name</description>

<display-name>Publish_NameBean</display-name><small-icon></small-icon><large-icon></large-icon>

The code generation of the publication and subscription services generates separate deployment descriptors in the META-INF2 and META-INF directories respectively). You must combine the deployment descriptors to deploy the beans that are generated as a single jar file.


Prepare the Code for Deployment | 79

<ejb-name>Publish_NameBean</ejb-name><home>com.tibco.ejb.TestSchema.Publish_NameHome</home><remote>com.tibco.ejb.TestSchema.Publish_Name</remote>

<ejb-class>com.tibco.ejb.TestSchema.Publish_NameBean</ejb-class>

<session-type>Stateless</session-type><transaction-type>Bean</transaction-type><resource-ref>

<description>Reference to TIBCO AEConnector</description><res-ref-name>tibco/aeconnector</res-ref-name>

<res-type>com.tibco.ejb.connector.AE3ConnectionFactory</res-type>

<res-auth>Container</res-auth></resource-ref></session>

</enterprise-beans><ejb-client-jar /></ejb-jar>

2. Create the BEA WebLogic 7.0 with the required service pack deployment descriptor file in the META-INF directory and add the following code:


<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 6.1.0 EJB//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd'><weblogic-ejb-jar>

<weblogic-enterprise-bean><ejb-name>Publish_NameBean</ejb-name><reference-descriptor><resource-description>

<res-ref-name>tibco/aeconnector</res-ref-name><jndi-name>tibco/aeconnectorJNDINAME</jndi-name></resource-description></reference-descriptor><jndi-name>Publish_NameBean</jndi-name>

</weblogic-enterprise-bean><weblogic-enterprise-bean>

<ejb-name>Subscribe_NameBean</ejb-name><jndi-name>Subscribe_NameBean</jndi-name>

</weblogic-enterprise-bean></weblogic-ejb-jar>

3. Run the jar -cvf NameBean.jar com\ META-INF\ command to archive the class files and deployment descriptor files.



Deploy the Connector Component

Deploying the connector component involves the following tasks:

• Deploying the Connector Component

• Editing the Repository and Configuration URLs

Task A Deploying the Connector Component

1. Click Start > Programs > BEA WebLogic E-Business Platform > WebLogic 6.1 > Start Default Server to start the WebLogic Default Server or at the command prompt, go to the <WebLogic_HOME>\config\<domain name> directory and run startWebLogic. (On UNIX, run startWebLogic.sh.)

2. Click Start > Programs > BEA WebLogic E-Business Platform > WebLogic 6.1 > Start Default Console to start the Administrator Console.

3. Select Connectors under the Deployments section and then click Install a New Connector Component.

4. Click Browse to select the AeConnector.rar file from the <ADEJB_HOME>\lib directory.

5. Click Upload to deploy the connector in the container.

Task B Editing the Repository and Configuration URLs

To edit the repository and configuration URLs:

1. In the Administrator Console, click Deployments > Connectors. If the connector (Aeconnector.rar) is deployed it will appear in the list of connectors.

2. Click Aeconnector and then click Edit Connector Descriptor.

The AeConnector.rar file is displayed in a new browser window.

3. Click Config Properties under WebLogic RA, and click repoUrl. The configuration page is displayed.

4. In the configuration page, change the value in the Config Property Value field as follows:

— On Microsoft Windows, enter <ADEJB_HOME>\examples\start\test.dat

— On UNIX, enter <ADEJB_HOME>/examples/start/test.dat

5. Click Apply.


Deploy the Connector Component | 81

6. Click Config Properties under WebLogic RA, and click configUrl. The configuration page is displayed.

7. In the configuration page, change the value in the Config Property Value field as follows:/tibco/private/adapter/EjbAdapterConfiguration/EJBAdapter

8. Click Apply.

9. Click Config Properties under WebLogic RA, and click TraFileName. The configuration page is displayed.

10. In the configuration page, change the value in the Config Property Value field as follows:

— <ADEJB_HOME>\bin\connector.tra (on Microsoft Windows).

— <ADEJB_HOME>/ bin/connector.tra (on UNIX).

11. Click Apply.

12. Select the TraFileName property. In the Value field, enter D:/tibco/adapter/adejb/5.2/bin/connector.tra for <traqFileName>.

13. Click Apply.



Deploy the Name Beans

The following steps explain how to deploy the beans.

1. Verify that the application server is started.

2. Click Start > Programs > BEA WebLogic E-Business Platform > WebLogic 6.1 > Start Default Console to start the Administrator Console

3. Select EJB under the Deployments section and then click Install a New EJB.

4. Choose the NameBean.jar file from the adapter installation examples/start subdirectory.

5. Click Upload. The jar will deploy.

If it fails, it is likely that the startWebLogic.cmd file is missing one or more necessary jars in the classpath.


Write the RMI Client Program for the Publication Service | 83

Write the RMI Client Program for the Publication Service

After deploying the Name beans, you must write the RMI client program:

1. Verify that the <ADEJB_HOME>\examples\start directory is included in the CLASSPATH environment variable.

2. Create the NamePublisherClient.java file in the <ADEJB_HOME>\examples\start directory and include the following code:

import java.io.*;import java.rmi.*;import java.util.*;import javax.ejb.*;import javax.naming.*;

import com.tibco.ejb.TestSchema.*;

import javax.rmi.PortableRemoteObject;

/*** EJB client program. It makes a call to a session bean* that in turn uses TIB/Rendezvous to publish a* message.* @see publish.subscriber.AESubscriber*/

public class NamePublisherClient{

public NamePublisherClient(){}

public static void main(String argv[]){

String JNDIName = System.getProperty("JNDIName");

// Obtain the home interface.Publish_NameHome home = null;try{

System.out.println("Starting the test client program.");Context ctx = new InitialContext();System.out.println("Obtained the initial context.");

// Use JNDI to look up the client bean.home = (Publish_NameHome)PortableRemoteObject.narrow(

ctx.lookup(JNDIName),Publish_NameHome.class);



System.out.println("Publish_NameBean lookup successful");}

catch(ClassCastException ex){

System.out.println("Invalid class returned from lookup.");System.out.println(

"Please check whether client stubs jar is in the CLASSPATH");ex.printStackTrace();System.exit(-1);

}catch(NamingException ex){

System.err.println("Lookup failed: " + ex.getMessage());ex.printStackTrace();System.exit(-1);

}

// Obtain the remote interface.Publish_Name publishBeanInterface = null;try

{System.out.println("creating session bean instance");publishBeanInterface = home.create();

}catch(CreateException ex)

{System.err.println("could not create Publish_Name bean: " +

ex.getMessage());System.exit(-1);

}catch(RemoteException ex){

System.err.println("RemoteException occurred during bean creation: "

+ ex.getMessage());System.exit(-1);

}try{

System.out.println("Publishing data:");com.tibco.ejb.TestSchema.Name name = new

com.tibco.ejb.TestSchema.Name();name.setFirstName("THOMAS");name.setLastName("EDISON");publishBeanInterface.publish(name);

}catch(Exception ex){

System.out.println("Error accessing Publish_Name bean");

ex.printStackTrace();}


Write the RMI Client Program for the Publication Service | 85

// Disconnect from the beantry{

publishBeanInterface.remove();}catch(RemoteException ex){

System.err.println("Error removing Publish_Name bean");

}catch(RemoveException ex)

{System.err.println("Error removing Publish_Name bean");

}}

}

3. Go to the <ADEJB_HOME>\examples\start directory and run the following command:javac NamePublisherClient.java



Create the TRA Files

You must now create the TRA files for the adapter services. This involves the following tasks:

• Creating the TRA File for the Publication Service

• Creating the TRA File for the Subscription Service

Task A Creating the TRA File for the Publication Service

• In the <ADEJB_HOME>\examples\start directory create the namepublisherclient.tra file as shown below:## Copyright (c) 2005 TIBCO Software Inc.# All Rights Reserved.##============================================================== # ** Common variables. Modify these parameters, if required. **#==============================================================

# The property tibco.env.PSP and its value should always be separated with "="

tibco.env.PSP=;

#TIBCO Hometibco.env.TIB_HOME D:/tibco

#TIB RV Hometibco.env.RV_HOME D:/tibco/tibrv

#TIB TPCL Hometibco.env.TPCL_HOME D:/tibco/tpcl/5.3

#TIBCO TRA Hometibco.env.TRA_HOME D:/tibco/tra/5.3

# TIBCO TRA Versiontibco.env.TRA_APPEND_VERSION 5.3

# Adapter Home tibco.env.TIB_ADEJB_HOME D:/tibco/adapter/adejb/<version_num>

#TIB Java Hometibco.env.TIB_JAVA_HOME D:/AppServers/bea/jdk131

The TRA files have hard-coded paths for WebLogic and TIBCO product installations. You must modify these values appropriately.


Create the TRA Files | 87

#TIB JVM Lib directorytibco.env.JVM_LIB_DIR D:/tibco/jre/1.4.2/bin

#TIB JVM Lib Pathtibco.env.JVM_LIB_PATH D:/AppServers/bea/jdk131/jre/bin/hotspot/jvm.dll

## this will be prepended to tibco.class.path.extendedtibco.env.CUSTOM_CP_EXT D:/AppServers/bea/wlserver6.1/lib/weblogic.jar

## this will be appended to tibco.class.path.extendedtibco.env.CUSTOM_CP_EXT1 %TIB_ADEJB_HOME%/examples/start%PSP%%TIB_ADEJB_HOME%/examples/lib%PSP%%TIB_ADEJB_HOME%/examples/classes

## this is the standard classpath containing TIBCO, Java and Adapter specific jar filestibco.env.STD_CP_EXT %TIB_ADEJB_HOME%/hotfix/lib%PSP%%TIB_ADEJB_HOME%/lib%PSP%%TRA_HOME%/hotfix/lib%PSP%%TRA_HOME%/lib%PSP%%RV_HOME%/lib%PSP%%TPCL_HOME%/lib%PSP%%TPCL_HOME%/lib/entrust%PSP%%TPCL_HOME%/jdbc%PSP%%TIB_JAVA_HOME%/lib/tools.jar%PSP%%TRA_HOME%/lib/repository_mappers

# this will be prepended to tibco.env.PATHtibco.env.CUSTOM_PATH

## this will be prepended to tibco.env.LD_LIBRARY_PATH,## tibco.env.SHLIB_PATH, tibco.env.LIBPATHtibco.env.CUSTOM_LIB_PATH

#==============================================================# <acronym> adapter run time parameters. Modify these parameters, if required.#==============================================================

## Specifies the initial Java heap size to allocatejava.heap.size.max 256Mjava.heap.size.min 32Mjava.thread.stacksize 128K

## Specifies the default user directoryjava.property.user.dir %TIB_ADEJB_HOME%java.property.tibco.adejb.log truejava.property.tibco.adejb.logFileName D:/tibco/adapter/adejb/<version_num>/examples/start/publish.logjava.property.java.naming.factory.initial weblogic.jndi.WLInitialContextFactoryjava.property.java.naming.provider.url t3://localhost:7001java.property.java.naming.factory.url.pkgs no_valuejava.property.JNDIName Publish_NameBeanjava.property.CustId *java.property.Name acme



tibco.password adejbtibco.username adejb

adejb.perfMon off

tibco.repourl D:/tibco/adapter/adejb/<version_num>/examples/start/test.dattibco.configurl no_valuetibco.clientVar.DirTrace

D:/tibco/adapter/adejb/<version_num>/logstibco.clientVar.DirLedger

D:/tibco/adapter/adejb/<version_num>/ledgertibco.instanceid no_value

## Specifies the remaining arguments to pass into the application# -d : to activate the debug info dump#application.args -dapplication.args -system\:perfMon -system:Hawk -system:propfile D:/tibco/adapter/adejb/<version_num>/examples/start/namepublisherclient.traapplication.start.dir %TIB_ADEJB_HOME%

# ***** properties for installing as a service *****ntservice.name adejbntservice.displayname TIBCO Adapter for EJBntservice.starttype manualntservice.binary.path.absolute %TIB_ADEJB_HOME%/bin/adejb.exe#ntservice.dependencies foo barntservice.interactive true#ntservice.account #ntservice.password

# ***** property for connection retry *****# Default is true (connection retry is enabled)java.appserver.connectionretry true

#============================================== # *** Do NOT modify beyond this line ***#==============================================

## Set the PATHtibco.env.PATH %CUSTOM_PATH%%PSP%%TIB_ADEJB_HOME%/hotfix/bin%PSP%%TIB_ADEJB_HOME%/bin%PSP%%TIB_ADEJB_HOME%/hotfix/lib%PSP%%TIB_ADEJB_HOME%/lib%PSP%%TRA_HOME%/hotfix/bin%PSP%%TRA_HOME%/bin%PSP%%TPCL_HOME%/bin%PSP%%RV_HOME%/bin

## Specifies the JVM to be used to launch this applicationjava.library %JVM_LIB_PATH%

## Specifies the Java class that contains the mainjava.start.class NamePublisherClient



## Specifies the main function in invokejava.start.method mainjava.stop.method shutdown

## Specifies the classpath and provides for automatic expansiontibco.class.path.extended %CUSTOM_CP_EXT%%PSP%%STD_CP_EXT%%PSP%%CUSTOM_CP_EXT1%

Task B Creating the TRA File for the Subscription Service

• In the <ADEJB_HOME>\examples\start directory, create the namesubscriber.tra file as shown below:## Copyright (c) 2004 TIBCO Software Inc.# All Rights Reserved.##============================================================== # ** Common variables. Modify these parameters, if required. **#==============================================================

# The property tibco.env.PSP and its value should always be separated with "="

tibco.env.PSP=;

#TIBCO Hometibco.env.TIB_HOME D:/tibco

#TIB RV Hometibco.env.RV_HOME D:/tibco/tibrv

#TIB TPCL Hometibco.env.TPCL_HOME D:/tibco/tpcl/5.3

#TIBCO TRA Hometibco.env.TRA_HOME D:/tibco/tra/5.3

# TIBCO TRA Versiontibco.env.TRA_APPEND_VERSION 5.3

# Adapter Home tibco.env.TIB_ADEJB_HOME D:/tibco/adapter/adejb/<version_num>

#TIB Java Hometibco.env.TIB_JAVA_HOME D:/AppServers/bea/jdk131

#TIB JVM Lib directorytibco.env.JVM_LIB_DIR D:/tibco/jre/1.4.2/bin

#TIB JVM Lib Pathtibco.env.JVM_LIB_PATH D:/AppServers/bea/jdk131/jre/bin/hotspot/jvm.dll



## this will be prepended to tibco.class.path.extendedtibco.env.CUSTOM_CP_EXT D:/AppServers/bea/wlserver6.1/lib/weblogic.jar

## this will be appended to tibco.class.path.extendedtibco.env.CUSTOM_CP_EXT1 %TIB_ADEJB_HOME%/examples/start%PSP%%TIB_ADEJB_HOME%/examples/lib%PSP%%TIB_ADEJB_HOME%/examples/classes

## this is the standard classpath containing TIBCO, Java and Adapter specific jar filestibco.env.STD_CP_EXT %TIB_ADEJB_HOME%/hotfix/lib%PSP%%TIB_ADEJB_HOME%/lib%PSP%%TRA_HOME%/hotfix/lib%PSP%%TRA_HOME%/lib%PSP%%RV_HOME%/lib%PSP%%TPCL_HOME%/lib%PSP%%TPCL_HOME%/lib/entrust%PSP%%TPCL_HOME%/jdbc%PSP%%TIB_JAVA_HOME%/lib/tools.jar%PSP%%TRA_HOME%/lib/repository_mappers

# this will be prepended to tibco.env.PATHtibco.env.CUSTOM_PATH

## this will be prepended to tibco.env.LD_LIBRARY_PATH,## tibco.env.SHLIB_PATH, tibco.env.LIBPATHtibco.env.CUSTOM_LIB_PATH

#==============================================================# <acronym> adapter run time parameters. Modify these parameters, if required.#==============================================================

## Specifies the initial Java heap size to allocatejava.heap.size.max 256Mjava.heap.size.min 32Mjava.thread.stacksize 128K

## Specifies the default user directoryjava.property.user.dir %TIB_ADEJB_HOME%java.property.tibco.adejb.log truejava.property.tibco.adejb.logFileName D:/tibco/adapter/adejb/<version_num>/examples/start/subscribers

ample.logjava.property.java.naming.factory.initial weblogic.jndi.WLInitialContextFactoryjava.property.java.naming.provider.url t3://localhost:7001java.property.java.naming.factory.url.pkgs no_valuejava.property.JNDIName no_valuejava.property.CustId no_valuejava.property.Name no_value

tibco.password adejbtibco.username adejb

# Adapter specific propertiesadejb.perfMon offadejb.ThrowAdEJBSystemException True



adejb.sequenceTypeToActualObject False

tibco.repourl D:/tibco/adapter/adejb/<version_num>/examples/start/test.dattibco.configurl /tibco/private/adapter/EJBAdapterConfigurationtibco.clientVar.DirTrace

D:/tibco/adapter/adejb/<version_num>/logstibco.clientVar.DirLedger

D:/tibco/adapter/adejb/<version_num>/ledgertibco.instanceid EJBAdapterConfiguration

## Specifies the remaining arguments to pass into the application# -d : to activate the debug info dump#application.args -dapplication.args -system\:perfMon -system:Hawk -system:propfile D:/tibco/adapter/adejb/<version_num>/examples/start/namesubscri

ber.traapplication.start.dir %TIB_ADEJB_HOME%

# ***** properties for installing as a service *****ntservice.name adejbntservice.displayname TIBCO Adapter for EJBntservice.starttype manualntservice.binary.path.absolute %TIB_ADEJB_HOME%/bin/adejb.exe#ntservice.dependencies foo barntservice.interactive true#ntservice.account #ntservice.password

# ***** property for connection retry *****# Default is true (connection retry is enabled)java.appserver.connectionretry true

#============================================== # *** Do NOT modify beyond this line ***#==============================================

## Set the PATHtibco.env.PATH %CUSTOM_PATH%%PSP%%TIB_ADEJB_HOME%/hotfix/bin%PSP%%TIB_ADEJB_HO

ME%/bin%PSP%%TIB_ADEJB_HOME%/hotfix/lib%PSP%%TIB_ADEJB_HOME%/lib%PSP%%TRA_HOME%/hotfix/bin%PSP%%TRA_HOME%/bin%PSP%%TPCL_HOME%/bin%PSP%%RV_HOME%/bin

## Specifies the JVM to be used to launch this applicationjava.library %JVM_LIB_PATH%

## Specifies the Java class that contains the mainjava.start.class com/tibco/ejb/adapter/EjbAdapter

## Specifies the main function in invokejava.start.method main



java.stop.method shutdown

## Specifies the classpath and provides for automatic expansion tibco.class.path.extended %CUSTOM_CP_EXT%%PSP%%STD_CP_EXT%%PSP%%CUSTOM_CP_EXT1%


Start the Adapter Services | 93

Start the Adapter Services

You must now start the adapter services. The steps are:

• Trigger the Publication Service

• Start the Subscription Service

Task A Start the Subscription Service

1. Verify that the PATH environment variable includes the <ADEJB_HOME>\bin directory.

2. In the command window, go to the <ADEJB_HOME>\examples\start directory and run the following commandadejb --run --propFile <ADEJB_HOME>\examples\start\namesubscriber.tra

Task B Trigger the Publication Service

To start the publication service:

1. Verify that the PATH environment variable includes the <ADEJB_HOME>\bin directory.

2. In a command window, go to the <ADEJB_HOME>\examples\start directory and run the following command:adejb --run --propFile <ADEJB_HOME>\examples\start\namepublisherclient.tra



Test the Adapter

Testing the adapter is simply to start it after configuring it and check for correct messaging. In this method, you can configure the adapter as desired, then start it. If your preparations and configuration are successful, the adapter will connect to EJB and messaging will indicate no errors.


Stop the Adapter | 95

Stop the Adapter

To stop the adapter, send a TIBCO Rendezvous or JMS message using the name specified in the Termination Subject or Topic field under the General tab of the adapter instance. The default termination subject or topic is TIBCOEJBService.Terminate. Use TIBCO Designer to change this name or retain the default name.

You can use this method to stop the inbound adapter process. Stop the connector by undeploying the bean or stopping the application server.




| 97

Chapter 4 Preparing EJB Application Interfaces

This chapter explains how to prepare the supported application servers for interaction with the adapter.

Topics

• Overview, page 98

• Preparing BEA WebLogic Application Server 7.0/BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, SP6, and SP7, page 101

• Preparing BEA WebLogic Application Server 8.1/BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5 or SP6, page 107

• Preparing BEA WebLogic Application Server 9.0, 9.1, and 9.2, page 117

• Preparing IBM WebSphere 5.1.0 Application Servers, page 128

• Preparing IBM WebSphere 5.1.0 Application Servers, page 128

• Preparing IBM WebSphere 6.0 Application Server, page 136

• Preparing IBM WebSphere 6.0.2 and 6.1 Application Servers, page 140

• Preparing the Sun Java System Application Server Platform Edition 7, page 145

• Preparing the Sun Java System Application server Platform Edition 8.1, page 148

• Preparing the Oracle 9i Application Server, page 151

• Preparing the Oracle 10g Application Server, page 157

• Preparing the JBoss 3.2.3 Application Server, page 163

• Preparing the JBoss Application Server 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4 Application Servers, page 167


98 | Chapter 4 Preparing EJB Application Interfaces

Overview

Before configuring the adapter you must prepare the application server that you have installed so the adapter can interoperate with it.

Supported Connection Management FeaturesThe following matrix shows the available application servers and the connection management features that have been tested for each application server.

Table 6 Connection management features that are tested for the available application servers

Application ServerConnection Retry if the Application Server is not Running

Connection Retry if the Bean has not been deployed

BEA WebLogic 7.0 and BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, SP6, and SP7

Supported Supported

BEA WebLogic 8.1 Supported Supported

BEA WebLogic 8.1 with SP1, SP2, SP3 SP4, SP5, and SP6

Supported Supported

BEA WebLogic 9.0, 9.1, and 9.2 Supported Supported

IBM WebSphere 5.1 Not supported Supported


IBM WebSphere 6.0.2 Not supported Supported


Oracle 9i 9.0.3/Oracle 10g 9.0.4, 10.1.2, and 10.1.3

Supported Not supported

Sun Java System Application Server Platform Edition 7

Supported Supported

Sun Java System Application server Platform Edition 8.1

Supported Supported

JBoss 3.2.3 Supported Supported


Overview | 99

Access to TIBCO Repository over HTTPSThe following matrix shows the application servers that support the HTTPS protocol:

* You do not have to add the jar files listed below to the classpath of the application server or to the tibco.env.STD_CP_EXT property of the example tra files.

JBoss 4.0.0, 4.0.1, 4.0.2, 4.0.3. and 4.0.4 Supported Supported

Table 6 Connection management features that are tested for the available application servers

Application ServerConnection Retry if the Application Server is not Running

Connection Retry if the Bean has not been deployed

Table 7 Application servers that support the HTTPS protocol

Application ServerSubscriber and Request-Response Server Services

Publisher and Request-Response Client Services

BEA WebLogic 7.0 and BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, and SP6

Supported Supported

BEA WebLogic 8.1 Supported* Supported

BEA WebLogic 8.1 with SP1, SP2, SP3, SP4, SP5, and SP6

Supported* Supported

IBM WebSphere 5.1 Supported* Supported

Oracle 9i 9.0.3/Oracle 10g 9.0.4, 10.1.2, and 10.1.3

Supported Supported


Supported* Not supported


Supported Supported

JBoss 3.2.3 Supported* Supported

JBoss 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4

Supported Supported



The following section describes the procedure to be used for configuring TIBCO Repository access over HTTPS.

The outbound scenario refers to running the publication or request-response invocation service and the inbound scenario refers to running the adapter’s request-response server or subscription service.

To use the HTTPS protocol with the supported application servers, do the following:

• Change the repository URL to https://<local host>/<domain>/repo?<repository name>&userName=<username>&password=<password>&timeout=<simeout>&operationRetry=<number of retries>&urlFile=<URL file> to access the HTTPS repository.

If you are using the HTTPS protocol to access the repository or if you are using a repository present in a repository server, to run the examples, add the following jar files to the tibco.env.STD_CP_EXT property in the tra files for the subscription and request-response services, and to the server classpath for the publication and request-response invocation services:

• Download the following jar files from http://java.sun.com/products/jce/index-122.html:

— jce1_2_2.jar

— sunjce_provider.jar

— local_policy.jar

— US_export_policy.jar

• Download the following jar files from http://java.sun.com/products/jsse/index-103.html:

— jcert.jar

— jnet.jar

— jsse.jar

For details on using these files with the HTTPS protocol, see the Modifying the Repository and Configuration URLs section for the application server you are using.

For details on using these files with TIBCO Administrator, see Deploy the Project on page 217.


Preparing BEA WebLogic Application Server 7.0/BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, SP6, and

Preparing BEA WebLogic Application Server 7.0/BEA WebLogic

Application Server 7.0 with SP2, SP4, SP5, SP6, and SP7

You can configure the application server for use with the adapter on Microsoft Windows and UNIX platforms.

Preparation on Microsoft Windows PlatformsOn Microsoft Windows platforms, preparing the application server for use with the adapter involves the following tasks:

• Configuring the Application Server

• Deploying the Connector

Configuring the Application Server

To configure the application server:

1. The setWLSEnv.cmd file is located under the following directory:

<WebLogic_HOME>\server\bin

2. Add the following environment variables to the :setWLSEnv section of the file. The environment variable must point to the installation directory for the product.

— set TIBCO_TRA_HOME=<TRA installation directory>

— set TIBCO_RV_HOME=<TIBCO Rendezvous installation directory>

— set TIBCO_ADEJB_HOME=<Adapter installation directory>

— set TIBCO_TPCL_HOME=<Third party core libraries installation directory>

— set TIBCO_JRE_HOME=<JRE installation directory>

The setWLSEnv.cmd file also sets the environment for user applications. Add the following jar files to the CLASSPATH environment variable in the :setWLSEnv section:

set CLASSPATH=%CLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jar



set CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jar

3. The startWLS.cmd file is located under the <WebLogic_HOME>\server\bin directory. Add the following environment variables to the :runWebLogic section of the file. The environment variable must point to the installation directory for the product.






The startWLS.cmd file sets the required environment for starting the WebLogic server. Add the following jar files to the CLASSPATH environment variable in the:runWeblogic section of the script after the Set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar line.

set CLASSPATH=%CLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jar

For BEA WebLogic 7.0, and BEA WebLogic Application Server 7.0 with SP2, SP4, SP5 and SP6 with the JMS transport, the request-response invocation service fails with the com.microstar.xml.SAXDriver is not in classpath error.

Add the following lines to the WebLogic startWLS.cmd file:

set TIBCO_TPCL_HOME=C:\tibco\tpcl\<version_num>

set CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jar

set CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jar



set CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jar

Deploying the Connector

To deploy the connector:

1. Start the application server by running the following commands in the <WebLogic_HOME>\server\bin directory:

— setWLSEnv.cmd

— startWLS.cmd

2. Click Start > Programs > BEA WebLogic Platform 7.0 > WebLogic Server 7.0 > Server Tour and Examples > Start Admin Console.

3. Enter your username and password.

4. Click Connectors under the Domain Configuration section and then click Configure a new Connector Component.

5. Click upload it through your browser.

6. Click Browse to select the AeConnector.rar file from the <ADEJB_HOME>\lib directory.

7. Click Upload to deploy the connector in the container. The file will be listed in the browser.

8. Click Select for the connector.

9. Choose your application server from the Available Servers list and move it to the Target Servers list. The connector, AeConnector.rar, will be displayed in the Enter a name for this application field in Step 4.

10. Click Configure and Deploy to deploy the connector.

Preparation on UNIX PlatformsOn Microsoft Windows platforms, preparing the application server for use with the adapter involves the following tasks:

If you are using the HTTPS protocol to access the repository or if you are using a repository present in a repository server, do the following for the subscription and request-response server services:

Add <TPCL_HOME>/lib/entrust/unsigned to the tibco.env.STD_CP_EXT property in the tra file associated with the request-response server and subscription services. You must include this path before the reference to the <TPCL_HOME>/lib/entrust.







1. The setWLSEnv.sh file can be located under the following directory:

<WebLogic_HOME>/server/bin

2. Add the following environment variables after the section related to setting WL_HOME. The environment variable must point to the installation directory for the product.

— export TIBCO_TRA_HOME=<TRA installation directory>

— export TIBCO_RV_HOME=<TIBCO Rendezvous installation directory>

— export TIBCO_ADEJB_HOME=<Adapter installation directory>

— export TIBCO_TPCL_HOME=<Third party core libraries installation directory>

— export TIBCO_JRE_HOME=<JRE installation directory>

The setWLSEnv.sh file sets the environment for user applications. Add the following jar files to the CLASSPATH environment variable in the setWLSEnv.sh file.

CLASSPATH=$CLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarCLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarCLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarCLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jarCLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarCLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jar

3. At the end of the setWLSEnv.sh file add the following lines to update the LD_LIBRARY_PATH, SHLIB_PATH, or LIBPATH.

For HP-UX:

SHLIB_PATH=$SHLIB_PATH:$TIBCO_TRA_HOME/libSHLIB_PATH=$SHLIB_PATH:$TIBCO_RV_HOME/libexport SHLIB_PATH

For Solaris and Linux:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TIBCO_TRA_HOME/libLD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TIBCO_RV_HOME/libexport LD_LIBRARY_PATH



For AIX:

LIBPATH=$LIBPATH:$TIBCO_TRA_HOME/libLIBPATH=$LIBPATH:$TIBCO_RV_HOME/libexport LIBPATH

4. The startWLS.sh file can be located under the following directory:








The startWLS.sh file sets the required environment for starting the WebLogic server. Add the following jar files to the CLASSPATH environment variable.

CLASSPATH=$CLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarCLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarCLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarCLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarCLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarCLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jar

6. In the startWLS.sh file, modify the LD_LIBRARY_PATH for Solaris and Linux, SHLIB_PATH for HP-UX, and LIBPATH for AIX to include TIBCO Rendezvous shared objects.

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TIBCO_RV_HOME/lib

For BEA WebLogic 7.0, and BEA WebLogic Application Server 7.0 with SP2, SP4, SP5 and SP6 with the JMS transport, the request-response invocation service fails with the com.microstar.xml.SAXDriver is not in classpath error.

Add the following lines to the WebLogic startWLS.sh file:

set TIBCO_TPCL_HOME=C:/tibco/tpcl/5.3

set CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jar

set CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jar



7. In the command window from which you are starting the application server, set TIBCO_RV_HOME/bin in the PATH environment variable.



1. At the command prompt, go to the <WebLogic_HOME>\server\bin directory and run startWLS.sh.

2. Enter your username and password.

3. Click Connectors under the Domain Configuration section and then click Configure a new Connector Component.

4. Click upload it through your browser under Step 1.

5. Click Browse to select the AeConnector.rar file from the <ADEJB_HOME>/lib directory.

6. Click Upload to deploy the connector in the container. The file will be listed under Step 2 in the browser.

7. Click Select for the connector.

8. Choose your application server from the Available Servers list and move it to the Target Servers list. The connector, AeConnector.rar, will be displayed in the Enter a name for this application field in Step 4.

9. Click Configure and Deploy under Step 5 to deploy the connector.


• Add <TPCL_HOME>/lib/entrust/unsigned to the tibco.env.STD_CP_EXT property in the tra file associated with the request-response server and subscription services. You must include this path before the reference to the <TPCL_HOME>/lib/entrust.


Preparing BEA WebLogic Application Server 8.1/BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5 or

Preparing BEA WebLogic Application Server 8.1/BEA WebLogic

Application Server 8.1 with SP1, SP2, SP3, SP4, SP5 or SP6

You can configure the application server for use on Microsoft Windows and UNIX platforms. To deploy the connector to the WebLogic application server, do one of the following:

• Manually deploy the connector

— OR —

• Automatically deploy the connector using the Ant script provided under <TIBCO_ADEJB_HOME>/deploy.

Manually Deploying the Connector on Microsoft Windows PlatformsDeploying the connector in the application server involves the following tasks:





1. The setWLSEnv.cmd file is located under the following directory:








The setWLSEnv.cmd file also sets the environment for user applications. Add the following jar files to the CLASSPATH environment variable in the :setWLSEnv section after the set:CLASSPATH=%WEBLOGIC_CLASSPATH%;%CLASSPATH% line:

set CLASSPATH=%CLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jar



set CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jar

3. The startWLS.cmd file is located under the following directory:


4. Add the following environment variables to the :runWebLogic section of the file. The environment variable must point to the installation directory for the product.






The startWLS.cmd file sets the required environment for starting the WebLogic server. Add the following jar files to the CLASSPATH environment variable in the:runWeblogic section of the script after the Set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar line.

set CLASSPATH=%CLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jar

If you are using the HTTPS protocol to access the repository or if you are using a repository present in a repository server, do the following:

• For the publication and request-response invocation services, add all the jar files present in the <TPCL_HOME>/lib/entrust directory to the WebLogic classpath.





1. To start the WebLogic server, at the command prompt, go to the <WebLogic_HOME>\server\bin directory on Microsoft Windows and run the startWLS command.

2. Click Start > Programs > BEA WebLogic Platform 8.1 > Examples > WebLogic Server Examples > Server Admin Console to start the Administrator Console.

3. Type the username and password to start the WebLogic server.

4. Click Connector Modules under Deployments.

5. Click Deploy a new Connector Module.

6. Click Upload your file(s).

7. Click Browse and choose AeConnector.rar under the <ADEJB_HOME>\lib directory.

8. Click the myserver folder.

9. Click Upload folder.

10. Select AeConnector.rar and click Target module.

11. Click Deploy. The Status of Last Action column will display a message that states that the deployment is successful.

Automatically Deploying the Connector on Microsoft Windows PlatformsDeploying the connector in the application server involves the following task:

• Running ant target deploy.adapter.weblogic81 from the ant script.

On UNIX, in the command window from which you are starting the application server, set TIBCO_RV_HOME/bin in the PATH environment variable.

If you are an existing user of TIBCO Adapter for EJB, and have an existing deployment of the connector and its glue beans from an earlier version of the adapter, you must uninstall it before running the ant script. For details, see Appendix E, Uninstalling an Existing Connector and Glue Beans for your Application Server, on page 423.



Running ant target deploy.adapter.weblogic81 from ant script

1. Edit the %TIBCO_ADEJB_HOME%\deploy\build-dist.properties file and change the values of the following properties in that file. For directory path, use forward slash ("/").

— tibco.tibrv.dir (Location of the TIBCO Rendezvous installation directory)

— tibco.tpcl.dir (Location of TIBCO Third Party Core Libraries (TPCL) directory)

— tibco.tra.dir (Location of the TIBCO Runtime Agent installation directory)

— tibco.adejb.dir (Location of the TIBCO Adapter for EJB directory)

— tibco.ejb.gen.code.dir (Location of the directory in which the source code is generated by the TIBCO Adapter for EJB palette)

— tibco.connector.repourl (Repourl of the TIBCO Adapter for EJB specified in the connector DD ra.xml)

— tibco.connector.configurl (Configurl of the TIBCO Adapter for EJB specified in the connector DD ra.xml)

— tibco.connector.trafilename (Configurl of the TIBCO Adapter for EJB specified in the connector DD ra.xml)

— tibco.connector.jndi.name (JNDI name of the connector, for example, tibco/aeconnector, which will be specified in Weblogic-ra.xml). It is very important that this value should be the same as the value specified for the Resource Reference while generating the glue bean code from the TIBCO Adapter for EJB palette.

— ejb.spec.version (The version of the EJB specification you use to generate the glue beans deployment descriptor. The valid values are: 2.0 and 2.1. The MDB code generation value must be 2.1 and the application server used must be J2EE 1.4 compliant.)

— application.xml.disp.name (value of the tag display-name in deploymentdescriptorapplication.xml of EAR file.)

— application.xml.desc (value of the tag description in deploymentdescriptorapplication.xml of EAR file.)

— rar.file.name (Name of the RAR file generated by ant script that contains the resource adapter deployment descriptor and will be packaged in EAR file.)

— ear.file.name (Name of the EAR file generated by ant script which contains the resource adapter RAR file and the glue beans JAR file.)



— ejb.jar.file.name (Name of the EJB JAR file prepared by ant script that contains the glue beans.)

— tibco.connector.dir.loc (Directory where the application server-specific RAR file is located)

— weblogic.8.1.home (WebLogic 8.1 installation directory location)

— weblogic.8.1.adminurl (WebLogic 8.1 administration url)

— weblogic.8.1.target.server (WebLogic 8.1 server name)

— weblogic.8.1.user (WebLogic 8.1 administrator user name)

— weblogic.8.1.password (WebLogic 8.1 administrator password)

2. Open a command prompt window and go to the %TIBCO_ADEJB_HOME%\deploy directory.

3. Set up the WebLogic environment by running <WebLogic_HOME>\server\bin\setWLSEnv.cmd at the command prompt.

4. Make sure the WebLogic application server to which you want to deploy the connector is running.

5. Run the ant target by typing the command ant deploy.adapter. weblogic81 at the command prompt.

A message is displayed, indicating that the connector along with the glue beans have been deployed successfully to the WebLogic application server.

Manually Deploying the Connector on UNIX PlatformsDeploying the connector in the application server involves the following tasks:





1. The setWLSEnv.sh file is located under the following directory:










The setWLSEnv.sh file also sets the environment for user applications. Add the following jar files to the CLASSPATH environment variable:

export CLASSPATH=$CLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarexport CLASSPATH=$CLASSPATHVTIBCO_TRA_HOME/lib/TIBCOtsm.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jar

3. At the end of the setWLSEnv.sh file add the following lines to update the LD_LIBRARY_PATH, SHLIB_PATH, or LIBPATH.

For HP-UX:




For AIX:LIBPATH=$LIBPATH:$TIBCO_TRA_HOME/libLIBPATH=$LIBPATH:$TIBCO_RV_HOME/libexport LIBPATH

4. The startWLS.sh file is located under the following directory:










The startWLS.sh file sets the required environment for starting the WebLogic server. Add the following jar files to the CLASSPATH environment variable.

export CLASSPATH=$CLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jar






1. To start the WebLogic server, at the command prompt, go to the <WebLogic_HOME>/server/bin directory and run the startWLS.sh command





2. Start the Administrator Console.


4. Click Connector Modules under Deployments.

5. Click Deploy a new Connector Module.

6. Click Upload your file(s).

7. Click Browse and choose AeConnector.rar under the <ADEJB_HOME>/lib directory.

8. Click the myserver folder.

9. Click Upload folder.

10. Select AeConnector.rar and click Target module.

11. Click Deploy. The Status of Last Action column will display a message that states that the deployment is successful.

Automatically Deploying the Connector on UNIX PlatformsDeploying the connector in the application server involves the following task:

• Running the ant target deploy.adapter.weblogic81 from the ant script.





Running the ant target deploy.adapter.weblogic81 from the ant script

1. Edit $TIBCO_ADEJB_HOME/deploy/build-dist.properties file and change the values of the following properties in that file. For directory path, use forward slash ("/").











— application.xml.disp.name (value of the tag display-name in deploymentdescriptorapplication.xml of EAR file.)

— application.xml.desc (value of the tag description in deployment descriptorapplication.xml of EAR file.)

— rar.file.name (Name of the RAR file generated by ant script that contains the resource adapter deployment descriptor and will be packaged in EAR file.)

— ear.file.name (Name of the EAR file generated by ant script which contains the resource adapter RAR file and the glue beans JAR file.)



— ejb.jar.file.name (Name of the EJB JAR file prepared by ant script that contains the glue beans.)







2. Change directory to the $TIBCO_ADEJB_HOME/deploy directory.

3. Set up the WebLogic environment by running <WebLogic_HOME>/server/bin/setWLSEnv.sh at the command prompt.

4. Make sure that the WebLogic application server to which you want to deploy the connector is running.

5. Run the ant target by typing the command ant deploy.adapter. weblogic81 at the command prompt.



Preparing BEA WebLogic Application Server 9.0, 9.1, and 9.2 | 117

Preparing BEA WebLogic Application Server 9.0, 9.1, and 9.2

You can configure the application server for use on Microsoft Windows and UNIX platforms. To deploy the connector to the WebLogic application server, do one of the following:


— OR —


Manually Deploying the Connector on Microsoft Windows PlatformsDeploying the connector in the application server involves the following tasks:





1. The setWLSEnv.cmd file is located under the following directory: <WebLogic_HOME>\server\bin







The setWLSEnv.cmd file also sets the environment for user applications. Add the following jar files to the CLASSPATH environment variable in the :setWLSEnv section after the set:CLASSPATH=%WEBLOGIC_CLASSPATH%;%CLASSPATH% line:

set CLASSPATH=%CLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jar



set CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jar

3. The startWLS.cmd file is located under the following directory: <WebLogic_HOME>\server\bin

4. Add the following environment variables to the :runWebLogic section of the file. The environment variable must point to the installation directory for the product.






The startWLS.cmd file sets the required environment for starting the WebLogic server. Add the following jar files to the CLASSPATH environment variable in the :runWeblogic section of the script after the Set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar line.

set CLASSPATH=%CLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jarset CLASSPATH=%CLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset CLASSPATH=%CLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jar







1. Start the WebLogic server:

— At the command prompt, go to the <WebLogic_HOME>\server\bin directory on Microsoft Windows and run the startWLS command.

— At the command prompt, go to the <WebLogic_HOME>/server/bin directory and run the startWLS.sh command.

2. Start the Administrator Console.


4. Click Lock & Edit under Change Center.

5. Click Deployments under Domain Structure.

6. Click Install under Deployments.

7. Choose AeConnector.rar under the <ADEJB_HOME>\lib directory.

8. Click Next.

9. Choose Install this deployment as an application and click Next.

10. Click Next.

11. Click Finish.

12. Click Save to save the changes.

13. Click Activate Changes under Change Center.


15. Select the check box for AeConnector under deployments. Click Start > Servicing all requests.

The State column will display the Active value if the deployment is successful.


• Running ant target deploy.adapter.weblogic90 from the ant script




Running ant target deploy.adapter.weblogic90 from the ant script

1. Edit the %TIBCO_ADEJB_HOME%/deploy/build-dist.properties file and change the values of the following properties in that file. For directory path, use forward slash ("/").










— tibco.inbound.connector.jndi.name (jndi-name tag in weblogic-ra.xml for deployment of JCA 1.5 EJB adapter. This JNDI name is used by MDBs to bind to the resource adapter during the end point



activation of MDBs. There is another jndi-name tag inside outbound-resource-adapter tag.)

— rar.file.name (Name of the RAR file generated by the ant script that contains the resource adapter deployment descriptor. It will be packaged in EAR file.)

— ear.file.name (Name of the EAR file prepared by the ant script that contains the resource adapter RAR file and the glue beans JAR file.)

— ejb.jar.file.name (Name of theEJB JAR file generated by the ant script that contains the glue beans.)


— application.xml.disp.name (Value of the tag display-name in deploymentdescriptorapplication.xml of EAR file.)

— application.xml.desc (Value of the tag description in deploymentdescriptorapplication.xml of EAR file.)







2. Open a command prompt window and go to the %TIBCO_ADEJB_HOME%\deploy directory.

3. Set up the WebLogic environment by running <WebLogic_HOME>\server\bin\setWLSEnv.cmd at the command prompt.

4. Make sure the WebLogic application server to which you want to deploy the connector is running.

5. Run the ant target by typing the command deploy.adapter.weblogic90 at the command prompt.

After you run the ant script EAR file, the glue beans JAR file is generated in dist directory under %TIBCO_ADEJB_HOME%\deploy directory. Because XDoclet engine which TIBCO uses to generate the deployment descriptor for EJBs does not support Weblogic 9.0, you must manually prepare the



weblogic-ejb-jar.xml for the beans getting deployed and package them in EJB JAR file and package the EJB JAR back into the EAR file generated. You can now deploy the EAR file that cotains the resource adapter and the glue beans to Weblogic 9.0 application server. You can find an example weblogic-ejb-jar.xml can be found at %TIBCO_ADEJB_HOME%\examples\beans\META-INF directory. Deploy the EAR file to WebLogic 9.0 application server using WebLogic admin console.


Manually Deploying the Connector on UNIX PlatformsDeploying the connector in the application server involves the following tasks:





1. The setWLSEnv.sh file is located under the following directory: <WebLogic_HOME>/server/bin







The setWLSEnv.sh file also sets the environment for user applications. Add the following jar files to the CLASSPATH environment variable:

export CLASSPATH=$CLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jar



export CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jar

3. At the end of the setWLSEnv.sh file, add the following lines to update the LD_LIBRARY_PATH, SHLIB_PATH, or LIBPATH.

For HP-UX:


For Solaris and Linux:LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TIBCO_TRA_HOME/libLD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TIBCO_RV_HOME/libexport LD_LIBRARY_PATH

For AIX:


4. The startWLS.sh file is located under the following directory: <WebLogic_HOME>/server/bin







The startWLS.sh file sets the required environment for starting the WebLogic server. Add the following jar files to the CLASSPATH environment variable:

export CLASSPATH=$CLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarexport CLASSPATH=$CLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarexport CLASSPATH=$CLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jar








1. To start the WebLogic server, at the command prompt, go to the WebLogic_HOME>/server/bin directory and run the startWLS.sh command

2. Start the Administrator Console:


4. Click Lock & Edit under Change Center.


6. Click Install under Deployments.

7. Choose AeConnector.rar under the <ADEJB_HOME>\lib directory.

8. Click Next.

9. Choose Install this deployment as an application and click Next.

10. Click Next.

11. Click Finish.

12. Click Save to save the changes.

13. Click Activate Changes under Change Center.


15. Select the check box for AeConnector under deployments. Click Start > Servicing all requests.

The State column will display the Active value if the deployment is successful.






• Running ant target deploy.adapter.weblogic90 from the ant script

Running ant target deploy.adapter.weblogic90 from the ant script

1. Edit $TIBCO_ADEJB_HOME/deploy/build-dist.properties file and change the values of the following properties in that file. For directory path, use forward slash ("/").








— tibco.connector.jndi.name (JNDI name of the connector, for example, tibco/aeconnector, which will be specified in Weblogic-ra.xml). It is very important that this value should be the same as the value specified for Resource Reference while generating the glue bean code from the EJB adapter palette.

— tibco.inbound.connector.jndi.name (jndi-name tag in weblogic-ra.xml for deployment of JCA 1.5 EJB adapter. This JNDI name is used by MDBs to bind to the resource adapter during the end point



activation of MDBs. There is another jndi-name tag inside outbound-resource-adapter tag.)

— rar.file.name (Name of the RAR file generated by the ant script that contains the resource adapter deployment descriptor. It will be packaged in EAR file.)

— ear.file.name (Name of the EAR file prepared by the ant script that contains the resource adapter RAR file and the glue beans JAR file.)

— ejb.jar.file.name (Name of theEJB JAR file generated by the ant script that contains the glue beans.)


— application.xml.disp.name (Value of the tag display-name in deploymentdescriptorapplication.xml of EAR file.)









3. Set up the WebLogic environment by running <WebLogic_HOME>/server/bin/setWLSEnv.sh at the command prompt.

4. Make sure that the WebLogic application server to which you want to deploy the connector is running.

5. Run the ant target by typing the command deploy.adapter.weblogic90 at the command prompt.

After you run the ant script EAR file, the glue beans JAR file is generated in dist directory under %TIBCO_ADEJB_HOME%\deploy directory. Because XDoclet engine which TIBCO uses to generate the deployment descriptor for EJBs does not support Weblogic 9.0, you must manually prepare the weblogic-ejb-jar.xml for the beans getting deployed and package them in



EJB JAR file and package the EJB JAR back into the EAR file generated. You can now deploy the EAR file that cotains the resource adapter and the glue beans to Weblogic 9.0 application server. You can find an example weblogic-ejb-jar.xml can be found at $TIBCO_ADEJB_HOME\examples\beans\META-INF directory. Deploy the EAR file to WebLogic 9.0 application server using WebLogic admin console.




Preparing IBM WebSphere 5.1.0 Application Servers

To install and set up the application server, see http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1/index.jsp

To deploy the connector to the WebSphere application server, do one of the following:


— OR —


Manually Deploying the Connector on Microsoft Windows and UNIX PlatformsPreparing the application server to interact with the adapter on Microsoft Windows or UNIX platforms involves the following steps:


• Installing the Connector

• Adding a Connection Factory

Set the following environment variables. The environment variable must point to the installation directory for the product.

— TIBCO_TRA_HOME=<TRA installation directory>

— TIBCO_RV_HOME=<TIBCO Rendezvous installation directory>

— TIBCO_ADEJB_HOME=<Adapter installation directory>

— TIBCO_TPCL_HOME=<Third party core libraries installation directory>

— WAS_HOME=<WebSphere installation directory>

— TIBCO_JRE_HOME=<JRE installation directory>


Preparing IBM WebSphere 5.1.0 Application Servers | 129



1. Copy the following jar files to the location of IBM WebSphere Application server, <WAS_HOME>/lib/ext:

— <ADEJB_HOME>/<version_num>/lib/EjbSupport.jar

— <ADEJB_HOME>/<version_num>/lib/GlBeansSupport.jar

— <TIBCO_TRA HOME>/lib/TIBCOrt.jar

— <TIBCO_TRA HOME>/lib/TIBCOxml.jar

— <TIBCO_TRA HOME>/lib/TIBCOtsm.jar

— <TIBCO_TRA HOME>/lib/TIBCOjms.jar

— <TIBCO_TRA HOME>/lib/TIBCrypt.jar

— <TIBCO_RV_HOME>/lib/tibrvj.jar

— <TIBCO_TPCL_HOME>/<version_num>/lib/xmlParserAPIs.jar

— <TIBCO_TPCL_HOME>/<version_num>/lib/xercesImpl.jar

2. Modify the LIBRARY PATHs in the startServer.sh script on UNIX. This file is located in the <WAS_HOME>/bin directory:

TIBCO_RV_HOME=<TIBCO Rendezvous installation directory>export TIBCO_RV_HOME

PLATFORM=`/bin/uname`case $PLATFORM in AIX)

EXTSHM=ONLIBPATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LIBPATHexport LIBPATH EXTSHM ;;

Linux)LD_LIBRARY_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LD_LIBRARY_PATHexport LD_LIBRARY_PATH ;;SunOS)LD_LIBRARY_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LD_LIBRARY_PATH export LD_LIBRARY_PATH ;;HP-UX)

On UNIX:

Define the TIBCO_RV_HOME variable in the startServer.sh script that will be used to start the application server.

In the command window from which you are starting the application server, set TIBCO_RV_HOME/bin in the PATH environment variable.



SHLIB_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$SHLIB_PATHexport SHLIB_PATH ;;esac

Installing the Connector

To install the connector:

1. Do one of the following to start the server:

— On Microsoft Windows, select Start > Programs > IBM WebSphere > Application Server V5.0 > Start the Server to start the WebSphere Application Server 5.0. The application server may take a few minutes to start.

— On UNIX, go to the <WebSphere_HOME>/bin directory and run startServer <node_name>.

2. Do one of the following to start the administrative console:

— On Microsoft Windows, select Start > Programs > IBM WebSphere > Application Server V5.0 > Administrative Console to start the administrative console. A browser with two panels is displayed.

— On UNIX, open a browser window and in the Address field enter <local host>://<port>/admin/.

3. Click Resources and then click Resource Adapters. The Resource Adapters page is displayed.

4. Click Install RAR, to install the connector.

5. Click Browse to locate the AeConnector.rar file. This file is in the lib subdirectory of the adapter installation.

6. Select Node depending on which machine you will use to install the connector. By default, only the local machine is listed.

7. Click Next to continue installing the connector.

8. Enter the connector name as TIBCOAeConnector in the Name field.

9. Click OK to complete the deployment. The connector, TIBCOAeConnector, is displayed.


• For the publication and request-response invocation services, copy all the jar files present in <TPCL_HOME>/lib/entrust to the <WAS_HOME>/lib/ext directory.



10. Click Save to apply changes to the master configuration.

Adding a Connection Factory

To add a connection factory:

1. Start the WebSphere Administrative Console and click Resource Adapters under Resources.

2. Click TibcoAeConnector and then J2C Connection Factories.

3. Click New to display the J2C Connection Factory Properties window.

4. Enter the connection reference name as TIBCOAeConnector in the Name field.

5. Enter the JNDI binding path as tibco/aeconnector in the JNDI Name field.

6. Click Apply to create a connection factory.

7. Click Save to save the master configuration.

8. Click Resource Adapters under Resources.

9. Click J2C Connection Factories under TibcoAeConnector.

10. Click TibcoAeConnector under J2C Connection Factories.

11. Click Custom Properties under TibcoAeConnector.

12. Select the RepoUrl property and enter <repoUrl> in the Value field.

For example, D:/tibco/adapter/adejb/<version_num>/examples/data/ejb_sample.d

at

13. Click Apply.

14. Select the ConfigUrl property and enter <configUrl> in the Value field.

For example, /tibco/private/adapter/Connector/RPC/EJBAdapter

15. Click Apply.

16. Select the TraFileName property and enter <traFileName> in the Value field. For example,D:/tibco/adapter/adejb/<version_num>/bin/connector.tra.

Click Apply and click Save to save the master configuration.




• Running ant target deploy.adapter.was51 from the ant script.

Running ant target deploy.adapter.was51 from the ant script












— WAS.5.1.home (WAS 5.1 installation directory location)

— WAS.5.1.host (WAS 5.1 host machine IP address)




— WAS.5.1.node (Name of the WAS 5.1 node where the connector will be installed)

— WAS.5.1.cell (Name of the WAS 5.1 cell where the connector will be installed)

— WAS.5.1.user (WAS 5.1 administrator user name)

— WAS.5.1.password (WAS 5.1 administrator password)

2. Change to the %TIBCO_ADEJB_HOME%\deploy directory.

3. Set up the WebSphere environment by running <WAS_HOME>\bin\ setupCmdLine.bat at the command prompt.

4. Make sure the WebSphere application server to which you want to deploy the connector is running.

5. Run the ant target by typing the command ant deploy.adapter.was51 at the command prompt.

A message is displayed, indicating that the connector along with the glue beans have been deployed successfully to the WebSphere application server.


1. Running ant target deploy.adapter.was51 from the ant script.


1. Edit the $TIBCO_ADEJB_HOME/deploy/build-dist.properties file and change the values of the following properties in that file. For directory path, use forward slash ("/").












— application.xml.desc (This will be value of the tag description in deploymentdescriptorapplication.xml of EAR file.)

— rar.file.name (Name of the RAR file generated by ant script that contains the resource adapter deployment descriptor. It will be packaged in EAR file.)

— ear.file.name (Name of theEAR file prepared by ant script which contains the resource adapter RAR file and glue beans jar.)

— ejb.jar.file.name (Name of theEJB jar file generated by ant script that contains the glue beans.)


— application.xml.disp.name (This will be value of the tag display-name in deploymentdescriptorapplication.xml of EAR file)










2. Change to the $TIBCO_ADEJB_HOME/deploy directory.

3. Set up the WebSphere environment by running <WAS_HOME>/bin/ setupCmdLine.sh at the command prompt.


5. Run the ant target by typing the command ant deploy.adapter.was51 at the command prompt.




Preparing IBM WebSphere 6.0 Application Server


To deploy the connector to the WebSphere application server, you must manually deploy the connector.

Manually Deploying the Connector on Microsoft Windows and UNIX PlatformsPreparing the application server to interact with the adapter on Microsoft Windows or UNIX platforms involves the following steps:


• Installing the Connector

• Adding a Connection Factory






— WAS_HOME=<WebSphere installation directory>




Automatic deployment of connector using the ant scripts is applicable only for IBM WebSphere 6.0.2 and 6.1.


Preparing IBM WebSphere 6.0 Application Server | 137

1. Copy the following jar files to the location of the IBM WebSphere Application server, <WAS_HOME>/lib/ext:

— <ADEJB_HOME>/<version_num>/lib/EjbSupport.jar

— <ADEJB_HOME>/<version_num>/lib/GlBeansSupport.jar

— <TIBCO_TRA HOME>/lib/TIBCOrt.jar

— <TIBCO_TRA HOME>/lib/TIBCOxml.jar

— <TIBCO_TRA HOME>/lib/TIBCOtsm.jar

— <TIBCO_TRA HOME>/lib/TIBCOjms.jar

— <TIBCO_TRA HOME>/lib/TIBCrypt.jar

— <TIBCO_RV_HOME>/lib/tibrvj.jar

— <TIBCO_TPCL_HOME>/5.3/lib/xmlParserAPIs.jar

— <TIBCO_TPCL_HOME>/5.3/lib/xercesImpl.jar

2. Modify the LIBRARY PATHs in the startServer.sh script on UNIX. This file is located in the <WAS_HOME>/bin directory:

TIBCO_RV_HOME=<TIBCO Rendezvous installation directory>export TIBCO_RV_HOMEPLATFORM=`/bin/uname`case $PLATFORM in AIX)EXTSHM=ONLIBPATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LIBPATHexport LIBPATH EXTSHM ;;Linux)LD_LIBRARY_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LD_LIBRARY_PATHexport LD_LIBRARY_PATH ;;SunOS)LD_LIBRARY_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LD_LIBRARY_PATHexport LD_LIBRARY_PATH ;;HP-UX)SHLIB_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$SHLIB_PATHexport SHLIB_PATH ;;esac

On UNIX:

Define the TIBCO_RV_HOME variable in the startServer.sh script that will be used to start the application server. In the command window from which you are starting the application server, set TIBCO_RV_HOME/bin in the PATH environment variable.



Installing the Connector

To start the administrative console:

1. Do one of the following:

— On Microsoft Windows, select Start > Programs > IBM WebSphere > Application Server V6.0 > Profiles > <Server Name>Administrative Console to start the administrative console. A browser with two panels is displayed.

— On UNIX, open a browser window and in the Address box enter <localhost>://<port>/admin/.

2. Enter the User Id to continue.


4. Click Install RAR, to install the connector.

5. Click Browse to locate the AeConnector.rar file. This file is in the lib subdirectory of the adapter installation.

6. Click Next to continue installing the connector.

7. Enter the connector name as TIBCOAeConnector in the Name field.

8. Click OK to complete the deployment. The connector, TIBCOAeConnector, is displayed.

9. Click Save to apply changes to the master configuration.

Adding a Connection Factory

1. Start the WebSphere Administrative Console and click Resource Adapters under Resources.

2. Click TibcoAeConnector and then J2C Connection Factories.

3. Click New to display the J2C Connection Factory Properties window.

4. Enter the connection reference name as TIBCOAeConnector in the Name box.


• For the publication and request-response invocation services, copy all the jar files present in <TPCL_HOME>/lib/entrust to the <WAS_HOME>/lib/ext directory.


Preparing IBM WebSphere 6.0 Application Server | 139

5. Enter the JNDI binding path as tibco/aeconnector in the JNDI Name box.

6. Click Apply to create a connection factory.

7. Click Save to save the master configuration.

8. Click Resource Adapters under Resources.

9. Click J2C Connection Factories under TibcoAeConnector.

10. Click TibcoAeConnector under J2C Connection Factories.

11. Click Custom Properties under TibcoAeConnector.

12. Select the RepoUrl property and enter the <repoUrl> in the Value box. For example, D:/tibco/adapter/adejb/<version_num>/examples/data/ejb_sample.d

at

13. Click OK.

14. Select the ConfigUrl property and enter the <configUrl> in the Value box. For example, /tibco/private/adapter/Connector/RPC/EJBAdapter

15. Click OK.

16. Select the TraFileName property and enter d:\tibco\adapter\adejb\<version_num>\bin\connector.tra

17. Click OK and click Save to save the master configuration.



Preparing IBM WebSphere 6.0.2 and 6.1 Application Servers


Preparing the application server to interact with the adapter on Microsoft Windows or UNIX platforms involves the following steps:

Manually Deploying the Connector on Microsoft Windows and Unix PlatformsFor information on deploying the connector manually on Microsoft Windows and Unix platforms, see , Manually Deploying the Connector on Microsoft Windows and UNIX Platforms, on page 136.


• Running ant target deploy.adapter.was60 from the ant script


Preparing IBM WebSphere 6.0.2 and 6.1 Application Servers | 141




























3. Set up the WebSphere environment by running <WAS_HOME>\bin\setupCmdLine.bat at the command prompt.


5. Run the ant target by typing the command <WAS_HOME>\bin\ws_ant deploy.adapter.was60 at the command prompt at the command prompt.



• Running ant target deploy.adapter. was60 from the ant script

Running ant target deploy.adapter. was60 from the ant script





Preparing IBM WebSphere 6.0.2 and 6.1 Application Servers | 143


















— WAS. 6.0.host (WAS 6.0 host machine IP address)

— WAS. 6.0.node (Name of the WAS 6.0 node where the connector will be installed)

— WAS. 6.0.cell (Name of the WAS 6.0 cell where the connector will be installed)



2. Change to the $TIBCO_ADEJB_HOME/deploy directory.

3. Set up the WebSphere environment by running <WAS_HOME>/bin/setupCmdLine.sh at the command prompt.


5. Run the ant target by typing the command <WAS_HOME>\bin\ws_ant deploy.adapter.was60 at the command prompt.



Preparing the Sun Java System Application Server Platform Edition 7 | 145

Preparing the Sun Java System Application Server Platform Edition

7

To install and configure the Sun Java System Application Server Platform Edition 7, follow the steps outlined in:

• http://docs.sun.com/

• http://wwws.sun.com/software/products/appsrvr/appsrvr_download.html

Preparing the application server for use with the adapter on Microsoft Windows or UNIX platforms involves the following tasks:











1. For Microsoft Windows:

Click Start > Programs > Sun Microsystems > Sun ONE Application Server V7 > Start Application Server to start the application server. The application server will take a few minutes to start.

For Unix:

Execute this command: <APPSERVER_HOME>/bin/asadmin start-domain <domain-name>





Click Start > Programs > Sun Microsystems > Sun ONE Application Server V7 > Start Administrative Console to start the administrative console. A browser with two panels is displayed.

For Unix:

Use the URL: http://<IP_address_of_app_server_machine>:4848

3. Click JVM Settings and then click Path Settings and enter a class path.

4. Enter the following jar files in the Class Path suffix field, and use the semicolon (;) as a file separator:

— <ADEJB_HOME>\lib\EjbSupport.jar

— <ADEJB_HOME>\lib\GlBeansSupport.jar

— <ADEJB_HOME>\lib\AeConnector.jar

— <TIBCO_TRA HOME>\lib\TIBCOrt.jar

— <TIBCO_TRA HOME>\lib\TIBCOxml.jar

— <TIBCO_TRA HOME>\lib\TIBCOtsm.jar

— <TIBCO_TRA HOME>\lib\TIBCOjms.jar

— <TIBCO_TRA HOME>\lib\TIBCrypt.jar

— <TIBCO_RV_HOME>\lib\tibrvj.jar

— <TIBCO_TPCL_HOME>\lib\xmlParserAPIs.jar

— <TIBCO_TPCL_HOME>\lib\xercesImpl.jar

5. Enter D:\tibco\tra\5.3\bin in the Native path prefix and Native path suffix fields, if you have installed the TIBCO Runtime Agent in D:, otherwise, modify the path to reflect the correct system drive.

6. Add the following to the end of the server.policy file that is present in the <APPSERVER_HOME>\domains\domain1\server1\config directory:

// Permissions for TIBCO Rendezvous"grant {permission java.util.PropertyPermission "*", "read,write";

};



1. Click Start > Programs > Sun Microsystems > Sun ONE Application Server V7 > Start Application Server to start the application server. Typically, the application server will take a few minutes to start.


Preparing the Sun Java System Application Server Platform Edition 7 | 147

2. Click Start > Programs > Sun Microsystems > Sun ONE Application Server V7 > Start Administrative Console to start the administrative console. A browser with two panels is displayed.

3. Click Applications for your server instance.

4. Click Connector Modules.

5. Click Deploy to install the connector.

6. Click Browse to locate the AeConnector.rar file in the <ADEJB_HOME>\lib directory.

7. Click OK to complete the deployment of the connector. A window is displayed and the connector is named TIBCOAeConnector.



Preparing the Sun Java System Application server Platform Edition

8.1

To install and configure the Sun Java System Application Server Platform Edition8, follow the steps outlined in:

• http://docs.sun.com/

• http://wwws.sun.com/software/products/appsrvr/appsrvr_download.html

Preparing the application server for use with the adapter on Microsoft Windows or UNIX platforms involves the following tasks:




• TIBCO_TRA_HOME=<TRA installation directory>

• TIBCO_RV_HOME=<TIBCO Rendezvous installation directory>

• TIBCO_ADEJB_HOME=<Adapter installation directory>

• TIBCO_TPCL_HOME=<Third party core libraries installation directory>

• TIBCO_JRE_HOME=<JRE installation directory>

Configuring the Application ServerTo configure the application server:


Click Start >Programs >Sun Microsystems >Application Server PE >Start Default Server to start the application server. The application server will take a few minutes to start.

For Unix:

Execute this command: <APPSERVER_HOME>/bin/asadmin start-domain <domain-name>


Click Start >Programs >Sun Microsystems >Application Server PE >Admin Console to start the administrative console. A browser with two panels is displayed.


Preparing the Sun Java System Application server Platform Edition 8.1 | 149

For Unix:

Use the URL: http://<IP_address_of_app_server_machine>:4848

3. Click JVM Settings. Then click Path Settings and enter a class path.

4. Enter the following jar files in the Class Path suffix field, and use the semicolon (;) as a file separator:

<ADEJB_HOME>\lib\EjbSupport.jar<ADEJB_HOME>\lib\GlBeansSupport.jar<ADEJB_HOME>\lib\AeConnector.jar<TIBCO_TRA HOME>\lib\TIBCOrt.jar<TIBCO_TRA HOME>\lib\TIBCOxml.jar<TIBCO_TRA HOME>\lib\TIBCOtsm.jar<TIBCO_TRA HOME>\lib\TIBCOjms.jar<TIBCO_TRA HOME>\lib\TIBCrypt.jar<TIBCO_RV_HOME>\lib\tibrvj.jar<TIBCO_TPCL_HOME>\lib\xmlParserAPIs.jar<TIBCO_TPCL_HOME>\lib\xercesImpl.jar

5. Enter D:\tibco\tra\<version_num>\bin in the Native path prefix and Native path suffix fields, if you have installed the TIBCO Runtime Agent in D:, otherwise, modify the path to reflect the correct system drive.

6. Append the following to the end of the server.policy file that is present in the <APPSERVER_HOME>\domains\domain1\config directory:

// Permissions for TIBCO Rendezvous"grant {permission java.util.PropertyPermission "*", "read,write";

};

Deploying the ConnectorTo deploy the connector:

1. Click Start > Programs >Sun Microsystems >Application Server PE>Start Application Server to start the application server. Typically, the application server will take a few minutes to start.

2. Click Start >Programs >Sun Microsystems Application Server PE>Admin Console to start the administrative console. A browser with two panels is displayed.

3. Click Applications for your server instance.

4. Click Connector Modules.

5. Click Deploy to install the connector.

6. Click Browse to locate the AeConnector.rar file in the <ADEJB_HOME>\lib directory.



7. Click OK to complete the deployment of the connector. The connector is named TIBCOAeConnector.


Preparing the Oracle 9i Application Server | 151

Preparing the Oracle 9i Application Server

To install and set up the supported container for this application server, follow the procedure outlined in http://otn.oracle.com/tech/java/oc4j/htdocs/oc4j-install-note.html (for J2EE 1.3 Developer Preview). You can download the Oracle9iAS Containers with J2EE 1.3 Developer Preview from http://otn.oracle.com/tech/java/oc4j/htdocs/utilsoft.html.

Preparation on Microsoft Windows PlatformsOracle J2EE containers have a predefined configuration stored in the server-side configuration file server.xml. If you want to make a Java library available to the application server, the library reference must be added in the server.xml file. This file is located in the <ORACLE9IAS-ROOT>\j2ee\home\config directory.

Preparing the application server on Microsoft Windows platforms involves the following tasks:

• Preparing the Connector


Preparing the Connector

To prepare the connector:

1. Set the following environment variables. The environment variable must point to the installation directory for the product.





— ORACLE9IAS-HOME=<Oracle 9i application server installation>


Oracle J2EE containers have a predefined configuration stored in the server-side configuration file — server.xml. If you want to make a Java library available to the application server, the library reference must be added in the server.xml file. This file is located in the <ORACLE9IAS-ROOT>\j2ee\home\config directory.



For example, if you have installed the adapter at D:\tibco\adapter\adejb\<version_num>; the TRA at D:\tibco\tra\5.3; TPCL at D:\tibco\tpcl\5.3; and TIBCO Rendezvous at D:\tibco\tibrv, you would add the following entry to server.xml file:<library path="<Existing_Jar_Files>;D:\Tibco\adapter\adejb\<version_num>\lib\EjbSupport.jar;D:\Tibco\adapter\adejb\<version_num>\lib\GlBeansSupport.jar;D:\Tibco\adapter\adejb\<version_num>\lib\AeConnector.jar;D:\Tibco\tra\5.3\lib\TIBCOrt.jar;D:\Tibco\tra\5.3\lib\TIBCOjms.jar; D:\Tibco\tra\5.3\lib\TIBCOtsm.jar; D:\Tibco\tra\5.3\lib\TIBCOxml.jar;D:\Tibco\tra\5.3\lib\TIBCrypt.jar;D:\Tibco\tpcl\5.3\lib\xmlParserAPIs.jar;D:\Tibco\tpcl\5.3\lib\xercesImpl.jar;D:\tibco\tibrv\lib\tibrvj.jar;"/>



1. Add the following code to the oc4j-connectors.xml file in the <ORACLE9IAS-ROOT>\j2ee\home\config\ directory.

If this file does not exist, create it, and add the following information. If the file already exists, only add the content marked in the bold type face.

------------------------------------------------------------------<?xml version="1.0" standalone='yes'?><!DOCTYPE oc4j-connectors PUBLIC "-//Oracle//DTD Connectors configuration//EN" "http://xmlns.oracle.com\ias\dtds\oc4j-connectors.dtd"><oc4j-connectors>

<connector name="standalone" path="AeConnector.rar"></connector>

</oc4j-connectors>------------------------------------------------------------------

2. In the <ORACLE9IAS-ROOT>\j2ee\home\config\server.xml file, make sure that the connector-directory attribute is specified in the <application-server> element as connector-directory="../connectors"

3. In the <ORACLE9IAS-ROOT>\j2ee\home\config\application.xml file, make sure the <connector path> element is defined under the <orion-application> element as follows:





<connectors path="./oc4j-connectors.xml"/>

4. Create a directory called standalone in the <ORACLE9IAS-ROOT>\j2ee\home\connectors directory.

5. Copy the Resource adapter (RAR) file (AeConnector.rar) from <ADEJB_HOME>\lib to the <ORACLE9IAS-ROOT>\j2ee\home\connectors\standalone directory.

6. Go to the <ORACLE9IAS-ROOT>\j2ee\home directory and run java -jar oc4j.jar to start the application server. OC4J will automatically unpack AeConnector.rar in the <ORACLE9IAS-ROOT>\j2ee\home\connectors\standalone\AeConnector\ directory.

Preparation on UNIX PlatformsOracle J2EE containers have a predefined configuration stored in the server-side configuration file server.xml. If you want to make a Java library available to the application server, the library reference must be added in the server.xml file. This file is located in the <ORACLE9IAS-ROOT>\j2ee\home\config directory.

Preparing the application server on UNIX platforms involves the following tasks:



If you want to deploy the connector as a JAR (library) instead of a RAR, use the ejb-jar.xml file. EJB deployment descriptors should not refer to any Resource type.





Before you start, do the following:








Oracle J2EE containers have a predefined configuration stored in the server-side configuration file — server.xml. If you want to make a Java library available to the application server, the library reference must be added in the server.xml file. This file is located in the <ORACLE9IAS-ROOT>/j2ee/home/config directory.

For example, if you have installed the adapter at /home/tibco/adapter/adejb/<version_num>; the TRA at /home/tibco/tra/<version_num>; TPCL at /home/tibco/tpcl/<version_num>; and TIBCO Rendezvous at /home/tibco/tibrv, you would add the following entry to server.xml file:

<library path="<Existing_Jar_Files>;/home/tibco/adapter/adejb/<

version_num>/lib/EjbSupport.jar;/home/tibco/adapter/adejb/<vers

ion_num>/lib/GlBeansSupport.jar;/home/tibco/adapter/adejb/<vers

ion_num>/lib/AeConnector.jar;/home/tibco/tra/<version_num>/lib/

TIBCOrt.jar;/home/tibco/tra/<version_num>/lib/TIBCOjms.jar; /ho

me/tibco/tra/5.3/lib/TIBCOtsm.jar; /home/tibco/tra/<version_num

>/lib/TIBCOxml.jar;/home/tibco/tra/5.3/lib/TIBCrypt.jar;/home/t

ibco/tpcl/5.3/lib/xmlParserAPIs.jar;/home/tibco/tpcl/<version_n

um>/lib/xercesImpl.jar;/home/tibco/tibrv/lib/tibrvj.jar;"/>

If the library element does not exist, create it.





1. Add the following code to the oc4j-connectors.xml file in the <ORACLE9IAS-ROOT>/j2ee/home/config/ directory.


------------------------------------------------------------------<?xml version="1.0" standalone='yes'?><!DOCTYPE oc4j-connectors PUBLIC "-//Oracle//DTD Connectors configuration//EN" "http://xmlns.oracle.com/ias/dtds/oc4j-connectors.dtd"><oc4j-connectors>


</oc4j-connectors>------------------------------------------------------------------

2. In the <ORACLE9IAS-ROOT>/j2ee/home/config/server.xml file, make sure that the connector-directory attribute is specified in the <application-server> element as connector-directory="../connectors"

3. In the <ORACLE9IAS-ROOT>/j2ee/home/config/application.xml file, make sure the <connector path> element is defined under the <orion-application> element as follows:


4. Create a directory called standalone in the <ORACLE9IAS-ROOT>/j2ee/home/connectors directory.

5. Copy the Resource adapter (RAR) file (AeConnector.rar) from <ADEJB_HOME>/lib to the <ORACLE9IAS-ROOT>/j2ee/home/connectors/standalone directory.

6. Go to the <ORACLE9IAS-ROOT>/opmn/bin directory and run opmnctl startall to start the application server. OC4J will automatically unpack





AeConnector.rar in the <ORACLE9IAS-ROOT>/j2ee/home/connectors/standalone/AeConnector/directory.



Preparing the Oracle 10g Application Server | 157

Preparing the Oracle 10g Application Server

To install and set up the supported container for this application server, follow the procedure outlined in http://otn.oracle.com/tech/java/oc4j/htdocs/oc4j-install-note.html (for J2EE 1.3 Developer Preview). You can download the Oracle9iAS Containers with J2EE 1.3 Developer Preview from http://otn.oracle.com/tech/java/oc4j/htdocs/utilsoft.html.

Preparation on Microsoft Windows PlatformsOracle J2EE containers have a predefined configuration stored in the server-side configuration file application.xml. If you want to make a Java library available to the application server, the library reference must be added in the application.xml file. This file is located in the <ORACLE10gAS-ROOT>\j2ee\home\config directory.

Preparing the application server on Microsoft Windows platforms involves the following tasks:




To prepare the connector:








Oracle J2EE containers have a predefined configuration stored in the server-side configuration file — application.xml. If you want to make a Java library available to the application server, the library reference must be added in the application.xml file. This file is located in the <ORACLE10gAS-ROOT>\j2ee\home\config directory.



For example, if you have installed the adapter at D:\tibco\adapter\adejb\<version_num>; the TRA at D:\tibco\tra\5.3; TPCL at D:\tibco\tpcl\5.3; and TIBCO Rendezvous at D:\tibco\tibrv, you would add the following entry to application.xml file:<library path="<Existing_Jar_Files>;D:\Tibco\adapter\adejb\<version_num>\lib\EjbSupport.jar;D:\Tibco\adapter\adejb\<version_num>\lib\GlBeansSupport.jarD:\Tibco\adapter\adejb\<version_num>\lib\AeConnector.jar;D:\Tibco\tra\5.3\lib\TIBCOrt.jar;D:\Tibco\tra\5.3\lib\TIBCOjms.jar; D:\Tibco\tra\5.3\lib\TIBCOtsm.jar; D:\Tibco\tra\5.3\lib\TIBCOxml.jar;D:\Tibco\tra\5.3\lib\TIBCrypt.jar;D:\Tibco\tpcl\5.3\lib\xmlParserAPIs.jar;D:\Tibco\tpcl\5.3\lib\xercesImpl.jar;D:\tibco\tibrv\lib\tibrvj.jar;"/>



1. Add the following code to the oc4j-connectors.xml file in the <ORACLE10gAS-ROOT>\j2ee\home\config\ directory.


------------------------------------------------------------------<?xml version="1.0" standalone='yes'?><!DOCTYPE oc4j-connectors PUBLIC "-//Oracle//DTD Connectors configuration//EN" "http://xmlns.oracle.com\ias\dtds\oc4j-connectors.dtd"><oc4j-connectors>


</oc4j-connectors>------------------------------------------------------------------

2. In the <ORACLE10gAS-ROOT>\j2ee\home\config\application.xml file, make sure that the connector-directory attribute is specified in the <application-server> element as connector-directory="../connectors"

3. In the <ORACLE10gAS-ROOT>\j2ee\home\config\application.xml file, make sure the <connector path> element is defined under the <orion-application> element as follows:






4. Create a directory called standalone in the <ORACLE10gAS-ROOT>\j2ee\home\connectors directory.

5. Copy the Resource adapter (RAR) file (AeConnector.rar) from <ADEJB_HOME>\lib to the <ORACLE10gAS-ROOT>\j2ee\home\connectors\standalone directory.

6. Go to the <ORACLE10gAS-ROOT>\j2ee\home directory and run java -jar oc4j.jar to start the application server. OC4J will automatically unpack AeConnector.rar in the <ORACLE10gAS-ROOT>\j2ee\home\connectors\standalone\AeConnector\ directory.

Preparation on UNIX PlatformsOracle J2EE containers have a predefined configuration stored in the server-side configuration file application.xml. If you want to make a Java library available to the application server, the library reference must be added in the application.xml file. This file is located in the <ORACLE10gAS-ROOT>\j2ee\home\config directory.

Preparing the application server on UNIX platforms involves the following tasks:








Before you start, do the following:








Oracle J2EE containers have a predefined configuration stored in the server-side configuration file — application.xml. If you want to make a Java library available to the application server, the library reference must be added in the application.xml file. This file is located in the <ORACLE10gAS-ROOT>/j2ee/home/config directory.

For example, if you have installed the adapter at /home/tibco/adapter/adejb/<version_num>; the TRA at /home/tibco/tra/<version_num>; TPCL at /home/tibco/tpcl/<version_num>; and TIBCO Rendezvous at /home/tibco/tibrv, you would add the following entry to application.xml file:

<library path="<Existing_Jar_Files>;/home/tibco/adapter/adejb/<

version_num>/lib/EjbSupport.jar;/home/tibco/adapter/adejb/<vers

ion_num>/lib/GlBeansSupport.jar;/home/tibco/adapter/adejb/<vers

ion_num>/lib/AeConnector.jar;/home/tibco/tra/5.3/lib/TIBCOrt.ja

r;/home/tibco/tra/5.3/lib/TIBCOjms.jar; /home/tibco/tra/5.3/lib

/TIBCOtsm.jar; /home/tibco/tra/5.3/lib/TIBCOxml.jar;/home/tibco

/tra/5.3/lib/TIBCrypt.jar;/home/tibco/tpcl/5.3/xmlParserAPIs.ja

r;/home/tibco/tpcl/5.3/xercesImpl.jar;/home/tibco/tibrv/lib/tib

rvj.jar;"/>

If the library element does not exist, create it.





1. Add the following code to the oc4j-connectors.xml file in the <ORACLE10gAS-ROOT>/j2ee/home/config/ directory.


------------------------------------------------------------------<?xml version="1.0" standalone='yes'?><!DOCTYPE oc4j-connectors PUBLIC "-//Oracle//DTD Connectors configuration//EN" "http://xmlns.oracle.com/ias/dtds/oc4j-connectors.dtd"><oc4j-connectors>


</oc4j-connectors>------------------------------------------------------------------

2. In the <ORACLE10gAS-ROOT>/j2ee/home/config/server.xml file, make sure that the connector-directory attribute is specified in the <application-server> element as connector-directory="../connectors"

3. In the <ORACLE10gAS-ROOT>/j2ee/home/config/application.xml file, make sure the <connector path> element is defined under the <orion-application> element as follows:


4. Create a directory called standalone in the <ORACLE10gAS-ROOT>/j2ee/home/connectors directory.

5. Copy the Resource adapter (RAR) file (AeConnector.rar) from <ADEJB_HOME>/lib to the <ORACLE10gAS-ROOT>/j2ee/home/connectors/standalone directory.

6. Go to the <ORACLE10gAS-ROOT>/j2ee/home directory and run java -jar oc4j.jar to start the application server. OC4J will automatically unpack





AeConnector.rar in the <ORACLE10gAS-ROOT>/j2ee/home/connectors/standalone/AeConnector/directory.



Preparing the JBoss 3.2.3 Application Server | 163

Preparing the JBoss 3.2.3 Application Server

You can prepare the application server for use on both Microsoft Windows and UNIX platforms.

Preparation on Microsoft Windows PlatformsPreparing the application server for use with the adapter involves the following tasks:






— JBOSS_HOME=<JBOSS installation directory>




— TIBCO_TPCL_HOME=<Third Part Core Libraries installation directory>


2. Add the following classpath to the run.bat file located in the <JBOSS_HOME>\bin directory:

set TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbAdapter.jar




set TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jar

set TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\server\default\lib\jboss-j2ee.jar

3. Add the following variable to the JBOSS classpath in the run.bat file in the <JBOSS_HOME>\bin directory:

set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%JAVAC_JAR%;%RUNJAR%;%TIBCLASSPATH%



1. If the JBoss server is not running, open a new command window and run the following command:<JBOSS_HOME>\bin\run.bat

2. Copy the <ADEJB_HOME>\lib\ AeConnector.rar to the <JBOSS_HOME>\server\default\deploy directory.

3. Restart the server after you have deployed the connector.

Preparation on UNIX PlatformsPreparing the application server for use with the adapter involves the following tasks:




• For the publication and request-response invocation services, add all the jar files present in the <TPCL_HOME>/lib/entrust directory to the JBoss classpath.


Preparing the JBoss 3.2.3 Application Server | 165









2. Add the following classpath to the run.sh file located in the <JBOSS_HOME>/bin directory:

export TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbAdapter.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jarexport TIBCLASSPATH=$TIBCLASSPATH:$JBOSS_HOME/server/default/lib/jboss-j2ee.jar

3. Add the following variable to the JBOSS classpath in the run.sh file in the <JBOSS_HOME>/bin directory:

export JBOSS_CLASSPATH=$JBOSS_CLASSPATH:$JAVAC_JAR:$RUNJAR:$TIBCLASSPATH

In the command window from which you are starting the application server, set TIBCO_RV_HOME/bin in the PATH environment variable.


• For the publication and request-response invocation services, add all the jar files present in the <TPCL_HOME>/lib/entrust directory to the JBoss classpath.





1. If the JBoss server is not running, open a new command window and run the following command:<JBOSS_HOME>/bin/run.sh

2. Copy the <ADEJB_HOME>/lib/AeConnector.rar to the <JBOSS_HOME>/server/default/deploy directory.



Preparing the JBoss Application Server 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4 Application Servers | 167

Preparing the JBoss Application Server 4.0.0, 4.0.1, 4.0.2, 4.0.3, and

4.0.4 Application Servers

You can prepare the application server for use on both Microsoft Windows and UNIX platforms. To deploy the connector to the JBoss application server, do one of the following:


— OR —


Manually Deploying the Connector on Microsoft Windows PlatformsPreparing the application server for use with the adapter involves the following tasks:












2. Add the following CLASSPATH to the run.bat file located in the <JBOSS_HOME>\bin directory:




set TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbAdapter.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\server\default\lib\jboss-j2ee.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\jmx-client.jar set TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\jboss-common-client.jar set TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\concurrent.jar set TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\log4j.jar set TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\lib\dom4j.jar set TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\lib\jboss-system.jar

3. Add the following variable to the JBoss CLASSPATH in the run.bat file in the <JBOSS_HOME>\bin directory:

set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%JAVAC_JAR%;%RUNJAR%;%TIBCLASSPATH%


To deploy the connector for the JBoss 4.0.0 application server:

1. Do the following:

a. Copy the AeConnector.rar from <ADEJB_HOME> to the temporary directory, for example d:\connector.

b. Open the command prompt and change to the directory d:\connector.

c. Run the command jar xvf AeConnector.rar. The directory will now have AeConnector-ds.xml, AeConnector.jar and META-INF\ra.xml files.

d. From the same command prompt, run the following command:jar cvf Aeconnector.rar META-INF Aeconnector.jar


For the publication and request-response invocation services, add all the jar files present in the <TPCL_HOME>/lib/entrust directory to the JBoss CLASSPATH.

The JBoss 4.0.0 application server expects to find the AeConnector-ds.xml file outside the rar file. The steps above repackage the AeConnector.rar file without the AeConnector-ds.xml file in it.



2. Copy AeConnector.rar and AeConnector-ds.xml from the temporary directory created above (d:\connector) to <JBOSS_HOME>\server\default\deploy directory


To deploy the connector for the JBoss 4.0.1, 4.0.2, 4.0.3, and 4.0.4 Application Servers:

1. If the JBoss server is not running, open a new command window and run the following command:<JBOSS_HOME>\bin\run.bat

2. Copy the <ADEJB_HOME>\lib\AeConnector.rar to the <JBOSS_HOME>\server\default\deploy directory.

Restart the server after you have deployed the connector.

Automatically Deploying the Connector on Microsoft Windows PlatformsPreparing the application server for use with the adapter involves the following task:

• Running ant target deploy.adapter.jboss40 from the ant script.

Running ant target deploy.adapter.jboss40 from the ant script

1. To deploy MDBs into the JBoss application server, open the MDB java file generated by EJB adapter and specify @jboss.resource-adapter tag at the beginning of the java file, so it points to the correct RAR file name.
















— application.xml.disp.name (Value of the tag display-name in the deploymentdescriptorapplication.xml of EAR file.)

— ejb.jar.file.name (Name of the EJB JAR file generated by ant script that contains the glue beans.)



— ear.file.name (Name of the EAR file generated by ant script that contains the resource adapter RAR file and glue beans jar.)


— tibco.connector.dir.loc (Directory where the application server-specific RAR file is located.)



3. Set the environment variable JBOSS_HOME to the JBoss installation root directory. For example, open a command prompt window and type the following to set the environment variable:

set JBOSS_HOME = C:\jboss-4.0.2


5. Make sure the JBoss application server to which you want to deploy the connector is running.

6. Run the ant target by typing the command ant deploy.adapter.jbss40 at the command prompt.

A message is displayed, indicating that the connector along with the glue beans are deployed successfully to the JBoss application server.

Manually Deploying the Connector on UNIX PlatformsPreparing the application server for use with the adapter involves the following tasks:





1. Set the following environment variables. The environment variable must point to the installation directory for the product:






2. Add the following classpath to the run.sh file located in the <JBOSS_HOME>/bin directory:

export TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jar



export TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbAdapter.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jarexport TIBCLASSPATH=$TIBCLASSPATH:$JBOSS_HOME/server/default/lib/jboss-j2ee.jarexport TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/jmx-client.jar export TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/jboss-common-client.jar export TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/concurrent.jar export TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/log4j.jar export TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/lib/dom4j.jar export TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/lib/jboss-system.jar

3. Add the following variable to the JBoss CLASSPATH in the run.sh file in the <JBOSS_HOME>/bin directory:

export JBOSS_CLASSPATH=$JBOSS_CLASSPATH:$JAVAC_JAR:$RUNJAR:$TIBCLASSPATH

4. In the command window from which you are starting the application server, update the LD_LIBRARY_PATH, SHLIB_PATH, or LIBPATH.

For HP-UX:SHLIB_PATH=$SHLIB_PATH:$TIBCO_TRA_HOME/lib

SHLIB_PATH=$SHLIB_PATH:$TIBCO_RV_HOME/lib

export SHLIB_PATH

For Solaris and Linux:LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TIBCO_TRA_HOME/lib


export LD_LIBRARY_PATH

For AIX:LIBPATH=$LIBPATH:$TIBCO_TRA_HOME/lib

LIBPATH=$LIBPATH:$TIBCO_RV_HOME/lib

export LIBPATH


To deploy the connector for the JBoss 4.0.0 application server:





1. Do the following:

a. Copy AeConnector.rar from <ADEJB_HOME> to the temporary directory, for example, /usr/temp/connector.

b. Change to the directory usr/temp/connector.

c. Run the command jar xvf AeConnector.rar. The directory will now have AeConnector-ds.xml, AeConnector.jar, and META-INF\ra.xml files.

d. Run the following command from the same console and directory:Jar cvf Aeconnector.rar META-INF Aeconnector.jar

2. Copy AeConnector.rar and AeConnector-ds.xml from the temporary directory (usr/temp/connector) to the <JBOSS_HOME>/server/default/deploy directory


To deploy the connector for JBoss 4.0.1, 4.0.2, 4.0.3, and 4.0.4 application servers:

1. If the JBoss server is not running, open a new command window and run the following command:<JBOSS_HOME>/bin/run.sh

2. Copy the <ADEJB_HOME>/lib/AeConnector.rar to the <JBOSS_HOME>/server/default/deploy directory.

Restart the server after you have deployed the connector.

Automatically Deploying the Connector on UNIX PlatformsPreparing the application server for use with the adapter involves the following task:

• Running ant target deploy.adapter.jboss40 from the ant script.

The JBoss 4.0.0 application server expects to find the AeConnector-ds.xml file outside the rar file. The steps above repackage the AeConnector.rar file without the AeConnector-ds.xml file in it.




Running ant target deploy.adapter.jboss40 from the ant script

1. To deploy MDBs into the JBoss application server, open the MDB java file generated by EJB adapter and specify @jboss.resource-adapter tag at the beginning of the java class file, so it points to the correct RAR file name.











— application.xml.disp.name (Value of the tag display-name in the deploymentdescriptorapplication.xml of EAR file.)

— ejb.jar.file.name (Name of the EJB JAR file generated by ant script that contains the glue beans.)







— ear.file.name (Name of the EAR file generated by ant script that contains the resource adapter RAR file and glue beans jar.)



3. Set the environment variable JBOSS_HOME to the JBoss installation root directory. For example, type the following at the command prompt:

export JBOSS_HOME=/usr/adiwan/jboss-4.0.2


5. Make sure the JBoss application server to which you want to deploy the connector is running.

6. Run the ant target by typing the command ant deploy.JBoss4.0 at the command prompt.

A message is displayed, indicating that the connector along with the glue beans are deployed successfully to the JBoss application server.




| 177

Chapter 5 Adapter Instance Options

This chapter explains how to create an adapter instance and assign it services by configuring standard settings. All configuration tasks are performed in TIBCO Designer and the information is stored in a project that is later used by the run-time adapter.

Topics


• Adapter Instance Fields, page 179

• Adapter Services, page 186

• Publication Service Fields, page 187

• Subscription Service Fields, page 194

• Request-Response Service Fields, page 201

• Request-Response Invocation Service Fields, page 208


178 | Chapter 5 Adapter Instance Options

Overview

You can configure adapter instances and add and configure adapter services using TIBCO Designer.

Configuration TasksUse the following sequence to create and configure an adapter service.

1. Start TIBCO Designer and open a multi-file project. See the TIBCO Designer User’s Guide for details.

2. Drag the EJB Adapter Configuration icon from the palettes panel to the design panel. This creates an adapter named, by default, EjbAdapterConfiguration.

3. Define the adapter instance by assigning a new name and optionally change logging options. See Logging Tab on page 183 for details.

4. Add a service to the adapter instance by dragging the service icon from the palettes panel and dropping it in the design panel.

5. Under the Configuration tab, set the combination of options required for your service.

6. Define run-time connection, general, startup, and monitoring options.

7. Save the project as a server repository project and exit TIBCO Designer.

After configuring the adapter, you must create the run-time adapter property file and add the project name and adapter instance name.


Adapter Instance Fields | 179

Adapter Instance Fields

The following tabs are used to define an adapter instance:

• Configuration Tab

• Run-time Connection Tab

• Adapter Services

• General Tab

• Logging Tab

• Startup Tab

• Monitoring Tab

Configuration Tab

Instance Name

Use the default name or replace it with a name of your choice.

• An instance name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.

• An instance name cannot use global variables.

• An instance name must be unique with respect to other adapter instances for the same adapter in the project. The same instance name can be used to name an adapter instance for a different adapter in the same project. For example, an R/3 adapter instance named TEST and a Siebel adapter instance named TEST can coexist in the same project.

• Each instance name must be unique per adapter within a project even if each instance is defined in a different folder. That is, configuring same-named adapter instances in different folders will not make their names unique.

When you create an adapter instance, the palette automatically creates several resources for it. The names of these resources derive from the name of the instance they belong to. Changing the adapter instance name results in an automatic regeneration of the resources names. If you manually modify any resource name, that particular name will not be automatically regenerated next time you rename the adapter instance.



Description

Provide information about the adapter instance that you want stored in the project. The field is optional.

Version

The version string indicates the ActiveEnterprise (AE) format in which the adapter instance is saved. An adapter instance can be saved in AE Version 4.1, AE Version 5.0, AE Version 5.1, or AE Version 5.2 format.

When a new adapter instance is created in TIBCO Designer 5.x, the version string is set to AE Version <version_num>. When a 4.x adapter instance is opened in Designer 5.x, the Version field is set to AE Version 4.1.

• If a 4.x adapter instance is to be run against a 4.x run-time adapter, the instance must be saved with the Version field set to AE Version 4.1.

If you are using TIBCO Designer 5.x to modify 4.x adapter instances, change only features supported by the 4.x. run-time adapter and use the validation utility to verify the instance before deploying the project. The validation utility scans the project and returns warnings if any 5.x features are defined for 4.x adapter instances. Invoke the utility from the Project>Validate Project for Deployment menu command in Designer.

• If a 4.x adapter instance is to be run against a 5.x run-time adapter, the Version field should be set to AE Version 5.0, AE Version 5.1, or AE Version 5.2.

To change versions, click the Change Version button.

Message Filter

Specify a message filter, if you have configured a message filter resource for use with the adapter. The filter allows you to manipulate incoming and outgoing data before sending it on the network or handing it to the target application. Filters can be written using the TIBCO Adapter SDK. See the TIBCO Adapter SDK Programmer’s Guide for information about writing a message filter.

Show All Tabs

Select this box to display additional tabs for configuring advanced options. When you select this option, the General tab is displayed.



Change Version

You can save the adapter instance in 4.x or 5.x format. If you save the adapter instance in the 4.x format, run the validation utility to make sure that 5.0 features have not been defined for the 4.x configuration.

Run-time Connection Tab

Maximum Number of Reconnect Attempts

Specify the total number of reconnection attempts to make before the run-time adapter or adapter service is stopped. A value of -1 means reconnection attempts will continue indefinitely.

Number of Reconnect Attempts Before Suspending Impacted Service(s)

Specify the number of reconnection attempts to make before suspending a run-time adapter or adapter service. The Adapter Termination Criteria field value determines whether the adapter or an adapter service is stopped.

Interval between Reconnect Attempts (milliseconds)

Specify the time interval in milliseconds to elapse between each reconnection attempt.

Adapter Termination Criteria (after max number of reconnect attempts)

If your adapter supports only a single connection to a vendor application or database, either choice results in the same behavior. The adapter stops if the service loses its connection. This field is only applicable for the inbound adapter process.

If your adapter supports multiple connections, select from the drop-down list:

• When Any Service is Suspended stops the adapter if any one service has been unable to re-establish connection after the specified number of reconnection attempts.

• When All Services Are Suspended stops the adapter only when all services have been suspended. That is, only the adapter service that cannot reconnect is stopped. Other adapter services that are connected continue to function normally.



Adapter Services

Number of threads per session

Specify the number of threads that must be started for the current session. This field is applicable only for the inbound adapter process.

General TabThis is an advanced configuration option.

Termination Subject or Topic

A message sent on the termination subject (if TIBCO Rendezvous is the transport) or topic (if JMS is the transport) stops the adapter. In most cases, you should use the default value. This field is only applicable for the inbound adapter process.

See TIBCO Rendezvous Concepts for information about specifying subject names. See the TIBCO Enterprise Message Service User’s Guide for information about publishing on a topic.

Enable Tracking

Select this check box to track trace message information. By default, this option is selected. For an adapter instance in the AE 5.0 format, this field is unavailable. However, for an adapter instance in the AE 4.1 format, this field is available and you can select or clear the check box.

Generate Verbose Log

Select this check box to specify that errors that occur are logged in the error log file. By default, this option is not selected.

Trace Messages in AE4 format

Select this check box to specify that errors are tracked using the old error messages. By default, this option is not selected and the adapter traces errors using the new error messages.

Enable Advisory Messages

Select this option to log advisory messages that are generated when the adapter is running. By default, this option is not selected.



Logging Tab

Use Advanced Logging

When Use Advanced Logging is not selected (the default), you can set two standard output destinations (sinks) for trace messages and set the tracing level for the roles selected.

When Use Advanced Logging is selected, you have complete control on selecting the destinations and associating desired roles with each of the destinations.

To create and configure the sinks, select the log sinks folder under the Advanced folder in the project panel.

To create sinks, drag and drop the Generic log sink icon from the palette panel into the design panel. From the configuration panel, select the sink type. The following are the sink types available:

— File

— Hawk

— Network

— STDIO

When File and STDIO sinks are created from the Generic log sink they offer further configuration options. For the File sink, the file limit, file count, and the option to append or overwrite can be specified. When created by default, this is set to 30000 bytes, 3 and append mode respectively. For the STDIO sink, the option to write to stdout or stderr can be selected. When created by default, stdout is selected.

The Hawk sink uses the hawk session, created and used by the adapter for monitoring purposes, to send tracing messages to the TIBCO Hawk monitor or Display. For details on Hawk sessions, see Using Global Variables on page 227. The configuration for the Hawk sink involves specifying the MicroAgent Name that must be specified in the configuration panel.

The Network sink is used to publish tracing message on TIBCO Rendezvous. The configuration for the network sink involves specifying the session, and the subject on which the trace messages needs to be published.

For all the sinks, optionally the name and description for the sinks can be provided.



Log to Standard I/O

(STDIO Sink) When selected, trace messages are displayed in the command prompt window where the adapter is started. When not selected, trace messages do not display in the window.

Log File

Specify the name of the log file (log sink) to which trace messages are written. Global variables can be used to specify the location of the log file. See Using Global Variables on page 227 for more information.

The roles available are Info, Debug, Warning, and Error messages. The trace message generated depends on the roles selected. Turning on the roles can affect the performance of the adapter. Therefore, it is recommended that you turn on the required roles only.

Log Info/Debug/Warning/Error Messages

Trace messages of the selected level(s) will be collected in the named log sink. You can configure what levels of trace messages you want logged, and where trace messages are sent. There are three types of logs (log sinks) that you can configure to hold trace messages, corresponding to three levels (roles) of trace messages, Information, Warning and Error. A fourth level of trace messages, Debug, is reserved and should not be enabled unless requested by the TIBCO Product Support Group. This option writes a lot of information to the log file and significantly reduces the speed of the adapter.

Startup Tab

Show Startup Banner

This field is predefined and cannot be changed. The startup banner displays the run-time adapter version, the infrastructure version on which the adapter is built, and copyright information in the console window when the adapter is started.

Metadata Search URL

This field is predefined and cannot be changed. The field specifies the location where the adapter searches for base schemas. The adapter searches for any schema that has been defined and saved at this location, and that should be loaded at startup.



Monitoring TabMany of the following fields make use of global variables. Click the Global Variables tab in the project panel to enter a value for a global variable.

Enable Standard Microagent

Allows you to turn on or off the standard TIBCO Hawk Microagent. The way to turn it on or off is also configurable. By clicking the globe icon, a standard check box or text value (true or false) can be used to turn the standard microagent on or off.

Standard Microagent Name

This is the name for the standard microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used. The InstanceId variable need not be set because it is automatically set at run time by the run-time adapter.

Enable Class Microagent

Allows you to turn on or off the instance or class specific standard TIBCO Hawk Microagent. The way to turn it on or off is also configurable. By clicking the globe icon, a standard check box or text value (true or false) can be used to turn the class microagent on or off.

Class Microagent Name

This is the name for the class microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used.

Default Microagent Session

Specify the name of the TIBCO Rendezvous session that will be used by the standard, class, and custom microagents.

The session name and the corresponding session is automatically generated by TIBCO Designer. Do not change the session name or the session. However, you can modify the session parameters if required. Navigate to the Sessions folder under the Advanced folder to modify the session parameters.

Make sure you have set the correct parameter value for the global variables that correspond to the TIBCO Hawk configuration. If the session parameters are not set properly, the microagents will not display in the TIBCO Hawk Display.



Adapter Services

After configuring an adapter instance, select one or multiple adapter services for the instance. The following sections describe the services and fields that are available to the adapter:

• Publication Service Fields on page 187

• Subscription Service Fields on page 194

• Request-Response Service Fields on page 201

• Request-Response Invocation Service Fields on page 208


Publication Service Fields | 187

Publication Service Fields

The following tabs are available:• Configuration Tab on page 187

• Transport Tab on page 188

• Schema Tab on page 191

• Code Generator Tab on page 191

Configuration Tab

Name

You can use the default name or replace it with a name of your choice.

• A service name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.

• A service name cannot use global variables.

Description


Transport Type

Select the transport to be used by the run-time adapter, JMS or TIBCO Rendezvous. After selecting the transport, the transport-specific configuration fields display.

The transport can be configured to use a trusted store and identity resource for use in SSL (Secure Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration.

To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.



Transport Tab

Message Subject

This field displays only if TIBCO Rendezvous is selected in the Transport Type field (under the Configuration tab).

By default a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field. See TIBCO Rendezvous Concepts for information about specifying subject names.

Destination

This field displays only if JMS is selected in the Transport Type field (under the Configuration tab).

By default a service uses a dynamic destination that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default dynamic destination, make sure the values for Domain and Deployment are not empty. You can override the default dynamic destination by specifying the static destination in this field. The static destination must be defined on the JMS server before it can be used by the run-time adapter. See the TIBCO Enterprise Message Service User’s Guide for information about destinations.

Reply Message Subject

The TIBCO Rendezvous subject that the source application is expected to send the message on. This option will be available only for the Publication Service. When the publisher has the reply subject then the publisher waits for the reply after publishing the request.

Reply Destination

The destination that the source application is expected to send the message on. This option will be available only for the Publication Service. When the publisher has the reply subject then the publisher waits for the reply after publishing the request.

Quality of Service

If TIBCO Rendezvous is selected as the transport type, select:



• Reliable

Ensures that each multicast or broadcast message is received as long as the physical network and packet recipients are working, and that the loss of a message is detected. This choice can compensate for brief network failures because it can retransmit a message on request if the first attempt failed. This choice is appropriate when message delivery is expected but some loss can be tolerated.

• Certified

Guarantees that every certified message reaches its intended recipient in the order sent. The message can be sent across network boundaries, and if a network fails, delivery attempts continue until delivery succeeds or until the message's time limit expires. This is often called certified message delivery.

If certified message delivery is used, data is stored in a ledger file. The size of the ledger depends on several factors, the most important of which is the retention rate of stored data. That is, the ledger grows fastest in response to the cumulative length of undeliverable messages. You must ensure that sufficient disk space is available for the expected size of the ledger.

Wire Format

Services must use the same wire format to exchange data.

• ActiveEnterprise Message (TIBCO Rendezvous only)

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 the TIBCO Adapter SDK Programmer’s Guide for details about the control information generated and sent with ActiveEnterprise messages.

• XML Message (TIBCO Rendezvous or JMS)

The XML Message wire format conforms to specifically constructed and fully compliant XML Schema (XSD) based on the existing definition of the ActiveEnterprise schema.

Connection Factory Type

• Queue (JMS only)

A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the



queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.

• Topic (JMS only)

A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe.

Delivery Mode

• Non Persistent (JMS only)

A message marked non persistent will not be available to a JMS client if the JMS server goes down.

• Persistent (JMS only)

In general, a message marked persistent will be available to a JMS client even if the JMS server goes down.

Messages sent with the persistent delivery mode are always written to persistent storage, except when they are published to a topic that has no durable subscribers. When a topic has no durable subscribers, there are no subscribers that need messages resent in the event of a server failure. Therefore, messages do not need to be saved, and performance is improved because disk I/O is not required.

The semantics for these fields are somewhat more complex than the explanation given here. See the TIBCO Enterprise Message Service User’s Guide for more information.

Session Reference

Every adapter instance can have one or more sessions configured for it. Sessions encapsulate stateful connections to the TIBCO-enabled application and other messaging sources. The session object shown in this field is initially supplied by the adapter, depending on the Quality of Service selected. You can change the session by browsing for it in the project panel.

• DefaultRVSession Reliable Message Delivery.

• DefaultRVCMSession Certified Message Delivery.

• DefaultQueueJMSSession (available if you select JMS in the Transport Type field under the Configuration tab).

Changing the Quality of Service, changes the session reference to an appropriate default session.



The Go To button takes you to the session.

Endpoint Reference

Specifies the location in the repository server where the endpoint information will be stored. Endpoints store information such as a TIBCO Rendezvous message subject, endpoint type (such as RV Publisher, RVCM Publisher), and startup state (for example active, inactive).• Browse lets you locate another endpoint to associate this Publication Service

with.

• Go To lets you change the parameters associated with this endpoint. You can also find the session associated with this endpoint by clicking the Go To button and clicking on the parent node of the highlighted tree item.

Schema Tab

Class Reference

Select a class from the Schema lists available for the ActiveEnterprise wire format. Available for ActiveEnterprise and XML formats.

When ActiveEnterprise Message (specified by the Wire Format option) is selected, the schema classes for data mapping must be specified.

Once the schema has been specified for an operation, you can view its attributes by selecting the Schema folder. On the Schema folder, you can expand the field names to view the data types and field attributes. For more information about schema, see the TIBCO Designer User’s Guide.

Code Generator Tab

EJB Spec Version

Select the EJB Specification version from the drop-down list.

Bean

Specify the location to which the code generator must write the generated code. All generated classes will have the package prefix specified in the Package Root field. The remainder of the class name will come from the URL path of the endpoint from which the class is generated.



Deployment Descriptor

Specify the location for the deployment descriptor. The EJB code generator produces a standard EJB 1.1, 2.0, or 2.1 deployment descriptor file, which needs to be placed in the META-INF directory of the bean archive. This file contains the minimal deployment information required for the bean(s) that have been generated. In addition, when generating code for a bean that is a request-response invocation service or publication service, the code generator will add to each bean's session tag either a resource-ref element or a set of env-entry elements, that contain information needed to establish a connection to the J2EE Connector library.

Package Root

This field specifies a package root value for the generated code. For example, if you want your code to be generated under e:\GeneratedCode\com\tibco\test\…, make sure your output directory is set to e:\GeneratedCode and the package root value is com.tibco.test.

Use Resource Reference

If you select Use Resource Reference, then the generated deployment descriptor file will include a resource-ref section for each bean. resource-ref is used to specify information about a deployed resource archive and its associated ConnectionFactory class. If your J2EE server supports J2EE Connectors, then you can select Use Resource Reference. If your server does not have this support, you must clear this box.

Resource Reference

The Resource Reference field is displayed if you select the Use Resource Reference check box. The information from this field will be used in the res-ref-name field of the resource-ref section in the deployment descriptor. This is the name that the bean code will use to locate the TIBCO J2EE Connector's ConnectionFactory. This name will be mapped to a JNDI location when the Connector is deployed and registered into the application server environment.

Repository URL

If the Use Resource Reference check box is not selected, then the code generator will show the Repository URL field. The Repository URL is a string that identifies the name and, if necessary, connection parameters for the repository server instance containing the Connector configuration. For example: tibcr://ejb_sample:userName=adejb:password=adejb.



Configuration URL

This is a string that identifies the location of the adapter instance information in the repository. For example,

/tibco/private/adapter/Connector/RPC/EJBAdapter

You must enter the location of the adapter instance in the configURL text box and click the Set button. The code generator will display the endpoints attached to the specified adapter instance on the Endpoint Chooser window.

EJB Name Prefix

The value in this field will be prepended to the ejb-name value generated in the beans' deployment descriptor.

Indent Level

Specify the code indent level. This field adjusts the indent level during code generation. The default is four space characters.

Generate Code

Click this button to generate the bean information.

For details on the code generator output, see Code Generator on page 289.



Subscription Service Fields




• Connection Info Tab on page 198


Configuration Tab

Name




Description


Transport Type





Subscription Service Fields | 195

Transport Tab

Message Subject



Destination



Quality of Service


• Reliable


• Certified





• Distributed Queue

This is a group of cooperating transport objects that are used for one-of-many certified delivery to a group of worker processes. When this quality of service is chosen, an RVCMQ session will be used.

Wire Format





• XML Message (TIBCO Rendezvous or JMS)




A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.





Delivery Mode

For a subscription service, a message is marked as durable or non durable.

• Non Durable — Messages sent to a non durable service are not held by the JMS server. If the subscription service is down, it will not receive the messages that arrived at the JMS server while the service was down.

• Durable — A durable service is registered with the JMS server. Messages sent to a durable service are held by the JMS server until they are consumed by the service. The service can be down and expect to receive its messages when it comes back up.


Session Reference






Endpoint Reference

Specifies the location in repository server where the endpoint information will be stored. Endpoints store information such as a TIBCO Rendezvous message subject, endpoint type (such as RV Publisher, RVCM Publisher), and startup state (for example active, inactive).• Browse lets you locate another endpoint to associate this Publication Service

with.




• Go To… lets you change the parameters associated with this endpoint. You can also find the session associated with this endpoint by clicking the Go To… button and clicking on the parent node of the highlighted tree item.

Schema Tab

Class Reference

Select a class from the Schema lists available for the ActiveEnterprise wire format. Available for ActiveEnterprise and XML formats.

When ActiveEnterprise Message (specified by the Wire Format option) is selected, the schema classes for data mapping must be specified.

Once the schema has been specified for an operation, you can view its attributes by selecting the Schema folder. On the Schema folder, you can expand the field names to view the data types and field attributes. For more information about schema, see the TIBCO Designer User’s Guide.

Connection Info Tab

Deployment Option

To deploy the adapter, use Inbound Connector or the standalone adapter

Inbound Connector—If you select this option, use the adapter subscription service to perform inbound processing.

Standalone Adapter—.If you select this option, use TIBCO Administrator to deploy the adapter. The adapter subscription service runs inside the standalone adapter process.

JNDI Provider Url

The JNDI location of the bean home.

If the application server is JCA 1.5 compliant, only then you can use Inbound Connector to deploy the adapter.



EJB Home Interface

The Java class for the bean home.

Application Server Connection

The reference to the application server resource.

Code Generator Tab

EJB Spec Version


Bean

Specify the location to which the code generator must write the generated code. All generated classes will have the package prefix specified in the Package Root field. The remainder of the class name will come from the URL path of the endpoint from which the class is generated.


Specify the location for the deployment descriptor. The EJB code generator produces a standard EJB 1.1, 2.0, or 2.1 deployment descriptor file, which needs to be placed in the META-INF directory of the bean archive. This file contains the minimal deployment information required for the bean(s) that have been generated. Additionally, when generating code for a bean that is a request-response invocation service or publication service, the code generator will add to each bean's session tag either a resource-ref element or a set of env-entry elements, that contain information needed to establish a connection to the J2EE Connector library.

If your schema class contains any of the special characters or words listed in Table 18, TIBCO ActiveEnterprise to J2EE Connector Name Mapping, on page 418, the class name of the generated class is mangled as these characters cannot be present in the class name. Therefore, it is advisable to generate the code for the glue beans first and the value of EJB Home Interface should be based on the name of the home class that is generated.

This field is available only if the adapter is installed for multiple application server support.



Package Root


EJB Name Prefix


Indent Level


Generate Code




Request-Response Service Fields | 201

Request-Response Service Fields




• Connection Info Tab on page 205


Configuration Tab

Name




Description


Transport Type






Transport Tab

Message Subject



Destination



Quality of Service


• Reliable


• Certified






This is a group of cooperating transport objects that are used for one-of-many certified delivery to a group of worker processes. When this quality of service is chosen, an RVCMQ session will be used.

Wire Format





• XML Message (JMS only)









Delivery Mode

For a subscription service, a message is marked as durable or non durable.

• Non Durable — Messages sent to a non durable service are not held by the JMS server. If the subscription service is down, it will not receive the messages that arrived at the JMS server while the service was down.

• Durable — A durable service is registered with the JMS server. Messages sent to a durable service are held by the JMS server until they are consumed by the service. The service can be down and expect to receive its messages when it comes back up.


Session Reference






Endpoint Reference


with.





Schema Tab

Class Reference

Select a class from the Schema lists available for the ActiveEnterprise wire format. This field is available only for ActiveEnterprise and XML formats.

When ActiveEnterprise Message is selected as the Wire Format option, the schema classes for data mapping must be specified.

Once the schema has been specified for an operation, you can view its attributes by selecting the Schema folder. On the Schema folder, you can expand the field names to view the data types and field attributes. For more information on schema, see the TIBCO Designer User’s Guide.

Connection Info Tab

Deployment Option

To deploy the adapter, use Inbound Connector or the standalone adapter.

Inbound Connector—If you select this option, use the adapter RPCServer to perform inbound processing.

Standalone Adapter—.If you select this option, use TIBCO Administrator to deploy the adapter. The adapter RPCServer runs inside the standalone adapter process.

JNDI Provider Url

The JNDI location of the bean home.

If the application server is JCA 1.5 compliant, only then you can use Inbound Connector to deploy the adapter.



EJB Home Interface

The Java class for the bean home.

Application Server Connection

The reference to the application server resource.

Code Generator Tab

EJB Spec Version


Bean

Specify the location to which the code generator must write the generated code. All generated classes will have the package prefix specified in the Package Root field. The remainder of the class name is derived from the URL path of the endpoint from which the class is generated.



If your schema class contains any of the special characters or words listed in Table 18, TIBCO ActiveEnterprise to J2EE Connector Name Mapping, on page 418, the class name of the generated class is mangled as these characters cannot be present in the class name. Therefore, it is advisable to generate the code for the glue beans first and the value of EJB Home Interface should be based on the name of the home class that is generated.

This field is available only if the adapter is installed for multiple application server support.



Package Root


EJB Name Prefix


Indent Level

This field adjusts the indent level during code generation. The default is four space characters.

Generate Code





Request-Response Invocation Service Fields





Configuration Tab

Name




Description


Transport Type





Request-Response Invocation Service Fields | 209

Transport Tab

Message Subject



Destination



Quality of Service


• Reliable


• Certified





Wire Format





• XML Message (JMS only)







Delivery Mode

• Non Persistent (JMS only)

A message marked non persistent will not be available to a JMS client if the JMS server goes down.



Messages sent with the persistent delivery mode are always written to persistent storage, except when they are published to a topic that has no durable subscribers. When a topic has no durable subscribers, there are no subscribers that need messages resent in the event of a server failure. Therefore, messages do not need to be saved, and performance is improved because disk I/O is not required.

• Persistent (JMS only)

In general, a message marked persistent will be available to a JMS client even if the JMS server goes down.


Session Reference






Endpoint Reference


with.





Schema Tab

Class Reference

Select a class from the Schema lists available for the ActiveEnterprise wire format. This field is available only for ActiveEnterprise and XML formats.

When ActiveEnterprise Message is selected as the Wire Format option, the schema classes for data mapping must be specified.

Once the schema has been specified for an operation, you can view its attributes by selecting the Schema folder. On the Schema folder, you can expand the field names to view the data types and field attributes. For more information on schema, see the TIBCO Designer User’s Guide.

Code Generator Tab

EJB Spec Version


Bean

Specify the location to which the code generator must write the generated code. All generated classes will have the package prefix specified in the Package Root field. The remainder of the class name is derived from the URL path of the endpoint from which the class is generated.





Package Root



If you select Use Resource Reference, then the generated deployment descriptor file will include a resource-ref section for each bean. resource-ref is used to specify information about a deployed resource archive and its associated ConnectionFactory class. If your J2EE server supports J2EE Connectors, then you can select Use Resource Reference. If your server does not have this support, you must clear this box.

Resource Reference

The Resource Reference field is displayed if you select the Use Resource Reference check box. The information from this field will be used in the res-ref-name field of the resource-ref section in the deployment descriptor. This is the name that the bean code will use to locate the TIBCO J2EE Connector's ConnectionFactory. This name will be mapped to a JNDI location when the Connector is deployed and registered into the application server environment.

Repository URL

If the Use Resource Reference check box is not selected, then the code generator will show the Repository URL field. The Repository URL is a string that identifies the name and, if necessary, connection parameters for the repository instance containing the Connector configuration. For example: tibcr://ejb_sample:userName=adejb:password=adejb.

Configuration URL

This is a string that identifies the location of the adapter instance information in the repository. For example, /tibco/private/adapter/Connector/RPC/EJBAdapter

You must enter the location of the adapter instance in the configURL text box and click the Set button. The code generator will display the endpoints attached to the specified adapter instance on the Endpoint Chooser window.



EJB Name Prefix


Indent Level


Generate Code




| 215

Chapter 6 Deploying and Starting an Adapter Using TIBCO Administrator

This chapter provides an overview about deploying, starting, stopping, and monitoring adapter services using the TIBCO Administrator web interface.

Topics

• Create an EAR File in TIBCO Designer, page 216

• Deploy the Project, page 217

• Start or Stop the Adapter, page 220

• Monitor the Adapter, page 221

To process inbound messages, deploy the adapter in one of the following ways:

• On the application server as JCA 1.5 compliant adapter.

• As a standalone adapter using TIBCO Administrator.

However do NOT deploy the same instance of the adapter subscription service or the RPC server as JCA 1.5 compliant adapter on the application server and as a standalone adapter at the same time.


216 | Chapter 6 Deploying and Starting an Adapter Using TIBCO Administrator

Create an EAR File in TIBCO Designer

Generate an Enterprise Archive file (EAR) that contains information about the adapter services to deploy.

The EAR file contains information on what you wish to deploy. This could be one or more adapter services, one or more TIBCO BusinessWorks process engines, or both.

In TIBCO Designer, follow these steps to create an EAR:

1. Configure the adapter services.

2. Drag and drop the Enterprise Archive resource from the palette panel to the design panel. If there are any configured adapter services in your project, an Adapter Archive resource becomes available in the palette panel.

3. Drag the Adapter Archive into the design panel and specify information in the Configuration tab, then click Apply.

4. Go to the Enterprise Archive and click Build Archive to create the archive file.

See Also

See the TIBCO Designer User’s Guide for more information about this procedure. The guide is available from the Designer Help menu.

Building an archive creates the EAR file, which you can then deploy from TIBCO Administrator. If you make changes to the business processes or adapter services included in the archive, you need to rebuild the archive. Saving the project does not affect the archive.


Deploy the Project | 217

Deploy the Project

Before deploying a project, the machine on which the adapter is installed must be part of a TIBCO administration domain. After you have installed the TIBCO Administration Server, any machine on which you install TIBCO Runtime Agent (required by an adapter) can be added to the administration domain. The TIBCO software installed on the machine is then visible and accessible via the TIBCO Administrator GUI.

When you deploy a project, startup scripts and other information about the different components are sent to the machines to which the components were assigned. The project data store and TIBCO Administration Server are updated with the deployed components.

In TIBCO Adapter for EJB, only the Inbound scenarios, that is the subscription and request-response server services, can be executed in the TIBCO Administration Server. The Outbound services, namely the publication and request-response invocation services are hosted in the application server and cannot be run from the TIBCO Administration Server.

When you are running the adapter services from the TIBCO Administration server, you must include the following jar files in the classpath of the generated deployment:

• Glue Beans generated for the service

• Security related jar files

You can add these files to the classpath of the adapter application to be deployed. For details on adding classpath entries to the application being deployed, see the TIBCO Administrator User’s Guide.

To the server classpath, you must do the following:

• Prepend the security related jar files

• Append the glue beans related jars

For typical locations of glue bean stubs jars, see the tra files used for executing the subscription or request-response server services.



The following table lists the jar files that you need to include depending on the application server you are using:

Table 8 The jar files required to run the adapter with TIBCO Administrator Enterprise Edition

Application Server Security-related jar Files Glue Beans

BEA WebLogic 7.0 and BEA WebLogic Application Server 7.0 with SP2, SP4, SP5, and SP6

<TPCL_HOME>/lib/entrust/unsig

ned/enttoolkit.jar

Location of glue beans jar.

BEA WebLogic 8.1 Location of glue beans jar.

BEA WebLogic 8.1 with SP1, SP2, SP3, SP4, SP5, and SP6


BEA WebLogic 9.0, 9.1, and 9.2


IBM WebSphere 5.1 Location of glue beans stubs jar.


IBM WebSphere 6.0.2 Location of glue beans stubs jar.


JBoss 3.2.3 Location of glue beans jar.

JBoss 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4


Oracle 9i 9.0.3 <TPCL_HOME>/lib/entrust/unsig

ned/enttoolkit.jar

Location of glue beans stubs.

Oracle 10g 9.0.4, 10.1.2, and 10.1.3

<TPCL_HOME>/lib/entrust/unsig

ned/enttoolkit.jar

Location of glue beans stubs.




Deploy the Project | 219

To deploy a project:

1. Import the EAR file into TIBCO Administrator Enterprise Edition.

2. Assign adapter archives in the EAR file to adapters installed in the administration domain and likewise assign process archives to process engines.

3. Specify startup options for each adapter service.

See Also

See the TIBCO Administrator User’s Guide for an introduction to the TIBCO administration domain and detailed information about the above steps.



Table 8 The jar files required to run the adapter with TIBCO Administrator Enterprise Edition

Application Server Security-related jar Files Glue Beans



Start or Stop the Adapter

The TIBCO Administrator Application Management module allows you to start, and stop deployed applications.

To start an adapter service from the module:

1. In the Administrator GUI left pane, expand Application Management > Application-Name > Service Instances.

2. In the Service Instance panel, select the check box next to the adapter service.

3. Click the Start Selected button.

The status changes from Stopped to Starting up to Started.

4. To stop the adapter service, click the Stop Selected button.

See Also

See the TIBCO Administrator User’s Guide for more information.


Monitor the Adapter | 221

Monitor the Adapter

TIBCO Administrator offers a number of monitoring options. • Specify alerts and TIBCO Hawk rulebases for each machine in the domain.

• Specify alerts and Hawk rulebases for each adapter service.

• View the log for each adapter service.

See Also

See the TIBCO Administrator User’s Guide for information about configuring the above monitoring options.




| 223

Chapter 7 Advanced Topics

This chapter describes advanced topics such as defining a TIBCO Hawk session to monitor the adapter, using global variables, and setting encoding options.

Topics


• Defining a TIBCO Hawk Session, page 225

• Using Global Variables, page 227

• Setting Encoding Options, page 232

• Running the Adapter and Application Server on Different Machines, page 234

• Returning System Exceptions, page 239

• Configuring the Connector Using the Properties File, page 240

• Deploying Connectors in a Clustered Environment, page 241

• Converting the Sequence Field, page 251


224 | Chapter 7 Advanced Topics

Overview

The advanced features help you to define a TIBCO Hawk session to monitor the adapter, use variable substitution to override global variables that are predefined in the project in a restricted manner, and set encoding options before running the adapter so that it handles files in different encoding.


Defining a TIBCO Hawk Session | 225

Defining a TIBCO Hawk Session

To use TIBCO Hawk to monitor the adapter you must first define a TIBCO Rendezvous session. Use the following steps to create the session.

1. In the project tree panel, click the EjbAdapterConfiguration icon defined for your adapter instance.

2. Select the Show All Tabs check box, then click the Monitoring tab.

3. The Default MicroAgent Session contains the name of the Hawk session:DefaultHawkSession. Use default setting for the other fields.

The next diagram shows the definition for a Monitoring tab.

4. Open the Advanced folder for the adapter instance. Double-click the Sessions folder.



5. Double-click the DefaultHawkSession icon.

You can now configure the session, as below.

If you choose to change the defaults, Click Apply and save the project.


Using Global Variables | 227

Using Global Variables

The variable substitution mechanism can override global variables predefined in the project in a restricted manner. Predefined variables can be viewed and set in TIBCO Designer. Variables are specified as %%VARNAME%% and cannot contain any white space.

Variable substitution allows you to accomplish the following.

• Substitute string variables specified in the project at startup time.

• Locally define the value for a variable for a specific project. The local value takes precedence over any global value.

• Specify the value for a variable in a properties file. This overrides the project repository and values set in code, but not variables set on the command line.

• Enforce the pre-defined variables listed in Predefined Global Variables on page 229.

Variables can be used anywhere in the configuration and will be replaced by the locally-defined adapter instance.

Specifying Variables Using TIBCO Designer

Global variables provide an easy way to set defaults for use throughout your project. There are several ways in which they can be used:

• Define a variable using TIBCO Designer, then override the value for individual applications at deployment time using TIBCO Administrator. You can also override values for predefined variables, unless the GUI does not allow you to make them settable later.

• Predefine a variable using TIBCO Designer, then override the value for individual services (for example, publication service or TIBCO BusinessWorks process) at deployment time using TIBCO Administrator. The values you specify are then used at runtime. You can also override values for predefined variables, unless the GUI does not allow you to make them settable later.

For example, you could assign the value 7474 to the predefined global variable RvDaemon. You can then use the variable in different sessions in your adapter. If you wish to change the TIBCO Rendezvous daemon for your adapter, you can globally set it to a different value or override it from the command line.

To use global variables in your project, follow these steps:

1. In the project panel, select the Global Variables tab.



The project panel is updated to display all currently defined global variables. Click Open Advanced Editor (pencil icon at the top left corner). You now have these choices:

— To assign or change a variable value, select that region and triple-click the variable. The variable expands so you can change either the variable name or the variable value. Press Enter when you’re done.

— To add a new global variable group, click the leftmost icon at the bottom of the dialog box. Specify the name of the group, then press Enter. With the group icon selected, you can click the abc icon to add variables to the group.

— To add a global variable, click the abc icon. A new global variable item is added to the bottom of the list. Supply the variable name and, optionally, the value. Press Enter when you’re done.

The global variable is now displayed in the global variables list.

5. When you want to use the global variable in the fields of a resource, enter the variable name surrounded by %% on both sides.

When the project is deployed and the configured components are run, all occurrences of the global variable name are replaced with the global variable value (unless it was overridden in a way that had higher precedence).

A number of global variables are predefined. See Predefined Global Variables on page 229 for information. You may add definitions of any variables you need to the predefined variables.

Changing Global Variable Values at RuntimeYou can change the value of a global variable when you deploy your project in TIBCO Administrator. See the section on modifying runtime variables in the TIBCO Administrator User’s Guide for more information on using TIBCO Administrator.

If you are using TIBCO Designer 5.3, do the following to edit the global variables:

1. Click the Open Advanced Editor icon. This opens the window with a list of global variables.

2. Click the variable whose value you want to change.

3. Click the Value box, and enter the value.

4. Click OK to save the changes.



You can also specify values for global variables when starting a process engine on the command line. To do this, specify the following as a command line argument when starting the process engine:

-tibco.clientVar.<variablePathAndName> <value>

where variablePathAndName is the name of the variable you wish to set, including the path to the variable if it is contained in a folder. value is the value you wish to set the variable to. For example, if you have a global variable named item1 contained in a folder named myGroup and you wish to set its value to 500, add the following argument to the command line when starting the process engine:

-tibco.clientVar.myGroup/item1 500

Predefined Global VariablesThe next table lists and explains the predefined global variables. Some global variables are automatically used within the system when an adapter instance is configured.

Table 9 Predefined Global Variables

Variable Description

Deployment Defaults to the TIBCO Designer project name. This global variable is used by the system to partially define the subject name defined for a service.

DirLedger Specifies the path name of the TIBCO Rendezvous certified messaging ledger file. The default is the root installation directory.

DirTrace Specifies the path name for log file used by the adapter. The default is the root installation directory.

Domain The default value for file-based local projects is MyDomain. The value for server-based projects is the domain to which the project was saved.

HawkEnabled Indicates whether TIBCO Hawk is used to monitor the adapter. True indicates that a TIBCO Hawk microagent is defined for the adapter. False indicates the microagent is not to be used.

JmsProviderUrl Tells applications where the JMS daemon is located. Setting this value mostly makes sense in early stages of a project, when only one JMS daemon is used.



JmsSslProviderUrl

Specifies where the JMS SSL daemon is located.

RemoteRvDaemon TIBCO Rendezvous routing daemon (rvrd) to be used. See TIBCO Administrator Server Configuration Guide for details about setting up a domain using rvrd.

RvDaemon TIBCO Rendezvous daemon. Sessions use this daemon to establish communication. The default value is 7500.

RvNetwork TIBCO Rendezvous network. This variable need only be set on computers with more than one network interface. If specified, the TIBCO Rendezvous daemon uses that network for all outbound messages.

In most cases, you can leave the default.

RvService TIBCO Rendezvous service. The TIBCO Rendezvous daemon divides the network into logical partitions. Each transport communicates on a single service. A transport can communicate only on the same service with other transports.

Unless you are using a non-default TIBCO Rendezvous configuration, you should leave the default (7500).

RvaHost Computer on which the TIBCO Rendezvous agent runs. This variable is only relevant if you are using the TIBCO Rendezvous Agent (rva) instead of the TIBCO Rendezvous daemon, and if you have configured a non-default setup. See TIBCO Rendezvous Administration for details about specifying the rva parameters.

RvaPort TCP port where the TIBCO Rendezvous agent (rva) listens for client connection requests. See TIBCO Rendezvous Administration for details about specifying the rva parameters. Defaults to 7501.

TIBHawkDaemon TIBCO Rendezvous daemon used in the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.





TIBHawkNetwork TIBCO Rendezvous network used by the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBHawkService TIBCO Rendezvous service used by the TIBCO Hawk session. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.





Setting Encoding Options

See the TIBCO Adapter Concepts book for an introduction to Internationalization topics such as Unicode and how adapters handle it.

Complete the following steps prior to running the adapter so it can handle files in different encodings.

1. Configure inter-communication encoding.

The wire format encoding used for communication between adapters and TIBCO-enabled applications is determined by the encoding property set in the project.

The adapter instance can be saved in a local or repository server-based project.

— If the adapter instance is saved in a repository server-based project, inter-communication encoding is determined by repo.encoding property in the server's tibcoadmin.tra file. Each adapter or TIBCO-enabled application that uses the repository server for storing and retrieving configuration data from a project uses this encoding setting when communicating. This assures that all components (including adapters and other TIBCO-enabled applications) that use the same repository also use the same encoding value to communicate. The repo.encoding property value can be ISO8859-1 (the default) or UTF-8. If English or other Latin-1 language data is transmitted between adapters, ISO8859-1 should be used. Otherwise use UTF-8.

— If an adapter instance is saved in a local project, the inter-communication encoding is determined by the encoding property of the local project file. To communicate with other adapters using the same encoding, all adapters and applications must set their local project file encoding property to be identical. The encoding value is set on the root project folder, in the Save Project dialog box, TIBCO Messaging Encoding field. The default encoding is ISO8859-1.

The encoding property set in the project file is superseded by the server's encoding property.

The encoding property discussed above is the encoding used by the communication between adapters and applications, not the encoding used for the persistent storage of the project files. Project files are always saved using UTF-8.

2. Java SDK takes advantage of the native Java Unicode support and does not use the tibicudata.dat. Therefore, the adapter does not require that you use tibicudata.dat.


Setting Encoding Options | 233

Since the adapter's target application is an EJB residing in a Java/J2EE application server, the adapter takes advantage of Java's Unicode support. Therefore, no application-specific encoding is required.



Running the Adapter and Application Server on Different Machines

To run the adapter, if the application server is not installed on the same machine as the adapter, you must make configuration changes to the adapter services.

PrerequisitesTo run the request-response server or subscription service using the remotely installed application server, you do not need any additional software on the application server machine.

To run the publication or request-response invocation service from the remotely installed application server, you must make the following software available on the machine on which the application server is installed:

• TIBCO Rendezvous

• TIBCO Runtime Agent

• TIBCO Enterprise Message Service client packages (required only if JMS transport is used).

Configuration Changes RequiredYou must make configuration changes when running the adapter on a remotely installed application server because:

• The application server J2EE implementation jar files are not available on the adapter machine and therefore, have to be made available. TRA files shipped with the installation use the application server home path specified during the installation to refer to the application server jar files. This path should be available to the adapter runtime.

• Some application server implementations require the generated stubs of the deployed beans to be in the classpath of the client application. These stubs are generated in the application server and therefore are not present on the adapter machine.

• When the adapter is running as a connector deployed in an application server, the adapter needs the TIBCO Rendezvous, TIBCO Runtime Agent, and TPCL-specific jar files, in the application server's classpath.

For details on the software version that is compatible with the adapter, see the TIBCO Adapter for EJB <version_num> readme.txt file.


Running the Adapter and Application Server on Different Machines | 235

• The default entry of the java.property.java.naming.provider.url property in the TRA files assumes that the application server is locally installed.

Making Configuration ChangesDo the following:

1. Make sure that the jar files listed in the table below are available on the machine on which the adapter is installed. Also, you must update the entries in the tibco.CUSTOM_CP_EXT variable in all the TRA files to use the location of the application server’s jar files. The jar files required for each of the supported application servers are listed in the following table:

Table 10 Locations of JAR files for the supported application servers

Application Server Location of the JAR files

BEA WebLogic 7.1 <APP_SERVER_HOME>/server/lib/weblogic.jar

BEA WebLogic 8.1 <APP_SERVER_HOME>/server/lib/weblogic.jar

BEA WebLogic 9.0, 9.1, and 9.2

<APP_SERVER_HOME>/server/lib/weblogic.jar

IBM WebSphere 5.1

<APP_SERVER_HOME>/lib/j2ee.jar, <APP_SERVER_HOME>/lib/namingserver.jar, <APP_SERVER_HOME>/lib/naming.jar

IBM WebSphere 6.0, 6.0.2, and 6.1

<APP_SERVER_HOME>/lib/j2ee.jar, <APP_SERVER_HOME>/lib/namingserver.jar, <APP_SERVER_HOME>/lib/naming.jar<APP_SERVER_HOME>/lib/namingclient.jar<APP_SERVER_HOME>/lib/ras.jar<APP_SERVER_HOME>/lib/wsexception.jar<APP_SERVER_HOME>/lib/bootstrap.jar<APP_SERVER_HOME>/lib/emf.jar<APP_SERVER_HOME>/lib/ecutils.jar<APP_SERVER_HOME>/lib/iwsorb.jar<APP_SERVER_HOME>/lib/idl.jar<APP_SERVER_HOME>/lib/ffdc.jar


<APP_SERVER_HOME>/lib/appserv-ext.jar



2. The stub generated when the glue beans are deployed in an application server should be made available on the adapter installation machine and be added to the classpath of the properties files of the adapter. You need to do this only for some of the supported application servers. The following table lists the application servers for which the stubs are required.


<APP_SERVER_HOME>/lib/appserv-ext.jar

JBoss 3.2.3 <APP_SERVER_HOME>/client/jbossall-client.jar

JBoss 4.0.0, 4.0.1, 4.0.2, 4.0.3, and 4.0.4

<APP_SERVER_HOME>/client/jbossall-client.jar

Oracle 9.0.3 <APP_SERVER_HOME>/j2ee/home/oc4j.jar<APP_SERVER_HOME>/j2ee/home/lib/ejb.jar<APP_SERVER_HOME>/j2ee/home/lib/jmxri.jar<APP_SERVER_HOME>/j2ee/home/lib/jta.jar<APP_SERVER_HOME>/j2ee/home/lib/connector.jar<APP_SERVER_HOME>/j2ee/home/lib/servlet.jar<APP_SERVER_HOME>/j2ee/home/lib/

Oracle 9.0.4, Oracle 10.1.2, and Oracle 10.1.3

<APP_SERVER_HOME>/j2ee/home/oc4j.jar<APP_SERVER_HOME>/j2ee/home/lib/ejb.jar<APP_SERVER_HOME>/j2ee/home/lib/jmxri.jar<APP_SERVER_HOME>/j2ee/home/lib/jta.jar<APP_SERVER_HOME>/j2ee/home/lib/connector.jar<APP_SERVER_HOME>/j2ee/home/lib/servlet.jar<APP_SERVER_HOME>/j2ee/home/lib/<APP_SERVER_HOME>/diagnostics/lib/ojdl.jar.

Table 10 Locations of JAR files for the supported application servers

Application Server Location of the JAR files

The names used in the table are the names generated for the stubs when the beans of the examples shipped with the adapter are deployed in an application server.


Running the Adapter and Application Server on Different Machines | 237

3. The jar files related to TIBCO Rendezvous (tibrvj.jar), TIBCO Runtime Agent (TIBCOrt.jar, TIBCOjms.jar, TIBCOtsm.jar, TIBCOxml.jar, TIBCrypt.jar), and TPCL (xercesImpl.jar, xmlParserAPIs.jar) should be made available on the application server machine.

4. The java.property.java.naming.provider.url property for all the TRA files that are shipped with the adapter must point to the IP address of the remotely installed application server.

Running the Subscription and Request-Response Server ServicesYou do not need to make any further configuration changes to run these services.

Running the Publication and Request-Response Invocation ServicesMake the following changes to run these services:

1. Make sure that the EjbSupport.jar, GlBeansSupport.jar, and AeConnector.jar files that are shipped with the adapter are available on the machine on which the application server is installed.

2. Set the classpath in the application server to contain references to jar files that are present in TIBCO Rendezvous, TIBCO Runtime Agent, and TPCL directories. These jar files are already made available if you have fulfilled the requirements specified in Prerequisites on page 234. For details, see Preparing EJB Application Interfaces on page 97.

3. Deploy the connector on the remote application server machine. For details, see Preparing EJB Application Interfaces on page 97.

Table 11 Locations of the Example Stubs files for the application servers

Application Server Location of Example Stubs File

IBM WebSphere 5.1 <APP_SERVER_HOME>/installedApps/<your-node-name>/ExampleBeans_jar.ear/ExampleBeans.jar


<APP_SERVER_HOME>/domains/domain1/server1/applications/j2ee-modules/ExampleBeans_1/ExampleBeansClient.jar


<APP_SERVER_HOME>/domains/domain1/applications/j2ee-modules/ExampleBeans/ExampleBeansClient.jar



4. By default, the AeConnector.rar file points to a local repository file, for example, C:\tibco\adapter\adejb\<version_num>\examples\data\ejb_sample\d

ata. Make sure that the AeConnector.rar file points to the correct location of the repository file. For details on modifying the repository URL, see Modifying the Repository and Configuration URLs of the Connector Configuration in the TIBCO Adapter for EJB Examples Guide.

After you have made the configuration changes listed in this section, you can run the publication and request-response invocation services.


Returning System Exceptions | 239

Returning System Exceptions

The adapter and connector can be configured to return the system exceptions to the calling process by setting the flag adejb.ThrowAdEJBSystemException in the properties file. The valid options are True or False.

For the inbound scenario, this flag is set in the tra file that is used by the adapter process during the startup. For the outbound scenario, this flag is set in the connector.tra present in the <ADEJB_HOME>/bin directory.

To return the system exceptions:

1. Set the value of the flag adejb.ThrowAdEJBSystemException in the tra file to true.

2. Make sure that the class adEJBSystemException is created in the repository with the two String attributes errorClass and errorMsg. This class should be present in /AESchemas/ae/adEJB/ejb/Classes.

3. RPC Operations must have the field adEJBSystemException. This field must point to /AESchemas/ae/adEJB/ejb.aeschema#class.adEJBSystemException.

If any step of the configuration is missed out, the exceptions are not returned to the calling process. An appropriate information message is logged.



Configuring the Connector Using the Properties File

You can override the values of the global variables present in the repository when you use the connector configuration.

Do not set any Java environment variable in this file as it is not supported by the connector configuration. TIBCO-specific properties like config url and repo url should not be set using this file. The connector deployment descriptor contains configuration property for setting these parameters. The connector configuration properties are specified in the <ADEJB_HOME>/bin/connector.tra file.

See the Predefined Global Variables section for more details on the list of global variables that can be specified in the connector.tra file.

You can also specify user-defined variables. For example, to set the subject name from the properties file, make sure the connector.tra file contains tibco.clientVar.SubjectName <subject>.

You must restart the application server if any property has changed in the connector.tra file.


Deploying Connectors in a Clustered Environment | 241

Deploying Connectors in a Clustered Environment

TIBCO Adapter for EJB supports deploying the connector in the clustered environment. This feature is tested and supported with BEA WebLogic Application Server 8.1 and WebSphere Application Server 6.0.

Deploying the connector in the clustered environment requires that CMName and the ledger file are different for each deployment. CM name must be unique in a given subnet, therefore, clustered deployments of the connector need to take care of this.

TIBCO Adapter for EJB supports the connector configuration through the properties file. So, you can maintain a properties file for each instance of the connector that needs to be deployed in the clustered environment. The following sections describe how to configure the connector, and deploy the connector and beans in a clustered environment.

The steps below assume a cluster with three managed servers, Server_1, Server_2 and Server_3 in the cluster named Cluster_1.

For BEA WebLogic Application Server 8.1

Configuring the Connector

To configure the connector:

1. The <ADEJB_HOME>/bin contains the file connector.tra. This file is used for providing the configuration properties for the connector. Since each connector instance must be configured with different CM name and ledger files, make copies of this file. For example, connector-1.tra, connector-2.tra and connector-3.tra.

2. Open connector-1.tra and add the following lines at the end of the file:

tibco.clientVar.CMName Server1tibco.clientVar.WLSServer Server1

3. Repeat step 2 for connector-2.tra and connector-3.tra and change the value Server1 to Server2 and Server3 respectively.

• To create a BEA WebLogic Application server cluster, visit http://e-docs.bea.com/wls/docs81/cluster/setup.html#757726

• To create a WebSphere Application Server cluster, visit http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/topic/com.ibm.websphere.nd.doc/info/ae/ae/trun_wlm_cluster.html



4. Copy the file <ADEJB_HOME>\lib\AeConnector.rar to create AeConnector-1.rar, AeConnector-2.rar and AeConnector-3.rar in a folder (D:\cluster).

5. Start a command prompt window and go to d:\cluster. Using the jar utility, extract AeConnector-1.rar. For example:

jar xvf AeConnector-1.rar.

This will create the folder META-INF and AeConnector.jar in the current folder.

6. Open ra.xml from the META-INF folder and change the value for the property d:/tibco/adapter/adejb/<version_num>/bin/connector.tra. The value by default is <ADEJB_HOME>\bin\connector.tra. Change this to <ADEJB_HOME>\bin\connector-1.tra. Also change map-config-property-value for the TraFileName property in the Weblogic-ra.xml file.

7. Delete AeConnector-1.rar and re-package AeConnector-1.rar by using the jar command at the command prompt. For example,

jar cvf AeConnector-1.rar META-INF AeConnector.jar

8. Delete the META-INF folder and AeConnector.jar file.

9. Repeat step 5, step 6, step 7, and step 8 and appropriately replace AeConnector-1.rar with AeConnector-2.rar and AeConnector-3.rar, and connector-1.tra with connector-2.tra and connector-3.tra respectively.

Configuring the Repository File

The CM Name and the Ledger File fields must include the global variables defined in the connector configuration files.

To change these fields for the ejb_sample.dat file:

1. Go to <ADEJB_HOME>/examples/data folder. This folder contains the repository file, ejb_sample.dat.

2. Create a new project in TIBCO Designer by importing the dat file.

3. Click Connector>RPC >Advanced>Sessions.

4. Click DefaultRVCMSession.

5. In the CM Name field, the default value is

%%Domain%%.%%Deployment%%.%%AppName%%.%%InstanceId%%.CM

Go to the end of the value and replace CM with %%CMName%%. The string value should be



%Domain%%.%%Deployment%%.%%AppName%%.%%InstanceId%%.%%CMName%%

6. In the Ledger File field, the default value is

%%DirLedger%%/%%AppName%%_%%InstanceId%%.ldg

Go to the end of the value and replace ldg with %%WLSServer%%. The string value should be

%%DirLedger%%/%%AppName%%_%%InstanceId%%.%%WLSServer%%

This creates two new global variables, CMName and WLSServer. The values of these global variables will be passed through the connector.tra file.

7. Save the project.

8. Export the project by clicking File>Export Full Project.

9. Specify the name of the dat file as ejb_sample and location as <ADEJB_HOME>/examples/data.

Deploying the Connector in the Cluster

In the following example, the domain mydomain has the administration server myserver. The cluster Cluster_1 is created with three servers Server_1, Server_2, and Server_3 associated with it.

The following jar files need to be added to the WebLogic classpath. You must add the jar files to the WebLogic classpath in startWebLogic.cmd and startManagedWebLogic.cmd (on Microsoft Windows) and startWebLogic.sh and startManagedWebLogic.sh (on UNIX).

%TIBCO_RV_HOME%\lib\tibrvj.jar%TIBCO_TRA_HOME%\lib\TIBCOxml.jar%TIBCO_TRA_HOME%\lib\TIBCOrt.jar%TIBCO_TRA_HOME%\lib\TIBCOtsm.jar%TIBCO_TRA_HOME%\lib\TIBCOjms.jar%TIBCO_TRA_HOME%\lib\TIBCrypt.jar%TIBCO_ADEJB_HOME%\lib\EjbSupport.jar%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jar %TIBCO_ADEJB_HOME%\lib\AeConnector.jar%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jar %TIBCO_TPCL_HOME%\lib\xercesImpl.jar

To start the administration server:

• Open the command prompt and go to the folder <WLS_HOME>/user_projects/mydomain.startWeblogic.cmd

The names CMName and WLSServer are the variable names defined in the connector configuration files.



To start the managed servers:

1. Open the command prompt and go to the folder <WLS_HOME>/user_projects/mydomain.

startManagedWebLogic.cmd Server_1

2. Repeat step 1 to start Server_2 and Server_3.

To deploy the connector on multiple servers, do the following from the administration console:

1. Click mydomain>Deployments>Connector Modules.

2. Click Deploy a new Connector Module on the right panel.

3. Browse for the AeConnector-1.rar file that was created while configuring the connector. Select AeConnector-1.rar and click Target Module.

4. Select the Cluster_1 check box and select Server_1 under Part of the Cluster.

5. Click Continue.

6. Change the connector name to AeConnector-1 and click Deploy.

7. Repeat step 1 through step 6 to deploy AeConnector-2.rar and AeConnector-3.rar.

Deploying the Beans

To deploy the beans:

1. Click mydomain>Deployments>EJB Modules.

2. On the right panel, click Deploy a new EJB Module.

3. Browse for <ADEJB_HOME>/examples/lib/ExampleBeans.jar. Select ExampleBeans.jar and click Target Module.

4. Click Cluster_1 and All Servers in the cluster and click Continue.

5. Click Deploy.

Running the EJB Client

The provider URL property needs to be changed to get the initial context to the server running in the cluster. For example, for running the Request Reply Invocation example, the value for the property java.property.java.naming.provider.url needs to be changed. The port should be changed to the port number of one of the servers in the cluster. For example:



java.property.java.naming.provider.url t3://localhost:7003

(7003 is the port on which Server_1 is listening for requests).

For WebSphere Application Server 6.0

Configuring the Connector

To configure the connector:

1. The <ADEJB_HOME>/bin contains the file connector.tra. This file is used for providing the configuration properties for the connector. Since each connector instance must be configured with different CM name and ledger files, make copies of this file. For example, connector-1.tra, connector-2.tra and connector-3.tra.

2. Open connector-1.tra and add the following lines at the end of the file:

tibco.clientVar.CMName Server1tibco.clientVar.WASServer Server1

3. Repeat step 2 for connector-2.tra and connector-3.tra and change the value Server1 to Server2 and Server3 respectively.

4. Copy the file <ADEJB_HOME>\lib\AeConnector.rar to create the AeConnector-1.rar, AeConnector-2.rar and AeConnector-3.rar in a folder (D:\cluster).

5. Start a command prompt window and go to d:\cluster. Using the jar utility, extract AeConnector-1.rar. For example:

jar xvf AeConnector-1.rar

This will create the folder META-INF and AeConnector.jar in the current folder.

Open ra.xml from the META-INF folder and change the value for the property d:/tibco/adapter/adejb/<version_num>/bin/connector.tra. The value by default is <ADEJB_HOME>\bin\connector.tra. Change this to <ADEJB_HOME>\bin\connector-1.tra.

6. Delete AeConnector-1.rar and re-package AeConnector-1.rar by using the jar command at the command prompt. For example,

jar cvf AeConnector-1.rar META-INF AeConnector.jar

7. Delete the META-INF folder and AeConnector.jar file.

8. Repeat step 5, step 6, and step 7, and appropriately replace AeConnector-1.rar with AeConnector-2.rar and AeConnector-3.rar, and connector-1.tra with connector-2.tra and connector-3.tra respectively.



Configuring the Repository File

The CM Name and the Ledger File fields must include the global variables defined in the connector configuration files.

To change these fields for the ejb_sample.dat file:

1. Go to the <ADEJB_HOME>/examples/data folder. This folder contains the repository file ejb_sample.dat.

2. Create a new project in TIBCO Designer by importing the dat file.

3. Click Connector > RPC > Advanced > Sessions.

4. Click DefaultRVCMSession.

5. In the CM Name field, the default value is %%Domain%%.%%Deployment%%.%%AppName%%.%%InstanceId%%.CM

Go to the end of the value and replace CM with %%CMName%%. The string value should be%Domain%%.%%Deployment%%.%%AppName%%.%%InstanceId%%.%%CMName%%

6. In the Ledger File field, the default value is %%DirLedger%%/%%AppName%%_%%InstanceId%%.ldg

Go to the end of the value and replace ldg with %%WASServer%%. The string value should be%%DirLedger%%/%%AppName%%_%%InstanceId%%.%%WASServer%%

This creates two new global variables, CMName and WASServer. The values of these global variables will be passed through the connector.tra file.

7. Save the project.

8. Export the project by clicking File > Export Full Project.

9. Specify the name of the dat file as ejb_sample and location as <ADEJB_HOME>/examples/data.

Deploying the Connector in the Cluster

In the following example, Dmgr01 is the WebSphere Application Server Network Deployment Manager. The cluster Cluster_1 is created with three servers Server_1, Server_2, and Server_3. Server_1 and Server_2 are on Node_1 and Server_3 is on Node_2.

The names CMName and WLSServer are the variable names defined in the connector configuration files.



The following jar files need to be added to the WAS classpath. You must add the jar files to WAS_HOME\lib\ext. If Node_1 and Node_2 are on different machines, the following jars must be added on both the machines.

%TIBCO_RV_HOME%\lib\tibrvj.jar%TIBCO_TRA_HOME%\lib\TIBCOxml.jar%TIBCO_TRA_HOME%\lib\TIBCOrt.jar%TIBCO_TRA_HOME%\lib\TIBCOtsm.jar%TIBCO_TRA_HOME%\lib\TIBCOjms.jar%TIBCO_TRA_HOME%\lib\TIBCrypt.jar%TIBCO_ADEJB_HOME%\lib\EjbSupport.jar%TIBCO_ADEJB_HOME%\lib\AeConnector.jar%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jar%TIBCO_TPCL_HOME%\lib\xercesImpl.jar

To start the deployment manager (On UNIX):

• Open the command prompt and go to the folder <WAS_HOME>/profiles/ Dmgr01/bin

startManager.sh

To start the deployment manager (On Microsoft Windows):

• On Microsoft Windows, select Start > Programs > IBM WebSphere > Application Server Network Deployment v6 > profiles > Dmgr01 > Start the deployment manager. The application server may take a few minutes to start.

To start the managed servers:

1. Do one of the following:

— To start the Administrative console (on UNIX). Open the web browser and type http://<hostname>:9060>/admin. A browser with two panels is displayed.

— To start the Administrative console (on Microsoft Windows), select Start > Programs > IBM WebSphere > Application Server Network Deployment v6> profiles> Dmgr01> Start Administrative Console. A browser with two panels is displayed.

2. Type the username and password to log on to the console.

3. Click Clusters under Servers. All configured clusters are displayed.

4. Select the check box against Cluster_1.

5. Click the Start button. This will start all the cluster members.

The cluster may take few minutes to start. After starting successfully a green arrow is displayed in status column of Cluster_1.

To deploy the connector on multiple servers, do the following from the administration console:



1. Install RAR on the nodes.

a. Click Resources > Resource Adapters.

b. Click Install RAR on the right panel.

c. Browse for the AeConnector-1.rar file that was created while configuring the connector using the local path.

d. Select Node_1 for Scope.

e. Click Next.

f. Enter AeConnector-1 as the name and click OK.

g. Repeat step a through step f to install AeConnector-2.rar on Node_1 and AeConnector-3.rar on Node_2.

2. Deploy RAR on the server.

a. Click Resources > Resource Adapters.

b. In Scope settings, select Node_1 for node and Server_1 for server.

c. Click Apply.

d. Click New.

e. Enter AeConnector-1 in the Name box.

f. Select the Active Path as {CONNECTOR_INSTALL_ROOT}/AeConnector-1.rar from the List of installed RAR files.

g. Click Apply.

h. Click J2C connection Factories under Additional Properties on the right panel.

i. Click New.

j. Enter AeConnector_ConnectionFactory in the Name box and tibco/aeconnector in the JNDI name box.

k. Click OK.

l. Repeat step a through step k to deploy AeConnector-2.rar on Server_2 and AeConnector-3.rar on Server_3.

The JNDI name should match the res-ref-name specified in the Glue EJB deployment descriptor file.



Deploying the Beans

To deploy the beans:

1. In the WebSphere Administrative Console, click Enterprise Applications under Applications. A list of the applications that are installed is displayed.

2. Click Install. The Preparing for the application installation screen is displayed.

3. Click Browse to locate the EJB jar file containing the glue beans. This file contains the EJB class files, the EJB deployment descriptor, ejb-jar.xml and WAS specific deployment descriptors ibm-ejb-jar-bnd.xmi and ibm-ejb-jar-ext.xmi.

4. Click Next twice to continue the EJB deployment.

5. Select the Deploy EJBs check box and click Next to continue the EJB deployment.

6. Click Next and verify that the JNDI names specified in the Provide JNDI Names for Beans screen are accurate.

7. Click Next and check the JNDI names of the connector reference in the Map resource references to resources page. Make sure that only two beans use the resource Reference Binding and that the JNDI name is tibco/aeconnector.

8. Click Next. The Map modules to application servers page is displayed.

9. Select Cluster_1 from the Cluster and Servers list box.

10. Select the jar file to deploy the beans.

11. Click Next until the Finish button is displayed.

12. Click Finish to complete the generation of the stubs and deploy the beans. This process will take a few minutes.

13. Click Save to save the master configuration. After you have deployed the beans, you must start them.

14. Click Enterprise Applications under the Applications folder.

15. Select the newly deployed enterprise application.

16. Click Start. The status of the newly deployed enterprise application changes from red to green.



Running the EJB Client

The provider URL property needs to be changed to get the initial context to the server running in the cluster. For example, to run the Request Response Invocation service example, the value for the property java.property.java.naming.provider.url needs to be changed.

You can use two different provider URL forms with the WebSphere Application Server's initial context factory:

• CORBA Object URL

• IIOP URL

Consider Server_1 is listening on 9810 bootstrap port, Server_2 is listening on 9811 bootstrap port, and Server_3 is listening on 9812 bootstrap port.

Server_1 and Server_2 are hosted on host1 and Server_3 is hosted on host3.

IIOP URL will be the bootstrap address of one of the servers in the cluster. For example:

java.property.java.naming.provider.url iiop://host1:9810

CORBA Object URL will contain the bootstrap addresses for all servers in the cluster in the URL. For example,

java.property.java.naming.provider.url corbaloc::host1:9810,:host1:9811,:host2:9812

For CORBA Object URL, the operation succeeds if at least one of the servers is running, eliminating a single point of failure. There is no guarantee of the order in which the address list will be processed. For example, the second bootstrap address may be used to obtain the initial context even though the server at the first bootstrap address in the list is available.

The URLs should only contain the bootstrap addresses of members of the same cluster. Otherwise, incorrect behavior might occur.


Converting the Sequence Field | 251

Converting the Sequence Field

In the earlier versions, the adapter converted a sequence to a Java list object and the list contained a MappedRecord for each item in the sequence.

In this version of the adapter, this feature is enhanced to allow you to select the conversion. You can opt to convert a sequence field to the actual Java object rather than a Mapped Record by setting the flag adejb.sequenceTypeToActualObject to TRUE. However, this is optional. The default behavior is to convert the sequence field to a Mapped Record.

For the inbound scenario, this flag needs to be set in the tra file that is used by the adapter process during the startup.

For the outbound scenario, this property needs to be set in the connector.tra file present in <ADEJB_HOME>/bin, where ADEJB_HOME is the adapter installation location.

To use the beans generated by earlier versions of the adapter:

1. Make a backup of the previous version of bean code.

2. Generate the beans using the Code Generator tool.

3. Add the business logic from the backup to the generated bean code.

4. Compile and redeploy the beans.

5. Make sure that the flag adejb.sequenceTypeToActualObject is set to TRUE.

6. Add the bean jar file to the application server classpath. This is required as the connector needs to access the utility classes generated during code generation. For details on how to add the jar file to the application server classpath, see Chapter 4, Preparing EJB Application Interfaces, on page 97.

7. Restart the application server.

This feature only works for the beans generated using the Code Generator tool provided in this version of the adapter. For this feature to work, you must add the beans jar to the application server’s classpath. To use the beans generated by earlier versions, follow the steps mentioned below.




| 253

Chapter 8 Monitoring the Adapter Using TIBCO Hawk

This chapter explains how to use TIBCO Hawk microagents to monitor and manage the adapter.

Topics


• Starting TIBCO Hawk Software, page 255

• The Auto-Discovery Process, page 256

• Invoking Microagent Methods, page 257

• Available Microagents, page 260


254 | Chapter 8 Monitoring the Adapter Using TIBCO Hawk

Overview

TIBCO Hawk is a sophisticated tool for enterprise-wide monitoring and managing of all distributed applications and systems. System administrators can use it to monitor adapters in a wide area network of any size. TIBCO Hawk can be configured to monitor system and adapter parameters and to take actions when predefined conditions occur. These actions include: sending alarms that are graphically displayed in the TIBCO Hawk display, sending email, paging, running executables, or modifying the behavior of a managed adapter.

Unlike other monitoring applications, TIBCO Hawk relies on a purely distributed intelligent agent architecture using publish or subscribe to distribute alerts. TIBCO Hawk uses TIBCO Rendezvous for all messaging and thus gains the benefits and scalability from the TIBCO Rendezvous features of publish/subscribe, subject name addressing, interest-based routing, and reliable multicast.

TIBCO Hawk is a purely event-based system that uses alerts. The agents are configured with rules that instruct them on everything from what and how to monitor to what actions to take when problems are discovered. Thus the workload is fully distributed throughout the enterprise. Every agent is autonomous in that it does not depend on other components to perform its functions.

The TIBCO Hawk Enterprise Monitor consists of these components:

• Display—GUI front end that displays alarms and provides editors to create rule bases, create tests, view messages, and invoke microagents to request information or initiate an action.

• Agents—Intelligent processes that perform monitoring and take actions as defined in rules.

• Rulebases—Rules that are loaded by agents to determine agent behavior.

• Application Management Interface (AMI)—Manages network applications via TIBCO Rendezvous and supports communication between a network application and monitoring TIBCO Hawk agents, including the ability to examine application variables, invoke methods, and monitor system performance.

• Microagents—Feed information back to TIBCO Hawk and expose action methods to rulebases.

For more information, see the TIBCO Hawk documentation.


Starting TIBCO Hawk Software | 255

Starting TIBCO Hawk Software

The TIBCO Hawk agent can be configured to start automatically during the system boot cycle. See the TIBCO Hawk Installation and Configuration guide for information about starting TIBCO Hawk.

The TIBCO Hawk Administrator’s Guide explains how to start the TIBCO Hawk Display.

The guides are included in your TIBCO Hawk software installation area.



The Auto-Discovery Process

After you start an instance of TIBCO Hawk Display, it continually discovers machines running TIBCO Hawk Agents on your network. Container icons are created for each agent, and arranged hierarchically in clusters. By default, agent icons are clustered according to subnets.

At first, the Agents container is empty. Its counter displays a value of zero and, on the right, the Discovered counter is also at zero. Both icons are initially green in color to show that no alerts, or warning messages, are in effect. As agents are discovered, the counters increment to reflect the current number of discovered agents:

Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a container in the left panel displays nested items on the right.

Icon colors change to reflect the highest level of alert found on discovered agents. For explanations of icon elements and characteristics, see your TIBCO Hawk Administrator’s Guide.


Invoking Microagent Methods | 257

Invoking Microagent Methods

A set of default microagents is loaded when a TIBCO Hawk Agent is started. When you install and start the adapter, its microagents are dynamically added to the local agent.

To invoke a microagent method:

1. Start TIBCO Hawk Display, then right-click on the agent icon and select Get Microagents.

If TIBCO Hawk security is implemented on your system and you do not have access to microagents on this agent, an error dialog displays. Select another agent, or contact your system administrator to obtain access.

The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent.

This dialog has two modes, Invoke and Subscribe. Invoking a method immediately returns a single set of current results. Subscribing provides updates of current results at regular intervals. Radio buttons at the bottom of the dialog control these modes.

2. Click a microagent name, such as Self, to display a list of associated methods and text descriptions in the panels below.



3. Click the name of the method to invoke, such as getComponentInfo.

If the method accepts arguments, fields for each argument display in the upper right panel. Detailed help text displays in the lower panel.

4. Specify any arguments for the method invocation.

5. Verify that the Invoke radio button is selected.

6. Click the Invoke button to invoke the selected method.

The Invocation Results dialog displays the results returned by the method.

7. Click Done to close the dialog.


Invoking Microagent Methods | 259

These steps describe how to interactively invoke a microagent method and receive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to evaluate them, then take action if necessary. For more information on building TIBCO Hawk rules and rule bases, see your TIBCO Hawk Administrator’s Guide.



Available Microagents

Each adapter has three microagents, a standard TIBCO Hawk microagent named COM.TIBCO.ADAPTER.xyz where xyz is the adapter configuration name, a custom microagent, and a class microagent (for PAM compliance). The microagents provide:

• Business level statistics—statistics that report the progress of the adapter as it interacts with the vendor application. For example, in a database adapter such statistics might indicate whether objects were successfully or unsuccessfully inserted, updated, or deleted in the database.

• Queries that return information about the state of the adapter. This can be an important tool for seeing the internals of an adapter and debugging it if something appears wrong. For example, methods can return information about threads, internal queues, or connections to the target system. Using these methods, one might be able to identify certain bottlenecks or gauge how successfully an adapter is scaling with respect to the current environment.

• Updates of the adapter runtime parameters. This includes retrieving the current runtime parameters and setting new runtime parameters without restarting the adapter. An example of this is getting and setting the polling interval. Updating a runtime parameter through the Hawk microagent only affects the setting of the instance that is running. It does not make a permanent change of the setting in either the repository or the .tra file.

By default all three microagents are available at runtime.

perfMon property value set in the adapter’s property file affects the business statistics related methods. If this property is set to on, the adapter does all the performance related calculations. When you invoke the methods, if the perfMon property is set to off, default values are displayed and not the valid values.

You can disallow adding custom methods to the class microagent when deploying the adapter by changing the addCustomHawkMethodstoClassMAgent property value in the adapter’s property file. If this property is set to on, custom methods are added to the class microagents. If set to off, these methods are not visible.

Custom microagents are deprecated in this release. All business statistics related methods which were part of the custom microagent are now available in the class microagent.


Available Microagents | 261

The following table lists each standard method available for the adapter and page on which the method is explained.

Table 12 Standard Microagent Methods

Method Description Page

activateTraceRole() Activates a mapping of a role to a sink at runtime.

264

deactivateTraceRole() Deactivates a mapping of a roles to sinks at runtime.

265

getActivityStatistics

()

Returns the total number of objects processed for all the schemas.

266

getActivityStatistics

ByService()

Returns information about the services implemented by this adapter.

267

getAdapterServiceInfo

rmation()


268

getComponents() Returns information about the publisher, subscriber and IODescriptor.

269

getConfig() Returns basic configuration information. More specific information is accessed by the more specific methods.

270

getConfigProperties() Returns all attributes and elements for the given repository object.

271

getConnectionStatisti

cs()

Returns the state and statistics for all the current connections used by the adapter.

272

getHostInformation() Returns standard and extended application information.

273

getPerfMonSetting() Returns the setting of the perfMon option.

274

getRvConfig() Returns information about all TIBCO Rendezvous sessions defined.

275



getStatus() Returns general status information, such as the number of TIBCO Rendezvous messages received and published, the number of errors since the last call, the PID of the application, and more.

276

getTraceSinks() Returns information about sinks to which traces currently go.

277

getVersion() Returns the configuration ID, application name, version, and date for this adapter instance.

278

_onUnsolictedMsg() Displays alert messages sent to the current adapter.

279

preRegisterListener() Preregisters an anticipated listener. 280

resetActivityStatisti

cs()

Resets all the counts for the activity statistics.

281

reviewLedger() Returns information retrieved from the ledger file of a certified messaging session for a publisher adapter.

282

setTraceSinks() Adds a role or changes the file limit of a previously specified sink.

284

stopApplicationInstan

ce()

Stops the running adapter instance. 285

unRegisterListener() Unregisters a currently preregistered listener.

286

Table 13 Class Microagents


getActivityStatis

ticsBySchema()

Returns the total number of objects processed for the given schema by each service that uses the schema.

287

Table 12 Standard Microagent Methods (Cont’d)

Method (Cont’d) Description (Cont’d) Page


Available Microagents | 263

From the 5.1.0 release, the adapter’s custom microagent includes the following deprecated methods:

• getActivityStatistics()

• getActivityStatisticsBySchema()

• getActivityStatisticsByService()

• resetActivityStatistics()

You should use the same methods available in the class microagent because they have been enhanced to report additional information. The methods in the custom microagent exist for backward compatibility.



activateTraceRole()

Activates a mapping of a role to a sink at runtime. This replaces the now-deprecated setTraceSink() TIBCO Hawk method.

Input Parameters Type Description

Role Name string Name of the role to activate.

Sink Name string Name of the sink for which to activate the role.


deactivateTraceRole() | 265

deactivateTraceRole()

Deactivates a mapping of roles to sinks at runtime.


Role Name string Name of the role to activate.

Sink Name string Name of the sink for which to activate the role.



getActivityStatistics()

Returns the total number of objects processed for all the schemas, based on the request type. Also, returns the number of success and error objects.

Input Parameter Type Description

GetSubTotalBy string Indicates how to group the subtotals, by Service or Operation.

Returns Type Description

Name string Service name or All Services which represents the final tally of all the services

Total integer Total number of objects processed including both success and failures.

Success integer Total number of objects successfully processed.

Failure integer Total number of objects that caused an error during processing.

MeasurementInterval

integer Displays the time (in seconds) since last time the adapter was reset, or if never reset, since the adapter started.


getActivityStatisticsByService() | 267

getActivityStatisticsByService()

Returns statistics about the data handled by a given adapter service or all adapter services since the time the adapter was started.

Input parameter Type Description

Service Name string Name of service to get the statistics for. If no service name is given, performance statistics for all services is returned.


Service Name string Service name

Schema Name string Name of top level schema processed by this service.

Operation string Type of operation this service provides.

Total integer Total number of objects processed, both success and failures.

Success integer Total number of objects successfully processed.

Failure integer Total number of objects that caused an error during processing.

MeasurementInterval


LineIndex string Concatenated string of Service Name and Operation separated by a comma.



getAdapterServiceInformation()



Service Name string Name of the service from which to get information. Default is ALL.


Line integer Sequential row number.

Service Name string Name of the service as defined at design-time.

Endpoint Name string Name of the endpoint used for this service.

Type string Type of the endpoint, for example, publisher or subscriber.

Quality of Service

string Quality of service for the endpoint. For example RVCM or JMS Persistent.

Subject string Subject defined for this endpoint.

Class string Class associated with the endpoint.

Number of Messages

integer Number of messages processed for this endpoint.


getComponents() | 269

getComponents()

Returns information about the currently active TIBCO Hawk components such as publishers, subscribers, or timers.


Component Name string Name of the component. If no value is entered, all components display.

Component Type string Any of Publisher, Subscriber, Timer, or IODescriptor. The default value is All.


Instance ID string Name of this adapter instance as defined at design-time.

Adapter Name string Name of the adapter.

Component Name string Name of the component.

Component Type string The name of the TIBCO Adapter SDK class for this component, such as Publisher, Subscriber, or IODescriptorSource. For more information about the class, see your TIBCO Adapter SDK documentation.

Session Name string Name of the session.

Description string Information about this component, for example, time interval, signal type, and validating the publisher or subscriber.



getConfig()

Retrieves generic configuration information. More specific configuration information is accessed through separate methods.


Instance ID string Configuration ID of this adapter.


Repository Connection

string URL of the repository used for adapter instance.

Configuration URL

string Location of the adapter project; either a file name or configuration URL.

Command string Command line arguments used to start the adapter.


getConfigProperties() | 271

getConfigProperties()

Returns all attributes and elements for the given repository object.


Property string Name of the property for which elements (tags) and attributes are desired. For example, agentone/startup.

If no value is given, all properties are returned.


Element Name string Repository directory for the property.

Attribute Name string Name of the repository object attribute.

Attribute Value string Value of the repository object attribute.

Line integer Line number in which this property is defined in the project file.



getConnectionStatistics()

Returns the state and statistics for all the current connections used by the adapter.


Connection ID string Unique identification of a particular connection.

Connection Type string Type or key that will match this connection to a thread or queue.

State string Current state: CONNECTED or DISCONNECTED.

NumRetries integer Total number of times this connection had to be reestablished.

TotalNumOperations

integer Total number of operations processed by this connection since the adapter started.

CurrentNumOperations

integer Total number of operations processed by this connection since the last reconnection.

NumLostConnections

integer Total amount of time that this connection has been lost.

MeasurementInterval



getHostInformation() | 273

getHostInformation()

Returns standard and extended application information set. It returns the following information.


Name string Name of the property.

Value string Value of the property.



getPerfMonSetting()

Returns the setting of the perfMon option. It returns the following information.


Setting string Value of the perfMon option.


getRvConfig() | 275

getRvConfig()

Returns information about the TIBCO Rendezvous session defined by this adapter. Information about all currently defined sessions is returned if no sessionName is provided.


Session Name string Name of the TIBCO Rendezvous session for which configuration is required. If not given, information about all sessions is returned. The default is all.


Instance ID string Configuration ID of this adapter.


Session Name string Name of the session.

Service string Service parameter for this session.

Daemon string Daemon parameter for this session.

Network string Network parameter for this session.

Synchronous? boolean Returns 1 if this is a synchronous session, 0 otherwise.

Session Type string Type of session; one of M_RV, M_RVCM, or M_RVCMQ.

Certified Name string Name of this certified session.

Ledger File string Ledger file for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.

CM Timeout string Timeout for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.



getStatus()

Retrieves basic status information about the adapter.

This information is fairly limited; for more detail, additional methods are provided (getConfig() on page 270 and getRvConfig() on page 275).


Instance ID string Configuration ID for this adapter instance.


Uptime integer Number of seconds since startup.

Messages Received integer Number of TIBCO Rendezvous messages received.

Messages Sent integer Number of TIBCO Rendezvous messages published.

New Errors integer Number of errors since the last call to this method.

Total Errors integer Total number of errors since startup.

Process ID integer Process ID of the application.

Host string Name of host machine on which this adapter is running.


getTraceSinks() | 277

getTraceSinks()

Returns information about sinks to which traces currently go.


Sink Name string Name of the sink for which you need information. If no name is specified, information about all sinks is returned. Default is all.

Role Name string Name of the role for which you need information for the specified sink or sinks. Default is all.


Instance ID string Name of this adapter instance as a string.

Adapter Name string Name of the application for this sink.

Sink Name string Name of the sink

Sink Type string Type of this sink. One of fileSink, rvSink, hawkSink, stderrSink.

Roles string Roles this sink supports, as a string. For example warning, error, debug.



getVersion()

Retrieves version information for the current application. Two lines may be returned, one for the TIBCO Adapter SDK, one for the adapter.

Returns Description

Instance ID Configuration ID as a string, for example SDK.

Adapter Name Name of the adapter as a string, for example agentone.

Version Version number as a string, for example 5.1.


_onUnsolictedMsg() | 279

_onUnsolictedMsg()

Displays all alert messages sent from the adapter or an error if not successful.



preRegisterListener()

Preregister an anticipated subscription service. Some sending applications can anticipate requests for certified delivery even before the listening applications start running. In such situations, the publication service can preregister subscription services, so TIBCO Rendezvous software begins storing outbound messages in the publication service ledger. If the listening correspondent requires old messages, it receives the backlogged messages when it requests certified delivery.

Returns OK if the subscription service was preregistered successfully, false otherwise.


Session Name string Name of the session that anticipates the listener.

Publisher Name string Name of the component for which the listener should be preregistered.

Listener Session Name

string Name of the subscription service to preregister.


resetActivityStatistics() | 281

resetActivityStatistics()

Resets all the counts for the activity statistics.



reviewLedger()

Returns information retrieved from the ledger file of a TIBCO Rendezvous certified messaging session.

Before invoking this method, ensure that the certified messaging publisher adapter has established a certified delivery agreement with its subscriber agents.


Session Name string Name of the TIBCO Rendezvous session for which ledger information is desired (default is all).

Subject string Name of the subject for which ledger information is desired.


Session Name string Name of the TIBCO Rendezvous CM session to which this information applies.

Subject string Subject name for this session.

Last Sent Message integer Sequence number of the most recently sent message with this subject name.

Total Messages string Total number of pending messages with this subject name.

Total Size integer Total storage (in bytes) occupied by all pending messages with this subject name.

If the ledger contains ten messages with this subject name, then this field sums the storage space over all of them.


string Within each listener submessage, the Listener Session Name field contains the name of the delivery-tracking listener session.


reviewLedger() | 283

Last Confirmed string Within each listener submessage, the Last Confirmed field contains the sequence number of the last message for which this listener session confirmed delivery.

Line integer Row number in ledger file.

UnacknowledgedMessages

integer Number of RVCM messages pending for this listener. The value is computed by subtracting the last sent sequence number from the last acknowledged sequence number.

Returns (Cont’d) Type Description



setTraceSinks()

Adds a role or changes the file limit of a previously specified sink.

Returns OK if successful or an error if not successful.


Sink Name string Name of the sink for which you want to add a role or change the file limit.

Role Name string Name of the role you want to add to this sink (warning, error, debug, or user defined). Default is all.

File Size integer Maximum file size for this sink.

This parameter is ignored if the sink specified by sinkName is not a file sink.


stopApplicationInstance() | 285

stopApplicationInstance()

Stops the specified adapter by calling the internal stop() method. This method returns OK if successful or an error if not successful.



unRegisterListener()

Unregister a currently preregistered subscription service.

This method returns true if the subscription service was unregistered successfully, false otherwise.


Session Name string Name of the session that anticipates the subscription service.

Publisher Name string Name of the publication service to which the subscription service is preregistered.


string Name of the subscription service to unregister.


getActivityStatisticsBySchema() | 287

getActivityStatisticsBySchema()

Returns the total number of objects processed for the given schema by each service that uses the schema. Also, returns the number of success and error objects.


Schema Name string Name of the schema.


Service Name string Name of the service that is associated with the specified schema.

Total string Total number of objects processed for this schema for a publication service.

Total number of objects received for this schema for a subscription service.

Success string Number of objects that were successfully identified for this schema, which will be published or written to a file.

Failure string Number of objects that were identified for this schema but were not published because the header of the schema failed validation for a publication service, or was written to a file because the schema was not associated with a subscriber for a subscription service.




| 289

Chapter 9 Code Generator

This chapter describes the code generator component of the adapter.

Topics


• Code Generator Inputs, page 292

• Code Generator Outputs, page 297

• Generating Glue Beans to Enable Inbound Communication, page 300

• Generating Glue Beans to Enable Outbound Communication, page 310

• Using the Generated Glue Beans, page 320


290 | Chapter 9 Code Generator

Overview

The Code Generator is a Java library that runs as part of the adapter's palette. The code generator takes in inputs that describe legacy EJBs deployed in the application server and generates beans that enable communications between the legacy and either the adapter or the connector. The generated beans called glue beans, serve as a bridge between legacy EJBs and TIBCO Adapter for EJB when they are deployed in the application server.

The code generator tool can generate deployment descriptors for EJB Specification version 1.1, 2.0, and 2.1. The adapter supports inbound and outbound communication differently. The code generator has two main modes of operation, depending on whether inbound or outbound communication to the TIBCO message transport from an EJB is required:• In the case of inbound communication, the code generator generates an EJB

code skeleton that has empty bodies for the bean method implementations.

TIBC

O M

essa

ging

Support Library

LegacyBean

ConnectorBean

GLUEBEAN

TIBC

O A

dapt

erfo

r EJB

Application Server

Code GeneratorEngine

JNDI

Adapter PaletteTIBCO Repository

Indicates ‘generates’

Indicates ‘uses’

Legend:


Overview | 291

These can be filled with business logic. The bean implementation will be called by the adapter process when incoming requests are received by that process from the TIBCO message transport. The bean in this case functions as either a request-response server or as a subscriber to TIBCO data.

• In the case of outbound communication, the code generator creates a complete EJB with a home interface, remote interface, bean implementation class, and deployment descriptor. The resulting bean will use the J2EE Connector library to interface with a TIBCO component. The bean in this case functions either as a request-response invocation service or as a publisher of data.

Necessity of Code Generator or Glue BeansThe primary assignments of the TIBCO Adapter for EJB are:• To enable components in the TIBCO environment, such as TIBCO

IntegrationManager, TIBCO BusinessWorks, or TIBCO Adapters to use (invoke) legacy EJB-enabled services deployed and running in application servers.

• To enable legacy components in the EJB/application server environment to use/invoke TIBCO services, such as the services of another TIBCO adapter.

In both these scenarios, the presence of legacy EJBs means that the TIBCO Adapter for EJB must be able to adapt to varying parameters such as:• A variety of application servers.

• Legacy beans with varying JNDI names, Home and Remote interfaces.

• Legacy beans with varying services and methods.

To be able to satisfy both scenarios and the parameters, the adapter must interact with components that have been customized with the individual parameters of the legacy beans. These components must have the ability to communicate both with the adapter and with the legacy beans.

These components are glue beans, and TIBCO Adapter for EJB provides a Code Generator component that automates the generation of these glue beans.



Code Generator Inputs

The following figure shows the various inputs that are required by the Code Generator.

EJB Spec Version

• Valid Values — 1.1, 2.0, or 2.1

• Default Value — For standalone adapter and outbound connector, 2.0. For inbound connector (JCA 1.5 compliant), 2.1.

• Purpose — Generates bean code and deployment descriptors that are compliant with either the EJB 1.1, 2.0, or 2.1 specifications. It is recommended that you retain/set the value to 2.0 or 2.1, unless you are generating beans that will be deployed in application servers that support the EJB 1.1 specification. Verify the EJB specification version that your application server supports before setting this field.

• Services Affected — Publication, Subscription, Request-Response Invocation, Request-Response Server.

• Mandatory — Yes.

Bean

• Valid Values — The complete path, location and valid name of a directory.


Code Generator Inputs | 293

• Default Value — None. Browse to select the location of a valid, existing directory.

• Purpose — This field specifies the location where the generated code should be saved.




• Valid Values — The complete path, location and valid name of a directory.

• Default Value — Implicitly same as the Bean's directory (see Bean above).

• Purpose — This field specifies the location where the generated deployment descriptor file should be saved.


• Mandatory — No. If not specified, the code generator saves the deployment descriptor in the directory specified for the generated bean code.

Package Root

• Valid Values — Directory names separated by periods. Names of directories must adhere to the conventions and rules specified by the operating system. For example, directory names on Microsoft Windows platforms cannot contain special characters such as ?, :, >, and so on. For example, a typical package root may look like this:

com.tibco.test

• Default Value — None. If not specified, code is generated directly under the directory specified in the bean directory field.

• Purpose — This field specifies the directory structure to create under the bean directory field. Generated code is then saved in the package root directory structure. This is useful when the packaging of the generated bean needs to be analogous to the packaging of legacy beans deployed in the target application server.


• Mandatory — No. If not specified, code is generated directly under the directory specified in the bean directory field.




• Valid Values — Selected, Cleared

• Default Value — Selected

• Purpose — If the check box is selected:

— The Resource Reference field is displayed.

— The Repository URL field is hidden.

— The generated deployment descriptor file will include a resource-ref section for each bean. The resource-ref section is used to specify information about a deployed resource archive and its associated ConnectionFactory class.

• Services Affected — Publication, Request-Response Invocation.

• Mandatory — Yes. This field must be selected if the application server supports the Java Connector Architecture specification and if you intend to deploy the Connector as Java library (jar) rather than a resource archive (rar).

Resource Reference

• Valid Values — The name of a valid resource reference.

• Default Value — None.

• Purpose — This field is used by the generated bean code to look up the Connector bean's ConnectionFactory in the JNDI.

This field is visible only when the Use Resource Reference check box is selected. When the check box is selected, the generated deployment descriptor file will include a resource-ref section for each bean. The resource-ref section is used to specify information about a deployed resource archive and its associated ConnectionFactory class. See Use Resource Reference for further details.

The resource reference field will be used to fill in the res-ref-name part of the resource-ref section in the deployment descriptor. This is the name that the bean code will use to look up the TIBCO J2EE Connector's ConnectionFactory. This name will be mapped to a JNDI location when the Connector is deployed and registered into the application server environment.

• Services Affected — Publication, Request-Response Invocation.

• Mandatory — Yes. This is a required field when the Use Resource Reference check box is selected.


Code Generator Inputs | 295

Repository URL

• Valid Values — A repository URL. This could be either local or remote. When local, the URL must contain the complete path and name of the repository.


• Purpose — This field is used by the generated bean code to look up the Connector bean's configuration information.

This field is visible only when the Use Resource Reference check box is cleared. When the box is cleared, the code generator will use the Repository URL field. The Repository URL is a string that identifies the name and, if necessary, connection parameters for the TIBCO Repository instance containing the Connector configuration. For example: tibcr://ejb_sample:userName=adejb:password=adejb.

• Services Affected — Subscription, Request-Response Server.

• Mandatory — Yes. This is a required field when the Use Resource Reference check box is cleared.

Configuration URL

• Valid Values — URLs in strings that point to valid adapter configurations.

• Default Value — The URL of the adapter instance being configured. For example, /tibco/private/adapter/Connector/RPC/SampleEJBAdapter.

• Purpose — This is a string that identifies the location of the adapter configuration information in the repository. This is not an editable field — it merely indicates the adapter configuration for which code will be generated.



EJB Name Prefix

• Valid Values — Any alphanumeric string that conforms to the Java/J2EE variable naming conventions.


• Purpose — The value in this field will be prepended to the ejb-name value in the generated beans' deployment descriptor. This is a convenient feature that lets you group and identify beans based on a common, well-known prefix.




• Mandatory — No.

Indent Level

• Valid Values — 0 - 99

• Default Value — 4

• Purpose — This field adjusts the indent level of the generated code. It assists in code beautification and better comprehension.


• Mandatory — No.


Code Generator Outputs | 297

Code Generator Outputs

You can see examples of the code generator's output for different types of beans by examining the examples\beans directory under the adapter installation. This directory contains the source code for the four main classes of EJBs that can be generated. The classes are request-response invocation services, request-response server services, publishers, and subscribers. The request-response invocation service is under the com/tibco/connector directory, and the request-response server service is under the com/tibco/adapter directory.

Code can be generated by clicking the Generate Code button for the adapter service during configuration. For details, see Adapter Instance Options on page 177. The generated EJB is a stateless session bean (a Message Driven Bean if Inbound Connector is selected as the deployment option) that corresponds to a TIBCO application endpoint. The business methods of the bean use only standard Java primitive classes, Java 2 container types such as Map and List, and classes that are derived from javax.resource.cci.Record.

The code generator will write the generated code to the directory specified in the Output Dir Location of the code generator window. All generated classes will have the package prefix specified in the Package Root field. The remainder of the class name will come from the URL path of the endpoint from which the class is generated.

For request-response invocation and publication services, the code generator produces a complete EJB consisting of a home and remote interface, and bean implementation class. The generated bean uses some utility classes which provide a wrapper around the TIBCO J2EE Connector API. These classes are named RPCSupport and PublishSupport, and are further documented in Appendix B, Bean Programming Guide for Request-Response Invocation and Publication Services, on page 375.

For request-response server and subscription services, the code generator does not produce a full EJB implementation. Instead, it generates a skeleton that allows a program developer to fill in the logic implement a TIBCO service using an EJB. See Appendix C, Bean Programming Guide for Request-Response and Subscription Services, on page 407, for information on how to complete the skeleton implementation.

The Code Generator generates classes for all the inputs and outputs in an operation. However, if the return type is a class, the java class will not be generated.



Directory Structure and Class NamesGenerated beans are placed in a directory structure that corresponds to the structure of the TIBCO ActiveEnterprise class definitions in the repository. For example, a server for the class located at /tibco/public/classes/ae/OrderManagement/PurchaseOrder in the repository is placed in the directory ae/OrderManagement/ under the root directory specified in the code generator UI.

The names of the generated classes also follow the names of the corresponding TIBCO ActiveEnterprise classes. For example, if the TIBCO ActiveEnterprise class is named PurchaseOrder, the bean class would have one of the following names, based on its role:• "PurchaseOrderBean" if it is a request-response invocation service for an

operation that is part of the PurchaseOrder class.

• "PurchaseOrderBean" if it is a request-response server service for operations on the PurchaseOrder class.

• "Subscribe_PurchaseOrderBean" if it is a subscriber to data instances of class PurchaseOrder

• "Publish_PurchaseOrderBean" if it is a publisher of instances of class PurchaseOrder.

• "PurchaseOrderMDB" if it is a request-response service for an operation that is part of the class PurchaseOrder and the deployment option is Inbound Connector.

• "Subscribe_PurchaseOrderMDB" if it is a subscriber to data instances of the class PurchaseOrder and the deployment option is Inbound Connector

The corresponding remote interfaces will have names without the "Bean" suffix.

Dependent Classes and ExceptionsA generated class may depend on other classes. For example, a method within the PurchaseOrder class may take an argument that is of type Customer. In this case, the code generator will produce source for the Customer class which implements it as a Record instance. That is, it will implement the javax.resource.cci.Record interface, and also have standard get and set methods for the class attributes, per the Java Beans (not EJB) specification. These dependent classes will be placed in a directory structure corresponding to the location of their class definition within the repository, as explained in the preceding section.


Code Generator Outputs | 299

Similarly, if a method within the class is declared (in the TIBCO ActiveEnterprise metadata) to throw a non-standard exception, then source for an exception class will be generated, which will extend java.lang.Exception.

The exception classes will be placed in the same directory as the class that uses them.

Also a helper class (AttributeDetails) containing the ActiveEnterprise Class names and the corresponding java class name is generated in the same directory. This is required for the adapter to convert the ActiveEnterprise Object to the corresponding java object during the runtime

Deployment DescriptorThe EJB code generator produces a standard EJB 1.1, 2.0, or 2.1 deployment descriptor file, which needs to be placed in the META-INF directory of the bean archive. This file contains the minimal deployment information required for the bean(s) that have been generated. In addition, when generating code for a bean that is an RPC client or publisher, the code generator will add to each bean's session tag either a resource-ref element or a set of env-entry elements, that contain information needed to establish a connection to the J2EE Connector library. See Deployment Descriptor on page 404, for a description of these elements.

Note that some EJB server vendors, including BEA WebLogic, require additional vendor-specific XML files to be included in the META-INF directory of an EJB archive. At present, the EJB code generator does not generate these vendor-specific XML files.



Generating Glue Beans to Enable Inbound Communication

To enable inbound communication, the following can be generated:• Generating Glue Beans for the Subscription Service

• Glue Beans for the Request-Response Server Service

Generating Glue Beans for the Subscription ServiceThe following sections provide information about generating subscription service glue beans for the standalone adapter and for the inbound connector.

For Standalone Adapter

The typical glue bean code generated for a subscription service, using an ActiveEnterprise schema class ae/SAP_EXAMPLES/SAPAdapterSchema/BRFCKNA1 and the package root as com.tibco. would contain the following files:• EJBHome class —

com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.Subscribe_BRFCKNA1Ho

me.java

• EJBObject class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.Subscribe_BRFCKNA1.j

ava

• Stateless Session Bean — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.Subscribe_BRFCKNA1Be

an.java

• Schema class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.BRFCKNA1.java

• Attribute Detail Class —com.tibco.ae.SAP_EXAMPLE.SAPAdapterSchema.AttributeDetails.java

• Deployment descriptor — ejb-jar.xml

EJBHome Class

This contains a create method that will create the corresponding EJBObject class.

public interface Subscribe_BRFCKNA1Home extends EJBHome {

public Subscribe_BRFCKNA1 create() throwsRemoteException, CreateException;


Generating Glue Beans to Enable Inbound Communication | 301

}

EJBObject Class

This class contains the abstract method subscribe with the following signature:

public interface Subscribe_BRFCKNA1 extends javax.ejb.EJBObject{public void subscribe (com.tibco.subscribe.ae.SAP_EXAMPLE.SAPAdapterSchema.BRFCKNA1 ) throws java.rmi.RemoteException, java x.ejb.EJBException;

}

Stateless Session Bean Class

Apart from the usual life cycle methods, this contains the following method:

public void subscribe (com.tibco.subscribe.ae.SAP_EXAMPLE.SAPAdapterSchema.BRFCKNA1 subscribeObj) throws java.rmi.RemoteException, javax.ejb.EJBExc

epti on {// add method implementation here}

This is the main business method of the session bean, to which you must add the custom implementation.

Schema Class

This is a class that corresponds to the ActiveEnterprise schema class that extends javax.resource.cci.Record. A typical code snippet of this class appears as follows:

public class BRFCKNA1 implements javax.resource.cci.Record, java.io.Serializable{

public BRFCKNA1(){

m_recordName = "BRFCKNA1";m_recordShortDescription = "container for instance of TIBCO ActiveEnterprise class /tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema/BRFCKNA1";

}

String m_recordName;String m_recordShortDescription;

String m_KUNNR;



String m_NAME1;

public String getKUNNR() {return m_KUNNR;

}

public void setKUNNR(String p_KUNNR) {m_KUNNR = p_KUNNR;

}

public String getNAME1() {return m_NAME1;

}

public void setNAME1(String p_NAME1) {m_NAME1 = p_NAME1;

}................

}

The generated class contains attributes that correspond to the fields present in the ActiveEnterprise schema class and Java Bean-compliant get and set methods for these attributes.

Attribute Detail Class

This class contains the information that is required by the adapter to convert the ActiveEnterprise Class mentioned in the sequence attribute during the ActiveEnterprise schema creation, to the actual java object. The typical code snippet for this class appears as follows:

public class AttributeDetails {public Map getMap(){

Map map = new HashMap();map.put(<AEClass>, <Java Class>);return map;

}}


The deployment descriptor, ejb-jar.xml, is EJB 1.1, 2.0, or 2.1 compliant based on the option selected. A typical ejb-jar.xml appears as follows:



<ejb-jar><description />



<display-name>TIB Integration Server Beans</display-name><small-icon /><large-icon /><enterprise-beans>

<session><description>Subscriber to TIBCO AE Class

/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema/BRFCKNA1</description>

<display-name>Subscribe_BRFCKNA1Bean</display-name><small-icon></small-icon>

<large-icon></large-icon><ejb-name>Subscribe_BRFCKNA1Bean</ejb-name>

<home>com.tibco.subscribe.ae.SAP_EXAMPLE.SAPAdapterSchema.Subscribe_BRFCKNA1Home</home><remote>com.tibco.subscribe.ae.SAP_EXAMPLE.SAPAdapterSchema.Subscribe_BRFCKNA1</remote><ejb-class>com.tibco.subscribe.ae.SAP_EXAMPLE.SAPAdapterSchema.Subscribe_BRFCKNA1Bean</ejb-class>


</session>

</enterprise-beans><ejb-client-jar />

</ejb-jar>

Generating Glue Beans

To generate the glue beans:

1. To compile the Java code, set classpath to include <TRA_HOME>\lib\TIBCOrt.jar;<ADEJB_HOME>\lib\EjbSupport.jar;<ADEJB_HOME>\lib\GlBeansSupport.jar and a jar file that contains J2EE interfaces. For example, <J2EE_RI_HOME>\lib\j2ee.jar.


javac com\tibco\ae\SAP_EXAMPLES\SAPAdapterSchema\*.java

Before you generate the jar file for the glue beans, generate the application server-specific deployment xml generated. For details on generating the deployment descriptor, see the documentation for the application server you are using.

To make a jar file, run the following command:

jar -cvf ExampleBeans.jar com META-INF

This will generate the glue beans jar for deployment.



For Inbound Connector

The typical glue bean code generated for a subscription service, using an ActiveEnterprise schema class ae/SAP_EXAMPLES/SAPAdapterSchema/BRFCKNA1 and the package root as com.tibco. would contain the following files:• Message Driven Bean Implementation class —

com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.Subscribe_BRFCKNA1MD

B.java

• Schema class —

com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.BRFCKNA1.java

• Attribute Detail Class —

com.tibco.ae.SAP_EXAMPLE.SAPAdapterSchema.AttributeDetails.java


Message Driven Bean Implementation class


public void subscribe(com.tibco.subscribe.ae.SAP_EXAMPLE.SAPAdapterSchema.BRFCKNA1 subscribeObj) throws java.rmi.RemoteException,javax.ejb.EJBException {// add method implementation here}


Schema Class


public class BRFCKNA1 implements javax.resource.cci.Record,java.io.Serializable

{public BRFCKNA1(){

m_recordName = "BRFCKNA1";m_recordShortDescription = "container for instance ofTIBCO ActiveEnterprise class/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema/BRFCKNA1";}



Glue Beans for the Request-Response Server ServiceThe typical glue bean code generated for a request-response server service, using an ActiveEnterprise operation class ae/SAP_EXAMPLES/SAPAdapterSchema/RFC_CUSTOMER_GET with the operation RFC_CUSTOMER_GET which in turn uses the schema class BRFKCNA1, displays InvalidCustException, and has the package root as com.tibco contains the following files:• EJBHome class —

com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GETHome

.java

• EJBObject class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GET.jav

a

• Stateless Session Bean — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GETBean

.java


• Operation schema class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GET.jav

a

• Exception class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GET_Inv

alidCustException.java

• Exception data class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.InvalidCustException

Data.java

• Attribute Detail Class —com.tibco.ae.SAP_EXAMPLE.SAPAdapterSchema.AttributeDetails.java


EJBHome Class


public interface RFC_CUSTOMER_GETHome extends EJBHome {



public RFC_CUSTOMER_GET create() throwsRemoteException, CreateException;

}

EJBObject Class

This class contains the abstract method RFC_CUSTOMER_GET1 with the following signature:

public interface RFC_CUSTOMER_GET extends javax.ejb.EJBObject{

public java.util.Map RFC_CUSTOMER_GET1 (com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.BRFCKNA1) throws RFC_CUSTOMER_GET_InvalidCustException, java.rmi.RemoteException,

javax.ejb.EJBException, com.tibco.ejb.support.AEEjbException;

}

The method name is changed to RFC_CUSTOMER_GET1 because it matches with the operation class name. Therefore, if the same name is used, the method name is treated as a constructor. A 1 is appended to the method name. The return type of the method is a Map. This map contains a parameter called _returnValue that gives the status of the method call and information on any additional return value from the method call.



public java.util.Map RFC_CUSTOMER_GET1 (com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.BRFCKNA1) throws RFC_CUSTOMER_GET_InvalidCustException, java.rmi.RemoteException, javax.ejb.EJBException, com.tibco.ejb.support.AEEjbException {

// add method implementation here}


Schema Class


public class BRFCKNA1 implements javax.resource.cci.Record, java.io.Serializable



{public BRFCKNA1(){


}


String m_KUNNR;String m_NAME1;


}


}


}


}................}


Exception Data Class

A class generated for InvalidCustExceptionData that contains the attributes corresponding to fields defined in the Exception class and get and set methods for these attributes.

This is an additional class created for the Exception class:

public class RFC_CUSTOMER_GET_InvalidCustException extends AEEjbException{

public RFC_CUSTOMER_GET_InvalidCustException(String name, Object data){



super(name,data);}public

RFC_CUSTOMER_GET_InvalidCustException(AEResourceException aer){

super(aer);}

}

An instance of this class is displayed when an exception is thrown by the request-response server class.





}}





<ejb-jar><description /><display-name>TIB Integration Client Beans</display-name><small-icon /><large-icon /><enterprise-beans>

<session><description>EJB client for operations on TIBCO AE Class

/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema.aeschema/Classes/RFC_CUSTOMER_GET</description>

<display-name>RFC_CUSTOMER_GETBean</display-name><small-icon></small-icon><large-icon></large-icon><ejb-name>RFC_CUSTOMER_GETBean</ejb-name>



<home>com.tibco.ae.SAP_EXAMPLE.SAPAdapterSchema.RFC_CUSTOMER_GETHome</home><remote>com.tibco.ae.SAP_EXAMPLE.SAPAdapterSchema.RFC_CUSTOMER_GET</remote><ejb-class>com.tibco.ae.SAP_EXAMPLE.SAPAdapterSchema.RFC_CUSTOMER_GETBean</ejb-class>

<session-type>Stateless</session-type><transaction-type>Bean</transaction-type><resource-ref>

<description>Reference to TIBCO AEConnector</description>

<res-ref-name>tibco/aeconnector</res-ref-name><res-type>com.tibco.ejb.connector.AE3ConnectionFactory</res-type>



</ejb-jar>



1. To compile the Java code, set classpath to include <TRA_HOME>\lib\TIBCOrt.jar;<ADEJB_HOME>\lib\EjbSupport.jar;<ADEJB_HOME>\lib\GlBeansSupport.jar and a jar file that contains J2EE interfaces. For example, <J2EE_RI_HOME>\lib\j2ee.jar.




To make a jar file, run the following command:jar -cvf ExampleBeans.jar com META-INF




Generating Glue Beans to Enable Outbound Communication

To enable inbound communication, the following can be generated:• Glue Beans for the Publication Service

• Glue Beans for the Request-Response Invocation Service

Glue Beans for the Publication ServiceThe typical glue bean code generated for a publication service, using an ActiveEnterprise schema class ae/SAP_EXAMPLES/SAPAdapterSchema/BRFCKNA1 and the package root com.tibco. contains the following files:• EJBHome class —

com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.Publish_BRFCKNA1Home

.java

• EJBObject class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.Publish_BRFCKNA1.jav

a

• Stateless Session Bean — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.Publish_BRFCKNA1Bean

.java



EJBHome Class


public interface Publish_BRFCKNA1Home extends EJBHome {

public Publish_BRFCKNA1 create() throwsRemoteException, CreateException;

}

EJBObject Class

This class contains the abstract method publish with the following signature:

public interface Publish_BRFCKNA1 extends javax.ejb.EJBObject{


Generating Glue Beans to Enable Outbound Communication | 311

public void publish (com.tibco.publish.ae.SAP_EXAMPLE.SAPAdapterSchema.BRFCKNA1 publishObj) throws java.rmi.RemoteException,javax.ejb.EJBException;

}


This contains the following implementation:

public void ejbCreate() throws CreateException{

try {publisher = new PublishSupport(FACTORY_REF,

m_ejbContext.getEnvironment());} catch (RuntimeException rex) {

// The app server does not support deprecated call to getEnvironment()

publisher = new PublishSupport(FACTORY_REF);}try {

// Prepare to publish an object on the TIB (r). The first param// is the endpoint URL (can be a subscriber or publisher). The// second param is the class definition of the object to be pub-// to be published.

publisher.prepare("/tibco/public/endpoint/adapter/Connector/RPC/EjbAdpPublisher", "/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema/BRFCKNA1", InteractionSpec.SYNC_SEND_RECEIVE);

} catch (ResourceException ex) {throw new CreateException(ex.getMessage());

}}

The ejbCreate method creates an instance of PublishSupport, whose constructor accepts a string as an argument. The string is the JNDI name with which the connection factory is registered. The constructor of PublishSupport looks up the Connection Factory and creates a connection.

Additionally in ejbCreate, certain other parameters specific to TIBCO world, such as endpoint reference and schema class are set.

public void publish (com.tibco.publish.ae.SAP_EXAMPLE.SAPAdapterSchema.BRFCKNA1 publishObj) throws java.rmi.RemoteException,javax.ejb.EJBException {

try {publisher.publish(publishObj);}



catch(ResourceException ex) {throw new EJBException(ex.getMessage());

}}

This is the method that causes the publication of publishObj using the endpoint reference set during the construction of PublishSupport.

Schema Class



public BRFCKNA1(){


}




}


}


}


}................

}





The deployment descriptor, ejb-jar.xml, is EJB 1.1, 2.0, or 2.1 compliant based on the option selected. A typical ejb-jar.xml generated by the Publis code generator appears as follows:


<session><description>EJB publisher for TIBCO AE Class

/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema/BRFCKNA1</description>

<display-name>Publish_BRFCKNA1Bean</display-name><small-icon></small-icon><large-icon></large-icon><ejb-name>Publish_BRFCKNA1Bean</ejb-name>

<home>com.tibco.publish.ae.SAP_EXAMPLE.SAPAdapterSchema.Publish_BRFCKNA1Home</home><remote>com.tibco.publish.ae.SAP_EXAMPLE.SAPAdapterSchema.Publish_BRFCKNA1</remote><ejb-class>com.tibco.publish.ae.SAP_EXAMPLE.SAPAdapterSchema.Publish_BRFCKNA1Bean</ejb-class>


<resource-ref><description>Reference to TIBCO AEConnector</description><res-ref-name>tibco/aeconnector</res-ref-name>

<res-type>com.tibco.ejb.connector.AE3ConnectionFactory</res-type>



</ejb-jar>

Apart from the bean declaration, this file also contains a resource-ref node that points to the connection factory JNDI name. Therefore, the code generated for the publication service is complete in itself, and requires no further modifications.


To generate glue beans:

1. To compile the java code, set the classpath to include <TRA_HOME>\lib\TIBCOrt.jar;<ADEJB_HOME>\lib\EjbSupport.jar;<ADEJB_HOME>\lib\GlBeansSupport.jar and a jar file that contains J2EE interfaces. For example, <J2EE_RI_HOME>\lib\j2ee.jar.





Before you generate the jar file for the glue beans, you must generate the application server-specific deployment xml. For details on generating the deployment descriptor, see the documentation for the application server you are using.


This will generate the glue beans jar file for deployment.

Glue Beans for the Request-Response Invocation ServiceThe typical glue bean code generated for a request-response invocation service, using an ActiveEnterprise operation class ae/SAP_EXAMPLES/SAPAdapterSchema/RFC_CUSTOMER_GET with the operation RFC_CUSTOMER_GET which in turn uses the schema class BRFKCNA1, displays InvalidCustException, and has the package root as com.tibco contains the following files:• EJBHome class —

com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GETHome

.java

• EJBObject class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GET.jav

a

• Stateless Session Bean — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GETBean

.java


• Operation schema class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GET.jav

a

• Exception class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.RFC_CUSTOMER_GET_Inv

alidCustException.java

• Exception data class — com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.InvalidCustException

Data.java



• Attribute Detail Class com.tibco.ae.SAP_EXAMPLE.SAPAdapterSchema.AttributeDetails.java


EJBHome Class


public interface RFC_CUSTOMER_GETHome extends EJBHome {

public RFC_CUSTOMER_GET create() throwsRemoteException, CreateException;

}

EJBObject Class

This class contains the following methods:

public interface RFC_CUSTOMER_GET extends javax.ejb.EJBObject{

public String getEndpointName() throws java.rmi.RemoteException;

public String getAEClassName() throws java.rmi.RemoteException;

public java.util.Map RFC_CUSTOMER_GET1 (com.tibco.ae.SAP_EXAMPLES.SAPAdapterSchema.BRFCKNA1)throws RFC_CUSTOMER_GET_InvalidCustException, java.rmi.RemoteException, javax.ejb.EJBException,

com.tibco.ejb.support.AEEjbException;

}

The method name is changed to RFC_CUSTOMER_GET1 because it matches with the operation class name. Therefore, if the same name is used, the method name is treated as a constructor. The number 1 is appended to the method name. It also contains a method for obtaining the endPointName and AEClass.


This class contains the following method:

public void ejbCreate() throws CreateException{

try {rpcs = new RPCSupport(FACTORY_REF,

m_ejbContext.getEnvironment());}catch(RuntimeException rex){



rpcs = new RPCSupport(FACTORY_REF);}

}

The ejbCreate method creates an instance of RPCSupport, which is a helper for the request-response invocation operations. FACTORY_REF, the JNDI name with which the Connection Factory is registered, is passed to the constructor of the RPCSupport class. The constructor of RPCSupport looks up the ConnectionFactory and creates a connection.

public java.util.Map RFC_CUSTOMER_GET1 (String KUNNR, String NAME1, java.util.List CUSTOMER_T)throws java.rmi.RemoteException, javax.ejb.EJBException, com.tibco.ejb.support.AEEjbException {

// Prepare to call a remote service. The first parameter is the// endpoint URL to call, the second is the method name.rpcs.prepare(getEndpointName(), getAEClassName(),

"RFC_CUSTOMER_GET", InteractionSpec.SYNC_SEND_RECEIVE);rpcs.addParam("KUNNR", KUNNR);rpcs.addParam("NAME1", NAME1);IndexedRecord ir2 = new IndexedRecordImpl(CUSTOMER_T);ir2.setRecordName("CUSTOMER_T");rpcs.addParam("CUSTOMER_T", ir2);boolean ok = rpcs.execute();if (rpcs !=null) rpcs.cleanup();return rpcs.getOutputs();

}

This is the main business method of the session bean that is fully implemented by the code generator to call the request-response server service and return the results obtained from it.

Schema Class



public BRFCKNA1(){

m_recordName = "BRFCKNA1";m_recordShortDescription = "container for instance of TIBCO ActiveEnterprise class

/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema/BRFCKNA1";

}

String m_recordName;



String m_recordShortDescription;



}


}


}


}................}


Exception Data Class

A class generated for InvalidCustExceptionData that contains the attributes corresponding to fields defined in the Exception class and get and set methods for these attributes.

This is an additional class created for the Exception class:

public class RFC_CUSTOMER_GET_InvalidCustException extends AEEjbException{

public RFC_CUSTOMER_GET_InvalidCustException(String name, Object data)

{super(name,data);

}public

RFC_CUSTOMER_GET_InvalidCustException(AEResourceException aer){

super(aer);}

}

An instance of this class is displayed when an exception is thrown by the request-response server class.







}}






<session><description>EJB client for operations on TIBCO AE Class

/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema.aeschema/Classes/RFC_CUSTOMER_GET</description>

<display-name>RFC_CUSTOMER_GETBean</display-name><small-icon></small-icon><large-icon></large-icon><ejb-name>RFC_CUSTOMER_GETBean</ejb-name>

<home>com.tibco.rpcclient.ae.SAP_EXAMPLE.SAPAdapterSchema.RFC_CUSTOMER_GETHome</home><remote>com.tibco.rpcclient.ae.SAP_EXAMPLE.SAPAdapterSchema.RFC_CUSTOMER_GET</remote><ejb-class>com.tibco.rpcclient.ae.SAP_EXAMPLE.SAPAdapterSchema.RFC_CUSTOMER_GETBean</ejb-class>


<resource-ref><description>Reference to TIBCO AEConnector</description><res-ref-name>tibco/aeconnector</res-ref-name>



<res-type>com.tibco.ejb.connector.AE3ConnectionFactory</res-typ e><res-auth>Container</res-auth>

</resource-ref></session>


</ejb-jar>

Apart from the bean declaration the ejb-jar.xml file contains a resource-ref node that points to the connection factory JNDI name. Therefore, the code generated for the request-response invocation service is complete and requires no further modifications.



1. To compile the Java code, set classpath to include <TRA_HOME>\lib\TIBCOrt.jar;<ADEJB_HOME>\lib\EjbSupport.jar; <ADEJB_HOME>\lib\GlBeansSupport.jar and a jar file that contains J2EE interfaces. For example, <J2EE_RI_HOME>\lib\j2ee.jar.








Using the Generated Glue Beans

This section explains how to use the generated glue beans with the adapter services.

Using the Generated Glue Beans with the Publication ServiceFor details on deploying the generated glue beans, see the Preparing the Test or Example Beans and Deploying the Test or Example Beans sections in the TIBCO Adapter for EJB Examples Guide.

The glue beans generated by the code generator for the publication service have the complete code to publish data to the TIBCO endpoint that they were generated for. Therefore, to trigger the publication, only the publish method of the bean needs to be called and passed to the instance of the generated class that corresponds to the ActiveEnterprise schema class.

The following example shows code that triggers the publication service:

// Obtain the home interface.Publish_BRFCKNA1Home home = null;

Context ctx = new InitialContext();

// Use JNDI to look up the client bean.home = (Publish_BRFCKNA1Home)PortableRemoteObject.narrow(

ctx.lookup(JNDIName),Publish_BRFCKNA1Home.class);

// Obtain the remote interface.Publish_BRFCKNA1 publishBeanInterface = null;publishBeanInterface = home.create();

BRFCKNA1 cust = new BRFCKNA1();cust.setKUNNR("1235");cust.setNAME1("Acme Inc.");cust.setANRED("");cust.setPFACH("");cust.setSTRAS("132 Shady Glen Rd.");cust.setPSTLZ("95124");cust.setORT01("Menlo Park");cust.setTELF1("650-275-2323");cust.setTELFX("650-275-2330");publishBeanInterface.publish(cust);

The example code shown above does the following:• It looks up the home interface of the publish glue bean.

• It then calls a create method that creates an instance of the EJBObject class.


Using the Generated Glue Beans | 321

• Next, it creates an instance of the Java class that is generated corresponding to the ActiveEnterprise schema.

• Finally, it calls the publish function and passes the instance of the schema class to it.

Using the Generated Glue Beans with the Subscription ServiceFor details on deploying the generated glue beans, see the Preparing the Test or Example Beans and Deploying the Test or Example Beans sections in the TIBCO Adapter for EJB Examples Guide.

The glue beans generated by the code generator for the subscription service have an empty method called subscribe. You must add business logic to this method to be able to call another set of beans.

When you start the subscription service after starting the adapter, it performs the initialization required to start an ActiveEnterprise subscriber. Additionally, based on the JNDI Home reference and EJBHome class stored in the repository, the subscription service looks up the EJBHome class. If the service is unable to locate the home class, it will not start.

When the subscriber receives a message, it calls the subscribe method on the glue bean.

Using the Generated Glue Beans with the Request-Response Invocation Service

For details on deploying the generated glue beans, see the Preparing the Test or Example Beans and Deploying the Test or Example Beans sections in the TIBCO Adapter for EJB Examples Guide.

The glue beans generated by the code generator for the request-response invocation service have the complete code to invoke the beans that they were generated for.

The following example shows code that triggers the request-response invocation service:

// Obtain the home interface.RFC_CUSTOMER_GETHome_Connector home = null;try

Context ctx = new InitialContext();

// Use JNDI to look up the client bean.home = (RFC_CUSTOMER_GETHome_Connector)PortableRemoteObject.narrow(



ctx.lookup(JNDIName),RFC_CUSTOMER_GETHome_Connector.class);

// Obtain the remote interface.RFC_CUSTOMER_GET_Connector getCustInterface = null;getCustInterface = home.create();

Map result =getCustInterface.RFC_CUSTOMER_GET1(custId,name,new ArrayList());Object retVal = result.get("_returnValue");System.out.println("Return value = " + retVal);Object outParam = result.get("CUSTOMER_T");List custs = (List)outParam;Map cust = (Map)custs.get(0);if (cust == null){

System.err.println("Warning: customer was null");}else{

System.out.println("Customer data = " + cust.toString());}

//If you have set the flag to convert the sequence to actual object, the object can be //typecasted to actual java object. //For example,//BRFCKNA1 cust = (BRFCKNA1) custs.get(0);

The example code shown above does the following:• It looks up the home interface of the request-response invocation glue bean.

• It then calls a create method on it that will create an instance of the EJBObject class. During the create call, the corresponding RPCSupport class is initialized with the endPoint, schema class, and the operation name.

• Finally, the call to invoke the method on the bean results in the actual request-response invocation call.

Using the Generated Glue Beans with the Request-Response Server ServiceFor details on deploying the generated glue beans, see the Preparing the Test or Example Beans and Deploying the Test or Example Beans sections in the TIBCO Adapter for EJB Examples Guide.

The glue beans generated by the code generator for the request-response server service have empty method implementations for all the methods that are defined in the ActiveEnterprise schema for the service. To use these methods to call another set of beans, you must add business logic to these methods.


Using the Generated Glue Beans | 323

When the request-response server service is started by starting the adapter, it performs the initialization required to start an ActiveEnterprise request-response server. Additionally, based on the JNDI Home reference and EJBHome class stored in the repository, it looks up the EJBHome class. If the service is unable to locate the home class, the service does not start. When the request-response server receives a call, it calls the corresponding method on the glue bean and then returns the result.




| 325

Appendix A Trace Messages

This appendix explains the trace messages that are logged to a location specified at configuration time.

Topics


• Trace Message Fields, page 328

• Status Messages, page 331


326 | Appendix A Trace Messages

Overview

Trace messages provide information about adapter activities. The messages are logged to the console where the runtime adapter was started and to a log file. Trace messages can also be redirected to the TIBCO Hawk Display application, or sent to other applications using the TIBCO Rendezvous transport.

Each trace message can include the following fields:

<Timestamp> <Adapter Identifier> <Role> <Category> <Status Code> <Tracking Identifier>

The above fields are explained in Trace Message Fields on page 328. The following diagram shows an example trace message and calls out the fields.

Example Trace Messages

The following trace messages were written during a session where TIBCO Adapter for EJB received a message from a TIBCO ActiveEnterprise application, then processed the message.

The first message indicates that TIBCO Adapter for EJB has started. The timestamp indicates when the adapter started, and the role indicates that the trace message is informational, which means the activity is normal for the adapter. The category is identified, and the corresponding status code is displayed. The status code indicates that the adapter started successfully.

2003 Jun 04 18:25:28:171 GMT +5 Subscriber Info [Adapter] AEEJB-000037"TIBCO Adapter for EJB is ready"

The next set of trace messages indicates the adapter received a message that was sent on TIBCO Rendezvous transport. The mzh0ZH7MB6tifUa3/Mzzw4Kkzzw# tracking identifier included in the trace message uniquely identifies the message. The TIBCO ActiveEnterprise application from which the message originated provided the identifier.

2003 Jun. 18:25:28:171 GMT +5

EjbAdapter.EjbAdapterConfiguration Info [Adapter]

AEEJB-000526 Message: RV Transport Data Event Received

tracking=#mzh0ZH7MB6tifUa3/Mzzw4Kkzzw#

Timestamp

Adapter Identifier Role Category

Status Code

Tracking Identifier


Overview | 327

2003 Jun 04 18:25:42:041 GMT +5 Subscriber Debug [Connector/Adapter]AEEJB-000526 "Message: RV Transport Data Event received"2003 Jun 04 18:25:42:101 GMT +5 Subscriber Debug [Adapter] AEEJB-000514

"Subscriber eventhandler received a message :com.tibco.subscribe.ae.SAP_EXAMPLE.SAPAdapterSchema.BRFCKNA1@10ffb38"tracking=#mzh0ZH7MB6tifUa3/Mzzw4Kkzzw#

The final trace messages indicate the message has been executed in the EJB at the application server, which completes the adapter’s interaction with the object.

2003 Jun 04 18:25:42:692 GMT +5 Subscriber Debug [Adapter] AEEJB-000515"Bean Method invocation was successful!"tracking=#IdHJUOTECn5aQk9P4uzzwDskzzw#2002 Jun 04 18:25:42:692 GMT +5 Subscriber Info [Adapter] AEEJB-510013"Message acknowledgement sent"



Trace Message Fields

Each trace message includes the following fields:

Table 14 Tracing Fields

Field Name Description

Timestamp Timestamp of occurrence. For example, 2003 Feb 22 20:14:51:718 GMT -8.

Adapter Identifier

Name of the adapter that wrote the trace message. This is a combination of the adapter acronym and adapter instance name. For example, the application identifier, ADEJB.publisher1 identifies a TIBCO Adapter for EJB service named publisher1.

Role A role can be:

• Info. Indicates normal adapter operation. No action is necessary. A tracing message tagged with Info indicates that a significant processing step was reached and has been logged for tracking or auditing purposes. Only info messages preceding a tracking identifier are considered significant steps.

• Warn. An abnormal condition was found. Processing will continue, but special attention from an administrator is recommended.

• Error. An unrecoverable error occurred. Depending on the error severity, the adapter may continue with the next operation or may stop altogether.

• Debug. A developer-defined tracing message. In normal operating conditions, debug messages should not display.

When configuring the adapter you define what roles should or should not be logged. For example, you may decide not to log Info roles to increase performance.


Trace Message Fields | 329

Category One of the following:

• Adapter. The adapter is processing an event.

• Application. The adapter is interacting with the application server.

• Configuration. The adapter is reading configuration information.

• Database. The adapter is interacting with a database.

• Metadata. The adapter is retrieving metadata from the application server.

• Palette. The adapter is interacting with the palette.

• Publisher Service. The publication service is reporting this trace message.

• Request-Response Client Service. The request-response invocation service is reporting this trace message.

• Request-Response Server. The request-response service is reporting this trace message.

• Shutdown. The adapter is shutting down.

• Startup. The adapter is starting.

• Subscription Service. The subscription service is reporting this trace message.

• System. This category is not linked to a specific event process. The trace message may be related to a Microsoft Windows service related message, memory allocation, file system error, and so on.

• TibRvComm. The adapter is communicating with TIBCO Rendezvous.

• XML. The adapter is parsing XML documents.

Status Code Unique code for the message and description. Status codes are identified by a unique number and description. If a trace message includes an error or warn role, the status code documentation includes a resolution. See Status Messages on page 331 for details.





Tracking Identifier

A unique identifier that is “stamped” on each message by the originating adapter. The tracking identifier remains in effect from a message’s beginning to its completion as it is exchanged by TIBCO-enabled applications. If the adapter is the termination point of the message, the tracking identifier is not displayed in the trace message.

You cannot modify the tracking identifier format or configure what information is displayed.




Status Messages | 331

Status Messages

This section lists the following:

• New Status Messages

• Old Status Messages

You can configure the adapter to display old status messages by setting the -system:traceOldMessages property to TRUE in the .tra file. By default, this property is set to FALSE and the adapter displays new status messages.

New Status Messages

Status Code Role Category Resolution

AEEJB-000001 Error while invoking the Bean Method: <method name> with the message <reason>

errorRole Adapter Make sure that the application server is running, the bean has been deployed, and the method exists in the bean

AEEJB-000002 RPC: Error while sending reply with the message <reason>

errorRole Adapter Make sure that the reply sent to the adapter has the correct data types and that the reply schema is valid

AEEJB-000003 Invalid Input with the message <description of invalid input>.

errorRole Adapter This error indicates a mismatch between the data types and the corresponding data. Check that the reply sent to the adapter has the correct data types

AEEJB-000004 No configured EJBs found for the adapter instance: <instance name>.

errorRole Adapter Check the Jabs that you have deployed in the application server. Then, add the EJB configuration information to the adapter instance



AEEJB-000005 Adapter Properties: AEServer named <endpoint name> is not defined in the adapter instance.

errorRole Adapter Make sure that either the Server name matches a name in the adapter instance configuration. If the Server name does not exist in the adapter instance configuration, add it

AEEJB-000006 Adapter Properties: AEClass <class name> is not defined in repository

errorRole Adapter Make sure that either the AEClass name matches a name in the adapter configuration. If the AEClass name does not exist in the adapter instance configuration, add it

AEEJB-000007 Provided endpoint: <endpoint> is of type: <type of endpoint>. <endpoint type> endpoint is required for <service type> service

errorRole Adapter Make sure that the endpoint provided matches with the service configured. Only subscriber and request-response server endpoints are permitted for this service

AEEJB-000008 Subscriber activation failed with the message <reason>.

errorRole Adapter Anomalies in parameters such as the server name or protocol may cause this error. Make sure that the server properties configured in the repository are accurate

AEEJB-000009 Exception occurred in the event handler: with the message <error description>.

errorRole Adapter Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the subscription service. For details on configuration of a subscription service, see Subscription Service Options in the TIBCO Adapter for EJB User’s Guide.




AEEJB-000011 Error occurred while invocation of outbound RPC with <direction>: <error>.

errorRole Connector Make sure that the reply sent to the adapter has the correct data types and the reply schema is valid

AEEJB-000012 SDK Exception in execute()

errorRole Connector(Interaction)

Make sure that the reply sent to the adapter has the correct data types and the reply schema is valid

AEEJB-000013 Reply from TIBCO Application for operation <operation name> contains exception

infoRole Connector Indicates normal adapter operations. No action necessary.

AEEJB-000014 SDK Runtime exception occurred <reason>.

errorRole Connector Some session properties may be missing, incorrectly configured, or corrupted and are therefore unreadable. Make sure that the session properties are accurate

AEEJB-000015 Publisher endpoint <endpoint name> associated with the application is null

errorRole Connector Configure a valid publisher endpoint in the repository

AEEJB-000016 Error: The data to be published is null

errorRole Connector Check that the data received from the EJB application is not null

AEEJB-000017 Warning: missing value for parameter <parameter name>.

warnRole Connector(RecordToSDKConversion)

Check that values are set for all parameters appropriately based on the inbound and outbound request-response scenario




AEEJB-000018 Timeout Exception for Operation: <operation name> Server did not respond within <time> ms

errorRole Connector Make sure that the application server is running and the bean has been deployed. If both are verified, increase the reply timeout value

AEEJB-000019 Unsupported Session Name: <name> type: <type>.

errorRole Connector The configured session is an invalid type for this service. Select another type of session

AEEJB-000020 Unsupported Endpoint Name: <name> type: <type>.

errorRole Connector The configured endpoint is an invalid type for this service. Select another type of endpoint

AEEJB-000021 Publication of scalar objects is not supported

errorRole Connector Make sure that you are publishing only complex, MData-type objects

AEEJB-000022 Received valid reply Record from TIBCO Application

infoRole Connector(Interaction)

Indicates normal adapter operations. No action necessary.

AEEJB-000023 Adding key <key name> to output mapped record



AEEJB-000024 Return value from TIBCO Application is null



AEEJB-000025 Return value from TIBCO Application is: <value>.






AEEJB-000026 Error while converting Record type to SDK type with the message <error>.

errorRole Adapter This error is a catch-all for some error(s) that may have occurred earlier. Please check your repository configuration and ensure that the schema is correct and matches the data types being converted

AEEJB-000027 Error while creating Interaction: <error message>.

errorRole Connector Make sure that you have a valid repository instance that the connector can use. Alternatively, your machine may be running low on memory. Close some applications to free up the memory

AEEJB-000028 Subscriber endpoint <endpoint name> could not be located in the adapter instance

errorRole Adapter Configure a valid subscriber endpoint in the repository

AEEJB-000029 Data published successfully on Subject name: <subject name>.


AEEJB-000030 Warning: Attempting to set value for the out parameter: <parameter name>, Details: <reason>

warnRole Connector(SdkInterface)

AEEJB-000031 Warning advisory: <advisory warning information>.

warnRole Adapter

AEEJB-000032 Error advisory: <advisory error information>.

errorRole Adapter Make sure that you have a valid repository instance that the adapter can use, and that the data in it is not corrupted. Alternatively, your machine may be running low on memory. Close some applications to free up the memory




AEEJB-000033 Error creating client request object for: <reason>.


AEEJB-000034 Connection failed: Unable to connect to Application Server: <reason>.

errorRole Adapter Make sure that the application server is running and that the bean has been successfully deployed. Also, make sure that the connection parameters to the application server and bean are valid

AEEJB-000035 EJB lookup failed: Unable to get the Remote object: <reason>.

errorRole Adapter Make sure that the application server is running and that the bean has been successfully deployed. Also, Make sure that the connection parameters to the application server and bean are valid

AEEJB-000036 TIBCO Adapter for EJB initialization failed: <reason>.

errorRole Adapter This error is a catch-all for some error(s) that may have occurred earlier. Make sure that the EJBs and endpoints are correctly configured in the repository, a valid instance of the repository is running, and that you have enough free memory to create new objects such as dispatchers

AEEJB-000037 TIBCO Adapter for EJB is ready.

infoRole Adapter Indicates normal adapter operations. No action necessary.

AEEJB-000038 Dispatcher count = <number of dispatchers>.


AEEJB-000039 Advisory Information: <advisory information>





AEEJB-000040 Loaded Custom Hawk MicroAgents for <application name>.


AEEJB-000041 Startup Error. Unable to create a connection with the target application <application name> using connection parameters <parameters used> and the target application error is <error displayed>.

errorRole Adapter Make sure that the application server is running and that the bean has been successfully deployed. Also, make sure that the connection parameters to the application server and bean are valid

AEEJB-000042 Custom Hawk micro agents not found in <repository name>

warnRole Adapter Make sure that the correct TIBCO Hawk Microagents are configured in the repository. Also, check the TIBCO Hawk arguments passed to adapter

AEEJB-000043 Notification of unsolicited messages sent to <application name>


AEEJB-000044 Error occurred while sending a notification to Hawk. <error>

errorRole Adapter Make sure that the correct TIBCO Hawk Microagents are configured in the repository. Also, check the TIBCO Hawk arguments passed to adapter

AEEJB-000045 Error closing connection <connection> with the application server with the message <message>

errorRole Adapter This is typically not a fatal error. However, ensure that the application server and up and that the bean has been deployed




AEEJB-000046 Error closing interaction <interaction type> with the bean method with the message <message>

errorRole Adapter This is typically not a fatal error. However, ensure that the application server is running and that the bean has been deployed

AEEJB-000047 Exception occurred when setting the value for attribute <attribute name> in the method <method name> in the <direction> direction with the message <message>

errorRole Adapter Please check your repository configuration and ensure that the attribute exists

AEEJB-000048 Exception retrieving attribute <attribute name> of class <class name> with the message <message>

warnRole Adapter Please check your repository configuration and ensure that the attribute exists

AEEJB-000049 Exception retrieving data for member <name> of union <union name> with the message <message>

warnRole Adapter Please check your repository configuration and ensure that the attribute exists

AEEJB-000050 Exception while loading class <class name> in the method in the <direction> direction with the message <message>

warnRole Adapter Ensure that the application server is running and that the bean has been deployed. Please check your repository configuration and ensure that the class name exists

AEEJB-000051 Exception while invoking method <method name> on class <class name> using attribute <attribute name> with the message <message>

warnRole Adapter Ensure that the application server is running and that the bean has been deployed. Please check your repository configuration and ensure that the class and method names exist




AEEJB-000052 Exception while creating an indexed record using sequence <sequence> and encoding <encoding type> with the message <message>

warnRole Adapter Please check your repository configuration and ensure that the schema is correct and the encoding value is proper

AEEJB-000053 Possible error while converting SDK type to Record type with the message <message>


AEEJB-000054 Shutdown subscriber activated <name>


AEEJB-000055 No shutdown listeners configured in the repository for <name>


AEEJB-000056 No service with name <service> configured. Check the Service name passed.

errorRole Adapter Check the Service name passed.

AEEJB-000058 Value of the perfMon flag is <flag>.


AEEJB-000059 Application was successfully shutdown.


AEEJB-000060 Overridden Global variable: <Global Variable> with value: <value>.





AEEJB-000061 No <field> field present in the exceptions thrown by operation <operation>, hence exception will not be returned to client

warnRole Adapter Please check the configuration and ensure that the field name is attached to the operation.

AEEJB-000062 Field <field (adEJBSystemException)> present in the exceptions thrown by operation <operation> does not point to <exception class>(adEJBSystemException)>, hence exception will not be returned to client

warnRole Adapter Please check the configuration and ensure that the field(adEJBSystemException) present in the exceptions thrown by the operation does point to the system exception class (adEJBSystemException).

AEEJB-000063 Field <field> is not present in <exception class> exception class for operation <operation>, hence exception will not be returned to client.

warnRole Adapter Check for presence of attributes which were expected to be filled up in the exception class.

AEEJB-000064 Exception occurred during RPC Operation <operation>, however Adapter variable adejb.ThrowAdEJBSystemException is set to false, hence exception will not be returned to client

warnRole Adapter Set the value of the variable to TRUE, in the configuration files. This variable needs to be set in the corresponding TRA files.

AEEJB-000065 Type of exception thrown is /tibco/public/class/ae/adEJB/ejb/adEJBSystemException, but adejb.ThrowAdEJBSystemException flag is set to false, hence the exception will be sent back as AEEjbException.

warnRole Connector Set the value of the flag adejb.ThrowAdEJBSystemException to TRUE in <ADEJB_HOME>/bin/connector.tra




AEEJB-000066 Exception occurred during RPC Operation <operation>, however Adapter variable adejb.ThrowAdEJBSystemException has not been set, hence exception will not be returned to client

warnRole Adapter Set the variable adejb.ThrowAdEJBSystemException to TRUE in the corresponding tra file that is used by the adapter process.

AEEJB-000067 Type of exception thrown is /tibco/public/class/ae/adEJB/ejb/adEJBSystemException, however Adapter variable adejb.ThrowAdEJBSystemException has not been set, hence the exception will be sent back as AEEjbException

warnRole Connector Set the value of the flag adejb.ThrowAdEJBSystemException to TRUE in <ADEJB_HOME>/bin/connector.tra

AEEJB-000068 Value of the sequenceTypeToActualObject flag is <flag>

infoRole Adapter/Connector


AEEJB-000069 Work is rejected by the application server. The event type is %1. Subscriber name is %2. Destination is %3. Exception details are %4.

errorRole Connector EJB adapter during the inbound processing is using the work management contract and while handing over the event received error. Please see the exception details and take corrective action.

AEEJB-000070 Work submitted is completed by the application server. The event type is %1. Subscriber name is %2. Destination is %3. Exception details are %4.

infoRole Connector Indicates the adapter works as expected. No action is required.

AEEJB-000071 Work submitted is accepted by the application server. The event type is %1. Subscriber name is %2. Destination is %3. Exception details are %4.





AEEJB-000072 Error occured while deactivating the endpoint for end point server %1. The error message is %2.

infoRole Connector Error appears if MDBs cannot be stopped by the application server. Typically MDBs stop when you shut down the application server.

the adapter deployed into an application server is about to shut down or the application server is shutting down, the MDBs registered with the adapter are being stopped. Perform the corrective action.

AEEJB-000073 There are no end point MDBs registered as listener for RPCServer %1 and operation %2.

errorRole Connector Indicates that none of the MDBs are attached to the adapter to process incoming messages.

Deploy atleast one MDB to complete the processing of inbound TIBCO Rendezvous or EMS message.

AEEJB-000074 Shutdown for RPCServer %1 and operation %2 is complete.


AEEJB-000075 MDB Endpoint deactivation request for %1 inbound server received.


AEEJB-000076 MDB Endpoint deactivation request for %1 inbound server received.


AEEJB-000077 No listeners found for inbound server %1 hence suspending the inbound server.

infoRole Connector The adapter does not find any MDBs registered as a listener. Therefore it suspends the subscriber or the RPC server.




AEEJB-000078 One MDB endpoint activated for %1 inbound server.

infoRole Connector Is an informational message which indicates that MDB is bound to the adapter for listening the messages.

AEEJB-000079 Exception stack trace is %1.


Prints the exception stack trace. No corrective action is required.

AEEJB-000530 Naming Exception caught while loading the connector using the JNDI factory reference. The factory reference object contains <details>. Message is <message>

errorRole Adapter/Connector

Ensure that the JNDI name and factory reference object configured in the repository, bean and deployment descriptor are correct. Also ensure that the application server is running and the bean has been correctly deployed

AEEJB-000531 Naming Exception caught while loading the connector using the JNDI factory reference. The factory reference object contains <details> and the environment bean properties contain <details>. Message is <message>

errorRole Adapter/Connector

Ensure that the JNDI name and factory reference object configured in the repository, bean and deployment descriptor are correct. Also ensure that the application server is running and the bean has been correctly deployed

AEEJB-000532 The Generate Verbose Log flag in the repository is configured to <configuration setting>



AEEJB-000533 Trace messages will be logged in <format name> format






AEEJB-000534 Receipt of advisory messages has been set to <setting>



AEEJB-510001 Error while invoking the Bean Method: <method name> with the message <reason>.

errorRole Adapter Make sure that the application server is running, the bean has been deployed, and the method exists in the bean

AEEJB-510002 No configured EJBs could be found or initialized for the adapter instance: <instance name>.

errorRole Adapter Ensure the validity and deployment of the EJBs in the application server. Add the EJB configuration information to the adapter instance if necessary

AEEJB-510003 Provided endpoint: <endpoint name> is of type: <endpoint type>. <endpoint service> endpoint is required for <endpoint service> service

errorRole Adapter Make sure that the endpoint provided matches with the service configured. Only subscriber and request-response server endpoints are permitted for this service


errorRole Adapter Make sure that the reply sent to the adapter has the correct data types and the reply schema is valid

AEEJB-510005 SDK Runtime exception occurred with the message <error description>.

errorRole Connector Some session properties may be missing, incorrectly configured, or corrupted and are therefore unreadable. Make sure that the session properties are accurate

AEEJB-510006 Unsupported Session Name: <session name> type: <session type>.

errorRole Adapter The configured session is an invalid type for this service. Select another type of session




AEEJB-510007 Unsupported Endpoint Name: <endpoint name> type: <endpoint type>.

errorRole Adapter The configured endpoint is an invalid type for this service. Select another type of endpoint

AEEJB-510008 Error while converting Record type to SDK type with the message <error description>.


AEEJB-510009 Error while creating Interaction: <error description>.

errorRole Adapter Make sure that you have a valid repository instance that the connector can use. Alternatively, your machine may be running low on memory. Close some applications to free up the memory

AEEJB-510010 Error advisory: <error description>.


AEEJB-510011 EJB lookup failed: Unable to get the Remote object or bean: <error description>.

errorRole Adapter Make sure that the application server is running and that the bean has been successfully deployed with the correct JNDI name. Also, make sure that the connection parameters to the application server and bean are valid

AEEJB-510012 No auto confirm set for <service name>





AEEJB-510013 Message acknowledgement sent


AEEJB-510014 Exception occurred while getting the return value from Bean. It may not match with the configured return type of operation. The return class URL is <class URL>, the return value is <value> and the message is <reason>.

errorRole Adapter Please verify the return value of the bean matches the one configured in the repository

AEEJB-510015 The value for parameter <parameter name> cannot be sent to the TIBCO RPC Client, since the direction of the parameter is defined as IN in the operation <operation name>.

warnRole Adapter Please ensure that the direction matches the one specified in the operation configured in the repository

AEEJB-510016 The value for parameter <parameter name> cannot be sent to the TIBCO RPC Server, since the direction of the parameter is defined as OUT in the operation <operation name>.

warnRole Adapter Please ensure that the direction matches the one specified in the operation configured in the repository

AEEJB-510017 Error occurred while sending the reply parameter <parameter name> since it was not found in the operation <operation name>.

errorRole Adapter Please ensure that the parameter matches the one specified in the operation configured in the repository

AEEJB-510018 Error occurred while sending the reply parameter <parameter name> since it was not found in the operation <operation name>.

errorRole Adapter Please ensure that the parameter matches the one specified in the operation configured in the repository




AEEJB-890001 Suspending Subscriber <subscriber name>. Could not establish connection within <n> retries

warnRole Connection

AEEJB-890002 Error while attempting to suspend subscriber <subscriber name>

errorRole Connection Check the validity of the connection parameters. Anomalies in parameters such as the server name or protocol may cause this error. Make sure that the server properties configured in the repository are accurate. Also make sure that a valid subscriber endpoint has been configured

AEEJB-890003 An attempt was made to suspend <n> subscribers because a connection could not be re-established within <n> retries

warnRole Connection

AEEJB-890004 The subscriber <subscriber name> was activated after a connection was re-established

infoRole Connection Indicates normal adapter operations. No action necessary.

AEEJB-890005 Error while attempting to activate the subscriber <subscriber name> after a connection was re-established

errorRole Connection Check the validity of the connection parameters. Anomalies in parameters such as the server name or protocol may cause this error. Make sure that the server properties configured in the repository are accurate. Also make sure that a valid subscriber endpoint has been configured

AEEJB-890006 An attempt was made to activate <n> subscribers because a connection was re-established after <n> retries

warnRole Connection

AEEJB-890007 The Initial Context <context name> of the application server was retrieved successfully





AEEJB-890008 The class <class name> was successfully loaded


AEEJB-890009 The adapter received a <error type> error when attempting to get the InitialContext of the application server

warnRole Connection

AEEJB-890010 The adapter received a <error type> error when attempting to load the class <class name>.

warnRole Connection

AEEJB-890011 Successfully looked up the home interface <interface name> using the JNDI home <JNDI name> of the <class name> class


AEEJB-890012 A <error type> error occurred when looking up the home interface <interface name> using the JNDI home <JNDI name> of the <class name> class

warnRole Connection

AEEJB-890013 Successfully created the dynamic dispatcher using the home interface <interface name> and the method <method name>.


AEEJB-890014 An unidentified exception occurred when creating the dynamic dispatcher using the home interface <interface name> and the method <method name>.

warnRole Connection

AEEJB-890015 Successfully invoked on dynamic dispatcher which returned an object <name>.





AEEJB-890016 Received an <error description> exception when attempting to invoke a method on the dynamic dispatcher. The application server may not be responding

warnRole Connection

AEEJB-890017 Received an <error description> <class name> <exception name> exception when attempting to invoke a method on the dynamic dispatcher. The bean may not be responding

warnRole Connection

AEEJB-890018 The connection parameter <parameter name> has the value <value> in the repository


AEEJB-890019 The Connection Manager retried to contact the server/bean/method <number> times


AEEJB-890020 The Connection Manager received exception <name of exception> during attempt no. <number> to connect to the server with the message <message>.

warnRole Connection

AEEJB-910001 Startup Error. The tra file <file name> is missing

errorRole Startup Verify that the name and location of the tra file is correct. For details, see Starting and Stopping the Run-time Adapter in the TIBCO Adapter for EJB User’s Guide.

AEEJB-910002 Startup Error. The tra file <file name> specification is incorrect. Parameters <parameter list> missing and parameters <parameter list> have invalid values.

errorRole Startup Verify the specification of tra file. For details, Starting and Stopping the Run-time Adapter in the TIBCO Adapter for EJB User’s Guide.




AEEJB-910003 Startup Error. The command-line parameters: <list of command line parameters> has not been specified

errorRole Startup Specify the required command-line parameter. For details, see Starting and Stopping the Run-time Adapter in the TIBCO Adapter for EJB User’s Guide.

AEEJB-910004 Startup Error. SDK Exception <error description> occurred in the adapter initialization while creating the MAppProperties object. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Startup For Repository URL and COnfiguration URL specifications, see the SDK documentation

AEEJB-910005 Startup Error. SDK Error <error description> received on starting the adapter after initialization. The Repository URL is <respository URL> and the Configuration URL is <configuration URL>.

errorRole Startup Verify the repository settings. For details, see Startup Tab in the TIBCO Adapter for EJB User’s Guide.

AEEJB-910006 Startup Error. SDK Exception <error description> occurred while creating a shutdown listener with parameters <parameter list>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Startup Verify the repository settings for validity of configuration for the shut down listener. For details, see Starting and Stopping the Run-time Adapter in the TIBCO Adapter for EJB User’s Guide.

AEEJB-910010 Startup Error. Failed to load properties file containing trace messages from path <file path> for Adapter Instance <instance name>. Error Message <error description>.

errorRole Startup Verify that the locale is set to en_US on your machine




AEEJB-910012 Startup Error. Unable to create a Custom Hawk Micro Agent Named <agent name> used to <description>.

errorRole Startup Make sure that the Hawk Micro Agent is correctly configured in the repository. For details, see Monitoring Tab in the TIBCO Adapter for EJB User’s Guide.

AEEJB-910020 Startup warning. Failed to initialize the server <server URL> with the name <server name> and class name <class name>. The application name is <application name>, repository URL is <repository URL> and configuration URL is <configuration URL>.

warnRole Startup

AEEJB-910021 Successfully initialized <number> out of a possible <number> configured servers

infoRole Startup Indicates normal adapter operations. No action necessary.

AEEJB-910022 Service <service name> is connected to the application server <application server connection>


AEEJB-910023 Service <service name> is using the connection properties mentioned in tra file


AEEJB-910032 TIBCO Adapter for EJB failed for initialize: <error description>.

errorRole Startup This error is a catch-all for some error(s) that may have occurred earlier. Make sure that the EJBs and endpoints are correctly configured in the repository, a valid instance of the repository is running, and that you have enough free memory to create new objects such as dispatchers




AEEJB-920001 Subscription error. Subscription service <service name> listening on <subject> received an unexpected event of type <inbound event type>, expects event <expected event type>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Subscriber Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the subscription service. For details on configuration of a subscription service, see Subscription Service Options in the TIBCO Adapter for EJB User’s Guide.

AEEJB-920002 Subscription error. Subscription service <service name> failed to deserialize the event received on subject <subject> and SDK exception thrown is <SDK error description>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Subscriber Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please refer to User Guide section "Configure the Subscription Service" for details on configuration of subscription service

AEEJB-920003 Subscription error. Subscription service <service name> listening on subject <subject> received inbound event with null data. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Subscriber Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the subscription service. For details on configuring a subscription service, see Subscription Service Options in the TIBCO Adapter for EJB User’s Guide.




AEEJB-920005 Subscription error. Subscription service <service name> listening on subject <subject>, could not find the tracking data. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.


AEEJB-920006 Subscription error. Subscription service <service name> listening on subject <subject> received error <user exit error code and exception> in SDK message level UserExit <name of message-level user exit>.

errorRole Subscriber Make sure the UserExit parameters are valid and the user exit can be invoked from SDK

AEEJB-920007 Subscription error. Subscription service <service name> listening on subject <subject> could not get the class description of <class name>. The Repository URL is <repository url> and the Configuration URL is <configuration url>.

errorRole Subscriber Check the repository configuration for this service. For details on how to configure, run, and test the subscription, see Subscription Service Options in the TIBCO Adapter for EJB User’s Guide.

AEEJB-920008 Subscription error. Subscription service <service name> listening on subject <subject> could not find the mandatory property <property name> in class <class name>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.





AEEJB-920009 Subscription error. Subscription service <service name> listening on subject <subject> received event with invalid value <value> for property <property name> in class <class name>.


AEEJB-920010 Subscription error. Subscription service <service name> listening on subject <subject> received event with missing attribute <attribute name> in class <class name>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.


AEEJB-920014 Subscription error. Subscription service <service name> listening on subject <subject> could not process the inbound event due to connection error <target application connection error> against target application.

errorRole Subscriber Check the application server and make sure it is running. Check the validity of the connection parameters. For details on how to specify connection parameters, see the Adapter Configuration Options section in the TIBCO Adapter for EJB User’s Guide.




AEEJB-920015 Subscription error. Subscription service <service name> listening on subject <subject> failed due to target application invocation error <error description>. Target application is <target application name>. The target application specific commands and parameters are <target application-specific commands and parameters>.

errorRole Subscriber Check the bean operation and the parameters and make sure they are valid. You can also try to execute the operation outside the adapter environment, in the application server GUI and verify that it succeeds

AEEJB-920016 Subscription error. Subscription service <service name> listening on <subject> received error <error description> in Post Processing UserExit <user exit name>. The user exit parameters are <parameter list>.


AEEJB-920039 Failed to activate subscriber <subscriber name> having the service name <service name>. The error message is <error description>.

errorRole Subscriber Anomalies in parameters such as the server name or protocol may cause this error. Make sure that the server properties configured in the repository are accurate. Also make sure that a listener is attached to the subscriber

AEEJB-920040 Subscriber service <service name> could not be located in the adapter instance to create a subscriber endpoint. The retrieved subscriber endpoint associated with the application is null

errorRole Subscriber Make sure that a valid subscriber endpoint has been configured in the repository




AEEJB-930003 Publication error. Publication service <service name> with publishing subject as <subject> received event from target application. It failed while converting event to Minstance as it could not get the class description for <class name>. Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Publisher Verify the configuration of the publication service and check that the schema/class definitions are present in the repository. For details on configuring a publication service, see Publication Service Options in the TIBCO Adapter for EJB User’s Guide.

AEEJB-930012 Publication error. Publication service <service name> with publication subject <subject> received error <error description> in the SDK message level UserExit.

errorRole Publisher Make sure the UserExit parameters are valid and the user exit can be invoked from SDK

AEEJB-930014 Publication error. Publication service <service name> with publication subject <subject> received error while sending event over the wire. The Publish endpoint details are <endpoint details>.

errorRole Publisher Verify the configuration of the publication service and check that the schema/class definitions are present in the repository. For details on configuring a publication service, see Publication Service Options in the TIBCO Adapter for EJB User’s Guide.

AEEJB-930034 Publisher service <service name> could not be located in the adapter instance <instance name> in the repository <repository name> to create a publisher endpoint. The retrieved publisher endpoint associated with the application is null.

errorRole Publisher Make sure that a valid publisher endpoint has been configured in the repository

AEEJB-930035 Error: The data to be published on the endpoint <endpoint name> is null

errorRole Publisher Check that the data received from the EJB application is not null





errorRole Publisher Make sure that you are publishing only complex, MData-type objects

AEEJB-940001 Request Response error. Request Response service <service name> listening on <subject> received unexpected null data in incoming request. Expects event <event type>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Request_Response_Server

Check the configuration of the application that is requesting the event and make sure that it matches the inbound event definition for the request-response service. For details on configuring a request-response service, see Request-Response Service Options in the TIBCO Adapter for EJB User’s Guide.

AEEJB-940005 Request Response error. Request Response service <service name> failed to deserialize the received MServerRequest to MInstance: Received event on subject <subject>, event = <event type>, SDK exception = <error description>. The Repository URL is <repository URL> and the Configuration URL is <configuration URL>.



AEEJB-940006 Request Response error. Error in incoming data for RPC service: <server name> on subject: <service>. Not able to map incoming data to the business object schema: <received class> configured at design time. Invalid data type: <data type> for attribute: <attribute name>.






AEEJB-940008 Request Response error. Connection error in invocation of RPC service: <server name> on subject: <subject>.


Check if the application server and bean are running and the JNDI name used to look up the bean is correct. Also, verify that the connection parameters that are specified in the repository are valid

AEEJB-940010 Request Response error. Request Response service <service name> listening on subject <subject> failed to create Reply Object Error <error description>.


Check the bean operation and the parameters and make sure they are valid. You can also try to execute the operation outside the adapter environment, in the application server GUI and verify that it succeeds

AEEJB-940012 Request Response error. Request Response service <service name> listening on subject <subject> receive an error while sending Data on Reply. Error Message <error description>.


Make sure that the request client is active

AEEJB-940033 RPC Error while sending reply to the AE application: <error description>.


Make sure that the reply sent by the EJB has the correct data types. Also ensure that the reply schema is valid and that it matches that data. You must ensure that the schema of the data being sent out of the EJB matches the schema that the connector/adapter expects

AEEJB-940034 Invalid input to connector/adapter. Mismatch between data sent and schema expected: <error description>.


Make sure that the reply sent to the adapter has the correct data types and the reply schema is valid. You must ensure that the schema of the data being sent out of the EJB matches the schema that the connector/adapter expects




AEEJB-940035 Adapter Properties: AEServer named <server name> is not defined in the adapter instance


Make sure that the AEServer name exists in the repository and that it matches a corresponding name in the adapter configuration

AEEJB-940036 Adapter Properties: AEClass <class name> is not defined in repository


Make sure that the AEClass name exists in the repository and that it matches a corresponding name in the adapter configuration

AEEJB-940037 Error creating Client Request for: <endpoint name>.


Make sure that you have a valid repository instance that the adapter can use, that it is accessible and that the data in it is not corrupted. Alternatively, your machine may be running low on memory. Close some applications to free up the memory

AEEJB-950001 Request Response Invocation error. Request Response Invocation service <service name> with subject as <subject> received event from target application. It failed while converting event to Request, as it could not get the class description for <class name>. Repository URL is <repository URL> and the Configuration URL is <configuration URL>.

errorRole Request_Response_Client

Verify the configuration of the request-response invocation service and check that the schema/class definitions are present in the repository. For details on configuring a request-response invocation service, see Request-Response Invocation Service Options in the TIBCO Adapter for EJB User’s Guide.




AEEJB-950002 Request Response Invocation error. Request Response Invocation service <service name> with subject as <subject> received event from target application. It failed while converting event to Request, as it could not get the class description for <class name>. Repository URL is <repository URL> and the Configuration URL is <configuration URL>.



AEEJB-950003 Request Response Invocation error. Request Response Invocation service <service name> with subject as <subject> received event from target application. It failed while converting event to Request, as it could not get the Operation description <operation description> in the class <class name>. Repository URL is <repository URL> and the Configuration URL is <configuration URL>.



AEEJB-950004 Request Response Invocation error. Request Response Invocation service <service name> with subject as <subject> received event from target application. It failed while converting event to Request, as it cannot set Operation Parameter <parameter name>. Repository URL is <repository URL> and the Configuration URL is <configuration URL>.






AEEJB-950007 Request Response Invocation error. Request Response Invocation service <service name> with subject <subject> received error while sending event over the wire.



AEEJB-950009 Request Response Invocation error. Request Response Invocation service <service name> with subject <subject> received error while requesting event over the wire.



AEEJB-950010 Request Response Invocation error. Request Response Invocation service <service name> with subject <subject> received null reply while requesting event over the wire.


Make sure that the application server is running and the bean has been deployed with the correct JNDI name. Also, check the configuration of the request-response invocation service

AEEJB-950011 Request Response Invocation error. Request Response Invocation service <service name> with subject <subject> received timeout error while requesting event over the wire.


Make sure that the application server is running and the bean has been deployed with the correct JNDI name. If all are verified, increase the reply timeout value




Old Status Messages

AEEJB-950012 Request Response Invocation error. Request Response Invocation service <service name> with subject <subject> received timeout error while requesting event over the wire.


Check the repository settings to make sure that the configuration of the request-response invocation endpoint for this service is valid. For details on setting up a request-response invocation service and endpoint, see Request-Response Invocation Service Options in the TIBCO Adapter for EJB User’s Guide.

AEEJB-950033 Error occurred while invocation of outbound RPC with <operation type>: <error description>.


Make sure that the reply sent to the adapter has the correct data types and the reply schema is valid. You must ensure that the schema of the data being sent out of the EJB matches the schema that the connector/adapter expects

AEEJB-950100 Converted record to SDK parameters using MappedRecord <record name>, class URL <URL of class> and operation name <operation name>.

debugRole Connector



AEEJB-000001 Error while invoking the Bean Method: <method name> <reason>

Error Adapter Make sure that the application server is running, the bean has been deployed, and the method exists in the bean.

AEEJB-000002 RPC:Error while sending reply <reason>

Error Adapter An error occurred while the adapter was sending the reply to the adapter client program.



AEEJB-000003 Invalid Input <description of invalid input>

Error Adapter An error occurred while the adapter was sending the reply to the adapter client program.

AEEJB-000004 No configured EJBs found for the adapter instance: <instance name>

Error Adapter The adapter instance does not contain the information required to connect to EJBs. The list of EJBs and the information required to connect to the EJBs is contained in AdapterSpecific node.

Add the missing configuration information to connect to EJBs.

AEEJB-000005 Adapter Properties: AEServer named <endpoint name> is not defined in the adapter instance.

Error Adapter The endpoint specified in AEServer is either missing or invalid.

Provide the correct endpoint's name in the AEServer entry.

AEEJB-000006 Adapter Properties: AEClass <class name> is not defined in repository.

Error Adapter The class name specified is not defined in the adapter instance.

Create a class or point to the correct class name stored in the repository.

AEEJB-000007 Provided endpoint: <endpoint> is of type: <type of the endpoint>. <service type> endpoint is required for <service type> service

Error Adapter Provide correct endpoint and endpoint type for the service in the adapter instance.

AEEJB-000008 Subscriber activation failed <reason>

Error Adapter The subscriber could not be activated.

AEEJB-000009 Exception occurred in the event handler: <error description>

Error Adapter A run-time error occurred during event handling.




AEEJB-000011 Error occurred while invocation of outbound RPC with <direction>:<error>

Error Connector An unexpected error occurred during the invocation execute function on the interactor.


Error Connector An unexpected error occurred during the invocation execute function on the interactor.

To get the details of the cause of the failure, enable tracing in errorRole.

AEEJB-000013 Reply from TIBCO Application for operation <operation name> contains exception

Information Connector Indicates normal adapter operations. No action necessary.

AEEJB-000014 SDK Runtime exception occurred <reason>

Error Connector A generic SDK runtime exception has occurred.

AEEJB-000015 Publisher endpoint <endpoint name> associated with the application is null.

Error Connector The connector could not create the specified endpoint.

Check the validity of the endpoint.

AEEJB-000016 The data to be published is null.

Error Connector A run-time error occurred because the connector tried to publish a null record.

Check that you are not publishing a null record from EJB. Also, verify that the mapping between the Record type and the TIBCO ActiveEnterprise class being published is not broken.




AEEJB-000017 Missing value for parameter <parameter name>

Warning Connector One or more of the parameter values are not supplied to the converter. This could happen due to mismatch in the schema mapping between the Bean method and the TIBCO ActiveEnterprise method. In the case of inbound invocations, all parameters of inout and out type are expected to be supplied by the method. In the case of outbound invocations involving connector mechanism, except for the out parameter all other parameters are expected to have valid values.

This warning could also be displayed if one or more reply objects are not set to the reply MappedRecord by the bean method.

Check that the values for inout and out parameters for the AEOperation are returned correctly from the bean method. In the case of outbound invocations, verify that the required in and inout parameters are being set by the bean method.

AEEJB-000018 Timeout Exception for operation <operation name>: Server did not respond within <n> ms

Error Connector The request-response invocation service in the adapter or connector could not receive a response within the time set as the timeout period.

Check that the request-response invocation service is accessible. You may also want to increase the timeout value depending on the response time of the remote server. See Request-Response Invocation Service Fields on page 208 to set the timeout value for endpoints.

AEEJB-000019 Unsupported Session Name: <name>, type: <type>

Error Connector An endpoint with an incompatible type of session has been supplied.

Provide the correct session through the endpoint.




AEEJB-000020 Unsupported Endpoint Name: <name>, type: <type>

Error Connector An incompatible endpoint has been supplied as part of the configuration information.

Provide the correct endpoint.


Error Connector The adapter does not support publishing of scalar data through the connector.

Create a wrapper TIBCO ActiveEnterprise class containing the scalar values and set the publisher endpoint to publish the TIBCO ActiveEnterprise Class.

AEEJB-000022 Received valid reply Record from TIBCO Application


AEEJB-000023 Adding key <key name> to output mapped record


AEEJB-000024 Return value from TIBCO Application is null

Information Adapter Indicates normal adapter operations. No action necessary.

AEEJB-000025 Return value from TIBCO Application is: <value>





AEEJB-000026 Error while converting Record type to SDK type <error>

Error Adapter Conversion error occurred while converting the connector Record type to TIBCO's ActiveEnterprise message data type.

Check if it is a runtime error. Otherwise check if there is a data type mismatch or a discrepancy in the attribute names between Record data type and TIBCO ActiveEnterprise class. See Appendix D, TIBCO ActiveEnterprise to J2EE Connector Mapping, on page 415 for details.

AEEJB-000027 Error while creating Interaction: <error message>

Error Connector An error occurred during the creation of the Interaction object.

One of possible errors could be a missing/invalid repoUrl or configUrl. Check the repoUrl and configUrl provided with bean environment, if you are deploying AeConnector as a jar. If AeConnector is deployed as resource adapter (.rar), check the ra.xml file.

AEEJB-000028 Subscriber endpoint could not be located in the adapter instance

Error Adapter The subscriber endpoint is missing for the specified adapter instance. Check the subscriber endpoint in the .dat file.

AEEJB-000029 Data published successfully on Subject name: <subject name>


AEEJB-000030 Attempting to set value for the out parameter: <parameter name>Details: <reason>

Warning Connector This is a warning message that informs you that the adapter is attempting to set value for the out parameter. Check the bean code and fix the problem.




AEEJB-000031 Advisory: <advisory warning information>

Warning Adapter This is a warning message.

AEEJB-000032 Error advisory: <advisory error information>

Error Adapter Make sure that you have a valid repository instance that the adapter can use, and that the data in it is not corrupted. Alternatively, your machine may be running low on memory. Close some applications to free up the memory.

AEEJB-000033 Error creating Client Request for: <reason>

Error Adapter There was an error in creating Client Request object.

AEEJB-000034 Connection failed: Unable to connect to Application Server: <reason>

Error Adapter There was a communication error while connecting to server. Examine the reason and fix the problem.

AEEJB-000035 EJB lookup failed: Unable to get the Remote object: <reason>

Error Adapter Failed to lookup the bean.

AEEJB-000036 TIBCO Adapter for EJB initialization failed: <reason>

Error Adapter The adapter failed to initialize.

AEEJB-000037 TIBCO Adapter for EJB is ready


AEEJB-000038 Dispatcher count = <number of dispatchers>


AEEJB-000039 Advisory Information: <advisory information>




Status Messages for the Palette | 369

Status Messages for the Palette

.


AEEJB-970101 Error while Generating Code: <error description>

errorRole Code Generator

Verify the configuration information used to generate the bean code. Please ensure that the target output directories exist, and have write permissions

AEEJB-970102 Error while generating Deployment Descriptor: <error description>


Verify the configuration information used to generate the deployment descriptor. Please ensure that the target output directories exist, and have write permissions

AEEJB-970103 No operation defined in: <class name>


Ensure that you have attached at least one operation to the configured operation class

AEEJB-970104 No operation defined in: <class name>


Ensure that you have attached at least one operation to the configured operation class

AEEJB-970105 No schema associated with: <endpoint name>


Ensure that you have attached a schema class to the configured endpoint or service

AEEJB-970106 No schema associated with: <endpoint name>


Ensure that you have attached a schema class to the configured endpoint or service

AEEJB-970107 Error while writing bean method: <error description>


Verify the configuration information used to generate the bean code. Please ensure that the target output directories exist, and have write permissions



AEEJB-970108 Error while generating the Home class using endpoint <endpoint name> with the associated schema


Ensure that you have attached the appropriate schema class to the configured endpoint or service

AEEJB-970109 Error while generating code: <error description>


This error is a catch-all for some error(s) that may have occurred earlier while generating code for the outbound scenario. Verify the configuration information used to generate the bean code and deployment descriptor. Ensure that the appropriate operations and classes are attached to the operation classes and endpoints

AEEJB-970110 Error in generating code: <error description>


This error is a catch-all for some error(s) that may have occurred earlier. Verify the configuration information used to generate the bean code and deployment descriptor. Ensure that the appropriate operations and classes are attached to the operation classes and endpoints. Please ensure that the target output directories exist, and have write permissions

AEEJB-970111 Missing value for the mandatory field: <field name>


This field is a mandatory field for this service. Please ensure that it has been correctly filled in

AEEJB-970112 Invalid value entered for: <field name>


Enter a valid name for this field. You must ensure that the name is not empty, and does not contain any special characters that are disallowed by the operating system

AEEJB-970113 Invalid value entered for numeric field: <field name>


The value entered in this field should be a numeric value. Please ensure that it has been correctly filled in, or reset it back to its original value




AEEJB-970114 Schema associated with <endpoint name> has an incorrect operation class


The configured type of endpoint cannot have that operation class type associated with it. Please make sure that the appropriate class is associated with the endpoint

AEEJB-970115 Exception encountered while generating the remote interface class for the operation <operation name> and class <class name> for the repository path <path>, using the package name <package name> and output directory <output directory>.


Verify that the operation, class, repository and output parameters are correct

AEEJB-970116 Invalid schema type specified for the endpoint <endpoint name>.


Verify that the schema type specified for the endpoint is valid.

AEEJB-970117 The specified data type <data type> is not supported.


Verify that supported data types are used in the schema.

AEEJB-970118 The specified data type <data type> is not valid.


Verify that valid data types are used in the schema.

AEEJB-970119 The specified data type for parameter <parameter name> in the operation <operation name> is not valid.


Verify that valid data types are used for the parameter types.

AEEJB-970120 The specified data type for sequence <sequence type> in the class <class name> is not valid.


Verify that valid data types are used for the sequence types.




AEEJB-970121 The specified data type for scalar <scalar field> in the class <class name> is not supported or invalid.


Verify that valid supported data types are used for the scalar fields.

AEEJB-970122 The operation <operation name> defined in the RPC class <class name> is not valid.


Verify that valid data types are used for return type, parameters and exceptions in the operation class.

AEEJB-970123 The operation <operation name> is not valid.


Verify that valid supported data types are used for return type and parameters in the operation class.

AEEJB-970124 The specified data type for exception <error description> in the operation <operation name> is not valid.


Verify that valid data types are used for the exception types.

AEEJB-970125 The specified return type for the operation <operation name> defined in RPCClass <class name> is not valid.


Verify that valid data types are used for the operation return types.

AEEJB-970002 Invalid value entered for numeric field: <field name>, Permissible values are <value> to <value>.

errorRole Palette The value entered in this field should be a numeric value. Please ensure that it has been correctly filled in, or reset it back to its original value

AEEJB-970003 Invalid value entered for numeric field: <field name>





AEEJB-970201 Empty encoding value for the field: <field name>

errorRole Palette You must select or enter a valid encoding format for this field. Please use the editable drop-down list to select/ view the supported encoding formats or type in a valid encoding format

AEEJB-970202 Unable to resolve reference <reference> for the service <service name>. Message is <error description>.

errorRole Palette Please verify the service name and folder in the configuration

AEEJB-970203 Unable to convert URL <URL> to a usable path for Hawk. Message is <error description>.

errorRole Palette Please verify URL and Hawk settings in the configuration

AEEJB-970204 Unable to create JMS the terminator service for the adapter <name>. Message is <error description>.

errorRole Palette Please verify the JMS terminator settings in the configuration

AEEJB-970205 Unable to store the value <value> into the global variable <variable> in the Designer store. Message is <error description>.

errorRole Palette Please verify that the global variable exists in the store

AEEJB-970206 Unable to set name <original name> to <changed name> in the context of%3. Message is <error description>.

errorRole Palette Please verify your repository settings with respect to the context provided.

AEEJB-970207 Number of reconnect attempts should be less than or equal to total number of reconnect attempts

errorRole Palette The value entered in this field should be a numeric value. Please ensure that Number of reconnect attempts should be less than Maximum number of Reconnect Attempts




AEEJB-970208 Invalid value entered for numeric field: <field name>, Permissible values are 0 to <value>


AEEJB-970209 Missing value for the mandatory field: <field name>

errorRole Palette This field is a mandatory field for this service. Please ensure that it has been correctly filled in

AEEJB-970210 Invalid subject error for field: <field name>

errorRole Palette Subject name entered is not a valid subject name. Special characters are not allowed in subject field. Please enter the valid subject and then try again

AEEJB-970211 The adapter name <name> contains characters that may generate illegal subject names (characters that have special meaning for RV subjects should not be used).

errorRole Palette Adapter name entered is not a valid name. Please enter the valid adapter name and then try again

AEEJB-970212 Invalid value entered for numeric field: <field name>, Permissible values are -1, 0 and 1 to <value>

errorRole Palette The value entered in this field should be a numeric value. Please ensure that Number of reconnect attempts should be less than Maximum number of Reconnect Attempts



| 375

Appendix B Bean Programming Guide for Request-Response Invocation and Publication Services

This appendix provides guidelines for programming EJBs that use the TIBCO J2EE Connector implementation to communicate with TIBCO services, including both synchronous request-response invocation and asynchronous publication.

Topics

• Introduction, page 376

• Programming Using the Connector API, page 377

• Custom Exception Handling, page 384

• RPC Support Library, page 387

• Publish Support Library, page 396

• Deployment Descriptor, page 404


376 | Appendix B Bean Programming Guide for Request-Response Invocation and Publication Services

Introduction

The TIBCO Adapter for EJB software includes an implementation of the Java Connector Architecture version 1.5. This is a standard API developed by a committee including representatives from Sun Microsystems, TIBCO Software, and other Enterprise Application Integration (EAI) vendors. This chapter assumes that you are familiar with EJB programming. Some familiarity with the J2EE Connector specification will also be helpful.

For more information, please refer to the following URL:http://java.sun.com/j2ee/connector/


Programming Using the Connector API | 377

Programming Using the Connector API

The J2EE Connector API has been designed to be similar to the JDBC API used to access relational databases. This section provides general information on how to program for the Connector API, especially for the TIBCO Connector implementation.

The simplest way to produce an EJB capable of accessing a TIBCO service is to use the code generator provided with the adapter. The code produced by the code generator uses some utility classes, for example, RPC Support for request-response invocation interactions, and Publish Support for publication. These provide a convenient and high-level API specifically for accessing TIBCO services. These utility classes still use the Connector API underneath. Utility classes are described in later sections of this chapter.

However, if you wish to write your own bean code, or if you want to understand how the generated EJB works, then the information in this chapter will be helpful.

In TIBCO's implementation of the Connector API, a Connection obtained does not represent a connection to a specific enterprise system. Instead, it represents a connection to the TIBCO-enabled application software. This connection can be used to access any TIBCO ActiveEnterprise service whose configuration information is in the same repository instance that is used to instantiate the connection factory.

Programming using the connector API involves the following tasks:

1. Accessing the Connection Factory

2. Creating a Connection

3. Creating an Interaction

4. Using an Interaction

Accessing the Connection FactoryThe first step while using the J2EE Connector API is to obtain an instance of the TIBCO connection factory.

There are two ways to achieve this:

• Look Up Resource Factory Using JNDI

• Directly Construct a Connection Factory Instance



Look Up Resource Factory Using JNDI

You will use this method in an EJB server that supports hosting J2EE Connectors, for example, the Sun reference server. Your connection factory access code would be similar to the following:

Context c = new InitialContext();ConnectionFactory cf =

(ConnectionFactory)c.lookup("java:comp/env/"+factoryRef);

Here, factoryRef is the name of the reference that the bean uses to access the connection factory. factoryRef is mapped to a global name in the JNDI namespace by a resource-ref entry in the bean's deployment descriptor. The JNDI name of the connector is set when the Connector is deployed into the J2EE server. Detailed deployment procedures are vendor-specific.

Directly Construct a Connection Factory Instance

If you want to use the Connector API in an EJB server or servlet environment that does not support registering a Connector in JNDI, you can directly create an instance of a connection factory using a constructor. Your connection factory access code will appear as follows:

Map properties = new HashMap();properties.add("repoUrl","tibcr://ejb_sample:userName=adejb:password=adejb");properties.add("configUrl","Connector/defaultIntance/adapter");ConnectionFactory cf = new com.tibco.ejb.connector.AE3ConnectionFactory(properties);

This code directly imports TIBCO's implementation of Connection Factory, called AE3ConnectionFactory. You must construct this connection factory with a Map object containing two entries:

• repoUrl – This is a string that identifies the name and, if necessary, connection parameters for the repository instance containing the Connector configuration. For example: tibcr://ejb_sample:userName=adejb:password=adejb.

• configUrl – This is a string that identifies the location of the Connector configuration information within the repository. For the sample repository instance included with the TIBCO Adapter for EJB, this string should be /tibco/private/adapter/Connector/RPC/EJBAdapter.

Creating a ConnectionAfter you have created a ConnectionFactory instance using one of the methods described above, you can create a ConnectionInstance from it by calling the getConnection method as follows:



Connection c = cf.getConnection();

You must close the connection object after using it by calling the close() method for the object.

Creating an InteractionFrom a Connection object, you can create an instance of the Interaction interface using the createInteraction method. You use this interface to access a specific TIBCO ActiveEnterprise service.

For example:

Interaction inter = connection.createInteraction();

An interaction object is used with an instance of InteractionSpec, which specifies the details of the operation to be performed with it.

InteractionSpec is an interface defined in the J2EE Connector API. TIBCO's implementation of this API is class com.tibco.ejb.connector.AE3InteractionSpec.

Using an InteractionYou can use the com.tibco.ejb.connector.AE3InteractionSpec class for the following tasks:

• Making Request-Response Calls

• Publishing Data

Making Request-Response Calls

Making request-response calls involves the following tasks:

• Creating and Configuring an InteractionSpec

• Making the Request-Response Call

Task A Creating and Configuring an InteractionSpec

The following is a typical example of creating and configuring an InteractionSpec for use in a request-response scenario:

// Instantiate an InteractionSpecAE3InteractionSpec iSpec = new AE3InteractionSpec();// Set InteractionSpec propertiesiSpec.setServerURL("/tibco/public/endpoint/SAP_EXAMPLE/SapAdapterSchema/endpoint");



iSpec.setClassURL("/tibco/public/class/ae/SAP_EXAMPLE/SapAdapterSchema/RFC_CUSTOMER_GET");iSpec.setFunctionName("RFC_CUSTOMER_GET");iSpec.setExecutionTimeout(60000);iSpec.setInteractionVerb(InteractionSpec.SYNC_SEND_RECEIVE);

In this example, you first create an InteractionSpec instance, and then set several properties on it. The properties are:

• ServerURL—which is the full global name of the TIBCO Rendezvous request-response endpoint definition of the service that is being invoked.

• ClassURL—which is the TIBCO ActiveEnterprise class definition that contains the operation that is being invoked.

• FunctionName—which is the name of the TIBCO ActiveEnterprise operation that is being invoked.

• ExecutionTimeout — specified in milliseconds, is the timeout value to be used for the request-response invocation service. If the server does not respond within this time period, an exception is thrown to the calling client. This value overrides the value set in the design-time configuration of the request-response invocation service. However, if this value is not set at runtime, the design-time timeout value is used during execution.

Task B Making the Request-Response Call

To make a remote procedure call, the execute() method on the Interaction object must be called, passing it to the InteractionSpec and the inputs (parameters) to the request-response server service or request-response invocation service. The parameters are stored in a MappedRecord, with each named parameter having a corresponding name-value pair stored in the record. A typical example is as follows:

// get the RecordFactory asssociated with the ConnectionFactoryrf = cf.getRecordFactory();// Create record to hold inputsMappedRecord inputs = rf.createMappedRecord("inputs");inputs.add("NAME1","ACME Widgets");// .. add more inputs if required// Create record to hold output resultsMappedRecord outputs =rf.createMappedRecord("outputs");// execute the callboolean ok = inter.execute(is,inputs,outputs);inter.close(); // deallocate Interaction

Endpoints referred to in the setServerURL method of the AE3InteractionSpec class must refer to objects that exist in the repository instance associated with the Connector.



After this code is run, the output Record will contain any out or in/out parameters set as a result of the request-response call. Additionally, the output Record will contain an entry with the _returnValue key.

Publishing Data

Publishing data involves the following tasks:

• Creating and Configuring an InteractionSpec

• Publication of the Data

Task A Creating and Configuring an InteractionSpec

The following is a typical example of creating and configuring an InteractionSpec for use in publishing data:

// Instantiate an InteractionSpecAE3InteractionSpec iSpec = new AE3InteractionSpec();// Set InteractionSpec propertiesiSpec.setServerURL("/tibco/public/endpoint/SAP_EXAMPLE/SapAdapterSchema/endpoint");iSpec.setClassURL("/tibco/public/class/ae/SAP_EXAMPLE/SapAdapterSchema/BRFCKNA1");iSpec.setFunctionName("publish");iSpec.setInteractionVerb(InteractionSpec.SYNC_SEND);

In this example, you first create an InteractionSpec instance, and then set several properties on it. The properties are:

• ServerURL—which is the full global name of the request-response TIBCO Rendezvous message endpoint definition for the publisher. This can also be a subscriber endpoint.

• ClassURL—which is the TIBCO ActiveEnterprise class definition for the data to be published.

• FunctionName— which is the name of the operation being invoked and this operation must be publish.

Task B Publication of the Data

Publishing data is accomplished by calling the execute() method on the Interaction object, passing it to the InteractionSpec and to the data to be published. The data should be in the form of a Record, whose attributes have names corresponding to the TIBCO ActiveEnterprise class definition.

Endpoints referred to in the setServerURL method of the AE3InteractionSpec class must refer to objects that exist in the repository instance associated with the Connector.



// get the RecordFactory asssociated with the ConnectionFactoryrf = cf.getRecordFactory();// Create record to hold inputsMappedRecord inputs = rf.createMappedRecord("inputs");inputs.add("NAME1","ACME Widgets");// .. add more fields if required// publish the databoolean ok = inter.execute(is,inputs);inter.close(); // deallocate Interaction

TIBCO Connector LimitationsThe following are limitations associated with the TIBCO Connector:

• The transaction contract segment of the J2EE Connector API is not supported at present (this is an optional part of the Connector specification).

• There is no security support. No sign-on is required to access the connector.

You cannot enlist Connector interactions and other operations, such as Java Database Connectivity (JDBC), in the same transaction since there is no transaction support. However, even if the Connector had such support, most enterprise systems and TIBCO ActiveEnterprise products with which the connector would interact do not support an XA-compliant transaction interface and, therefore, can not be used in a transaction anyway.

A security limitation is that when you use a TIBCO-enabled application to connect business systems, the TIBCO Adapter servicing the business system is typically the component that performs the signon. The remote client does not sign on with a unique user identification (ID). Instead, the adapter allows multiple-client access using a single EIS connection or pool of connections, just as an application server does.

Information on EndpointsEndpoints are objects stored in the repository server. An endpoint is associated with a Session object that contains communication parameters such as the port number used for a TIBCO-enabled application, and the quality of service, for example, certified or reliable messaging. The endpoint itself contains a reference to the associated session, a subject name, and a reference to a class definition object that defines the schema of the objects to be sent or received using the endpoint. You can view and edit the repository contents, including endpoints, using TIBCO Designer.



Endpoints can be of several types. As the Connector is primarily designed for outbound communication with an EJB, generally the EJB functions in the role of a TIBCO Rendezvous publication service or a request-response invocation service. If the EJB is a message subscription service or a request-response service, see Bean Programming Guide for Request-Response and Subscription Services on page 407.

If you specify a request-response invocation service endpoint in the setServerURL method, then the Interaction will use that endpoint for communication. The endpoint must exist and is typically added to the Connector’s configuration information by means of TIBCO Designer. For communication to occur, the request-response invocation endpoint’s subject name must match the subject name used by a corresponding request-response endpoint. Also the sessions used by the request-response invocation and the request-response service’s endpoints must be compatible, that is, they should use the same port number.

Similarly, for the request-response invocation service, you can specify a publication service endpoint to the setServerURL method, and the EJB will function as a publisher. The Publisher endpoint must exist and must be compatible with a corresponding Subscriber endpoint that is part of the receiving adapter’s configuration.



Custom Exception Handling

Custom Exception handling in outbound request-response service facilitates translation of TIBCO ActiveEnterprise exceptions to application exceptions (Business Exceptions) in EJB.

For a request from an EJB (via the Connector) to TIBCO ActiveEnterprise, the request-response server service can return an error condition and error data. The Connector translates this error and displays the AEResourceException class, which represents the error displayed by the connector after translating the error returned by the request-response operation. The error data is encapsulated in the form of a javax.cci.Record.

The AEResourceException class is extended from the javax.resource.ResourceException.

See TIBCO Designer Palette Reference about how to define an exception class for TIBCO ActiveEnterprise operations.

The following table lists the constructor and method of this class.

The Java class generated by the code generator can be used to display an application error from EJB.

Table 15 Constructor for the AEResourceException class

Constructor Summary

AEResourceException(String name, Object

data)

Constructs a new AEResourceException with the provided name and exception data.

Table 16 Methods for the AEResourceException class

Method Summary

String getExceptionName() Returns the name of the exception.

Object getExceptionData() Returns the exception data object.

String toString() Returns the exception data in string format.

String getMessage() Returns the exception message.

void setExceptionName(String expName) Sets the exception name.

void setExceptionData(Object data) Sets the exception data object.


Custom Exception Handling | 385

The following example demonstrates the conversion of a TIBCO ActiveEnterprise Exception for an outbound request-response service to an application exception in EJB.

The example consists of:

• Bean Implementation, which invokes the request through the connector

• Server

Bean Implementation

EJB encounters AEResourceException on RPC invocation and displays an equivalent application exception (InvalidCustException):

try{ // Prepare to call a remote service. The first parameter is the // endpoint URL to call, the second is the method name.

rpcs.prepare(getEndpointName(), getAEClassName(), "RFC_CUSTOMER_GET", InteractionSpec.SYNC_SEND_RECEIVE);

rpcs.addParam("KUNNR", KUNNR);rpcs.addParam("NAME1", NAME1);IndexedRecord ir2 = new IndexedRecordImpl(CUSTOMER_T);ir2.setRecordName("CUSTOMER_T");rpcs.addParam("CUSTOMER_T", ir2); boolean ok = rpcs.execute();

}catch(ResourceException ex){if (ex instanceof AEResourceException){

AEResourceException aeresExcp= (AEResourceException)ex;String expName=aeresExcp.getExceptionName();if (expName.compareTo("InvalidCustException")==0){

throw new InvalidCustException(aeresExcp); }else{

throw new AEEjbException(aeresExcp);}

}else{

throw new EJBException(ex.getMessage());}

}finally{if (rpcs !=null)

rpcs.cleanup();}return rpcs.getOutputs();

}



Here InvalidCustException is the application exception class generated by the Code Generator.

Server Exception Handling

The request-response server implementation that returns error data on receipt of the request from the EJB (Connector):

if(//Exception condition){ MInstance invalidCust = m_dataFactory.newInstance( "/tibco/public/class/ae/SAP_EXAMPLE/SAPAdapterSchema/ InvalidCustExceptionData"); invalidCust.set("KUNNR", KUNNR); invalidCust.set("NAME1", NAME1); reply.setException("Invalid Customer Exception",invalidCust); return reply;}

In this example, the InvalidCustException set by the request-response server is translated to the application error InvalidCustException with the error data encapsulated as javax.cci.Record.


RPC Support Library | 387

RPC Support Library

The request-response Support Library provides a runtime helper class called RPCSupport. This class is utilized by the code generated beans to communicate with the Connector interfaces. A custom EJB can make use of this utility. One instance of the class handles one method invocation at a time and cannot be used for concurrent access.

There are four basic steps to use this facility:

1. Create an instance of the RPCSupport class. This is typically done in a bean's ejbCreate method. This step locates or creates a ConnectionFactory. If a factory instance cannot be obtained, javax.ejb.CreateException is displayed.

2. Call the prepare() method for the RPCSupport class.

This sets up the instance with the class and method name to call.

3. Add parameter values for the invocation using the addParam() method.

4. Run the RPC call.

5. Call the cleanup() method to free the resources used.

The following is a detailed reference of the RPCSupport class.



RPCSupportClass

Declaration package com.tibco.ejb.runtime;

Purpose This class is utilized by the code generated beans to communicate with the Connector interfaces.

Remarks One instance of the class handles one method invocation at a time and is not meant for concurrent access.

Data Members


RPCSupport() Creates an RPCSupport instance. 389

prepare() Prepares the instance for execution. 390

addParam() Adds a parameter value prior to invoking the method.

391

execute() Executes the method. 392

getOutputs() Gets the output from the method after invocation and returns a record containing the results of the invocation.

393

cleanup() Cleans up after a method invocation. 394

remove() Closes any allocated connections. 395


RPCSupport() | 389

RPCSupport()Constructor

Declaration public RPCSupport() throws javax.ejb.CreateException;

Purpose Creates an RPCSupport instance, ConnectionFactory.

Remarks Call this constructor from ejbCreate. The ConnectionFactory instance is created internally from information in the bean's environment or resource-reference settings. If ConnectionFactory cannot be created, it throws CreateException.

Parameter None.



prepare()Deprecated in release 4.1.0

Declaration public void prepare(String endpointName,String className,String methodName,int verb,int timeout);

Purpose Prepares the instance for execution.

Remarks This is a deprecated method, which is retained to support backward compatibility.

Parameters Parameter Description

endpointName Full global name for the TIBCO Rendezvous request-response service endpoint with which we will interact.

className Full global name of the class in which the method is to be invoked.

methodName Name of the method.

verb Verb constant from Interaction Specification. It can have the following values: SYNC_SEND, SYNC_RECEIVE, or SYNC_SEND_RECEIVE.

timeout Sets timeout value for the request-response and request-response invocation endpoints.

Current version retrieves the timeout value from the configuration. The timeout value set through this option is ignored.


addParam() | 391

addParam()method

Declaration public void addParam(String name, Object param);

Purpose Adds a parameter value prior to invoking the method.

Remarks Parameters are assumed to be Java primitive types, or collections (Maps and Lists).


name Name of the parameter to be added.

param Java object that needs to be passed as a parameter.



execute() method

Declaration public void execute();

Purpose Executes the method.

Remarks None.

Parameters None.


getOutputs() | 393

getOutputs() method

Declaration public MappedRecord getOutputs();

Purpose Gets the output from the method after invocation and returns a record containing the results of the invocation.

Remarks The actual function returning a value is in the field named _returnValue. Other map contents, if set, reflect out parameters or in-out parameters of the method.

Parameters None.



cleanup() method

Declaration public void cleanup();

Purpose Cleans up after a method invocation.

Remarks After this call, prepare() is ready to be called again.

Parameters None.


remove() | 395

remove() method

Declaration public void remove();

Purpose Closes any allocated connections.

Remarks Call this method from the EJB's ejbRemove method.

Parameters None.



Publish Support Library

The PublishSupport class is a run time helper class used by the code generator.

There are four basic steps to use this facility:

1. Create an instance of the PublishSupport class.

This is typically done in a bean's ejbCreate method. This step locates or creates a Connection Factory. If a factory instance cannot be obtained, javax.ejb.CreateException is displayed.

2. Call the prepare() method.

3. Call the publish() method.

This method requires an argument, which is the data to be published.

4. Call the cleanup() method to free resources.

The following is a detailed reference of the PublishSupport class.


PublishSupport | 397

PublishSupportClass

Declaration package com.tibco.ejb.runtime;

Purpose This runtime class is for code-generated beans. One instance of this class handles one publish operation at a time. It is not designed for concurrent access.

Remarks This class creates a PublishSupport instance.

Data Members Method Description Page

Publish

Support()

Creates a PublishSupport instance. page 398

cleanup() Cleans up after a publish operation. page 399

get

Connection()

Returns a Connection instance. page 400

prepare() Prepares for a new publish operation. page 401

publish() Publishes on the endpoint previously submitted to the prepare() call.

page 403

remove() Calls this method from the EJB's ejbRemove method.

page 402



PublishSupport()Constructor

Declaration public PublishSupport() throws javax.ejb.CreateException;

Purpose Create a PublishSupport instance. Call this from ejbCreate. This method creates a ConnectionFactory internally from information in the bean's environment or resource-ref settings.

Remarks Call this constructor from ejbCreate. If ConnectionFactory cannot be created, it throws CreateException.

Parameter Parameter Description

factoryRef Name of the resource reference for the ConnectionFactory.


cleanup() | 399

cleanup() Method

Declaration public void cleanup();

Purpose Cleans up after a method invocation.

Remarks After this call, prepare() can be called again.

Parameters None.



getConnection() Method

Declaration public javax.resource.cci.Connection getConnection();

Purpose Returns a Connection instance.

Remarks None.

Parameters None.


prepare() | 401

prepare()Method

Declaration public void prepare(String endpointName,String classURL,int verb);

Purpose Prepares to perform a new publish operation.

Remarks None.


endpointName The full global name for the endpoint with the method will interact. If it is a Publisher endpoint, the session for that input will be used for communication.

classURL Class to publish

verb Constant from InteractionSpec. Currently ignored.



remove() Method

Declaration public void remove();

Purpose Closes any allocated connections.

Remarks Call this method from the EJB's ejbRemove method.

Parameters None.


publish() | 403

publish()Method

Declaration public void publish(data);

Purpose Publishes on the endpoint previously submitted to the prepare() call.

Remarks None.


data The data to publish.




TIBCO's J2EE Connector implementation can be used either as a standard Java archive file (jar) loaded into the application server's JVM, or as a resource archive (rar), which can be loaded by an application server with explicit support for J2EE Connectors.

The bean code can be identical when the J2EE connector is used either as a standard Java archive file or a resource archive, but the deployment descriptor will be different. If the Connector is being used as a standard Java archive, the deployment descriptor should define environment entries (env-entry elements in the XML) for each bean in the archive. These entries identify the location of the Connector configuration data in repository. Three mandatory environment entries are:• repoUrl

You can also specify the authentication details as shown next:

tibcr://ejb_sample:userName=adejb:password=adejb

• configUrl

• traFileName

The path to the connector.tra file. This file is located in <ADEJB_HOME>/bin. For example, D:/tibco/adapter/adejb/<version_num>/bin/connector.tra

You must supply the complete URL, including the name of the instance.

Use this file to override values of global variables set in the repository or for setting values of adapter-specific configuration parameters.

Do not set any java environment variable in this file as it is not supported by the connector configuration.

TIBCO-specific properties like config and repo url should not be set using this file. The connector deployment descriptor contains configuration property for setting these parameters.

See the Predefined Global Variables section for more details on the list of global variables that can be specified in the connector.tra file.


Deployment Descriptor | 405

If the Connector is installed as a resource archive, the env-entry sections of the deployment descriptor are not needed. In this case, repoUrl and configUrl are not set in the bean's deployment descriptor, but instead are properties of the ConnectionFactory instance associated with the Connector and are set at the time the factory is registered in the J2EE environment.

Instead of the env-entry sections, the deployment descriptor in this case should have a resource-ref section for each bean in the archive, similar to the following:

<resource-ref><description>Reference to TIBCO AE Connector</description><res-ref-name>tibco/aeconnector</res-ref-name><res-type>com.tibco.ejb.connector.AE3ConnectionFactory

</res-type><res-auth>Container</res-auth>

</resource-ref>

The resource-ref is a part of the EJB 1.1 specification. However, many J2EE servers do not allow a ConnectionFactory to be specified as the res-type attribute: this is a feature of J2EE servers that include support for the J2EE Connector API. Generally, these servers are also compliant with EJB 2.0 rather than 1.1. Some examples are HP Bluestone 7.3, and HP Application Server 8.0.




| 407

Appendix C Bean Programming Guide for Request-Response and Subscription Services

This appendix provides guidelines for programming EJBs that receive incoming requests or notifications from TIBCO Adapter for EJB. When used in this way, these beans operate as a request-response service or subscription service in the TIBCO environment.

Topics

• Introduction, page 408

• Writing Request-Response Server Beans, page 410

• Writing Subscriber Beans, page 412

• Custom Exception Handling, page 413

• Deployment, page 414


408 | Appendix C Bean Programming Guide for Request-Response and Subscription Services

Introduction

Standalone Adapter

During inbound communication, an adapter process outside the application server converts incoming TIBCO ActiveEnterprise operation requests or message publications into RMI calls to an EJB. This section discusses the requirements for writing beans that work together with the adapter process to function as request-response servers or message subscribers on TIBCO Rendezvous and JMS.

Such a bean is a stateless session bean. Therefore, it must have an ejbCreate() method with no parameters. A stateless session bean can also have one or more business methods, whose method signatures correspond to the parameters in the TIBCO ActiveEnterprise operation(s) for which the bean is to act as a server.

Note that the EJB code generator can generate most of the code required to implement a TIBCO ActiveEnterprise server or subscriber bean, given a TIBCO ActiveEnterprise endpoint definition. It generates complete source code for the remote and home interfaces, and a skeleton for the bean itself, which is complete except for the implementation of the business method. It also generates custom record classes for any complex types required by the bean's method signature, and a deployment descriptor. See Chapter 9, Code Generator, on page 289 for more details about the code generator.

This chapter discusses server and subscriber bean programming in detail, which may be useful if you do not want to use the code generator, need to extend its generated classes, or want to understand better how the generated classes work.

Inbound Connector

If the inbound adapter is deployed into an application server, an adapter process inside the application server converts the incoming TIBCO ActiveEnterprise operation requests or message publications into local calls to an MDB. This section discusses the requirements for writing MDBs that work together with the adapter process to function as request-response servers or message subscribers on TIBCO Rendezvous and JMS.

An MDB must extend com.tibco.ejb.jca15.support. AbstractMessageListener and must implement javax.ejb.MessageDrivenBean interface. It must have an ejbCreate() method with no parameters. A message driven bean can also have one or more business methods, whose method signatures correspond to the parameters in the TIBCO ActiveEnterprise operation(s) for which the bean is to act as a server. Note that the EJB adapter code generator can generate most of the code required to implement a TIBCO ActiveEnterprise server or subscriber bean, given a TIBCO ActiveEnterprise


Introduction | 409

endpoint definition. It generates complete source code skeleton for the MDB itself, which is complete except for the implementation of the business method. It also generates custom record classes for any complex types required by the bean's method signature, and a deployment descriptor. See Chapter 9, Code Generator, on page 289 for more details about the code generator.



Writing Request-Response Server Beans

Writing request-response server beans involves the following tasks:• Matching Method Signatures

• Entering Complex Data Types

• Handling Return Values

Matching Method SignaturesFor every TIBCO ActiveEnterprise class operation, the EJB remote interface must have a corresponding method. For example, in case of session beans, if TIBCO ActiveEnterprise class contains Method1 and Method2, the remote interface must have Method1 and Method2.

These methods must have the same signature. In other words, there must be a pair of methods with the following attributes that:• Have the same name, for example Method1

• Are of equivalent return type, for example boolean

• Have the same number of parameters

• Have the same name for each parameter

• Have matching parameters of equivalent data types

For details, see Appendix D, TIBCO ActiveEnterprise to J2EE Connector Mapping, on page 415 for a list of the Java types that correspond to TIBCO ActiveEnterprise data types.

The adapter needs one-to-one mapping between the TIBCO ActiveEnterprise classes and the Record classes in Java. Therefore, the special characters in the Class, Attribute, Operation, Parameter, and schema Exception names will be replaced by their string equivalents. For details, see Appendix D, TIBCO ActiveEnterprise to J2EE Connector Mapping, page 415.

In the special case where the method name is the same as the enclosing class name, the digit 1 should be appended to the method name so that the method will not be considered a Java constructor.


Writing Request-Response Server Beans | 411

Entering Complex Data TypesComplex data types (for example, parameters that are classes) are input as custom records. They should be represented as classes that implement the javax.resource.cci.Record interface. Each such record should have get and set methods for each attribute of the class. For example, if the attribute is Name, the methods should be called getName and setName.

Unions are also represented as classes that implement javax.resource.cci.Record. However, in this case the class should have three methods:• getValue() – returns an Object representing the current value of the union.

• getCurrentMemberName() – returns a String that names the current member of the union that is active.

• setCurrentValue(String memberName, Object value) – sets the current member name to be the first parameter, and the current value to be the second parameter.

Handling Return ValuesThe return value from a bean method that implements a TIBCO ActiveEnterprise request-response service must be of type java.util.Map.

If the TIBCO ActiveEnterprise operation has a return value of a type other than void, then one of the entries in the Map should have a String key named _returnValue. The value of the String key is the return value for the operation.

If the TIBCO ActiveEnterprise operation has in/out or out parameters, then the value of those parameters should also be stored in the Map that is returned. Their values are stored with String keys corresponding to the names of the parameters (as given in the TIBCO ActiveEnterprise schema definition).



Writing Subscriber Beans

EJBs that function as subscribers via the adapter process must be stateless session beans. The bean must include a business method named subscribe. The argument to subscribe is a single object that implements javax.resource.cci.Record, and whose contents correspond to the TIBCO ActiveEnterprise class being received. (The object must have a class definition, because the TIBCO Adapter SDK does not support publication of primitive types such as String).

The code generator will generate custom Record classes that can be used together with a subscriber bean. These classes will have get and set methods for each attribute of the class. For more information, see Chapter 9, Code Generator, on page 289.

The subscribe() method has no return value. If an error occurs within the method it can throw javax.ejb.EJBException or a custom exception.

The Record that is input to subscribe has attributes that are Java and/or J2EE Connector types. These attributes have been mapped from the original TIBCO ActiveEnterprise data types by the adapter. See Appendix D, TIBCO ActiveEnterprise to J2EE Connector Mapping, on page 415 for information on the mapping between TIBCO ActiveEnterprise and J2EE Connector data types.


Custom Exception Handling | 413

Custom Exception Handling

Custom Exception handling in inbound request-response service facilitates translation of application exceptions (Business Exceptions) generated from an EJB to an exception in TIBCO ActiveEnterprise.

When the EJB application encounters an error, it can throw custom exceptions in the form of a java object. This exception object is constructed based on the exception class configured as Exception parameter in the operation class. The exception thrown from the Bean to the adapter can also be a string object. The adapter converts the exception class into an object of MInstance and returns it to the client.

The Code Generator generates the code for the operation if you specify the data and the exception classes in the Exception parameter.

To implement the custom exceptions, you need to add the code in the subscriber method in the bean code as per the requirement. The following code explains how an inbound bean can throw an exception with the exception data.

if(KUNNR.compareTo("9999")==0){System.out.println("Invalid customer ID, throwing Exception...");InvalidCustExceptionData invalidCustData=new

InvalidCustExceptionData();invalidCustData.setKUNNR(KUNNR);invalidCustData.setNAME1(NAME1);throw new InvalidCustException("InvalidCustException", invalidCustData);}

Here, InvalidCustExceptionData is the exception data class and it has the equivalent ActiveEnterprise class stored in the repository. The code generator generates the equivalent java class for this exception data class.

InvalidCustException is the Exception name configured in the operation. The code generator will generate equivalent java code for the Exception name. For more information on the generation of exception classes See Dependent Classes and Exceptions on page 298.



Deployment

The deployment descriptor for a server or subscriber bean does not require either the env-entry or resource-ref sections that are required for a request-response invocation/publisher bean.

For more information, see Deployment Descriptor on page 404.


| 415

Appendix D TIBCO ActiveEnterprise to J2EE Connector Mapping

This appendix lists the mapping details between the TIBCO ActiveEnterprise data types and Java data types and the one-to-one name mapping between the ActiveEnterprise Classes and the Record classes in Java.

Topics

• ActiveEnterprise to J2EE Connector Type Mapping, page 416

• ActiveEnterprise to J2EE Connector Name Mapping, page 418


416 | Appendix D TIBCO ActiveEnterprise to J2EE Connector Mapping

ActiveEnterprise to J2EE Connector Type Mapping

The following are the details of the mapping performed by the TIBCO Adapter for EJB between TIBCO ActiveEnterprise data types and Java data types.

Table 17 TIBCO ActiveEnterprise to J2EE Connector Type Mapping

Type Java

any java.lang.Object

string java.lang.String

fixed.p.s java.math.BigDecimal

boolean java.lang.Boolean

dateTime java.util.Date

date java.util.Date

time java.util.Date

i1, byte java.lang.Byte

i2 java.lang.Short

i4 java.lang.Integer

i8 java.lang.Long

ui1 java.lang.Byte

ui2 java.lang.Short

ui4 java.lang.Integer

ui8 java.lang.Long

r4 java.lang.Float

r8 java.lang.Double

binary.n byte[]

binary.1 byte


ActiveEnterprise to J2EE Connector Type Mapping | 417

char.n java.lang.String

char.1 java.lang.String (with length=1) or

java.lang.Character

sequence javax.resource.cci.IndexedRecord

union javax.resource.cci.MappedRecord / Actual Object.

class javax.resource.cci.MappedRecord / Actual Object.

void not supported presently

interval not supported presently

dateTime.tz not supported presently

Table 17 TIBCO ActiveEnterprise to J2EE Connector Type Mapping

Type Java



ActiveEnterprise to J2EE Connector Name Mapping

TIBCO Adapter for EJB needs one to one mapping between the ActiveEnterprise Classes and the Record classes in Java. Although the definition of AESchema allows the use of the listed characters while naming, these characters are not allowed in Java tokens. If the adapter detects an illegal character in the class schema, it dynamically generates a valid Java name by substituting the character by using the corresponding replacement string. The Code Generator uses the same logic while generating CCI data types. This name validation and substitution is applied to class names, sequence names, attribute names, operation names, parameter names, and schema exception names and types. This does not affect the one to one mapping between the TIBCO ActiveEnterprise Classes and the Record classes in Java and you can use these characters as needed.

Table 18 TIBCO ActiveEnterprise to J2EE Connector Name Mapping

Special Character Changes to

~ _a_

! _b_

@ _c_

# _d_

$ _e_

% _f_

^ _g_

& _h_

* _i_

( _j_

) _k_

- _l_

+ _m_

= _n_


ActiveEnterprise to J2EE Connector Name Mapping | 419

| _o_

{ _p_

} _q_

] _r_

[ _s_

< _t_

> _u_

? _v_

; _w_

. _x_

, (comma) _y_

: _z_

` (single quote) _A_

/ _B_

(space) _C_

\ _D_

" _E_

‘ (back quote) _F_

abstract _abstract_

boolean _boolean_

break _break_

byte _byte_

case _case_





catch _catch_

char _char_

class _class_

const _const_

continue _continue_

default _default_

do _do_

double _double_

else _else_

extends _extends_

final _final_

finally _finally_

float _float_

for _for_

goto _goto_

if _if_

implements implements_

import _import_

instanceof _instanceof_

int _int_

interface _interface_

long _long_

native _native_




ActiveEnterprise to J2EE Connector Name Mapping | 421

new _new_

package _package_

private _private_

protected _protected_

public _public_

return _return_

short _short_

static _static_

strictfp _strictfp_

super _super_

switch _switch_

synchronized _synchronized_

this _this_

throw _throw_

throws _throws_

transient _transient_

try _try_

void _void_

volatile _volatile_

while _while_

com _com_

java _java_

javax _javax_






| 423

Appendix E Uninstalling an Existing Connector and Glue Beans for your Application Server

This appendix provides guidelines on how to undeploy a connector for your application server, if you have an existing deployment of the connector and glue beans from an earlier version of the adapter.

It is important that you undeploy earlier versions of the connector and clean up the application server before you use ant deploy.

Topics

• Undeploying the Connector for BEA WebLogic Application Server 8.1/BEA WebLogic Application Server 8.1 with SP1, SP2, SP3 or SP4, page 424

• Undeploying the Connector for IBM WebSphere 5.1.x Application Servers, page 426

• Undeploying the Connector for JBoss 4.0.0, 4.0.1, 4.0.2, and 4.0.3 Application Servers, page 429


424 | Appendix E Uninstalling an Existing Connector and Glue Beans for your Application Server

Undeploying the Connector for BEA WebLogic Application Server

8.1/BEA WebLogic Application Server 8.1 with SP1, SP2, SP3 or SP4

This section describes how to uninstall an existing connector and its glue beans on Microsoft Windows and UNIX platforms.

Uninstalling the Connector and Glue Beans on Microsoft Windows PlatformsTo uninstall the connector and glue beans:

1. Start the WebLogic server.

2. Click Start > Programs > BEA WebLogic Platform 8.1 > Examples > WebLogic Server Examples > Server Admin Console to start the Administrator Console.


4. Click the Connector Modules under Deployments.

5. Right-click the TIBCO Connector module and select Delete to delete the connector module.

6. Remove the glue EJBs from the EJB modules.

7. Right-click the server name under the Servers folder, located on the left-hand side of the server console. Select the Start/Stop this server option. Click the Start/Stop tab and select the Graceful shutdown of this server option.

8. Undo the changes to setWLSEnv.cmd. Remove all references of TIBCO jar files from the %CLASSPATH% variable. These changes are made to the :setWLSEnv section of the batch file.

9. Remove the following environment variables if you have set them:— %TIBCO_TRA_HOME%

— %TIBCO_RV_HOME%

— %TIBCO_ADEJB_HOME%

— %TIBCO_TPCL_HOME%

— %TIBCO_JRE_HOME%


Uninstalling the Connector and Glue Beans on UNIX platformsTo uninstall the connector and glue beans:


Undeploying the Connector for BEA WebLogic Application Server 8.1/BEA WebLogic Application Server 8.1 with SP1, SP2,

1. Start the WebLogic server.

2. Start the Administration Console.


4. Click the Connector Modules under Deployments.

5. Right-click the TIBCO Connector module and select Delete to delete the connector module.

6. Remove the glue EJBs from the EJB modules.

7. Right-click the server name under the Servers folder, located on the left-hand side of the server console. Select the Start/Stop this server option. Click the Start/Stop tab and select the Graceful shutdown of this server option.

8. Undo the changes to setWLSEnv.sh. Remove all the references of TIBCO jar files from the $CLASSPATH variable.

9. Remove the following environment variables if you have set them.

— $TIBCO_TRA_HOME

— $TIBCO_RV_HOME

— $TIBCO_ADEJB_HOME

— $TIBCO_TPCL_HOME

— $TIBCO_JRE_HOME

10. Undo/remove any changes to $LD_LIBRARY_PATH, $SHLIB_PATH, or $LIBPATH in setWLSEnv.sh. Typically, the changes might be like this:

For HP-UX:




For AIX:


Restart the application server.



Undeploying the Connector for IBM WebSphere 5.1.x Application

Servers



1. On Microsoft Windows, select Start > Programs > IBM WebSphere > Application Server V5.1 > Start the Server to start the WebSphere Application Server 5.1 The application server may take a few minutes to start.

2. Select Start > Programs > IBM WebSphere > Application Server V5.1 > Administrative Console to start the administrative console. A browser with two panels is displayed.


4. Click the resource adapter link which shows the configuration page for the adapter. Under Additional Properties select J2C Connection Factories. Select the connection factory and delete it.

5. Click Save configuration to save to the master configuration.

6. Select the TIBCO resource adapter and click Delete to remove the adapter.


8. Click Enterprise Applications and select the glue EJBs for the TIBCO connector. Click stop and then click Uninstall to uninstall the glue beans.


10. Shut down the application server.


Undeploying the Connector for IBM WebSphere 5.1.x Application Servers | 427

11. Remove or delete all the TIBCO related jar files from <WAS_HOME>/lib/ext:— EjbSupport.jar

— GlBeansSupport.jar

— TIBCOrt.jar

— TIBCOxml.jar

— TIBCOtsm.jar

— TIBCOjms.jar

— TIBCrypt.jar

— tibrvj.jar

— xmlParserAPIs.jar

— xercesImpl.jar

Uninstalling the Connector and Glue Beans on UNIX PlatformsTo uninstall the connector and glue beans:

1. Go to the <WebSphere_HOME>/bin directory and run startServer <node_name>. The application server may take a few minutes to start.

2. Start the administrative console by opening the web browser and typing http://<hostname>:9090/admin. A browser with two panels is displayed.


4. Click the resource adapter link that shows the configuration page for the adapter. Under Additional Properties select J2C Connection Factories. Select the connection factory and delete it.


6. Select the TIBCO resource adapter and click Delete to remove the adapter.


8. Click Enterprise Applications and select the glue EJBs for the TIBCO connector. Click stop and then Uninstall to uninstall the glue beans.


10. Shut down the application server.



11. Remove or delete all the TIBCO-related jar files from <WAS_HOME>/lib/ext:— EjbSupport.jar

— GlBeansSupport.jar

— TIBCOrt.jar

— TIBCOxml.jar

— TIBCOtsm.jar

— TIBCOjms.jar

— TIBCrypt.jar

— tibrvj.jar

— xmlParserAPIs.jar

— xercesImpl.jar

12. Undo or remove any changes to $LD_LIBRARY_PATH, $SHLIB_PATH, or $LIBPATH in <WAS_HOME>/bin/startServer.sh. The changes will be typically like this.

TIBCO_RV_HOME=<TIBCO Rendezvous installation directory>export TIBCO_RV_HOMEPLATFORM=`/bin/uname`case $PLATFORM in AIX)EXTSHM=ONLIBPATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LIBPATHexport LIBPATH EXTSHM ;;

Linux:

LD_LIBRARY_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LD_LIBRARY_PATHexport LD_LIBRARY_PATH ;;

SunOS:

LD_LIBRARY_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$LD_LIBRARY_PATHexport LD_LIBRARY_PATH ;;

HP-UX:

SHLIB_PATH="$WAS_LIBPATH":$TIBCO_RV_HOME/lib:$SHLIB_PATH

export SHLIB_PATH ;;


Undeploying the Connector for JBoss 4.0.0, 4.0.1, 4.0.2, and 4.0.3 Application Servers | 429

Undeploying the Connector for JBoss 4.0.0, 4.0.1, 4.0.2, and 4.0.3

Application Servers



1. Shut down the JBoss server.

2. Delete AeConnector.rar and AeConnector-ds.xml from the <JBOSS_HOME>\server\default\deploy directory.

3. If you have set the following environment variables, reset them to default values:






4. Undo the modifications to run.bat under <JBOSS_HOME>\bin. Typically, the changes will be:

set TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_RV_HOME%\lib\tibrvj.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOrt.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOjms.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCrypt.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOtsm.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TRA_HOME%\lib\TIBCOxml.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbSupport.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\GlBeansSupport.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\AeConnector.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbAdapter.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TPCL_HOME%\lib\xmlParserAPIs.jarset TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_TPCL_HOME%\lib\xercesImpl.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\server\default\lib\jboss-j2ee.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\jmx-client.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\jboss-common-client.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\concurrent.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\client\log4j.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\lib\dom4j.jarset TIBCLASSPATH=%TIBCLASSPATH%;%JBOSS_HOME%\lib\jboss-system.jarset JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%JAVAC_JAR%;%RUNJAR%;%TIBCLASSPATH%



Uninstalling the Connector and Glue Beans on UNIX PlatformsTo uninstall the connector and glue beans:

1. Shut down the JBoss server.

2. Delete AeConnector.rar and AeConnector-ds.xml from the <JBOSS_HOME>\server\default\deploy directory.

3. If you have set the following environment variables, reset them to default values:






4. Undo the modifications to run.sh under <JBOSS_HOME>\bin. Typically, the changes will be:

export TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_RV_HOME/lib/tibrvj.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOrt.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOjms.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCrypt.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOtsm.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TRA_HOME/lib/TIBCOxml.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/EjbSupport.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/GlBeansSupport.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_ADEJB_HOME/lib/AeConnector.jarexport TIBCLASSPATH=%TIBCLASSPATH%;%TIBCO_ADEJB_HOME%\lib\EjbAdapter.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TPCL_HOME/lib/xmlParserAPIs.jarexport TIBCLASSPATH=$TIBCLASSPATH:$TIBCO_TPCL_HOME/lib/xercesImpl.jarexport TIBCLASSPATH=$TIBCLASSPATH:$JBOSS_HOME/server/default/lib/jboss-j2ee.jarexport TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/jmx-client.jarexport TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/jboss-common-client.jarexport TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/concurrent.jarexport TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/client/log4j.jarexport TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/lib/dom4j.jarexport TIBCLASSPATH=$TIBCLASSPATH;$JBOSS_HOME/lib/jboss-system.jarexport JBOSS_CLASSPATH=$JBOSS_CLASSPATH:$JAVAC_JAR:$RUNJAR:$TIBCLASSPATH


| 431

Appendix F Regeneration and Incremental Deployment of Glue Beans for Automatic Deployment

In earlier versions of the adapter, the code was generated using the adapter palette and then the glue beans and the connector were manually deployed to the application server. However, the adapter now offers the option to automate the deployment of the adapter and glue beans to the application server using an Ant script. This feature is useful to the existing users of the adapter.

Topics

• Regenerating Glue Beans, page 432

• Incremental Deployment of New Glue Beans Using Ant Script, page 433


432 | Appendix F Regeneration and Incremental Deployment of Glue Beans for Automatic Deployment

Regenerating Glue Beans

To regenerate the glue EJB code for automatic deployment using Ant script, you must:

• Un-install the existing connector and glue beans from the application server

• Regenerate the glue bean code using the current version of the adapter palette.

• Deploy the connector and glue beans to the application server using the ant script.

Task A Uninstall the existing connector and glue beans from the application server

To uninstall the connector and the glue beans, see Appendix E, Uninstalling an Existing Connector and Glue Beans for your Application Server, on page 423.

Task B Regenerate the glue bean code using the current version of the adapter palette

The adapter uses the XDoclet code generation engine to generate the glue EJB code. The XDoclet code generation engine uses special tags in EJB java code to generate the rest of the code. Introduction of these special tags is done by the adapter palette during code generation. So it is important to re-generate the glue bean code using the latest adapter palette. For details on how to generate the glue bean code, see Generate the Code on page 74.

TIBCO strongly recommends saving the glue bean code for later use if you want to incrementally deploy new beans after the initial adapter deployment using the automatic deployment feature. This will help package the new glue beans with the old glue beans in one deployable archive.

Task C Deploy the connector and glue beans to the application server using the ant script

Once you generate the glue beans using the adapter palette, you can automatically deploy the glue beans and the connector for your application server, using ant script. For details, see Chapter 4, Preparing EJB Application Interfaces, page 97.


Incremental Deployment of New Glue Beans Using Ant Script | 433

Incremental Deployment of New Glue Beans Using Ant Script

If the glue beans and the connector were deployed using the ant script and you want to deploy a set of new glue beans, do the following:

• Undeploy the connector and the glue beans using the ant target

• Redeploy the connector and new beans using the ant script.

BEA WebLogic Application Server 8.1 and BEA WebLogic Application Server 8.1 with SP1, SP2, SP3, SP4, SP5, or SP6

Automatically Deploying the Connector on Microsoft Windows Platforms

1. Complete steps 1 through 4 in the section Running ant target deploy.adapter.weblogic81 from ant script on page 110.

2. Run the ant target by typing the command ant undeploy.adapter.weblogic81 at the command prompt. This will undeploy the connector and the glue beans from the application server.

3. Make sure the old glue bean code and the new glue bean code is in the directory specified in the tibco.ejb.gen.code.dir variable in step 1. This will ensure that the new and the old glue bean code is packaged in one archive.

4. Complete the steps in the section Running ant target deploy.adapter.weblogic81 from ant script on page 110 to deploy the old beans, the new beans, and the connector in one archive.

Automatically Deploying the Connector on UNIX Platforms

1. Complete steps 1 through 4 in the section Running the ant target deploy.adapter.weblogic81 from the ant script on page 115.


3. Make sure the old glue bean code and the new glue bean code is in the directory specified in the tibco.ejb.gen.code.dir variable in step 1. This will ensure that the new and old glue bean code is packaged in one archive.

4. Complete the steps in the section Running the ant target deploy.adapter.weblogic81 from the ant script on page 115 to deploy the old beans, the new beans, and the connector in one archive.



BEA WebLogic Application Server 9.0, 9.1, and 9.2


1. Complete steps 1 through 4 in the section Running ant target deploy.adapter.weblogic90 from the ant script on page 120.


3. Make sure the old glue bean code and the new glue bean code is in the directory specified in the tibco.ejb.gen.code.dir variable in step 1. This will ensure that the new and old glue bean code is packaged under one archive.

4. Complete the steps in the section Running ant target deploy.adapter.weblogic90 from the ant script on page 120 to deploy the old beans, new beans, and the connector in one archive.


1. Complete steps 1 through 4 in the section Running ant target deploy.adapter.weblogic90 from the ant script on page 125.


3. Make sure the old glue bean code and the new glue bean code is in the directory specified in the tibco.ejb.gen.code.dir variable in step 1. This will make sure the new and old glue bean code is packaged under one archive.

4. Complete the steps in the section Running ant target deploy.adapter.weblogic90 from the ant script on page 125 to deploy the old beans, new beans, and the connector in one archive.

JBoss 4.0.x Application Server


1. Complete steps 1 through 4 in the section Running ant target deploy.adapter.jboss40 from the ant script on page 169.



2. Run the ant target by typing the command ant undeploy.adapter.jboss40 at the command prompt. This will undeploy the connector and the glue beans from the application server.

3. Make sure the old glue bean code and the new glue bean code is in the directory specified in the tibco.ejb.gen.code.dir variable in step 1. This will make sure the new and the old glue bean code is packaged in one archive.

4. Complete the steps in the section Running ant target deploy.adapter.jboss40 from the ant script on page 169 to deploy the old beans, new beans, and the connector in one archive.


1. Complete steps 1 through 4 in the section Running ant target deploy.adapter.jboss40 from the ant script on page 174.

2. Run the ant target by typing the command ant undeploy.adapter.jboss40 at the command prompt. This will undeploy the connector and the glue beans from the application server.


4. Complete the steps in the section Running ant target deploy.adapter.jboss40 from the ant script on page 174 to deploy the old beans, new beans, and the connector in one archive.

IBM WebSphere Application Server 5.1.x


1. Complete steps 1 through 4 in the section Running ant target deploy.adapter.was51 from the ant script on page 132.

2. Run the ant target by typing the command ant undeploy.adapter.was51 at the command prompt. This will undeploy the connector and the glue beans from the application server.


4. Complete the steps in the section Running ant target deploy.adapter.was51 from the ant script on page 132 to deploy the old beans, new beans, and the connector.








IBM WebSphere Application Server 6.0.2 and 6.1

Automatically Deploying on Microsoft Windows Platforms


2. Run the ant target by typing the command undeploy.adapter.was60 at the command prompt. This will undeploy the connector and the glue beans from the application server.




1. Complete steps 1 through 4 in the section Running ant target deploy.adapter. was60 from the ant script on page 142.





4. Complete the steps in the section Running ant target deploy.adapter. was60 from the ant script on page 142 to deploy the old beans, new beans and the connector.




| 439

Appendix G Frequently Asked Questions

This appendix lists answers to the frequently asked questions.

Topics

• Frequently Asked Questions, page 440


440 | Appendix G Frequently Asked Questions

Frequently Asked Questions

What is the purpose of the adapter?

It provides bi-directional connectivity between Java 2 SDK Enterprise Edition (J2EE) applications and TIBCO Active Enterprise

What are the TIBCO software included in the adapter installation package?

TIBCO Adapter for EJB <version_number>.

What are the JCA versions that the adapter complies to?

JCA 1.5 and JCA 1.0.

What is the EJB specification version that the adapter complies to?

EJB 2.1, EJB 2.0, and EJB 1.1.

Which are the application servers currently supported?

• For Microsoft Windows platforms, see , Supported Application Servers, on page 34.

• For Unix platforms, see , Supported Application Servers, on page 42

Does TIBCO adapter for EJB provide a container for EJB?

No. TIBCO Adapter for EJB does not provide container for EJB.

In what modes can the adapter be deployed (Publication/Subscription/Request-Response)?

The adapter supports four modes of operation: publish, subscribe, request-response invocation, and request-response server.These operations are referred to as Publication, Subscription, Request-Response Server, and Request-Response Invocation services.

What components make up the adapter instance and deployment (GUI/ Publisher/ Subscriber/ TIBCO Administrator/ other)?

• J2EE Connector library

• Adapter Process

• EJB Code Generator


Frequently Asked Questions | 441

• TIBCO Designer with the custom palette.

What quality of service options are offered in the adapter?

If TIBCO Rendezvous is used as the transport, the following quality of service options are available:

• Reliable

• Certified


If JMS is used as the transport, the following connection factory type options are available:

• Queue

• Topic

If JMS is used as the transport, the following delivery mode options are available:

• Non persistant

• Persistant

Fault Tolerance is not supported at present.

Which versions of the EJB spec is the adapter currently compliant with?

TIBCO Adapter for EJB 5.3 supports both EJB 1.1, EJB 2.0, and EJB 2.1 Specifications.

Can I use the bean programs and jar files created by TIBCO Adapter for EJB 3.1.1?

You can use the bean programs and jar files created by TIBCO Adapter 3.1.1 in TIBCO Adapter for EJB 4.1.0, 5.0.1, 5.1.0, 5.1.1, 5.1.2, 5.2, and 5.3.

If my TIBCO Rendezvous license has expired, will I be able to perform any operation?

If the TIBCO Rendezvous license has expired, you will not be able to perform any operation using TIBCO Rendezvous. In the adapter, the Sender and Receiver use the same TIBCO Rendezvous sessions. If your TIBCO Rendezvous license expires when the adapter is running, you will still be able to invoke the bean but will not be able to publish/send the data on TIBCO Rendezvous.

Why does the adapter startup fail, even after specifying the appropriate DAT file?

Make sure that the repository server has been started, before starting the adapter.



Can I run the adapter as a Microsoft Windows service? If yes, how?

Yes, you can run the adapter either as a console application (adejb --run) or as a Microsoft Windows service. Use the following options to install and start the adapter as a Microsoft Windows service:adejb --install

adejb --start

During installation of the adapter, if a wrong entry is configured for the Java library, the installer script displays an error, but does not give me an opportunity to correct the error. How do I correct the Java library entry?

The workaround for this is to continue and complete the installation with the wrong Java library (ignore the unable to load the Java library error). On completion of the installation, open the file adejbpostinstall.tra located in the %TIBCO_ADEJB_HOME%\bin directory. Update the value for the java.library attribute with the correct value.

Can I run the EJB adapter and Application Server on two different systems?

Yes. You can run the adapter and the application server on two different systems (that is, in a distributed environment).

Can EJB adapter connect to multiple application servers at a time?

TIBCO Adapter for EJB 5.2 (and higher) can connect to different applications at a time. You can configure different adapter services (subscription and request-response services) of a single adapter instance to connect to different application servers. This feature is only available if the adapter is installed for multiple application server support.

Adapter versions earlier than 5.2 cannot connect to multiple application servers at a time.

Why does an error appear saying, port is in use appear when trying to restart the application server after shutting down on UNIX?

When an application server is started, it typically spawns a TIBCO Rendezvous daemon processes. This daemon inherits the ports (file descriptors or sockets) of the application server. When the application server is shut down, the spawned RVD daemon still continues to hold the inherited application server ports and therefore will not let the application server restart. To workaround this, kill the spawned rvd processes before shutting down the application server.

While deploying the ExampleBeans.jar, the following error appears



"weblogic.management.DistributedManagementException: Distributed Management [1 exceptions]" on the WebLogic 6.1 console on Microsoft Windows.Why does this happen?

This error appears when you do the following:

1. Deploy the AeConnector.rar and ExampleBeans.jar files.

2. Undeploy ExampleBeans.jar.

3. Restart the Application server and try to redeploy the ExampleBeans.jar.

To overcome the error follow these steps:

1. Browse to the /<Application server home>/config/mydomain/application folder.

2. Delete the AeConnector.rar and ExampleBeans.jar files.


4. Deploy AeConnector.rar and then ExampleBeans.jar.

Can I run the adapter and WebLogic 6.1 Application Server on two different systems?

Yes. You can run the adapter and the application server on two different systems. However, the connector component must be run in the application server.

When I try to compile a Java program in the EJB 4.1.0 environment, I get the error: "Java.lang.InternalError: jzentry == 0 at java.util.zip.ZipFile$2.nextElement(Unknown Source)…" Why does this happen?

If you are using Sun JDK 1.3.x, this is due to an acknowledged Java compiler bug in this version of the JDK. You can refer to the Sun site for more details. (Sun bug #4353705)

http://developer.java.sun.com/developer/bugParade/bugs/4353705.html

According to the Sun site, this bug is fixed in JDK 1.3.1_03.

Why is inbound communication handled by an external adapter process, while outbound communication is handled by a JCA 1.0 compliant connector?

There is no direct access to the enterprise bean when it is running within the container. The container manages the beans and clients typically access it through wrapper classes provided by the container, which include security checks. Therefore, a message cannot simply be delivered to the bean.

Additionally, there is a difficulty associated with bean lifetimes. A message listener should run continuously. However, session and entity beans are typically instantiated in response to the client’s RMI requests and may be garbage collected, or returned to a not-ready state when the client has finished using them.



The EJB version 1.1 specification does not provide a standard mechanism for instantiating a long-lived listener class for messages. The EJB 2.0 specification addresses this through the creation of a new type of EJB: a message-driven bean. However JCA 1.5 compliant EJB adapter it is possible to have inbound as well as outbound communication handler by connector deployed in to application server.

The solution adopted in the adapter is to use an external adapter process to handle inbound communication. This allows inbound message handling to be supported even in EJB 1.1 servers (the same approach will also work in EJB 2.0 servers). EJB 2.0 users can also use JMS to call a message-driven bean. However, in many cases, the JMS implementations provided by application server vendors do not interoperate with TIBCO messaging, and so are not an option for communication with TIBCO services.

Can I install and configure TIBCO Adapter for EJB to run on a machine other than the one the application server is running on?

OR

Can the application server and TIBCO Adapter for EJB each be installed and configured to run on different machines?

Yes. This is possible.

In many deployment scenarios, the application server, the adapter, and other TIBCO software are all installed on a single machine.

However, sometimes you may not want to set up the adapter and TIBCO software on the same machine as the application server. Such a scenario is called Remote Deployment Setup.

When should I consider installing TIBCO Adapter for EJB on a different machine than the one on which the application server is installed?

OR

Under what cases should I consider using the Remote Deployment Setup?

You could consider such a setup if:

1. If you have EJBs that are driving critical business logic

2. Those EJBs are deployed and running on an application server

3. The application server is in a production environment



4. The machine running the application server does not already have existing installations of TIBCO software

5. You do not want to disturb this existing setup too much

You might not want to disturb the setup by installing TIBCO software (including the adapter) on the application server machine.

In such a scenario, the TIBCO software including the adapter, are installed on a different machine than the one hosting the application server.

However, at a minimum, the following components must be installed on the machine hosting the application server, even in the Remote Deployment Setup.

• The Glue Beans generated by the adapter during service configuration will have to be installed on the machine hosting the application server.

• If you want to use either the Publication service or the Request-Response Invocation service, you will have to deploy the connector on the machine hosting the application server. For details, see the following FAQ.

During Remote Deployment Setup, which components will I need to install on the machine hosting the application server and the machine hosting the adapter and why?

This depends on the type of service you are using.

On the machine hosting the application server:

• For the Subscription and Request-Response Server services: The Glue Beans generated during the service configuration are deployed in the application server. The deployed Glue beans are invoked by the adapter using Java/RMI and therefore, neither the application server nor any of its deployed components need access to TIBCO Runtime Agent.

• For the Publication and Request-Response Invocation services: Both, the connector that is shipped with the adapter, and the Glue Beans, are deployed in the application server. The connector needs access to TIBCO Rendezvous, TIBCO Runtime Agent, and the TIBCO Enterprise Message Service client packages (if JMS transport is used) for its data translation and messaging capabilities. For details on the software version that is compatible with the adapter, see the TIBCO Adapter for EJB readme.txt file.

On the machine hosting the adapter and/or TIBCO Runtime Agent:

• For the Subscription and Request-Response Server services: The adapter needs access to the application server's J2EE implementation classes, so that it can invoke its services, such as Context, Lookup, and so on.

• For the Publication and Request-Response Invocation services: The machine hosting the adapter and/or TIBCO Runtime Agent does not need access to any additional components.



See some suggested options of enabling access to the application server's J2EE classes, and enabling access to TIBCO Runtime Agent.

During the Remote Deployment Setup, what are some of the options to get the application server/connector to access TIBCO Runtime Agent? Also, what are some of the options to get the adapter to access the application server's J2EE implementation libraries?

On the machine hosting the application server

Some of the options to access these components are:

• For the Subscription and Request-Response Server services: None. Except for the deployed Glue Beans, no other access is required. These services are executed on the Adapter machine.

• For the Publication and Request-Response Invocation services: The connector needs access to TIBCO Rendezvous, TIBCO Runtime Agent, and TIBCO Enterprise Message Service (if JMS transport is used) for data translation and messaging capabilities.

Some options are:

• TIBCO Rendezvous: The connector needs to connect to a running rvd daemon or start a new rvd daemon. You could:

Install TIBCO Rendezvous on the machine hosting the application server (contact your TIBCO representative for details)

OR

Map drives (in case of Microsoft Windows) or mount partitions (in case of UNIX) containing the TIBCO Rendezvous installation and add TIBCO_RV_HOME/bin to the path of the application server machine. The Connector is then able to start rvd on the application server machine, using the rvd in its path.

• TIBCO Rendezvous: The connector needs access to TIBCO Rendezvous implementation jar files. You could:

Install TIBCO Rendezvous on the machine hosting the application server (contact your TIBCO representative for details)

OR

Map drives (in case of Microsoft Windows) or mount the particular partition (in case UNIX) containing the TIBCO Rendezvous installation and appropriately add the location to the classpath of the application server.

• TIBCO Runtime Agent: The connector needs access to TIBCO Runtime Agent implementation jar files. You could:



Install TIBCO Runtime Agent on the machine hosting the application server (please contact your TIBCO representative for details)

OR

Map drives (in case of Microsoft Windows) or mount the particular partition (in case of UNIX) containing the TIBCO Runtime Agent installation and appropriately add the location to the classpath of the application server.

• TIBCO Enterprise Message Service Client packages: The connector needs a running JMS Server to connect to, if JMS transport is used by the configured adapter services. This JMS server can be running on a remote machine. You could:

Install TIBCO Enterprise Message Service Client packages on the machine hosting the application server (contact your TIBCO representative for details)

OR

Map drives (in case of Microsoft Windows) or mount the particular partition (in case of UNIX) containing the TIBCO Enterprise Message Service installation and start the JMS Server from the mapped location.

On the machine hosting TIBCO Adapter for EJB and/or TIBCO Runtime Agent

• For the Subscription and Request-Response Server services: The adapter needs access to the application server's J2EE implementation classes, so that it can invoke its services, such as Context, Lookup, and so on. In case of some application server implementations, the adapter also needs the stubs generated by the application server when the glue beans are deployed. Some options are:

— Application Server J2EE implementation: Most application servers do not have a client installation which typically is needed for executing client applications on a particular machine. Hence, the entire J2EE implementation jar has to be made available on the client machine.

You could map drives (in case of Microsoft Windows) or mount the particular partition (in case of UNIX) containing the Application Server installation and appropriately add the location of this jar to the adapter classpath.

— Glue Beans Stub: Stubs generated by the application server get generated on the application server machine during deployment and in some application server implementations, these are required for the execution of



the client application while they lookup the EJBHome, and so on. You could:

Copy the Stubs generated on the application server machine on the adapter machine and add the location to the classpath of the adapter.

OR

Map drives (in case of Microsoft Windows) or mount the particular partition (in case of UNIX) containing the stubs of the glue beans and appropriately add the location of the jar to the adapter classpath.

• For the Publication and Request-Response Invocation services: The machine hosting the adapter and/or TIBCO Runtime Agent does not need any access to any additional components. These services are executed on the application server machine.


| 449

Glossary

A

activationThe process of transferring an enterprise bean from secondary storage to memory.

application clientA first-tier client component that executes in its own Java virtual machine. Application clients have access to some (JNDI, JDBC, RMI-IIOP, JMS) J2EE platform APIs.

application serverA software server that lets thin clients use applications and databases that are managed by the server. The application server handles all the application operations and connections for the clients.

B

beanA Bean is a reusable software component that can be visually manipulated in builder tools. Beans can be combined to create traditional applications, or their smaller web-oriented brethren, applets. In addition, applets can be designed to work as reusable Beans.

bean managed persistenceData transfer between an entity bean's variables and a resource manager managed by the entity bean.

bean managed transactionA transaction whose boundaries are defined by an enterprise bean.

business logicThe code that implements the functionality of an application. In the Enterprise JavaBeans model, this logic is implemented by the methods of an enterprise bean.

business methodA method of an enterprise bean that implements the business logic or rules of an application.

C

CCICommon Client Interface. It is an API that allows J2EE clients to access an underlying EIS.

character setsA standard collection of characters. A character set may include letters, digits, punctuation, control codes, graphics, mathematical symbols, and other signs. Each character in the set is represented by a unique character code, which is a binary number used for storage and transmission.

character encodingCharacter encoding is a table in a font or a computer operating system that maps character codes to glyphs in a font. Most operating systems today represent character codes with an 8-bit unit of data known as a byte. Thus, character encoding tables today are restricted to at most 256 character codes. Not all operating system manufacturers use the same character encoding. For example, the Macintosh platform uses the standard Macintosh character set as defined by Apple Computer, Inc., while the Microsoft Windows operating system uses


450 | Glossary

another encoding entirely, as defined by Microsoft. Fortunately, standard Type 1 fonts contain all the glyphs needed for both these encodings, so they work correctly not only with these two systems, but others as well.

code generatorTIBCO Adapter for EJB provides a GUI-based EJB code generation tool which automates the process of generating EJB code and deployment descriptors for beans that access or use TIBCO ActiveEnterprise services. The code generator tool can generate deployment descriptors for EJB Specification version 1.1 and 2.0.

componentAn application-level software unit supported by a container. Components are configurable at deployment time. The J2EE platform defines four types of components: enterprise beans, Web components, applets, and application clients.

component contractThe contract between a component and its container. The contract includes: life cycle management of the component, a context interface that the instance uses to obtain various information and services from its container, and a list of services that every container must provide for its components.

connectionA set of interfaces and classes that represent the connection to the underlying EIS.

connection factoryA set of interfaces and classes that provide an application component with a Connection instance to an EIS.

connectorA standard extension mechanism for containers to provide connectivity to enterprise information systems. A connector is specific to an enterprise information system and consists of a resource adapter and application development tools for enterprise information system connectivity. The resource adapter is plugged in to a container

through its support for system-level contracts defined in the Connector architecture.

containerAn entity that provides life-cycle management, security, deployment, and runtime services to components. Each type of container (EJB, Web, JSP, servlet, applet, and application client) also provides component-specific services.

container managed persistenceData transfer between an entity bean's variables and a resource manager managed by the entity bean's container.

container managed transactionA transaction whose boundaries are defined by an EJB container. An entity bean must use container-managed transactions.

CORBACommon Object Request Broker Architecture. A language-independent distributed object model specified by the Object Management Group (OMG).

create methodA method defined in the home interface and invoked by a client to create an enterprise bean.

D

DDDeployment Descriptor. It is a configuration file with a predefined format that all J2EE compliant Web applications and Enterprise Java Beans (EJBs) must use, and that all J2EE compliant servers must know how to read.

deployerThe process whereby software is installed into an operational environment.

deploymentThe process whereby software is installed into an operational environment.


Glossary | 451

deployment descriptorAn XML file provided with each module and application that describes how they should be deployed. The deployment descriptor directs a deployment tool to deploy a module or application with specific container options and describes specific configuration requirements that a deployer must resolve.

destinationIn the JMS world, a destination is the object a client uses to specify the target of messages it produces and the source of messages it consumes. In the PTP messaging domain, destinations are called queues.

distributed applicationAn application made up of distinct components running in separate runtime environments, usually on different platforms connected via a network. Typical distributed applications are two tier (client and server), three tier (client and middleware and server), and multi-tier (client and multiple middleware and multiple servers).

DTDDocument Type Definition. It defines the way an XML document should be constructed. The DTD adds portability to an XML document's extensibility, resulting not only in flexible data, but data that can be processed and validated by any machine that can locate the document's DTD.

E

EAIEnterprise Application Integration.

EAR fileEnterprise Archive file. A JAR archive that contains a J2EE application.

EISEnterprise Information System.

EJBEnterprise Java Bean. It is a server-side component that encapsulates the business logic of an application.

EJB containerA container that implements the EJB component contract of the J2EE architecture. This contract specifies a runtime environment for enterprise beans that includes security, concurrency, life cycle management, transactions, deployment, naming, and other services. An EJB container is provided by an EJB or J2EE server.

EJB container providerA vendor that supplies an EJB container.

EJB contextAn object that allows an enterprise bean to invoke services provided by the container and to obtain the information about the caller of a client-invoked method.

EJB home objectAn object that provides the life cycle operations (create, remove, find) for an enterprise bean. The class for the EJB home object is generated by the container's deployment tools. The EJB home object implements the enterprise bean's home interface. The client references an EJB home object to perform life-cycle operations on an EJB object. The client uses JNDI to locate an EJB home object.

EJB jar fileA JAR archive that contains an EJB module.

EJB moduleA software unit that consists of one or more enterprise beans and an EJB deployment descriptor.

EJB objectAn object whose class implements the enterprise bean's remote interface. A client never references an enterprise bean instance directly; a client always references an EJB object. The class of an


452 | Glossary

EJB object is generated by a container's deployment tools.

EJB serverSoftware that provides services to an EJB container. For example, an EJB container typically relies on a transaction manager that is part of the EJB server to perform the two-phase commit across all the participating resource managers. The J2EE architecture assumes that an EJB container is hosted by an EJB server from the same vendor, so it does not specify the contract between these two entities. An EJB server may host one or more EJB containers.

EJB server providerA vendor that supplies an EJB server.

endpointAn endpoint is a node in the repository that represents the services an adapter provides. Publisher, subscriber, client, or server instance in the adapter application.

enterprise beanA component that implements a business task or business entity and resides in an EJB container; either an entity bean, session bean, or message-driven bean.

Enterprise Information SystemThe applications that comprise an enterprise's existing system for handling company-wide information. These applications provide an information infrastructure for an enterprise. An enterprise information system offers a well-defined set of services to its clients. These services are exposed to clients as local or remote interfaces or both. Examples of enterprise information systems include enterprise resource planning systems, mainframe transaction processing systems, and legacy database systems.

Enterprise Java BeansDefines the queries for the finder and select methods of an entity bean with container-managed persistence. A subset of

SQL92, EJB QL has extensions that allow navigation over the relationships defined in an entity bean's abstract schema.

entity beanAn enterprise bean that represents persistent data maintained in a database. An entity bean can manage its own persistence or can delegate this function to its container. An entity bean is identified by a primary key. If the container in which an entity bean is hosted crashes, the entity bean, its primary key, and any remote references survive the crash.

F

first tier componentThe set of components that make up the interface to the user and interact with the middle tier, such as the business logic.

G

glue beanA bean generated by the code generator that serves as a bridge between a legacy EJB and the TIBCO Adapter for EJB. The bean contains information such as the schema of the legacy bean, JNDI information and the configured TIBCO services. The type of glue beans generated differ depending on the type of service or mode of communication.

H

handleAn object that identifies an enterprise bean. A client may serialize the handle, and then later


Glossary | 453

de-serialize it to obtain a reference to the enterprise bean.

home interfaceOne of two interfaces for an enterprise bean. The home interface defines zero or more methods for managing an enterprise bean. The home interface of a session bean defines create and remove methods, while the home interface of an entity bean defines create, finder, and remove methods.

I

IIOPInternet Inter-ORB Protocol. A protocol used for communication between CORBA object request brokers.

inbound communicationFlows of data in to an EJB in the application server from a TIBCO-enabled application, through the adapter.

inbound glue beanA bean generated by the code generator that serves as a bridge between a legacy EJB and the standalone executable adapter component. The bean contains information such as the schema of the legacy bean, JNDI information and the configured TIBCO services. It contains an EJB code skeleton, which has empty bodies for the bean method implementations. These can be filled in with business logic. The bean implementation will be called by the adapter executable process when incoming requests are received by that process from the TIBCO message transport.

J

java beans componentA Java class that can be manipulated in a visual builder tool and composed into applications. A Java Beans component must adhere to certain property and event interface conventions.

J2EEJava 2 Platform Enterprise Edition. It is a platform that provides a component-based approach to the design, development, assembly, and deployment of enterprise applications. It offers a multi-tiered distributed application model, the ability to reuse components, integrated XML-based data interchange, a unified security model, and flexible transaction control.

J2EE applicationAny deployable unit of J2EE functionality. This can be a single module or a group of modules packaged into an EAR file with a J2EE application deployment descriptor. J2EE applications are typically engineered to be distributed across multiple computing tiers.

J2EE productAn implementation that conforms to the J2EE platform specification.

J2EE serverThe runtime portion of a J2EE product. A J2EE server provides EJB or Web containers or both.

JARJava Archive. A platform-independent file format that permits many files to be aggregated into one file.

J2SDKJava 2 Software Development Kit. Sun's implementation of the J2EE platform. This implementation provides an operational definition of the J2EE platform.

JCAJava Connector Architecture. It defines a


454 | Glossary

standard architecture for connecting the J2EE platform to heterogeneous EISs.

JDBCJava Database Connectivity. An API for database-independent connectivity between the J2EE platform and a wide range of data sources.

JMSJava Messaging Service. It is an API that allows applications to create, send, receive, and read messages. The JMS API defines a common set of interfaces and associated semantics that allow programs written in the Java programming language to communicate with other messaging implementations.

JMS applicationOne or more JMS clients that exchange messages.

JMS clientA Java language program that sends or receives messages.

JMS providerA messaging system that implements the Java Message Service as well as other administrative and control functionality needed in a full-featured messaging product.

JMS sessionA single-threaded context for sending and receiving JMS messages. A JMS session can be non transacted, locally transacted, or participating in a distributed transaction.

JNDIJava Naming and Directory Interface. It is an API that provides naming and directory functionality to applications written Java. It is defined to be independent of any specific directory service implementation.

JNIJava Native Interface. It defines a standard naming and calling convention so the Java virtual machine (JVM) can locate and invoke native methods.

JSPJava Server Pages. An extensible Web technology that uses template data, custom elements, scripting languages, and server-side Java objects to return dynamic content to a client. Typically the template data is HTML or XML elements, and in many cases the client is a Web browser.

JSP applicationA stand-alone Web application, written using the Java Server Pages technology, that can contain JSP pages, servlets, HTML files, images, applets, and Java Beans components.

JSP containerA container that provides the same services as a servlet container and an engine that interprets and processes JSP pages into a servlet.

JVMJava Virtual Machine. The runtime environment of the Java platform.

L

life cycleThe framework events of a component's existence. Each type of component has defining events which mark its transition into states where it has varying availability for use. For example, a servlet is created and has its init method called by its container prior to invocation of its service method by clients or other servlets that require its functionality. After the call of its init method it has the data and readiness for its intended use. The servlet's destroy method is called by its container prior to the ending of its existence so that processing associated with winding up may be done, and resources may be released. The init and destroy methods in this example are callback methods. Similar considerations apply to all J2EE component types: enterprise beans, Web


Glossary | 455

components (servlets or JSP pages), applets, and application clients.

lookupEvery kind of EJB component (session, entity, and message driven) has a home interface. The home interface is a bean's base of operations; once you've found it, you have access to that bean's functionality. EJB applications look up the JNDI to access their beans' home interfaces. Since EJB applications tend to run multiple beans, and because JNDI lookups are often present in many components, much of an application's performance overhead can be spent on these lookups.

M

mapped recordA data class belonging to the Java Connector Architecture specification. It typically holds data mapped in from an EIS.

MDBMessage Driven Bean. It is an enterprise bean that allows J2EE applications to process messages asynchronously. It acts as a JMS message listener, which is similar to an event listener except that it receives messages instead of events. A message-driven bean has no state for a specific client, but its instance variables may contain state across the handling of client messages, including an open database connection and an object reference to an EJB object. A client accesses a message-driven bean by sending messages to the destination for which the bean is a message listener.

messageIn the Java Message Service, an asynchronous request, report, or event that is created, sent, and consumed by an enterprise application, not by a human. It contains vital information needed to coordinate enterprise applications, in the form of

precisely formatted data that describes specific business actions.

message consumerAn object created by a JMS session that is used for receiving messages sent to a destination.

message producerAn object created by a JMS session that is used for sending messages to a destination.

moduleA software unit that consists of one or more J2EE components of the same container type and one deployment descriptor of that type. There are three types of modules: EJB, Web, and application client. Modules can be deployed as stand-alone units or assembled into an application.

N

naming contextA set of associations between unique, atomic, people-friendly identifiers and objects.

non-JMS clientA messaging client program that uses a message system's native client API instead of the Java Message Service.

O

objectAn object is a software bundle of related variables and methods. Software objects are often used to model real-world objects you find in everyday life. The important thing about an object is what is does, not what it has. The latter is an implementation matter.

operation classAn operation class is a node in the repository


456 | Glossary

that holds method names of operations that can be invoked in the EIS.

outbound communicationFlows of data out from an EJB in the application server, through the connector, and in to a TIBCO-enabled application.

outbound glue beanA bean generated by the code generator that serves as a bridge between a legacy EJB and the connector library component. The bean contains information such as the schema of the legacy bean, JNDI information and the configured TIBCO services. It contains a complete EJB with home interface, remote interface, bean implementation class, and deployment descriptor. The resulting bean will use the J2EE Connector library to interface with a TIBCO ActiveEnterprise component.

P

passivationThe process of transferring an enterprise bean from memory to secondary storage.

persistenceThe protocol for transferring the state of an entity bean between its instance variables and an underlying database.

point-to-point messaging systemA messaging system built around the concept of message queues. Each message is addressed to a specific queue; clients extract messages from the queue(s) established to hold their messages.

publish/subscribe messaging systemA messaging system in which clients address messages to a specific node in a content hierarchy. Publishers and subscribers are generally anonymous and may dynamically publish or subscribe to the content hierarchy. The system takes care of distributing the

messages arriving from a node's multiple publishers to its multiple subscribers.

Q

queueA simple data structure for managing the time-staged delivery of requests to servers. Queued elements may be sorted in some order of priority. Clients insert items in the queue and servers remove items from the queue, as soon as possible, in batch, or periodically.

In data handling, a queue is a temporary holding structure in which values can be stored until needed. A queue is organized in such a way that the first item added to the queue is also the first item out of the queue. This processing is known as FIFO, for first-in, first-out. Job and print queues are perhaps the best known for those who work with computers.

R

RARResource Adapter Archive. A JAR archive that contains a resource adapter.

referenceA reference (to an object) is a pointer to an object in memory, and is held in a variable. It can also be viewed as an alias (an alternate name) for an object.

remote interfaceOne of two interfaces for an enterprise bean. The remote interface defines the business methods callable by a client.

resource adapterA system-level software driver that is used by an EJB container or an application client to connect to an enterprise information system. A resource


Glossary | 457

adapter is typically specific to an enterprise information system. It is available as a library and is used within the address space of the server or client using it. A resource adapter plugs into a container. The application components deployed on the container then use the client API (exposed by the adapter) or tool-generated high-level abstractions to access the underlying enterprise information system. The resource adapter and EJB container collaborate to provide the underlying mechanisms--transactions, security, and connection pooling--for connectivity to the enterprise information system.

resource managerProvides access to a set of shared resources. A resource manager participates in transactions that are externally controlled and coordinated by a transaction manager. A resource manager is typically in a different address space or on a different machine from the clients that access it. Note: An enterprise information system is referred to as a resource manager when it is mentioned in the context of resource and transaction management.

RMIRemote Method Invocation. A technology that allows an object running in one Java virtual machine to invoke methods on an object running in a different Java virtual machine.

RMI-IIOPA version of RMI implemented to use the CORBA IIOP protocol. RMI over IIOP provides interoperability with CORBA objects implemented in any language if all the remote interfaces are originally defined as RMI interfaces.

RPCRemote Procedure Call. A technology that allows an object running in one Java virtual machine to invoke methods on an object running in a different Java virtual machine.

RVTIBCO Rendezvous Service.

RVCMTIBCO Rendezvous Certified Messaging Service.

RVCMQTIBCO Rendezvous Certified Messaging Queues Service.

S

servletA Java program that extends the functionality of a Web server, generating dynamic content and interacting with Web clients using a request-response paradigm.

servlet containerA container that provides the network services over which requests and responses are sent, decodes requests, and formats responses. All servlet containers must support HTTP as a protocol for requests and responses, but may also support additional request-response protocols, such as HTTPS.

servlet contextAn object that contains a servlet's view of the Web application within which the servlet is running. Using the context, a servlet can log events, obtain URL references to resources, and set and store attributes that other servlets in the context can use.

sessionAn object used by a servlet to track a user's interaction with a Web application across multiple HTTP requests.

session beanAn enterprise bean that is created by a client and that usually exists only for the duration of a single client-server session. A session bean performs operations, such as calculations or accessing a database, for the client. Although a


458 | Glossary

session bean may be transactional, it is not recoverable should a system crash occur. Session bean objects can be either stateless or can maintain conversational state across methods and transactions. If a session bean maintains state, then the EJB container manages this state if the object must be removed from memory. However, the session bean object itself must manage its own persistent data. It is an EJB that performs a task for a client. It represents a single client inside the J2EE server.

stateful session beanA session bean with a conversational state.

stateless session beanA session bean with no conversational state. All instances of a stateless session bean are identical.

T

topicIn the publication/subscription messaging domain of JMS, a topic is the object a client uses to specify the target of messages it produces and the source of messages it consumes. In the PTP messaging domain, destinations are called queues.

transactionAn atomic unit of work that modifies data. A transaction encloses one or more program statements, all of which either complete or roll back. Transactions enable multiple users to access the same data concurrently.

transaction managerProvides the services and management functions required to support transaction demarcation, transactional resource management, synchronization, and transaction context propagation.

U

unicodeA 16-bit character set that assigns unique character codes to characters in a wide range of languages. Unlike ASCII, which defines 128 distinct characters typically represented in 8 bits, there are as many as 65,536 distinct Unicode characters that represent the unique characters used in many languages.

W

WAR fileWeb Archive file. A JAR archive that contains a Web module.

web componentA component that provides services in response to requests; either a servlet or a JSP page.

web containerA container that implements the Web component contract of the J2EE architecture. This contract specifies a runtime environment for Web components that includes security, concurrency, life-cycle management, transaction, deployment, and other services. A Web container provides the same services as a JSP container as well as a federated view of the J2EE platform APIs. A Web container is provided by a Web or J2EE server.

web serverSoftware that provides services to access the Internet, an intranet, or an extranet. A Web server hosts Web sites, provides support for HTTP and other protocols, and executes server-side programs (such as CGI scripts or servlets) that perform certain functions. In the J2EE architecture, a Web server provides services to a Web container. For example, a Web container typically relies on a Web server to provide HTTP message handling. The J2EE


Glossary | 459

architecture assumes that a Web container is hosted by a Web server from the same vendor, so does not specify the contract between these two entities. A Web server may host one or more Web containers.

X

XMLExtended Markup Language. A markup language that allows you to define the tags (markup) needed to identify the content, data, and text in XML documents. It differs from HTML, the markup language most often used to present information on the internet. HTML has fixed tags that deal mainly with style or presentation. An XML document must undergo a transformation into a language with style tags under the control of a stylesheet before it can be presented by a browser or other presentation mechanism. Two types of style sheets used with XML are CSS and XSL. Typically, XML is transformed into HTML for presentation. Although tags may be defined as needed in the generation of an XML document, a document type definition (DTD) may be used to define the elements allowed in a particular type of document. A document may be compared with the rules in the DTD to determine its validity and to locate particular elements in the document. J2EE deployment descriptors are expressed in XML with DTDs defining allowed elements. Programs for processing XML documents use SAX or DOM APIs. J2EE deployment descriptors are expressed in XML.

XSLExtensible Stylesheet Language. An XML transformation language used for transforming XML documents into documents with flow object tags for presentation purposes. The transformation aspect of XSL has been abstracted into XSLT, with the XSL name now used to

designate the presentation flow language. XSL is a direct descendent of the DSSSL style language for SGML (Standard Generalized Markup Language), the language from which XML was sub-setted. It was designed to have all the capabilities of CSS, the stylesheet often used with HTML. XSL flow objects can be presented by specialized browsers and can themselves be transformed into PDF documents.

XSLTXSL Transformation. An XML file that controls the transformation of an XML document into another XML document or HTML. The target document often will have presentation-related tags dictating how it will be rendered by a browser or other presentation mechanism. XSLT was formerly part of XSL, which also included a tag language of style flow objects.


460 | Glossary


TIBCO Software Inc. End User License Agreement | 461

TIBCO Software Inc. End User License AgreementREAD THIS END USER LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING THE SOFTWARE, YOU AGREE TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE TO THESE TERMS, DO NOT DOWNLOAD OR INSTALL THE SOFTWARE AND RETURN IT TO THE VENDOR FROM WHICH IT WAS PURCHASED.

Upon your acceptance as indicated above, the following shall govern your use of the Software except to the extent all or any portion of the Software (a) is subject to a separate written agreement, or (b) is provided by a third party under the terms set forth in an Addenda at the end of this Agreement, in which case the terms of such addenda shall control over inconsistent terms with regard to such portion(s).

License Grant. The Software is the property of TIBCO or its licensors and is protected by copyright and other laws. While TIBCO continues to own the Software, TIBCO hereby grants to Customer a limited, non-transferable, non-exclusive, license to use the Number of Units set forth in the Ordering Document, in machine-readable, object code form and solely for Customer's internal business use.

Restrictions. Customer agrees not to (a) make more copies than the Number of Units plus a reasonable number of backups; (b) provide access to the Software to anyone other than employees, contractors, or consultants under written contract with Customer agreeing to be bound by terms at least as protective of TIBCO as those in this End User License Agreement ("Authorized Users"); (c) sublicense, transfer, assign, distribute to any third party, pledge, lease, rent, or commercially share the Software or any of Customer's rights under this Agreement (for the purposes of the foregoing a change in control of Customer is deemed to be an assignment); (d) use the Software for purposes of providing a service bureau, including, without limitation, providing third-party hosting, or third-party application integration or application service provider-type services, or any similar services; (e) use the Software in connection with ultrahazardous activities, or any activity for which failure of the Software might result in death or serious bodily injury to Customer or a third party; or (f) directly or indirectly, in whole or in part, modify, translate, reverse engineer, decrypt, decompile, disassemble, make error corrections to, create derivative works based on, or otherwise attempt to discover the source code or underlying ideas or algorithms of the Software.

Beta and Evaluation Licenses. Notwithstanding the foregoing, if the Software is being provided for demonstration, beta testing, or evaluation purposes, then Customer agrees (a) to use the Software solely for such purposes, (b) that the Software will not be used or deployed in a production or development environment, and (c) that such use shall automatically terminate upon the earlier of thirty days from the date Customer receives the right to install the Software, or Customer's receipt of notice of termination from TIBCO.

Technical Support. Provided Customer has paid applicable support fees (not included with Software fees unless separately listed), TIBCO shall provide support for generally available Software ("Maintenance") on an annual basis commencing on the Purchase Date. Thereafter Maintenance will be automatically renewed for successive one (1) year terms at the then current rates. Customer shall designate at TIBCO's support website https://support.tibco.com/eSupport/newuser.html, the number of authorized contacts as permitted by TIBCO based on the level of Maintenance purchased (contacts are changeable upon 48-hours prior written notice to TIBCO). Each contact may contact TIBCO for problem resolution during TIBCO's published support hours corresponding to the level of Maintenance purchased.

Upon notice from a contact of a Software problem which can be reproduced at a TIBCO Maintenance facility, TIBCO shall use reasonable efforts to correct or circumvent the problem according to its published maintenance objectives. TIBCO reserves the right to make changes only to the most currently available version. TIBCO will use reasonable efforts to support the previously released version of the Software for a maximum of six months.

Maintenance Fees for lapsed Maintenance or the changing of the level of Maintenance shall be mutually agreed upon between Customer and TIBCO. Upgrades, patches, enhancements, bug fixes, new versions and/or new releases of the Software provided from time to time under Maintenance shall be used only as replacements to existing copies, and shall not be deemed to increase the Number of Units, and use thereof shall be governed by the terms of this Agreement, except for the first paragraph of the Limited Warranty and any right of return or refund.

Services. Customer may request additional services ("Services") either in an Ordering Document, or by a separate mutually executed work order, statement of work or other work-request document incorporating the term of this End User License Agreement (each, a "Work Order"). Unless otherwise expressly agreed to in a Work Order, all Services and any work product therefrom shall be (a) performed on a time and materials basis, plus meals, lodging, travel, and other expenses reasonably incurred in connection therewith, (b) deemed accepted upon delivery, and (c) exclusively owned by TIBCO (except for Confidential Information of Customer), including all right, title and intellectual property or other right or interest therein. Each Work Order is intended to constitute an independent and distinct agreement of the parties, notwithstanding that each shall be construed to incorporate all applicable provisions of this End User License Agreement. Fees for Services shall be due and payable in United States dollars net 30 from the date of TIBCO's invoice.

Limited Warranty. If Customer obtained the Software directly from TIBCO, then TIBCO warrants that for a period of thirty (30) days from the Purchase Date: (i) the media on which the Software is furnished will be free of defects in materials and workmanship under normal use; and (ii) the Software will substantially conform to its Documentation. This limited warranty extends only to the original Customer hereunder. Customer's sole and exclusive remedy and the entire liability of TIBCO and its licensors under this limited warranty will be, at TIBCO's option, repair, replacement, or refund of the Software and applicable Maintenance fees, in which event this End User License Agreement shall terminate upon refund thereof.

This warranty does not apply to any Software which (a) is licensed for beta, evaluation, testing or demonstration purposes for which TIBCO does not receive a license fee, (b) has been altered or modified, except by TIBCO, (c) has not been installed, operated, repaired, or maintained in accordance with instructions supplied by TIBCO, (d) has been subjected to abnormal physical or electrical stress, misuse, negligence, or accident, or (e) is used in violation of any other term of this End User License Agreement. Customer agrees to pay TIBCO for any Maintenance or Services provided by TIBCO related to a breach of the foregoing on a time, materials, travel, lodging and other reasonable expenses basis. If Customer obtained the Software from a TIBCO reseller or distributor, the terms of any warranty shall be as provided by such reseller or distributor, and TIBCO provides Customer no warranty with respect to such Software.

EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY, THE SOFTWARE, MAINTENANCE AND SERVICES ARE PROVIDED "AS


462 | TIBCO Software Inc. End User License Agreement

IS", ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, SATISFACTORY QUALITY OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE, ARE HEREBY EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE LAW. CERTAIN THIRD PARTY SOFTWARE MAY BE PROVIDED TO CUSTOMER ALONG WITH CERTAIN TIBCO SOFTWARE AS AN ACCOMMODATION TO CUSTOMER. THIS THIRD PARTY SOFTWARE IS PROVIDED "AS IS". CUSTOMER MAY CHOOSE NOT TO USE THIRD PARTY SOFTWARE PROVIDED AS AN ACCOMMODATION BY TIBCO. NO WARRANTY IS MADE REGARDING THE RESULTS OF ANY SOFTWARE, MAINTENANCE OR SERVICES OR THAT THE SOFTWARE WILL OPERATE WITHOUT ERRORS, PROBLEMS OR INTERRUPTIONS, OR THAT ERRORS OR BUGS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE'S FUNCTIONALITY, MAINTENANCE OR SERVICES WILL MEET CUSTOMER'S REQUIREMENTS. NO TIBCO DEALER, DISTRIBUTOR, AGENT OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, EXTENSIONS OR ADDITIONS TO THIS WARRANTY.

Indemnity. If Customer obtained the Software from TIBCO directly, then TIBCO agrees at its own expense to defend or, at its option, to settle, any claim or action brought against Customer to the extent it is based on a claim that the unmodified Software infringes any patent issued by the United States, Canada, Australia, Japan, or any member of the European Union, or any copyright, or any trade secret of a third party; and TIBCO will indemnify and hold Customer harmless from and against any damages, costs and fees reasonably incurred (including reasonable attorneys' fees) that are attributable to such claim or action and which are assessed against Customer in a final judgment; provided that TIBCO is promptly notified in writing of such claim, TIBCO has the exclusive right to control such defense and/or settlement, and Customer shall provide reasonable assistance (at TIBCO's expense) in the defense thereof. In no event shall Customer settle any claim, action or proceeding without TIBCO's prior written approval. In the event of any such claim, litigation or threat thereof, TIBCO, at its sole option and expense, shall (a) procure for Customer the right to continue to use the Software or (b) replace or modify the Software with functionally equivalent software. If such settlement or modification is not commercially reasonable (in the reasonable opinion of TIBCO), TIBCO may cancel this End User License Agreement upon sixty days prior written notice to Customer, and refund to Customer the unamortized portion of the license fees paid to TIBCO by Customer based on a five-year straight-line depreciation. This Section states the entire liability of TIBCO with respect to the infringement of any intellectual property rights, and Customer hereby expressly waives any other liabilities or obligations of TIBCO with respect thereto. The foregoing indemnity shall not apply to the extent any infringement could have been avoided by use of the then-current release.

Limitation of Liability. EXCEPT AS PROVIDED UNDER INDEMNITY OR RESULTING FROM A BREACH OF CONFIDENTIALITY (THE "EXCLUDED MATTERS"), IN NO EVENT WILL EITHER PARTY OR TIBCO'S LICENSORS BE LIABLE FOR ANY LOST DATA, LOST REVENUE, LOST PROFITS, DAMAGE TO REPUTATION, BUSINESS INTERRUPTION, OR ANY OTHER INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, PUNITIVE, EXEMPLARY OR ANY SIMILAR TYPE DAMAGES ARISING OUT OF THIS AGREEMENT, THE USE OR THE INABILITY TO USE THE SOFTWARE, OR THE PROVISION OF ANY MAINTENANCE OR SERVICES, EVEN IF A PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. EXCEPT FOR THE EXCLUDED MATTERS, IN NO EVENT SHALL A PARTY BE LIABLE TO THE

OTHER, WHETHER IN CONTRACT, TORT (INCLUDING ACTIVE OR PASSIVE NEGLIGENCE), BREACH OF WARRANTY, CLAIMS BY THIRD PARTIES OR OTHERWISE, EXCEED THE PRICE PAID BY CUSTOMER UNDER THE APPLICABLE ORDERING DOCUMENT.

THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF ITS ESSENTIAL PURPOSE. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO CUSTOMER.

Confidentiality. "Confidential Information" means the terms of this End User License Agreement; all information marked by the disclosing party as proprietary or confidential; any provided software, related documentation or related performance test results derived by Customer; and any methods, concepts or processes utilized in provided software or related documentation. Confidential Information shall remain the sole property of the disclosing party and shall not be disclosed to any non-Authorized User of either TIBCO or Customer without the prior written consent of the disclosing party. If Confidential Information is communicated orally, such communication shall be confirmed as "Confidential" in writing within thirty days of such disclosure. The parties agree to protect the Confidential Information of the other in the same manner it protects the confidentiality of similar information and data of its own (and at all times exercising at least a reasonable degree of care). Except with respect to the Software, items will not be deemed Confidential Information if (i) available to the public other than by a breach of an agreement with TIBCO, (ii) rightfully received from a third party not in breach of any obligation of confidentiality, (iii) independently developed by one party without use of the Confidential Information of the other; (iv) known to the recipient at the time of disclosure (other than under a separate confidentiality obligation); or (v) produced in compliance with applicable law or court order, provided the other party is given reasonable notice of the same. Both parties agree to indemnify the other for any damages the other may sustain resulting from their unauthorized use and/or disclosure of the other's Confidential Information. Such damages shall include reasonable expenses incurred in seeking both legal and equitable remedies. To the extent required by law, at Customer's request, TIBCO shall provide Customer with the interface information needed to achieve interoperability between the Software and another independently created program, on payment of TIBCO's applicable fee. Customer agrees to observe obligations of confidentiality with respect to such information.

Export. Software, including technical data, is subject to U.S. export control laws, including the U.S. Export Administration Act and its associated regulations, and may be subject to export or import regulations in other countries. Customer agrees to comply strictly with all such regulations and agrees to obtain all necessary licenses to export, re-export, or import Software.

Government Use. If the Customer is an agency, department, or other entity of the United States Government ("Government"), the use, duplication, reproduction, release, modification, disclosure or transfer of the Software, or any related documentation of any kind, including technical data or manuals, is restricted in accordance with Federal Acquisition Regulation ("FAR") 12.212 for civilian agencies and Defense Federal Acquisition Regulation Supplement ("DFARS") 227.7202 for military agencies. The Software is commercial computer software and commercial computer software documentation. Use of the Software and related documentation by the Government is further restricted in accordance with the terms of this Agreement, and any modification thereto.


TIBCO Software Inc. End User License Agreement | 463

Orders. An Ordering Document shall be deemed accepted only by issuance of a TIBCO invoice and solely for purposes of administrative convenience. None of the terms of the Ordering Document (other than the Software product name, Number of Units, level of Maintenance, description of Services, and fees due in connection therewith) shall apply for any reason or purpose whatsoever, regardless of any statement on any Ordering Document to the contrary, unless countersigned by an officer of TIBCO. This Agreement constitutes the entire agreement between the parties with respect to the use of the Software, Maintenance and Services, and supersedes all proposals, oral or written, and all other representations, statements, negotiations and undertakings relating to the subject matter hereof. All orders of Software, Maintenance or Services by Customer to TIBCO shall be deemed to occur with or without reference to, under the terms of this End User License Agreement, unless expressly superseded by a signed written agreement between the parties. Software shall be delivered electronically, and such delivery shall be deemed complete when the Software is made available for download by Customer.

Term and Termination. Maintenance or Services may be terminated: (a) by either party upon a default of the other, such default remaining uncured for fifteen days from written notice from the non-defaulting party; (b) upon the filing for bankruptcy or insolvency of the other party, (c) by either party upon prior written notice at least ninety (90) days prior to the end of any annual Maintenance term; or (d) by Customer (for Services), upon ten days prior written notice. Termination of Maintenance or Services shall not terminate this End User License Agreement. Customer may terminate this End User License Agreement in its entirety at any time by destroying all copies of the Software. Upon termination of this End User License Agreement in its entirety, for any reason, Customer must cease using and return or destroy all copies of the Software. Customer's obligation to pay accrued charges and any fees due as of the date of termination, as well as the sections entitled "Confidentiality", "Limited Warranty" and "Limitation of Liability" shall survive any such termination.

Authority. You hereby represent and warrant that you have full power and authority to accept the terms of this End User License Agreement on behalf of Customer, and that Customer agrees to be bound by this End User License Agreement.

General. Fees on the Ordering Document (all to be paid on the latter of thirty days from Invoice by TIBCO or the date set forth in the Ordering Document) do not include sales, use, withholding, value-added or similar taxes, and Customer agrees to pay all sales, use, value-added, goods and services, consumption, withholding, excise and any other similar taxes or government charges, exclusive of TIBCO's income tax. Customer agree to pay all reasonable costs incurred (including reasonable attorneys' fees) in collecting past due amounts. Except as set forth in the Section entitled "Limited Warranty" all fees paid under or in connection with this End User License Agreement are non-refundable and no right of set-off exists. All payments of fees due shall be made in U.S. dollars, net 30 from Purchase Date, or, for any other amounts coming due hereafter, net 30 from TIBCO's invoice. A service charge of one and one-half percent per month will be applied to all invoices that are not paid on time. No delay in the performance of any obligation by either party, excepting all obligations to make payment, shall constitute a breach of this End User License Agreement to the extent caused by force majeure. Customer hereby grants TIBCO and its independent auditors the right to audit Customer's compliance with this End User License Agreement. If any portion of this End User License Agreement is found to be void or unenforceable, the remaining provisions shall remain in full force and effect. This End User License Agreement shall be governed by and construed in accordance with the laws of the State of California, United States of America, as if performed wholly within the state and without giving effect to the principles of conflict of

law. The United Nations Convention on Contracts for the International Sale of Goods is excluded from application hereto. If any portion hereof is found to be void or unenforceable, the remaining provisions of this Agreement shall remain in full force and effect.

Definitions. In connection with this End User License Agreement the following capitalized terms shall have the following meaning: "Connection" means for TIBCO SmartSockets and TIBCO SmartMQ, any network protocol link established with such Software (directly or indirectly) to any other entity, including but not limited to software, firmware or hardware; "Connected Processor" means a Processor that produces information or messages consumed by the relevant Software (excluding Processors on devices such as routers, switches, proxies, HTTP or application servers configured to substantially pass-through information or messages to TIBCO Software); "Customer" means the original purchaser or licensee of the Software and any permitted successors and assigns; "Developer" means a Named User of a TIBCO Software product for use only in Non-Production; "Documentation" means text material that accompanies the TIBCO Software on delivery; "Enterprise" means an unlimited Number of Units of the TIBCO Software set forth in an Ordering Document, deployed by Customer for a period of one (1) year (unless otherwise set forth in an Ordering Document) from the Effective Date (the "Enterprise Term"), at which time, the Number of Units then deployed in Production and Non-Production use by Customer becomes fixed and Customer may not thereafter deploy additional Units. During the Enterprise Term, Customer's right to deploy an unlimited Number of Units does not extend to any entity which acquires, is acquired by, merged into, or otherwise combined with Customer. Customer hereby agrees to provide TIBCO, within sixty (60) days after the end of the Enterprise Term, with written notice of the Number of Units deployed at the end of the Enterprise Term by License Type, Platform and Unit; "License Type" means the environment in which the TIBCO Software may be used (including without limitation, Production, Non-Production); "MSU" means Millions of Service Units per hour, based on the then current MSU rating established by IBM for IBM and IBM compatible hardware which is used for software pricing (not necessarily a direct indication of relative processor capacity) as set forth in IBM's generally available Large System Performance Reference; "Named User" means an identifiable individual, not necessarily named at the time of a license grant, designated by Customer to access the TIBCO Software, regardless of whether or not the individual is actively using the TIBCO Software at any given time; "Non-Production" means a non-operational environment into which the TIBCO Software may be installed, which is not processing live data, which is not running any operations of the Customer and which has not been deployed to permit any users to access live data. Non-Production environments include development, cold back-up, high availability, hot standby, and test environments; "Number of Units" means the cumulative number of copies of TIBCO Software licensed for use by type of Unit as set forth in this Agreement, or in an Ordering Document, and including, if applicable, as reported by Licensee upon expiration of a Project or Enterprise Term; "Ordering Document" means any purchase order or similar document or agreement requesting Software, Maintenance or Services; "Platform" means the operating system set forth in an Ordering Document; "Processor" means a central processing unit ("CPU") on which the TIBCO Software is licensed to run and which for the purposes of counting Processors on multicore chips, the number of Processors is the number of CPUs times the number of cores multiplied by .75.; "Processor Source Locked" means the number of connections to a single database made possible by (or licensed for) the relevant TIBCO Software regardless of how many Processors are used by the system or environment which is accessing the database; "Production" means an operational environment into which the licensed TIBCO Software has been installed, which is processing live data and which has been deployed so that the intended users of the


464 | TIBCO Software Inc. End User License Agreement

environment are able to access the live data; "Project" means an unlimited Number of Units for the License Type listed in this Agreement, to be deployed by Customer solely in connection with the undertaking described under an Ordering Document for a period of one (1) year (unless otherwise set forth in this Agreement) from the Effective Date (the "Project Term"), at which time, the Number of Units then deployed in Production and Non-Production use by Customer becomes fixed and Customer may not thereafter deploy additional Units. During the Project Term, Customer's right to deploy an unlimited Number of Units does not extend to any entity which acquires, is acquired by, merged into, or otherwise combined with Customer. Customer hereby agrees to provide TIBCO, within sixty (60) days after the end of the Project Term, with written notice of the Number of Units deployed at the end of the Project Term by Unit and License Type. "Purchase Date" means the date of the Ordering Document is accepted by TIBCO; "Server Instance" means a computer with 1 CPUs (unless otherwise specified in the Agreement) performing common services for multiple other machines; "Software" means the most current generally available object code version (as of the Purchase Date) of the software products listed in an Ordering Document (except as provided for beta or evaluation licenses), in whole and in part, including its Documentation; "Third Party Software" means third-party software identified by its company and/or product name, the provision of which by TIBCO is made solely as an accommodation and in lieu of Customer purchasing a license to Third Party Software directly from the third party vendor; "Trading Partner" means an entity or individual with which the Licensee engages in electronic commerce by means of TIBCO Software in accordance with this Agreement; "Unit" means a license restriction describing the manner in which a copy (or multiple copies) of the TIBCO Software may be deployed (including, without limitation, Processor, Named User, Connected Processor, and Processor Source Locked) and is the mechanism used to determine the Number of Units licensed pursuant to an Ordering Document.

Special Product Provisions. TIBCO BusinessPartner: Customer may sublicense to third parties ("Partners") up to the total Number of Copies of TIBCO BusinessPartner, provided that for every such sublicense, the Number of Copies Customer is licensed to use shall be reduced by the same number, and provided further that prior to delivery of TIBCO BusinessPartner to a Partner, such Partner agrees in writing (a) to be bound by terms and conditions at least as protective of TIBCO as the terms of this Agreement, (b) that TIBCO BusinessPartner be used solely to communicate with Customer's implementation of TIBCO BusinessConnect, and (c) for such Partner to direct all technical support and Maintenance questions directly to Customer. Customer agrees to keep records of the Partners to which it distributes TIBCO BusinessPartner, and to provide TIBCO the names thereof (with an address and contact name) within sixty days of the end of each quarter. Embedded/Bundled Products. Some TIBCO Software embeds or bundles other TIBCO Software (e.g., TIBCO InConcert bundles TIBCO Rendezvous). Use of such embedded or bundled TIBCO Software is solely to enable the functionality of the TIBCO Software licensed on the Cover Page, and may not be used or accessed by any other TIBCO Software, or for any other purpose. Open Source Software: If Customer uses Open Source software in conjunction with the TIBCO Software, Customer must ensure that its use does not: (i) create, or purport to create, obligations of use with respect to the TIBCO Software; or (ii) grant, or purport to grant, to any third party any rights to or immunities under TIBCO's intellectual property or proprietary rights in the TIBCO Software. You also may not combine the TIBCO Software with programs licensed under the GNU General Public License ("GPL") in any manner that could cause, or could be interpreted or asserted to cause, the TIBCO Software or any modifications thereto to become subject to the terms of the GPL.

Version 5.4, October 2006

Third-Party Software Notices

XDoclet 1.2.3

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ADDENDA: Third-Party Software License Agreements


Third-Party Software License Agreements | 465

Third-Party Software License AgreementsThe following are the software licenses for the Third-Party Software provided in connection with the software.

The XDoclet License, Version 1.2

Copyright (c) 2000-2004, XDoclet Team

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of the XDoclet team nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


466 | Third-Party Software License Agreements


| 467

Index

A

accessing the connection factory 377adapter

component (operation) information through TIBCO Hawk 269

adapter services 186adding adapter services

Request-Response Invocation Service 208Request-Response Service 201Subscription Service 194

addParam() 391agents 254alerts 254

C

certified quality of service 189, 195, 202, 209Class Microagent Name field, adapter 185cleanup() 394, 399client code generation 297code generator 289

class names 298dependent classes and exceptions 298deployment descriptor 299directory structure 298inbound communication 300inputs 292modes of operation 290necessity 291outbound communication 310outputs 297overview 290using generated glue beans 320working 290

code generator fieldsbean 292configuration URL 295deployment descriptor 293EJB name prefix 295EJB Spec Version 292indent level 296package root 293repository URL 295resource reference 294use resource reference 294

command line arguments 270Complex Data Types 411Components 3configuration properties, retrieving through TIBCO

Hawk 270creating a connection 378creating an Interaction 379Creating and Using an Interaction 379custom exception handling 384, 413

D

Data Type Translation 13Deployment 414Deployment Descriptor 404Distributed Queue 196, 203

E

endpoint 382Endpoint Reference 188, 195, 202, 209environment variables 40

Microsoft Windows Systems 40execute() 392


468 | Index

G

getHostInformation()Hawk method 273

getOutputs() 393global variables 227glue beans

generation for inbound communication 300generation for outbound communication 310necessity 291publication service 310request-response invocation service 314request-response server service 305using 320using with publication service 320using with request-response invocation service 321using with request-response server service 322using with subscription service 321

H

Handling Return Values 411Hawk methods

getHostInformation() 273preRegisterListener() 280

I

interaction 379creating 379usage

publication 381request-response 379

J

J2EE Integration 11JVM library

Microsoft Windows 35, 42

L

ledger filesretrieving information through TIBCO Hawk 282

Log File field, adapter 184Log Info field, adapter 184Log to Standard field, adapter 184

M

Message Subject 188Method Signatures Must Match 410microagent methods supported 261Microagent Session field, adapter 185

P

parametersreferences 188subjects 188

prepare() 390, 401preRegisterListener()

Hawk method 280publication service

glue beans 310Publication Service typical flow diagram 8

Q

qualities of service available 188, 202, 209Quality of Service 188, 195, 202, 209

R

Rapid Code Development 13Reliable quality of service 189, 195, 202, 209remove() 395, 402


Index | 469

request-response invocation serviceglue beans 314

request-response server serviceglue beans 305

reviewLedger, TIBCO Hawk method 282RPC Server Beans

handling return values 411RPC Support Library 387RPCSupport 388RPCSupport () 389

S

schemaexamples of use 14

setting environment variables 40Standard Microagent Name field, adapter 185Subscription Service

typical flow diagram 8substitution 227

T

TIBCO Connector limitations 382TIBCO Hawk

background information 254enterprise monitor components 254

TIBCO Hawk methodsgetComponents 269getConfig 270getRvConfig 275getStatus 276reviewLedger 282

TIBCO Rendezvous, retrieving configuration through TIBCO Hawk 275

Tracing and Error Messages 325Tracing Levels and Fields 328

U

using an Interaction 379

V

variable substitution 227variables 227

W

Wire Format 189, 196, 203, 210Writing ActiveEnterprise Server Beans 408Writing RPC Server Beans 410Writing Subscriber Beans 412


470 | Index


Date post:	23-Jul-2018
Category:	Documents
Upload:	hahanh
View:	228 times
Download:	0 times