This chapter introduces Integration Objects, which are Java™ beans that encapsulate interactions with a host application. Integration Objects are supported only by HATS Web applications.
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.
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 Web Application Programmer's Guide for information about other advanced tasks that can be performed with Integration Objects. Some of the tasks discussed are:
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 Projects 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. Select 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:
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 HATS 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 Host On-Demand 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 about macro chaining.
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 Projects view tab of the HATS Toolkit and expand the project name, then go to Source > IntegrationObject and double click the folder to view the contents.
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 run, the Integration Objects run 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.
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:
Two macros are required because the user must make a decision before the second macro can run. 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 you must do, thus reducing the overall complexity of your Integration Objects.
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 you must 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 76 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 run.
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:
You can record macros in HATS Toolkit using the HATS host terminal. On the HATS host terminal screen, click the Record Macro icon. For information about recording macros, see Macro related icons.
Repeat these steps for each Integration Object you want to create.
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.
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 Java EE 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.
When this happens, determine why this Integration Object is being invoked out of order.
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.
The traditional HATS approach to building a JSP is called Model 1.
In this model, a single JSP contains:
In the HATS Projects view, right click on the name of an Integration Object and select Create Model 1 Web Pages. Specify the input and output page names along with the destination, or accept the default names created from the Integration Object name. You can also specify Page generation options by selecting Append to existing files or Overwrite existing files. Click Next after completing your selections.
When you create Model 1 Web pages, you 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 run.
On the Define inputs page, you can define an input control for each input property. HTML controls are used as defaults. To change a control, select an input property and click Edit. You have the option to render input properties using either HTML controls or Dojo widgets. You can mix HTML controls and Dojo widgets on the same Model 1 web page. You can add the leading text for the control and, where necessary, configure the selected control. Instead of using an input control, you can elect to set the input property to the value of a global variable. You also have the option to store the input property value as a global variable (global variables used by Integration Objects are shared). When the input page is run, it does not pass control directly to the output page; it returns control to the HATS application allowing global variables to be set and other actions to be taken as needed.
On the Define outputs page, you select the output properties of the Integration Object that you want to display. To change a control, select an output property and click Edit. You have the option to render output properties using either HTML controls, Dojo widgets, or normal text. You can mix HTML controls and Dojo widgets on the same Model 1 Web page. You can add the leading text for the control. The output JSP contains code to initialize the Integration Object, to set the Integration Object properties from global variables, to run the Integration Object, and to display the Integration Object output.
The pages you create go in the Web Content/Model 1 Pages folder in the HATS Projects view. To edit a Web page and invoke the Rich Page Editor, double-click on the name of the page. To test your pages, right-click on the input page (or output page if there are no inputs) and select either Debug on Server or Run on Server.
SignOn.setHPubStartPoolName("<new_project_name>/<default_connection>");HATS enables you to use Struts 2 to build Web pages based on Integration Objects.
In the HATS Projects 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 following new files:
HATS also adds or updates an action to the struts.xml file to associate the Action class with the input/output/error 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 the Rich Page Editor and the palette for modifications and editing.
In the HATS Projects 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 selecting the check box. Click Next after completing your selections.
When you create JSF Web pages, you 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 run.
For the input page, you can define an input control for each input property. To change a control, select an input property and click Edit. You can add the leading text for the control and, where necessary, configure the selected control. Click Next.
For the output page, you select the output properties of the Integration Object that you want to display. To change a control, select an output property and click Edit. You can add the leading text for the control. Click Finish.
The pages you create go in the Web Content/JSF Pages folder in the HATS Projects view. To edit a Web page and invoke the Rich Page Editor, double-click on the name of the page. To test your pages, right-click on the input page (or output page if there are no inputs) and select either Debug on Server or Run on Server.
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.
You can find these error pages in the Navigator view, in the Web Content folder of your project.
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 Toolkit menu bar.
You can add Integration Object input and output to your transformation JSP.
Select Insert Integration Object Properties > Input when you want to add Integration Object input to a JSP. On the Select Integration Object class page, enter the class name of the Integration Object you want to use and the destination page that displays when the user submits the input form. Click Next. On the Define inputs page, to change a control, select an input property and click Edit. Here you can define the leading text, select an appropriate input control and configure it if necessary, and store the value as a global variable.
Select Insert Integration Object Properties > Output when you want to add Integration Object output to a JSP. On the Select Integration Object class page, enter the class name of the Integration Object you want to use and click the check box Insert Integration Object transaction methods to include the transaction methods that run Integration Objects. Click Next. On the Define outputs page, to change a control, select an output property and click Edit. Here you can define the leading text and select an appropriate output control.
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, you must 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.
Select Insert Forward to HATS Application to add a button to your transformation that forwards JSP control information back to the HATS application, either Web application or standard portlet, that your user started. For example, you might want to return control to the HATS application 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.