Using Integration Objects

This chapter introduces Integration Objects, which are JavaBeans that encapsulate interactions with a host application. If you have used IBM WebSphere Host Publisher, you are already familiar with most aspects of Integration Objects, but you will need to learn about how Integration Objects are used in HATS. You do not need to be an experienced Host Publisher developer to create and use Integration Objects in HATS.

If your HATS application will transform a single host application, with no secondary connections, you do not need to use Integration Objects. You may need to use Integration Objects if any of these statements are true:

When you have created an Integration Object, you can use it in many ways:

Refer to the HATS Programmer's Guide for information about other advanced tasks that can be performed with Integration Objects. Some of the tasks discussed are:

Creating an Integration Object

An Integration Object is created from a macro. Follow the steps described in Macros and Host Terminal to record a macro.

Right click on the macro in the HATS Project View and select Create Integration Object. The Integration Object will have the same name as the macro. You can also set a preference in HATS to automatically generate an Integration Object when a macro is recorded. Click Window > Preferences, expand HATS in the tree on the left, and click Integration Object. Check the box labeled Automatically generate Integration Object when saving macro, then click Apply.

When naming a macro used to create an Integration Object, ensure that you follow these requirements:

Note:
Automatically generated Integration Objects are always non-chained.

Integration Objects cannot get created from chained macros. Integration Object chaining is quite different from macro chaining, in that each Integration Object in a chain is run to completion before the next Integration Object in the chain takes control. Macro chaining, using the play macro action, terminates the current macro (the one in which the play macro action occurs) and begins to process the specified macro screen of the target macro. If you import a HOD macro that contains the <playmacro name="chainedMacroName/" tag, you can only use this macro in the HATS play macro and perform macro transaction actions. See HATS Advanced Macro Guide for more information on macro chaining.

Note:
If you create JSF pages for a chained Integration Object, the JSF pages do not display any outputs in the browser.

If a macro is changed using the macro editor, after an Integration Object has been created from that particular macro, the Integration Object has to be regenerated to accurately reflect the change. If the Automatically generate Integration Object when saving macro preference is selected, the Integration Object will be updated automatically.

To see a list of Integration Objects which you have created, click the HATS Project View tab of the HATS Studio and expand the project name, then go to Source > IntegrationObject and double click the folder to view the contents.

Note:
The IntegrationObject folder under Source is only visible after creating your first Integration Object.

Integration Object chaining

Integration Object chaining enables you to create multiple Integration Objects which can be grouped together into a single major task within your Host Access Transformation Services application. Each Integration Object performs one subtask, and the major task is performed by an Integration Object chain. When the application is executed, the Integration Objects execute in sequence, each using the same connection.

When you right click on the macro to create the Integration Object, select Create Chained Integration Object. Then specify whether the Integration Object is the first, middle, or last in the chain. There can be more than one middle Integration Object in a chain. Enter the labels that identify the start and stop states for this Integration Object. There is no start state label for an Integration Object that is first in its chain, and no stop state label for an Integration Object that is last in its chain. State labels are required to ensure that the Integration Objects in a chain are processed in the correct order, with the correct data passed each time.

This section describes Integration Object chaining in detail and shows you how to use it in your HATS applications.

Deciding when to use Integration Object chaining

To determine how many Integration Objects are needed in the chain, begin by listing all of the subtasks that need to be performed. For example, imagine a host application called fileview that, when invoked, displays a list of files. From the list of files, a user can select any file by typing 1 next to its name, pressing Enter, then viewing its contents. There are two tasks to perform here:

  1. Obtain the list of files to present to the user.

  2. Retrieve file details for a selected file.

Two macros are required because the user must make a decision before the second macro can execute. The second macro must wait for user input. Defining where user input is required is the first step in separating your tasks into individual Integration Objects.

If the user has multiple choices and each choice causes different host actions, then each choice must be a separate Integration Object. You can then piece together the Integration Objects dynamically, depending on the selections of the user. An example of this is a menu of five items. If the user is allowed to select any of the five choices, each selection must be created as an independent Integration Object.

After you understand the number of distinct tasks in your application, you can decide how chaining will affect your application. If you have more than two tasks, chaining might help improve your application's response time or decrease the amount of macro recording do, thus reducing the overall complexity of your Integration Objects.

Using Integration Object chaining

An Integration Object in a chain leaves the connection in a state (at a particular screen). After the Integration Object finishes running, another Integration Object that begins in that state (that is, at that screen) can run.

You can use chaining to break up a complex application into multiple tasks, each task represented by an Integration Object. You must ensure that the order of the Integration Objects is correct.

For example, if you have three Integration Objects in a chain (A, B, and C), then use A first, then B, then C. If Integration Object C is invoked before Integration Object B, then when C requests its connection, the connection is not available in the correct state, and the Integration Object fails.

Figure 34. Connection lifetime with chaining

connection lifetime with chaining

Figure 34 depicts the lifetime of a connection throughout the execution of three Integration Objects. Integration Object A is configured as first, Integration Object B as middle, and Integration Object C as last. Connection state data represents the connection and the state label of the last Integration Object executed.

  1. When Integration Object A begins to execute, it retrieves the connection specified in the macro. If checkin screen enabled and a connection is available, the connection is already logged on and ready. If checkin screen is enabled, but a connection is not available, the connection is created and the connect macro (if specified) is executed. If checkin screen is disabled, a connection is created and the connect macro (if specified) is executed.

  2. Integration Object A runs the associated macro, then saves the connection and its current state for the next invocation. (You would have defined this state as the stop state label during Integration Object chaining).

  3. When Integration Object B begins to execute, it retrieves a connection and its state from the connection state data because it is the middle Integration Object. You must have defined Integration Object B's start state label as Integration Object A's stop state label, which allows these Integration Objects to be chained.

  4. When execution completes for Integration Object B, the connection and its state are saved in the connection state data.

  5. Integration Object C also retrieves the connection from the connection state data. When Integration Object C begins to execute, it retrieves a connection and its state from the connection state data because it is the last Integration Object. You must have defined Integration Object C's start state label as Integration Object B's stop state label, which allows these Integration Objects to be chained. Last-in-chain Integration Objects have no end labels because the connection is always returned.

  6. When checkin screen is enabled, the connection returns to the pool; otherwise, the disconnect macro (if specified) is executed and the connection ends.
Note:
Settings for the checkin screen are made by going to Macro tab of your connection settings. You must enable pooling in order for the checkin screen setting to be available. For more information, see Connection editor.

To build an application using Integration Object chaining with HATS, you must first build the Integration Objects and then create your Web pages from the Integration Objects.

Follow these steps to create your application:

  1. Record macros

  2. Create chained Integrations Objects from each macro

  3. Create Web pages for each Integration Object.

Record a Macro

You can record macros in HATS Studio using the HATS host terminal. On the HATS host terminal screen, click the Record Macro icon. For information on recording macros, see ***.

Repeat these steps for each Integration Object you want to create.

Create Integrations Objects from each macro

Once all of your macros are created, you can go to the HATS Project View tab of the HATS Studio and expanding the project name, and open the Macros folder.

Right-click on each individual macro and select Create Chained Integration Object. You will have the option of selecting the position in the object chain to either First, Middle or Last. If you select First, the state will be the stop state during Integration Object chaining configuration. If you select Middle, the state can either be the start state, or the stop state. The Last position of the object chain uses the start state.

This needs to be done for all the Integration Objects which are part of the chain.

Create Web pages from each Integration Object.

Once you have created your Integration Objects, you can then create your Web pages. For information on creating Web pages from Integration Objects, see Building Web pages from an Integration Object.

Debugging applications that use Integration Object chaining

While Integration Object chaining is a powerful tool for modeling the most complex host applications, take care when assembling your applications. There is a risk of creating a J2EE application with Integration Objects that are invoked out of order; therefore, you should be aware of the errors you get on the server when this happens.

If you chain the Integration Objects incorrectly, you will experience problems when you run your Integration Object. Here are the error messages you might see on the server and how to debug them.

HPS5075 Received STATE_PLAY_ERROR while playing macro in file zzz.macro

This error occurs when the macro fails to play because it cannot match the current screen. This might happen if an Integration Object in a chain is invoked in the correct order (a connection in a specific chain was found for it to use), but the macro itself failed to play. It can be a problem if your start and stop state labels are all the same, or at least are the same for two Integration Objects, and you invoke the Integration Objects out of logical order.

HPS5035 There is no data source object {0} in HttpSession. A possible cause is the use of multiple browsers from a single machine to a chained application. See documentation for more information.

This error occurs when an Integration Object with a start state label of last Integration Object state fails to retrieve the connection and its state because its start state label does not match the stop state label of the preceding Integration Object.

When this happens, determine why this Integration Object is being invoked out of order.

  • Are you sure that another Integration Object (either a first or middle Integration Object) has already run and has placed its connection in the state labeled last Integration Object state (its stop state label)?

  • Are you sure that the JSP running this Integration Object was linked in the correct order?

  • Is there another Integration Object on the JSP that should have put the connection into the state labeled last Integration Object state and that failed? This does not always prevent other Integration Objects on the page from being invoked. You might be looking at a chain of errors.

Building Web pages from an Integration Object

You can create a JSP from any Integration Object There are three approaches to building these pages; they are called Model 1, JSF, and Struts. The following sections describe these three approaches and how to create pages using them.

Create Model 1 Web pages

The "traditional" HATS approach to building a JSP is called Model 1. In this model, a single JSP contains:

  • The information to be presented to the user

  • Formatting tags that specify how the information is displayed

  • Control logic that controls which page is called next

In the HATS Project View, right click on the name of an Integration Object and select Create Model 1 Web Pages. Specify the output page name along with the destination, or accept the default name created from the Integration Object name. You can also specify Page generation options by selecting Append to existing files or Overwrite existing files. Click Finish after completing your selections.

When you create Model I Web pages, you will define two pages: an input page, which gathers the data required by the Integration Object, and an output page, which presents the results after the Integration Object is executed. You will define a source for each input property, either an HTML control for the JSP or a global variable (global variables used by Integration Objects are shared). The input sources will be prefilled based on the macro handler chosen for the macro from which the Integration Object was generated. When the input page is executed, it does not pass control directly to the output page; it returns control to the HATS servlet so that global variables can be set and other actions taken as needed.

Note:
If your macro has no prompts, there will be no input page.

Next you will choose the output properties of the Integration Object that you want to display on the output JSP. If you display several output properties, put them into a table or a list. You can also specify that the output properties should be stored in global variables. The output JSP will contain code to initialize the Integration Object, to set the Integration Object properties from global variables, to execute the Integration Object, and to display the Integration Object output.

The pages you create will go in Model 1 Pages folder. To test your pages, open the folder, and find your input page (or output page if there is no inputs). Right-click on the page and choose Run on Server.

Create Struts Web pages

HATS enables you to use Struts to build Web pages based on Integration Objects. In the HATS Project View, right click on the name of an Integration Object and select Create Struts Web Pages. Specify names for input and output pages, or accept the default names created from the Integration Object name. Click Finish.

When you create Struts Web pages, HATS generates five new files:

Struts Action class

This class is the main class. It instantiates the Integration Object, sets the Integration Objects properties using values in the ActionForm class, sets the Integration Object's poolname, and executes the Integration Object. It then forwards to the output JSP, or if there is an error, then it returns to the HATS runtime and allows the HATS runtime to handle the error. The developer should not modify this class.

ActionForm class

This class contains setters and getters for each input in the input JSP. The input JSP submits to the Struts Servlet, which instantiates the ActionForm class and sets all of its properties based off the submitted input JSP form. This class is used by the Action class to set all of the Integration Objects properties. If you add or remove input properties from the input JSP, add or remove the matching setters and getters from this file.

input JSP

The input JSP contains a Struts HTML form that will send the request to the Struts Controller, which creates an ActionForm and forwards the request to appropriate Action class. If the Integration Object does not need any input, or where the inputs come from different sources, such as global variables, an empty input JSP will be created containing only the HTML form. The input page will be created in the Struts Pages folder. To test your pages, open the folder and find the page you created. Right-click on the page and choose Run on Server.

output JSP

The output JSP displays the Integration Object's output properties. This page is similar to the Model 1 output JSP.

WebDiagram

This file displays the flow and logic of the Struts based web pages. Please refer to the Struts tooling documentation in Rational Studio for more information about modifying the Web Diagram.

HATS also adds an action mapping to the struts-config.xml file to associate the Action class with the ActionForm class.

Struts was developed as part of the Apache Software Foundation's Jakarta project. For detailed information about Struts, refer to http://jakarta.apache.org/struts as well as the Rational Studio help contents.

Create JSF Web pages

JavaServer Faces (JSF) is a framework for developing user interfaces (UI) for Web applications which run on a Java server. You can quickly build web applications by assembling reusable UI components in a page. Once you have created JSF Web pages, you can use tools such as page designer and the palette for modifications and editing.

In the HATS Project View, right click on the name of an Integration Object and select Create JSF Web Pages. Specify names for input and output pages as well as the destination, or accept the default names created from the Integration Object name. You can also Overwrite existing files by checking the check box. Click Finish after completing your selections.

You can see the newly created JSF Web pages by expanding the Web Content/JSF Pages folder of the HATS Project View tab of the HATS Studio. To edit a Web page and invoke the page designer editor, double-click on the name of the page.

BasicIOErrorPage.jsp and AdvancedIOErrorPage.jsp

The BasicIOErrorPage is the default error page used by JSPs that drive Integration Objects.

If an error occurs, it will return basic information to the browser about the nature of the error. The backend connection is automatically discarded in this processing. The AdvancedIOErrorPage.jsp allows the connection to be passed to the HATS entry servlet for a default transformation if the connection was created from the default connection definition.

This processing allows you to interact with the backend connection and possibly determine why the error happened. The default transformation also gives you the ability to disconnect the connection. Basically, the AdvancedIOErrorPage.jsp gives you more control over the processing when an Integration Object encounters an error.

Working with Integration Objects on JSPs

These HATS tools functions are applicable to working with Integration Objects on JSPs. You can select the items listed below using the HATS Tools menu on HATS Studio menu bar.

Insert Integration Object Properties

You can added Integration Object input and output to your transformation JSP.

Input

Select Insert Integration Object Properties > Input when you want to add Integration Object input to a JSP. From Insert Input Controls, select the name of the Integration Object you wish to use and then the page that displays when the end user submits the input form. Click Next to define the Integration Object input properties by highlighting the input and clicking Edit. Here you can define the leading text, choose and appropriate input control and configure it if necessary, and store the value as a global variable.

Output

Select Insert Integration Object Properties > Output when you want to add Integration Object output to a JSP. From Insert Output Controls, select the name of the Integration Object you wish to use and click the check box Insert Integration Object transaction methods to include the transaction methods that run Integration Objects.

Note:

A HATS global variable contains a value that can be used to pass information from one HATS object to another. If you want to pass Integration Object output data to another HATS object, add code to the output JSP used to drive the Integration Object. You should add the code after successfully running the Integration Object, for example: 

<%
IOGV.setGlobalVariableString(session, "exampleGV", 
exampleIO.getOutputData());
%>

In this example, the shared global variable named exampleGV is assigned the value of the OutputData property of the exampleIO Integration Object.

The global variable used in an Integration Object environment must be defined as a shared global variable. The code in the example creates the shared global variable if it does not already exist.

Insert Forward to HATS Servlet

Select Insert Forward to HATS Servlet to add a button to your transformation that forwards JSP control information to the HATS entry servlet, the servlet that is processed when a users starts your HATS application. For example, you might want to return control to the HATS entry servlet after a JSP drives an Integration Object and performs a designated task. You can edit the attributes of this button in the Design view by highlighting the button, right-clicking, and selecting Attributes.