com.ibm.as400.ui.framework.java
Interface DataBean

All Known Implementing Classes:
AS400JDBCDataSourcePaneDataBean

public interface DataBean

The interface which defines a data object that is capable of supplying data to a panel managed by the PDML runtime framework. A DataBean is a true Java bean, because in addition to the methods defined on the interface, an application's DataBean implementation is responsible for providing get and set accessor methods for each property whose data is displayed on a PDML panel. A UI component on a panel is associated with a property on a specific DataBean when the panel is created, using the GUI Builder or Resource Script Converter tools.

Gettors and Settors

Method protocols for the accessor methods vary according to the type of UI component for which data is supplied. Below are accessor method specifications for each UI component that PDML supports. Bear in mind that the correct method protocols are automatically generated by the GUI Builder and Resource Script Converter tools when you request DataBean generation. Certain optional methods that have specfic behaviors can be implemented but require hand editing. Warning: the data types of a corresponding gettor and settor pair must match.

UI Component Gettor Protocols Settor Protocols
Single/multiline labels and text fields
public String
 get<attribute_name>()
Returns:
The string to be inserted into the label or text field.
public void
 set<attribute_name>(String text)
Parameters:
text - The string currently in the text field.
This settor is not required for labels, which are read-only.
Radio buttons and checkboxes
public boolean
 is<attribute_name>()
Returns:
true if the radio button/checkbox should be selected; false otherwise.
public void
 set<attribute_name>(boolean selected)
Parameters:
selected - true if the radio button/checkbox is currently selected; false otherwise.
Button groups
public String
 get<attribute_name>()
Returns:
The identifier of the button component that should be selected.
public void
 set<attribute_name>(String selected)
Parameters:
selected - The identifier of the button component that is currently selected.
public void
 set<attribute_name>Immediate;(String selected)
Parameters:
selected - The identifier of the button component that is currently selected.
This settor is called whenever the selection changes in the ButtonGroup
Comboboxes
public ChoiceDescriptor[]
 get<attribute_name>Choices()
Returns:
An array of ChoiceDescriptors, each of which describes a choice in the combobox's dropdown list.
This gettor is only required if the choices cannot be statically defined in the PDML.
public String
 get<attribute_name>()
Returns:
The identifier of the choice that should be selected, or the string to be inserted if the combobox is editable.
public Object
 get<attribute_name>()
Returns:
The ChoiceDescriptor for the choice that should be selected, or an object of the appropriate type based on the format specified for the combobox. For example, the gettor should return an instance of Double for Percent format, an instance of Calendar for Date and Time formats, etc. If no format is specified a String should be returned.
This gettor is now supported by the PDML framework (it is not generated by the tools). See settor protocols.
public AbstractDescriptor
 get<attribute_name>()
Returns:
The AbstractDescriptor for the choice that should be selected. This method should only be used with settor of corresponding type.
This gettor is now supported by the PDML framework (it is not generated by the tools). See settor protocols.
public void
 set<attribute_name>(String selected)
Parameters:
selected - The identifier of the choice that is currently selected, or the string currently in the edit field if the combobox is editable.
public void
 set<attribute_name>(Object selected)
Parameters:
selected - The ChoiceDescriptor for the choice that is currently selected, or an object of the appropriate type based on the format specified for the combobox. For example, an instance of Double will be passed for Percent format, an instance of Calendar for Date and Time formats, etc. If no format is specified a String object will be passed.
This settor is now supported by the PDML framework (it is not generated by the tools). To activate this settor the corresponding gettor must return an Object. See gettor protocols.
public void
 set<attribute_name>(AbstractDescriptor selected)
Parameters:
selected - The AbstractDescriptor for the choice that is currently selected.
This method requires the public AbstractDescriptor[] get<attribute_name>() is implemented This method will be called whenever the selected item in the combobox changes.
Sliders
public int
 get<attribute_name>()
Returns:
The integer value to which the slider should be set.
public void
 set<attribute_name>(int value)
Parameters:
value - The integer value to which the slider is currently set.
Listboxes and table columns
public ItemDescriptor[]
 get<attribute_name>List()
Returns:
An array of ItemDescriptors, each of which describes an item in the list or table column.
This gettor is only required if the items cannot be statically defined in the PDML.
public String[]
 get<attribute_name>Selection()
Returns:
An array of identifiers which specify which list/table items should be selected.
This gettor is optional; if not implemented, no items will be selected when the list or table is displayed. For tables, this gettor is only called for the "primary" column as specified in the PDML.
public AbstractDescriptor[]
 get<attribute_name>Selection()
Returns:
An array of identifiers which specify which list/table items should be selected.
This gettor is optional; if not implemented, no items will be selected when the list or table is displayed. For tables, this gettor is only called for the "primary" column as specified in the PDML. This method is required if the set<attribute_name>Selection(AbstractDescriptor[] ads) is used.
public void
 set<attribute_name>List(ItemDescriptor[] items)
Parameters:
items - An array of ItemDescriptors, each of which describes an item currently in the list or table column.
This settor is only required if the user can add and remove items from the list or table.
public void
 set<attribute_name>Selection(String[] items)
Parameters:
items - An array of identifiers which specify the list/table items currently selected.
This settor is only required if the selection gettor is implemented. For tables, this settor is only called for the "primary" column as specified in the PDML.
public void
 set<attribute_name>Selection(AbstractDescriptor[] items)
Parameters:
items - An array of AbstractDescriptors that are in the list/table column.
This settor requires the selection gettor that returns an AbstractDescriptor[] is implemented. This settor will be called whenever the selection changes. For tables, this settor is only called for the "primary" column as specified in the PDML.
Trees
public NodeDescriptor[]
 get<attribute_name>Children()
Returns:
An array of NodeDescriptors, each of which describes a child element in the tree.
This gettor is only required if the items cannot be statically defined in the PDML.

Calls to this method are always preceded by a call to the settor method, which identifies for which parent node child elements are to be supplied.

Calls to this method are always preceded by a call to the settor method, which identifies for which parent node child elements are to be supplied.

public AbstractDescriptor[]
 get<attribute_name>Selection()
Returns:
An array of AbstractDescriptors, each of which is a node in the tree.
This gettor is only required if an initial selection is desired.
public void
 set<attribute_name>TreeParent(String parent)
Parameters:
parent - The name of the parent node for which children should be supplied when the gettor method is called.
91
This settor is only required if the items cannot be statically defined in the PDML.

public void
 set<attribute_name>Selection(AbstractDescriptor[] items)
Parameters:
items - An array of AbstractDescriptors that are nodes in the tree.
This settor requires the selection gettor that returns an AbstractDescriptor[] is implemented. This settor is called whenever the selection in the tree changes.
Spin buttons
public int
 get<attribute_name>()
Returns:
The integer value to be displayed in the spin button.
This gettor is used if the spin button is specified as having Integer format.
public java.util.Calendar
 get<attribute_name>()
Returns:
A Calendar containing the date/time to be displayed in the spin button.
This gettor is used if the spin button is specified as having either Date or Time format.
public void
 set<attribute_name>(int value)
Parameters:
value - The integer value currently in the spin button.
This settor is used if the spin button is specified as having Integer format.
public void
 set<attribute_name>(java.util.Calendar cal)
Parameters:
cal - A Calendar containing the date/time currently displayed in the spin button.
This settor is used if the spin button is specified as having either Date or Time format.

Functional Flow for Single Panels

Initial Panel Display

In the simplest case, an application defines a stand-alone window or dialog, whose data is supplied by a single instance of a DataBean implementation. The interaction between the application, the DataBean and the associated PanelManager object is shown in Figure 1 and described below. (See the PanelManager class description for sample code that displays a panel.)

Figure 1: Flowchart of initial panel display
Flowchart of initial panel display

In the diagram, aClient is an instance of an application class that will display the panel. It begins by instantiating the DataBean implementation and calling its load method. This method is defined on the DataBean interface to provide the implementation an opportunity to perform any long-running operations required to retrieve the data for the panel. It is never called by the PDML framework.

The client code then passes the newly initialized DataBean to the PanelManager object as a parameter on its constructor. During initialization of the panel, the PanelManager object calls the getCapabilities method on the DataBean to learn whether there are any properties that aren't available due to potential runtime constraints. For example, the DataBean may have determined that its data source doesn't support certain properties because the data source is running a back-level version of software.

Finally, the client calls setVisible on PanelManager to display the panel to the user. Before displaying the panel, the PanelManager object calls each gettor method on the DataBean to obtain the data to be displayed. The order in which the gettors are called is defined by the tabbing order of UI components on the panel.

Committing Changes

The next data interaction which normally occurs between the PanelManager object and the DataBean occurs when the user clicks the OK button on the panel. The interaction of committing changes is shown in Figure 2 and described below.

Figure 2: Flowchart of committing changes
Flowchart of committing changes

The PDML framework first attempts to validate the data for each UI component that contains data managed by the DataBean. For example, a text field on the panel may have been defined as requiring a string of a certain minimum length. If the string entered by the user is not long enough, the framework will display a message box explaining the error, and then return focus to the text field to allow the user to correct the problem. The GUI Builder lets application developers choose from a list of predefined formats that may be enforced by the framework, or the application may specify its own formatter class for performing custom validation. See the DataFormatter class description for more information.

Once all of the data fields have been successfully validated, the PanelManager object calls each settor method on the DataBean to transmit the changed user data. Once again, the order in which the settors are called is defined by the tabbing order of UI components on the panel. Settor methods may often perform additional application-defined data validation. If the data entered by the user is deemed invalid, the settor method should throw an IllegalUserDataException. The exception message should be in a form suitable for displaying to the user. The framework will display the exception message in a message box, and automatically return focus to the appropriate UI component to allow the user to correct the error.

Once all of the settor methods have run successfully, the PanelManager object calls the verifyChanges method. This allows the DataBean one final opportunity to verify that all changed user data is logically consistent. As before, if any of the data is found to be in error verifyChanges should throw an IllegalUserDataException.

Finally, the PanelManager object calls the save method to inform the DataBean that all user-supplied changes should be committed to the data source. The PanelManager object will close the panel immediately on return from the save method. An IllegalUserDataException may be thrown to display a message and stop the panel from closing.

Custom Data Transfers

The application may specifically request a transfer of data between the PanelManager and the DataBean at any time after the panel has been made visible. See the methods refreshComponent, loadData and applyChanges in the PanelManager class description.

Processing Multiple Data Beans

A developer may choose to structure an application such that the data displayed on a panel is sourced from more than one DataBean implementation. In this scenario the application supplies an array of DataBeans on the PanelManager constructor. Commit processing follows the flow shown in Figure 3 and described below.

Figure 3: Flowchart of processing multiple data beans
Flowchart of processing multiple data beans

The processing for validation and the calling of settor methods is similar to the single DataBean case. The only difference is that the settor method for a particular UI component may implemented on any one of the DataBean objects.

Once all of the settor methods have run successfully, the calls to verifyChanges and save are made to each DataBean in the order in which the DataBean objects were passed to the PanelManager object on its constructor. In this scenario any given implementation of verifyChanges may choose to access data from other DataBeans to verify that the changed user data is logically consistent. Exceptions thrown by the DataBean are handled the same as in the single DataBean case.

Functional Flow for Property Sheets and Wizards

Property sheets and wizards are collections of graphical panels, each one managed by an instance of the PanelManager class. In general, the processing described above for single panels is repeated for each constituent panel in the collection. (The preceding also holds for the nested subpanes - split panes, deck panes and tabbed panes.)

On initial display of a property sheet or wizard, the PropertySheetManager or WizardManager object calls only the gettor methods for data on the panel which is initially visible. Calls to gettors for other panels in the collection are called as needed when the panels are made visible in response to an appropriate user action.

For property sheets, commit processing occurs for each panel when the user clicks the OK button. The panels are processed in the order in which they appear in the property sheet.

For wizards, field validation and calls to settor methods occur when the user clicks the NEXT button to move to the next panel. Exceptions thrown by settor methods cause the current wizard page to be re-displayed, so that focus may be returned to the field containing the invalid data. The calls to verifyChanges and save are performed when the user reaches the last wizard panel and clicks the FINISH button. Once again, panels are processed in the order in which they appeared in the wizard.

Since:
v4r2m0
See Also:
Capabilities

Method Summary
 Capabilities getCapabilities()
          Returns a Capabilities object which identifies the attributes that aren't supported by this DataBean.
 void load()
          Initializes this object.
 void save()
          Saves all changes that have been applied to this object via its accessor methods.
 void verifyChanges()
          Validates any changes that have been applied to this object via its accessor methods.
 

Method Detail

load

public void load()
Initializes this object.

This method should be called prior to handing the DataBean off to the UI Framework. On return from this method the bean should be in a state where it is ready to return data on any of its accessor methods.

Since:
v4r2m0

verifyChanges

public void verifyChanges()
Validates any changes that have been applied to this object via its accessor methods.

This method is called just prior to save to give the receiver an opportunity to verify that its data is consistent with any changes made to other DataBeans associated with a given panel. If an inconsistency is discovered the DataBean should throw an exception. This will prevent the changes from being committed.

Since:
v4r2m0

save

public void save()
Saves all changes that have been applied to this object via its accessor methods. Called when the user has clicked the OK button on a panel.
Since:
v4r2m0

getCapabilities

public Capabilities getCapabilities()
Returns a Capabilities object which identifies the attributes that aren't supported by this DataBean. There are many reasons why a DataBean might not support a given attribute. For example:

The Capabilities object may provide a list of instructions, or HandlerTasks, which the UI framework is to perform. Typically these involve disabling or removing certain UI components from a panel.

Returns:
a Capabilities object which reflects this object's capabilities
Since:
v4r2m0
See Also:
Capabilities