TIBCO iProcess Java Plug-in

Two-Second Adv

TIBCO iProcess® Java

Plug-in

User’s GuideSoftware Release 11.4.1 April 2014

antage®

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 LICENSE.PDF) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

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

TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO Hawk, TIBCO Rendezvous, and TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

Enterprise Java Beans (EJB),Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2004-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

| i

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ivTIBCO iProcess Java Plug-in Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv

How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vTarget Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixHow to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Chapter 1 Introduction to EAI Java Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Why Use an EAI Java Step? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Overview of How an EAI Java Step Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Understanding the EAI Java Step Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Using Delayed Release or Immediate Release Invocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

EAI Java Step Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Transaction Scope of EAI Java Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2 Creating Your Java Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Using the EAI Java SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Implementing the Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Immediate Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Delayed Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Delayed Release and Withdraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Working with the Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Defining Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Error Logging Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Dynamic Loading of Java Objects (Advanced Topic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17XML Parsing (Advanced Topic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Manually Creating a Java Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Using the Example Java Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

TIBCO iProcess Java Plug-in User’s Guide

ii | Contents

Chapter 3 Defining EAI Java Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Creating an EAI Java Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Define Basic EAI Step Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Creating and Editing an EAI Java Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Define the Call to the Java Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Define iProcess Java Plug-in Input Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Define the iProcess Java Plug-in Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Using iProcess Array Fields as Input and Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Passing All Array Field Values to the Java Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Passing One Array Field Value to the Java Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 4 Migrating Procedures and Code From Previous Versions . . . . . . . . . . . . . . . . . . . . 35

Migrating Procedures From Versions Prior to i10.0(3.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Migrating Run-time Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Editing Run-time Code From Versions Prior to i10.0(3.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Editing Run-time Code From Version i10.0(3.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Appendix A Using the Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Setting Up Log4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44iProcess Engine Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44iProcess Workspace Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Java Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Appendix B Manually Performing a Delayed Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Manually Performing a Delayed Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Appendix C Return Values for getType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Appendix D Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Appendix E Configuring Database Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Database Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67


| iii

Preface

This guide describes how to define and use EAI Java steps in your iProcess procedures. EAI Java steps can be customized to perform the necessary business actions you require in your procedure (such as calling methods in Enterprise Java Beans or simply manipulating data via a Java object). The TIBCO iProcess Java Plug-in software consists of a Client plug-in, a Server plug-in and an SDK.

This guide is targeted at Java developers who are looking to use the TIBCO iProcess Java Plug-in product as an SDK to extend the functionality of the TIBCO iProcess® Engine.

Topics

• Related Documentation, page iv

• How to Use This Guide, page v

• Typographical Conventions, page vi

• Connecting with TIBCO Resources, page ix


iv | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO iProcess Java Plug-in DocumentationYou can find more information about the TIBCO iProcess Java Plug-in from the following sources:

• The TIBCO iProcess® Technology Plug-ins Installation Guide explains how to install the iProcess Java Server Plug-in.

• The TIBCO iProcess® Workspace Plug-ins Installation Guide explains how to install the iProcess Java Client Plug-in.

• The TIBCO iProcess® Modeler Integration Techniques guide explains how to integrate EAI steps with your enterprise applications.

• The HTML JavaDocs, supplied on the installation media for both the iProcess Technology Plug-ins and the iProcess Workspace Plug-ins, describe the interfaces that you can use when developing your custom Java objects. To access the JavaDocs, open the docs\javadocs\index.html file.

• The Release Notes, supplied with the software, provide any last-minute and version-specific information that could not be included in the main documentation.

• For the latest TIBCO iProcess product information, please refer to the TIBCO Support web site at http://www.tibco.com/services/supports.

• http://www.tibcommunity.com is a resource that delivers technical content to the TIBCO user community. This site has been developed to foster an open forum where users of TIBCO products can find valuable information and exchange ideas with other users. It includes working examples of iProcess Java processes and objects. Entry to this site requires a username and password. If you do not have a username, you can request one.


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

http://www.tibcommunity.com

Preface | v

How to Use This Guide

You should read Chapter 1, Introduction to EAI Java Steps, on page 1 first. This describes how an EAI Java step works.

• Chapter 2, Creating Your Java Object, on page 9 describes how to create a custom Java application that can be called from an EAI Java step in your procedure definition.

• Chapter 3, Defining EAI Java Steps, on page 21 describes how to define an EAI Java step in your iProcess procedure(s).

• Chapter 4, Migrating Procedures and Code From Previous Versions, on page 35 describes how to migrate procedures and run-time code (developed using a previous version of EAI Java) to use the new interfaces contained in this version.

• Appendix A, Using the Log Files, on page 39 describes how to configure error logging using Apache’s Log4J. It also provides information about the error messages that can be logged.

• Appendix B, Manually Performing a Delayed Release, on page 55 describes how to manually perform a delayed release action on an EAI Java step.

• Appendix C, Return Values for getType(), on page 59 describes the return values for the getType() function.

• Appendix D, Character Encoding, on page 61 describes important information about character encoding when an EAI Java step invocation is performed.

Target AudienceThis guide is aimed at the following types of user:

• Procedure definers

• Application developers and systems integrators

• Java developers


vi | Typographical Conventions

Typographical Conventions

Because this guide covers both Windows, UNIX and Linux versions of the iProcess Java Plug-in, this guide uses the Windows convention of a backslash (\). The equivalent pathname on a UNIX or Linux system is the same, but using the forward slash (/) as a separator character.

The following typographical conventions are used in this manual.

UNIX or Linux pathnames are occasionally shown explicitly, using forward slashes as separators, where a UNIX/Linux-specific example or syntax is required.

Any references to UNIX in this guide also apply to Linux unless explicitly stated otherwise.

Table 1 General Typographical Conventions

Convention Use

SWDIR Indicates the iProcess system directory where the iProcess™ Engine is installed.

Example:

If SWDIR is set to \swserver\staffw_nod1 then the full path to the swutil command would be:

• on a Windows server (on the c: drive):

c:\swserver\staffw_nod1\bin\swutil

• on a UNIX server:

/swserver/staffw_nod1/bin/swutil, or

$SWDIR/bin/swutil

Note: On a UNIX system, the environment variable $SWDIR should be set up to point to the iProcess system directory for the following users:

• root

• swadmin

• background user (default is pro).

SWCLIENT Indicates the directory where the TIBCO iProcess™ Workspace is installed.


Preface | vii

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font Bold code font is used in the following ways:

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

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

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]

italic font Italic font is used in the following ways:

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

• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName

Key combinations

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

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Table 1 General Typographical Conventions (Cont’d)

Convention Use


viii | Typographical Conventions

Table 2 Syntax Typographical Conventions

Convention Use

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

For example:

MyCommand [optional_parameter] required_parameter

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

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

MyCommand para1 | param2 | param3

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

For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}


Preface | ix

Connecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

How to Access TIBCO DocumentationYou can access TIBCO documentation here:

http://docs.tibco.com

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, contact TIBCO Support as follows:

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


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

https://support.tibco.com

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



https://support.tibco.com

http://docs.tibco.com

http://www.tibcommunity.com

x | Connecting with TIBCO Resources


| 1

Chapter 1 Introduction to EAI Java Steps

This chapter provides an overview of how EAI Java steps can be used, how they work and how they integrate with iProcess.

Topics

• Why Use an EAI Java Step?, page 2

• Overview of How an EAI Java Step Works, page 3

• EAI Java Step Architecture, page 5

• Transaction Scope of EAI Java Steps, page 7


2 | Chapter 1 Introduction to EAI Java Steps

Why Use an EAI Java Step?

EAI Java steps provide an open interface for you to create steps in your procedures that perform the tasks you require in your business process.

An EAI Java step enables you to design an iProcess procedure so that you can call out to a custom Java object to perform some additional work. This provides you with a very flexible and open architecture for enhancing your procedures.

For example, you can create a custom Java object to call business methods in Enterprise Java Beans (EJBs), call a database via a JDBC connection, or post a message on a Java Message Service (JMS) queue.

An EJB is a server-side component that encapsulates the business logic of an application. The business logic is the code that fulfills the purpose of the application. In a Human Resources application, for example, the EJBs might implement the business logic in methods called checkEmployeeBackground and orderUniform. By invoking these methods using the EAI Java step, you can access the services provided by the application.


Overview of How an EAI Java Step Works | 3

Overview of How an EAI Java Step Works

When you add an EAI Java step to your iProcess procedure, you can define a call to your custom Java object by defining the name of the Java object and (optionally) a list of input and output parameters.

The EAI Java step enables you to define the call to the Java object in the following ways:

• Input and Output - send iProcess fields and/or expressions to the Java object, and then pass data back to iProcess.

• Input only - send iProcess fields and/or expressions to the Java object.

• Output only - receive fields from the Java object.

• No input or output - call the Java object without any field and/or expression mappings.

Understanding the EAI Java Step ProcessWhen you install the iProcess Java Plug-in, the EAI Java Library is registered with the iProcess Engine. This library acts as the interface between your Java objects and the iProcess Engine.

The following sequence of events occurs each time a Java Object is called using the EAI Java step:

1. The Java Library is invoked. The library uses the Java Native Interface (JNI) to connect into a Java Virtual Machine (JVM) that is created when the iProcess Engine starts up.

2. iProcess field values and/or expressions and EAI Java step definition data are passed into a generic Java object that runs inside the JVM. The generic Java object uses the package name in the step definition data to identify your custom java object.

3. Your custom Java object is then instantiated or a cached instance is accessed (if the Java object has already been started). The setting of the Cache Object Between Invocations check box (see page 26) determines if the Java object is started or a cached version is used.

4. (Optional) The iProcess field and/or expression data is passed into your custom Java object by calling a defined method on it. You can just call the custom Java object without sending any case data - see Overview of How an EAI Java Step Works on page 3.



5. (Optional) If you want data to be returned to iProcess, it can be returned through the same method call, and is then used to update the iProcess case data.

Using Delayed Release or Immediate Release InvocationsThe EAI Java Plug-in SDK supports three different types of invocation: immediate release, delayed release or delayed release with withdraw. The invocation type you want to use must be defined in the custom Java object by implementing the appropriate interface(s). See Using the EAI Java SDK on page 11 for more information.

The invocation method you choose depends on the architecture of your system and how long the Java object will take to process its work. You need to make sure that the iProcess background process is not paused for long periods of time waiting for a response from the Java object. If this is likely to happen, you should use delayed release so that once the EAI Java step has been called, the background process can continue processing other work. If you also want the Java object to be notified if the EAI Java step is subsequently withdrawn, you should use delayed release with withdraw.

Delayed release is always part synchronous, part asynchronous. Immediate release is always synchronous.

For more information about delayed release and immediate release invocations, refer to “Using Enterprise Application Integration (EAI) Steps” in the TIBCO iProcess™ Modeler - Integration Techniques guide.

Example procedures, provided on the installation media for both the iProcess Technology Plug-ins and the iProcess Workspace Plug-ins, demonstrate the use of immediate release and delayed release invocations.


EAI Java Step Architecture | 5

EAI Java Step Architecture

The following diagram shows the architecture of a typical iProcess system with the iProcess Java Plug-in installed.

TIBCO iProcess Engine

EAI Java Step

Java Object

Business Process

iProcess Java Server Plug-in

Delayed Release Handler

JDBC Connection

Clie

ntS

erve

rJa

va O

bjec

t

TIBCO iProcess Database

TIBCO iProcess Modeler

iProcess Java Client Plug-in

TIBCO iProcess Workspace

Imm

ediate R

elease Ro

ute (S

ynchronous)D

elayed Release R

oute

(Asynchronous) - P

hase 2

Delayed R

elease R

oute (S

ynchronous) - P

hase 1



Client

The iProcess™ Modeler and iProcess™ Workspace enable the process definer to create the business process. The iProcess Java Client Plug-in is installed on the iProcess Workspace and allows the process designer to create EAI Java steps in the iProcess Modeler.

Server

The iProcess Java Server Plug-in is installed on the iProcess Engine. The iProcess Engine processes the procedure and any EAI Java steps are processed by the iProcess Java Server Plug-in.

Java Object

The Java object is the custom component that you need to create and call from the EAI Java step definition in the procedure. This performs the necessary task(s) you have coded, for example calling an EJB.


Transaction Scope of EAI Java Steps | 7

Transaction Scope of EAI Java Steps

When designing a procedure containing EAI Java steps, you need to consider the transaction implications in your system design. This is because this release does not support propagating a transaction context into a Java Virtual Machine through the Java Native Interface.

For example, suppose that an EAI Java step is linked to an EAI Database step. If there is a failure inside the EAI Database step, the transaction is aborted, and iProcess is rolled back to the point just before the execution of the EAI Java step. When the transaction is retried, the EAI Java step is re-processed. In this scenario, it is necessary to design your EAI Java object so that it can handle being called repeatedly without causing a problem.

Another consideration is that it is possible to design a deadlock into the procedure. For example, where there is an EAI Java step following an EAI Database step. If the EAI Java step uses JDBC to attempt to access a resource that the EAI Database step has used then a deadlock will occur. The EAI Database step does not relinquish its lock on the resource it has used until the transaction is complete, but the transaction will not complete until the EAI Java step has accessed the resource that the EAI Database step has locked.

Refer to “Using Enterprise Application Integration (EAI) Steps” in the TIBCO iProcess Modeler - Integration Techniques guide for more information about EAI steps and transactions.

If an EAI step is the first step in a procedure and it fails, the case is not started and nothing is recorded in the audit trail to say this.




| 9

Chapter 2 Creating Your Java Object

This chapter describes how to create the custom Java object(s) that will perform the external integration you require. After creating your Java object, you can call it from your EAI Java step in your iProcess procedure. Before creating your application, you should refer to Chapter 1 on page 1 to understand the EAI Java step process and architecture.

Topics

• Prerequisites, page 10

• Using the EAI Java SDK, page 11

• Implementing the Interfaces, page 13

• Working with the Interfaces, page 16

• Examples, page 18


10 | Chapter 2 Creating Your Java Object

Prerequisites

Before you start creating your Java object, you need access to the following resources:

• The SDK source files (EAIJSDK.jar and library files) are located on the product installation media for both iProcess Technology Plug-ins and iProcess Workspace Plug-ins, in the \sdk folder. Install the SDK by copying these files to the machine where you are building your Java object.

• Update the Java CLASSPATH to include the log4j-1.2.13.jar file.

• The JavaDocs contain detailed information about the interfaces and methods you can use when creating your custom Java object. It is recommended that you copy these files into your Integrated Development Environment (IDE).

The TIBCO iProcess Java Plug-in can be used with either JRE/JVM versions 1.5.0 or 1.6; for the exact versions, see TIBCO iProcess Technology Plug-ins Installation. Note that Java 1.4 is no longer supported.

It is important when you are compiling Java source code to work with the iProcess Java Plug-in that source code compatibility is set appropriately. Setting compatibility to Java 5 gives maximum flexibility in running on both 1.5 and 1.6 Java runtime environments.


Using the EAI Java SDK | 11

Using the EAI Java SDK

To extend the functionality of iProcess using Java it is necessary to write your own custom Java object(s) that are based on the EAI Java interfaces.

The iProcess Java Server Plug-in provides an SDK that contains a series of Java interfaces and objects contained in the EAIJSDK.jar file. This file must be imported into your build environment.

The interfaces are provided in the \sdk folder. Refer to Implementing the Interfaces on page 13 for more information about using them.

There are three Java packages within the EAIJSDK.jar file that form the SDK:

• com.staffware.eaijava

• com.staffware.eaijava.interfaces

• com.staffware.eaijava.delrel

The com.staffware.eaijava package contains the following interfaces:

• ImmediateReleasePluginSDK.

• DelayedReleasePluginSDK

• WithdrawablePluginSDK

Your custom Java object should implement these interfaces according to the iProcess invocation style that you want to use, as follows.

You must not change the contents of this file because the functionality of the iProcess Java Plug-in will be compromised.

The package also contains a GenericReleasePluginSDK interface. This interface is not supported in this release and its use is reserved for subsequent releases.

For more information about the EAIJSDK.jar contents, please refer to the JavaDocs.

Desired invocation style Use these interfaces

Immediate release ImmediateReleasePluginSDK

Delayed release DelayedReleasePluginSDK



Refer to:

• Using Delayed Release or Immediate Release Invocations on page 4 for more information about these invocation methods.

• Implementing the Interfaces on page 13 for more information about how to use the interfaces.

If you have been using a previous version of the iProcess Java Plug-in, refer to Chapter 4 on page 35 for detailed information about how to migrate your existing code and procedures to use the new interfaces.

Delayed Release and Withdraw

DelayedReleasePluginSDK and WithdrawablePluginSDK

Desired invocation style Use these interfaces


Implementing the Interfaces | 13

Implementing the Interfaces

Each interface is based on the SWPlugin Java interface (contained in the interfaces package). The SWPlugin interface contains an initialize method that must be implemented in your Java object. This method accepts a Java Properties object as a parameter; this properties object is initialized on your behalf and contains all of the properties listed in the EAI Java properties file (eaijava\properties).

Immediate Release The immediate release interface (ImmediateReleasePluginSDK) contains an execute method that must be implemented in your Java object. This method is called by the iProcess Java Plug-in and should contain the implementation of your bespoke functionality. The static data, iProcess field values and evaluated iProcess expressions specified at design-time are passed as parameters for this method.

The return data for this method is a Java map of iProcess field name / value pairs to be updated in the process. If no fields are to be updated, an empty Java map object should be returned.

Delayed Release The delayed release interface (DelayedReleasePluginSDK) contains two methods: executeSync and executeAsync. The synchronous method (executeSync) is called first and contains three additional parameters in addition to the ImmediateReleasePluginSDK: the iProcess delayed release ID that is generated by the TIBCO iProcess Engine at run-time, and the user name and message for the audit trail as contained in the EAI Java properties file. The executeAsync method is called second.

If you are using delayed release, you must use extreme caution if performing any thread related actions in your code. Using a sleep function is particularly discouraged.

Your Java object(s) must be included in the SWDIR\eaijava\libs\repository\user folder on the same machine as the iProcess Engine. Therefore, if you have developed the Java object on a development system, you need to copy it to the above location on the iProcess Engine. The iProcess Engine must be restarted after any change to the repository. Objects MUST NOT be updated or removed from the repository while the iProcess Engine is running.



It is important to note that the synchronous method operates synchronously with respect to the iProcess background process. Following completion of this method, the background process is detached and the asynchronous method is called. The executeAsync method contains a further parameter in addition to the executeSync method: the updated iProcess fields map (as returned by the executeSync method call) is passed as the syncFields parameter.

The asynchronous method permits long running work to be performed and operates within a separate Java thread to the main plug-in.

The return data for the executeSync method is a Java map object in the same way as for the ImmediateReleasePluginSDK. To indicate that a manual delayed release is desired, the executeAsync method should return null (refer to Appendix B on page 55 for more information).

iProcess field and expression data is specified in the execute interfaces using the Field interface. The standard iProcess field information is available within this object, including field name, type, length and number of decimal places where applicable. Further information can be found in the TIBCO iProcess™ Plug-in SDK: User's Guide. The Field interface also contains a reference to the value of the iProcess field or expression as evaluated at run-time.

Delayed Release and WithdrawThe delayed release and withdraw interface (WithdrawablePluginSDK) contains a single withdraw method, which contains the same parameters as the executeSync method in the DelayedReleasePluginSDK interface.

Your Java object should implement this method if it is also using the DelayedReleasePluginSDK and you want to be notified if the object’s step is withdrawn. There is no return data for this method.

By default, a Java thread is created for each delayed release execution. This can result in a large number of threads (and hence resource requirement) if many delayed release steps are being performed. This problem is exacerbated if the threads take a long time to complete (the bespoke Java code takes a long time to complete).

In the event that the iProcess Engine background processes were to crash, the associated Java threads would be destroyed and therefore the state of their work would be lost.


Implementing the Interfaces | 15

To use the delayed release and withdraw interface you must manually perform the delayed release - see Manually Performing a Delayed Release on page 55 for more information.

There is no guarantee that the same iProcess Engine background process will handle both the original EAI Java step callout and its withdrawal.

It is therefore the responsibility of your external system to make sure that the withdrawal is correlated with the original EAI Java step callout (for example, by using the delayed release ID).



Working with the Interfaces

The following sections describe other topics that you should take into consideration when implementing your chosen interfaces.

Defining ExceptionsIn the event of a problem within the Java object there are two types of exceptions defined in the API: the FatalPluginException and the NonFatalPluginException. These exceptions are available to the interface methods described previously with the exception that the delayed release asynchronous interface does not support non-fatal exceptions.

Non Fatal Exception

A non-fatal exception results in a warning being logged with no other action being required by the iProcess Engine.

Fatal Exception

A fatal exception signals to iProcess that an error should be logged and the current process transaction should be rolled back. Note that the delayed release invocation style commits the iProcess transaction after executing the synchronous method and before executing the asynchronous method for each EAI step. Rollback is therefore not possible for the asynchronous part of a delayed release EAI call and a fatal exception can be logged for a synchronous call (to both iProcess and the logging system) however a fatal exception cannot be recorded in the iProcess log file (and audit trail) for an asynchronous call.

Error Logging ActivityThe iProcess Java Plug-in uses Apache’s Log4J to record system activity. The log4j.properties file distributed with the iProcess Java Plug-in can be modified to suit your logging requirements. An alternative logging system can be used if you require but you will need to refer to the documentation supplied with the product to set it up. Refer to Appendix A on page 39 for more information about setting up Log4J log files.

The delayed release asynchronous interface does not throw a non-fatal exception.


Working with the Interfaces | 17

Dynamic Loading of Java Objects (Advanced Topic)If custom Java objects or third party libraries called by custom Java objects dynamically load other Java objects into the JVM (using Class.forName or Classloader.loadClass), then problems can occur if these loading mechanisms are used without reference to the current thread's class loader. All objects in the SWDIR\eaijava\libs\repository folder (including any sub-folders) are loaded using a custom iProcess class loader, including all custom Java objects and their associated third party libraries. This problem particularly affects J2EE related classes.

In the event that this problem proves fatal, it is possible to modify the SW_SYSCLASSPATH environment variable to include specific JAR files on the system class path. JAR files located on the SW_SYSCLASSPATH should NOT also be placed in the repository. It may be necessary to place any dependent objects on the SW_SYSCLASSPATH in order to achieve normal operation.

Thread currentThread = Thread.currentThread();currentThread.setContextClassLoader(this.getClass().getClassLoader());

XML Parsing (Advanced Topic)

The SUN Java Web Services Developer Pack (JWSDP) used in previous versions of this product is replaced with a combination of default libraries supplied with Java and libraries supplied by Apache, specifically XERCES 2.9.1 and XALAN 2.7.1.

The exact XML parser configuration is set in the xmlparser.properties file which can be found in the SWCLIENT\java_common folder on iProcess Workspace or SWDIR\eaijava on iProcess Engine.

The following code is executed within the iProcess Java Client and Server Plug-ins during initialization and also when creating threads for automatic delayed release:

The following represents a major change for version 11.0.0 onwards of the iProcess Java Plug-in.

Changing the values contained in the xmlparser.properties file is NOT supported.



Examples

The following sections summarize the two different approaches you can use to create your Java object.

Manually Creating a Java ObjectThe following example demonstrates how to create a Java object that can be called from an EAI Java step in your iProcess procedure definition.

1. Create a new Java class using the IDE (Integrated Development Enterprise) of your choice.

2. Based on the invocation style (delayed release or immediate release) that you want to use, implement one of the interfaces described in Using the EAI Java SDK on page 11. Refer to “Using Enterprise Application Integration (EAI) Steps” in the TIBCO iProcess Modeler - Integration Techniques guide for more information about delayed release and immediate release.

3. Provide an implementation for the initialize method. This method is called each time the Java object is instantiated. If you are using the Cache Object Between Invocations option (see Define the Call to the Java Object on page 24) this will only happen once for each iProcess Background process for each object. It is recommended that any slow initialization tasks be performed inside this method.

4. Provide an implementation for the execute method, or the executeSync/executeAsync methods if using delayed release. These methods get their input parameters from the field names, values and types that have been specified as input parameters for the Java object in the iProcess Step Definition.

If you are using delayed release, you must not perform any thread related actions in your code, for example, using a sleep function.

5. Your Java object must be located in one of the sub-folders under the SWDIR\eaijava\libs\repository folder on the iProcess Engine, typically SWDIR\eaijava\libs\repository\user. Therefore, if you have developed your object on a development machine, you need to copy it to the above location or the user folder or another sub-folder.

6. After modifying the repository, you need to restart the iProcess engine.

Refer to the HTML JavaDocs, supplied on the iProcess Java Plug-in product installation media, for detailed information about the interfaces and methods you can use.


Examples | 19

Using the Example Java ObjectsExample Java objects and procedures are available:

• In the examples folder on the product installation media for both iProcess Technology Plug-ins and iProcess Workspace Plug-ins.

• On the product download site.

• At http://power.tibco.com.

You can examine the code for these objects to familiarize yourself with how they have been implemented and then refer to the example procedures to see how they have been called from iProcess.


http://power.tibco.com



| 21

Chapter 3 Defining EAI Java Steps

This chapter describes how to define EAI Java steps in your iProcess procedures.

Before defining your EAI Java step, you need to have access to the Java object that you want to call from this step. This must be located on the same machine as your iProcess Engine. Therefore, if you are prototyping the system on a development machine, you need to copy the Java object to the machine hosting the iProcess Engine.

The Java object is the component that will perform the task you require from the step (such as interfacing with an application server to retrieve some account information.) Refer to Creating Your Java Object on page 9 for more information.

Topics

• Creating an EAI Java Step, page 22

• Using iProcess Array Fields as Input and Output Parameters, page 32


22 | Chapter 3 Defining EAI Java Steps

Creating an EAI Java Step

The following is an overview of the steps involved to create an EAI Java step in your procedure:

1. Define Basic EAI Step Information - step name, description, and type. Optionally, step deadline and audit trail information can also be defined.

2. Define the Call to the Java Object. You need to specify:

— the name of the Java object (mandatory)

— whether or not the Java object is cached when instantiated (optional)

— which fields/expressions are passed to the Java object (optional)

— which fields are returned to iProcess (optional), and

— a static data string that can be passed to the Java object (optional).

When you have done this, the EAI step type is defined as an EAI Java step.

Define Basic EAI Step Information1. Start the TIBCO iProcess Modeler, click the EAI Step tool and click in the

window where you want to place the EAI Step.

2. In the EAI Step Definition dialog, enter the Name and Description for the step.

3. In the EAI Type drop-down list, select EAIJAVA – TIBCO iProcess Java Client Plug-in.

You must select this when you first create the step; it cannot be changed later. The list box displays EAI step types that have been installed as TIBCO iProcess Workspace plug-ins.

4. Click the Ignore Case Suspend check box if you want the step to still be processed as normal while a case is suspended by an iProcess Objects or SAL application.

If Ignore Case Suspend is not checked (the default option), the step is not processed while the case is suspended.

Cases can only be suspended and re-activated from an iProcess Objects™ or SAL application. Audit trail messages indicate whether a case is active or suspended. Refer to the TIBCO iProcess™ Objects: Programmer’s Guide for more information about suspending cases.


Creating an EAI Java Step | 23

5. (Optional) Select the Don’t delete work items on withdraw option. If this option is selected, and the deadline on an outstanding step expires or it is withdrawn as an action (release or deadline expire) of another step:

— the deadline actions are processed.

— the step remains outstanding (the step remains in the workqueue or the sub-procedure case is not purged).

— when the step is released (or the sub-procedure case completes) the normal release actions are not processed but the case field data associated with the release step (e.g. the field values set in a normal step whilst in a work queue or the output parameters of a sub-case) is applied to the main case data.

6. Click the Audit Trail tab to define custom audit trail entry expressions. This enables you to define text expressions that are evaluated when the step is processed and inserted as the %USER value in the audit trail entries:

— In the Call-out Initiated field, enter a valid text expression that will replace the %USER value in the audit trail when the call out is initiated.

— In the Call-out Complete field, enter a valid text expression that will replace the %USER value in the audit trail when the call out is complete.

You must enter a value in both fields or leave them both empty.

7. The Delayed Release tab is disabled because you define the delayed release setting in the Java object by using the delayed release interfaces - see Implementing the Interfaces on page 13.

8. Click the Deadlines button if you want to enter deadline information for this step. Refer to “Using Deadlines” in the TIBCO iProcess Modeler - Basic Design guide for an explanation of defining deadlines.

9. Click the General tab, then click EAI Call-Out Definition. The TIBCO iProcess Java Client Plug-in dialog is displayed.

Creating and Editing an EAI Java StepYou will supply the same information to the iProcess Java Client Plug-in whether you are creating an EAI Java step or editing an existing one. However, the dialogs that you use to do this are slightly different. When you are creating a new EAI Java step, you are guided through the creation process. When you are editing an existing step, the information already entered is displayed on a series of tabbed dialogs. This enables you to edit information that needs to be changed, while leaving the remaining information unaffected.



Define the Call to the Java ObjectAt this point:

• If you are creating a new EAI Java step, the dialog shown in the following illustration is displayed.



• If you are editing an existing EAI Java step, the tab shown in the following illustration is displayed instead.

The first screen of the wizard or the General tab of the TIBCO iProcess Java Client Plug-in dialog enables you to specify the parameters required to call your Java object.

To define the call to your Java object:

1. (Mandatory) In the Object Name to be Called field, enter the name of the Java object you want to call, including the package hierarchy if it resides inside a package. For example, MyObjectName or PackageName.MyObjectName.

If you are using TIBCO iProcess Conductor, you can use a custom EAI Java step to perform state changes directly on the order through the Order Manager by specifying the appropriate class name in the Object Name to be Called field.

On the General tab of the EAI Java step, enter the class name:

com.staffware.frameworks.eaiorder.ipe.OrderStateChange



in the Object Name field. Alternatively, if statistics are to be collected on this custom EAI Java step, enter the class:

com.staffware.frameworks.eaiorder.ipe.OrderStateChangeStats

Both these classes are included in the order.jar file supplied with TIBCO iProcess Conductor.

By default this custom EAI Java step assumes that the Order ID is defined in the SWO_ORDERID field. If you need to change this default, edit the property eaiorder.orderid.field in the SWDIR\eaijava\properties\eaiorder\eaiorder.properties file to specify the field you require.

The custom EAI Java step also provides the capability to write the order xml into an iProcess Engine field. If the order.setxml=true is set in the static data the order xml is written by default to the iProcess field ORDER. This field can be changed by adding the property eaiorder.orderxml.output.field in the eaiorder.properties file. See the TIBCO iProcess Conductor Implementation Guide for further details.

.

2. (Optional) Check the Cache Object Between Invocations check box if you want your Java object to be cached and re-used. If you do not select this option, the Java object is instantiated each time the EAI Java step is processed.

Some Java objects have a very large initialization overhead so you can use this option to initialize the object only once and increase the performance of the EAI Java step at run-time.

3. (Optional) Specify a static data string that is passed to your Java object every time it is invocated. This can be used to control the behavior of the Java object (as demonstrated in the example Java objects available at http://power.tibco.com). You can either use a text string or use an expression.

— Select Text and enter a text string in the text area, or

— Select iProcess Expression and enter a valid iProcess expression in the text area. The iProcess expression is evaluated at run-time. Refer to the TIBCO iProcess Expressions and Functions: Reference Guide for more information about using expressions.

An example use of this is to provide a means by which the run-time behavior of the Java object can vary according to the contents of the data string. For example, one Java object could be defined so that it either sends an Email or posts an HTTP request depending on whether HTTP or EMAIL is specified as the static data string.

At this point:


http://power.tibco.com


• If you are creating a new EAI Java step, click Next on the dialog if you want to define any input fields and/or expressions, and see Define iProcess Java Plug-in Input Parameters on page 27. If you have finished defining your EAI Java step, click Finish.

• If you are using the tabbed dialogs to edit an existing step, and you want to change the specification of input fields and/or expressions, refer to Define iProcess Java Plug-in Input Parameters on page 27; to change the specification of output fields, refer to Define the iProcess Java Plug-in Output Parameters on page 29. Otherwise, click OK and OK again to finish editing your EAI Java step.

Define iProcess Java Plug-in Input ParametersAt this point:




• If you are editing an existing EAI Java step, the tab shown in the following illustration is displayed instead.

The second screen of the wizard or the Inputs tab enables you to specify iProcess fields and/or expressions as inputs to your Java object. Defining input parameters is optional because you can call a Java object without passing in any fields or expressions.

To define input parameters to the Java Object:

1. (Optional) To pass in an iProcess expression, enter a valid iProcess expression in the iProcess Expression field and then click >> to make it available to the Java object. An expression is displayed italicized in red so that you can easily differentiate between fields and expressions.

The color used for expression fields is hard coded to red. This means that if you have the Windows Selected Item color also set to red, you can get display problems. Also, when selecting fields in the Selected Data list, the text does not change color as it does when selecting fields in the Available Fields list.

The hot keys for adding/removing fields (<< and >>) are not available for this tab.



2. (Optional) The Available Fields list displays the iProcess fields that you can pass to your Java object. Select a field and click >> to move it into the Selected Data list in the right hand pane. To remove a field or expression from the Selected Data list, select the field or expression and click <<.

You can pass in iProcess array fields to your Java object. Array fields are listed in the Available Fields pane but are not distinguished from standard fields. The iProcess Java Client Plug-in automatically determines whether a field is an array and, if it is, passes all the array field values to the Java object. Refer to Using iProcess Array Fields as Input and Output Parameters on page 32 for more information.

At this point:

• If you are creating a new EAI Java step, click Next on the dialog if you want to define any output fields and/or expressions, and see Define the iProcess Java Plug-in Output Parameters on page 29. If you have finished defining your EAI Java step, click Finish.

• If you are using the tabbed dialogs to edit an existing step, and you want to change the specification of output fields, refer to Define the iProcess Java Plug-in Output Parameters on page 29. Otherwise, click OK and OK again to finish editing your EAI Java step.

Define the iProcess Java Plug-in Output ParametersAt this point:

You can use the Up and Down buttons to re-order the items in the Selected Data list but this does not have any impact on your Java objects at run-time.






• If you are editing an existing EAI Java step, the tab shown in the illustration below is displayed instead.

The Outputs tab enables you to specify which fields are sent from the Java object back to iProcess. Defining output parameters is optional because you can call a Java object without specifying output parameters.

To define output parameters from the Java Object:

1. The Available Fields list displays the iProcess fields that your Java object can return. Select a field and click >> to move it into the Selected Data list. To remove a field from the Selected Data list, select it and click <<.

2. Click Finish on the wizard or OK on the tabbed dialog when you have defined all your output fields.

You can use the Up and Down buttons to re-order the items in the Selected Data list but this does not have any impact on your Java objects at run-time.

Hot keys for adding/removing fields (<< and >>) are not available in this dialog.



Using iProcess Array Fields as Input and Output Parameters

This version of the iProcess Java Plug-in supports using iProcess array fields. This section describes how to use arrays as input and output parameters.

The array field parameters are read at run-time and, by default, automatically populated into field mappings using explicit array indexes. (For more information about arrays see “Using Arrays” in the TIBCO iProcess Modeler - Advanced Design Guide.)

You can also pass a single value from an array field to the Java object, as a single instance field value.

Passing All Array Field Values to the Java ObjectIf you have an array field in iProcess, by default all of its values are passed to the Java object. In this scenario, the array must contain zero based, contiguous elements.

For example, the following entries show valid and non valid array fields:

Passing One Array Field Value to the Java ObjectIn addition to passing all the array field values (as described in the preceding section), you can pass a single value from an array field to the Java object as a single instance field value.

To do this, before you call the EAI Java step you must set the IDX_ field or SW_GEN_IDX field to the correct value in the array that you want to pass to the Java object. The IDX_ field sets the index number for its respective array field (for example, IDX_ARR1 for the array field ARR1) and the SW_GEN_IDX field sets the index number for all array fields. For example if you set SW_GEN_IDX to [5], the value with an index number of [5] is passed to your Java object (as a single instance field value).

A[0], B[1], A[2], C[3] Valid

A[3], A[5], B[7], C[1] Not a valid contiguous array field

A, B, C = array field names

[n] = array index number


Using iProcess Array Fields as Input and Output Parameters | 33

As output array fields are also supported, it is necessary to upgrade any previously unsupported run-time code to this supported release. Note that in order to use arrays as output fields it is still necessary to map the fields at design-time (omitting the [] index suffix).




| 35

Chapter 4 Migrating Procedures and Code From Previous Versions

This chapter describes how to migrate iProcess procedures and run-time code that you have developed using versions up to and including version i10.0(3.0) of the iProcess Java Plug-in.

Topics

• Migrating Procedures From Versions Prior to i10.0(3.0), page 36

• Migrating Run-time Code, page 37

If you are using manual delayed release in procedures developed with any previous version of the plug-in (prior to version 11.0), further changes may be required. See Appendix B, Manually Performing a Delayed Release, on page 55.


36 | Chapter 4 Migrating Procedures and Code From Previous Versions

Migrating Procedures From Versions Prior to i10.0(3.0)

This version of the iProcess Java Plug-in can read data formats from pre-i10.0(3.0) versions, which means that you can edit procedures that use older EAI Java steps in the iProcess Modeler. However, to run such procedures using this version of the iProcess Java Plug-in, you need to edit the existing procedures so that they use the new data format.

To migrate your procedures, do the following:

1. Open the procedure in the iProcess Modeler.

2. Select the first EAI Java step in your procedure, edit the step definition and click EAI Call-out Definition.

3. Click OK, and then OK again.

4. Repeat this for each EAI Java step in the procedure and for each procedure containing EAI Java steps.

5. Save the procedure(s).

Migration of procedures created using Version i10.0(3.0) or later is not required.


Migrating Run-time Code | 37

Migrating Run-time Code

If you have developed a Java object using the interfaces from a previously unsupported version (i.e. a version earlier than i10) or from the supported i10.0(3.0) version, you should migrate your code to the new interfaces.

Any delayed release code you have will also need updating to the new interfaces.

Editing Run-time Code From Versions Prior to i10.0(3.0)Follow the steps below to convert your Java code to the new interfaces (new interfaces are suffixed with SDK):

1. Edit your existing code and convert the imported iProcess package names to the new name of com.staffware.eaijava.

2. Convert the inherited parent object for the Java object according to the interface being used. For example, convert it to SWImmediateReleasePluginSDK.

3. Previously, the SW_CLASSPATH environment variable was used to store the location of your Java objects. This is no longer required, but you must copy your objects to the SWDIR\eaijava\libs\repository\user folder.

4. Rename the old style configuration file to eaijavaplugin.properties. Convert the contents of the configuration file to the Java standard properties file format.

The following have been added to the eaijavaplugin.properties file:

— proxy values for HTTP URLs. Refer to the TIBCO iProcess Technology Plug-ins Installation Guide for more information.

— schema owner (only applicable if you are using Microsoft SQL Server). Refer to the TIBCO iProcess Technology Plug-ins Installation Guide for more information.

— database pooling parameters. See Appendix E, Configuring Database Connections, on page 63.

5. Convert the initialize method parameters and logic to use the Java standard properties object instead of the old style configuration object.

6. If you are using objects with delayed release, convert from inheriting from a Java object to a Java interface. Any delayed release code will also need

The legacy interfaces supplied in Version i10.0(3.0) of this product are no longer supported.


38 | Chapter 4 Migrating Procedures and Code From Previous Versions

converting to the new interfaces. See Appendix B, Manually Performing a Delayed Release, on page 55.

7. Use the new logging library (Log4J) as appropriate - see Setting Up Log4J on page 40.

8. Convert execute method parameters and logic to use the new OO style field parameters. Reference the correct SDK and JavaDocs for type definitions.

9. Save and test your updated procedure(s) and Java object(s).

Editing Run-time Code From Version i10.0(3.0)Follow the steps below to convert your Java code to the new interface:

1. If you have been using the legacy interfaces supplied in version i10.0(3.0), convert to using the equivalent interfaces supplied in this release.

2. Previously, the SW_CLASSPATH environment variable was used to store the location of your Java objects. This is no longer required, but you must copy your objects to the SWDIR\eaijava\libs\repository\user folder.

3. Convert the eaijava.properties file to use the “eaijava.” prefix for all eaijava standard properties and remove the line that references the log4j.properties file as this is no longer required.

The following have been added to the eaijava.properties file:

— proxy values for HTTP URLs. Refer to the TIBCO iProcess Technology Plug-ins Installation Guide for more information.

— schema owner (only applicable if you are using Microsoft SQL Server). Refer to the TIBCO iProcess Technology Plug-ins Installation Guide for more information.

— database pooling parameters. See Appendix E, Configuring Database Connections, on page 63.

4. Use the new logging library (Log4J) as appropriate - see Setting Up Log4J on page 40.

5. Convert the delayed release objects to use executeSync, executeAsync, or both methods. See Appendix B, Manually Performing a Delayed Release, on page 55.

6. Save and test your updated procedure(s) and Java object(s).


| 39

Appendix A Using the Log Files

This appendix describes how to set up and use the Java logging facility for the iProcess Java Plug-in and describes the error messages you might see in the iProcess Engine log files and/or Java log files.

The iProcess Java Plug-in uses Apache’s Log4J logging facility to record its activity. This logging facility is highly configurable and can log to file, TCP/IP socket, Email, Windows Event Log, etc. More detailed information about Log4J can be found at http://logging.apache.org.

Topics

• Setting Up Log4J, page 40

• Error Messages, page 44


http://logging.apache.org

40 | Appendix A Using the Log Files

Setting Up Log4J

You can customize the logging style and the location of the logging output using the log4j.properties file on both the iProcess Engine and the iProcess Workspace (Windows). This file is located:

• on the iProcess Engine, in the SWDIR\eaijava directory

• on the iProcess Workspace (Windows), in the SWCLIENT\eaijava directory

If you make any changes to the log4j.properties file on the iProcess Engine, the changes will take effect the next time an EAI Java step is executed, or when the iProcess Engine is next restarted, whichever is the sooner. If you modify the file on the iProcess Workspace (Windows), the change will take effect the next time an EAI Java step is edited, or when the client is restarted.

A typical SWDIR\eaijava\log4j.properties file is shown below.

log4j.rootLogger=warn, EAIJAVA

log4j.appender.EAIJAVA=org.apache.log4j.FileAppenderlog4j.appender.EAIJAVA.Append=truelog4j.appender.EAIJAVA.File=C:/swserver/staffw_nod3/logs/eaijava.log

log4j.appender.EAIJAVA.layout=org.apache.log4j.PatternLayoutlog4j.appender.EAIJAVA.layout.ConversionPattern=%d [%-5p]%x %c{1} - %m%n%nTIBCO.SingleLogFile=false

A typical SWCLIENT\eaijava\log4j.properties file is shown below.

log4j.rootLogger=warn, EAIJAVACOMMON

log4j.appender.EAIJAVACOMMON=org.apache.log4j.FileAppenderlog4j.appender.EAIJAVACOMMON.Append=falselog4j.appender.EAIJAVACOMMON.File=c:/swclient/eaijava/eaijava.loglog4j.appender.EAIJAVACOMMON.layout=org.apache.log4j.PatternLayoutlog4j.appender.EAIJAVACOMMON.layout.ConversionPattern=%d [%-5p] %c{1} - %m%n%n

The exact format of the files is described in the Log4J documentation.

By default, error log messages are written to the following files:

• On the iProcess Engine, the default is that a separate log file is created per background process. The files are called eaijava.guid.log, where guid is a


Setting Up Log4J | 41

unique ID number that distinguishes the output from different background processes. For example:

eaijava.921d6562d19b912e0000011e009931f5.log

You can specify that a single consolidated log file should be produced instead of these multiple files. If you select this option, the same unique process ID that is used to identify multiple log files (guid) is included in each log message within the consolidated file, to differentiate between messages produced by different processes. See Examples on page 43.

Also by default, the log files are located in the following directory:

SWDIR\logs\

• On the iProcess Workspace (Windows), the file is by default written to:

SWCLIENT\eaijava\eaijava.guid.log

where, as for the server, guid is a unique ID number.

To change the default settings:

• To change the logging output location, edit the File entry in the Log4J file.

• To change the logging level, change the rootLogger entry in the Log4J file. This defaults to WARN. Possible levels are:

• For the SWDIR\eaijava\log4j.properties file, specify that the iProcess Engine should use a single consolidated log file by setting the TIBCO.SingleLogFile entry to true. If you set this value, %x in the ConversionPattern is replaced in each log message by the guid of the process that produced the message.

On UNIX, if you remove the SWDIR/logs/eaijava.guid.log file while the iProcess Engine is running, you must restart it before a new log file can be created.

ERROR This is the minimum level of output. It displays messages of severity ERROR only.

WARN This displays error and warning messages. It is the default value.

INFO This level displays error, warning and information messages.

DEBUG This is the maximum level of output. It is not recommended for normal use, and is intended for locating and analyzing problems.



The exact settings are subject to change by the underlying Log4J implementation. You should always refer to the Log4J documentation set for the version of Log4J installed by the iProcess Java Plug-in. The default setting for the iProcess Java Client Plug-in is Append=false. The default setting for the iProcess Java Server Plug-in is Append=true.

Each time an EAI Java step is edited in the iProcess Java Client Plug-in, the log file will be cleared and reset. To retain the contents of the log file between invocations for the iProcess Java Client Plug-in you must change the settings to Append=true. It is not sufficient however to change this property alone - refer to the Log4J documentation for further information.


Setting Up Log4J | 43

ExamplesIf the diagnostic level is set to INFO and TIBCO.SingleLogFile to false, output similar to the following example will be produced. Note that since the single log file option is not enabled, no message about that option appears:

2007-02-21 14:37:40,123 [INFO ] SWEAIJavaClassLoader - displayJavaInfo()2007-02-21 14:37:40,123 [INFO ] SWEAIJavaClassLoader - java.vendor: Sun Microsystems Inc.2007-02-21 14:37:40,123 [INFO ] SWEAIJavaClassLoader - java.vm.name: Java HotSpot(TM) Client VM2007-02-21 14:37:40,123 [INFO ] SWEAIJavaClassLoader - java.vm.version: 1.5.0_06-b052007-02-21 14:37:40,123 [INFO ] SWEAIJavaClassLoader - java.version: 1.5.0_06

If the diagnostic level is set to INFO and TIBCO.SingleLogFile to true, a single log file similar to the following example will be produced:

2007-02-21 15:17:21,316 [INFO ]e4e0c73088892bf70000013501b67f74 SWEAIJavaClassLoader - SingleLogFile enabled2007-02-21 15:17:21,316 [INFO ]e4e0c73050a8b4e00000013501b67f74 SWEAIJavaClassLoader - SingleLogFile enabled2007-02-21 15:17:21,331 [INFO ]e4e0c7308cf995070000013501b67f74 SWEAIJavaClassLoader - displayJavaInfo()2007-02-21 15:17:21,331 [INFO ]e4e0c73050a8b4e00000013501b67f74 SWEAIJavaClassLoader - displayJavaInfo()2007-02-21 15:17:21,331 [INFO ]e4e0c7308cf995070000013501b67f74 SWEAIJavaClassLoader - java.vendor: Sun Microsystems Inc.2007-02-21 15:17:21,331 [INFO ]e4e0c73050a8b4e00000013501b67f74 SWEAIJavaClassLoader - java.vendor: Sun Microsystems Inc.2007-02-21 15:17:21,331 [INFO ]e4e0c730721047db0000013501b67f74 SWEAIJavaClassLoader - displayJavaInfo()2007-02-21 15:17:21,331 [INFO ]e4e0c730655b5e340000013501b67f74 SWEAIJavaClassLoader - java.vm.name: Java HotSpot(TM) Client VM2007-02-21 15:17:21,331 [INFO ]e4e0c73050a8b4e00000013501b67f74 SWEAIJavaClassLoader - java.vm.name: Java HotSpot(TM) Client VM2007-02-21 15:17:21,331 [INFO ]e4e0c730721047db0000013501b67f74 SWEAIJavaClassLoader - java.vendor: Sun Microsystems Inc.

Note that the messages produced by different processes are interleaved. The process guid is necessary to distinguish the output of each process. The string e4e0c73088892bf70000013501b67f74 in the first message is an example of this ID number.



Error Messages

The following sections describe the error messages that can be logged to the iProcess Engine log files (SWDIR\logs\sw_error and SWDIR\logs\sw_warn) and to the Java log file. This covers both the iProcess Java Client and iProcess Java Server plug-ins.

iProcess Engine Error MessagesThe following table lists the messages that can be logged to the iProcess Engine log files.

Error Message Description/Solution

JAVA_HOME not set This does not need to be set under normal circumstances. Please contact TIBCO Support.

Could not create JVM Check that the System Path contains a reference to the JVM. If this fails please contact TIBCO Support.

Could not attach to already instantiated JVM

A JVM was previously created for this process and cannot now be contacted – please contact TIBCO Support.

Can't find java Plugin class Check that the iProcess system class path is set correctly (SW_SYSCLASSPATH) and that the Jar files are in the correct directory. If this fails please contact TIBCO Support.

Can't find java class constructor

A Java object cannot be located. Please contact TIBCO Support.

Could not instantiate java class


Could not get a handle to the execute method


Could not get a handle to the getOutputFieldsAsString method


Could not get a handle to the isDelayedRelease() method



Error Messages | 45

Can't find initialize Method A Java object cannot be located. Please contact TIBCO Support.

Can't find java String class Check that the iProcess system class path is set correctly (SW_SYSCLASSPATH) and that the Jar files are in the correct directory. If this fails please contact TIBCO Support.

Can't find java PluginException class

Check that the iProcess system class path is set correctly (SW_SYSCLASSPATH) and that the Jar files are in the correct directory. If this fails please contact TIBCO Support.

Could not get a handle to the FatalPluginException getStackTraceString method


Can't find java Parser class Check that the iProcess system class path is set correctly (SW_SYSCLASSPATH) and that the Jar files are in the correct directory. If this fails please contact TIBCO Support.

Can't find Parser class constructor


Could not get a handle to the ParseExistingXML() method


Could not get a handle to the GetFieldQueries() method


Could not get a handle to the GetInputExpressionQueries() method


Could not get a handle to the GetStaticExpressionQuery() method


Could not get a handle to the SetFieldResults() method





Could not get a handle to the SetInputExpressionResults() method


Could not get a handle to the SetStaticExpressionResult() method


Step definition not present The design-time definition has been lost. Please contact TIBCO Support.

Could not instantiate Parser class


Parser failed to parse existing XML

The design-time data has become corrupt or invalid. Please contact TIBCO Support.

Failed to evaluate expression

The iProcess expression was invalid. Please check its syntax and if necessary change the expression in the iProcess Java Client plug-in. If this fails please contact TIBCO Support.

Failed to obtain field value The iProcess field could not be found. Please check it exists in the process definition and if necessary change the field mapping in the iProcess Java Client plug-in. If this fails please contact TIBCO Support.

Failed to parse returned values from Java object

The Java object returned values that were not recognized by iProcess. Please check the Java object code and if this fails please contact TIBCO Support.



Error Messages | 47

iProcess Workspace Error MessagesThe following table lists the messages that can occur in the iProcess Workspace.


Plug-in failed to initialize Check your SW_CLIENTCLASSPATH environment variable and remove any entries in the path that are no longer needed - for example, for old iProcess Java Client plug-in installations.

SW_CLIENTCLASSPATH is the search path that the JVM uses to initialize the iProcess Java Client plug-in. If this environment variable gets too long (for example, if you have done multiple re-installations of the iProcess Java Client plug-in), the JVM cannot find the bootstrap classes required to successfully load the iProcess Java Client plug-in.

If this fails please contact TIBCO Support.



Java LogsThe following messages are grouped by their Java object context. This context appears by default at the start of each line in the logging output.

SWGenericPlugin

Severity Message Description

Error createObject() failed with InstantiationException

Unable to create the bespoke Java object – check the iProcess class path (SW_SYSCLASSPATH) and your Java object code and if this fails please contact TIBCO Support.

Error createObject() failed with IllegalAccessException

Please check your Java object code and if this fails please contact TIBCO Support.

Error createObject() failed with ClassNotFoundException

Unable to create the bespoke Java object – check the iProcess class path (SW_SYSCLASSPATH) and make sure the Jar files are in the correct folder (SWDIR\eaijava\libs\repository\user). If this fails please contact TIBCO Support.

Error createObject() failed with NoClassDefFoundError

Unable to create the bespoke Java object – check the iProcess class path (SW_SYSCLASSPATH) and make sure the Jar files are in the correct folder (SWDIR\eaijava\libs\repository\user). If this fails please contact TIBCO Support.

Error createObject() failed with Throwable

An unexpected error occurred - please contact TIBCO Support.

Error execute() - Could not instantiate Unable to create the bespoke Java object – check the iProcess class path (SW_SYSCLASSPATH), your Java object code and make sure the Jar files are in the correct folder (SWDIR\eaijava\libs\repository\user). If this fails please contact TIBCO Support.

Error execute() – NonFatalPluginException

Thrown by the bespoke Java object – this is an intentionally thrown error and can be ignored.


Error Messages | 49

Error execute() – FatalPluginException

Thrown either by the bespoke Java object or by the iProcess Java Plug-in – this is an intentionally thrown error and will result in the iProcess transaction being rolled back. If this occurs unexpectedly please check your Java code and if this fails please contact TIBCO Support.

Error execute() - Cannot perform delayed release without required configuration parameters

An attempt to perform a delayed release without the required delayed release configuration was made. Configure delayed release according to the Installation Guide, restart the iProcess Engine and try again. If this fails please contact TIBCO Support.

Error execute() - Plugin object does not implement a known plugin interface!

The bespoke Java object does not implement a known iProcess EAI Java SDK interface. Please check your Java code and if this fails please contact TIBCO Support.

Warning initialize() - Delayed release parameters not specified. Will be unable to use Delayed Release functionality

Delayed release has not been configured – this may be intentional. If not, please configure delayed release according to the Installation Guide, restart the iProcess Engine and try again. If this fails please contact TIBCO Support.

Error initialize() - Unexpected exception in EAIGenericPlugin initialize method

An unexpected error occurred – please contact TIBCO Support.




SWParser

SWDelayedReleaser


Error getFieldQueries() - RuntimeException


Error getInputExpressionQueries() - RuntimeException


Error getInputFields() – RuntimeException


Error getOutputFields() - RuntimeException


Error getStaticExpressionQuery() - RuntimeException


Error parseExistingXML() - Unable to parse XML

The design-time data has become corrupt or invalid. Please contact TIBCO Support.

Error parseExistingXML(): Version number is incorrect

An incompatible version of the design-time component is being used. Please contact TIBCO Support.

Error parseExistingXML() - RuntimeException


Error setFieldResults() - RuntimeException


Error setExpressionResults()- RuntimeException



Error run() - Plugin reported fatal error whilst executing

The Java object threw a Fatal exception whilst executing – this is anticipated behavior. Please check your Java code and if this fails contact TIBCO Support.


Error Messages | 51

SWDelayedReleaseInfo

SWDelayedReleaseHandler


Error SWDelayedReleaseInfo() - Invalid ID

The iProcess delayed release ID is invalid. Please contact TIBCO Support.


Error db_close() - Failed to close Statement

A database error occurred. Please check your database status and if this fails contact TIBCO Support.

Error db_close() - Failed to close connection


Error db_connect() - db_driver and db_connection must be set

The driver and connection details have not been set in the EAI Java properties file. Please check this file and if this fails please contact TIBCO Support.

Error db_connect() - db_user and db_password must be set

The driver and connection details have not been set in the EAI Java properties file. Please check this file and if this fails please contact TIBCO Support.

Error db_connect() - Connection to Database failed - no delayed releases will be carried out!


Error db_connect() - Database driver class not found - no delayed releases will be carried out!

The database JDBC driver could not be found. Please check that you have the necessary JAR files for your JDBC driver in the SWDIR\eaijava\repository\database folder and restart the iProcess Engine if required. If this fails please contact TIBCO Support.

Error db_connect() - Failure while connecting to database - no delayed releases will be carried out!




Error db_connect() - Failure preparing statements, no delayed release can be carried out!

A database error occurred. Please contact TIBCO Support.

Error executeCommit() - Error commiting work

A database error occurred and the delayed release transaction has been lost. Please check your database status and if this fails contact TIBCO Support.

Error getQueueName() - Error getting queue name


Error PreparedStatement() - Error creating statement for queue


Error postRelease() - Queuename is null, error


Error postRelease() - Failed to prepare release statement


Error prepareStatements() - Error preparing statements!


Error processRequest() - DelayedReleaseId is null


Error processRequest() - Invalid Delayed release ID


Error processRequest() - Couldn't connect to Database!


Error processRequest() - Failed to get Node Info


Error processRequest() - Failed to get Proc Info


Error processRequest() - Failed to get Procedure version information




Error Messages | 53

SWEAIFrameworkDisplayFactory

This applies to the iProcess Java Client Plug-in only.

Error processRequest() - Error posting case data


Error processRequest() - Couldn't post release information


Error processRequest() - Couldn't commit work

A database error occurred and the delayed release transaction has been lost. Please check your database status and if this fails contact TIBCO Support.

Error processRequest() - An exception caused failure to release the following item. Message will be requeued (unless max requeue limit met)

A database error occurred and the delayed release transaction may have been lost. Please check your database status and if this fails contact TIBCO Support.


Error Message Description

Unable to set look and feel The Java Runtime Environment was unable to set the look and feel of the application to Windows. Please contact TIBCO Support.

Error whilst setting up pages

When initializing the TIBCO iProcess Java Client Plug-in dialog it was not possible to configure the tabs. Please contact TIBCO Support.

Runtime exception occurred!

An unexpected error occurred. Please contact TIBCO Support.

Error whilst setting up display

An unexpected error occurred whilst initializing the TIBCO iProcess Java Client Plug-in dialog. Please contact TIBCO Support.

Cannot create JAXB context Necessary Java objects for reading the internal data format were not found – check your installation by uninstalling and re-installing the iProcess Java Client Plug-in and if necessary contact TIBCO Support.

Cannot create SWEAIJavaPlugin

Necessary Java objects for reading the internal data format were not found. Please contact TIBCO Support.



Cannot create GeneralType Unable to write the internal data format. Please contact TIBCO Support.

Cannot create StaticDataType

Necessary Java objects for writing the internal data format were not found. Please contact TIBCO Support.

Cannot create InputsType Necessary Java objects for writing the internal data format were not found. Please contact TIBCO Support.

Cannot create SWStaffwareField


Cannot create MappingsType


Cannot create MappedInputsType


Cannot create MappedOutputsType


Cannot create Marshaller Necessary Java objects for writing the internal data format were not found. Please contact TIBCO Support.

Cannot set marshaller properties


Cannot marshall XML Writing the internal data format failed. Please contact TIBCO Support.

Unable to parse XML The internal data format appears to be corrupt or invalid. Please contact TIBCO Support.

Error Message Description


| 55

Appendix B Manually Performing a Delayed Release

This appendix describes how to manually perform a delayed release on an EAI Java Step.

Topics

• Overview, page 56

• Manually Performing a Delayed Release, page 57


56 | Appendix B Manually Performing a Delayed Release

Overview

The standard behavior of the iProcess Java Plug-in is that the release for a delayed release step is performed automatically. Any updated iProcess field values and the release instruction are posted to iProcess via the iProcess Engine database.

Occasionally you may want to manually perform the release and its associated field/value update. This is particularly the case if:

• you want to be notified if the object’s step is withdrawn.

• the step calls an external system that needs to take control of releasing the step

• the step is expected to take a long time to complete. If the delayed release option is not used, the Background (BG) process will be blocked until the step is completed; having a BG process blocked for more than a few seconds would have a severe impacted on performance.

• there are many delayed release steps expected to be in execution at any one time

• fault tolerance and failover is a particular concern.


Manually Performing a Delayed Release | 57

Manually Performing a Delayed Release

To manually perform a delayed release:

1. Configure the iProcess Java Server Plug-in for delayed release as normal, following the instructions in the installation guide.

2. Define your iProcess procedure as normal – for EAI Java steps configure the output fields as normal.

3. Within your bespoke Java code, extend the DelayedReleasePluginSDK interface as normal, but within the executeAsync method capture the names of the output fields, field values, delayed release ID, user and audit message parameters. All these values are required by iProcess when releasing a delayed release step.

4. Inside the Java code, make a call to the external system that will be responsible for triggering the manual release, passing the values of the parameters from the previous step.

5. Return a value of null from the executeAsync method of the Java code – this instructs the iProcess Java Server Plug-in not to perform an automatic release of the step.

There are various means by which a delayed release step can be released. These include the use of:

• PStaffifc

• iProcess Objects

• The SSOLite Stored Procedures; see the iProcess Engine Administrator's Guide for your database for details of these procedures.

• The Java API wrapping the SSOLite Stored Procedures. (Note that the JavaDoc is included on the installation media for both the iProcess Workspace Plug-ins and the iProcess Technology Plug-ins, in the \javadoc folder.)

In addition there is an API provided as part of the iProcess Java Plug-in that performs the release using a JDBC connection to the iProcess Engine database.

In order to use this API, use the objects contained in the iProcess Java Plug-in as follows:

This API is supplied as an example, and is not suitable for production use without modification, as it makes certain assumptions that may not be valid in a production environment.


58 | Appendix B Manually Performing a Delayed Release

• Call the SWDelayedReleaseHandlerFactory’s getHandler static method, passing a Java Properties object that contains the contents of the iProcess Java Server Plug-in properties file.

• Call the processRequest method on the returned SWDelayedReleaseHandler object, passing the values previously obtained for the delayed release ID, output field names and values, user and audit message parameters. In addition, the updated output field values should be supplied in a Java Map object containing the iProcess field name as a key, and the updated field value as the key’s value.

Note that in the current implementation most, but not all, error conditions are returned via an exception on the processRequest method. This will be addressed in a subsequent release.

In order to use the above Java objects the Java environment must be correctly configured. Make sure that the Java CLASSPATH includes:

1. the following files, which are supplied on the installation media for both the iProcess Technology Plug-ins and the iProcess Workspace Plug-ins in the \lib folder:

— SWDIR\eaijava\libs\repository\system\crypto.jar

— SWDIR\eaijava\libs\bootstrap\log4j-1.2.13.jar

2. the following files, which are supplied on the installation media for both the iProcess Technology Plug-ins and the iProcess Workspace Plug-ins in the \sdk folder:

— EAIJSDK.jar (see page 10)

— EAIJSDK_ ssolite.jar

— EAIJSDK_eaijava.jar

3. JDBC drivers as required for the database type being used

You should also make sure that Log4J is suitably configured for use with the external system that will be responsible for triggering the manual release.


| 59

Appendix C Return Values for getType()

This appendix describes the field type values that are returned with the getType() method.

Field Type Value

DATE D

MEMO F

NUMERIC R

TEXT A

TIME T

EXPRESSION E

COMMA SEPARATED NUMERIC N


60 | Appendix C Return Values for getType()


| 61

Appendix D Character Encoding

The iProcess Modeler is implemented in C and is NOT UNICODE compliant in the current release. When entering or editing data in a form, the default encoding from the host operating system is used. On International English versions of Windows this is typically Cp1252.

When converting this data on the iProcess Engine to Java strings, (as part of an EAI Java step invocation) it is necessary to explicitly state the encoding used on the client to encode and decode the data correctly. This particularly affects non-ASCII characters, such as the Euro symbol, and extended character sets such as Polish and Cyrillic.

Please note the following:

• The current encoding used by the iProcess Java Client is stored in the SWDIR\eaijava\encoding.properties file.

• It is not possible to set the encoding to more than one encoding set - support for multiple encoding sets across iProcess Workspace clients connected to a single iProcess Engine is not permitted in this release.

• When passing XML data, including for example the Euro symbol, care must be taken with respect to the encoding used within the XML document and the XML editor used. Euro in UTF-8 is represented as â‚¬ when viewed in a non UNICODE compliant editor.


62 | Appendix D Character Encoding


| 63

Appendix E Configuring Database Connections

This appendix describes how you can configure your database connections for best performance.

Topics

• Introduction, page 64


64 | Appendix E Configuring Database Connections

Introduction

The iProcess Java Plug-in enables you to create and manage a pool of database connections. This pool is used for automatic delayed release operations.

In previous releases, the connections to the database were created and dropped for each individual delayed release call. Pooling enables the connection to be kept open (based on the configuration parameters) and re-used across many calls, thus improving the use of resources and increasing performance. In this release, one pool is created for each iProcess background process. The pool for each process is initialized when the first delayed release instruction is processed.

The iProcess Java Plug-in enables you to specify many database pool parameters, so that they can be administered dynamically.

For each database connection in the pool, you can direct messages from the plug-in to use a specific background message queue. This is done using the existing iProcess SSOLite functions SW_SET_QUEUE() and SW_UNSET_QUEUE(). (See the Appendix "SSOLite Stored Procedures" in the TIBCO iProcess Engine Database Administrator’s Guide for your database for full details of these functions.)

The default values for these parameters will be entirely suitable for most installations. You should only change the default values as part of a performance-tuning exercise if you are entirely familiar with all aspects of the iProcess system and of your database. Otherwise, your system’s performance may degrade.


Database Pooling | 65

Database Pooling

The iProcess Java Plug-in uses a pool of database connections to ensure best performance when using delayed release and handling database updates using the SSOLite stored procedures. It provides facilities that enable you to tailor some of the parameters used for this database connection pooling.

The default values for the attributes which control the way each pool behaves are defined in the file SWDIR\eaijava\properties\eaijavapooling.properties. Periodically, the system looks for changes in eaijavapooling.properties. The property eaijava.rescaninterval in SWDIR\eaijava\eaijavaplugin.properties defines how often this check takes place; by default, rescans occur every minute.

The same property file also contains the property eaijava.db_specific_queue. This property determines which queue will be used when the pool connects to the database. If this property is set:

• to eaijava.db_specific_queue=true, then iProcess ensures that the stored procedure SW_SET_QUEUE is called upon database connection

• to eaijava.db_specific_queue=false, then iProcess ensures that the stored procedure SW_UNSET_QUEUE is called upon database connection.

• to the default value of eaijava.db_specific_queue=default, then neither SW_SET_QUEUE nor SW_UNSET_QUEUE is called upon database connection.

The values in SWDIR\eaijava\eaijavaplugin.properties are not dynamically configurable. They are used when the iProcess Java Plug-in is started, and subsequent changes to the file have no effect until the next time the plug-in is started.

As well as being able to define defaults for many parameters associated with the database pooling mechanism used by the iProcess Java Plug-in, there are further facilities which enable you to dynamically change the values at run-time.

For information on the procedures SW_SET_QUEUE and SW_UNSET_QUEUE, see the Appendix "SSOLite Stored Procedures" in the TIBCO iProcess Engine Administrator’s Guide for your database.


66 | Appendix E Configuring Database Connections

The property file SWDIR\eaijava\properties\eaijavapooling.properties is monitored periodically for any change. When a change is detected, the pool is adjusted dynamically.

Changing the following parameters is supported:

eaijava.db_MaxActive=8eaijava.db_WhenExhaustedAction=1eaijava.db_MaxWait=-1eaijava.db_MaxIdle=8eaijava.db_MinIdle=0eaijava.db_TestOnBorrow=falseeaijava.db_TestOnReturn=falseeaijava.db_TimeBetweenEvictionRunsMillis=900000eaijava.db_NumTestsPerEvictionRun=3eaijava.db_MinEvictableIdleTimeMillis=1800000eaijava.db_TestWhileIdle=falseeaijava.db_SoftMinEvictableIdleTimeMillis=-1eaijava.db_Lifo=true

For more information, see the Apache Commons Pool 1.4 API documentation. This is supplied on the iProcess Technology Plug-ins installation media in the \pooling folder. Click on index.html to open the document, and then click on the class GenericObjectPool.

The values given in the list above are the supplied defaults. For details about each of these parameters, see GenericObjectPool in the Apache Commons Pool 1.4 API documentation.

Note that changing any of the above values is normally done as part of a tuning exercise to improve performance. It is not possible to recommend alternative values without examining the performance characteristics of a particular system. You must carry out any changes with great care, to avoid affecting the performance of your system adversely.


| 67

Index

A

Apache XALAN 17Apache XERCES 17Array fields as input and output parameters 32

C

Character encoding 61converting data to Java strings 61UNICODE 61

Creating Java Objects 9customer support ix

D

Defineinput parameters from Java object 27Java call parameters 24output parameters from Java object 29

Delayed Releaseimplementing 13overview 4performing manually 55

Delayed release and withdrawimplementing 14

DelayedReleasePluginSDK 11

E

EAI Javaunderstanding the process 3

EAI Java SDK 11

EAIJSDK.jar 11Error Messages 44

I

Immediate Releasediagram 5implementing 13overview 4

ImmediateReleasePluginSDK 11Input fields

arrays 32to Java Object 29

InterfacesDelayed Release 13Delayed release and withdraw 14Immediate Release 13

J

Java Objectcreating 9dynamic loading 17input fields 29name to be called 25output fields 31set cache option 26

K

Keep Alive optionCache Java Object 26


68 | Index

L

Log4J setup 40

M

Manual delayed release 55Migrating

old procedures to new format 36previous versions 35run-time code 37

O

Output fields, from Java Object 31

R

Return values for getType() 59

S

SDK, EAI Java 11SUN Java Web Services Developer Pack 17support, contacting ix

T

technical support ixTransaction scope of EAI Java steps 7

W

Withdrawoverview 4

WithdrawablePluginSDK 11

X

XML parsing 17


Documents

TIBCO iProcess Java Plug-in