Integration Objects

Integration Objects 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:

You can have HATS automatically generate an Integration Object each time you save a macro. To set this preference, see Use HATS preferences.

 

Create an Integration Object

To create an Integration Object, follow the steps described in Incorporating macros 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 so that whenever you create a macro, an Integration Object with the same name will be created. 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.

An Integration Object will always be non-chained if you choose this option.

If, after creating an Integration Object from a macro, you change the macro using the macro editor, the Integration Object will be updated automatically to accurately reflect the macro. If you did not check Automatically generate Integration Object when saving macro, then Integration Object will not be regenerated to reflect the macro changes.

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.

 

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.

 

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

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 4. Connection lifetime with chaining
connection lifetime with chaining

Figure 4 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 connection pooling is enabled and a connection is available, the connection is already logged on and ready. If connection pooling is enabled, but a connection is not available, the connection is created and the connect macro (if specified) is executed. If connection pooling 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 connection pooling is enabled, the connection returns to the pool; otherwise, the disconnect macro (if specified) is executed and the connection ends.

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 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. The Record Macro wizard appears and enables you to name the macro, give it a description, and specify where the macro is saved. Click Finish when you have specified these items. Next the Define Screen Recognition Criteria window will appear because HATS forces the first screen to have defined screen recognition. You can then use the HATS host terminal screen to navigate through the host application to any screen.

When you are finished recording your macro, click the Stop Macro icon. Once you have stopped your macro you will need to save it by clicking the Save Macro icon.

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, 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 page 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.

In any case, check the message log for the and look for reasons for the problem. Refer to message HPS5035 in HATS Messages for details.

 

Building Web pages from an Integration Object

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

 

Model 1 and Model 2

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

In Model 2, these three elements are divided into separate files. Model 2 is also called the Model-View-Controller approach, because it divides each component into the model (business information), view (how the information is presented), and controller (which page is presented next).

WebSphere Studio provides support for Model 2 development by incorporating Struts, a set of Java classes and JSP tag libraries that form an open-source framework for building Web applications. 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.

 

Building input and output JSP pages

If you choose to 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 page 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.

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

Next you will choose the output properties of the Integration Object that you want to display on the output JSP page. 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.

 

Building 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 WebSphere 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.

For detailed information about Struts, refer to http://jakarta.apache.org/struts as well as the WebSphere Studio help contents.

 

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.

 

Work with Integration Objects on JSP pages

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

 

Insert Integration Object Input

Select Insert Integration Object 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.

 

Insert Integration Object Output

Select Insert Integration Object 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.

 

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.

 

Home