|
JBPM 3.3.1 GA brings a few interesting news: one of this is the GWT console which allows for rapid publishing of Process information as REST resources and has out of the box support for "application/json" and "text/xml" marshalling.
In the web services world, REST is a key design idiom that embraces a stateless client-server architecture in which the web services are viewed as resources and can be identified by their URLs.
In short, the difference with traditional web services is that traditional Web Services are enginereed with a more complex protocol (SOAP) which has been built over HTTP. The web services request and response are in fact SOAP messages. REST web services on the other hand can be invoked as simple HTTP requests, adding the methods and parameters on the URL.
Step 1: download and install JBPM 3.3.1
JBPM can be downloaded from JBoss site at
http://www.jboss.org/jbossjbpm/downloads/
You'll notice that it is not a .zip file as the previous release. It's actually an installer.
java -jar jbpm-installer-3.3.1.GA.jar
A wizard will guide you through the installation. Select th database you want to use (in this tutorial we'll use MySQL)
Then you have to opportunity to select your JBoss server so JBPM gets actually deployed on your server with all the required libraries (this was really an annoying task to do manually!)
Step 2: configure the Database
Once the wizard has completed, move to the "deploy" folder of your JBoss distribution. You'll notice a jbpm folder which contains the libraries, the applications and the configuration.
If you have selected MySQL as database you'll find an "jbpm-mysql-ds.xml". JBPM installer has created it for you. Not only, it has also copied the jdbc drivers for MySQL. Wonderful isn't it ???
You need only to specify the Database settings, in our datasource file :
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<xa-datasource>
<jndi-name>JbpmDS</jndi-name>
<xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
<xa-datasource-property name="URL">jdbc:mysql://localhost/jbpm</xa-datasource-property>
<user-name>jbpm</user-name>
<password>jbpm</password>
<transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
<no-tx-separate-pools />
<track-connection-by-tx />
<exception-sorter-class-name>
com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
</exception-sorter-class-name>
<valid-connection-checker-class-name>
com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
</valid-connection-checker-class-name>
<metadata>
<type-mapping>mySQL</type-mapping>
</metadata>
</xa-datasource>
</datasources>
In our sample we have created an empty schema named "jbpm" on our local machine.
Ok, now populate the Database running the scripts found under the JBPM_HOME/database folder
(I suggest you reading this tip for information about the jbpm database users: http://www.mastertheboss.com/en/jboss-howto/44-jbpm/169-how-to-log-on-the-jbpm-console-.html)
Step 3: launch the console
The GWT console server can be reached at http://localhost:8080/gwt-console-server/
This is an hard copy if it:
GWT Console Server
Published REST Url's
| Method |
Context |
Description |
Mime Types |
Process Management
|
| GET |
/rs/process/definitions |
A list of process definitions |
application/json |
| POST |
/rs/process/definitions/{processId}/remove |
Removes a particular process definition |
application/json |
| GET |
/rs/process/definitions/{id}/instances |
A list of process instances for a given process definition |
application/json |
| POST |
/rs/process/instances/{id}/state/{next} |
Change instance state (RUNNING, SUSPENDED, ENDED) |
*/* |
| POST |
/rs/process/definitions/{processId}/instances/new |
Create a new process instance |
application/json |
User Management
|
| GET |
/rs/user/roles?roleCheck=a,b,c |
A list of assigned roles matching the query parameter (Comma seperated list) |
application/json |
Task Management
|
| GET |
/rs/tasks/actor/{actorId} |
A list of available tasks (OPEN and IN_PROGRESS) for an actor |
application/json |
| GET |
/rs/tasks/{taskId}/assignment/{actorId} |
Assign a task to an actor actor. If you leave out the actorId it will release (IN_PROGRESS->OPEN) the task |
application/json |
| POST |
/rs/tasks/{taskId}/close/transition?signal={signalName} |
Complete a task with signal |
application/json |
| POST |
/rs/tasks/{taskId}/close/transition/default |
Complete a task with default transition |
application/json |
jBPM3 proprietary extensions
|
| GET |
/rs/jbpm3/definitions/{processId}/image |
Retrieve a process definition image (GPD), if deployed |
image/jpeg |
| GET |
/rs/jbpm3/definitions/{processId}/diagramInfo |
Retrieve a process definition coordinates (GPD) |
application/json |
| GET |
/rs/jbpm3/instances/{instanceId}/activeNodeInfo |
Retrieve a process definition coordinates (GPD) of the active node |
application/json |
| POST |
/rs/jbpm3/definitions/new |
Upload a new process definition |
Accept:multipart/form-data
Produce:application/json |
| POST |
/rs/jbpm3/tokens/{tokenId}/transition?signal={signalName} |
Signal a token by specifiy a transition |
|
| POST |
/rs/jbpm3/tokens/{tokenId}/transition/default |
Signal a token to take the default transition |
|
|
As you can see, every process management action can be done simply with an HTTP request!
The output of the RestFul Web services is JSON.
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is another protocol to exchange data between web applications. is easy for humans to read and write. It is easy for machines to parse and generate.
JSON is built on two structures:
- A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
- An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.
In order to consume these web services you have several options, here we have used a simple shell command "curl" which is available on most Linux platforms and can be downloaded here for other OS:
http://curl.haxx.se/download.html
Here's a sample output from curl under windows:
curl http://localhost:8080/gwt-console-server/rs/process/definitions -u admin:admin
{"definitions":[{"processId":3,"name":"simple","version":"2"},{"processId":2,"na
me":"simple","version":"1"}]}
curl has many options, here we are only passing the URL of the Web service and the -u option which sets username and password needed.
You can see how powerful is this ? imagine you can now create simple JBPM clients even with just a shell interpreter!
to be continued in part 2!
|
