Programming with Integration Objects

This chapter introduces Integration Objects, which are Java beans that encapsulate interactions with a host application. If you have used IBM WebSphere Host Publisher, you are already familiar with most aspects of Integration Objects, but you will need to learn about how HATS enables you to work with Integration Objects. You do not need to be familiar with Host Publisher to use Integration Objects in HATS.

HATS User's and Administrator's Guide explains how to create an Integration Object 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 HATS and used in the same ways as Integration Objects that were created in HATS Studio. This document describes these advanced uses of Integration Objects:

• Invoke an Integration Object from business logic. This process is described in Adding business logic.

• Invoke an Integration Object from another WebSphere application. This process is described in Using Integration Objects in a WebSphere J2EE Application.

• Create Web services based on one or several Integration Objects. This process is described in Creating Web services.

• Create EJB Access Beans based on one or several Integration Objects.This process is described in Creating and Using a HATS EJB application.

• Modify the Java code contained in the Integration Object. This is described in Integration Objects - advanced topics.

Note:

Using HATS Integration Objects in a non-HATS Web module, such as a portlet, can cause Object not defined errors (HPS5031) if the display name in the web.xml file doesn't match the context defined in application.xml file. To avoid the errors, change the display-name tag in the web.xml file (in the .war file) to match the context value from the application.xml (in the EAR file).

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 on 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

HATS 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 HATS Integration Object or EJB Access Bean from a servlet or JSP. If you use this method, HATS manages Integration Object chaining. However, 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 HATS 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 HATS 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.

Note:

This method is deprecated and cannot be used for Integration Objects that were created with HATS or with Host Publisher after Version 3.5.

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 HATS application name. For example, the pool name should be my_hats_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 stylesheet processing to the returned string. See Applying XML stylesheet 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 HATS entry servlet and a default transformation can be applied. The method should be used in combination with the predefined AdvancedIOErrorPage.jsp. Note that 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 HATS 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 HATS 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 HATS 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 HATS, and with Integration Objects created in HATS Studio. They cannot be used with Database Access Integration Objects created with Host Publisher.

java.lang.String getHPubLinkKey()

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)

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()

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()

Returns the name of the last Host On-Demand macro screen that was executed when the macro was stopped.

java.lang.String getHPubMacroMessage()

Returns the value of the message tag of the last screen that was executed in the current Host On-Demand macro screen.

Database Access Integration Object methods

These methods can be used in Database Access Integration Objects that you created with Host Publisher and imported into HATS. They cannot be used with Host Access Integration Objects that you created with Host Publisher, and they cannot be used with Integration Objects that were created in HATS Studio. Refer to the Rational Studio 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.

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 HATS 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 HATS Advanced Macro Guide for more information on macro chaining.

Note:

Creating JSF pages from chained Integration Objects is not supported by the HATS Studio wizard.

Integration Object chaining is handled by HATS for the following:

• HATS applications using Integration Objects or the corresponding EJB Access Beans

• Custom JSPs or servlets that use Integration Objects or the corresponding EJB Access Beans in a Web container

In these cases, the doHPTransaction execution method is used.

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

• EJB Access Beans running outside of a Web container

• Custom EJBs that use Integration Objects.

In these cases, the processRequest execution method is used.

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

HATS 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.

Applying XML stylesheet processing to Integration Object output

HATS provides an XML stylesheet, HPubConvertToTableFormat.xsl, that can be applied to the getHPubXMLProperties() function call for tabular data. Applying the stylesheet produces an XML format including the table name and column names, and reorders data in record format. To apply the HPubConvertToTableFormat.xsl stylesheet, 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 stylesheet 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 2. 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 stylesheet 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 stylesheet applied

The sample data shown in Table 2 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>