oracle.ide.panels
Interface Traversable

All Known Subinterfaces:

NavigableUIContainer

All Known Implementing Classes:

AbstractUIContainer, DefaultTraversablePanel

public interface Traversable

The methods defined in the Traversable interface specify the operations that a UI component must support in order to be traversed in complex UI widgets such as a property dialog, a wizard, or any other panel-based UI.

Property dialogs and wizards typically involve some set of panels that are displayed to the user. In the case of property dialogs, the user can traverse the panels in a random-access manner; in wizards, the user traverses the panels in a sequential order. Often, the data structures being edited by the panels do not necessarily correspond to the structure of the panels. That is, a single panel may edit multiple data objects, or multiple panels may edit a single data object. Moreover, values displayed in one panel may also be affected by edits performed in another panel.

The Traversable interface specifies the protocol through which panels can communicate indirectly with each other. The onEntry(TraversableContext) and onExit(TraversableContext) methods comprise the main part of the interaction. The getExitTransition() method is currently reserved for use by wizards, and implementations should just return null from this method for the time being.

The Traversable implementation finds the data objects that it needs by querying the TraversableContext. The TraversableContext uses a Namespace to hold data objects. Therefore the Traversable must be able to find its data objects using predefined names. Consequently, the names and data types of the required data objects must be documented by every Traversable implementation. It is then the responsibility of the UI container and the class instantiating the UI container to ensure that the Namespace is populated with the appropriate data objects before entering the Traversable. These are the essential details of the interaction of the Traversable with its UI container and other Traversables.

The Traversable interface is intentionally designed to allow a single panel to be used in both a property dialog and a wizard. Generally, a property dialog is used to edit the properties of an existing object, and a wizard is used to guide the user through the creation of a new object. In some cases, the property dialog and the wizard are essentially identical and may even use the same panels; in other cases, the wizard only displays the most commonly edited properties and leaves the more advanced editing to be performed in the property dialog. Panels that implement the Traversable interface are available to be reused in either a property dialog or a wizard, provided that the data objects are properly loaded into the Namespace used by the TraversableContext.

In order for such reuse to occur in practice, there must be a property dialog and wizard implementation available that manages panel interactions through the Traversable interface. For a property dialog, see MDDPanel. A wizard implementation is not yet available, but there is a prototype wizard in the JDeveloper deployment framework that uses a finite-state-machine representation to drive the dynamic ordering of wizard panels. At some point, that code will be updated to use the Traversable interface and be made available in a subpackage of this package. (jdijamco -- March 5, 2001)

See Also:

MDDPanel

Method Summary

java.awt.Component	getComponent() Normally, the Traversable class will itself be the UI Component.
java.lang.Object	getExitTransition() Returns the exit transition that can be used by a Traversable-aware wizard.
void	onEntry(TraversableContext dataContext) This method is called when the Traversable is being entered.
void	onExit(TraversableContext dataContext) This method is called when the Traversable is being exited.

Method Detail

onEntry

public void onEntry(TraversableContext dataContext)

This method is called when the Traversable is being entered. The data that the Traversable should use to populate its UI components comes from the specified TraversableContext.

When the same Traversable is entered more than once in the course of interacting with the user, the Traversable needs to reload the data directly from the TraversableContext rather than caching data objects. Some reasons for this include:

• Other Traversables may edit the data objects or even replace them.
• The same Traversable instance may be used for editing multiple different instances of the same object type.

Loading data directly from the TraversableContext is the best way to ensure that the Traversable will not be editing the wrong data.

The Traversable should not even cache references to data objects between invocations of onEntry and onExit(TraversableContext) because the UI container is not required to guarantee that the references will be identical.

Parameters:

dataContext - The data wrapper where the Traversable locates the data that it needs to populate the UI.

getComponent

public java.awt.Component getComponent()

Normally, the Traversable class will itself be the UI Component. Therefore, getComponent() typically just returns this. In this situation the getComponent() method then is simply a means of avoiding a type cast.

In other cases, it would be useful to have the ability to return a different Component based on the contents of the TraversableContext that is passed to the onEntry(TraversableContext) method. UI containers (e.g. property dialogs and wizards) that are designed to use the Traversable interface must call the onEntry(TraversableContext) method before calling getComponent(). This allows a Traversable implementation to have the opportunity to configure the UI Component or even create a new one before it is displayed.

In either situation, the implementation should strive to return the same Component instance as often as possible rather than creating a new instance becaues the UI container will call this method frequently.

Returns:

The UI Component that the user interacts with for creating or editing an object.

onExit

public void onExit(TraversableContext dataContext)
            throws TraversalException

This method is called when the Traversable is being exited. At this point, the Traversable should copy the data from its associated UI back into the data structures in the TraversableContext.

If the Traversable should not be exited because the user has entered either incomplete, invalid, or inconsistent data, then this method can throw a TraversalException to indicate to the property dialog or wizard that validation failed and that the user should not be allowed to exit the current Traversable. Refer to the TraversalException javadoc for details on passing the error message that should be shown to the user.

Parameters:

dataContext - The data object where changes made in the UI should be copied so that the changes can be accessed by other Traversables.

Throws:

TraversalException - if the user has entered either incomplete, invalid, or inconsistent data. This exception prevents the property dialog or wizard from continuing and forces the user to stay on the current Traversable until the data entered is valid or the user cancels. The exception class itself is capable of carrying an error message that will be shown to the user. Refer to its javadoc for details.

getExitTransition

public java.lang.Object getExitTransition()

Returns the exit transition that can be used by a Traversable-aware wizard. The wizard can use the exit transition to direct the user through an alternate or streamlined set of panels based on their current input.

If the Traversable implementation does not support multiple exit transitions, then this method should just return null.

Returns:

The exit transition for the Traversable that is used by dynamic interview-style wizards to determine the next course of action. A Traversable class that does not support multiple possible transitions should just return null.