|
||||||||||
PREV NEXT | FRAMES NO FRAMES |
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.
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.
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.
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.
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.
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: falseHere, 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: myUserNameGet 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: usernamelisting 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.
warning.toString()
), and also at the FINEST logging
level with a full stack trace.
severe.toString()
), and also at
the FINER logging level with a full stack trace.
unexpected.toString()
), and also at the
FINE logging level with a full stack trace.
SuspendConnection
controls
the time in minutes before the connection expires permanently.
connection.token
- token for activating the passivated
connection later.
expected.entity
- used to validate the session on activation.
Activation will fail if the session is not on the expected entity.
|
||||||||||
PREV NEXT | FRAMES NO FRAMES |