Code review

This section shows how the Business Process Choreographer Explorer (BPC Explorer) components are used in your Java Server Faces (JSF) application.

Using BPC Explorer components

BPC Explorer delivers a set of pre-defined JSF components covering all areas of the BPC API. These components are the main building blocks of your application. Using these components, you can create command-bars, list items, and display details or messages. This chapter gives an overview on how to use the BPC Explorer components in your JSPs. A more detailed discussion about the components list, command-bar, details, and message are provided in the next sections. It is explained how these components can be customized and extended to fit your specific requirements.

Add components to your JSP

Figure 1 outlines how you can use BPC Explorer components in your Java Server Pages (JSP). If you add a component to your JSP, you have to specify its properties in the JSF configuration file. In the most cases you can use the pre-defined JSF components. If you need a more specific solution, you will use other JSF components together with your own managed beans using the interfaces provided by the BPC Explorer API.

Figure 1: Using BPC Explorer components

To use JSF and BPC Explorer components, you have to add the required tag libraries to your JSP. The following codes snippet shows the basic skeleton of a JSP using JSF and BPC Explorer components:

Add the BPC Explorer components within the <h:form> element. The following code snippet shows the definition of the BPC Explorer list component:

<bpe:list model="#{ProcessTemplateListHandler}" checkbox="false">
<bpe:column action="ProcessStartForm" name="displayName" label="Name" />
<bpe:column name="description" label="Description" />
</bpe:list>

The type of items to be listed is specified indirectly by the list handler, which is also responsible for providing the items. The list handler is specified using the model attribute, which refers to a definition in the JSF configuration file. This definition is explained in the next section. The nested elements of the <bpe:list> specify which attributes of the items are displayed in the list. There is one attribute 'displayName' and another 'description'. The column headers are defined using the 'label' attribute, in this case 'Name' and 'Description'. For the first element an action is defined that appears as clickable link in the GUI. The action is specified in the faces-config.xml file as JSF navigation target.

To customize the look and feel, add CSS styles to your components:

<bpe:list model="#{ProcessTemplateListHandler}"
          styleClass="list"
          headerStyleClass="template-headers"
          buttonStyleClass="list-buttons"
          checkbox="false">

To see the complete source code of this JSP, click this link: ProcessTemplateList.jsp

Customize your faces-config.xml file

When you use BPC Explorer components in your JSPs, you have to customize your JSF configuration file accordingly. The list component outlined in the previous section refers to a list handler, which is a managed bean in terms of JSF. Managed beans have to be specified in the JSF configuration file, which per default is named faces-config.xml. The following code snippet shows the definition of the list handler:

<managed-bean>
  <managed-bean-name>ProcessTemplateListHandler</managed-bean-name>
  <managed-bean-class>com.ibm.bpe.jsf.handler.BPCListHandler</managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>

  <managed-property>
    <property-name>query</property-name>
    <value>#{ProcessTemplateQuery}</value>
  </managed-property>

   <managed-property>
    <property-name>type</property-name>
    <value>com.ibm.bpe.api.ProcessTemplateData</value>
  </managed-property>

  <managed-property>
    <property-name>itemListener</property-name>
    <list-entries>
      <value-class>com.ibm.bpe.jsf.handler.ItemListener</value-class>
      <value>#{ProcessInstanceStartHandler}</value>
    </list-entries>
  </managed-property>

</managed-bean>

This list handler specifies the bean name, the implementation class, com.ibm.bpe.jsf.handler.BPCListHandler, and several managed properties. The query property refers to another managed bean, representing a query against the BPC API, which retrieves process templates. The type property defines the type of the listed items, in this case com.ibm.api.ProcessTemplateData. The item listener property lists the registered item listeners. In this case the item listener refers to a managed bean, which is called when an item in the list is clicked.

To see the complete source code of the faces configuration file, click this link: faces-config.xml.

Use custom beans and queries

There are two ways to customize queries against the BPC API: adjusting the query parameters and writing your own query objects. Adjusting query parameters makes a standard query more selective, for example, by adding a where clause. This approach does not modify the item type returned by the query. If you want to modify the returned items, e.g. by adding properties, you will have to write your own query class that is capable of returning your custom items.

The following code snippet shows a standard query with a custom where clause, as defined in the JSF configuration file (see list handler from the previous chapter):

<managed-bean-name>ProcessTemplateQuery</managed-bean-name>
  <managed-bean-class>bpc.samples.query.CustomProcessTemplateQuery</managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>

  <managed-property>
    <property-name>whereClause</property-name>
    <value>PROCESS_TEMPLATE.VALID_FROM < TS('2999-12-31')</value>
  </managed-property>

<managed-property>
<property-name>type</property-name>
<value>com.ibm.bpe.api.ProcessTemplateData</value>
</managed-property>

  ...

</managed-bean>

To write a custom query, you can subclass the com.ibm.bpc.clientcore.GenericBPCQuery class and implement the abstract method execute(). To see the implementation of the custom process template query, click this link: CustomProcessTemplateQuery.java.

List component

To use the BPC Explorer list component, you have to specify the underlying model. The model refers to a managed bean, which in turn specifies the kind of items in the list, the query to retrieve these items and, optionally, an item listener, which is called when an item is selected. Figure 2 outlines, how to use the BPC Explorer list component.

Figure 2: Explorer list component

The following code snippet shows the list component of the ProcessInstanceList.jsp:

<bpe:list model="#{ProcessInstanceListHandler}"
          styleClass="list"
          headerStyleClass="template-headers"
          buttonStyleClass="list-buttons"
          checkbox="false">

   <bpe:column name="name" label="Name" action="ProcessInstanceDetails"/>
   <bpe:column name="orderNo" label="Order No."/>
   <bpe:column name="department" label="Department"/>
   <bpe:column name="executionState" converterID="ProcessStateConverter" label="Status"/>
   <bpe:column name="startTime" label="Started" converterID="CalendarConverter"/>
</bpe:list>

In the list component, you can specify converters for columns. Converters transform cryptic values into a user-friendly representation. In this list component, converters are specified for the columns 'executionState' and 'startTime'. Converters have to be defined in the JSF configuration file:

<converter>
  <converter-id>ProcessStateConverter</converter-id>
  <converter-class>bpc.samples.converter.ProcessStateConverter</converter-class>
</converter>

<converter>
  <converter-id>CalendarConverter</converter-id>
  <converter-class>bpc.samples.converter.CalendarConverter</converter-class>
</converter>

The list handler, to which the model attribute of the list element refers, is defined in the JSF configuration file:

<managed-bean>
  <managed-bean-name>ProcessInstanceListHandler</managed-bean-name>
  <managed-bean-class>com.ibm.bpe.jsf.handler.BPCListHandler</managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>

  <managed-property>
    <property-name>query</property-name>
    <value>#{ProcessInstanceQuery}</value>
  </managed-property>

  <managed-property>
    <property-name>type</property-name>
    <value>bpc.samples.bean.CustomProcessInstanceBean</value>
  </managed-property>

  <managed-property>
    <property-name>itemListener</property-name>
    <list-entries>
      <value-class>com.ibm.bpe.jsf.handler.ItemListener</value-class>
      <value>#{ProcessInstanceDetailsHandler}</value>
    </list-entries>
    </managed-property>

</managed-bean>

To specify the type of the items in the list, you add the managed property 'type' to your list handler bean. In the code sample, the type refers to a Java class, which extends the process instance bean provided by the BPC Explorer client model. This custom bean offers two additional fields, 'department' and 'orderNo', which are stored as custom properties of the process instance. The items of the list are determined by a query, which is another managed property of the list handler. This query refers to a second managed bean, which is shown later in this section. Finally, there is a list of item listeners (here with a single element) defined for the list handler. This item listener refers to another managed bean in the JSF configuration file. The following code snippet shows the definition of the query managed bean and the associated connection managed bean:

<managed-bean>
  <managed-bean-name>ProcessInstanceQuery</managed-bean-name>
  <managed-bean-class>bpc.samples.query.CustomProcessInstanceQuery</managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>

  <managed-property>
    <property-name>selectClause</property-name>
    <value>DISTINCT PROCESS_INSTANCE.PTID, PROCESS_INSTANCE.PIID, PROCESS_INSTANCE.STATE, PROCESS_INSTANCE.NAME,            PROCESS_INSTANCE.TEMPLATE_NAME, PROCESS_ATTRIBUTE0.VALUE, PROCESS_ATTRIBUTE1.VALUE</value>
  </managed-property>

  <managed-property>
    <property-name>orderClause</property-name>
    <value>PROCESS_INSTANCE.PTID,PROCESS_INSTANCE.STATE</value>
  </managed-property>

  <managed-property><property-name>whereClause</property-name>
    <value>PROCESS_ATTRIBUTE0.NAME=''orderNo'' AND PROCESS_ATTRIBUTE1.NAME=''department''</value>
  </managed-property>

  <managed-property>
    <property-name>connection</property-name>
    <value>#{bfmConnection}</value>
  </managed-property>
</managed-bean>

<managed-bean>
  <managed-bean-name>bfmConnection</managed-bean-name>
  <managed-bean-class>com.ibm.bpe.clientmodel.BFMConnection</managed-bean-class>
  <managed-bean-scope>application</managed-bean-scope>

   <managed-property>
    <property-name>jndiName</property-name>
    <value>java:comp/env/ejb/LocalBusinessProcessHome</value>
  </managed-property>
</managed-bean>

The following code snippet shows the definition of the item listener managed bean:

<managed-bean>
  <managed-bean-name>ProcessInstanceDetailsHandler</managed-bean-name>
  <managed-bean-class>com.ibm.bpe.jsf.handler.BPCDetailsHandler</managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>

  <managed-property>
    <property-name>type</property-name>
    <value>bpc.samples.bean.CustomProcessInstanceBean</value>
  </managed-property>

</managed-bean>

Click on the links to see the source code of the ProcessInstanceList.jsp, faces-config.xml, CustomProcessInstanceQuery.java, and CustomProcessInstanceBean.java.

For a detailed discussion of the BPC Explorer list component, refer to the WebSphere information center.

Details component

To display fields of a bean, such as a process or task instance, you can use the BPC Explorer details component. For the details component, you specify an item provider, and the fields that you want to display on your page. For the fields, you can specify converters to transform the values.

Figure 3: BPC Explorer details component

The following code snippet shows, how you define the details component in your JSP:

<bpe:details model="#{ProcessInstanceDetailsHandler}">
<bpe:property label="Department:" name="department" />
<bpe:property label="Order number:" name="orderNo" />
</bpe:details>

The model attribute of the details component refers to a managed bean in the JSF configuration file. This managed bean specifies the item provider class and the type of the bean to be displayed. The bean must have getter methods for all properties that are defined in the details component. For example, to display the 'department' value, the bpc.samples.bean.CustomProcessInstanceBean class must have a method getDepartment(). The following code snippet shows the definition of the item provider in the JSF configuration file:

Click on the links to see the source code of the ProcessInstanceDetails.jsp, faces-config.xml, and CustomProcessInstanceBean.java.

For a detailed discussion of the BPC Explorer details component, refer to the WebSphere information center.

Command-bar component

The BPC Explorer command-bar component displays a bar with buttons. These buttons represent commands that operate on an object or the selected objects in a list. To identify the object, an item provider must be specified. Figure 4 outlines, how to use a command-bar in your application.

Figure 4: BPC Explorer command-bar component

The following code snippet shows a command-bar with 4 commands, as it is specified in the TaskInstanceDetails.jsp.

<bpe:commandbar model="#{TaskMessageHandler}" buttonStyleClass="command-button" >

  <bpe:command label="Claim"
               commandID="ClaimTaskInstance"
               commandClass="bpc.samples.command.ClaimTaskCommand"
               action="#{TaskMessageHandler.refresh}" />

  <bpe:command label="Save"
               commandID="SaveTaskInstance"
               commandClass="bpc.samples.command.SaveTaskCommand"
               context="#{TaskMessageHandler}"
               action="#{TaskMessageHandler.refresh}" />

  <bpe:command label="Finish"
               commandID="FinishTaskInstance"
               commandClass="bpc.samples.command.CompleteTaskCommand"
               context="#{TaskMessageHandler}"
               action="#{TaskMessageHandler.refreshList}" />

  <bpe:command label="Release"
               commandID="ReleaseTaskInstance"
               commandClass="bpc.samples.command.CancelClaimCommand"
               action="#{TaskMessageHandler.refreshList}" />

  <bpe:command label="Back"
               commandID="BackTaskInstance"
               action="#{TaskMessageHandler.refreshList}" />

</bpe:commandbar>

The following code snippet shows the definition of the item provider for the command-bar. The class 'bpc.samples.handler.CustomTaskMessageHandler' must implement the item provider interface 'com.ibm.bpe.jsf.handler.ItemProvider'.

<managed-bean>
  <managed-bean-name>TaskMessageHandler</managed-bean-name>
  <managed-bean-class>bpc.samples.handler.CustomTaskMessageHandler</managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>
</managed-bean>

Command elements specify the actions to be performed. This action can be specified using the action attribute, a command class, or both. A command class must implement the 'com.ibm.bpc.clientcore.Command' interface, the action element must refer to a method with a specific signature: String method(). The return value of this method is used by the JSF navigation handler to determine the navigation rule. The method can be implemented, for example, by a managed bean.

Click on the links to see the source code of the TaskInstanceDetails.jsp, faces-config.xml, CustomTaskMessageHandler.java, and SaveTaskCommand.java.

For a detailed discussion of the BPC Explorer command-bar component, refer to the WebSphere information center.

Message component

To display a message and its values, either use the BPC Explorer message component, or implement the rendering yourself. If you use the message component, you can profit from the generic rendering mechanism. If you want to use your own implementation, see ProcessStartForm.jsp for an example of how you can render an input form without using the BPC Explorer message component.

The BPC Explorer message component renders the process or task messages and primitive types, such as integers or strings. If the message type is a primitive type, a label and an input field are rendered. If the message type is a data object, the component traverses the object and renders the elements within the object. If a custom JSP is defined for a task, this custom JSP displayed when the message is rendered.

Figure 5: BPC Explorer message component

The following code snippet shows how the <bpe:form> tag is defined:

<bpe:form model="#{TaskMessageHandler.outputMessage}"
readOnly="#{TaskMessageHandler.readOnly}"
simplification="true" />

The model attribute of the form element specifies the the message. It refers to a com.ibm.bpe.clientcore.MessageWrapper or a commonj.sdo.DataObject, provided by a managed bean in the JSF configuration file. Use the readOnly attribute to control whether the message is rendered to be edited or read-only. If the simplification attribute is set to true, only message parts with a cardinality of zero or null are rendered. The following code snippet shows the definition of the item provider:

Click on the links to see the source code of the TaskInstanceDetails.jsp, faces-config.xml, CustomTaskMessageHandler.java.

For a detailed discussion of the BPC Explorer form component, refer to the WebSphere information center.