Developer Tutorial (How to build on B2J)

Author: Antony Miguel, Last Updated 19th April 2006

If you found this tutorial useful or lacking in any way or if you think there are certain areas which could be better explained or more fully explained please Let Me Know.

How developers and vendors can build on B2J

  • B2J can be extended via two routes:

    • By writing Web Services that the B2J reference engine can run
    • By using the B2J APIs to run BPEL processes

    This tutorial will cover the second of these methods: using the B2J APIs to run BPEL processes.

    For information on writing BPEL and running web services in the B2J reference engine you should see the BPEL Authors section of the B2J home page.

B2J BPEL execution API

    All the B2J public APIs are gathered under a 'publicapi' package in the two B2J plugins:

    • org.eclipse.stp.b2j.core
    • org.eclipse.stp.b2j.ui

    The API we will look at in this document is the BPELEngine API.

    There are two working examples of this API under the publicapi package themselves:

    • org.eclipse.stp.b2j.core.publicapi.example.IndependantAPIExample
    • org.eclipse.stp.b2j.ui.publicapi.example.WorkbenchAPIExample

    These two example classes both do exactly the same thing, they have two static methods; one to run a specified BPEL file locally and one to run the specified BPEL file distributed over a list of hosts.

    The difference is that the IndependantAPIExample can run outside of Eclipse and use a non-Eclipse JDT based Java compiler to compile the BPEL file. The WorkbenchAPIExample must run inside Eclipse and will use the Eclipse JDT to compile the BPEL file for execution.

    The example classes are very simple and the best way to see what is going on is to just take a quick look at the code.

    The IndependantAPIExample code can be viewed direct from CVS here.

    The WorkbenchAPIExample code can be viewed direct from CVS here.

    The basic API classes to be aware of are:

    • org.eclipse.stp.b2j.core.publicapi.program.BPELProgram
    • org.eclipse.stp.b2j.core.publicapi.engine.BPELEngineListener
    • org.eclipse.stp.b2j.core.publicapi.transport.session.SessionAddress

    These are the unchanging base classes in the API. They are used in conjunction with either:

    • org.eclipse.stp.b2j.core.publicapi.engine.WorkbenchBPELEngine
    • org.eclipse.stp.b2j.ui.publicapi.program.WorkbenchBPELProgram
    • (Note that the WorkbenchBPELProgram is in the B2J UI plugin since it depends on the B2J Eclipse UI)

    OR

    • org.eclipse.stp.b2j.core.publicapi.engine.IndependantBPELEngine
    • org.eclipse.stp.b2j.core.publicapi.program.IndependantBPELProgram

    Depending on whether you want to be inside or outside Eclipse.

    The basic process is to first create a BPELProgram instance. This represents the BPEL file plus any extra information required to run in the engine (such as the hosts you wish to run the program across).

    The next step is to create a BPELEngine instance. This represents the engine that will run your BPEL program.

    Once you have these two you can call runProgram() on your BPELEngine and the BPEL process should launch and execute.

Running a non-local BPEL process

    If you decide to use the B2J distributed BPEL engine then you will need to use the SessionAddress object.

    The SessionAddress object is basically equivalent to a hostname except with more information about requirements you have on that particular network link.

    When you are using the B2J distributed BPEL engine there is a single link from the client workbench to the coordinator host and one link from the coordinator host to each of the worker hosts (see the B2J Distribution Tutorial if you are unclear on what this means). When running a distributed BPEL program you can specify a SessionAddress for each of these links and in tandem a SessionAddress to specify the daemon connection information for each of these links. (e.g. one SessionAddress to specify a connection to an engine Daemon on host X using password Y and another SessionAddress to specify the actual engine connection to that host using encryption or link reconnection etc).

    Eclipse Workbench
    |
    Coordinator host
    / | \
    Worker host 1 Worker host 2 Worker host 3

    Each SessionAddress contains a number of attributes which place requirements on the link. The attributes are as follows (note that those attributes marked with 'IGNORED' should be ignored or left unset as the underlying implementation will set during the engine setup):

    • encryption - the link should be encrypted (e.g. if Daemon is set to use HTTPS)
    • encryption strength - the minimum strength of the encryption required on the link

    • authentication - the link should be authenticated
    • link reconnection - if the link fails it should be automatically reestablished
    • link reconnection timeout - the time to wait before giving up trying to reconnect a broken link
    • link reconnection start timeout - the time to wait before giving up making the initial link connection

    • requires password - used to specify whether a Daemon requires a password
    • password - used to specify the password for a Daemon

    • initiator host - (IGNORED) the host that should initiate the link connection
    • initiator port min/max - (IGNORED) the local port range the initiator host should use
    • listener host - the host that should listen for the link connection
    • listener port min/max - (IGNORED) the local port range the listener host should use
    • transport provider class - (IGNORED) the classname of the underlying transport provider
    • transport provider plugin name - (IGNORED) the plugin of the underlying transport provider