Chapter 3. Using JoltBeans

JoltBeans is a collection of beans that you can use to build your own Jolt client applications or applets. During development, take the beans from the JoltBeans toolkit in the component palette of a development tool and position them on the Java form (or forms) of a Jolt client application or applet. Populate the properties of the beans and establish event source-listener relationships between various beans of the application or applet. Typically, the development tool is used to generate the event hook-up code, or you can code the hook-up manually.

The JoltBeans product consists of two sets of Java Beans. The first set, the JoltBeans toolkit, is a beans version of the Jolt API. The second set, Jolt aware AWT beans, is a "Jolt enabled" version for some of the standard JDK 1.1 AWT components. These Jolt aware AWT components help you to build Jolt client GUIs with minimal or no coding.

Note: To use the toolkit, it is recommended that you are familiar with JavaBeans enabled Integrated Development Environments (IDEs). The walkthrough in this chapter is based on Symantec's Visual Cafe´ 2.5 IDE and illustrates the basic steps of building a sample applet.

This chapter contains the following topics:

What Is the JoltBeans Toolkit?

The JoltBeans toolkit includes the following beans:

These components encompass the complete Jolt Class Library as Java Beans.

The following sections provide information about the properties for each bean. For additional information, refer to your BEA Jolt User's Guide or BEA TUXEDO documentation.

See Chapter 4, "JoltBeans Toolkit Class Library Reference," and Chapter 5, "Jolt Aware AWT Beans Class Library Reference," for additional information about the JoltBeans toolkit and Jolt aware AWT beans classes, constructors, and methods.

JoltSessionBean

The JoltSessionBean represents the TUXEDO session. It encapsulates the functionality of the JoltSession, JoltSessionAttributes, and JoltTransaction classes. The JoltSessionBean offers properties to set session and security attributes, such as send timeout or TUXEDO user name, as well as methods to open and to close a TUXEDO session.

The JoltSessionBean sends a PropertyChange event when the TUXEDO session is established or closed. PropertyChange is a standard bean event defined in the java.beans package. The purpose of this event is to signal other beans about a change of the value of a property in the source bean. In this case, the source is the JoltSessionBean, the targets are JoltServiceBeans or JoltUserEventBeans, and the property changing is the LoggedOn property of the JoltSessionBean. When a logon is successful and a session is established, LoggedOn is set to true. After the logoff is successful and the session is closed, the LoggedOn property is set to false.

The JoltSessionBean provides methods to control transactions, including beginTransaction(), commitTransaction(), and rollbackTransaction().

Table 3-1 shows the JoltSessionBean properties and descriptions.

Table 3-1 JoltSessionBean Properties

Property Description

AppAddress

Set the IP address (host name) and port number of the JSL or the Jolt Relay. The format is //host:port number (e.g., myhost:7000).

AppPassword

Set the TUXEDO application password used at logon, if required.

IdleTimeOut

Set the IDLETIMEOUT value.

inTransaction

Indicate true or false depending if a transaction has been started and not committed or aborted.

LoggedOn

Indicate true or false if a TUXEDO session does or does not exist.

ReceiveTimeOut

Set the RECVTIMEOUT value.

SendTimeOut

Set the SENDTIMEOUT value.

SessionTimeOut

Set the SESSIONTIMEOUT value.

UserName

Indicate the TUXEDO user name, if required.

UserPassword

Indicate the TUXEDO user, if required.

UserRole

Indicate the TUXEDO user role, if required.

JoltServiceBean

The JoltServiceBean represents a remote TUXEDO service. The name of the service is set as a property of the JoltServiceBean. The JoltServiceBean listens to JoltInputEvents from other beans to populate its input buffer. JoltServiceBean offers the callService() method to invoke the service. JoltServiceBean is an event source for JoltOutputEvents that carry information about the output of the service. After a successful callService(), listener beans are notified via a JoltOutputEvent which carries the reply message.

Although the primary way of changing and querying the underlying message buffer of the JoltServiceBean is via events, the JoltServiceBean also provides methods to access the underlying message buffer directly (setInputValue(), getOutputValue()).

Table 3-2 shows the JoltServiceBean properties and descriptions.

Table 3-2 JoltServiceBean Properties

Property Description

ServiceName

The name of the TUXEDO service represented by this JoltServiceBean.

Session

The JoltSessionBean associated with the bean that allows access to the TUXEDO client session.

Transactional

Set to true if this JoltServiceBean is to be included in the transaction that was started by its JoltSessionBean.

JoltUserEventBean

The JoltUserEventBean provides access to TUXEDO events. The TUXEDO event to subscribe to or unsubscribe from is defined by setting the appropriate properties of this bean (event name and event filter). The actual event notification is delivered in the form of a JoltOutputEvent from the JoltSessionBean.

Table 3-3 shows the JoltUserEventBean properties and descriptions.

Table 3-3 JoltUserEventBean Properties

Property Description

EventName

Set the name of the user event represented by the bean.

Filter

Set the event filter

Session

The JoltSessionBean associated with the bean that allows access to the TUXEDO client session.

Jolt Aware AWT Beans

The Jolt aware AWT Beans are inherited from the JDK 1.1 Abstract Windowing Toolkit. They include:

JoltTextField

A Jolt aware extension of java.awt.TextField that is linked to a specific field in the Jolt input or output buffer by its JoltFieldName property. If the field occurs multiple times, the occurrence this textfield is linked to is specified by the occurrenceIndex property of this bean.

JoltTextField can be connected with JoltServiceBeans in two ways:

JoltLabel

This is a Jolt aware extension of java.awt.Label that is linked to a specific field in the Jolt output buffer by its JoltFieldName property. If the field occurs multiple times, the occurrence this textfield is linked to is specified by the occurrenceIndex property of this bean. JoltLabel can be connected with JoltServiceBeans to display output from a service. A JoltLabel listens to JoltOutputEvents from JoltServiceBeans and updates its contents according to the occurrence of the field to which it is linked.

JoltList

This is a Jolt aware extension of java.awt.List that is linked to a specific Jolt field in the Jolt input or output buffer by its JoltFieldName property. If the field occurs multiple times in the Jolt input buffer, the occurrence this list is linked to is specified by the occurrenceIndex property of this bean. JoltList can be connected with JoltServiceBeans in two ways:

JoltCheckbox

The JoltCheckbox is a Jolt aware extension of java.awt.Checkbox, that is linked to a specific field in the Jolt input buffer by its JoltFieldName property. If the field occurs multiple times, the occurrence this checkbox is linked to is specified by the occurrenceIndex property of this bean.

It can be connected with JoltServiceBeans to contain parts of the input for a service. A JoltServiceBean may listen to events raised by a JoltCheckbox. JoltCheckbox sends JoltInputEvents to its listeners (typically JoltServiceBeans) when the selection in the checkbox changes. The JoltInputEvent in this case is populated with the TrueValue property of data type String (if the box is selected) or FalseValue (if the box is unselected).

JoltChoice

The JoltChoice provides a Jolt aware extension of java.awt.Choice, that is linked to a specific field in the Jolt input buffer by its JoltFieldName property. If the field occurs multiple times, the occurrence this choice is linked to is specified by the occurrenceIndex property of this bean.

It can be connected with JoltServiceBeans to contain parts of the input for a service. A JoltServiceBean may listen to events raised by a JoltChoice. JoltChoice sends JoltInputEvents to its listeners (typically JoltServiceBeans) when the selection in the choicebox changes. The JoltInputEvent in this case is populated with the single value of the selected item.

Using the Property List and the Property Editor to Modify the JoltBeans Properties

The values of most JoltBeans properties can be modified by simply editing the right column of the Property List shown in Figure 3-1.

For some properties of JoltBeans, Custom Property Editors are provided.

The Custom Property Editors, accessed from the Property List, include dialog boxes that are used to modify the property values. You can invoke the Custom Property Editors from the Property List by selecting the button with the ellipsis "..." that is next to the value of the corresponding property value. An example is shown in Figure 3-1.

Figure 3-1 Example of the Property List and Ellipsis Button

When the ellipsis button is selected, the Property Editor shown in Figure 3-2 displays.

Figure 3-2 Property Editor Dialog Box

.

The Custom Property Editors of JoltBeans read cached information. Initially, there is no cached information available, so when the Property Editor is used for the first time, the dialog box is empty. Log on to the Jolt repository and load the property editor cache from the repository.

Details of the logon and an example of using the Property List and Property Editor are shown in the "Using the JoltBeans Repository and Setting the Property Values" section of the "JoltBeans Class Library Walkthrough."

JoltBeans Class Library Walkthrough

This walkthrough describes how to build an applet that is used to enter the account ID, click on the Inquiry button, and display the balance of the account shown in Figure 3-3.

This is an example of a completed Java form containing JoltBeans. The applet implements the client functionality for the INQUIRY service of BANKAPP.

Figure 3-3 Sample Inquiry Applet

Refer to Figure 3-5 for an example of each item. To begin, select the following items shown in Table 3-4.

Table 3-4 Required Form Components

Component Purpose

Applet

A form used to paint the beans in your development environment.

JoltSessionBean

Logs on to a TUXEDO session.

JoltTextField

Gets input from the user (in this case, ACCOUNT_ID).

JoltTextField

Displays the result (in this case, SBALANCE).

JoltServiceBean

Accesses a TUXEDO service. (In this case, INQUIRY from BANKAPP).

Button

Initiates an action.

Label

Describes the field on the applet.

Building the Sample Form

The following example is created using the Visual Cafe´ 2.5 development environment. Follow the steps to build a sample form.

  1. Drag and drop the beans (as shown in Figure 3-4) to the desired location (shown in Figure 3-5).

    Figure 3-4 JoltBeans and the Form Designer in Visual Cafe´

    Figure 3-4 shows how a JoltBean is selected and painted to the palette of the Visual Cafe´ development environment.

    Figure 3-5 Java Applet Form Designer

    Figure 3-5 shows how the JoltBeans appear in a development environment when the placement of the beans is completed.

  2. To modify or customize the buttons, labels or fields, use the Property List. Some JoltBeans use a Custom Property Editor. The example in Figure 3-6 shows how selecting the JoltFieldName of the button property list displays the Custom Property Editor. Set the properties of the beans (e.g., set the JoltFieldName property of the JoltTextField to ACCOUNT_ID. Refer to Figure 3-6).

    Note: For complete information on setting and modifying the properties of the JoltBeans, refer to "Using the JoltBeans Repository and Setting the Property Values"section in this chapter.

    Table 3-5 specifies the property values that should be set. Bold values are required, plain text recommended, and italic values are examples of required values that will vary for your configuration.

    Table 3-5 Required and Recommended Property Values

    Bean Property Value

    label1

    Text

    Account ID

    label2

    Text

    Balance

    JoltTextField1

    Name

    accountId

    JoltTextField1

    JoltFieldName

    ACCOUNT_ID

    JoltTextField2

    Name

    balance

    JoltTextField1

    JoltFieldName

    SBALANCE

    JoltSessionBean1

    AppAddress

    //tuxserv:2010

    JoltServiceBean1

    Name

    inquiry

    JoltServiceBean1

    ServiceName

    INQUIRY

    button1

    Label

    Inquiry

    Note: In this walkthrough, the default occurrenceIndex of 0 works for both JoltTextFields.

    Refer to Table 3-6 and the section, "Using the JoltBeans Repository and Setting the Property Values" for general guidelines on JoltBean properties.

    Figure 3-6 Example of JoltTextField Property List and Custom Property Editor

  3. To change the value of the JoltFieldName property, click on the ellipsis button of the JoltFieldName in the Property List. The Custom Property Editor displays. Select or type the new field name (in this example, "ACCOUNT_ID"). Select OK.

    Figure 3-7 Revised JoltFieldName in the JoltTextField Property List

    The change is reflected in the Property List shown in Figure 3-7 and on the button shown in Figure 3-8.

    Figure 3-8 Example of Applet Form Designer with Property Changes

    Figure 3-8 is an example of how the text on the Button changes after the label text is added to the Property List fields for these beans.

  4. After you set the properties to the right values (refer to Table 3-5 for additional information on the required and recommended property values), define how the beans will interact by wiring them together using the Visual Cafe´ Interaction Wizard similar to the windows shown in Figure 3-10 and Figure 3-11.

Wiring the JoltBeans Together

After all of the beans are positioned on your form and the properties are set, wire the events together. Save, compile, and run the applet. Figure 3-9 gives an example of the flow to help you determine the order when you are ready to wire the beans.

Wiring the beans allows you to establish event source-listener relationships between various beans of the form. For example, the JoltServiceBean is a listener of ActionEvents from the button and invokes callService() when the event is received. The development environment provides a tool (in this example, Visual Cafe´ Interaction Wizard) to wire beans together. In the absence of this tool, the event source-listener pairs are implemented manually.

For more information, refer to Figure 3-9 and the accompanying steps.

Figure 3-9 Example of How the Form Runs

Step 1: Wire the JoltSessionBean logon

  1. Select the Interaction Wizard button. Click in the applet window (not on another bean) and drag a line to the JoltSessionBean. The Interaction Wizard window similar to the example shown in Figure 3-10 displays.

    Figure 3-10 Visual Cafe´ Interaction Wizard (Window 1 of 2)

  2. Choose ComponentShown as event and select "Logon to the TUXEDO system" as method. Select Finish.

    Note: The results of completing these two steps will enable the logon() method of the JoltSessionBean to be triggered by an applet (e.g., ComponentShown) that is sent when the applet is opened for the first time.

Step 2: Wire JoltSessionBean to JoltServiceBean via propertyChange

  1. Select the Interaction Wizard button. Click on the JoltSessionBean and drag a line to the JoltServiceBean. The Interaction Wizard window similar to the example shown in Figure 3-10 displays.

  2. Choose propertyChange as event and select "Handle a property change event..." as the method. Select Next. The Interaction Wizard "How it should happen" window similar to the example shown Figure 3-11 displays.

    Figure 3-11 Visual Cafe´ Interaction Wizard (Window 2 of 2)

  3. Select "A variable or parameter" method. In this example, event is the default and the correct value. Select Finish.

    Note: The results of completing these three steps will enable the JoltSessionBean to send a propertyChange event when logon() completes. The JoltServiceBean listens to this event and associates its service with this session.

Step 3: Wire the accountID JoltTextField as input to the JoltServiceBean using JoltInputEvent

  1. Select the Interaction Wizard button. Select the accountID JoltTextField bean and drag a line to the JoltServiceBean. The Interaction Wizard window similar to the example shown in Figure 3-10 displays.

  2. Choose dataChanged as event and select "Handle a jolt input event" as method. Select Next. The Interaction Wizard "How it should happen" window similar to the example shown in Figure 3-11 displays.

  3. Select "A variable or parameter." Select Finish.

    Note: The results of completing these three steps will enable you to type the account number in the first text field. The JoltFieldName property of this JoltTextField is set to "ACCOUNT_ID". Whenever the text inside this text box changes, it sends a JoltInputEvent to the JoltServiceBean. (The JoltServiceBean listens to JoltInputEvents from this textbox.) The JoltInputEvent object contains the name, value, and occurrence index of the field.

Step 4: Wire Button to JoltServiceBean using JoltAction

  1. Select the Interaction Wizard button. Select the Inquiry Button and drag a line to the JoltServiceBean. The Interaction Wizard window similar to the example shown in Figure 3-10 displays.

  2. Choose Action as the event. Select "Invoke TUXEDO Service represented by this bean" as the method. Select Finish.

    Note: The results of completing these two steps will enable the callService() method of the JoltServiceBean to be triggered by an ActionEvent from the Inquiry button.

Step 5: Wire JoltServiceBean to the balance JoltTextField using JoltOutputEvent

  1. Select the Interaction Wizard button. Select the JoltServiceBean and drag a line to the AmountJoltTextField bean. The Interaction Wizard window similar to the example shown in Figure 3-10 displays.

  2. Choose serviceReturned as the event. Select "serviceReturned..." as the method. Press Next. The Interaction Wizard "How it should happen" similar to the example shown in Figure 3-11 displays.

  3. Select "A variable or parameter." Select Finish.

    Note: The results of completing these three steps of the JoltServiceBean sends a JoltOutputEvent when it receives reply data from the remote service. The JoltOutputEvent object contains methods to access fields in the output buffer. The JoltTextField displays the result of the INQUIRY service.

Step 6: Wire the JoltSessionBean logoff

  1. Select the Interaction Wizard button. Click in the applet window (not on another bean) and drag a line to the JoltSessionBean. The Interaction Wizard window similar to the example shown in Figure 3-10 displays.

  2. Choose componentHidden as event and select "Logoff from the TUXEDO system" as method. Select Finish.

    Note: The results of completing these two steps will enable the logoff() method of the JoltSessionBean to be triggered by an applet (e.g., componentHidden) that is sent when the applet gets hidden.

Step 7: Compile the applet

Upon completion of the wiring, compile your applet using your development software.

Fill in the empty catch blocks for exceptions. For example, you can add the following error handling code:

e.printStackTrace();

Check the message window for any compilation errors and exceptions.

Refer to Table 3-6 and Figure 3-12 for additional information.

Using the JoltBeans Repository and Setting the Property Values

Custom Property Editors are provided for the following properties:

The Property Editor, accessed from the Property List, includes dialog boxes that are used add or modify the properties. You can invoke the boxes from the Property List by selecting the button with the ellipsis "..." that is next to the value of the corresponding property value.

Some JoltBeans require input in the Property List field. The beans are listed in Table 3-6.

Table 3-6 JoltBean Specific Properties

JoltBean Property Input Description

JoltSessionBean

appAddress

userName, Password or AppPassword

e.g., //host:port

Type your TUXEDO user name and passwords.

JoltServiceBean

serviceName

isTransactional

e.g., INQUIRY

Set to true if the service needs to be executed within a transaction. Set isTransactional to false if the service does not require a transaction.

JoltUserEventBean

eventName

filter

Refer to the TUXEDO tpsubscribe calls.

all Jolt aware AWT beans

joltFieldName

occurrenceIndex

e.g., ACCOUNT_ID

Multiple fields of the same name. Index starts at 0.

JoltCheckbox

TrueValue and FalseValue

The field value corresponding to the state of the checkbox.

The property editor reads cached information from the repository and returns names of the available services and data elements in a list box. An example of the ServiceName property editor is shown in Figure 3-12:

Figure 3-12 JoltServiceBean Property Editor

  1. Select the service name by clicking on the ellipsis in the ServiceName field shown in Figure 3-12.

  2. The Custom Property Editor for ServiceName shown in Figure 3-13 displays.

    Figure 3-13 Custom Property Editor for serviceName

    Note: If you cannot or do not want to connect to the Repository database, simply type the service name in the text box and proceed to Step 7.

  3. If you are not logged on, select Logon. The JoltBeans Repository Logon shown in Figure 3-14 displays.

    Figure 3-14 JoltBeans Repository Log On

  4. Type the TUXEDO or Jolt Relay Machine name for Server and the JSL or Jolt Relay Port Number. Type passwords and user name information (if required) and select Logon.

  5. The Property Editor loads its cache from the repository.

    Figure 3-15 Property Editor with Selected Service

  6. Select the appropriate service name in the list box shown in Figure 3-15. Enter the property value (service or field name) directly. A text box is provided. Select OK on the property editor dialog in Figure 3-15. The bean property gets set with the contents of the textbox.

  7. Select OK on the Custom Property Editor dialog shown in Figure 3-15.

JoltBeans Programming Tasks

The additional procedures include:

Using Transactions with JoltBeans

Your TUXEDO application services may have functionality that will update your database. If so, you can use transactions with JoltBeans (e.g., in BANKAPP, the services TRANSFER and WITHDRAWAL update the database of BANKAPP). If your application service is read-only (e.g., INQUIRY), you do not need to use transactions.

The following example shows how to use transactions with JoltBeans.

  1. setTransactional (true) is called on the JoltServiceBean. (isTransactional is a boolean property of the JoltServiceBean.)

  2. beginTransaction() is called on the JoltSessionBean.

  3. callService() is called on the JoltServiceBean.

  4. Depending on the outcome of the service call, commitTransaction() or rollbackTransaction() is called on the JoltSessionBean.

Using Custom GUI Elements with the JoltService Bean

The JoltBeans product provide a limited set of GUI components that are Jolt enabled. It is also possible to use controls that are not Jolt enabled together with the JoltServiceBean. Figure 3-16 outlines the different ways to link controls that are not Jolt enabled with the JoltServiceBean. Three examples are presented. In Example 1, the GUI element displays output information of the service represented by the JoltServiceBean, in the Examples 2 and 3, the control contains input information.

In Example 1, the GUI element uses an adapter class that implements the JoltOutputListener interface to listen to JoltOutputEvents. The JoltServiceBean as the event source for JoltOutputEvents calls the serviceReturned() method of the adapter class when it sends a JoltOutputEvent. Inside serviceReturned(), the control's internal data is updated using information from the event object.

The development tool generates the adapter class when the JoltServiceBean and the GUI element are wired together.

In Example 2, the GUI element calls the setInputTextValue() method on the JoltServiceBean. In this example, the GUI element contains data which is input for the TUXEDO service represented by the JoltServiceBean.

In Example 3, the GUI element implements the required methods (addJoltInputListener and removeJoltInputListener) to act as an event source for JoltInputEvents. The JoltServiceBean acts as an event listener for these events. The control sends a JoltInputEvent once its own state changes to keep the JoltServiceBean updated with the input information.

Refer to Figure 3-16 for a graphical representation of using the GUI elements with the JoltServiceBean.

Figure 3-16 Example of Using Custom GUI Elements with the JoltServiceBean

Using TUXEDO Event Subscription and Notification with JoltBeans

TUXEDO supports brokered and unsolicited event notification. Jolt provides a mechanism for Jolt clients to receive TUXEDO events. JoltBeans also include this capability.

Note: TUXEDO event subscription and notification is different than JavaBeans events.

The following example shows how the TUXEDO asynchronous notification mechanism is used in JoltBeans applications.

  1. Use the setEventName() and setFilter() methods of the JoltUserEventBean to specify the TUXEDO event to which you want to subscribe.

  2. The component that wants to receive the event notifications registers itself as a JoltOutputListener to the JoltSessionBean.

  3. subscribe() is called on JoltUserEventBean.

  4. When the actual TUXEDO event notification arrives, JoltSessionBean sends a JoltOutputEvent to its listeners by calling serviceReturned() on them. The JoltOutputEvent object contains the data of the TUXEDO event.

When the client is not interested any more in the event it calls unsubscribe() on the JoltUserEventBean.

Note: If the client wants to only subscribe to unsolicited events, use setEventName ("\\.UNSOLMSG") that can be set using the property sheet. EventName and Filter are properties of the JoltUserEventBean.)