Copyright © Cloud Software Group, Inc. All Rights Reserved

Object Integration Gateway EJB Components

ects2EJBbase Base Class

A ects2EJBbase base class is provided for Object Integration Gateway EJB session bean implementations. You extend this class to create your EJB session bean components.

This class contains methods for running Gateway objects. The source code for a sample class, ects2EJBSampleBean, is provided later in this chapter to illustrate how to extend the base class for your own EJB component class.

Methods

 

Method	Description
addSessionParm(String persistKey, String value) throws java.rmi.RemoteException	Adds a persistent data item to the session data collection.
addSessionParms(java.util.HashMap persistData) throws java.rmi.RemoteException	Adds a set of persistent data items to the session data collection.
deletePersistData() throws java.rmi.RemoteException	Deletes all persistent data items from the session data collection.
deletePersistData(String persistKey) throws java.rmi.RemoteException	Deletes a persistent data item from the session data collection.
ejbActivate() throws javax.ejb.EJBException, java.rmi.RemoteException	Implementation of the javax.ejb.SessionBean interface method.
ejbCreate() throws javax.ejb.EJBException, java.rmi.RemoteException	Implementation of the javax.ejb.SessionBean interface method. Create without a session pool.
ejbPassivate() throws javax.ejb.EJBException, java.rmi.RemoteException	Implementation of the javax.ejb.SessionBean interface method.
ejbRemove() throws javax.ejb.EJBException, java.rmi.RemoteException	Implementation of the javax.ejb.SessionBean interface method.
String getDocument(String docname) throws java.rmi.RemoteException	Returns the XML document from the last run method call. The XML document must be of type ROWSET or MSSCHEMA.
String getEndMsg() throws java.rmi.RemoteException	Returns the end message set by the last Gateway operation.
java.util.HashMap getPersistData() throws java.rmi.RemoteException	Returns the session data collection.
String getResult() throws java.rmi.RemoteException	Returns the HTML contents of the results area.
String getSessionParm(String persistKey) throws java.rmi.RemoteException	Returns a persistent data item from the session data collection.
java.util.HashMap getSessionParms() throws java.rmi.RemoteException	Returns the session data collection.
WebRowSet getTable(String docName) throws java.rmi.RemoteException	Converts an XML document from the last run method call to a WebRowSet object, and returns the WebRowSet object. The XML document must be of type ROWSET or MSSCHEMA.
WebRowSet getTableFromDoc(String docName)	Returns a WebRowSet by parsing an XML document returned as a result of running a defined XML document.
openApplication() throws ects2EJBException	Obtains an unpooled session with the parameters specified in the deployment descriptor for this EJB.
openApplication(boolean pooled) throws ects2EJBException	Obtains a pooled or unpooled session with the parameters specified in the deployment descriptor for this EJB.
openApplication(java.util.HashMap parms, boolean pooled) throws ects2EJBException	Obtains a pooled or unpooled session with the parameters supplied in the parms argument. Parameters not supplied in the parms argument are provided by the deployment descriptor for this EJB.
removeSessionParm(String persistKey) throws java.rmi.RemoteException	Deletes a persistent data item from the session data collection.
removeSessionParms() throws java.rmi.RemoteException	Deletes all persistent data items from the session data collection.
runRule(String RuleName) throws java.rmi.RemoteException	Runs the named rule within the context of the Object Integration Gateway rules framework. The named rule can access data processed via setTable and setDocument. The named rule can also produce and return XML documents, and so on.
runTrans(String transname) throws java.rmi.RemoteException	Runs the named Gateway transaction.
runXMLDoc(String docname) throws java.rmi.RemoteException	Runs the named Gateway XML document.
setDocument(String docname, String document) throws java.rmi.RemoteException	Stages one or more XML documents to be sent to the Gateway on the next run method call.
setDocument(String docname, WebRowSet wrs) throws java.rmi.RemoteException	Stages one or more XML documents to be sent to the Gateway on the next run method call.
setPersistData(java.util.HashMap persistData) throws java.rmi.RemoteException	Adds a set of persistent data items to the session data collection.
setTable(WebRowSet wrs) throws java.sql.SQLException, java.rmi.RemoteException	Passes the contents of a WebRowSet object to a TIBCO Object Service Broker data table. The method converts the WebRowSet to an XML document so that when the next Gateway object is invoked, the XML document is sent along with any other parameters and loaded into a TIBCO Object Service Broker data table. Since no table name argument is provided, the data table from which the WebRowSet was created is updated.
setTable(WebRowSet wrs, String tablename) throws java.sql.SQLException, java.rmi.RemoteException	Passes the contents of a WebRowSet object to a TIBCO Object Service Broker data table. The method converts the WebRowSet to an XML document so that when the next Gateway object is invoked, the XML document is sent along with any other parameters and loaded into a TIBCO Object Service Broker data table. Since a table name argument is provided, the specified data table is updated.
setUserData(String userdata) throws java.rmi.RemoteException	Sets user data (name-value pairs) passed with run method calls. Multiple name-value pairs must be separated using commas. A value that contains a space character must be enclosed in single quotation marks.
setUserData(String name, String value) throws java.rmi.RemoteException	Sets user data (name-value pairs) passed with run method calls. Each call to this method adds a name-value pair to the userdata collection passed on the next interaction. There are no restrictions on the naming of user data; the same name can be used multiple times.
startTran(boolean update) throws java.rmi.RemoteException	Starts a bean-managed transaction that can span multiple interactions. The update parameter controls the mode of the TIBCO Object Service Broker transaction started.
stopTran(boolean commit) throws java.rmi.RemoteException	Stops a bean-managed transaction with either rollback or commit processing.

Home Interface

The home interface exposes methods for creating instances of the EJB component class (your extensions of the Object Integration Gateway base class). When a client makes a call to a create() method of the home interface, the return value is the remote interface of your EJB component class.

Methods

 

Method	Description
ejbRemoteInterface create() throws javax.ejb.CreateException, java.rmi.RemoteException	Causes the EJB server to instantiate an EJB session bean that does not participate in session pooling. Returns an instance of this EJB’s remote interface.

Remote Interface

The remote interface exposes to the client the methods of your EJB session bean component. These are the methods that actually do the work of your Object Integration Gateway application. The remote interface includes methods to run Gateway objects such as transactions.

Deployment Descriptor

The deployment descriptor is an XML document that contains information about the EJB components you want to deploy to your EJB container. It should be packaged at the root of your applicationname-ejb.jar file (where applicationname is the name of your EJB application).

In the deployment descriptor you specify the JNDI names of your EJB component, home interface, and remote interface classes. You can also specify Object Integration Gateway session initialization parameters, and any other values you want passed to your EJB component.

WebRowSet Class

You use WebRowSet objects to manipulate XML document data as recordsets. The WebRowSet class is an implementation of the javax.sql.RowSet interface. For information about the methods available in WebRowSet objects, refer to “Methods” on page 61.

Following are some general notes you should be aware of when using WebRowSet objects.

Column References

Because TIBCO Object Service Broker programmers are accustomed to referencing fields by name, the WebRowSet class is extended to let users get data by column name as well as by column number. If a column label is provided in the XML document definition in the TIBCO Object Service Broker UI (as specified in the Root Name field on the Properties tab), this value, and not the column name, is used for the column label property.

Supported Schemas

The WebRowSet class supports two XML schema types: MSSCHEMA and ROWSET. MSSCHEMA is the preferred schema type of Microsoft, whereas ROWSET is the preferred schema type of Sun Microsystems. MSSCHEMA is the schema type used by Microsoft’s ADO components to encode recordsets. The ROWSET schema is part of a prerelease of the JDBC 3.0 specification. Neither requires a document type definition for validation.

There are some interesting differences between the two schema types:

•	MSSCHEMA is an attribute-based schema.

•	ROWSET is a character-based schema.

•	ROWSET schemas tend to carry much more metadata than MSSCHEMA. You could find that you need this metadata.

For various reasons, one schema outperforms the other in certain circumstances. You should experiment to determine which schema type best suits your application needs.

Data Integrity

Because the WebRowSet object is a completely disconnected recordset, modifications to its data are done without a transactional context. No locks are held, and the data is not guaranteed to remain unchanged while the rowset travels between various servers. It is up to the application programmer to use these disconnected recordsets in such a manner that data integrity is maintained.

Data Sources

A recordset can be created using a wide variety of data sources. You can then use the recordset to populate a WebRowSet object, and send the WebRowSet to the Object Integration Gateway to update a table. Sending data to the Gateway from external data sources is not a supported feature but it should work correctly as long as a compatible table definition can be created. This technique has risks that you need to be aware of:

•	TIBCO Object Service Broker is not guaranteed to support all the data types available in other data sources. Incompatible fields can cause either the population of the WebRowSet to fail, or the consumption of the XML document to fail.

•	Most unsupported data types cause a java.sql.SQLException to be thrown from a WebRowSet object.

Constructors

 

Constructors	Description
WebRowSet() throws java.sql.SQLException	Default constructor. Instantiates the WebRowSet but does not initialize any data structures.

Methods

 

Methods	Description
String getSchemaType()	Returns the schema type that the WebRowSet is currently set to use.
readXml(java.io.Reader reader, int docType throws java.sql.SQLException	Reads an XML document from the reader and initializes the contents for the rowset accordingly. This docType provided to this method relieves the parser of the burden of dynamically detecting the document' schema.
readXml(java.io.Reader reader) throws java.sql.SQLException	Reads an XML document from the reader and initializes the contents for the ROWSET accordingly.
setSchemaType(String schematype) throws java.sql.SQLException	Set the schema type that the ROWSET is to use.
writeUpdateOnly(java.io.Writer writer) throws java.sql.SQLException	Writes the contents of the WebRowSet to generate an XML document consisting of only the changed, deleted or inserted rows.
writeXml(java.io.Writer writer) throws java.sql.SQLException	Writes the contents of the WebRowSet to generate an XML document.
writeXml(java.sql.ResultSet resultset, java.io.Writer writer) throws java.sql.SQLException	Uses the contents of the named WebRowSet to generate an XML document.

EJB Code Examples

This section presents code for a sample Object Integration Gateway EJB component class, its home and remote interfaces, and its deployment descriptor file.

ects2EJBSampleBean

The following is sample code for an EJB component class that extends the Gateway EJB base class.

/* A reference implementation of the OIG EJB sessionbean. */

package com.ObjectStar.ects;

import javax.ejb.*;

import java.util.*;

import java.io.*;

import javax.naming.*;

import sun.jdbc.rowset.WebRowSet;

import com.ObjectStar.ects.*;

public class ects2EJBSampleBean extends ects2EJBbase implements SessionBean {

// empty constructor

public ects2EJBSampleBean() {

   }

   

   // EJB Container required methods. These are not available

   // to the client program, but are used only by the container.

   

   public void ejbActivate()

throws javax.ejb.EJBException, java.rmi.RemoteException {

System.out.println("ects2EJBSampleBean.activate");

super.ejbActivate();

   }

   public void ejbPassivate()

throws javax.ejb.EJBException, java.rmi.RemoteException {

System.out.println("ects2EJBSampleBean.passivate");

super.ejbPassivate();

   }

   public void ejbRemove()

throws javax.ejb.EJBException, java.rmi.RemoteException {

System.out.println("ects2EJBSampleBean.remove");

super.ejbRemove();

   }

   

   // Create with no pool. Called when client

   // calls "create()" on the home interface

   public void ejbCreate()

throws javax.ejb.EJBException, java.rmi.RemoteException {

System.out.println("ects2EJBSessionBean.create()");

super.ejbCreate(null);

   }

   

   // Create with pool. Called when client calls "create(poolname)"

   // on the home interface

   public void ejbCreate(String poolname)

throws javax.ejb.EJBException, java.rmi.RemoteException {

System.out.println("ects2EJBSessionBean.create()");

super.ejbCreate(poolnm);

   }

}

ects2EJBSampleHome

The following is sample code for the home interface class. The create () methods of the home interface return an instance of the EJB component’s remote interface to the client.

/* A reference implementation of the OIG EJB sessionHome class. */

package com.ObjectStar.ects;

import java.rmi.RemoteException;

import javax.ejb.CreateException;

import javax.ejb.EJBHome;

public interface ects2EJBSampleHome extends EJBHome {

ects2EJBSample create()

throws RemoteException, CreateException;

ects2EJBSample create(String poolName)

throws RemoteException, CreateException;

}

ects2EJBSample

The following is sample code for the remote interface class. The methods exposed in the remote interface must match the methods of the EJB component class. A client call to a remote interface method is executed by the corresponding method of the EJB component.

/* A reference implementation of the OIG EJB session remote interface. */

package com.ObjectStar.examples;

import com.ObjectStar.ects.*;

import javax.ejb.EJBObject;

import com.ObjectStar.jdbc.rowset.*;

public interface ects2EJBSample extends ects2EJBRemoteIntf {

StringBuffer runTag(String tagName)

throws java.rmi.RemoteException;

StringBuffer runXMLDoc(String docName)

throws java.rmi.RemoteException;

StringBuffer runTrans(String tranName)

throws java.rmi.RemoteException;

}

Deployment Descriptor

This is a sample deployment descriptor file for the ects2EJBSample EJB component.

<?xml version="1.0"?>

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://www.java.sun.com/dtd/ejb-jar_2_0.dtd">

<ejb-jar>

<description>OIG EJB support</description>

<display-name>ectsEJB</display-name>

<enterprise-beans>

<session>

<description>no description</description>

<display-name>ectsSample</display-name>

<ejb-name>ects2EJBSample</ejb-name>

<home>com.ObjectStar.examples.ects2EJBSampleHome</home>

<remote>com.ObjectStar.examples.ects2EJBSample</remote>

<ejb-class>com.ObjectStar.examples.ects2EJBSampleBean</ejb-class>

<session-type>Stateful</session-type>

<transaction-type>Bean</transaction-type>

<env-entry>

<env-entry-name>HOST</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>pipin</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>PORT</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>9068</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>USERID</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>HURON1</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>PASSWORD</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>HURON1</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>LIBRARY</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>ECTSSAMP</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>SEARCH</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>L</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>MAXSESSION</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>3</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>POOLTIMEOUT</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>4000</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>DATAIN</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>16384</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>DATAOUT</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>16384</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>XMLTRACEDIR</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value><null/></env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>DEBUG</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>false</env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>TRACEMESSAGES</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value><null/></env-entry-value>

</env-entry>

<env-entry>

<env-entry-name>XMLPARSER</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>org.apache.xerces.parsers.SAXParser</env-entry-value>

</env-entry>

</session>

</enterprise-beans>

<assembly-descriptor>

<security-role>

<description>Users</description>

<role-name>users</role-name>

</security-role>

</assembly-descriptor>

</ejb-jar>

 

Copyright © Cloud Software Group, Inc. All Rights Reserved