|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
UI Component | Gettor Protocols | Settor Protocols |
---|---|---|
Single/multiline labels and text fields |
public String get<attribute_name>()
|
public void set<attribute_name>(String text)
|
Radio buttons and checkboxes |
public boolean is<attribute_name>()
|
public void set<attribute_name>(boolean selected)
|
Button groups |
public String get<attribute_name>()
|
public void set<attribute_name>(String selected)
public void set<attribute_name>Immediate;(String selected)
|
Comboboxes |
public ChoiceDescriptor[] get<attribute_name>Choices()
public String get<attribute_name>()
public Object get<attribute_name>()
public AbstractDescriptor get<attribute_name>()
|
public void set<attribute_name>(String selected)
public void set<attribute_name>(Object selected)
Object .
See gettor protocols.
public void set<attribute_name>(AbstractDescriptor selected)
|
Sliders |
public int get<attribute_name>()
|
public void set<attribute_name>(int value)
|
Listboxes and table columns |
public ItemDescriptor[] get<attribute_name>List()
public String[] get<attribute_name>Selection()
public AbstractDescriptor[] get<attribute_name>Selection()
|
public void set<attribute_name>List(ItemDescriptor[] items)
public void set<attribute_name>Selection(String[] items)
public void set<attribute_name>Selection(AbstractDescriptor[] items)
|
Trees |
public NodeDescriptor[] get<attribute_name>Children()
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()
|
public void set<attribute_name>TreeParent(String parent)
public void set<attribute_name>Selection(AbstractDescriptor[] items)
|
Spin buttons |
public int get<attribute_name>()
public java.util.Calendar get<attribute_name>()
|
public void set<attribute_name>(int value)
public void set<attribute_name>(java.util.Calendar cal)
|
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
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.
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
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.
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.
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
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.
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.
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 |
public void load()
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.
public void verifyChanges()
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 DataBean
s associated
with a given panel. If an inconsistency is discovered the
DataBean
should throw an exception. This will
prevent the changes from being committed.
public void save()
public Capabilities getCapabilities()
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 HandlerTask
s, which the
UI framework is to perform. Typically these involve disabling
or removing certain UI components from a panel.
Capabilities
object which reflects this object's capabilitiesCapabilities
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |