Understanding Almo 2.0: The Almo API

Building a WorkflowConfiguration

To get an empty WorkflowConfiguration, use the following code:

WorkflowConfiguration w = AlmoFactory.createWorkflow(false,null);

The first argument is used to configure log4j. When the WorkflowConfiguration is created, you can decide whether to enable log4j messages generated by Almo. Passing true, will configure log4j to print logging messages to the console. Passing false, will not configure log4j, instead you can configure log4j to your own needs. The second argument is used to to initialize the Almo elements with an arbitrary object, which you might need to use when the WorkflowInstance is executed, e.g. a database connection (see later section for more information).

Now we will add some elements to the WorkflowConfiguration. At this point you do not need to worry about their implementation. We will cover that in the next section.

try {
	Task t1 = new DefaultTask("t1");
	w.addTask(t1);
		
	Operation o2 = new Operation2("o2");
	o2.setPackage("org.ontoware.almo.example");
	o2.setClass("Operation2");
	t1.addElement(o2);
	
	Task t2 = new Task2("t2");
	t2.setPackage("org.ontoware.almo.example");
	t2.setClass("Task2");
	w.addTask(t2);
	
	Container c1 = new DefaultContainer("c1");
	t2.addElement(c1);
		
	Operation o3 = new Operation3("o3");
	o3.setPackage("org.ontoware.almo.example");
	o3.setClass("Operation3");
	c1.addElement(o3);
			
	Operation o4 = new Operation4("o4");
	o4.setPackage("org.ontoware.almo.example");
	o4.setClass("Operation3");
	c1.addElement(o4);
		
} catch (IllegalLabelException e) {
	e.printStackTrace();
} catch (IllegalSettingsException e) {
	e.printStackTrace();
}

	The first Task is the DefaultTask offered by Almo.
	The add methods will throw two Exceptions: IllegalLabelException: if the label of the element to add is not unique IllegalSettingsException: if the settings of the element to add are illegal
	This Operation is not implemented by Almo, therefore you have to specify its package and class.
	This Task is not implemented by Almo, therefore you have to specify its package and class.
	This Container is implemented by Almo.

As result we get the following WorkflowConfiguration tree:

The lock indicates that all these elements are required. We will deal with the difference between required and optional elements later.

Implementation of Almo elements

In the previous section we have used some implementations of Almo elements to form our WorkflowConfiguration. Now we will take a look at how to implement the abstract Almo classes.

Task

Implementing a Task is done by deriving a class from the abstract super-class org.ontoware.almo.api.Task. The following methods have to be implemented:

public void print(String s)

If the Almo GUI is used, this method prints the String on the DefaultTaskPanel. If the verbose value of the WorkflowInstance is set to 1, the String will be printed on the console.

public void initObject(Object o)

This method was mentioned above, but what the use of it? Imagine you have to access some ressources within your application via a Java object. You can use the initObject method to initialize this object. Example:

class DBOperation extends Operation {

	DBConnection con;
	
	...
	
	public void initObject(Object o) {
		this.con = (DBConnection)o;
	}
	
	...
	
	public void run() {
		...
		this.con.doesSoemthing();
		...
	}

}

	You have an instance variable to access a database within your Operation class.
	The initObject method initializes your instance variable.
	So you can use it later.

But this will only work, if you convey the initialized Java object to the createWorkflow methods of the class AlmoFactory.

DBConnection db = new DBConnection(...);
WorkflowConfiguration w = AlmoFactory.createWorkflow(false,db);
...
Operation op = new DBOperation("label");
someTask.addElement(op);
...

Adding more behaviour to your WorkflowConfiguration

So far, we have created a very simple WorkflowConfiguration, with some Tasks, Containers and Operations, that are all required. But Almo supports more functions. You can add optional elements to your WorkflowConfiguration, and by adding and removing them you allow the user of your workflow to build a flexible WorkflowInstance. Now we will take a look about the concepts of required and optional elements.

Required and optional elements

Required elements are the skeleton of your configuration. They may never be removed. But if you want to include elements, that may be added or removed, you can add optional elements. This is done by setting the usage property to optional.

Let us create a new Task and add two optional Operations to it.

...
Task t3 = new DefaultTask("t3");
w.addTask(t3);
			
Operation o5 = new Operation5("o5");
o5.setPackage("org.ontoware.almo.example");
o5.setClass("Operation5");
o5.setUsage(Constants.USAGE_OPTIONAL);
t3.add(o5);
			
Operation o6 = new Operation6("o6");
o6.setPackage("org.ontoware.almo.example");
o6.setClass("Operation6");
o6.setUsage(Constants.USAGE_OPTIONAL);
t3.add(o6);
...

The setUsage method accepts a String with the new value for the usage. If the String is illegal an IllegalSettingsException is thrown. Make sure you use the Strings you find in the class Constants.

The resulting WorkflowConfiguration looks like this:

If you use the Almo GUI in your application, you could remove and add the elements "o5" and "o6" now.

Include and exclude actions

Optional elements offer another important feature. As author of a workflow, you first build a skeleton of required elements, then you add optional elements to your workflow. But what happens if certain optional elements require or prohibit the use of other elements? In applications you should not confront the user with such problems. Instead, the user should just add and remove optional elements, and those elements, which should or should not be part of the workflow, are automatically included or excluded, respectively. Almo provides such a functionality.

If you load the WorkflowConfiguration we have created so far, you will only get the skeleton of required elements, unless you add initial optional elements to required parent elements. Let us do that for our last Task "t3".

t3.add_OnAddIncludeElement(o5);

Now the Operation "o5" will be added to Task "t3", when the WorkflowConfiguration is loaded.

But what happens, if either Operation "o5" or Operation "o6" shall be part of the Workflow? These elements should include and exclude themselves, respectively. So if "o5" is added, "o6" shall be removed and if "o6" is added, "o5" shall be removed. But we do not want the user to leave Task "t3" without any Operations. So if he decides to remove an Operation rather than to add it, we should cover this, too. So if "o5" is removed, then "o6" shall be added and if "o6" is removed, then "o5" shall be added. Here is the code for that:

o5.add_OnAddExcludeElement(o6);
o6.add_OnAddExcludeElement(o5);

o5.add_OnRemoveIncludeElement(o6);
o6.add_OnRemoveIncludeElement(o5);

All the actions that should be carried out, when optional elements are added or removed, can be easily edited with the Almo application, but this should just give you an idea about this Almo feature, which can be important if you want to create a WorkflowInstance with the Almo API.

Creating a WorkflowInstance

One concept that might be confusing is that you can not create a WorkflowInstance from scratch. You have to build a WorkflowConfiguration first and derive a WorkflowInstance from that. The idea is that because of the distinction between required and optional elements and the actions that are performed, when optional elements are added or removed, the WorkflowInstance might be different every time.

Imagine that in your application you have some criterion that decides whether to use one element or another. Let us do that with our example and our optional Operations.

if (Math.random()>0.5) {
	t3.removeElement(o6);
}
else {
	t3.removeElement(o5);
}

The resulting WorkflowConfiguration either is:

Math.random()>0.5	OR	Math.random()<=0.5

From a given WorkflowConfiguration it is very easy to create a WorkflowInstance (Remember that a WorkflowInstance can only be generated, if all parent elements have at least one child element):

try {
	w.createInstance();
} catch (SecurityException e) {
	e.printStackTrace();
} catch (IllegalArgumentException e) {
	e.printStackTrace();
} catch (IllegalInstanceException e) {
	e.printStackTrace();
} catch (ClassNotFoundException e) {
	e.printStackTrace();
} catch (NoSuchMethodException e) {
	e.printStackTrace();
} catch (InstantiationException e) {
	e.printStackTrace();
} catch (IllegalAccessException e) {
	e.printStackTrace();
} catch (InvocationTargetException e) {
	e.printStackTrace();
} catch (IllegalSettingsException e) {
	e.printStackTrace();
}

The method createInstance creates the WorkflowInstance of the WorkflowConfiguration. The various Exceptions are thrown if "something" goes wrong. See the Javadoc Pages for more information.

Writing and reading the WorkflowConfiguration

The WorkflowConfiguration is written to an OutputStream by the write method. If the WorkflowConfiguration has a WorkflowInstance it is written to the OutputStream as well.

try {
	w.write(new FileOutputStream("examples/tutorial_1.almo"),true);
} catch (FileNotFoundException e) {
	e.printStackTrace();
} catch (IOException e) {
	e.printStackTrace();
}

The first argument of the write method is the OutputStream to write to, the second argument determines whether the OutputStream should be closed after writing.

Reading a WorkflowConfiguration is done with the createWorkflow method from the class AlmoFactory. If a WorkflowInstance is available, you can get it with the getInstance method from the returned WorkflowConfiguration object.

try {
	WorkflowConfiguration w = AlmoFactory.createWorkflow(false,new FileInputStream("examples/a.almo"),null);
} catch (FileNotFoundException e) {
	e.printStackTrace();
} catch (InstantiationException e) {
	e.printStackTrace();
} catch (IllegalAccessException e) {
	e.printStackTrace();
} catch (ClassNotFoundException e) {
	e.printStackTrace();
} catch (IllegalLabelException e) {
	e.printStackTrace();
} catch (IllegalSettingsException e) {
	e.printStackTrace();
} catch (SecurityException e) {
	e.printStackTrace();
} catch (IllegalArgumentException e) {
	e.printStackTrace();
} catch (NoSuchMethodException e) {
	e.printStackTrace();
} catch (InvocationTargetException e) {
	e.printStackTrace();
} catch (IllegalInstanceException e) {
	e.printStackTrace();
}

The first argument of the createWorkflow method is used to configure log4j or not, the second argument is the InputStream to read from and the third argument is the Object used for the initObject method (see previous section). For more details about the various Exceptions consult the Javadoc Pages.

Summary

In this section you have learnt the basics of the Almo API. Of course everything that we did here (apart from the implementation of Almo elements) can be done with the Almo application, but this section was meant to give you a brief overview. The next sections will summarize the settings of all elements and the basic methods that you need to add and remove elements from the Workflow.