TIBCO iprocess Java Plug-in User s Guide

Transcription

1 TIBCO iprocess Java Plug-in User s Guide Software Release 11.5 April 2015 Two-Second Advantage

2 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 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

3 i Contents Preface iii Related Documentation iv TIBCO iprocess Java Plug-in Documentation iv How to Use This Guide v Target Audience v Typographical Conventions vi Connecting with TIBCO Resources ix How to Join TIBCOmmunity ix How to Access TIBCO Documentation ix How to Contact TIBCO Support ix Chapter 1 Introduction to EAI Java Steps Why Use an EAI Java Step? Overview of How an EAI Java Step Works Understanding the EAI Java Step Process Using Delayed Release or Immediate Release Invocations EAI Java Step Architecture Transaction Scope of EAI Java Steps Chapter 2 Creating Your Java Object Prerequisites Using the EAI Java SDK Implementing the Interfaces Immediate Release Delayed Release Delayed Release and Withdraw Working with the Interfaces Defining Exceptions Error Logging Activity Dynamic Loading of Java Objects (Advanced Topic) XML Parsing (Advanced Topic) Examples Manually Creating a Java Object Using the Example Java Objects

4 ii Contents Chapter 3 Defining EAI Java Steps Creating an EAI Java Step Define Basic EAI Step Information Creating and Editing an EAI Java Step Define the Call to the Java Object Define iprocess Java Plug-in Input Parameters Define the iprocess Java Plug-in Output Parameters Using iprocess Array Fields as Input and Output Parameters Passing All Array Field Values to the Java Object Passing One Array Field Value to the Java Object Chapter 4 Migrating Procedures and Code From Previous Versions Migrating Procedures From Versions Prior to i10.0(3.0) Migrating Run-time Code Editing Run-time Code From Versions Prior to i10.0(3.0) Editing Run-time Code From Version i10.0(3.0) Appendix A Using the Log Files Setting Up Log4J Examples Error Messages iprocess Engine Error Messages iprocess Workspace Error Messages Java Logs Appendix B Manually Performing a Delayed Release Overview Manually Performing a Delayed Release Appendix C Return Values for gettype() Appendix D Character Encoding Appendix E Configuring Database Connections Introduction Database Pooling Index

5 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

6 iv Related Documentation Related Documentation This section lists documentation resources you may find useful. TIBCO iprocess Java Plug-in Documentation You 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 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.

7 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 Audience This guide is aimed at the following types of user: Procedure definers Application developers and systems integrators Java developers

8 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. 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. The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention SWDIR SWCLIENT Use 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). Indicates the directory where the TIBCO iprocess Workspace is installed.

9 Preface vii Table 1 General Typographical Conventions (Cont d) Convention code font Use 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.

10 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}

11 Preface ix Connecting with TIBCO Resources How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to How to Access TIBCO Documentation You can access TIBCO documentation here: How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, contact TIBCO Support as follows: For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: If you already have a valid maintenance or support contract, visit this site: Entry to this site requires a user name and password. If you do not have a user name, you can request one.

12 x Connecting with TIBCO Resources

13 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

14 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.

15 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 Process When 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 25) 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.

16 4 Chapter 1 Introduction to EAI Java Steps 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 Invocations The 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. 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. 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.

17 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. Client Server Java Object TIBCO iprocess Database Delayed Release Handler JDBC Connection TIBCO iprocess Workspace Delayed Release Route (Asynchronous) - Phase 2 TIBCO iprocess Engine Java Object Immediate Release Route (Synchronous) TIBCO iprocess Modeler iprocess Java Server Plug-in Delayed Release Route (Synchronous) - Phase 1 iprocess Java Client Plug-in EAI Java Step Business Process

18 6 Chapter 1 Introduction to EAI Java Steps 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.

19 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. 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. Refer to Using Enterprise Application Integration (EAI) Steps in the TIBCO iprocess Modeler - Integration Techniques guide for more information about EAI steps and transactions.

20 8 Chapter 1 Introduction to EAI Java Steps

21 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

22 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 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 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.

23 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. You must not change the contents of this file because the functionality of the iprocess Java Plug-in will be compromised. 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 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. Your custom Java object should implement these interfaces according to the iprocess invocation style that you want to use, as follows. Desired invocation style Immediate release Delayed release Use these interfaces ImmediateReleasePluginSDK DelayedReleasePluginSDK

24 12 Chapter 2 Creating Your Java Object Desired invocation style Delayed Release and Withdraw Use these interfaces DelayedReleasePluginSDK and WithdrawablePluginSDK 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.

25 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.

26 14 Chapter 2 Creating Your Java Object 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. 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. 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 Withdraw The 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.

27 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).

28 16 Chapter 2 Creating Your Java Object Working with the Interfaces The following sections describe other topics that you should take into consideration when implementing your chosen interfaces. Defining Exceptions In 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. The delayed release asynchronous interface does not throw a non-fatal exception. 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 Activity The 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.

29 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. 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: Thread currentthread = Thread.currentThread(); currentthread.setcontextclassloader(this.getclass().getclassloader()); XML Parsing (Advanced Topic) The following represents a major change for version onwards of the iprocess Java Plug-in. 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 and XALAN 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. Changing the values contained in the xmlparser.properties file is NOT supported.

30 18 Chapter 2 Creating Your Java Object Examples The following sections summarize the two different approaches you can use to create your Java object. Manually Creating a Java Object The 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.

31 Examples 19 Using the Example Java Objects Example 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 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.

32 20 Chapter 2 Creating Your Java Object

33 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

34 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 Information 1. 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.

35 Creating an EAI Java Step (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 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 Step You 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.

36 24 Chapter 3 Defining EAI Java Steps Define the Call to the Java Object At this point: If you are creating a new EAI Java step, the dialog shown in the following illustration is displayed.

37 Creating an EAI Java Step 25 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.. 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.

38 26 Chapter 3 Defining EAI Java Steps 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 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 or posts an HTTP request depending on whether HTTP or is specified as the static data string. At this point: 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 26. 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 26; 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 Parameters At this point:

39 Creating an EAI Java Step 27 If you are creating a new EAI Java step, the dialog shown in the following illustration is displayed.

40 28 Chapter 3 Defining EAI Java Steps 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.

41 Creating an EAI Java Step (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. 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. 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 Parameters At this point:

42 30 Chapter 3 Defining EAI Java Steps If you are creating a new EAI Java step, the dialog shown in the following illustration is displayed.

43 Creating an EAI Java Step 31 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 <<. 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. 2. Click Finish on the wizard or OK on the tabbed dialog when you have defined all your output fields.