Attachmate™ Verastream® Host Integrator J2EE Connector - Client 1.6.5-SNAPSHOT API

The Attachmate™ Verastream® Host Integrator (VHI) J2EE Connector (resource adapter or RA) connects to the VHI Session Server, providing managed and secure host access for J2EE applications.

See:
          Description

Packages
com.attachmate.vhi.resource.client Attachmate™ Verastream® Host Integrator J2EE Connector client classes.

 

The Attachmate™ Verastream® Host Integrator (VHI) J2EE Connector (resource adapter or RA) connects to the VHI Session Server, providing managed and secure host access for J2EE applications. The VHI-RA implements a resource adapter as defined in the J2EE Connector Architecture Specification, version 1.5.

The Resource Adapter (RA) is the preferred way for J2EE applications and components to connect to Enterprise Information Systems (EIS). While it is possible for J2EE components to contact the EIS directly, it introduces performance and security problems. The J2EE specification requires the RA to implement security interfaces and hooks so that the J2EE server can manage lifecycle and resources through a common administrative model. Application server users are accustomed to using this mechanism for configuring their systems.

A “pure” RA implementation would contact the EIS (mainframe host) directly; however, VHI already has a framework for dealing with host connections, so from the perspective of a VHI RA, the VHI Session Server is the EIS. It is a minor point, except that users may have to deal with some administrative overlap between VHI and the J2EE application server.

Lifecycle Management

The RA fully implements the lifecycle management interfaces as described in J2EE Connector Architecture Specification Version 1.5 section 5.3 Lifecycle Management Model except for inbound messaging. We do not support inbound messaging because VHI Session Server does not send host-initiated event messages to its clients.

Connection Management

The RA implements all of the required connection management interfaces exactly as described in J2EE Connector Architecture Specification Version 1.5 section 6.10.1 Resource Adapter. Prior to allocating a connection to a client, match connections verifies that the host session is still on the expected or home entity. If it is not, it will destroy that connection and create a new one automatically as part of the normal J2EE connection management process.

Security Contract

The RA fully implements all of the required security contract interfaces exactly as described in J2EE Connector Architecture Specification Version 1.5 section 9.2.1 Resource Adapter.

The well-known properties UserName and Password are mapped to the model variable keys userID and password according to the rules and policies specified by the J2EE specifications regarding security. When using component-managed connections, the client can specify the username and password; otherwise, the username and password come from the RA deployment and pool settings as prescribed by the administrator.

It is important to note that although clients and administrators can configure UserName and Password, which the appserver will process according to the J2EE specification, it is still the responsibility of the procedure designer and the VHI Session Server administrator to ensure that the credentials are used correctly in the VHI Session Server environment. For example, session pools that are already logged into a host session cannot log in again. That would be an example of VHI Session Server-managed logins, and there is nothing the RA can do if the Session Server configuration usurps this function. Similarly, if the procedure designer renames the default userID and password model variable names, the mapping will be broken.

Keep in mind, attempts by clients or administrators to set the model variables userID and password directly, in the RA configuration or in the connection spec, will fail. The RA sets (or over-writes) these model variables when it processes the UserName and Password properties during the authentication and connection process. No one can bypass security in this way. However, clients can still pass other model variables (such as LU-name, or secondary logins) transparently, through the RA.

Finally, the host login and the VHI Session Server login are two separate things. The VHI Session Server credentials are exposed as the RA configuration properties UserNameVHI and PasswordVHI. These are custom properties: Neither the appserver nor the RA provide any special security mapping or other processing for them. They are not exposed to the client for component-managed connections. They are administrator-configured settings only.

Transaction Management

The RA implements the transaction management interfaces as described in J2EE Connector Architecture Specification Version 1.5 section 7.13.1 Resource Adapter for the NoTransaction classification level of support. This requires parts of the RA API that involve transactions to throw the NotSupportedException when called. Transactions have no meaning in traditional screen-based applications.

Common Client Interface (CCI)

This RA implements CCI as described in J2EE Connector Architecture Specification Version 1.5 section 15.4 Common Client Interface as follows:

Procedure-Oriented

The RA is procedure-oriented. Every interaction with the Session Server follows the same pattern:
  1. set data (mapped record of filters and inputs each consisting of mapped records obtained from the RecordFactory)
  2. execute named procedure
  3. get results (returns javax.resource.cci.IndexedRecord)

Interaction Schema

This release supports data in javax.resource.cci.IndexedRecord and javax.resource.cci.MappedRecord.

Procedure Inputs

Procedure inputs consist of a mapped record containing

Procedure Outputs

Procedure outputs consist of an indexed record containing This schema follows a consistent model:

Data-Driven

The RA is data-driven. The same code works for all clients.

Packaging

Because it is data driven, users may package and deploy the RA once for each VHI Session Server or domain, and many clients can access it. This design also allows users to package an RA for individual applications. There are good reasons to do either or both; we do not constrain the user to one or the other.

An application server administrator can deploy the RA for container-managed or component-managed connections. In the container-managed scenario, the administrator specifies all settings during deployment and configuration. If the administrator allows it, component-managed connections can specify client-specific parameters such as user name, password, model variables, etc., but not settings related to the configuration of a target VHI Session Server.

You can generate project-specific Enterprise Java Beans (EJBs) in WebBuilder and incorporate them into your own J2EE applications, or write your own custom applications directly to the VHI RA Common Client Interface.

Custom applications must include vhi-ra-client.jar in the classpath (as part of a J2EE assembly or extension library) in order to reference the RA client classes.

Deployment

The VHI RA is designed to be data-driven, that is, you need only deploy it once. The same code works for all applications. It is possible to deploy it multiple times, with different configurations; however this is not necessary unless you have a specific reason to do so (for example, if you wish to package the RA along with a complete application). We envision the more common scenario is to deploy the RA once, and then create multiple RA pools with the appropriate configurations for various applications. You can then register these configurations in JNDI using names that your applications can use to look up an RA instance as needed.

The generic VHI RA module is located in install-dir/vhi/lib/java/vhi-ra.rar. Application servers differ in the way that they have you deploy resource adapters, but the usual procedure is to use a deployment tool (GUI or command line) or an administration console to browse to the vhi-ra.rar file to deploy the VHI RA. Alternatively, some appservers allow you to drop the vhi-ra.rar file into an auto-deploy directory.

Configuration

After you have deployed the VHI RA, the next step is to use the appserver's administration console to create resource pools using these VHI RA configuration properties. Configuration properties must include the following: The application server provides places to set these properties in the administration console. Advanced users may unzip vhi-ra.rar and edit ra.xml to customize and preconfigure the RA. Alternatively, you may build your own RAR file from scratch using vhi-ra-client.jar and vhi-ra-server.jar from the lib directory and deploy the customized RAR.

After you create the pool, you register it in the appserver's JNDI registry. The JNDI name (called "resource name" by some appservers) is the name that your applications will use to obtain an instance of the RA from the pool. For example, if you generated EJBs in WebBuilder using the default names, they would look up an RA pool named eis/ProjectName using the coded name java:comp/env/eis/ProjectName. You can use the resource reference (res-ref) mechanism to map the coded name to a different pool name if you choose to name the pool something else.

Note: Some application servers do not accept a generic RAR file, and do not provide a configuration UI. They require you to open the RAR file and customize META-INF/appserver-ra.xml instead. For those appservers, we have included sample appserver-ra.xml files in the generic RAR file for you to use as a starting point. The actual sample configuration is disabled by default.

Usage

The main class is the connection factory. You obtain an instance of this class using JNDI lookup, like this:
        Context initialContext = new InitialContext();
        ConnectionFactory cf = (ConnectionFactory)initialContext.lookup("java:comp/env/eis/PurchasesDemo");
        
(assuming the administrator named the resource pool "eis/PurchasesDemo" in the JNDI registry, or mapped the resource reference to it).

You can get resource adapter metadata like this:

        ResourceAdapterMetaData rmd = cf.getMetaData();
        
which, if you print rmd.toString(), looks something like this:
        com.attachmate.vhi.resource.ConnectionFactoryImpl$ResourceAdapterMetaDataImpl
            AdapterName:                             VHI Session Server Resource Adapter
            AdapterShortDescription:                 Resource adapter for host screen applications
            AdapterVendorName:                       Attachmate
            AdapterVersion:                          0.0.0.0
            InteractionSpecsSupported: 
                com.attachmate.vhi.resource.InteractionSpecImpl
            SpecVersion:                             1.5
            SupportsExecuteWithInputAndOutputRecord: true
            SupportsExecuteWithInputRecordOnly:      true
            SupportsLocalTransactionDemarcation:     false
        
Here, we obtain a component-managed connection to the RA configured for the PurchasesDemo model. We create a new connection spec:
        ConnectionSpec connectionSpec = new ConnectionSpecImpl();            
        
        connectionSpec.setUserName("myUserName");   // (optional)
        connectionSpec.setPassword("myPassword");   // (optional)
        
Now connectionSpec.toString() looks like this:
        com.attachmate.vhi.resource.ConnectionSpecImpl
            ModelVariables:   {}
            Password:         **********
            UserName:         myUserName
        
Get the connection and the metadata:
        ConnectionImpl connection = cf.getConnection(connectionSpec);            

        cmd = connection.getMetaData();
        
Now if you print cmd.toString(), it looks like this:
        com.attachmate.vhi.resource.ConnectionImpl$ConnectionMetaDataImpl
            EISProductName:    Verastream Host Integrator
            EISProductVersion: 6.5
            Locale:            en_us
            ModelVersion:      Apptrieve 6.5.1 Model v1145927641:1:0370128738 
            ProcedureNames:
                CustomersTable.AddCustomer
                CustomersTable.GetCustomers
                PurchasesTable.GetAllPurchases
                PurchasesTable.GetPurchasesByAcctNum
            ProcedureMetaData:
                {name=AddCustomer, description='This procedure adds a customer to the purchases list and returns a list of account numbers.  The account number of the new customer is the last one in the list.', metaDataType=4, filterColumns=[FirstInitial, LastName], requiredFilterColumns=[FirstInitial, LastName], inputColumns=[], requiredInputColumns=[], type=3, useForSQL=true}
                {name=GetCustomers, description='', metaDataType=4, filterColumns=[], requiredFilterColumns=[], inputColumns=[], requiredInputColumns=[], type=3, useForSQL=true}
                {name=GetAllPurchases, description='', metaDataType=4, filterColumns=[], requiredFilterColumns=[], inputColumns=[], requiredInputColumns=[], type=3, useForSQL=true}
                {name=GetPurchasesByAcctNum, description='Given an account number, this procedure lists the last 3 purchases made by that customer', metaDataType=4, filterColumns=[AcctNum], requiredFilterColumns=[AcctNum], inputColumns=[], requiredInputColumns=[], type=3, useForSQL=true}
            Secure:            false
            UserName:          username
        
listing information about the model or session you connected to. You can use procedures and procedure metadata for determining how to interact with the host. Procedures are listed qualified by table name. Procedure metadata is listed in the same order as the procedure names.

To execute a procedure, you create an interaction and an interaction spec, in the usual CCI style:

        Interaction interaction = connection.createInteraction();
        InteractionSpecImpl interactionSpec = new InteractionSpecImpl();

        interactionSpec.setFunctionName("CustomersTable.GetCustomers");
        
There are several other properties you can set on the interaction spec, but the most important one is the function name as shown above (CCI standard mandates "FunctionName" for this property; it maps to "procedure name" in VHI parlance). The interaction spec looks like this if you print interactionSpec.toString():
        com.attachmate.vhi.resource.InteractionSpecImpl
            ExecutionTimeout:    0
            FetchSize:           0
            FilterCaseSensitive: false
            FunctionName:        CustomersTable.GetCustomers
            InteractionVerb:     SYNC_SEND_RECEIVE
            OutputColumnNames:   null            
        
(please refer to the JavaDocs for information about the other properties).

All that remains now is to execute the interaction. You need to get an input record from the record factory. If your procedure has input parameters, you populate the input record with them. The example we're using has no input parameters, so you simply use the empty record of the type "inputs", like this:

        RecordFactory recordFactory = cf.getRecordFactory();
        MappedRecord inputParams = recordFactory.createMappedRecord("inputs");        
        
Here's how the record looks if you print inputParams.toString():
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             inputs
            RecordShortDescription: Procedure input record
            Keys:                   [filter, data]
            Values:                 [
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             filter
            RecordShortDescription: Procedure filter parameters
            Keys:                   []
            Values:                 [], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             data
            RecordShortDescription: Procedure data parameters
            Keys:                   []
            Values:                 []]        
        
The record has two sub-records, "filter" and "data" that correspond to filter and data parameters on VHI procedures. If you had filters or data parameters to send, you would put them into their respective records.

Clear warnings in preparation for executing the procedure...

        interaction.clearWarnings();
        
Now, execute the procedure:
        Record outputParams = interaction.execute(interactionSpec, inputParams);            
        
Check for warnings and extract the cause...
        ResourceWarning warning = interaction.getWarnings();

        if(warning != null)
        {
            EISApptrieveException cause = (EISApptrieveException)warning.getCause();

            cause.printStackTrace();
            throw(cause);
        }
        
The resulting record looks like this when you print outputParams.toString():
        com.attachmate.vhi.resource.IndexedRecordImpl
            RecordName:             rows
            RecordShortDescription: Procedure output rows
            Values:                 [
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [M, 20000, WAGY], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [A, 20008, WARD], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [J, 20003, WARNER], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [J, 20001, WATERS], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [J, 20007, WEBSTER], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [M, 20004, WILSON], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [S, 20006, WINTERS], 
        com.attachmate.vhi.resource.MappedRecordImpl
            RecordName:             columns
            RecordShortDescription: Procedure output columns
            Keys:                   [FirstInitial, AcctNum, LastName]
            Values:                 [M, 20002, KIRKMAN]]           
        
The outer record is an indexed record of type "rows", which contains the rows in the order they were returned by the procedure. Each row is a mapped record of type "columns", which contains the column data as key/value pairs.

You can re-use the interaction for multiple procedure calls with different interaction specs, but be sure to close the interaction when you are finished with it:

        interaction.close();
        

Finally, close the connection:

        connection.close();
        
It is a good idea to put the close inside a finally clause, so that the connection closes no matter what.

Errors and Logging

Exceptions are classified into three increasing levels of severity: warning, severe and unexpected. You can configure the appserver to record or filter log messages based on these logging levels.

Predefined System Procedures

System procedures are used to control or configure specific aspects of the VHI RA or VHI Session Server. You invoke predefined system procedures in the same way as you would user-defined custom procedures, described above.

vhi.sp_passivate

Provides support for passivating stateful session EJBs. Suspends the connection to the VHI Session Server. The values in the output record are used in the connection spec to obtain a new connection on EJB activation. The VHI RA configuration property SuspendConnection controls the time in minutes before the connection expires permanently.
Input Record
Output Record (one row)



Copyright © 2007 Attachmate Corporation. All Rights Reserved.