Editing Developers

Welcome to the developers tutorials!

In here you will find everything that you need to start developing plug-ins for OptFlux.

= First things first! =

OptFlux is built on top of [http://www.aibench.org AIBench] meaning that OptFlux itself is no more than set of plug-ins for the AIBench framework.

The AIBench Framework is a joint project by [http://sing.ei.uvigo.es colleagues] at [http://www.uvigo.es University of Vigo] and ourselves. You can find specific contacts and documentation for AIBench at its own website and [http://www.sciencedirect.com/science?_ob=ArticleURL&_udi=B6T5J-4Y34G0X-1&_user=2459786&_coverDate=05/31/2010&_rdoc=1&_fmt=high&_orig=search&_origin=search&_sort=d&_docanchor=&view=c&_acct=C000057396&_version=1&_urlVersion=0&_userid=2459786&md5=660fff51c519bea5e13198a8a0bce0dc&searchtype=a publication]. 

This AIBench sections of this documentation are partially based on the one found in the AIBench website.

OptFlux is being developed using [http://www.eclipse.org Eclipse IDE]. We recommend using Eclipse to create your own plug-ins since we already provide ready-to-go classpath and project configurations for this IDE. You are, however, free to develop in any IDE you see fit. Please contact us if you are willing to provide a tutorial on how to get things going in any other IDE. We would very much appreciate that :)

You can download Eclipse [http://www.eclipse.org/downloads/ here]. We recommend version 3.5.* or above.

= Getting the code =

The code of OptFlux can be obtained either in specific versions format or, alternatively, directly from the SVN server located at sourceforge.

== From version packages ==

Starting at version 2.3, you can download a "ready-to-go" eclipse configuration of OptFlux.

This will allow you to import this project into Eclipse and start developing new plug-ins with very little effort.

Version specific source code distributions can be found [http://sourceforge.net/projects/optflux/files/ here].

== Latest version from Sourceforge SVN ==

* The following command will checkout the latest snapshot from the Subversion server
 svn co https://optflux.svn.sourceforge.net/svnroot/optflux optflux

= AIBench Introduction =

AIBench is a lightweight, non-intrusive, MVC-based Java application framework that eases the connection, execution and integration of operations with well-defined input/output. This basic idea provides a powerful programming model to fast develop applications given that:
	
*The logic can be decoupled from the user interface.  	
*The interconnection of operations can also be decoupled based in the idea of "experiments".  	
*The programmer is forced to "think-before-programming", easing the code reuse.  

==Philosophy==

The AIBench platform was conceived to facilitate the development of a wide range of applications based on generic input-process-output cycles where the framework acts as the glue between each task. The framework manages three key concepts that are constant in every AIBench application: operations, data-types and views that realize the MVC design pattern. The developer only needs to focus on how to separate and structure the problem specific code into objects of these three entities. The framework will carry out the rest of the work to generate a completely executable final application, including:
   	
*Automatic generation of a GUI, where the user is allowed to select and execute the implemented functionality;  	
*Automatically retrieving the user parameters of a given operation when needed. These parameters could be both primitive values (numbers, strings, booleans) or any complex data-type previously created by an operation;  	
*Executing operations, gathering the results and keeping them available in a shared area for further use;  	
*Displaying the results through custom or default views (AIBench pack- ages with two default views for data-types);  	
*Keeping track of all the operations executed together with the information needed to repeat the same (or modified) workflow in the future (history, logging and script generation capabilities).  

Programming over AIBench is a lightweight task, since it makes use of Java Annotations, thus easily enforcing the MVC model upon the programmers.

==Operation Model==

An AIBench operation is a simple Java class with some annotations that define its INPUT/OUTPUT. For example: 

[[Image: aibench_ports.png]]

The example defines an Operation with three ports: the first two are INPUT ports and the last one is an OUTPUT port.

The idea is to isolate the logic and only the logic in Operations. 
The AIBench Core will receive the user requests and start the execution of the Operation. The ports will be called with the correct parameters and the results will be saved (see clipboard), but the programmer doesn't need to do any of these tasks.
With these annotations (plus a '''plug-in descriptor'''), AIBench knows everything it needs to:
   	
*Deploy these operations in menus.  	
*Generate input dialogs to invoke them.  	
*Save the results to give the possibility to forward them to other operations.  

Users/programmers can define their own data-types as the INPUT/OUTPUT of their operations (in-memory representation of data, trained neural networks, results, etc). Of course, the data-types don’t need to inherit from/implement anything. These data-types are specific of the desired domain, and AIBench only keeps track of them to give you the possibility to forward them from the output of an operation to the input of another. This is achieved by the clipboard mechanism.

=== The clipboard ===

The “clipboard” is the mechanism that allows the integration between operations. It works in the following way: all the results generated through the execution of Operations will be saved in the clipboard, which is a structure that keeps these data objects classified by their Java classes. This structure allows the user to forward the data generated with an operation to the input of the next one.

== The Workbench user interface ==

AIBench provides a Java Swing GUI (Graphical User Interface), called Workbench, that allows the user to request the execution of operations. The main features of the Workbench are:

* Deployment of the available Operations in menus. The Operations also define a logical path such as /load/csv/loadCSVFile used by the Workbench to create a menu hierarchy following those logical paths.
*Dynamic generation of input dialogs. When the user requests the execution of a given Operation, the Workbench generates an input dialog reflecting the input ports defined in that Operation. Depending of the data-type of each port, the control showed may change (see Dynamic generation of input dialogs).
* User's input validation. It uses the validating method provided in the operation (if there is one) to stop the user if the validation didn't succeed (see Validating the user input).
* Monitoring the process of the Operation's execution. The more monitoring information the Operation provides, the more information will be displayed (see Providing progress information).
* Display the results of an Operation. The Workbench provides a default View of the results, but you can provide more sophisticated custom components associated with a Data-type to display its information.

[[Image:workbench.png]]

he figure shows a snapshot of the OptFlux Workbench. On the left side, you can see the '''Clipboard''' tree where the operations and results are shown. On the right side, you can see the '''views''' for the results. These are displayed when a result with a valid view is clicked in the Clipboard. In the bottom-right zone there is a memory monitor, a Logging monitor and a Plug-in Manager.

=== Dynamic generation of input dialogs ===

Currently the dynamic generation of dialogs, maps Data-types with controls following the policy of the following table.

<table border="1" cellspacing="0" cellpadding="4" width="100%" bordercolor="#000000"> 	 	 	<tr valign="top"> 		<td width="50%" bgcolor="#000000"> 			<p class="western"><strong style="color: #ffffff">Data type</strong></p> 		</td> 		<td width="50%" bgcolor="#000000"> 			<p class="western" align="justify"><strong style="color: #ffffff">Control 			used</strong></p> 		</td> 	</tr> 	<tr valign="top"> 		<td width="50%"> 			<p class="western"><font size="2">Primitive Type (int, float, 			double, char)</font></p> 		</td> 		<td width="50%"> 			<p class="western" align="justify">Text 			field</p> 		</td> 	</tr> 	<tr valign="top"> 		<td width="50%"> 			<p class="western"><font size="2">Boolean</font></p> 		</td> 		<td width="50%"> 			<p class="western" align="justify">Check-box</p> 		</td> 	</tr> 	<tr valign="top"> 		<td width="50%"> 			<p class="western">Enum type (Java 1.5)</p> 		</td> 		<td width="50%"> 			<p class="western" align="justify">ComboBox with each option</p> 		</td> 	</tr> 	<tr valign="top"> 		<td width="50%"> 			<p class="western">A class with a constructor with 			one parameter of type String (primitive wrapper, String...)</p> 		</td> 		<td width="50%"> 			<p class="western" align="justify">Text 			field</p> 		</td> 	</tr> 	<tr valign="top"> 		<td width="50%"> 			<p class="western"><font size="2">java.io.File</font></p> 		</td> 		<td width="50%"> 			<p class="western" align="justify">Text 			field with a “Find...” button that brings a file chooser 			dialog</p> 		</td> 	</tr> 	<tr valign="top"> 		<td width="50%"> 			<p class="western">Other class (can only take the 			value from the CLIPBOARD)</p> 		</td> 		<td width="50%"> 			<p class="western" align="justify">Combo 			box with the instances of the same class available in the 			clipboard</p> 		</td> 	</tr> 	<tr valign="top"> 		<td width="50%"> 			<p style="margin-bottom: 0cm" class="western">Array</p> 			<p class="western"><br> 			</p> 		</td> 		<td width="50%"> 			<p class="western" align="justify">The 			control inferred with the above criteria, plus a list and an 			“add” button to put elements in the array</p> 		</td> 	</tr> </table>

The generation of dialogs is very powerful and can generate complex dialogs like this one:

[[Image:workbench2.png]]

== Plug-in Architecture (and the importance of the plugin.xml file) ==

The AIBench framework is powered by a versatile plug-in engine. This plug-in engine is ready to accept modification at several levels:
   	
*SERVICES PROGRAMMER - out of scope
*CORE PROGRAMMER
**CORE: Manages the operations, invoking them and keeping track of their results and invocation history.  	
**WORKBENCH: Implements a Swing based GUI and is responsible of the dynamic generation of input dialogs.   	
*PLUG-INS PROGRAMMER:
**PERSONAL PLUGINS: Here you put your operations, classes of your data-types and custom views. This is the level where the OptFlux plug-ins are developed. In fact, the entire OptFlux workbench is nothing more than a very powerful set of AIBench plug-ins.  

[[Image:aibench_plug.png]]

In summary, the Operations programmer builds this type of artefacts:

* '''Operations'''. The units of logic.
* '''Datatypes'''. Normal Java classes used as input and output of the Operations.
* '''Views'''. Classes that inherits from JComponent and are used to display the Data-types inside the Workbench.

This is in fact an abstraction of the '''Model-View-Controller (MVC)''' Design Standard:

[[Image:workbench3.png]]

AIBench/OptFlux uses a plugin engine behind the scenes to provide advanced capabilities such as dynamic discover and load of new Operations by only restarting the application. You need to know the basics of this engine in order to develop Operations/Plug-ins for OptFlux.

# A plugin engine is used to create applications based in software modules, called plugins. This paradigm follows these rules:
#* A plugin is a set of classes, isolated (by default) from the rest of the classes belonging to other plugins.
#* A plugin can define extension points (the yellow circles in Figure 5). An extension point is a place where other plugins can be connected to and then discovered and used at run-time. Optionally, an extension point could establish a Java interface that must be implemented by the plugins connected to it.
#* A plugin can use the classes from other plugin only if a dependency from the first to the second has been defined.
#* AIBench contains two basic plugins: the '''CORE''' and the '''WORKBENCH''', communicated internally by an extension point (the top one in the last figure), but this is out of the scope of this document.
# Also the CORE implements the extensible AIBench Operation Model by the definition of an extension point called '''aibench.core.operation-definition'''. 
#*'''To add Operations to AIBench/OptFlux''', you have to put them in a plugin and connect it to this extension point. There is not any required interface to implement.
# The WORKBENCH implements the Workbench user interface and also defines an extension point called '''aibench.workbench.view'''. To register a view component associated with a Datatype, you have to put your component in a plugin and connect it to this extension point. There is not any required interface to implement.
#*The user Datatypes have to be placed inside a plugin, but this plugin doesn't need to be connected to any extension point. (Please note that if some of your Operations use these Datatypes and reside in other plugins, they must depend on this plugin).
# You can put your Operations, Views and Datatypes in one, two or more separated plug-ins, based on your own design decision. The only rules that have to be followed are:
#* If there are Operations and/or Views in a plugin, this plugin must be connected to the properly extension points as it was explained before.
#* If the Views and/or Operations in a plugin make use of the Data-types located in other plugin, this plugin must depend on the Data-types plugin.
#* The connection and dependency between plugins is made through the '''plugin.xml''' file present in every plugin.
 
'''[[The_Plugin.xml_File | TO UNDERSTAND THE STRUCTURE OF THE plugin.xml FILE, FOLLOW THIS LINK]]'''

= OptFlux Architecture =

Version 2.3 (first fully open version of OptFlux) is composed of 5 inter-related projects, all of which are of major importance to OptFlux.

* ''''Utilitites''' - General utilities and datastructures developed at our group. This is used by most of our Projects as support.
* '''Solvers''' - A generic package of interaction between Java and some common LP, MIP and QP solvers. It supports interaction with QPGen, GLPK, CLP and CPLEX.
* '''JECoLi''' - The Java Evolutionary Computation Library. Our own Evolutionary Computation / meta-heuristics library. Find more at [http://darwin.di.uminho.pt/jecoli the JECoLi webpage].
* '''Metabolic''' - The metabolic package is the backbone of the OptFlux application. All individual API's for interaction with the operations/methods of OptFlux are herein implemented. Including MOMA, ROOM, FBA, rFBA, pFBA, etc...
* '''OptFluxCore''' - The glue between all the last and a specialization of the AIBench platform. OptFluxCore provides Graphical User Interfaces (GUIs), intuitive operations and datatypes to easily interact with all the methods provided by the Metabolic package. It also provides the plug-in engine allowing for users to expand OptFlux to their own needs.

Focusing on the '''OptFluxCore''' project, we have 6 standard plug-ins that provide all the basic functionalities in the release version.

This six plug-ins are the following:

* '''optflux.core''' - the core datatypes, viewers and operations to load/export and interact with models in several formats
* '''optflux.simulation''' - simulation related datatypes, operations and views. Wild-type, Gene and Reaction KO. (FBA, MOMA, ROOM, FVA, etc...)
* '''optflux.optimization''' - optimization specific datatypes, operations and views (Gene and Reaction KO optimization)
* '''optflux.biovisualizer''' - our own visualizer for biochemical networks. Support for CellDesigner layouts
* '''optflux.saveloadquit''' - just a save / load / quit project dedicated plug-in. Datatype agnostic as long as data is serializable.
* '''optflux.extraviewers''' - some extra viewers that we decided to include in the core release.

= Your first basic plug-in =

Go to [[Developers_First_Plugin]]!

= Deep into the OptFlux Specifics =


== Operations in OptFlux ==


== The Datatypes of OptFlux ==


== Views in OptFlux ==


= Deployment and versioning =


= How To's =


== Accessing data from the clipboard ==


== Performing a simulation and retrieving results ==


== Creating a tabular view for your data ==


== Performing an Optimization Procedure ==


== Invoking other operations from your own ==


== Adding results from your operation to the Clipboard ==


== Developing your own GUI for an Operation ==