JavaFBP

Java Implementation of "Classical" Flow-Based Programming (FBP)

General web site on Flow-Based Programming: https://jpaulm.github.io/fbp/ .

Latest release is v4.1.14. The jar file - javafbp-4.1.14.jar - can be obtained from the Releases folder, or from build/libs. Note: The Maven 'shield' below may show an earlier release. If you click on the Maven shield below, select Download, then jar.

This implementation is a kit for building JavaFBP projects. For a number of sample networks, go to https://github.com/jpaulm/javafbp/tree/master/src/main/java/com/jpaulmorrison/fbp/resourcekit/examples .

For your own projects, include the JavaFBP jar file in the Build Path property for the project.

General

General web site for "classical" FBP:

• https://jpaulm.github.io/fbp

In computer programming, flow-based programming (FBP) is a programming paradigm that defines applications as networks of "black box" processes, which exchange data across predefined connections by message passing, where the connections are specified externally to the processes. These black box processes can be reconnected endlessly to form different applications without having to be changed internally. FBP is thus naturally component-oriented.

FBP is a particular form of dataflow programming based on bounded buffers, information packets with defined lifetimes, named ports, and separate definition of connections.

JavaFBP Syntax and Component API:

• https://jpaulm.github.io/fbp/jsyntax.htm

An automatically generated Javadoc can also be browsed at http://jpaulm.github.io/javafbp/ . Unfortunately this isn't very useful for someone planning to use JavaFBP components, so we have built an FBP-specific Component Attributes List, which can be displayed by clicking on http://htmlpreview.github.io/?https://github.com/jpaulm/javafbp/blob/master/compList.html - see below.

MySQL Support

Two components are available for reading and writing MySQL tables, respectively: ReadJDBC and WriteJDBC, in core.components.jdbc. These dynamically load the most recent MySQL jar file, and use reflection to execute SQL services.

If you are looking for an application using these components, it can be found in the FBP-ETL repository. This application of course uses the JavaFBP jar file as a dependency.

If you get a message saying "No suitable driver found", try restarting the MySQL service in services.msc.

JavaFBP-WebSockets

There is also a small GitHub project called javafbp-websockets, which contains two generalized components supporting WebSockets ( https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API ), and a simple test component and network - it can be found at https://github.com/jpaulm/javafbp-websockets .

Running a network

Default connection size

JavaFBP recommends using a small connection size for debugging, and a larger one for production. In the latest version of JavaFBP, this is specified in the <user>.JavaFBPProperties.xml file - tag.

Running on DOS

You will have downloaded the JavaFBP jar file earlier, so do a gradle build for your project, to make sure the compiled classes (.class files) are in the 'bin' directory.

Now position the current directory to your own project, using cd, and enter the following into the DOS window:

  java -cp "<JavaFBP directory>/javafbp-x.y.z.jar;." <program class name> 

where x.y.z is the version of the JavaFBP jar file. Note the final ;.... or you can place .; in front of the jar file name.

Program class name must be the fully qualified network name.

You must also make sure that java can find any class files that your main line needs, by specifying the necessary jar files, and class directories using the -cp/-classpath parameter.

Here is a test command you can run (changing x.y.z to the current version number, of course), using networks and components provided by the JavaFBP project. Note that the bin folder is not uploaded to GitHub, so you will have to compile any networks to be tested to the bin folder (or add them to your own jar file):

Do a cd command to your downloaded JavaFBP project, then enter

 java -cp ".;build/libs/javafbp-x.y.z.jar" com.jpaulmorrison.fbp.resourcekit.examples.networks.Copy1    

For your own project, you will probably have to add more directories to the classpath parameter - remember to provide the whole directory name.

Running on *nix

Replace the ';' in the -cp parameter with ":" for *nix.

Running in Eclipse

Go to Properties/Java Build Path for your project; click on Add External Jars, add your JavaFBP jar file to the list, and then hit Apply and OK.

Select Debug for your project.

Checking your setup

Here is a simple command-line test that can be run to test that everything is working.

Position to the javafbp directory; then enter

java -cp ".;build/libs/javafbp-x.y.z.jar" com.jpaulmorrison.fbp.resourcekit.examples.networks.MergeandSort

where x.y.z is the current version number of JavaFBP.

Alternatively, if you position to your own bin folder, you might code something like

java -cp ".;C:\users\<you>\downloads\javafbp-x.y.z.jar" <name of class to be run>

Here is a picture of MergeandSort, drawn using DrawFBP:

This network contains 4 processes:

• 2 occurrences of GenerateTestData,
• a Sort process - a very simple-minded Sort, which can only handle up to 9,999 information packets
• a text display component, which invokes Java Swing to display the sorted data in a scroll pane.

The outputs of the two GenerateTestData processes are merged on a "first come, first served" basis. During the run you should see a scroll pane with the sorted data scrolling down.

At the end of the run, you should see:

Run complete.  Time: x.xxx seconds
Counts: C: 150, D: 153, S: 300, R (non-null): 304, DO: 0

where the counts are respectively: creates, normal drops, sends, non-null receives, and drops done by "drop oldest".

Warning!

Care must be taken if combining LoadBalance (with substreams) and SubstreamSensitiveMerge in a divergent-convergent pattern - this pattern is one of the warning signals for deadlocks anyway. The problem is described in more detail under #8.

Tracing and other options

To trace JavaFBP services and/or lock usage, set the appropriate parameter(s) in JavaFBPProperties.xml in the <user> directory to true:

• tracing
• tracelocks

e.g.

<?xml version="1.0"?> 
<properties> 
<tracing>true</tracing>
<tracelocks>false</tracelocks>
<defaultcapacity>...</defaultcapacity>    (as of v4.1.3)
</properties> 

These traces will appear in the project directory (in GitHub if running Eclipse) under the name xxxx-fulltrace.txt, where xxxx is the name of the network being run. Subnets have their own trace output files.

Values for defaultcapacity are as follows:

• PRODUCTION (currently 10)
• DEBUG (currently 1)
• any number
• defaultcapacity not specified - defaults to DEBUG value

Two other options are also supported in the properties file:

• deadlocktest (defaults to true, so you might set it to false if debugging)
• forceconsole (used if immediate console output is required during debugging - normally, console output is sent to a file)