Java Connector

Use the Java Connector to create Java applications that integrate host data into web applications or client/server applications. This section describes the Java connector and provides tips on how to build powerful and robust applications that take advantage of the connector's features and options.

You can use the Web Builder tool to create Java projects, based on the "demo" models provided with Verastream Host Integrator, and then examine the Java code in your projects to see how the Java connector works.

To be able to use the Verastream Java Connector on your computer, you must choose the "Java Connector" when you're installing Verastream Host Integrator. Installing with this option selected copies all necessary files to your computer including the Java Development Kit.

To use the Java connector to develop an application that accesses the host application model file on your Host Integrator Server, you need the provided Java Development Kit as well as a Java IDE of your choice. You can use the JDK Framework to build, deploy, and run XML Web services and Java-connected applications.

• Java class library
• Java interfaces
• Importing Java classes
• Method reference

Java Class Library

The AppConn Class Library

The file apptrieve.jar contains the class libraries for the Java connector. The AppConn Java methods are documented in a set of Javadoc HTML files installed with the SDK. To view these files, you need a supported browser. View the methods reference in a new browser window.

The AppConn Java interface is implemented through the following classes:

• com.wrq.apptrieve.appconn.AppConnSession

  This class contains methods that manage model- and terminal-level tasks like connecting and disconnecting from the Host Integrator Server, navigating to and fetching entities and attributes, performing operations, and managing host application model variables. It also contains methods that perform table-level tasks, such as executing SQL statements and performing procedures.

• com.wrq.apptrieve.appconn.AppConnRecord

  This contains methods that access the data fields returned by access methods in the AppConnSession class.

• com.wrq.apptrieve.appconn.AppConnRecordSet

  This class contains methods that access data records returned by the fetch methods in the AppConnSession class. It always contains a collection of either AppConnRecord or AppConnModelRecord objects.

• com.wrq.apptrieve.agent.AppConnException

  These libraries contain methods that help you manage exceptions, errors and security.

Importing the AppConn Java Classes

To use the AppConn interfaces, add the following statement into your classes:

   import com.wrq.apptrieve.appconn.*; 
   import com.wrq.apptrieve.agent.*; 
   import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
   import org.bouncycastle.jsse.provider.BouncyCastleJsseProvider;
   import java.security.Security;

Adding the Bouncy Castle security provider

security.addProvider(new BouncyCastleFipsProvider());
security.addProvider(new BouncyCastleJsseProvider());

VHI uses Bouncy Castle as the default SSL engine for HTTPS connections. To facilitate this the Bouncy Castle provider must be the default provider and the default SSL provider. Instead of importing the Bouncy Castle security statements, you can add the the Bouncy Castle security provider by modifying your java.security file in the JRE you are using to run the Java application:

Edit your <jre>/lib/security/java.security file and add the Bouncy Castle providers to the top of the list. Remember to re-number the elements below the Bouncy Castle providers.

Java Interfaces

The AppConn Java methods are implemented through the interfaces listed below. Click the interface name to view the Java documentation for it.

• com.wrq.apptrieve.appconn.AppConnChannel

  The AppConnChannel interface contains communication methods for connecting to the Host Integrator Server and establishing sessions with models and session pools.

• com.wrq.apptrieve.appconn.AppConnTable

  Use the AppConnTable interface to interact with host application data that is based in tables. AppConnTable extends AppConnChannel, so all required connect or disconnect methods are automatically included.

• com.wrq.apptrieve.appconn.AppConnModel

  Use the AppConnModel interface to interact with host application data that is based in attribute and recordset field definitions. AppConnModel extends AppConnChannel, so all required connect or disconnect methods are automatically included.

• com.wrq.apptrieve.appconn.AppConnTerm

  The AppConnTerm interface contains methods for managing terminal sessions. You can issue any available terminal key as well as query the host for strings at the given the cursor position or screen coordinates. AppConnTerm extends AppConnChannel, so all required connect or disconnect methods are automatically included.

Structuring Your Applications

The AppConnChannel, AppConnTable, AppConnModel, and AppConnTerm interfaces are all implemented by the AppConnSession class. It's unlikely that you will work with a host application model that requires you to interact on the model, table, and terminal levels at the same time. For this reason, we recommend that when you begin new applications, you use the more specific interface definitions to keep the number of available methods within the relevant framework. For example,

AppConnTable mySession=new AppConnSession();

The statement above creates a new object that supports only the AppConnTable interface class.

Importing Java Classes

To use the AppConn interfaces, add the following statement into your classes:

        import com.wrq.apptrieve.appconn.*;     //appconn classes
        import com.wrq.apptrieve.agent.*;       //exception classes
        import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;
        import org.bouncycastle.jsse.provider.BouncyCastleJsseProvider;
        import java.security.Security;

Method Reference

The method reference for the Host Integrator java connecter is available here.

Field attributes and color constants

The method getXMLText (public java.lang.String getXMLText()) creates an XML document that specifies the text, colors, fields, and field attributes of a terminal screen. These attributes are also valuable if you want to understand or modify the XSLT used to create the green terminal screen.

The XML document references these attributes:

Field attributes

Attribute	Value
BL	Blinking text
CO	Column separated (AS/400)
Hi	Hidden
Hn	High intensity
In	Input (unprotected)
Nu	Numeric
Pe	Pen detectable (3270)
Re	Reverse video
Un	Underscore
CLR	color
Ofs	Offset
Len	Length
MDT	Field-modified

Color constants

Color constant	Value
Red	Host red
Blu	Host blue
Pnk	Host pink
Grn	Host green
Tur	Host turquoise (cyan)
Ylw	Host yellow
Wht	Host white
SL	Status line (AS/400)
PNA	Protected/Normal/Alpha
PNN	Protected/Normal/Numeric
PHA	Protected/Highlight/Alpha
PHN	Protected/Highlight/Numeric
UNA	Unprotected/Normal/Alpha
UNN	Unprotected/Normal/Numeric
UHA	Unprotected/Highlight/Alpha
UHN	Unprotected/Highlight/Numeric
ML	Message line (AS/400)
EL	Error line (AS/400)
SR	Sys request (AS/400)

Examples

You can use the Web Builder tool to create Java projects, based on the "demo" models provided with Verastream Host Integrator, and then examine the Java code in your projects to see how the Java connector works.

Pacific Department Stores Demo

The Pacific Department Stores web front-end provides users with a simple, easy-to-use interface to a mainframe application. The mainframe application's business processing is accessed through a Verastream model.

The demo is deployed to the local server and uses the Host Emulator to simulate the mainframe application. Before you run the demo, make sure that the localhost server is running in the Host Emulator.

To run the Pacific Department Stores demo:

1. Deploy the PurchasesDemo and CICSAcctsDemo models to localhost. You can find these models in the Micro Focus\Verastream\HostIntegrator\examples\ModelSamples directory.
2. Type or paste this URL into your browser: http://localhost:8081/PacificDepartmentStores.
3. Login as a CSR (Customer Services Representative).
4. Display, modify, or add customer accounts.

Because the mainframe application is just a simulation in this case, available data is limited to customers with names beginning with K or W, and to account numbers 20000 through 20004.