Using 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 ZIETrans project to another Web project and configure it to run your Integration Objects. This set of steps supports exporting and using one or more individual Integration Objects. If you want to use a chain of Integration Objects, you must copy all the files as described here and ensure that the Integration Objects run in the correct order.

ZIETrans maintenance is not applied to Integration Objects that are 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 ZIETrans project and then re-export them after performing the following steps:

Create a Web project, if it does not already exist. This is the target project to which you are exporting the Integration Objects. Copy the Integration Object and BeanInfo source files into the Source directory of the Web project. Be sure to keep the IntegrationObject package.
Copy the profiles directory located at Web Content/WEB-INF/profiles 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 that are used by the Integration Object. Either way, you need to have these files:
```
WEB-INF\profiles\application.hap
WEB-INF\profiles\connections\ioconn.hco
WEB-INF\profiles\macros\iomacro.hma
```
Edit the application.hap file to remove unnecessary information. Right click the file, select Open with.. and select the text editor. When you save your changes in the text editor, you might see a message saying that you are saving a resource in a non-workbench encoding. This is because the file is UTF-8 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 ZIETrans 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>
```
Add all the jar files in the ZIETrans EAR file into the class path of the Web project, by copying them to the WEB-INF/lib directory of the Web project.
Note: You can also copy all the jar files in the ZIETrans EAR file to your own EAR file. However, before doing this, you must update the project's Java™ Buildpath explicitly to point to the files and update the web project MANIFEST.MF to point to include those files on the CLASSPATH.
Copy the runtime.properties file into the same directory where you added the jar files. The location of the logs directory will be in the same directory as the runtime.properties file.
Note: If you want to test your project in the local test environments, also copy the runtime-debug.properties file.

Add three function calls to initiate the ZIETrans runtime in your servlet or JSP.

// Initialize and activate the ZIETrans 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 can use the Integration Object as a regular Java bean in your Web project.

To write a servlet that invokes an Integration Object:

Create an instance of your Integration Object by calling its constructor.
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.
You can 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 specifying the name of the connection pool you want to use:
```
void setHPubStartPoolName(String)
```
Invoke the Integration Object to perform its task (running a macro, for example):
```
void doHPTransaction(HttpServletRequest, HttpServletResponse)
```
Check for errors. The doHPTransaction(HttpServletRequest, HttpServletResponse) method throws 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 catches the exception and redirects the browser to the error page that is specified on the errorPage="errorPageName" attribute of the page directive. Refer to the ZIETrans 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
    }
```
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 throws an ArrayIndexOutOfBoundsException exception when you have reached the end of the array.
- Regardless of the application that 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.
To verify input or output variable names that are generated from data that you entered, look at the properties that are 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 ZIETrans Toolkit, the BeanInfo file is visible only in the Navigator view.