169Developing with the task AP

The @name attribute of the variable element is required and refers to a process or local variable that’s accessible in the context that the task is running within. The @mapped-name attribute is the task variable name that’s assigned, and if omitted, it would assume the same name as the process variable. The @access attribute controls the behavior of how the task variable is written back to the process variable at the com- pletion of the task. The three possible values are read, write, and required. A read value indicates the task can only read the process variable. A write value indicates the task variable will be written back to the corresponding process variable by the task. A value of required indicates the task variable must be populated when attempting to convert the value to the process variable.

As you can see, the built-in task controller has fairly limited capabilities. However, as with most things in jBPM, you’re free to create your own task controller by imple- menting the TaskControllerHandler. Depending on your requirements, this could be a fairly complex undertaking, so we won’t cover it here (the User Guide provides some guidance on this, and I suggest looking at the source code). However, you can easily see how this approach could greatly simplify the form and process variables we created in figure 6.1. In that example, each field in the form represented a process variable. A far better solution would be to create a complex Java class that houses the data as a single process variable, and then use a controller to carve it into task vari- ables more suitable for use within the form framework you’re using. Another intrigu- ing idea would be to store the complex objects as service data objects (SDOs are discussed in chapter 4), and then use the metadata features of SDO to dynamically build your form.

In the next section, we’re going to change the pace a bit and begin to tap into the abilities that the jBPMAPI provides. It is through the API that you really start to appre- ciate the capabilities of jBPM, because it unlocks so many fascinating integration opportunities. My interest in jBPM began to flourish as I learned how to fully leverage this capability. Indeed, this is what distinguishes open source from proprietary solu- tions. When using a closed source, commercial application, you’re usually beholden to a limited number of public APIs that they deem worthy of sharing. The good stuff is kept private. With open source, you have access to everything, and you can look at the code to understand exactly how it’s being used. I chose to begin talking about the API

in conjunction with tasks because this is likely one of the first places you’ll want to use it. I pointed out earlier that the task form capabilities of jBPM are fairly restricted, but with the API, you can easily augment it with your own code. Let’s begin.

6.5

Developing with the task API

As we discussed in section 6.1, while the form framework that comes with building task forms for the jBPM Console is simple to use, it also is fairly limited. Specifically, it’s limited in its ability to display and work with complex data, such as repeating rows and complex table layouts. Most enterprise users of jBPM will quickly determine that they must create their own forms using their framework of choice, be it Google’s GWT, Adobe Flex, or TIBCO’s GI, among others. Fortunately, using the jBPM API makes

170 CHAPTER 6 jBPM tasks

doing this far less daunting than you might imagine. Let’s illustrate some of the more common API calls that you might find beneficial.

6.5.1 Identifying processes within a jBPM instance

Although not directly related to tasks, finding all process definitions with a jBPM

instance is likely one of the first places you’ll begin when using the API and working with tasks. As a refresher, a process is simply a unique process definition, whereas a pro-

cess instance is an instantiated instance of a given process.

The first step in using the API, regardless of which operation you wish to perform, is to acquire a JbpmContext instance. In conjunction with the hibernate.cfg.xml (and/or hibernate.properties; see the sidebar “Using hibernate.properties to specify which

jBPM instance to connect”), the JbpmContext instance is used to establish which jBPM

database or instance to connect. Once a JbpmContext is acquired, you can then per- form a variety of operations, as listing 6.2 shows. In this listing, we retrieve a list of pro- cess definitions within a given jBPM instance. In this case, we’re creating a helper class called JBPMHelper, to which we’ll gradually add additional static methods, starting with listProcesses (I settled on static in order to simplify calling these helper meth- ods without having to first instantiate the class).

public class JBPMHelper {

public static List<ProcessDefinition>

Listing 6.2 Helper class method to retrieve a process from a jBPM instance

Using hibernate.properties to specify which jBPM instance to connect

When you create a jBPM process project within the Eclipse Graphical Process Designer, it will automatically create a hibernate.cfg.properties file in the src/main/ config directory. By default, this is set up to connect to a hypersonic in-memory database. To connect to a remote database, you have two options: (1) specify the connection settings in the hibernate.cfg.xml file (search for “JDBC connection properties (begin)”), or (2) comment out the connection properties in hibernate.properties and instead create a hibernate.properties file in the same config directory. Configure this file to resemble this:

hibernate.connection.driver_class=org.hsqldb.jdbcDriver hibernate.connection.url=jdbc:hsqldb:hsql://localhost/ hibernate.connection.username=sa

hibernate.connection.password=

hibernate.dialect=org.hibernate.dialect.HSQLDialect

Obviously, change the property values to reflect your environment. Although there is no single correct choice for specifying connection settings, my preference is the hibernate.properties file, since you isolate your changes and don’t risk inadvertently

171