Use the CommandBar component to integrate action buttons in 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
A command is triggered only if one
of the following conditions are true:
- An exception is not thrown
- If an exception is thrown, it is an ErrorsInCommandException exception
There are several ways in which you can implement error handling
in the CommandBar component:
- 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 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 navigation target.