Programming with Integration Objects

Integration Objects are Java™ beans that encapsulate interactions with a host application.

ZIETrans User's and Administrator's Guide explains how to create an &IO; from a macro and how to create Web pages based on an Integration Object. Integration Objects created using IBM® WebSphere® Host Publisher can be imported into ZIETrans and used in the same ways as Integration Objects that were created in &studio;. This document describes these advanced uses of &IO;s:

A common class for accessing Integration Object information

The properties of an Integration Object can be accessed from WebSphere applications. The calling program must know the name of the Integration Object and the name of the variable. Sometimes, it is advantageous for the calling program to be able to access properties that all Integration Objects share without knowing the name of the Integration Object. The Java class, com.ibm.HostPublisher.IntegrationObject.HPubCommon, is extended by all Integration Objects. The class com.ibm.HostPublisher.IntegrationObject.HPubHostAccess extends HPubCommon and is common to all Host Access Integration Objects. The class com.ibm.HostPublisher.IntegrationObject.HPubDBAccess extends HPubCommon and is common to all Database Integration Objects. You can extract information from these classes without knowing the name of the Integration Object. Introspect these classes to find the names of the current properties that can be extracted using the Integration Object methods. For information about these methods, see Integration Object methods.

Java class hierarchy of Integration Objects

Following is the Java class hierarchy of the default and customizable Integration Objects:

HPubCommon + -- HPubHostAccess + -- HPubHODCommon -- HPubTemplateHODBean.Default
           |                   |
           |                   + -- HPubTemplateHODBean.Customize
           |
           + -- HPubDBAccess

Integration Object methods

&sprod; Integration Objects contain Java methods that you can use when programming with Integration Objects. Some of the methods are common to all Integration Objects. Some apply only to Host Access Integration Objects and some apply only to Database Access Integration Objects. This section lists the methods and a short description of the function of each method.

Common methods

These methods are common to all Integration Objects.

void doHPTransaction(HttpServletRequest req, HttpServletResponse resp) throws BeanException
This execution method runs a &sprod; Integration Object or EJB Access Bean from a servlet or JSP. If you use this method, &sprod; manages Integration Object chaining. However, you must ensure that the Integration Objects in your Web project are chained together in the correct order.
void processRequest() throws BeanException
This execution method runs an Integration Object or EJB Access Bean in environments where there is no HttpServletRequest or HttpServletResponse (environments other than a Web module). To run chained Integration Objects using this method, additional programming is required; refer to Integration Object chaining.
java.lang.String getHPubBeanName()
Returns the name of the current Integration Object or EJB Access Bean.
java.lang.String getHPubBeanType()
Returns a string representing the type of &sprod Integration Object or EJB Access Bean. The returned string can be one of the following:
HOD
The bean was created using Host Access.
DB
This bean was created using Database Access.
void setHPubErrorPage(java.lang.String value)
For Integration Objects that were created with Host Publisher Version 2.2.1 or Version 3.5, this method sets the name of the error page to be used. Use this method only if you are running the &sprod; Integration Object or EJB Access Bean from a servlet or JSP. Specify the name of your error page relative to the location of your servlet or JSP.
java.lang.String getHPubStartPoolName()
Returns the name of the connection pool from which the Integration Object acquired the connection.
void setHPubStartPoolName(java.lang.String value)
Sets the name of the connection pool from which the Integration Object will acquire the connection. If the processRequest() business method of the Integration Object is being used (for example, when the Integration Object is deployed in an EJB container or as a Web service), the pool name must be qualified with the ZIETrans application name. For example, the pool name should be my_ZIETrans_project/main.
java.lang.String getHPubXMLProperties()
Returns an XML formatted string that specifies the property names and values for this Integration Object.
java.lang.String getHPubXMLProperties(HPubConvertToTableFormat.xsl)
Returns an XML formatted string that specifies the property names and values for this Integration Object, and applies XML style sheet processing to the returned string. See Applying XML style sheet processing to Integration Object output for more information.
void setHPubSaveConnOnError(java.lang.Boolean flag)
Sets an indicator in the Integration Object that specifies that the connection should not be destroyed if an error is detected while executing the Integration Object. Instead, the connection should be saved so that it can be passed to the ZIETrans entry servlet and a default transformation can be applied. The method should be used in combination with the predefined AdvancedIOErrorPage.jsp. The connection can be transformed only if it was obtained from the default connection pool. This method cannot be used with EJB Access Beans or ZIETrans Web services support.
int getHPubErrorOccurred()
Returns a nonzero value when an error has occurred.
java.lang.Exception getHPubErrorException()
Returns an exception object that describes the error that occurred; valid only if HPubErrorOccurred is nonzero. This property is not contained in the io_name_Output_Properties class that is generated by ZIETrans Web services support because parameters of type java.lang.Exception cannot be serialized over Simple Object Access Protocol (SOAP.)
java.lang.String getHPubErrorMessage()
Returns a string containing the &sprod; code and message of the error that occurred; valid only if HPubErrorOccurred is nonzero.

Host Access Integration Object methods

These methods can be used in Host Integration Objects created with Host Publisher and imported into ZIETrans, and with Integration Objects created in &studio. They cannot be used with Database Access Integration Objects created with Host Publisher.

java.lang.String getHPubLinkKey()
This method returns the name of the key that represents the connection for the Integration Object chain. This value should be obtained from the first Integration Object in a chain after the Integration Object has run in a non-Web container.
void setHPubLinkKey(java.lang.String value)
This method sets the name of the key that represents the connection for the Integration Object chain. This value should be set for any chained Integration Objects, other than the first Integration Object in the chain, before they run in a non-Web container.
java.lang.String getHPubStartChainName()
This method returns the name of the start state label as defined when a middle or last in chain Integration Object is created. This value is Null for the first Integration Object in a chain or an Integration Object that is not chained.
java.lang.String getHPubEndChainName()
Returns the stop state label as defined when a first in chain Integration Object is created. This value is Null for the last Integration Object in a chain or an Integration Object that is not chained.
java.lang.String getHPubScreenState()
This method returns the name of the last &HOD macro screen that was executed when the macro was stopped.
java.lang.String getHPubMacroMessage()
This method returns the value of the message tag of the last screen that was executed in the current &HOD; macro screen.
public java.lang.String getHPubConnectionOverrides()
This method returns the connection overrides used by IO in the format "key1=value1, key2=value2" or an empty string.

See Specifying Connection Overrides for further information.

public void setHPUBConnectionOverrides (String overrides)
This method specifies the connection overrides to apply when establishing the host connection for the Integration Object. The connection overrides have to be set before calling the processRequest() or doHPTransaction() methods of the Integration Object. The connection overrides must be in the format "key1=value1, key2=value2". This format is more convenient when building Web services.

This method should be used with client programs based on ZIETrans EJB access beans or Web Services clients generated to be used with ZIETrans web services.

If connection overrides have been specified, then when the Integration Object's doHPTransaction() or processRequest() method is called a new connection pool for the Integration Object is created. The new pool is based on the Integration Object's original connection pool and the supplied connection overrides. The Integration Object is automatically switched to use the new connection pool. new pool name can be retrieved using the Integration Object instance method getHPubStartPoolName().

See Specifying Connection Overrides for further information.

public void setHPubConnectionOverrides(Properties overrides)
This method sets the connection overrides to apply when establishing the host connection for the Integration Object. The connection overrides have to be set before calling the processRequest() or doHPTransaction() business methods of the Integration Object establishing the host connection.

When the Integration Object doHPTransaction() or processRequest() methods are called, if there are connection overrides associated with the Integration Object, a new connection pool for the Integration Object is created based on the Integration Object's connection pool and the connection overrides. The new pool name can be retrieved using the Integration Object instance method getHPubStartPoolName().

See Specifying Connection Overrides for further information.

Database Access Integration Object methods

These methods can be used in Database Access Integration Objects that you created with Host Publisher and imported into ZIETrans. They cannot be used with Host Access Integration Objects created with Host Publisher, and they cannot be used with Integration Objects that were created in &studio. Refer to the Rational® SDP documentation for information about accessing databases.

java.lang.String getHPubWarningOccurred()
Returns a nonzero value that indicates that a warning has occurred.
java.sql.SQLWarning getHPubSQLWarningException()
Returns a SQLWarning object of the warning that occurred; valid only if HPubWarningOccurred is nonzero.
java.sql.SQLException getHPubSQLErrorException()
Returns a SQL Exception object of the error that occurred; valid only if HPubErrorOccurred is nonzero and HPubErrorMessage indicates an SQL error.

Specifying Connection Overrides

Connection overrides can be set dynamically or by the user. Specifying connection overrides allows the user to build a generic application and customize some settings based on the user running the application. However, for example, the LUName being used for a 3270E connection or the workstationID for a 5250 connection can be set dynamically at runtime.

To specify connection overrides on Integration Objects, the user needs to modify the code accessing the Integration Object to call the Integration Object instance methods setHPubConnectionOverrides(Properties overrides) or setHPubConnectionOverrides(String overrides) before calling the doHPTransaction() or processRequest() methods. The method sets the connection overrides for the Integration Object. When the Integration Object doHPTransaction() or processRequest() methods are called, if there are connection overrides associated with the Integration Object, a new pool for the Integration Object is created based on the Integration Object's connection pool and connection overrides in input.

The following is an example of JSP code using the IO.setHPubConnectionOverrides() method:

<% / Set the connection overrides    
java.util.Properties overrides = new java.util.Properties();   
overrides.setProperty("LUName", "LU00001");   
// Apply overrides to the IO    
SignOn.setHPubConnectionOverrides(overrides);   
SignOn.doHPTransaction(request,response);       
// Get new IO pool name to be used in following logic   
String newPoolName = SignOn.getHPubStartPoolName();      

%>  

To specify connection overrides on existing Integration Objects, without recompiling the Integration Object, the new com.ibm.HostPublisher.IntegrationObject.HPubPoolFactory class can be used. Its static create() method can be used before calling the doHPTransaction() or processRequest() methods. The method generates a new pool object by cloning the pool object in input, and applying the connection overrides to the Host On-Demand properties associated with it. The new pool name is returned and must be set in the Integration Object using the setHPubStartPoolName() method. The create() method returns null, if the pool name in input is invalid.

If the third parameter of the create method is null, then the pool name must be qualified with the ZIETrans application name. For example, the pool name should be my_ZIETrans_project/main.

The two static methods that you can use are:

static String create(String poolName,
                     Properties overrides,
                     javax.servlet.http.HttpServletRequest httpServletRequest)

static String create(String poolName,
                     String overrides,
                     javax.servlet.http.HttpServletRequest httpServletRequest)

The methods create a new pool definition based on the named pool definition and the supplied connection overrides.

The new pool name must be set on the Integration Object using the instance method setHPubStartPoolName() before calling the doHPTransaction() or processRequest() methods of the Integration Object establishing the host connection.

The create() methods returns null if a connection definition for the supplied pool name does not exist in the project.

If the third parameter of the create method is null, then the pool name must be qualified with the ZIETrans application name. For example, the pool name should be "my_ZIETrans_project/main".

The connection overrides must be in the format "key1=value1, key2=value2" if the second method signature is used. The first method uses a standard Java Properties object to specify the overrides.

The following is an example of JSP code using the com.ibm.HostPublisher.IntegrationObject.HPubPoolFactory,create() method:

<% / Set the connection overrides    
java.util.Properties overrides = new java.util.Properties();   
overrides.setProperty("LUName", "LU00001");   
// Create a new Pool based on a the default pool and the connection overrides    
String poolName = SignOn.getHPubStartPoolName();   
String newPoolName = 
com.ibm.HostPublisher.IntegrationObject.HPubPoolFactory.create    
                               (poolName, overrides, request);   
// If a valid poolName is returned, make the IO use the new pool   
if (newPoolName != null) {      
  SignOn.setHPubStartPoolName(newPoolName);      
  SignOn.doHPTransaction(request,response);   
}  
else {     
  // Error condition  
}  

%>  

For chained Integration Objects to work correctly:

With either example, the Integration Object uses a new Pool object created by cloning the original Integration Object's pool and applying the connection overrides. All the settings that apply to the original Integration Object's pool also apply to the new pool, including pooling. Connection overrides can be different for each user accessing an Integration Object. ZIETrans runtime creates a pool object for each user. These pools, created dynamically when connection overrides are specified, are destroyed when the last active connection is terminated, providing that pooling is not enabled. Connection override parameters specified on the Connection Parameter Overrides page on the Other tab in the project settings editor do not apply to Integration Objects.

Pools dynamically created when connection overrides are specified are automatically destroyed when the last active connection is terminated, providing that pooling is not enabled.

Integration Object chaining

Integration Object chaining can break up a complex application into multiple tasks, with each task represented by an Integration Object. Chaining enables you to run several Integration Objects in sequence, with each Integration Object depending on the one before it for its input. Refer to ZIETrans User's and Administrator's Guide for an introduction to Integration Object chaining. 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 PlayMacro action, terminates the current macro (the one in which the PlayMacro action occurs) and begins to process the specified macro screen of the target macro. There is no return to the calling macro. See ZIETrans Advanced Macro Guide for more information on macro chaining.

Integration Object chaining is handled by &sprod; fr the following:

In these cases, the doHPTransaction execution method is used.

Properties that enable chaining must be retrieved and set for the following:

In these cases, the processRequest execution method is used.

See Integration Object methods for a description of the doHPTransaction and processRequest methods.

ZIETrans provides methods that enable you to extract the key that represents the connection for the Integration Object chain from the first Integration Object in a chain and to set the property for subsequent Integration Objects in the chain. Properties that enable chaining for Web Services must also be retrieved and set.

To build an Integration Object chain using the processRequest method, do the following:

  1. Create an instance of the first Integration Object in the chain by calling its constructor.
  2. Invoke the methods for the Integration Object instance. You might want to invoke methods to set properties of input variables. The naming convention for setter methods is as follows:
    IOChain1.setXyz(String)
    where Xyz is the name of your input variable.
  3. Invoke the Integration Object to perform its task (running a macro, for example), using the method:
    IOChain1.processRequest()
  4. Check for errors by invoking:
    IOChain1.getHPubErrorOccurred()
  5. Extract and save the key that represents the connection for the Integration Object chain:
    String myLinkkey = IOChain1.getHPubLinkKey();
  6. Create an instance of the next Integration Object in the chain by calling its constructor.
  7. Set the key for this chained connection:
    IOChain2.setHPubLinkKey(myLinkkey);
  8. Invoke the methods for this Integration Object instance. You might want to invoke methods to set properties of input variables. The naming convention for setter methods is as follows:
    IOChain2.setXyz(String)
    where Xyz is the name of your input variable.
  9. Invoke this Integration Object to perform its task, using the method:
    IOChain2.processRequest()
  10. Check for errors by invoking:
    IOChain2.getHPubErrorOccurred()

Repeat steps 6 through 10 for any and all subsequent Integration Objects in the chain.

ZIETrans‐chained Web services

&prodname‐chained Web services require special consideration when used with Integration Objects. If you use chained Integration Objects within a &prodname Web service, you create a stateful Web service. &prodnae; runtime does not store data between invocations of chained Integration Objects in the same Web service. However, &prodnae; runtime does require that the next in chain Web service invocation be routed back to the same instance of the ZIETrans runtime, so the next&hyphe;in&hyphe;chain Integration Object uses the same Telnet connection.

If you are deploying the stateful ZIETrans Web service to a cluster, you can ensure that this occurs in one of the following ways:

  1. Create ZIETrans Web services from EJB Access Beans. The ZIETrans EJB is a stateful session EJB, so the EJB client always interacts with the same ZIETrans EJB instance.
  2. Configure the scope of the Web service to be session (either in the development environment or after deployment), and use the SESSION_MAINTAIN_PROPERTY in the Web service client runtime to maintain the session across invocations, ensuring HTTP session affinity.

Applying XML style sheet processing to Integration Object output

&sprod provides an XML style sheet, HPubConvertToTableFormat.xsl, that can be applied to the getHPubXMLProperties() function call for tabular data. Applying the style sheet produces an XML format including the table name and column names, and reorders data in record format. To apply the HPubConvertToTableFormat.xsl style sheet, you must code the getHPubXMLProperties() function call as getHPubXMLProperties("HPubConvertToTableFormat.xsl").

For information on the methods that you can use in WebSphere applications, see Integration Object methods.

DTD of XML data that is returned by getHPubXMLProperties() method

When an XML style sheet is not applied to Integration Object output, the XML data is returned with the following document type definition (DTD):

<?xml version=\"1.0\" standalone=\"yes\"?>
<!DOCTYPE com.ibm.HostPublisher.IntegrationObject.properties [
<!ELEMENT com.ibm.HostPublisher.IntegrationObject.properties 
             (inputProperties, outputProperties)>
<!ATTLIST com.ibm.HostPublisher.IntegrationObject.properties name CDATA "">
<!ELEMENT inputProperties (inputProperty*)>
<!ELEMENT inputProperty (value)>
<!ATTLIST inputProperty name CDATA "">
<!ELEMENT outputProperties (outputProperty*)>
<!ELEMENT outputProperty (value*)>
<!ATTLIST outputProperty name CDATA "" type (singlevalue|multivalue) 'multivalue'>
<!ELEMENT value (#PCDATA)>
]>

XML data using the getHPubXMLProperties() method

The following example shows sample data and the resulting XML data.

Table 3. Sample XML data
Name Phone Number
Mary Smith 765-4321
John Doe 123-4567
<com.ibm.HostPublisher.IntegrationObject.properties name=IntegrationObject.test1>
<inputProperties>
<inputProperty name=nameValue>
<value>%</value>
<inputProperty>
</inputProperties?
<outputProperties>
<outputProperty name=tablename type=multivalue>
<value>Mary Smith</value>
<value>John Doe</value>
</outputProperty>
<outputProperty name=table1phonenumber type=multivalue>
<value>867-5309</value>
<value>123-4567</value>
</outputProperty>
<outputProperty name=databaseStatus type=singlevalue>
<value>Ok</value>
</outputProperty>
<outputProperty name=hPubErrorOccurred" type=singlevalue>
<value>0</value>
</outputProperty>
<outputProperty name=hPubErrorException" type=singlevalue>
<value></value>
</outputProperty>
<outputProperty name=hPubErrorMessage" type=singlevalue>
<value></value>
</outputProperty>
</outputProperties>
</com.ibm.HostPublisher.IntegrationObject.properties>

All of the data is within multiple <value> tags with the <outputProperty> tags in columnar order.

DTD of XML data that is returned by getHPubXMLProperties (HPubConvertToTableFormat.xsl) method

When the XML HPubConvertToTableFormat style sheet is applied to Integration Object output, the XML data is returned with the following document type definition (DTD):

<?xml version=\"1.0\" standalone=\"yes\"?>
<!DOCTYPE com.ibm.HostPublisher.IntegrationObject.properties [
<!ELEMENT com.ibm.HostPublisher.IntegrationObject.properties 
             (inputProperties, outputProperties)>
<!ATTLIST com.ibm.HostPublisher.IntegrationObject.properties name CDATA "">
<!ELEMENT inputProperties (inputProperty*)>
<!ATTLIST inputProperty name CDATA "">
<!ELEMENT outputProperties (outputProperty*,Table*)>
<!ATTLIST outputProperty name CDATA "">
<!ELEMENT Table (DataRecord*)>
<!ATTLIST Table name CDATA "">
<!ELEMENT DataRecord (outputProperty*)>
]> 

XML data with HPubConvertToTableFormat style sheet applied

The sample data shown in Table 3 results in the following XML data:

<com.ibm.HostPublisher.IntegrationObject.properties name=IntegrationObject.test1>
<!-- Input Properties -->
<inputProperties>
<inputProperty name=inputName>
%
<inputProperty>
</inputProperties?
<outputProperties>

<!-- Table (multivalued) output property -->
<Table name=table1>
<DataRecord>
<outputProperty name=Name>Mary Smith</outputProperty>
<outputProperty name=phoneNumber>867-5309</outputProperty>
</DataRecord>
<DataRecord>
<outputProperty name=Name>John Doe</outputProperty>
<outputProperty name=phoneNumber>123-4567</outputProperty>
</DataRecord>
</Table>

<!-- Single Valued output Property -->
<outputProperty name=databaseStatus>
Ok
</outputProperty>

<!-- Standard Error  output Properties -->
<outputProperty name=hPubErrorOccurred">0</outputProperty>
<outputProperty name=hPubErrorException"></outputProperty>
<outputProperty name=hPubErrorMessage"></outputProperty>
</outputProperties>

</com.ibm.HostPublisher.IntegrationObject.properties>