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());
- 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:
where Xyz is the name of your input variable.void setXyz(String)
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 thepage
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
where Abc is the name of your output variable.String getAbc()
- Tables
- To get an entire column of results, invoke
where Abc is the name of your output variable.String[] getAbc()
- To get a single value from a column of results, invoke
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.String getAbc(int) throws ArrayIndexOutOfBoundsException
- To get an entire column of results, invoke
- Simple text
- 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:
which returns the IntegrationObject's properties and values as an XML-formatted string.String getHPubXMLProperties()
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
where Xyz is the name of your input variable.void getXyz(String)
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.
- Retrieve the values of output variables by invoking one of the
following methods: