Every instance of the List component is associated with an instance of the com.ibm.bpe.jsf.handler.BPCListHandler class.
This list handler tracks the selected items in the associated list and it provides a notification mechanism. The list handler is bound to the List component through the model attribute of the bpe:list tag.
The notification mechanism of the list handler is implemented using the com.ibm.bpe.jsf.handler.ItemListener interface. Business Process Choreographer Explorer uses this notification mechanism to associate the list entries with the details pages for the different kinds of items. The trigger for a notification event is typically one of the properties of the items that is displayed in the current list.
To exploit the notification mechanism, set the value of the action attribute of the bpe:column tag for the property to the JavaServer Faces (JSF) navigation target your application is to continue with when the notification event is triggered. The List component renders the entry in the column as a JSF command link. If the link is triggered, the object that represents the entry in the list is determined, and it is passed to all of the registered item listeners. You can register implementations of this interface in the configuration file of your JSF application.
The BPCListHandler class also provides a refreshList method. You can use this method in JSF method bindings to implement a user interface control for running the query again.
You can use the list handler to display all kinds of objects and their properties. The content of the list that is displayed depends on the list of objects that is returned by the implementation of the com.ibm.bpc.clientcore.Query interface that is configured for the list handler. You can set the query either programmatically using the setQuery method of the BPCListHandler class, or you can configure it in the JSF configuration files of the application.
You can run queries not only against the Business Process Choreographer APIs, but also against any other source of information that is accessible from your application, for example, a content management system or a database. The only requirement is that the result of the query is returned as a java.util.List of objects by the execute method.
The type of the objects returned must guarantee that the appropriate getter methods are available for all of the properties that are displayed in the columns of the list for which the query is defined. To ensure that the type of the object that is returned fits the list definitions, you can set the value of the type property on the BPCListHandler instance that is defined in the faces configuration file to the fully qualified class name of the returned objects. You can return this name in the getType call of the query implementation. At run time, the list handler checks that the object types conform to the definitions.
To map error messages to specific entries in a list, the objects returned by the query must implement a method with the signature public Object getID().
If an error occurs during the execution of a query, the BPCListHandler class distinguishes between errors that were caused by insufficient access rights and other exceptions. To catch errors due to insufficient access rights, the rootCause parameter of the ClientException that is thrown by the execute method of the query must be a com.ibm.bpe.api.EngineNotAuthorizedException or a com.ibm.task.api.NotAuthorizedException exception. The List component displays the error message instead of the result of the query.
If the error is not caused by insufficient access rights, the BPCListHandler class passes the exception object to the implementation of the com.ibm.bpc.clientcore.util.ErrorBean interface that is defined by the BPCError key in your JSF application configuration file. When the exception is set, the error navigation target is called.
The BPCListHandler class implements the com.ibm.bpe.jsf.handler.ErrorHandler interface. You can provide information about these errors with the map parameter of type java.util.Map in the setErrors method. This map contains identifiers as keys and the exceptions as values. The identifiers must be the values returned by the getID method of the object that caused the error. If the map is set and any of the IDs match any of the items displayed in the list, the list handler automatically adds a column containing the error message to the list.
(c) Copyright IBM Corporation 2005, 2006.
This information center is powered by Eclipse technology (http://www.eclipse.org)