====== Euphrates ======
Euphrates is a flow execution engine written in [[wp>Java_(software_platform)|Java]]. 
The purpose of Euphrates is to simplify development of highly concurrent and distributed Java applications.
===== Product components =====
  * Flow editor - Eclipse plug-in for editing flow definitions.
  * Specification - interfaces and foundation classes for constructing flows.
  * Engine - Implementation of specification interfaces.
===== License =====
[[wp>LGPL]]
===== Version =====
[[http://www.hammurapi.com/mantis/changelog_page.php?project_id=7|1.2.0]]

===== Value proposition =====
Utilize modern multi-core computers better leveraging data and task parallelism without having to deal explicitly with threading, synchronization, and data consistency.

===== Requirements =====
  * [[http://java.sun.com/javase/6/|Java 6]].
  * [[http://www.eclipse.org|Eclipse]] 3.5 for the flow editor plug-in.
===== Resources and downloads =====
==== Specification ====
  * [[http://www.hammurapi.com/products/euphrates/com.hammurapi.flow.zip|Jar files]].
  * [[http://www.hammurapi.com/products/euphrates/com.hammurapi.flow-src.zip|Sources]], includes Javadoc, model documentation, and jar files.  
  * [[http://www.hammurapi.com/products/euphrates/doc/model/index.html|Flow model documentation]]. The model extends [[products:config:start]] model.
  * [[http://www.hammurapi.com/products/euphrates/doc/api/index.html|Javadoc]].
  * [[products:update_site:start]] - Editor installation.
==== Implementation ====
  * [[http://www.hammurapi.com/products/euphrates-impl/com.hammurapi.flow.runtime.zip|Runtime jar files]], including specification jars.
  * [[http://www.hammurapi.com/products/euphrates-impl/com.hammurapi.flow.runtime-src.zip|Sources]], includes Javadoc, and jar files.
  * [[http://www.hammurapi.com/products/euphrates-impl/doc/api/index.html|Javadoc]].
==== General ====
  * [[http://www.hammurapi.com/bb/viewforum.php?f=5|Discussion forum]].
  * [[http://www.hammurapi.com/mantis/|Issue tracking]].
  * [[http://www.hammurapi.com/mantis/roadmap_page.php?project_id=7|Roadmap]]


===== Concepts =====
{{:products:euphrates:euphrates_concepts.png|}}
==== Thinking in flows ====
Java developers think in objects, object associations, method invocations, inheritance, polymorphism, etc. For a number of scenarios the flow paradigm is a better fit. Flow developers think in terms of processing nodes, which are objects, and data and control flowing concurrently between nodes through transitions.

==== Back-end ====
Back-end is an object to which the flow routes outbound invocations. It is purposed to simplify integrating flows into Java applications. 
==== Facade interface ====
If facade interface is set for the flow, then the flow creates a dynamic proxy implementing the interface. Proxy method invocations are routed to flow pins with matching names. The purpose of the facade interface is to simplify integrating flows into Java applications.
==== Flow ====
Flow is a collection of flow elements - nodes and transitions. Flow is itself a node, so flows can be nested.
==== Invocable ====
[[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/Invocable.html|Invocable]] is a receptor of invocations (activations). Transition starts and node inputs are invocables.
==== Invocation ====
Euphrates invocation extends semantics of Java method invocation. It consists of:
  * Flow state, maps to the ''obj'' argument of ''[[http://java.sun.com/javase/6/docs/api/java/lang/reflect/Method.html#invoke(java.lang.Object,%20java.lang.Object...)|Method.invoke(Object obj, Object... args)]]''.
  * Positional arguments, maps to the ''args'' argument of ''Method.invoke(Object obj, Object... args)''.
  * Named arguments - property sets.
  * Contextual information.

==== Invoker ====
[[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/Invoker.html|Invokers]] invoke/activate invocables. Transition ends and node outputs are invokers.
==== Node ====
[[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/Node.html|Nodes]] are primary processing units. A node has one or more pins. Nodes are activated by invocations arriving from incoming transitions. 
==== Transition ====
[[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/Transition.html|Transitions]] connect node pins and pass invocations between pins/nodes. Transitions can modify invocation data along the way, stop invocation propagation, or perform several invocations of target invocable in response to incoming invocation.  
==== Pin ====
Pins are node connection points. Each pin can have multiple inbound and outbound transitions. Nodes can implement different merge/join logic for incoming invocations. Euphrates Engine provides a [[http://www.hammurapi.com/products/euphrates-impl/doc/api/com/hammurapi/flow/runtime/impl/Joiner.html|helper class]] for implementing join/merge logic.

==== Property set ====
[[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/PropertySet.html|PropertySet]] is a set of name/value pairs, similar to ''java.util.Map''. The distinguishing features of Euphrates property sets are:
  * Asynchronous/delayed/lazy computation of values. Node or transition can put uncomputed value to a property set (''java.util.concurrent.Callable'') for later retrieval in other nodes/transitions. The property set will calculate the value asynchronously in a separate thread (for ''cook()'' methods) or on demand (for ''lazy()'' method).
  * Chaining of property sets with forward-only modification semantics.
==== Synapse ====
Synapse is an interceptor of invocations. Synapses are provided by the flow engine. Synapses are responsible for:
  * Infinite loop detection.
  * Dispatching a work request (processing of invocation by invocable) to a worker ([[wp>Task_parallelism|Task parallelism]]). It can be execution in a separate thread by a ThreadPoolExcecutor, or writing a work request to a database for manual execution, or sending a work request to another system over HTTP or JMS.  
  * Property set chaining. 
  * Converting a single invocation to zero or more invocations if one or more arguments are [[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/TokenIterable.html|TokenIterable]] ([[wp>Data_parallelism|Data parallelism]]). 

===== Contracts =====
This section describes responsibilities of flow developer, flow engine and client code.
==== Flow developer ====
Flow developer is responsible for
  * Implementation of flow, node, and transition classes. 
  * Creation of a flow definition file.
==== Client code ====
  * Loads flow definition (see [[products:config:start#client_code_application|Configurator client code]]).
  * Compiles flow definition to [[products:config:start]] definition, if it is not yet compiled, with [[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/FlowCompiler.html|FlowCompiler]].
  * Instantiates the flow as shown in the aforementioned Configurator client code example. Client code shall put appropriate implementations of [[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/SynapseFactory.html|SynapseFactory]] and [[http://www.hammurapi.com/products/euphrates/doc/api/com/hammurapi/flow/runtime/PropertySetFactory.html|PropertySetFactory]] to achieve desired qualities of service. E.g. 
    * Property sets can be in-memory or persistent. 
    * How many threads property sets use for "cooking" of values.
    * Synapses may dispatch invocations to be executed in the caller thread, multiple threads, or on multiple machines in the network.
  * Sets flow back-end object (optionally).
  * Activates the flow either through the facade interface or directly. 
==== Flow engine ====
  * Instantiates and configures flow, transitions and nodes according to definition.
  * Connects transitions to pins and inserts synapses.
  * Creates facade interface proxy, if the flow uses facade interface.
===== References =====
  * [[http://www.eclipse.org/modeling/gmf/|Eclipse Graphical Modeling Framework]] can be used to generate diagram editors from Euphrates flow model or its extensions.
  * [[http://www.jgraph.com/jgraph.html|JGraph]] can be used to create standalone or applet diagram editors.
  * More open source graphing libraries on [[http://www.manageability.org/blog/stuff/open-source-structured-graphics-libraries-in-java/|www.manageability.org]].
  * [[wp>Petri_net|Petri nets]].