CommandBar component

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.
  1. The CommandBar component identifies the implementation of the com.ibm.bpc.clientcore.Command interface that is specified for the button that generated the event.
  2. 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.
  3. 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.
  4. 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.

Terms of use |

Last updated: Tue Feb 21 17:31:25 2006

(c) Copyright IBM Corporation 2005.
This information center is powered by Eclipse technology (http://www.eclipse.org)