When the user clicks a button in the user interface, the corresponding
command is run on the selected objects. You can add and extend the
component
in your JSF application.
- Add the CommandBar component to the JavaServer
Pages (JSP) file.
Add the bpe:commandbar tag
to the <h:form> tag. The bpe:commandbar tag
must contain a model attribute.
The
following example shows how to add a CommandBar component
that provides refresh and claim commands for a task instance list.
<h:form>
<bpe:commandbar model="#{TaskInstanceList}">
<bpe:command commandID="Refresh" >
action="#{TaskInstanceList.refreshList}"
label="Refresh"/>
<bpe:command commandID="MyClaimCommand" >
label="Claim" >
commandClass="<customcode>"/>
</bpe:commandbar>
</h:form>
The model attribute refers
to a managed bean. This bean must implement the ItemProvider interface
and provide the selected Java™ objects. The CommandBar component
is usually used with either the List component or the Details component
in the same JSP file. Generally, the model that is specified in the tag is
the same as the model that is specified in the List component
or Details component on the same page. So for the List component,
for example, the command acts on the selected items in the list.
In
this example, the model attribute refers to the TaskInstanceList
managed bean. This bean provides the selected objects in the task instance
list. The bean must implement the ItemProvider interface.
This interface is implemented by the BPCListHandler class
and the BPCDetailsHandler class.
- Optional: Configure the managed bean that is referred
to in the bpe:commandbar tag.
If the CommandBar model attribute
refers to a managed bean that is already configured, for example, for a list
or details handler, no further configuration is required. If you change the
configuration of either of these handlers or you use a different managed bean,
add a managed bean that implements the ItemProvider interface
to the JSF configuration file.
- Add the code that implements the custom commands to the JSF application.
The following code snippet shows how to write a command class that
extends the command bar. This command class (MyClaimCommand) is referred to
by the bpe:command tag in the JSP file.
The command
checks the preconditions and any other prerequisites, for example, the correct
number of selected items. It then retrieves a reference to the human task
API, HumanTaskManagerService. The command iterates over
the selected objects and tries to process them. The task is claimed through
the HumanTaskManagerService API by an ID. If an exception
does not occur, the state is updated for the corresponding TaskInstanceBean
object. This action avoids retrieving the value of the object from the server
again.
public class MyClaimCommand implements Command {
public String execute(List selectedObjects) throws ClientException {
if( selectedObjects != null && selectedObjects.size() > 0 ) {
try {
// Determine HumanTaskManagerService from an HTMConnection bean.
// Configure the bean in the faces-config.xml for easy access
// in the JSF application.
FacesContext ctx = FacesContext.getCurrentInstance();
ValueBinding vb =
ctx.getApplication().createValueBinding("{htmConnection}");
HTMConnection htmConnection = (HTMConnection) htmVB.getValue(ctx);
HumanTaskManagerService htm =
htmConnection.getHumanTaskManagerService();
Iterator iter = selectedObjects.iterator() ;
while( iter.hasNext() ) {
try {
TaskInstanceBean task = (TaskInstanceBean) iter.next() ;
TKIID tiid = task.getID() ;
htm.claim( tiid ) ;
task.setState( new Integer(TaskInstanceBean.STATE_CLAIMED ) ) ;
}
catch( Exception e ) {
; // Error while iterating or claiming task instance.
// Ignore for better understanding of the sample.
}
}
}
catch( Exception e ) {
; // Configuration or communication error.
// Ignore for better understanding of the sample
}
}
return null;
}
// Default implementations
public boolean isMultiSelectEnabled() { return false; }
public boolean[] isApplicable(List itemsOnList) {return null; }
public void setContext(Object targetModel) {; // Not used here }
}
The command is processed in the following way:
- A command is invoked when a user clicks the corresponding button in the
command bar. The CommandBar component retrieves the selected
items from the item provider that is specified in the model attribute
and passes the list of selected objects to the execute method
of the commandClass instance.
- The commandClass attribute
refers to a custom command implementation that implements the Command interface.
This means that the command must implement the public String execute(List
selectedObjects) throws ClientException method. The command returns
a result that is used to determine the next navigation rule for the JSF application.
- After the command completes, the CommandBar component
evaluates the action attribute. The action attribute
can be a static string or a method binding to a JSF action method with the public
String Method() signature. Use the action attribute
to override the outcome of a command class or to explicitly specify an outcome
for the navigation rules. The action attribute is not
processed if the command generates an exception other than an ErrorsInCommandException exception.
Your JSF application now contains a JavaServer page that implements
a customized command bar.