refcodes-jobbus: Asynchronous job execution

README

“The REFCODES.ORG codes represent a group of artifacts consolidating parts of my work in the past years. Several topics are covered which I consider useful for you, programmers, developers and software engineers.”

What is this repository for?

This artifact makes use of the Command pattern and provides a frame to work with Command (job) instances (also in a distributed environments, e.g. REST, SOA, Cloud Computing) and provides do/undo functionality.

How do I get set up?

To get up and running, include the following dependency (without the three dots “…”) in your pom.xml:

1
2
3
4
5
6
7
8
9
<dependencies>
	...
	<dependency>
		<groupId>org.refcodes</groupId>
		<artifactId>refcodes-jobbus</artifactId>
		<version>3.3.5</version>
	</dependency>
	...
</dependencies>

The artifact is hosted directly at Maven Central. Jump straight to the source codes at Bitbucket. Read the artifact’s javadoc at javadoc.io.

Introduction

The terms command and job are used interchangeably. To understand the benefits which the job-bus offers, we should briefly understand the Command pattern:

See the blog Having fun with the command pattern on how to do the undo with the refcodes-command artifact …

Simply speaking, you push a job into your job-bus. You can either wait for the job to be executed and grab its result when done or you use a handle to grab the result later on. The job is being executed asynchronously, it is up to the job-bus where and when it is being executed: For example the job could be transported to some remote JVM to be executed there or the job could get executed as soon as a worker thread is happy to grab the job from a job-queue.

How do I get started?

First of all you got to be aware which jobs you got to create for your project (or at least with which ones to start) and on which kind of context your jobs will be applied. Your jobs will actually implement either the Command or the Undoable interface. The terms job, commandand undoablewill be used interchangeable here and there. The context can by of any type, it can be a service, a client or any other JavaObject.

Snippets of interest

Below find some code snippets which demonstrate the various aspects of using the refcodes-jobbus artifact (and , if applicable, its offsprings). See also the example source codes of this artifact for further information on the usage of this artifact.

Create your commands

Given you want to apply various arithmetic operations on a list of int values and return the result, we have to create according Command implementations first. Starting with the SumCommandImpl, the code might look as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
public class SumCommandImpl extends AbstractUndoable<List<Integer>, Integer, Exception> {

	/**
	 * {@inheritDoc}
	 */
	@Override
	public Integer execute( List<Integer> aContext ) {
		int theResult = 0;
		for ( Integer eInt : aContext ) {
			theResult += eInt;
		}
		return theResult;
	}
}

All the values contained in the context (being the list) will be summed up and the sum is returned by the execute method. That’s it. There may be additional jobs such as MaxCommandImpl, MinCommandImpl or AverageCommandImpl.

Your jobs may also modify (mutate) the context which would make a job being an Undoable applicable.

Execute your commands

To execute your Command instances, you need a JobBus instance:

a) Create an instance of your JobBus and feed it with your context:

1
2
3
4
...
List<Integer> context = new ArrayList<Integer>();
JobBusImpl<List<Integer>> jobBus = new JobBusImpl<List<Integer>>( context );
...

b) Synchronously executing your Undoable (job) is straight forward:

1
2
3
4
...
SumCommandImpl theSumCommand = new SumCommandImpl();
int theSumResult = jobBus.getResult( theSumCommand );
...

c) For asynchronous execution, you got the remember a handle with which you can retrieve the result later:

1
2
3
4
5
6
7
8
...
String theSumHandle = jobBus.execute( theSumCommand );
...
if( jobBus.isExecuted( theSumHandle ) ) { 
	int theSumResult = jobBus.getResult( theSumHandle );
	...
}
...

You can also wait for execution to finish by calling jobBus.waitForExecution( theSumHandle ).

Examples

Please refer to the example source code for more examples on the usage of this artifact.

Contribution guidelines

Report issues
Finding bugs
Helping fixing bugs
Making code and documentation better
Enhance the code

Who do I talk to?

Siegfried Steiner (steiner@refcodes.org)

Terms and conditions

The REFCODES.ORG group of artifacts is published under some open source licenses; covered by the refcodes-licensing (org.refcodes group) artifact - evident in each artifact in question as of the pom.xml dependency included in such artifact.

refcodes-jobbus: Asynchronous job execution

Categories

Tags