Creating and using a HATS EJB application

As an alternative to the usual HATS project, which transforms one or more host applications and presents Web pages to an end user, you can build a HATS Enterprise JavaBeans (EJB) project. A HATS EJB project provides access to the host interactions, which are encapsulated in Integration Objects. The Integration Objects are needed to provide host data to an EJB client, which can be another HATS application, a user-written Java™ program, a Web application, or even another EJB. A HATS EJB project enables you to separate the collection of the host data from its presentation. If you have one or more Integration Objects that you want to be able to invoke from several HATS projects, you can include them in a HATS EJB project and call them from several other HATS projects. When you have finished configuring your HATS EJB project, you can assemble it as a HATS EJB application.

Notes:
  1. HATS EJB project support is deprecated in HATS V9.5. While support for HATS EJB projects continues for now, IBM reserves the right to remove this capability in a subsequent release of the product. Alternatives are:
  2. This section assumes that you are familiar with basic EJB concepts. If not, refer to the Rational® SDP documentation on this subject, or the WebSphere® Knowledge Center for your version and edition of WebSphere Application Server.
  3. You cannot include an Integration Object that is configured to use Web Express Logon in a HATS EJB project.
  4. If you have developed EJB projects in Host Publisher, you can import them into HATS projects. Refer to HATS User's and Administrator's Guide for information about importing Host Publisher projects into HATS.

A HATS EJB application does not interact directly with an end user, nor does it transform host screens. It does not contain the resources that are included in a HATS project: screen customizations, templates, or transformations. A HATS EJB application contains one or more Integration Objects, whose services it makes available to calling programs.

When you create HATS EJB projects, a new view is opened in HATS Toolkit. This view is called the HATS EJB Project view. It is analogous to the HATS Projects view, but it contains only HATS EJB projects. It shows the EJB resources that are described in this section. To work with your HATS EJB project, you can use the HATS EJB Project view in the same ways that you use the HATS Projects view for other HATS projects. For example, you can click the project name in the HATS EJB Project view and then click the host terminal icon to open the host terminal for the project's main connection, in order to record macros.

A HATS EJB application is an enterprise archive (EAR file) made up of one or more Integration Objects, whose services it makes available to an EJB client and typically consists of these parts:

In addition to providing the HATS EJB, HATS EJB support generates an EJB Access Bean for each Integration Object. This EJB Access Bean has the same signature as the Integration Object, allowing applications and JSPs to be developed to drive an Integration Object using the EJB Access Bean. Because the EJB Access Bean has the same signature as the Integration Object, the EJB Access Bean can be used in client-side code exactly as the original Integration Object would be used. Therefore, the client can be:

Figure 21

shows the links between a HATS EJB application and other applications that use its services.

Figure 21. A HATS EJB project
A HATS EJB project

Creating a HATS EJB project

Follow these steps to create a HATS EJB project:

  1. Start with a HATS project, which will ultimately contain the EJB Access Beans. This is referred to as the target HATS project.
  2. Click File > New > Project > HATS > HATS EJB Project. Be sure to put the HATS EJB project in the same EAR as your HATS target project. Define one host connection in the wizard.
  3. If you want to use Integration Objects that were created with Host Publisher Studio, import them into your project. Click File > Import, select Host Publisher IO, and complete the wizard. You do not need to define connections or record macros for these Integration Objects.
  4. Define the connections to any additional host machines from which you will extract data. Refer to HATS User's and Administrator's Guide for information about defining connections.
  5. If any of your host connections require connect and disconnect macros, use the host terminal to record those macros. Then use the connection editor to update each affected connection to specify the names of the connect and disconnect macros that are used on that connection. Refer to HATS User's and Administrator's Guide for information about recording connect and disconnect macros.
  6. If you have not already created Integration Objects, connect to the host applications from the HATS EJB Project view and follow the instructions in HATS User's and Administrator's Guide to create Integration Objects.
  7. When your HATS EJB project contains all the connections, macros, and Integration Objects you require, you are ready to export EJB Access Beans to your target HATS project. To do this, right click any Integration Object in your EJB project in the HATS EJB Project view and select Export EJB Access Bean to HATS Project. You can then select the target HATS project, and the Integration Objects for which you want EJB Access Beans created.
  8. Now you are ready to work with the EJB Access Beans that you have just created in the target HATS project. The EJB Access Beans are in the source folder of the target HATS project, in the IntegrationObject package, in files with a name pattern of io-name_Access.java. You can create HATS business logic to drive an EJB Access Bean; the process is the same as driving an Integration Object from business logic, which is described in Adding business logic. You can use Rational SDP capabilities to Insert Beans and Insert Results from Beans onto JSP pages. You cannot generate HATS Model 1 or Struts Web pages directly from an EJB Access Bean.
  9. Assemble the projects into an enterprise archive (EAR file), as described in HATS Getting Started. Deploy it to WebSphere Application Server.

You can also use the EJB Access Beans in Java code that you write yourself. See Programming with EJB Access Beans for information about using the EJB Access Beans in code that you write.

The EJB Access Beans are created based on the macro that was recorded and made into an Integration Object. If you modify the macro in such a way that it changes the signature of the Integration Object, and redeploy the HATS EJB project, you must re-export the matching EJB Access Beans and modify the code or JSPs that use them.

Storing a HATS EJB project in a repository

If you store a HATS EJB project in a repository, such as CVS, some directories are not stored. You must store the contents of these directories manually. After storing your project, you must also store all the files in these directories. These files will not be included if a HATS EJB project is stored as an archive file.

Creating EJB Access Beans automatically

To make it easier to use EJB Access Beans in a project that is not a HATS project, refer to the preference Automatically generate EJB Access Bean in HATS EJB project when an Integration Object is created on the HATS Preferences page.

If you click this preference, an EJB Access Bean is created in your HATS EJB project whenever you create an Integration Object. If you have selected the Automatically generate Integration Object when saving macro preference, an EJB Access Bean is created along with the Integration Object when you create or modify a macro.

You can then copy the EJB Access Bean directly to your other project without having to export it to a HATS project. You must still follow the steps listed in Using EJB Access Beans with Java application clients to add the EJB reference and EJB environment variable in your other project.

EJB Access Beans are not created automatically when you migrate a project.

For more information about using HATS preferences, refer to HATS User's and Administrator's Guide.

Programming with EJB Access Beans

When you create an Integration Object in a HATS EJB Project in HATS Toolkit, EJB support files are generated. One of the files generated is the EJB Access Bean. The EJB Access Bean is a Java bean that has the same signature as the Integration Object that the Access Bean supports. Your application will use the EJB Access Bean to interact with the Integration Objects that are included in the HATS EJB application.

Using EJB Access Bean methods

HATS Integration Objects contain Java methods that you can use when programming with Integration Objects. These methods are also available when programming with EJB Access Beans. In addition to the methods described in Integration Object methods, you can use the following methods when programming with EJB Access Beans:

java.lang.Object getHPubAccessHandle()
Returns the handle for the HATS EJB instance corresponding to the Integration Object chain
void setHPubAccessHandle(java.lang.Object value)
Sets the handle for the HATS EJB instance corresponding to the Integration Object chain

EJB Access Bean chaining

To support chained Integration Objects, the HATS EJB is implemented as a stateful session bean, where the life cycle of a HATS EJB instance corresponds with the processing of an Integration Object chain. When EJB Access Beans for an Integration Object chain are processed, two EJB Access Bean properties are used:

hPubAccessHandle
Contains the handle for the HATS EJB instance corresponding to the Integration Object chain
hPubLinkKey
Contains the key that represents the connection for the Integration Object chain
EJB Access Bean chaining in a Web container

When EJB Access Beans are used in a Web module with the doHPTransaction method, the EJB Access Bean saves the values of the hPubAccessHandle and hPubLinkKey properties in the HttpSessionObject that is associated with the client session. The properties are retrieved by subsequent EJB Access Beans during processing of the Integration Object chain.

The EJB Access Bean for the first Integration Object in a chain creates an instance of the HATS EJB. That instance is used for all EJB Access Beans for the subsequent Integration Objects in the chain. After the processing of the EJB Access Bean for the last Integration Object in a chain, the HATS EJB instance corresponding to that Integration Object chain is removed. Thus, when using the doHPTransaction method in a Web module with EJB Access Beans, chaining is managed within the EJB Access Bean.

EJB Access Bean chaining outside a Web container

When EJB Access Beans are processed outside of a Web container (for example, directly from a Java program), the calling program must retrieve the values of the hPubAccessHandle and hPubLinkKey properties. The properties can be retrieved after the EJB Access Bean for the first Integration Object in the chain is processed. The calling program must set the two properties for all subsequent EJB Access Beans in the Integration Object chain before they are processed.

To chain EJB Access Beans outside of a Web container, do the following:

  1. Create an instance of the first EJB Access Bean in the chain by calling its constructor.
  2. Invoke the setter methods for the EJB Access Bean instance to set properties of input variables. The naming convention for setter methods is as follows: 
    EJBChain1.setXyz(String)
    where Xyz is the name of your input variable.
  3. Invoke the EJB Access Bean to perform its task, for example running a macro, using the method: 
    EJBChain1.processRequest()
  4. Check for errors by invoking: 
    EJBChain1.getHPubErrorOccurred()
  5. Extract and save the key that represents the connection for the EJB Access Bean chain: 
    String myLinkkey = EJBChain1.getHPubLinkKey();
  6. Extract and save the handle for the HATS EJB instance corresponding to the Integration Object chain: 
    Object myHandle = EJBChain1.getHPubAccessHandle();
  7. Create an instance of the next EJB Access Bean in the chain by calling its constructor.
  8. Set the key for this chained connection: 
    EJBChain2.setHPubLinkKey(myLinkkey);
  9. Set the handle for this chained connection: 
    EJBChain2.setHPubAccessHandle(myHandle);
  10. Invoke the methods for this EJB Access Bean instance. You might want to invoke methods to set properties of input variables. The naming convention for setter methods is as follows: 
    EJBChain2.setXyz(String)
    where Xyz is the name of your input variable.
  11. Invoke this EJB Access Bean to perform its task (running a macro or querying a database, for example), using the method: 
    EJBChain2.processRequest()
  12. Check for errors by invoking: 
    EJBChain2.getHPubErrorOccurred()

Repeat steps 7 through 12 for any and all subsequent EJB Access Beans in the chain.

Using EJB Access Beans with Java application clients

With WebSphere, Java application clients consist of the following models:

For more information about these client modules, refer to the WebSphere Knowledge Center documentation.

The following sections assume that you have chosen to use a Java EE application client. If you are using a Java thin application client, consult the WebSphere Knowledge Center for the instructions that are appropriate for your WebSphere release.

Complete the following steps to use EJB Access Beans with a Java application client:

  1. Start with a HATS EJB project that contains one or more macros, Integration Objects, and other resources, and a HATS project to which you have exported EJB Access Beans from the HATS EJB project.
  2. Create a Java EE application client as documented in the Knowledge Center for your version and edition of WebSphere Application Server. To follow these instructions, choose to generate a Main class, and a deployment descriptor. Put this new project into the same enterprise archive (EAR file) as the HATS EJB project. Add these jar files as dependent jars:
  3. Move your EJB Access Beans to the application client project. Copy the IntegrationObject folder that holds the EJB Access Beans from the HATS project to the appClientModule directory of the application client project.
  4. Build your test client in the Main class that was generated in your application client by implementing the code to instantiate your EJB Access bean and run it.
  5. If you are using the Java EE application client, add the EJB reference and environment variables to the client deployment descriptor:
    1. Open META-INF\application-client.xml.
    2. On the Design tab of the Application Client Descriptor Editor, do the following:
      1. Click Add and choose to add an environment variable:
        • Name: Copy the value of the last part of the HPUBEJB2_REFERENCE string in the EJB Access Bean into this field. For example, it might say HPUBEJB2_REFERENCE1318657356.
        • Type: java.lang.String
        • Value: ejb/ejb_project_name, where ejb_project_name is the name of your HATS EJB project.
      2. Click Add and choose to add an EJB reference:
        • EJB Reference name: ejb ejb_project_name, where ejb_project_name is the name of your HATS EJB project.
        • EJB Reference type: Session
        • Home: com.ibm.HostPublisher.EJB.HPubEJB2Home
        • Remote: com.ibm.HostPublisher.EJB.HPubEJB2
        • EJB link: ejb_project_name.jar# ejb_project_name, where ejb_project_name is the name of your HATS EJB project.
  6. Publish the EAR file to your test server.
  7. Test the application client:
    1. Open the Debug perspective.
    2. Start the application server.
    3. Click the Debug drop-down list , and select Debug to define and start the test environment for the Java EE application client that you created:
      1. Click WebSphere Application client.
      2. Click New.
      3. Click the Application tab and complete the fields:
        • In the Name field, type a name for your test configuration that is unique to your application client.
        • Select the WebSphere server type.
        • Select the EAR that your application client resides in.
        • Select your application client module.
        • Enable the application client to connect to a server and choose either a specific server or a provider URL.
        • Click Apply.
        • Click Debug to start the test environment. You will see the output of your test client in the console.
  8. Export the application client. From the Navigator view, right click the name of the application client project and select Export. Export it as an EAR file.

Running your application client

After you have completed the steps in the previous section, follow these steps to run your application client:

  1. Copy your EAR file into the bin directory of the application client.
  2. Open a command prompt and enter Run launchClient ejb_project_nameEAR, where ejb_project_name is the name of the ear file that you copied into the bin directory of the application client. This will run your application client. If you do not see the output you expect, check launchClient.bat to make sure that DEFAULTSERVERNAME is set to your test server and SERVERPORTNUMBER is set to the Bootstrap port of the test server. The default Bootstrap port is 2809, but might be different depending on the WebSphere configuration. The Bootstrap address is the combination of the Bootstrap Host and Bootstrap port, with a colon (:) between them. To find the Bootstrap port of the WebSphere Application Server, open the WebSphere Administrative Console and look for Servers > Application servers > servername > ports > BOOTSTRAP ADDRESS.

Running EJB application clients in a clustered environment

To run an EJB application client in a clustered environment, there are two options: