Using 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 ZIETrans 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, you must copy all the files as described here and ensure that the Integration Objects run in the correct order.

Note:

If using chained Integration Obejcts, use a stateful EJB project. Also, you must manage the ZIETrans session key (hPubLinkKey) in your EJB project. For more information see Integration Object chaining.
If not using chained Integration Object, use a stateless EJB project.
When running in a WebSphere® Application Server cluster, session affinity is handled by the EJB container.

ZIETrans maintenance is not applied to Integration Objects that are 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 ZIETrans project and then re-export them after performing the following steps. In addition, if you export ZIETrans runtime .jar files from a ZIETrans EAR into your project, you must re-export them if you apply ZIETrans maintenance.

Create a custom EJB project (File > New > Project > EJB Project). In this example, the project is referred to as My_EJB. Copy the application.hap file to the ejbModule folder of the EJB project.
In the ejbModule folder of the EJB project, create a folder named connections (File > New > Other , expand Simple and select Folder). Copy to this folder the .hco file that defines the connection that is used by the Integration Object.
In the ejbModule folder of the EJB project, create a folder named macros. Copy to this folder the .hma file that defines the macro that is used by the Integration Object, as well as any connect or disconnect macros that are required by your connections.
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 you should have these files:
```
ejbModule\application.hap
ejbModule\connections\ioconn.hco
ejbModule\macros\*.hma
ejbModule\IntegrationObject\*.java
```
Add all the jar files that are contained in the ZIETrans EAR file into the class path of the EJB project, by moving them either to your own EAR file, or into the ejbModule directory of the EJB project.
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.
In the ejbModule\META-INF folder of the EJB project, edit the MANIFEST.MF file and add all the ZIETrans runtime jar files to the dependency list.

Add these calls to your code to initiate the ZIETrans 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:

Create an instance of your Integration Object by calling its constructor.
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.
Set 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.
Invoke the Integration Object to perform its task (running a macro, for example), using the method:
```
void processRequest() throws BeanException
```
The processRequest() method throws 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 are reset with each invocation.
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 ZIETrans Messages. Note that the first seven characters are set to HATxxxx or HPSxxxx, where xxxx is the message number.
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.
If you are unsure about any 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 source file. The Integration Object's BeanInfo .java source file is in the Source folder of your project in the IntegrationObject package. The BeanInfo file is visible only in the Navigator view.