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:
The JoltBeans toolkit includes the following beans:
What Is the JoltBeans Toolkit?
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.
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 The JoltSessionBean provides methods to control transactions, including beginTransaction(), commitTransaction(), and rollbackTransaction().
Table 3-1 shows the JoltSessionBean properties and descriptions.
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.
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.
The Jolt aware AWT Beans are inherited from the JDK 1.1 Abstract Windowing Toolkit. They include:
JoltSessionBean
true
. After the logoff is successful and the session is closed, the LoggedOn property is set to false
.
JoltServiceBean
JoltUserEventBean
Jolt Aware AWT Beans
Note:
Refer to Chapter 5, "Jolt Aware AWT Beans Class Library Reference," for more information.
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:
JoltTextField
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.
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:
JoltLabel
JoltList
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 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.
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.
When the ellipsis button is selected, the Property Editor shown in Figure 3-2 displays.
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."
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.
Refer to Figure 3-5 for an example of each item. To begin, select the following items shown in Table 3-4.
The following example is created using the Visual Cafe´ 2.5 development environment. Follow the steps to build a sample form.
JoltCheckbox
TrueValue
property of data type String (if the box is selected) or FalseValue
(if the box is unselected).
JoltChoice
Using the Property List and the Property Editor to Modify the JoltBeans Properties
Figure 3-1 Example of the Property List and Ellipsis Button
Figure 3-2 Property Editor Dialog Box
.
JoltBeans Class Library Walkthrough
Figure 3-3 Sample Inquiry Applet
Building the Sample Form
Figure 3-4 shows how a JoltBean is selected and painted to the palette of the Visual Cafe´ development environment.
Figure 3-5 shows how the JoltBeans appear in a development environment when the placement of the beans is completed.
Figure 3-4 JoltBeans and the Form Designer in Visual Cafe´
Figure 3-5 Java Applet Form Designer
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.
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
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 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.
Figure 3-7 Revised JoltFieldName in the JoltTextField Property List
Figure 3-8 Example of Applet Form Designer with Property Changes
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
Figure 3-10 Visual Cafe´ Interaction Wizard (Window 1 of 2)
Figure 3-11 Visual Cafe´ Interaction Wizard (Window 2 of 2)
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.
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.
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
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.
Figure 3-13 Custom Property Editor for serviceName
Figure 3-14 JoltBeans Repository Log On
Figure 3-15 Property Editor with Selected Service
The additional procedures include:
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.
Using Transactions with JoltBeans
setTransactional
(true) is called on the JoltServiceBean. (isTransactional is a
boolean property of the JoltServiceBean.)
beginTransaction()
is called on the JoltSessionBean.
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
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.
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.)