Use the CommandBar component to add action buttons
to your application. The component creates the buttons for the actions in
the user interface and handles the events that are created when a button is
clicked.
These buttons trigger functions that act on the objects that are returned
by a com.ibm.bpe.jsf.handler.ItemProvider interface, such
as the BPCListHandler class, or the BPCDetailsHandler class.
The CommandBar component uses the item provider that is
defined by the value of the model attribute in the bpe:commandbar tag.
How commands are processed
When a button in the
command-bar section of the application's user interface is clicked, the associated
event is handled by the
CommandBar component in the following
way.
- The CommandBar component identifies the implementation
of the com.ibm.bpc.clientcore.Command interface that is
specified for the button that generated the event.
- If the model associated with the CommandBar component
implements the com.ibm.bpe.jsf.handler.ErrorHandler interface,
the clearErrorMap method is invoked to remove error messages
from previous events.
- The getSelectedItems method of the ItemProvider interface
is called. The list of items that is returned is passed to the execute method
of the command, and the command is invoked.
- The CommandBar component determines the JavaServer
Faces (JSF) navigation target. If an action attribute
is not specified in the bpe:commandbar tag, the return value
of the execute method specifies the navigation target.
If the action attribute is set to a JSF method binding,
the string returned by the method is interpreted as the navigation target.
The action attribute can also specify an explicit navigation
target.
Error handling
An action method
that is specified by the
action attribute in the
bpe:commandbar tag
is invoked if one of the following conditions are met:
- An exception is not thrown
- If an exception is thrown, it is an ErrorsInCommandException exception
You can implement error handling in the
CommandBar component
in several ways:
- You can decide not to use any of the features of the CommandBar component.
If, for example, you want to display the errors on a page that is specific
to the selected command, the implementation of the command can catch the exceptions
that occur and propagate them to a page bean that is used for the error page.
You can make the page bean available to the command implementation by using
the context attribute of the bpe:commandbar tag.
After the exception is set on the page bean, the command returns the string
of the JSF navigation rule that is defined for the error page.
- If you want to display an error message below the command-bar section
in the user interface, create an exception class that implements the com.ibm.bpc.clientcore.exception.CommandBarMessage marker
interface. This interface provides a message catalog of error messages.
- If the command operates on a list of items, you might want to track the
success of the command for each of the items in the list. To track the errors,
map each exception to the item for which the operation failed. The CommandBar component
can pass a map, which contains the identifiers as keys and the exceptions
as values, to the model object that is defined for the CommandBar component.
For
this mechanism to work, the model object must implement the com.ibm.bpe.jsf.handler.ErrorHandler interface
and the command must throw a com.ibm.bpc.clientcore.exception.ErrorsInCommandException exception.
The CommandBar component then passes the map contained
in the exception to the error handler. The action method is triggered although
an error occurred, and the current view is refreshed. The Business Process
Choreographer Explorer application makes use of this method to display exceptions
in lists.
- If you throw a ClientException exception that does
not implement the CommandBarMessage interface and the exception
is not an ErrorsInCommandException, the CommandBar component
propagates the exception to the BPCError error bean that
is defined in the configuration file of your application. The error processing
continues with the error page.