Programming with Integration Objects

This chapter introduces Integration Objects, which are Javabeans 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. You can also import an Integration Object that you created using IBM WebSphere Host Publisher and use it in the same ways that you can use an Integration Object created in HATS Studio. When you have created or imported an Integration Object, you can use it in many ways. HATS User's and Administrator's Guide describes how to create Web pages based on an Integration Object. This Programmer's Guide describes these advanced uses of Integration Objects:

• You can invoke an Integration Object from business logic. This process is described in Adding business logic.
• You can invoke an Integration Object from another WebSphere application. This process is described in Use Integration Objects in a WebSphere J2EE Application.
• You can create Web services based on one or several Integration Objects. This process is described in Create Web Services.
• You can create EJB Access Beans based on one or several Integration Objects.This process is described in Create and Using a HATS EJB application.
• You can modify the Java code contained in the Integration Object. This is described in Integration Objects - advanced topics.

 

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, you can run chained Integration Objects without additional programming to chain Integration Objects.

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, you have to do additional programming; 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 created with previous versions of Host Publisher, 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.

This method is deprecated and cannot be used for Integration Objects 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 specifying the property names and values for this Integration Object

java.lang.String getHPubXMLProperties(HPubConvertToTableFormat.xsl)

Returns an XML formatted string specifying 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 non-zero 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 non-zero. This property is not contained in the io_name_Output_Properties class generated by HATS Web services support because parameters of type java.lang.Exception cannot be serialized over SOAP.

java.lang.String getHPubErrorMessage()

Returns a string containing the HATS code and message of the error that occurred; valid only if HPubErrorOccurred is non-zero

 

Host Access Integration Object methods

These methods can be used in Host Integration Objects that you created with Host Publisher and imported into HATS. They cannot be used with Database Access Integration Objects that you created with Host Publisher. They can be used with Integration Objects created in HATS Studio.

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 in Host Access. 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 in Host Access. 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 executed when the macro was stopped.

java.lang.String getHPubMacroMessage()

Returns the value of the message tag of the last screen 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 created in HATS Studio. Refer to the WebSphere Studio documentation for information about accessing databases.

int getHPubNumberOfRowsChanged()

Returns the number of rows changed by this database request

java.lang.String getHPubWarningOccurred()

Returns a non-zero value indicating that a warning has occurred.

java.sql.SQLWarning getHPubSQLWarningException()

Returns a SQLWarning object of the warning that occurred; valid only if HPubWarningOccurred is non-zero

java.sql.SQLException getHPubSQLErrorException()

Returns a SQL Exception object of the error that occurred; valid only if HPubErrorOccurred is non-zero and HPubErrorMessage indicates an SQL error

 

Integration Object chaining

Use chaining to break up a complex application into multiple tasks, 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 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.

You must retrieve and set properties that enable chaining 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. You must also retrieve and set properties that enable chaining for Web Services.

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 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 sample data:

Table 2. Sample XML data

Name	Phone Number
Mary Smith	867-5309
John Doe	123-4567

sults in the following XML data:


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

 
Home