Create 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 JavaBean (EJB) project. A HATS EJB project provides access to the host interactions, encapsulated in Integration Objects, needed to provide host data to a calling application, which can be another HATS application or a user-written Java program. A HATS EJB project does not present transformed screens from a host application. Using 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. This section assumes that you are familiar with basic EJB concepts. If not, please refer to the WebSphere Studio documentation on this subject, or the WebSphere infocenter for your version and edition of WebSphere Application Server.

  2. WebSphere Studio Site Developer (WSSD) does not support Enterprise JavaBeans. You cannot create or work with HATS EJB projects, or import previously developed EJBs, using WSSD.

  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 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 Studio. This view is called the HATS EJB Project View. It is analogous to the HATS Project View, but it contains only HATS EJB projects. It will show the EJB resources described below. To work with your HATS EJB project, you can use the HATS EJB Project View in the same ways that you use the HATS Project 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) 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 will have the same signature as the Integration Object, allowing applications and JSPs to be developed to drive an Integration Object via the EJB Access Bean. Since 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 2

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

Figure 2. A HATS EJB project
A HATS EJB project

 

Create 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. We will call this 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 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 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 choose 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. Use WebSphere Studio capabilities to create Java Bean Web pages or 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 re-deploy the HATS EJB project, 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 use a code repository, such as CVS, to store your projects, you must do some extra work when you store a HATS EJB project. By default, most code repositories do not store .class files. When you create a HATS EJB project, some class files are created automatically. You must store these class files with your project, or the project will fail when it is checked out.

The four class files are created in the imported_classes\com\ibm\HostPublisher\EJB\ folder in your HATS EJB project. After you store your project, open the Navigator view, open this directory in your HATS EJB project and select the four class files. Right click and select Team > Add to Version Control (or the equivalent selection for your repository). If you see a message that says that files of that type are not usually stored in the repository, click to do it anyway. Then Commit those files.

 

Programming with EJB Access Beans

When you create an Integration Object in a HATS EJB Project in HATS Studio, 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 included in the HATS EJB application.

 

Use 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 associated with the client session. The properties are retrieved by subsequent EJB Access Beans in processing 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 
    String 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.

 

Use EJB Access Beans with Java application clients

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

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

In following the steps to use EJB Access Beans with a Java application client, choose whether you are using a J2EE application client or a Java thin application client. Follow these 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 J2EE 1.3 application client as documented in the infocenter for your version and edition of WebSphere Application Server. Put this new project into the same Enterprise Archive (.ear file) as the HATS EJB project. Add these jar files as dependent jars:

    • The EJB .jar file of the HATS EJB project

    • hatscommon.jar

    You will see a warning that the Main-class attribute must be defined. Ignore this message for now.

  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 your application client project. Create the public static void main stub.

  5. Now you can fix the missing Main-class attribute error from step 2:

    1. Open META-INF\MAINFEST.MF in the application client project.

    2. Click Browse next to the Main Class field. Choose your class from the list.

  6. If you are using the J2EE application client, add the EJB reference and environment variables to the client deployment descriptor:

    1. Open META-INF\application-client.xml.

    2. On the Overview tab, add an environment variable with these values:

      • 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: String

      • Value: ejb\ejb_project_name, where ejb_project_name is the name of your HATS EJB project.

    3. On the References tab, click Add, and choose EJB reference. Click Browse for the Link field, and choose the EJB in your HATS EJB project.

  7. Publish the .ear file to your test server.

  8. Test the application client:

    1. a. Open the Debug perspective.

    2. Start the application server.

    3. Click the bug drop-down list , and select Debug to define and start the test environment for the J2EE application client that you created:

      1. Click WebSphere V5 Application client.

      2. Click New.

      3. Go to 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.

        • Choose the WebSphere V5 server type.

        • Choose the .ear that your application client resides in.

        • Choose your application client module.

        • Click Apply.

        • Click Debug to start the test environment. You will see the output of your test client in the console.

  9. 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. If you are using the J2EE application client, open a command prompt and enter Run launchClient ejb_project_name.ear, 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 either blank or 2809.

  3. If you are using the Java thin application client, follow these steps:

    1. Locate the EJB_Access_Bean.properties file in your application client project. It should be in the appClientModule\IntegrationObject folder. Edit this file and set PROVIDER_URL to iiop://server-name:2809, where server-name is the name of your test server.

    2. Copy setupCmdLine.bat to setupCmdLineThin.bat.

    3. Edit setupCmdLineThin.bat and change J2EE to J2EETHIN.

    4. Copy launchClient.bat to launchClientThin.bat.

    5. Edit launchClientThin.bat and have it call setupCmdLineThin. Also, on the java command line, in the -classpath section, replace %WAS_CLASSPATH% with: %WAS_HOME%\properties;%WAS_HOME%\lib\bootstrap.jar;%WAS_HOME%\lib\lmproxy.jar

    6. Open a command prompt and enter Run launchClientThin ejb_project_name.ear, 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 launchClientThin.bat to make sure that DEFAULTSERVERNAME is set to your test server and SERVERPORTNUMBER is either blank or 2809.

 

Home