Integration Objects - advanced topics

 

+
Search Tips   |   Advanced Search

 

Integration Objects are created from templates containing Java code. The templates are stored as part of the HATS Studio toolkit in...

wstools/eclipse/plugins/com.ibm.hats/predefined/IOTemplates/predefined/IOTemplates

The default templates are...

The customizable templates are...

The default templates contain Java code that is independent of the HATS and Host On-Demand code. Integration Objects created using the default templates will not need to be recompiled and redeployed if the HATS or Host On-Demand code changes for enhancements or service.

The default templates call methods from the superclass. The customizable templates contain the methods, which you can customize. You can modify the HPubTemplateHODBean.Customize template to add function to your Integration Objects. For example, you might want to find out not just the text on the host screen, but also its characteristics, such as color or highlighting.

The customizable templates contain substantial Java code that interacts with the HATS code, Host On-Demand objects, events, and other Java constructs. These templates enable you to modify an Integration Object to perform additional functions. Integration Objects created using the customizable templates will contain code that directly interacts with the HATS and Host On-Demand code and implements much of the data processing. If any HATS or Host On-Demand code changes affect the code contained in the Integration Object, the Integration Object might have to be recompiled and redeployed.

The templates used by HATS are different from those used by Host Publisher. If you modified an Integration Object template in Host Publisher, make the same changes to the templates provided by HATS and recreate your Integration Objects in order to achieve the same functions in your Integration Objects. When you import or migrate a Host Publisher Integration Object created with a modified template, or an application using such an Integration Object, you will see a message indicating that the Javabean was created from a customized template.

 

Choosing Integration Object templates

If you do not need to modify how Integration Objects interact with HATS or the operating environment, always use the default templates, HPubTemplateHODBean.Default and HPubTemplateHODBeanInfo.Default. You do not need to take any action to use these templates, unless you have previously selected a different template.

If you want Integration Objects to perform additional functions, make a copy of the HPubTemplateHODBean.Customize and HPubTemplateHODBeanInfo.Customize templates and rename them. Modify the new template files to add Java code for the functions you want the Integration Objects to perform.

If you use either the customizable templates or renamed copies of the templates, tell HATS which templates to use when creating Integration Objects. To choose Integration Object templates in HATS Studio, click...

Window | Preferences | Host Access Transformation Services | Integration Object

Use the Browse buttons to locate the Integration Object templates you want to use.

 

Modify Java coding templates

The HPubTemplateHODBean.Customize and HPubTemplateHODBeanInfo.Customize templates contain Java code that is incorporated into the Integration Object Java bean code (.java) file when the Integration Object is compiled. The templates also contain constructs specifically for HATS, prefaced with a percent sign (%). These constructs enable HATS to create Java beans from the data specified by the user when the Integration Object is created. When modifying the template files, be careful not to delete the statements containing the HATS constructs. Make backup copies of the HPubTemplateHODBean.Customize and HPubTemplateHODBeanInfo.Customize templates before you begin making changes to the template files.

For example, suppose that you want to trace the name and the x and y screen coordinates of the Host On-Demand Extract Events that are processed by an Integration Object.

Extraction of the x and y screen coordinates is not available in the Web Services or EJB environments, because the x and y coordinates require access to internal variables not available in those environments.

Follow these steps:

  1. Back up the file HPubTemplateHODBean.Customize.

  2. Change the code that extracts the macro event in HPubTemplateHODBean.Customize to add the following lines after the pullVariableValueFromExtractData( haovWorkOnThis, data);... statement: 
    
     // --- Trace X and Y screen coordinates example ---
     if (HPubTracingOn) 
     {
       String strg = "Extracting variable: " 
                    + stringExtractNameForThisEvent 
                    + " from screen location (" 
                    + haovWorkOnThis.intXScreenLocation + "," 
                    + haovWorkOnThis.intYScreenLocation + ")";

       Ras.trace( this.getClass().getName(),"macroExtractEvent", strg);
     }

    For example: 

    ...
  public void macroExtractEvent(MacroExtractEvent oMacroExtractEvent)
  { 
    // a HOD macroExtractEvent was fired for this macro
    ...
    pullVariableValueFromExtractData( haovWorkOnThis, data);

     // --- Trace X and Y screen coordinates example ---
     if (HPubTracingOn) 
     {
       String strg = "Extracting variable: " 
                    + stringExtractNameForThisEvent 
                    + " from screen location (" 
                    + haovWorkOnThis.intXScreenLocation + "," 
                    + haovWorkOnThis.intYScreenLocation + ")";

       Ras.trace( this.getClass().getName(),"macroExtractEvent", strg);
     }...

  3. Update the HATS preferences to point to your new templates.

  4. Create an Integration Object as you normally would. If you want to modify an existing Integration Object to trace the name and the X and Y screen coordinates of the Host On-Demand Extract Events, re-create the Integration Object by right-clicking on the macro and selecting Create Integration Object. If you introduced Java syntax errors in your template changes, they will show up as compile error messages in the task list.

  5. Rebuild your HATS project: in the HATS Project View, right click the name of your project and select Rebuild HATS Project.

  6. If you already have a way to invoke your Integration Object, skip this step. To test your Integration Object, right click the name of the Integration Object and select either Create Model 1 Web pages or Create Struts Web pages. This will create a page from which you can supply the required inputs and invoke your Integration Object.

  7. Test your modified Integration Object using the Run on Server function: in the HATS Project View, right click the name of your project and select Run on Server. If you have not already done so, modify the WAR classloader policy of your HATS application on the server; refer to HATS Getting Started for more information.

 

Example modified Integration Object template

Appendix B. Sample modified Integration Object template contains an example Integration Object template, created by adding code to HPubTemplateHODBean.Customize. This example illustrates the use of a custom screen recognition criterion, which is added to the macro within the description of the appropriate screen, to trigger the DoReco() method, which is defined in the template. DoReco() saves all the fields of the host screen in an XML string named extendedxml. A getter method, getExtendedxml(), is provided so that the value can be extracted by a JSP after the Integration Object has been executed. The changes made to the template are marked with the comment // ADDED FOR XML TABLE.

The use of a custom screen recognition criterion, or descriptor, is of particular interest because it enables you to capture the content of any screen encountered by the Integration Object. Integration Objects are not notified when the host screen changes or when a screen is recognized. By inserting a custom screen recognition criterion, you can work with any screen.

To invoke the code that has been added to the template, modify the macro from which you will build the Integration Object. Locate the screen whose information you want to capture, and add this line as the last descriptor:

<customreco id="HPubExtractFieldAttributes|" optional="false" invertmatch="false" />

Be sure to add it after the other descriptors, so that it will be used only on the desired screens; otherwise you might collect data from the wrong screens. Note that the customreco id is "HPubExtractFieldAttributes", but the line added to the macro has "HPubExtractFieldAttributes|". The '|' character is used as a separator for parameters and must be included here even though there are no parameters.

If the macro uses the uselogic attribute to combine descriptors, update the uselogic value to include the new descriptor, or it will be ignored. Here is an example of the modifications make to the macro. If the original screen description is:

<screen name="Screen2.2" 
        entryscreen="true" 
        exitscreen="true" 
        transient="false">

        <description uselogic="1 and 2" >

            <oia status="NOTINHIBITED" 
                 optional="false" 
                 invertmatch="false" />

            <string value="Ready; T" 
                    row="1" 
                    col="1" 
                    erow="-1" 
                    ecol="-1" 
      casesense="true" 
                    optional="false"  
                    invertmatch="false" />

        </description>

Then here is the screen description with the new descriptor and the modified uselogic:

<screen name="Screen2.2" 
        entryscreen="true" 
        exitscreen="true" 
        transient="false">

        <description uselogic="1 and (2 and 3)" >

            <oia status="NOTINHIBITED" 
                 optional="false" 
                 invertmatch="false" />

            <string value="Ready; T" 
                    row="1" 
                    col="1" 
                    erow="-1" 
                    ecol="-1" 
      casesense="true" 
                    optional="false" 
                    invertmatch="false" />

            <customreco id="HPubExtractFieldAttributes|" 
                        optional="false" 
          invertmatch="false" />
        </description>

When the DoReco() method is called, the template checks whether it is being called to process the "HPubExtractFieldAttributes|" custom descriptor. If so, it captures the information from the screen; if not, it passes control to the parent method to perform screen recognition using one of the other descriptors. After the Integration Object completes, the calling JSP can use the getter method to obtain the XML string and then works with it.

 

Use Integration Objects in a WebSphere J2EE Application

This section describes how to use Integration Objects in two types of applications:

 

Use an Integration Object in a Web container (custom servlet or JSP)

The instructions in this section refer to Integration Object methods. See Integration Object methods for a description of these methods.

You can create your own Web project that runs Integration Objects. This section lists the steps to move files from your HATS project to another Web project and configure it to run your Integration Objects. This set of steps support exporting and using one or more individual Integration Objects. If you want to use a chain of Integration Objects, copy all the files as described here and ensure that the Integration Objects run in the correct order.

HATS maintenance will not be applied to Integration Objects deployed in a separate Web project. The best way to apply maintenance to Integration Objects used in this way is to update the Integration Objects in a HATS project and then re-export them following the procedure described here.

  1. Create a Web project. Copy the Integration Object and BeanInfo source files into the Source directory of the Web project. Be sure to keep the IntegrationObject package.

  2. Copy the profiles directory into the WEB-INF directory of the new project. You can copy the entire directory, or you can re-create the directory structure and copy just the connections and macros subdirectories of the profiles directory, with just the connection and macro used by the Integration Object. You need to end up with these files: 
    WEB-INF\profiles\application.hap
WEB-INF\profiles\connections\ioconn.hco
WEB-INF\profiles\macros\iomacro.hma

  3. Edit the application.hap file to remove unnecessary information. Right click the file, select Open with.. and choose the text editor. When you save your changes in the text editor, you will see a message saying that you are saving a resource in a non-workbench encoding. This is because the file is UFT8-encoded, which is required. Click Yes to continue. If you prefer, you can make a backup copy of application.hap before you copy it to the Web project, and edit it using the HATS editor.

    The only information application.hap must contain is the connections:

    <?xml version="1.0" encoding="UTF-8"?>
<application active="true" configured="true" description="" 
    template="Simple1.jsp">
    <connections default="ioconn">
        <connection name="ioconn"/>
   <connection name="io2conn"/>
    </connections>
</application>

  4. Add all the jar files contained in the HATS .ear FILE into the classpath of the Web project, by moving them either to your own .ear file , or into the WEB-INF/lib directory of the Web project.

  5. Copy the runtime.properties file into the same directory where you added the jars. The location of the logs directory will be in the same directory as the runtime.properties file.

  6. Adds three function calls to initiate the HATS runtime in your servlet or JSP. // Initialize and activate the HATS runtime RAS functions, // including tracing, logging, PII retrieval, locale. com.ibm.hats.util.Ras.initializeRas(getServletConfig()); // Create the license manager com.ibm.hats.util.LicenseManager.getInstance(); // Initialize Host Publisher / connection management runtime 
    com.ibm.hats.runtime.connmgr.Runtime.initRuntime(getServletConfig());

After performing these steps, you will be able to use the Integration Object as a regular JavaBean in your Web project.

To write a servlet that invokes an Integration Object:

  1. Create an instance of your Integration Object by calling its constructor.

  2. Invoke the setter methods for the Integration Object to set properties of input variables. The naming convention for setter methods is as follows: 
    void setXyz(String)
    where xyz is the name of your input variable.

    Use a different connection pool from the one you specified when you created your Integration Object. To specify a different connection pool, invoke the method

    void setHPubStartPoolName(String)

    specifying the name of the connection pool you want to use.

  3. Invoke the Integration Object to perform its task (running a macro, for example): 
    void doHPTransaction(HttpServletRequest, HttpServletResponse)

  4. Check for errors. The doHPTransaction(HttpServletRequest, HttpServletResponse) method will throw an exception (of type com.ibm.HostPublisher.IntegrationObject.BeanException) if the Integration Object has an error.

    When the Integration Object is called by a JSP, the JSP processor will catch the exception and redirect the browser to the error page specified on the errorPage="errorPageName" attribute of the page directive. Refer to the HATS default error page, DefaultErrorPage.jsp, for an example.

    When the Integration Object is called by a custom servlet, your code must catch the thrown exception:

    try {
     integrationObject.doHPTransaction(request, response);
    } catch (Exception e) {
    // Handle the exception condition and recover
    }

  5. Request the results from your Integration Object.

    • Retrieve the values of output variables by invoking one of the following methods:

      • Simple text 
        String getAbc()
        where abc is the name of your output variable.

      • Tables

        • To get an entire column of results, invoke 
          String[] getAbc()
          where abc is the name of your output variable.

        • To get a single value from a column of results, invoke 
          String getAbc(int) throws ArrayIndexOutOfBoundsException
          where abc is the name of your output variable, and int is the index of the value you want. As you iterate through the array, the method will throw an ArrayIndexOutOfBoundsException exception when you have reached the end of the array.

    • Regardless of the application you used to create your Integration Object, you can retrieve the output data in XML format by invoking the following method: 
      String getHPubXMLProperties()
      which returns the IntegrationObject's properties and values as an XML formatted string.

    The input variables for all Integration Objects have getter methods corresponding to each setter method so that you may retrieve those values if necessary. The signature for these methods is 

    void getXyz(String)

    where xyz is the name of your input variable.

    To verify input or output variable names that are generated from data that you entered, look at the properties defined in your Integration Object's BeanInfo java file. The Integration Object's BeanInfo .java file is in the source folder of your project in the IntegrationObject package. In HATS Studio, the BeanInfo file is visible only in the Navigator view.

 

Use an Integration Object in an EJB container (from your own EJB)

The instructions in this section refer to Integration Object methods. See Integration Object methods for a description of these methods.

You can create your own EJB project that runs Integration Objects. This section lists the steps to move files from your HATS project to another EJB project and configure it to run your Integration Objects. This set of steps support exporting and using one or more individual Integration Objects. If you want to use a chain of Integration Objects, copy all the files as described here and ensure that the Integration Objects run in the correct order.

HATS maintenance will not be applied to Integration Objects deployed in a separate EJB project. The best way to apply maintenance to Integration Objects used in this way is to update the Integration Objects in a HATS project and then re-export them following the procedure described here. In addition, if you export HATS runtime .jar files from a HATS .ear into your project, re-export them if you apply HATS maintenance.

  1. Create a custom EJB project. In this example we will call it My_EJB. Copy the application.hap file to the ejbModule folder of the EJB project.

  2. In the ejbModule folder of the EJB project, create a folder named connections. Copy to this folder the .hco file that defines the connection used by the Integration Object.

  3. In the ejbModule folder of the EJB project, create a folder named macros. Copy to this folder the .hma file that defines the macro used by the Integration Object, as well as any connect or disconnect macros required by your connections.

  4. In the ejbModule folder of the EJB project, create a folder named IntegrationObject. Copy to this folder the Integration Object files (*.java and *BeanInfo.java). At this point have these files: 
    ejbModule\application.hap
ejbModule\connections\ioconn.hco
ejbModule\macros\*.hma
ejbModule\IntegrationObject\*.java

  5. Add all the jar files contained in the HATS .ear FILE into the classpath of the EJB project, by moving them either to your own .ear file, or into the ejbModule directory of the EJB project.

  6. Copy the runtime.properties file into the same directory where you added the jars. The location of the logs directory will be in the same directory as the runtime.properties file.

  7. In the ejbModule\META-INF folder of the EJB project, edit the MANIFEST.MF file and add all the HATS runtime jars to the dependency list.

  8. Add these calls to your code to initiate the HATS runtime: 
    // obj is the EJB object reference, 
// e.g., com.ibm.hats.util.Ras.initializeRas(this);
 com.ibm.hats.util.Ras.initializeRas(obj);  
 com.ibm.hats.util.LicenseManager.getInstance();         
 // appName is a String representing the EJB project 
 // and obj is the EJB object reference
 // e.g. com.ibm.hats.runtime.Runtime.initRuntime(My_EJB, this); 
 com.ibm.hats.runtime.connmgr.Runtime.initRuntime(appName, obj);

To use an Integration Object from a custom EJB:

  1. Create an instance of your Integration Object by calling its constructor.

  2. Invoke the setter methods to invoke methods to set properties of input variables. The naming convention for setter methods is as follows: 
    void setXyz(String)
    where xyz is the name of your input variable.

  3. Set the the pool name to the name of the connection pool that the Integration Object will use. Note that the connection name must be qualified with the name of the EJB project. For example: 
    void setHPubStartPoolName("My_EJB/main");
    Where My_EJB is the name of the EJB project, and main is the name of the Integration Object's connection pool.

  4. Invoke the Integration Object to perform its task (running a macro, for example), using the method 
    void processRequest() throws BeanException

    The processRequest() method will throw an exception (of type com.ibm.HostPublisher.IntegrationObject.BeanException) if the Integration Object has an error.

    You can reset the input variables and invoke the processRequest() method multiple times. The error indications and result values will be reset with each invocation.

  5. Check for errors by invoking 
    int getHPubErrorOccurred()
    If your result is nonzero, an error has occurred. You will have an error exception. To get the specific exception for the error, invoke 
    Exception getHPubErrorException()
    You can retrieve the error message by invoking getMessage() on the Exception object. The messages are documented in HATS Messages. Note that the first seven characters are set to HATxxxx or HPSxxxx, where xxxx is the message number.

  6. Request the results from your Integration Object.

    • Retrieve the values; of output variables by invoking one of the following methods:

      • Simple text 
        String getAbc()
        where abc is the name of your output variable.

      • Tables

        • To get an entire column of results 
          String[] getAbc()
          where abc is the name of your output variable.

        • To get a single value from a column of results 
          String getAbc(int) throws ArrayIndexOutOfBoundsException
          where abc is the name of your output variable, and int is the index of the value you want. As you iterate through the array, the method will throw an ArrayIndexOutOfBoundsException exception when you have reached the end of the array.

    • Regardless of the application you used to create your Integration Object, you can retrieve the output data in XML format by invoking the following method: 
      String getHPubXMLProperties()
      which returns the IntegrationObject's properties and values as an XML formatted string.

    The input variables for all Integration Objects have getter methods corresponding to each setter method so that you can retrieve those values if necessary. The signature for these methods is 

    void getXyz(String)

    where xyz is the name of your input variable.

    If you are unsure about any input or output variable names that are generated from data that you entered, look at the properties defined in your Integration Object's BeanInfo java file. The Integration Object's BeanInfo .java file is in the source folder of your project in the IntegrationObject package. The BeanInfo file is visible only in the Navigator view.

 

Home