Home

WADE USER GUIDE

Contents

1. 30 Default 30 DF registration A WADE agent extending WadeAgent Imp1 automatically registers with the DF providing a DFAgentDescription that allows the Control Agents to restart it in case of unexpected failure either of the agent itself or of the container host the agent lives in Such DFAgentDescription includes among others the agent type role class name location host and all startup arguments received by the agent Thanks to this registration it is possible to search agents on the basis of their type and role The com tilab wade utils DFUtils class provides the searchAnyByType searchAllByType searchAnyByRole and searchAllByRole utility methods to do that very easily Agent attributes runtime inspection and management The WadeAgentImpl class provides an embedded mechanism that allows exposing some agent attributes and make them readable and possibly modifiable at runtime with minimal effort In order to make an attribute readable at runtime it is sufficient to have a getter method annotated by means of the AttributeGetter annotation as exemplified below QAttributeGetter name The name of the book I m trying to buy public String getTargetBook return targetBook In order to make an attribute not only readable but also modifiable it is sufficient to add a setter method annotated by means of the AttributeSetter annotation as below AttributeSetter public void setTargetBook String tb t
2. t lt property name configurationgPath 1 value project home cfg configuration gt i 1 4 lt properties gt i lt agentType gt 1 bookTr ee 1 L I src m workflow Book Trading i src workflow sources i i Gfany LLL LLL LLL LLL L LLL LL LLL LLL LLL 12 224 classes i L L cfg l L main properties 1 Book Tradi 1 1 1 types xml i 00K acing i mee roject configuration configurations i L L L L L L 1 L L L 1 Figure 10 Project property file The meaning of the class loader root property of the Control Agent type is described in more details in next section Finally it should be noticed that while the Main Container is actually part of the application and therefore must be launched specifying the project name as described above the BootDaemon is fully independent from the application and will always be launched by simply typing startBootdaemon 21 WADE USER GUIDE 2 7 Hot deployment of workflows As mentioned in 1 3 WADE workflows are implemented as Java code In order to support workflow hot deployment i e the possibility of adding new workflows and modifying existing ones without the need to tearing the system down an ad hoc ClassLoader is used to load them Moreover since agents executing workflows are typically scattered across different containers for each container there is an instance
3. HEURE S REIS aaa Pee bundles 40 5 2 Agent and containers fault tolerance 4 ce ee ecce ecce eee ee eee sees esee ose eese e eese tete see 40 WADE USER GUIDE 1 Introduction WADE Workflows and Agents Development Environment is a domain independent software platform built on top of JADE http jade tilab com a popular open source middleware conceived to facilitate the development of distributed applications based on the agent oriented paradigm Readers that are not familiar with JADE are encouraged to look at the JADE Administration Tutorial http jade tilab com doc tutorials JADEAdmin index html and if they have programming skills at the JADE Programming Tutorial for Beginners http jade tilab com doc tutorials JADEProgramming Tutorial for beginners pdf before going through the advanced sections of this document As depicted in Figure 1 JADE provides a distributed runtime environment the agent and behaviour a task performed by an agent abstractions peer to peer communication between agents and basic agent lifecycle management and discovery mechanisms WADE adds to JADE the support for the execution of tasks defined according to the workflow metaphor and a number of mechanisms and components that help managing the complexity of the distribution both in terms of administration and fault management In principle WADE supports notepad programming in the sense that there is no hidden stuff that deve
4. agentType gt lt agentType description Configuration Agent className com tilab wade cfa ConfigurationAgent role Administrator gt lt properties gt lt property name configurationsPath value cfg configuration gt lt properties gt lt agentType gt lt agentType description Runtime Allocator Agent className com tilab wade raa RuntimeAllocatorAgent dministrator gt W role A lt agentType description Workflow Status Manager Agent className com tilab wade wsma WorkflowStatusManagerAgent role Administrator gt lt agentType description Event System Agent className com tilab wade esa EventSystemAgent role Administrator gt agentTypes gt atform gt From the snippet above it can be noticed that the types xm1 file also allows the definition of agent roles the WADE default types xm1 file defines 2 agent roles Administrator and Workflow Executor An agent role can be seen as a macro type and many agent types can refer to the same agent role As for agent types also for an agent role it is possible to specify properties These properties will be inherited by all agent types that refer to that agent role The agent type and agent role abstractions provide the following advantages Application configuration files refer to agent types instead of agent class names that are typically less friendly to understand and remember All configuration parameters tha
5. argument test Parameter whose value is test value It should be noticed that the specification of an Agent Pool is very similar to the specification of an Agent A part from the size attribute however Agent Pools are not associated to a specific host and container WADE will take care of starting the agents of a pool in the available containers according to agent allocation policies More in details when executing the StartupPlatform action see section 2 2 the Configuration Agent first creates all containers and agents explicitly indicated in the target configuration and then for each agent pool if any delegates the creation of agents to the Runtime Allocator Agent RAA The latter already briefly mentioned in section 2 1 manages a set of agent allocation policies and whenever an agent must be created and there is no explicit indication about the container where to start it as in the case of agents in a pool it is requested to create that agent according to its policies 39 WADE USER GUIDE 5 1 1 Agent allocation policies Agent allocation policies managed by the RAA are specified in an XML file called raa xm1 and located in the c g raa directory The snippet below provides an example of how the raa xm1 file looks like allocationRules lt allocationRule gt lt Match all agents of type Foo with argument argl set to Bar gt lt condition gt type Foo arguments argl Bar lt condition gt lt A
6. be stored in the same DB without duplicating the same configurations in two different files 3 4 Workflow inheritance Considering the landscape of workflow management tools one of the most characterizing features of WADE is certainly the possibility of creating new workflows by extending existing ones In facts while the workflow approach is intrinsically procedural inheritance is a typical characteristic of Object Orientation The simplest extension mechanism is based on Java class inheritance being WADE workflows Java classes it is possible to redefine the methods associated to the process activities thus modifying the related operations according to the needs of the extended workflow Similarly it is possible to redefine the methods that implement transition conditions Beside that basic extension mechanism however WADE allows modifying the very flow of the parent process In order to support that the WorkflowBehaviour class provides the deregisterActivity andderegisterTransition methods that in conjunction with the registerActivity and registerTransition methods described in section 3 2 1 allows modifying the process execution flow at will For instance we could create an extended version of the Cof feeProcess presented in section 3 2 1 as shown in Figure 17 The Sweet Coffee Process adds the AddSugar activity and the related transitions Moreover it removes the transition from the Prepare activity to the Pour activity The defineA
7. how to install and use it is outside the scope of this document The basic WADE Management Console is implemented as an agent com tilab wade cfa ManagementAgent and is activated by default on the Main Container In order not to activate it it is sufficient to remove the ManagementAgent from the list of agents to be activated at Main Container bootstrap in the c g main properties file Having started the Main Container and the BootDaemon as described in 2 3 2 the WADE Management Console should appear showing that the status of the application is DOWN see Figure 7 15 WADE USER GUIDE WADE Platform Configurations Code b ou 12 e ap Platform status down status f Current State Qo Rative active with warnings Qo Starting Q Shutdown in progress 9 Q Down Figure 7 The basic WADE Management Console By clicking on the Import Configuration button or selecting the Configurations gt Import Configuration menu item it is possible to select and import the sample application configuration Platform Configurations Code p n a amp ap Platform status down status Current State Qiu Qs with warnings Select configuration name oO Starting QO Shutdown in progress Q Error o Down Figure 8 Importing a configuration Having imported a configuration it is now possible to activate the application note that at this point this is just a dummy application w
8. of execution failure instead of an INFORM message a FAILURE message will be sent back holding the failure reason 35 WADE USER GUIDE 4 1 Launching workflows from code the DispatchingCapabilities class In order to request an agent to execute a workflow from your code it is of course possible to create the ExecuteWorkflow object and to implement a FIPA request protocol with the intended executor as described in previous section However WADE provides a ready made class called DispatchingCapabilities that simplifies that The code snippet below taken and simplified from the WorkflowTracer example included among the WADE examples distribution shows how to use it Create a DispatchingCapabilities instance and link it to the local agent DispatchingCapabilities dc new DispatchingCapabilities dc init this try Create the WorkflowDescriptor specifying the workflow to execute and the parameters WorkflowDescriptor wd new WorkflowDescriptor tracer ThreeStepWorkflow Map String Object parameters new HashMap lt String Object gt parameters put message Hello World wd setParametersMap parameters Launch the workflow dc launchWorkflow executor wd new WorkflowResultListener public void handleAssignedId AID executor String executionId The executor correctly loaded the workflow and started the execution public void handleExecutionCompleted List results AID executor Stri
9. of this ClassLoader managed by the Control Agent controlling the container itself More in details the property class loader root of the Control Agent type defines the directory Xproject home deploy by default where jar files containing workflows must be placed As shown in Figure 11 jar files containing new modified workflows can be deployed at runtime by means of the WADE Management Console amp WADE lof xi Platform Configurations Code B a 2 amp Deploy Se Launcher status Current State Platform status starting status 8 Platform status active status Figure 11 Workflow hot deployment using the WADE Management Console NOTE It should be noticed that due to the Java ClassLoader delegation model if the class implementing a workflow is included in the application classpath it is not loaded by the WADE Control Agent ClassLoader but by the Java System ClassLoader As a consequence it will not be possible to update it by means of the WADE workflow hot deployment mechanism 22 WADE USER GUIDE 3 Workflows In this section we go in more details in the most relevant feature that WADE provides i e the support for defining system logics according to the workflow metaphor More in details in this chapter we present how workflows are implemented in WADE while in next chapter we will describe how to execute them Instead this guide does not provide a section focusing on how to use Wolf to create workf
10. particular the registerActivity and registerTransition methods allow adding activities and transitions to the process Even if in principle this is not strictly necessary it is highly recommended to register all process activities ina private void method called defineActivities and all transitions ina private void method called defineTransitions This is because the workflow graphical editor included in Wolf searches for these methods to detect process activities and transitions to show The registerActivity method gets the behaviour implementing the registered activity as an argument More in details there are different classes corresponding to the different types of activity presented in 3 1 These are CodeExecutionBehaviour to be used to register a code activity ToolExecutionBehaviour to be used to register a tool activity SubflowDelegationBehaviour to be used to register a subflow activity WebServiceInvocationBehaviour to be used to register a WebService activity and so on The actual operations to be performed in a registered activity no matter of its type are specified in avoid method of the workflow class That method has a name constructed by adding the execute prefix to the name of the corresponding activity Each activity behaviour is just responsible for invoking the related method when the activity is visited Similarly the registerTransition method gets a Transition object as an argument In case the transition has an as
11. Agent class agents extending WadeAgentImpl should redefine the agentSpecificSetup method rather than setup to perform their application specific initialization operations More in details the WadeAgentImpl class manages the following aspects Arguments passed to agents at startup time As described in 2 2 agents that make up a WADE based application are specified in the application configuration XML file That file also allows specifying startup arguments to be passed to each agent instance as exemplified in the snippet below container name Execution Node agents agent name john type Book Buyer Agent parameters lt parameter key TARGET BOOK lt value gt The Lord of the Rings lt value gt lt parameter gt lt parameter key MAX PRICE lt value gt 50 lt value gt lt parameter gt lt parameters gt lt agent gt lt agents gt lt container gt The WadeAgentImpl class makes available such arguments to subclasses in the form of a protecetd Map called argument s For instance refering to the snippet above the Book Buyer Agent can retrieve the target book to buy by just doing String targetBook String arguments get TARGET BOOK Furthermore methods to access agent arguments as String boolean int and so on managing all necessary format conversions are directly provided as exemplified below 19 WADE USER GUIDE int maxPrice getIntArgument MAX PRICE
12. Bue Window Hap BOSS 9 0 Q 0 AGr P seu1 HB Package SS 7 D f WorticwttanuttenasmAgertjere SE import java util ArrayList import jera utii Lircs import java utir logging Level import tom tilab wade cfa carology ConfiguraticenOatclagy import ccm tilab wada conmcns Agentlinitialisaticn xceptian import con tilsb wade commons Attribgtecetcer import com cilab wade commons WedeLgentImpl import com cilab wade performer Constants import com tilab wade performar cntology TbawWorkflcw tmport com tilab wwde performer ontclogy WorkflcwManagementOnto2logy import com cilab wade utils GUiDGenerstor import ccom cilsb wade wsma oncology CleanEmecuticns import com tileb wade vams cntology GetExecution import cum tilab wada wama cntolcgy Getfendingfxecutiaona import ccm tilab wsde wwma ontclogy CetSerialiredState import com tilab wede wsma ontology GetSessionExecutians import ccm cilab wade wsnma ontolocy QuervExecuricns External System External System Figure 15 The WadeServices Gateway Container in the Wolf AgentTree view 3l WADE USER GUIDE Q a warum se nate terre Wotton ieuVerezeriger ere kipe ae o DOE o s EN ce Fie di Source fetectey Newgate emit Project Wee Rae Window iep 7 amp S O G vo P t nE Pechage betse Noidan ta rage Agan usa 3 ara util Arza Figure 16 Exposing a Web Service using Wolf 3 3 3 Long Running workflows With the te
13. EventType description CoffeeReady gt lt parameters gt lt Parameter name requestId type java lang String gt Parameter name cupsNumber type java lang Integer gt lt parameters gt lt EventType gt lt customEventTypes gt Each EventType has a description that acts as the event type identifier plus a set of Parameters each one with a name and a type the fully qualified class name to be used for values of that parameter When adding a Wait Event Activity in a workflow the developer is requested to specify the type of the expected event one of those included in the customEventTypes section of the types xmdl file and optionally an expression that precisely identifies which specific event the workflow intends to receive For instance with reference to the snippet above a workflow that previously activated the preparation of a coffee can block until a Cof feeReady event is received with parameter requestId equals to a given value As usual it is possible to store the information parameters carried by the received event as it happens for e g subflow or web service output parameters This is done in the a terXXX method as exemplified below private int nCups public void afterWaitForCoff GenericEvent ev nCups int ev extract cupsNumber As briefly mentioned in 2 1 internally events are managed by the Event System Agent However unless they have specific requirements dev
14. More in details the Boot Daemons are shared among all applications hosted by a given WADE platform On the other hand each application will have its own Main Container and peripheral containers When the application is down only the boot daemons one per host and the Main Container with the JADE AMS DF and the WADE CFA are up and running In this status it is possible to request the CFA to import an application configuration ImportConfiguration action of the Configuration Ontology An application configuration is a file that specifies according to an XML Look at the Javadoc of the classes included in the com tilab wade cfa ontology for details about the parameters to be specified in the actions of the Configuration Ontology 11 WADE USER GUIDE based format which hosts are involved which containers must be executed in each host and which agents must be activated in each container The snippet below shows an example of an application configuration file involving a single host the local host with two containers called Administration Node and Execution Node the first one holds the Workflow Status Manager Agent and the Event System Agent while the second one holds two Workflow Engine agents lt xml version 1 0 encoding UTF 8 gt lt platform description This is a sample configuration name Sample gt lt hosts gt host name localhost gt lt containers gt lt container name Administration Node gt lt ag
15. Suite can be downloaded from the WADE download page of the WADE web site http jade tilab com wade in both bynary and source form In order to install them it is sufficient to unzip the bynary distribution packages as described below WADE Unzip the WADE distribution package somewhere on your disk The structure that is produced is described in section 2 3 Persistence Add On Unzip the Persistence Add On distribution package in the same directory where WADE was unzipped Wolf As all Eclipse plug ins the Wolf bynary distribution package must be unzipped in the home directory of your Eclipse installation Web Administration Console Unzip the Web Administration Console bynary package in the webapps directory of your servlet container WadeServices Unzip the WadeServices bynary package in the webapps directory of your servlet container WADE USER GUIDE 2 WADE based applications 2 1 Architecture This section presents the components that together with the basic components provided by JADE and summarized in 1 4 make up the WADE architecture As depicted in Figure 5 from the architectural point of view a WADE based application appears to be quite similar to a purely JADE based application It runs on a set of hosts each one holding one or more JADE containers and as usual the Main Container hosting the JADE AMS and DF must be activated first with other containers registering to it at bootstrap time Application specific age
16. WADE USER GUIDE WADE USER GUIDE USAGE RESTRICTED ACCORDING TO LICENSE AGREEMENT Last update 5 December 2013 WADE 3 3 Authors Giovanni Caire Telecom Italia S p A Copyright C 2010 Telecom Italia Copyright C 2011 Telecom Italia WADE Workflows and Agents Development framework is a software platform that facilitates the development of distributed multi agent applications where agent tasks can be defined according to the workflow metaphor From a different point of view WADE can be seen as an agent oriented Workflow Engine suitable to be used for business process orchestration This document gives an overview of the WADE platform presents its architecture and main functionalities and outlines the conceptual model underlying it Two major aspects of the platform are described the execution model based on the workflow metaphor and the configuration and control features designed to hide the complexity of the distribution WADE is based on JADE a popular open source agent oriented middleware and inherits from it a distributed topology with peer to peer networking and a software component architecture based on the agent paradigm The WADE library is free software you can redistribute it and or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation version 2 1 of the License This library is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY without
17. argetBook tb Runtime attribute inspection modification can be done by requesting an agent extending WadeAgentImpl to perform the GetAgentAttributes and SetAgentAttribute actions of the WadeManagementOntology The WOLF development environment provides a ready made GUI to inspect and modify agent attributes 2 6 Running WADE based applications In section 2 3 2 we showed how to use the WADE startup scripts to activate the WADE platform In general however a WADE based application is not only composed of workflows that can be executed on a naked WADE platform but also includes a number of classes e g application specific agents and possibly makes reference to some external libraries In order for the WADE startup scripts to include application specific jar files into the classpath it is of course possible to put them all including external libraries into the 1ib directory of the WADE installation Similarly it is possible to modify the configuration files included in the cfg directory of the WADE installation to reflect application specific configurations In general however we recommend to keep all application specific stuff separate from the WADE installation as described in the followings In this way it is possible to deal with more than one WADE based application at the same time without mixing libraries and configuration files 20 WADE USER GUIDE In order to do that it is sufficient to put a simple property file nam
18. ation and structure of WADE based applications that have to be launched using the WADE startup scripts as will be detailed in section 2 6 2 3 2 Starting up the platform In order to start the WADE platform up on a single host it is sufficient to e double click on the startMain bat file or execute the startMain sh script depending on the underlying operating system This activates the Main Container e double click on the startBootDaemon bat file or execute the startBootDaemon sh script depending on the underlying operating system This activates the BootDaemon on the local host To try WADE on more than one host WADE must be installed on all hosts and the BootDaemon must be activated on each of them 2 3 3 The Management Console In general we expect real world applications to provide their own management console possibly developed as a web application properly customized according to the addressed domain and the application requirements In order to start familiarizing with the platform however WADE comes with a minimal management console that allows performing basic administration actions such as starting and stopping an application importing and exporting configurations and deploying new modified workflows without tearing the application down this feature will be described in section 2 7 It has to be noticed the WADE suite also include a powerful web based administration console that provides a lot of additional features but
19. cally by an external system This is done including in the workflow a Wait Web Service Activity The invocation of a Web Service operation can be considered as a predefined type of event and as a matter of facts a Wait Web Service activity is very similar to a Wait Event Activity described in previous section The only difference is that the developer is not requested to select a custom event type among those defined in the types xml file but to select a Web Service operation among those exposed by the system as will be described later in this section A part from that the underlying mechanism is exactly the same and therefore as soon as the indicated WS operation is invoked the workflow is resumed and receives in its a terXXX method a GenericEvent whose parameters reflect those of the invoked operation The process to make a WADE based system expose a Web Service so that workflows can block waiting for its operations to be invoked is very simple The first step is to import the WSDL of the Web Service to be exposed This is done within Wolf the developer is requested to indicate whether the WSDL describes a Web Service to be invoked Import as client ortobeexposed Import as server In this section we focus on the second option The Import as server operation generates a new jar file in the wadeServices directory This jar file includes all the classes necessary to expose the Web Service and to manage operation parameters within workf
20. components briefly outlined in this section Web Administration Console This is a Web Application that can be installed in whatever Web Container such as Apache Tomcat and allows administering and monitoring a Wade based application deploying launching and controlling workflows creating reports on executed or running workflows and investigating problems WadeServices This is a Web Application that can be installed in whatever Web Container such as Apache Tomcat and allows Wade based applications to automatically expose Web Services When creating workflows it is possible to define steps where the execution flow suspends until a given Web Service operation is invoked typically by an external system This feature is described in section 3 3 2 Persistence Add On This additional module allows persisting the state of running workflows on a relational DB and is mandatory to execute long running workflows i e workflows that survive to a system shutdown and restart Figure 4 depicts a typical scenario for a Wade based application WADE USER GUIDE qe User RC E QA fd Developer Application Console Install Start Stop d monitor the System Deploy workflows Application specific user interaction Application specific Application Specific Components Web Service Invocations execution state Figure 4 Wade based application scenario 1 6 Download and Installation All components of the WADE
21. composted of several Containers that can run on different hosts and can contain each one a number of agents Even if this is not strictly mandatory most of the time a container corresponds to a JVM The set of active containers is called a Platform As depicted in Figure 3 a special container exists in the platform called Main Container The Main Container must be the first one to start and all other containers typically called peripheral containers register to it at bootstrap time Furthermore the Main Container holds two special agents The AMS Agent Management System that represents the authority in the platform i e it is the only agent that can activate platform management actions such as creating killing other agents killing containers and shutting down the platform Normal agents wishing to perform such actions must request them to the AMS The DF Directory Facilitator that implements the yellow pages service by means of which agents can advertise their services and find other agents offering services they need Further details on main JADE architectural components can be found in the JADE administration Tutorial http jade tilab com doc tutorials JADEAdmin index html Is registered with r r 1 Platform Network Figure 3 JADE distributed architecture WADE USER GUIDE Distribution is an important characteristic especially for applications that are expecte
22. ctivities and defineTransitions methods of the SweetCoffeeProcess class reflect these modifications 33 WADE USER GUIDE package coffee processes SWEET COFFEE PROCESS public class SweetCoffeeProcess extends CoffeeProcess public static final String ADD SUGAR ACTIVITY AddSugar private void defineActivities CodeExecutionBehaviour ceb new CodeExecutionBehaviour ADD SUGAR ACTIVITY this registerActivity ceb INITIAL private void defineTransitions deregisterTransition PREPARE ACTIVITY POUR ACTIVITY false registerTransition new Transition PREPARE ACTIVITY ADD SUGAR ACTIVITY NotEnoyghCoffee registerTransition new Transition ADD SUGAR ACTIVITY POUR ACTIVITY Code to add sugar protected void executeAddSugar throws Exception s NEW Pour AddSugar Figure 17 Workflow extension The changeActivityOrder method allows changing the order of an activity for instance an activity that is FINAL in the parent workflow and must become INTERMEDIATE in an extended workflow that adds an additional step at the end Finally all layout information can be changed at will 34 WADE USER GUIDE 4 Executing workflows As already mentioned WADE does not provide a single Workflow Engine Rather it embeds micro workflow engines into agents giving them the ability to execute tasks defined according to the workflow metaphor As a consequence launching a workflow means r
23. d to support heavy loads since a distributed application can be deployed on highly scalable hardware architectures such as blades It is clear however that administering a distributed application is more complex than administering a monolithic application unless proper tools are made available Furthermore the probability that a host crashes increases proportionally with the number of hosts the application is distributed on and proper recovery mechanisms are necessary to ensure the application can survive Clustering systems are often used for those purposes but they are typically quite expensive and difficult to configure WADE faces these problems by providing a number of mechanisms that help the administrator in e Installing the application e Configuring it tuning parameters e Activating deactivating the application spreading components i e containers and agents across available hosts according to specific needs e Monitoring runtime events and critical conditions such as disk and memory consumption e Deploying new modified system logics at runtime without system down e Automatically recovering from host container and agent faults The main mechanisms that WADE provides to hide the complexity of the distribution are described in chapters 2 and 5 that focus on the administration and fault tolerance aspects 1 5 The WADE Suite Besides the actual WADE platform and the Workflow Graphical Editor WOLF the WADE Suite includes additional
24. des a number of ready made mechanisms that are used to manage in a uniform way several aspects such as DF registration agent attributes inspection application termination and fault recovery In JADE an agent type just corresponds to a class that directly or indirectly extends jade core Agent WADE explicitly introduces the notion of agent type More in details an agent type has a name a corresponding class and possibly a set of properties that will apply to all agents of that type The agent types involved in a WADE based application are defined in a file called types xm1 located in the wade cfg directory In order to show how the types xm1 file looks like we provide below the default types xm1 file defining the WADE base types platform lt agentRoles gt lt agentRole description Administrator gt lt agentRole description Workflow Executor gt 17 WADE USER GUIDE lt agentRoles gt lt agentTypes gt lt lt pl lt agentType description Workflow Engine Agent className com tilab wade performer WorkflowEngineAgent role Workflow Executor lt agentType gt lt agentType description Control Agent className com tilab wade ca ControllerAgent role Administrator gt lt properties gt lt property name autorestart value true gt lt property name threadNumberThreshold value 300 gt lt property name class loader root value deploy gt lt properties gt lt
25. e seen nest tn sese ense etta aee 11 2 3 Getting started with the platform e ee eeee eee ee eee eeo eese eese sese se tese s tete sesso oes 13 2 3 1 WADE Distribution structure overview L2 oec oo ceto decree ned E rece da ad ants dee den n eda Dea dd 13 2 3 2 Startno Up The platform zei ennn aes E S A EA 15 2 2 5 The Management COBSDIG snes a a ssi a ina 15 2 4 Agent types and roles uoa eroe ende ria satira nee nei eaa aevi vasa Pn dev Ee edv eU a avi soss nois oses osssoossss agar gas 17 24L Using environment variables i cti oue toD Cx petet ut eiut dese aee 18 2 5 WADE Abehls eee evt v tit nete quee Ede gooi oe toss DeURN QR e Se Eye aie ab neve UO Na NEMO E FN aeu 19 2 6 Running WADE based applications 4 ceres ee eere ee eere eere esten esten aset eaae seen seen aee 20 2 7 Hot deployment of workflows iss scceisssccosvisseisexccsivecnsesecestdooessendesvesancsscessvsnonsoetssssnneudvensonetens 22 3 WORKFLOWS 2 2 ranisiveteberiseietiriiaieberseasebewiseiemestonsebirianieinatcovehawiuaduiuatunteboxouanecnd 23 3 1 The workflow Meta MOd el ue eiecit esos tknsaui goin enin phibno r eese o eain RE epe eoe eie Dae rrk aane ue 23 3 2 Workflow elements implementation eee ee ee ee eee eee eee eene eee en eee ta sete ta seen seen aa 25 3 2 1 The WorkflowBehaviour Classy is Desde ees eMe tubes Cist AM dre DU Lech on didab ecdt Mta dicic uda daa 25 3 2 2 Data Fields and Forma
26. ed lt application name gt properties into the projects directory This property file is mainly intended to specify the project home property that must point to where the project i e the application is located on the disk At this point the application Main Container can be launched by typing startMain lt application name gt A similar command line can be used in Linux Figure 10 provides an example showing how the project property file and the types xm1 file of a Book Trading WADE based application can look like With reference to that example the book trading Main Container can be launched by typing startMain booktrading bookTrading xml lib bookTrading jar Book Trading E project libraries log deploy 4 3 ES Eso Trading project workflows C project home C bookTr wade m i LI piso Pr ue Li i bin Li startMain bat startBootDaemon bat t Soswscsitecoestuce se cfg ME PER lib agentType description Control Agent 1 gt Wi acy a ade J a WADE lt properties gt jade jar libraries only zer 1 Xproperty name class loader root log value project home deploy I lt properties gt i projects lt agentType gt 1 booktrading properties i lt agentType description Configuration Agent L s 1 i lt properties gt
27. ed as a workflow Such representation is clearly extremely more intuitive with respect to a piece of software code and in general is understandable by domain experts as well as by programmers Domain experts can therefore validate system logics directly and not only on documents that most of the time are not perfectly up to date In some cases they could even contribute to the actual development of the system without the need for programming skill Another important characteristic is that being the execution steps explicitly identified the workflow engine i e a system able to automatically execute a process defined as a workflow can trace them This makes it possible to create automatic mechanisms to facilitate system monitoring Typically a workflow engine embeds ready made mechanisms to trace activities and to create reports on them Additionally when processes have to be executed within the scope of a transaction semi automatic rollback procedures can be activated in case of unexpected fault Finally since workflows are fully self documented workflow based development releases the development team of the burden of keeping documentation aligned each time design choices must be revisited to face implementation details or evolving requirements 1 2 Scope If on the one hand the workflow metaphor has a number of advantages as discussed in previous section it is in general not suitable to deal with low level operations such as data management and t
28. ee this GRIND ACTIVITY ERKOR ACTIVITY registerTransition new Transitio GRIND ACTIVITY PREPHRE ACTIVITY registerTransition new Transit 6n PREPARE ACTIVITY PUR ACTIVITY Pour LI protected void executeGrind throws Exception 1 Code to grind coffee i 1 v protected void executePrepare ApplicationList Appls throws Exception e Application prepareCoffee appls next Fill actual input parameters of applicAtion PrepareCoffee executeApplication prepareCoffee Store actual output parameters of Application PrepareCoffee protected void executePour Subflow sblf Fill actual input parameterg of process PourCoffee executeSubflow prepareCoffeg Store actual output parAmeters of process PourCoffee protected boolean checkNotEnoughCoffee Return true if we don t have enough coffee Figure 13 Workflow class structure In certain cases the execution of an activity cannot be fully carried out within a single method For instance when the execution flow reaches a WaitWebService activity before suspending it is often necessary to execute some logics to precisely define wich invocation of the indicated web service operation will actually resume the workflow For example the workflow must be resumed as soon as the notifyCoffeeReady web service operation will be invoked with parameter orderId equals to some value Of course as soon as the workflow will be r
29. elopers do not have to care about it The only important information they need to know is how to submit events to a WADE based system This is done by means of the EventChannel API included in the com tilab wade event package as exemplified by the snippet below where we show the code that could be used by the module in charge of actually preparing the coffee to submit a Cof feeReady event private EventChannel channel new EventChannel private submitCoffeeReady String id GenericEvent ev new GenericEvent CoffeeReady ev fill requestId id try channel submitEvent ev 29 WADE USER GUIDE catch Exception e e printStackTrace Events can be submitted by both external components systems and internal modules agents As a consequence the EventChannel class provides two constructors In the former case the constructor with no parameters must be used as in the snippet above that internally uses the default JadeGateway to connect to the WADE based world see the JADE documentation for details about how to initialize the JadeGateway In the latter case the constructor that takes an Agent instance as parameter must be used The Web Administration Console included in the WADE Suite provides a section to manually submit events to the system 3 3 2 Incoming Web Services In this section we describe how to block a workflow until a given Web Service operation is invoked typi
30. ents elect a new leader that takes care of restarting the dead container e Ifthe recreation of the whole container fails this is always the case when a container disappeared due to a fault of the underlying HW the leader Control Agent restarts all agents that where living in the dead container through the Runtime Allocator Agent described in section 5 1 The latter will then recreate all dead agents according to its agent allocation policies It should be noticed that the autorestart mechanism provided by WADE is only responsible for restarting the dead agents passing them the same arguments they were launched with Application developers are responsible for implementing application specific mechanisms to restore the internal state of the agents after a fault restart In order to facilitate that the WadeAgentImpl class that as mentioned in section 2 5 should be extended by all application agents provides the getRestarted method that can be used in the agentSpecificSetup method to distinguish between a normal startup and a restart after a crash 4
31. ents gt lt agent name wsma type Workflow Status Manager Agent gt lt agent name esa type Event System Agent gt lt agents gt lt container gt lt container name Execution Node gt lt agents gt agent name performerl type Workflow Engine Agent gt lt agent name performer2 type Workflow Engine Agent gt lt agents gt lt container gt lt containers gt lt host gt lt hosts gt lt platform gt Each application configuration has a name and an optional description Application configurations available for import are kept in files called lt configuration name gt xml and stored by default in the cfg configuration directory For each agent an application configuration specifies the name the type agent types will be described in section 2 3 and possibly some arguments as will be described in section 2 5 An application configuration also supports the specification of container profiles Each ContainerProfile includes either a set of JADE parameters type JADE that tune the behaviour of the container itself or a set of JAVA parameters type JAV A that tune the behaviour of the JVM hosting the container For instance if we want to create a container in a JVM using 512MB of heap we could define in our application configuration file a container profile of type JAVA as below containerProfile name Heap512M type JAVA gt properties lt property key Xmx512m gt lt prop
32. equesting an agent to execute it The interaction between the requester agent and the executor agent follwos a FIPA request protocol as depicted in Figure 18 Requester Executor Agent Agent REQUEST Load Workflow and Execute Workflow initialize input parameters AGREE Execution id Execute Workflow INFORM Result Figure 18 Workflow execution request interaction The ExecuteWorkflow action defined in the Workf lowManagementOntology as all other workflow execution related concepts mainly includes the Work lowDescriptor specifying the workflow to execute the actual parameters and optionally but specifying it is a recommended practice a session id that must be unique and that will be propagated to any subflow triggered by the workflow that is been launched If the workflow class is correctly loaded and instantiated the executor agent generates a unique execution id that can be used later on to act on the workflow e g to kill it This execution id is returned to the requester within the content slot of an AGREE message Note the difference between the session id and the execution id the former is choosen by the requester and will be preserved in subflows the latter is choosen by the executor and changes across subflows i e if a subflow is launched this will have a different execution id Once the workflow has been executed the executor agent sends back an INFORM holding the list of actual output parameters In case
33. ersistence Add On must have been added to the WADE installation this simply means unzipping the Persistence Add On distribution package in the same directory where the main WADE distribution package was unzipped 32 WADE USER GUIDE 3 3 4 The Persistence Add On The Persistence Add On allows WADE components agents to persist information on a relational Data Base by means of Hibernate Currently the only component that exploits the Persistence Add On is the Workflow Status Manager Agent i e the agent in charge of tracing the state of workflows However we expect to have other agents exploiting it in future versions By default the DB related configurations are specified in the wadePersistence cfg xml file included in the wadeSuite wade add ons persistence cfg directory This is a standard Hibernate configuration file where it is possible to define the Hibernate dialect indicating which DB to use and the connection driver URL username and password if any Of course it is possible to tell WADE to use a different Hibernate configuration file by specifying the property hibernateConfigurationFile in the global properties section of the types xml file as exemplified below lt platform gt lt properties gt lt Property name hibernateConfigurationFile value myPath myFile cfg xml gt lt properties gt lt agentTypes gt This allows for instance to make WADE internal information and application specific information to
34. erties gt lt containerProfile gt In order to activate the application it is necessary to request the CFA to perform the StartupPlat form action of the Configuration Ontology When serving this action the CFA reads the currently imported application configuration also called the target configuration and e For each host requests the associated boot daemon to launch the specified containers with the JADE and JVM configuration options defined by the JADE and JAVA container profiles if any each one with a Controller Agent on top 12 WADE USER GUIDE e For each container requests the associated Controller Agent to activate the specified agents The target configuration is kept internally by the CFA by default it is stored in a file called _target xm1 and users are not expected to act on it directly Once the application is active depending on the application needs the containers and agents distribution may change e g a new container can be launched with some agents on top to face an unexpected workload Therefore the running configuration may differ from the target configuration By requesting the CFA to perform the SaveConfiguration action of the Configuration Ontology it is possible to take a snapshot of the running configuration and make it become the target configuration In this way if the application is stopped and restarted its distribution of agents and containers will not change In order to tear down the application it is nece
35. esumed it is often necessary to execute some other logics to e g process the parameters of the web service operation that has just been invoked As a consequence for these types of activity there is not a single execute method 26 WADE USER GUIDE but a before method and an after method that will be invoked before and after the execution of the activity For instance given the WaitForCoffee WaitWebService activity the workflow class will have the methods protecetd void beforeWaitForCoffee and protecetd void afterWaitForCoffee 3 2 2 Data Fields and Formal Parameters Data Fields of a workflow process are implemented as fields of the workflow class For instance with reference to the coffee workflow shown in Figure 13 we could have a data field containing the amount of ground coffee in grams produced by the GRIND activity This is implemented as an int field of the CoffeProcess class Workflow formal parameters need to be accessed by the workflow in a similar way to data fields Therefore they are implemented like data fields as fields of the workflow class In order to let WADE know that they are formal parameters however they must be annotated by means of the FormalParameter annotation included in the com tilab wade performer package This annotation has several attributes indicating for instance the mode i e INPUT or OUTPUT or whether the parameter is mandatory default or optional For insta
36. even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE See the GNU Lesser General Public License for more details You should have received a copy of the GNU Lesser General Public License along with this library if not write to the Free S oftware Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA Java and HotJava are trademarks of Sun Microsystems Inc and refer to Sun s Java programming language and HotJava browser technologies The Workflows and Agents DEvelopment Framework WADE is not sponsored by or affiliated with SUN Microsystems Inc WADE USER GUIDE TABLE OF CONTENTS 7 INTRODUCTION m 4 1 1 W nuin re 4 1 2 SS COPD Soto acetate ted enelblt de dca thiet tede d etu ELI NE 5 13 ADDEOSCIL poscis coi sdr de ata Pesado NE ER HET o eR ARP EP NN EM RO nA Oi Ned pen PEN sses PE 6 14 Managing the complexity of the distribution ecce eese eee ee ee eren ee eren setate esten a 7 I5 The WADE Suite onion Doer E Porte a CDs coe DEM E p EDO IDEE DUE 8 1 6 Download and Installation ooi roseo nee Senor teh opo pastore aa ep ab oo pu nan eE In Po ados e soU eoa un E E pR Ra Ead auae 9 2 WADE BASED APPLICATIONS 5 ceca naiio eran a ade era ranae a aaa Gra ucc oneri a narra erae nonass 10 2 1 P Wweilicviii et opere IR basses 10 2 2 Application activation and termination eee e ceres eee eee ee eene e een
37. he process flow and a code view the usual Eclipse Java editor suitable to define execution details that are kept in synch Therefore the WADE workflow engine embedded into Workflow Engine agents is not an interpreter of a workflow description language but executes compiled Java code This on the one hand makes it extremely performant but on the other hand requires the necessary workflow classes to be available when an agent is requested to execute a workflow For this reason WADE uses ad hoc Java class loaders to allow deploying new modified workflows that become immediately executable without the need to turn the system down WADE USER GUIDE Another important characteristic of WADE workflows is that they can be extended That is it is possible to create new workflows by extending existing ones and just defining the differences This feature will be detailed in section 3 4 Finally it must be noticed that WADE does not impose that all system logics are defined as workflows Developers are free to exploit the workflow metaphor to describe those tasks for which they think it is appropriate and use normal JADE behaviours or other purely Java patterns elsewhere In certain cases one could even decide to create a WADE based application that does not use workflows at all How to define and execute workflows is described in details in chapters 3 and 4 1 4 Managing the complexity of the distribution WADE inherits from JADE a distributed runtime
38. ionPolicy base class Developers interested in defining their allocation policy according to application specific requirements just need to provide new policy classes see the javadoc of the AgentAllocationPolicy interface for details However WADE already provides a set of ready made policies such as the RoundRobinPolicy and the JavaProfileBasedRRPolicy mentioned in the snippet above that can be used to cover many realistic situations Details on how such policies work and how to configure them can be found in the related javadoc 5 2 Agent and containers fault tolerance Fault tolerance is a very important issue especially when dealing with real world application Using a distributed approach as typically happens when building an application on top of JADE WADE provides a mean to deal with unexpected HW faults JADE already includes suitable fault tolerance mechanisms such as the Main Container Replication Service described in chapter 9 of the book Developing Multi Agent Systems with JADE that allows the platform to survive to a fault of a container or host Such mechanisms however work at the platform level and not at the application level That is they ensure that the mechanisms provided 40 WADE USER GUIDE by the platform such as message delivery and agent creation destruction continue to work even after an unexpected fault of one of the hosts where a JADE based application is running Of course if an agent im
39. ith no logics as we don t have any application specific code or 16 WADE USER GUIDE workflow by clicking on the Startup button or selecting the Platform gt Startup menu item Figure 9 shows how the JADE RMA should look like once the application has started aj mag WADE JADE Remote Agent Management GUI ey File Actions Tools Remote Platforms Help amp eajg a Pie aa gg Bes elk e CEEA EOE name addresses state owner _ E3 WADE gt Main Container Administration Node CA Administration Node Wagt B esa WADE monitor Administration Node wsma WADE Execution Node CA Execution Node WADE monitor Execution Node WAL performer1 WADE performer2 WADE Figure 9 Running the sample configuration 2 4 Agent types and roles As mentioned a WADE based application is composed of a set of agents that are instances of one or more agent types As described in 2 1 WADE natively provides some agent types e g the Configuration Agent the Controller Agent the Workflow Engine Agent and so on An application often adds other domain specific agent types either extending the WADE base types Primarily the Workflow Engine Agent or directly extending their common base class WadeAgentImpl In general we recommend WADE developers not to extend the jade core Agent class of the JADE library directly As will be described in section 2 5 in facts the WadeAgentImpl class provi
40. ivity is terminated the conditions of all outgoing transitions are evaluated As soon as a condition holds the corresponding transition is fired and the execution flow goes on with the operations included in the destination activity A process can have one or more Formal Parameters defining the type of required inputs and expected outputs At process invocation time proper values must be provided for input parameters and at the end of the execution the values produced as output parameters are returned to the requester The main types of activity supported by WADE are described below Execution activities e Code activities The operations included in a code activity are specified directly by a piece of Java code embedded in the workflow process definition e Tool activities The operations included in a tool activity consist in invoking one or more external tool generically identified as Applications Applications are computational entities defined outside the workflow process and wrapped by a uniform interface Similarly to processes applications have formal parameters defining required inputs and expected outputs In general we expect applications to be provided to e g interact with an external system or appliance or to execute a ready made computation but developers are free to use the Application abstraction as they like e Subflow activities The operations included in a subflow activity consist in the invocation of another workflow proces
41. l Parameters eese vaodet etie ta dvdaer C a vine dotati oo Pea ERU ben CE Dad 27 3 2 3 BuildingBlock invocation 5 1 00sscisescsccassaccovesecoueteasesacainsaveieasvavadaudedeaesansavadsasgesaceassaveeabeaoans 27 32 4 Layout iINfOrm t OTI eos eec eosti Aaaa eee Aaa ea EN a Ae A ates dte ASAE IR E aA 28 3 3 Synchronization Activities seeesccessoesssecssecssocescooessocesoecssocesocesoosesoeessecesocesocessosesoeessecesosee 29 Slo E E EEE E ects es eben Scc oin itum itum E A 29 3 3 2 Incoming Web Services ienen ninan eea o AE ATA R Aaa A Eiaa 30 3 3 3 Long R nnng worktfloWws eSI en dod n o gd ie uan 32 3 34 The Persistence Add On oar Mesue ninia nec Chat elo a a a idR 33 WADE USER GUIDE Ad WorkHow inherit ales usi dier inopi eh be oti ter eoe opp tek geo p TEQUE CH da eda peel Usi po tel Poe poe USE PPRE FEE RENS 33 4 EXECUTING WORKFLOWS Leeeeeeeeen nn ee enne nnn a nnne aaa a nasa ausa nnns aaa a anna an 35 4 1 Launching workflows from code the DispatchingCapabilities class 36 4 2 Using the LauncherAgent to launch workflows esee ee eee eee eee eere ee ette seen nu 37 5 ADVANCED FEATURES nn cintsnscsigetienctsusinwnadvtiencteusiaususutinvshdusvesawthecahsediessasusinastauthes 39 5 1 Apent Pools aisi acahiatinceadssceneehichasdeactsageatat aasnscathoatsicliecsaceelaataneeasmidsctsautibeubeasas 39 5 1 1 Agent allocation policies es rrr SR HOO EEES UE AS
42. llocate them round robin across all containers with Java Profile P gt lt policy name com tilab wade raa policies JavaProfileBasedRRPolicy gt lt properties gt lt property name javaProfile value P gt lt properties gt lt allocationRule gt lt allocationRule gt lt Match all agents gt lt condition gt name lt condition gt lt Allocate them round robin across all containers gt lt policy name com tilab wade raa policies RoundRobinPolicy gt lt allocationRule gt lt allocationRules gt When the RAA is requested to create an agent somewhere in the platform it scans the rules defined in the raa xml file Each rule is composed of a condition and an allocation policy When processing a given rule the RAA matches the agent to be started against the condition If the match is OK then the RAA uses the allocation policy to select a container where to start the agent If the policy returns an existing container and the agent creation succeeds the process stops Otherwise the RAA moves to the next rule The snippet above for instance would result in starting all agents of type Foo with the argument argl setto Bar in containers with ContainerProfile of type JAVA P All other agents would be allocated round robin across all available containers An allocation policy is a Java class implementing the com tilab wade raa AgentAllocationPolicy interface or extending the com tilab wade raa policies BaseAgentAllocat
43. lopers can t control However especially considering that one of the main advantages of the workflow approach is the possibility of representing processes in a friendly graphical form WADE comes with a development environment called WOLF that facilitates the creation of WADE based application WOLF is an Eclipse www eclipse org plug in and as a consequence allows WADE developers to exploit the full power of the Eclipse IDE plus additional WADE specific features This document does not discuss WOLF Interested readers should refer to the WADE Development Tutorial http jade tilab com wade doc tutorial W ADE Tutorial pdf for details about how to install and use it Application specific features Workflow development Administration and fault management Distributed runtime Agent and behaviour Communication Discovery Figure 1 The WADE platform 1 1 Workflows A workflow is the formal definition of a process in terms of activities to be executed relations between them criteria that specify the activation and termination and additional information such as 4 WADE USER GUIDE the participants the software tools to be invoked required inputs and expected outputs and internal data manipulated during the execution The key aspect of the workflow metaphor is the fact that the execution steps as well as their sequencing are made explicit This makes it possible to give a graphical representation of a process defin
44. lows As soon as a WSDL has been imported as server its operations become available for selection when including a Wait Web Service activity in a workflow The second step is to expose the Web Service so that it becomes available for invocation This requires the WadeServices component as depicted in Figure 14 The WadeServices module is a web application war file that can be deployed in whatever Servlet container such as Apache Tomcat The actual Web Service exposure operation can be done from Wolf as described hereafter e Connect Wolf to the running WADE based application that must expose the Web Service e Be sure the WadeServices module is installed in your servlet container and the servlet container is up and running e Be sure the WadeServices module is connected to the WADE based application This can be done by checking if the WadeServices Gateway Container WSEG Container appears in the Wolf AgentTree view as depicted in Figure 15 If this is not the case connect the WadeServices module by means of the Start button of the WadeServices administration web page http localhost 8080 wadeServices e Inthe Eclipse Package Explorer right click on the service jar file and select the WADE Tools gt Expose menu item as depicted in Figure 16 30 WADE USER GUIDE WSDL V 1 Import WSDL 2 Deploy WebService Ao 2 Deploy Developer 7 A 3a Invocation e ae eb Service Be L9 Source Safer Masgse Sapch Projet Wo
45. lows Readers can refer to the WADE Tutorial available on line in the WADE site http jade tilab com wade doc tutorial W ADE Tutorial pdf for a step by step description about the Wolf Workflow Editor and the other relevant features that Wolf provides 3 1 The workflow meta model As anticipated the approach adopted by WADE to support workflow development is to provide a workflow view over a Java class with a proper structure that can therefore be managed exploiting the full power of the Eclipse IDE As a consequence WADE does not use internally any standard workflow definition language but a proprietary formalism based on the Java language However in order not to re invent the wheel and to facilitate import export operations WADE adopts a workflow meta model derived from that defined in the XPDL standard specified by the Workflow Management Consortium www wfmc org The main elements that compose this meta model are described hereafter A task that is being described is called a Process A process is composed of a set of Activities each one corresponding to the execution of given operations A process defines a single Start Activity specifying the execution entry point and one or more End Activity specifying the execution termination points Each non end activity has one or more outgoing Transitions possibly associated to a condition leading to another activity in the process Once the execution of the operations included in a given act
46. mListToMap static method can be used to convert it into a Map thus simplifying the retrieval of output parameter values 4 2 Using the LauncherAgent to launch workflows In order to try the execution of workflows WADE provides a simple utility agent called Workflow Launcher com tilab wade tools launcher LauncherAgent class that allows launching workflows and tracing their execution Again the Web Administration Console provides a more powerful interface to launch and control workflows but it is not discussed in this document The Workflow Launcher Agent can be started exactly as all other agents e g using the JADE RMA or specifying it among the agents to be activated at bootstrap time in the main properties file see section 2 3 1 Alternatively the WADE Management Console presented in section 2 3 3 allows starting the Workflow Launcher Agent by just clicking the Workflow Launcher button lolx File Workflow o 2 X Performet agent performer1 Workflow Events Workflow com tilab wade tools launcher test HelloVvord lt Session ID Generate Verbosity Level WORKFLOW x Transactional Workflow Parameters Name T Type Mode Value J Workflow Status Failure Reason r DL WADE USER GUIDE Figure 19 The Workflow Launcher Agent GUI The GUI of the Workflow Launcher Agent depicted in Figure 19 allows specifying among others the workflow to la
47. n may even not use Workflow Engine agents at all and just exploit the administration and fault tolerance features In that case we end up with a WADE based application that does not use workflows 10 WADE USER GUIDE Boot Daemon Boot Daemon Boot Daemon Ce age Container Container 1 Main Container qu Container 5 Container 2 Container 3 Container 6 Application specific agents Figure 5 The WADE Architecture Figure 5 also shows another 3 WADE specific agents Runtime Allocation Agent RAA active on the Main Container The role of this agent will be discussed in chapter 5 when presenting Agent Pools and Fault Tolerance Workflow Status Manager Agent WSMA This agent can be activated on whatever container and is responsible to trace workflow executions and to persist their state Event System Agent ESA This agent can be allocated in whatever container and implements the WADE Event System that allows a workflow to suspend waiting for an event In many cases the application may involve other non agent components such as a Database or a Web Interface running on the same or on separate hosts How to manage these components is outside the scope of this document 2 2 Application activation and termination First of all it has to be highlighted that though a single WADE platform can host several applications unlike the J2EE architecture such applications have dedicated processes
48. n to be invoked Therefore unlike methods corresponding to Code activities that take no arguments the methods corresponding to building block invocations take an argument representing the building block s to invoke With reference to the coffee example let s assume the PrepareCof fee application has the following formal parameters coffeeType INPUT of type St ring indicating the type of coffee to produce e g Espresso American cupsNumber INPUT of type int indicating the number of cups to prepare coffeeJug OUTPUT of type Cof feeJug a domain specific class indicating the jug containing the prepared coffee Here is how the executePrepare method corresponding to the PREPARE activity would look like public class CoffeeProcess extends WorkflowBehaviour Formal parameters GFormalParameter mode FormalParameter INPUT index 0 private int nCups Data fields private int groundCoffeeGr private int coffeeGrPerCup 10 private CoffeeJug jug protected void executePrepare ApplicationList appls throws Exception Application prepareCoff appls next Fill input parameters prepareCoffee fill coffeeType Espresso prepareCoffee fill cupsNumber nCups by This actually invokes the application execution executeApplication prepareCoffee Store output parameters jug CoffeeJug prepareCoffee extract coffeeJug The Application class provides overl
49. nce the coffee process can take an input formal parameters nCups indicating the number of cups to be prepared This would be implemented as an int field annotated as below public class CoffeeProcess extends WorkflowBehaviour Formal parameters FormalParameter mode FormalParameter INPUT private int nCups Data fields private int groundCoffeeGr private int coffeeGrPerCup 10 protected boolean checkNotEnoughCoffee return groundCoffeeGr coffeeGrPerCup nCups 3 2 3 BuildingBlock invocation As mentioned for each registered activity there is a corresponding method in the workflow class While for code activities this method actually specifies the operations to be performed in the activity for tool subflow WebService and other types of activity the corresponding method just specifies the invocation of the indicated element Such elements therefore can be seen as building blocks that are composed by the workflow to implement a complex process The invocation of a building block no matter if it is a subflow a web service or an application is composed of three steps 1 fill actual input parameters 2 invoke the indicated building block 3 extract actual output parameters and store them in suitable workflow data fields for later processing 27 WADE USER GUIDE In the case of a tool activity where it is possible to invoke more than one application these steps are repeated for each applicatio
50. ng executionId Workflow execution successfully completed System out println Workflow completed successfully Get output parameters Map String Object params ElementDescriptor paramListToMap results int length Integer params get messageLength System out println Output parameter messageLength length public void handleExecutionError ExecutionError er AID executor String executionId Workflow execution failed public void handleLoadError String reason Executor failed refused to load the workflow public void handleNotificationError AID executor String executionId Generic communication error This should never happen null catch Exception e 36 WADE USER GUIDE e printStackTrace From the code snippet above one can notice that e The fully qualified name of the workflow class must be indicated to specify the workflow to launch e Actual parameters can be filled in form of a Map and then set to the WorkflowDescriptor e The launchWorkflow method of the DispatchingCapabilities class can be used to trigger the execution of the indicated workflow on a given WorkflowEngineAgent e AWorkflowResultListener can be specified to be notified among others about the workflow execution completion e Workflow results i e output parameters if any are provided as a List of Parameter objects The para
51. noticed that WADE does not include a single powerful workflow engine as the majority of BPM oriented tools do On the contrary it provides an ad hoc type of Agent Workflow Engine Agent that embeds a micro workflow engine As a consequence besides normal tasks JADE behaviours each Workflow Engine agent active in a WADE based application is able to execute workflows represented according to a WADE specific formalism The second important point to highlight is that in order to allow developers to exploit the workflow metaphor to define system internal logics and at the same time to give them the same power of a software programming language and a comparable execution efficiency the WADE workflow representation formalism is based on the Java language That is a workflow that can be executed by WADE Workflow Engine agents is expressed as a Java class with a well defined structure detailed in chapter 3 As such WADE workflows can be edited refactored debugged and in general managed as all Java classes and can include all pieces of code methods fields of whatever types inner classes references to external classes and so on needed to implement the process details In addition of course the execution flow they specify can be presented and modified in a friendly graphical way More in details WOLF the development environment for WADE based applications is an Eclipse plugin and allows developers to work with a graphical view suitable to manage t
52. nts are distributed across the containers according to some criteria that depend on the application requirements WADE specific components are the Boot Daemon processes one per host each one responsible for activating containers in the local host the Configuration Agent CFA always running in the Main Container and responsible for interacting with the boot daemons and controlling the application life cycle and the Controller Agents one per container responsible for supervising activities in the local container and for all the fault tolerance mechanisms provided by WADE Of course the last fundamental component of the WADE platform are the Workflow Engine Agents i e the agents able to execute tasks defined as workflows as will be described in section 3 Workflow Engine Agents can be used as they are and in certain cases all the logics of an application can be embedded in workflows that will be executed by naked Workflow Engine agents In a more general case an application can extend the base Work lowEngineAgent class in order to provide domain specific features How many Workflow Engine agents to use and where in which containers to deploy them depends on the application requirements In general some of the application specific agents will be possibly extended Workflow Engine agents and will therefore be able to execute workflows while others will be normal agents running usual JADE behaviours It should be noticed that a WADE based applicatio
53. oaded fill methods to deal with all types of object without the need of casting On the other hand when storing output parameters into a data field a proper cast to the data field type and possibly a primitive conversion e g from Integer to int must be done explicitly Handling actual parameters of a subflow or web service is done exactly the same way since the Subflow class and the WebService class provides identical 111 and extract methods 3 2 4 Layout information All information related to the appearance of a workflow as shown in the graphical editor provided by Wolf e g the fact that the box representing a given activity is placed in a given position within the screen or that the arrow representing a given transition has some routing points are specified by means of proper annotations associated to the workflow class Clearly Wolf fully manages all these annotations and developers do not need to care or know anything about them 28 WADE USER GUIDE 3 3 Synchronization Activities 3 3 4 Events As mentioned WADE allows defining synchronization activities where the execution flow blocks until a given event happens These are called Wait Event Activities The first step to use Wait Event Activities is to define one or more custom event types This is done in the types xml already mentioned in 2 4 when describing agent types and roles file as exemplified in the snippet below lt customEventTypes gt lt
54. ple xml lib wade Jar wadeInterface jar jade jar este src deploy esed projects add ons The build xml file allows recompiling WADE and recreating the libraries using Apache ANT The bin directory includes bat and sh startup scripts for Windows and Linux respectively that can be used to start the Main Container and the BootDaemon process The cfg directory includes all configuration stuff In particular e themain properties file is the JADE property file that includes all configurations related to the Main Container e thetypes xml file define agent types and roles as will be described in section 2 4 e theconfiguration subdirectory as described in section 2 2 is used to store application configurations A sample application configuration actually that presented in 2 2 is provided in the sample xml file The 1ib directory includes the WADE libraries wade jar and wadeInterface jar and all libraries used by WADE including JADE The src directory includes all WADE sources The deploy directory is where deployed workflows will be stored The 10g directory is where log files produced by the Main Container and the local BootDaemon will be stored In particular the BootDaemon log file contains all logs produced by the containers launched by the BootDaemon prefixed with the container name 14 WADE USER GUIDE The projects directory is used to keep property files describing the loc
55. plementing a given application specific piece of functionality F was running on the crashed host the application even if its remaining agents will still be able to exchange messages and exploit other platform services may not work anymore as functionality F is no longer available In order to support fault tolerance at the application level WADE provides an additional mechanism that enable automatically restarting all agents that suddenly disappear due to HW or SW faults This mechanism is implemented by the Control Agents As described in section 2 1 each container but the Main Container holds a Control Agent that is responsible for supervising the resources in the local container Furthermore Control Agents coordinate themselves so that a single leader is elected The autorestart mechanism works as follows e Ifan agent suddenly dies this may happen if there is a software bug in the agent s code that causes an uncaught exception the Control Agent of the local container automatically restarts it e Ifan entire container suddenly dies e g because the container process is killed of course the local Control Agent dies too The leader Control Agent then takes care of restarting the whole container this operation is actually performed by the BootDaemon on the host where the container was active upon a request from the leader Control Agent with all its agents e If the dead container included the leader Control Agent other Control Ag
56. ransformation mathematical computations and so on Software code is typically more powerful and efficient to implement them As a consequence nowadays the workflow metaphor is mostly used in BPM contexts where a workflow represents a business process and orchestrates a number of existing systems typically but not necessarily accessible by means of Web Services based interfaces WADE tries to break this barrier and brings the workflow approach down to the level of system internal logics too Therefore as depicted in Figure 2 it can be fruitfully adopted both as an Orchestrator to coordinate existing systems and as a Software Development Framework to create brand new applications that imply the execution of possibly long and complex tasks WADE USER GUIDE Orchestration context WADE is used as a Workflow Engine and workflows implement processes that coordinate different systems WADE is seen as a black box that executes workflows Agents inside WADE are not even seen E a System development context WADE is used as an agent oriented Development Framework and workflows implement some of the agent tasks In some cases workflows may not even be used at all d Furthermore considering the distributed nature of the underlying agent oriented JADE layer WADE can provide a good value added whenever scalability is an issue Figure 2 WADE application contexts 1 3 Approach First of all it should be
57. rm Long running workflows we mean workflows that survive to the system shutdown and restart That is if the system is shut down while a long running workflow is running as soon as the system is restarted the workflow is automatically resumed from the point where it was interrupted In order to make this possible when executing a long running workflow the WADE Workflow Engine automatically saves the workflow state after each step of execution This is done by serializing the WorkflowBehaviour object implementing the workflow and storing the serialized bytes on a relational DataBased Clearly long running workflows are less efficient with respect to normal short running ones Therefore depending on the characteristics and requirements of a given process to be implemented developers can choose whether to implement it as a short running or as a long running workflow Even though this is not mandatory workflows that include Wait Event or Wait WebService activities 1 e workflows that can block for possibly long amount of times are typically declared as long running In order to create a long running workflow it is sufficient to 1 Declare the workflow as long running by redefining the isLongRunning method of the WorkflowBehaviour class as below public boolean isLongRunning return true 2 Be sure that the workflow class is Serializable Furthermore as mentioned in order to properly execute long running workflows the P
58. s The execution of the subflow takes place in a separate computational space and as will be described in section Errore L origine riferimento non stata trovata can be even carried out by a different performer 23 WADE USER GUIDE agent possibly running in a remote host with respect to that executing the main process e WebService activities The operations included in a Web Servicve activity consist in invoking a web service Synchronization activities e WaitEvent activities When the execution flow reaches a WaitEvent activity the workflow suspends until a given event happens Events are further discussed in section 3 3 1 e WaitWebService activities When the execution flow reaches a WaitWebService activity the workflow suspends until a given operation of a previously exposed Web Service is invoked e SubflowJoin By default subflows are executed synchronously i e the main workflow blocks until the subflow completes and then goes on Alternatively it is possible to execute a subflow asynchronously that is the main workflow proceeds just after launching the subflow When the execution flow reaches a Subflow Join activity the workflow blocks until a previously launched asynchronous subflow completes Finally the process makes reference to a set of Data Fields each one having a name a type and possibly an initial value Data fields can be referenced wherever in the process e g in the conditions associated to the transitions a
59. s actual parameters for application subflow and web service invocations and in the pieces of code triggered by code activities Figure 12 shows an example summarizing some of the elements of the WADE meta model Process P 1 Application X produces value 10 and stores it in data filed e Data Fields Activity A1 Tool transition is Activity A3 Subflow 3 A3 consist in the execution of another workflow process defined outside P Figure 12 Main elements in the XPDL meta model 24 WADE USER GUIDE 3 2 Workflow elements implementation Having described the main elements that make up a workflow process in this section we show the structure of the Java code that actually implements them It is important to note that even if they could we expect developers not to write the pieces of code that are described in this section directly but to use the graphical workflow editor provided by WOLF to do that However understanding the Java based workflow definition formalism adopted by WADE may be useful to prevent unexpected behaviours and to investigate problems 3 2 1 The WorkflowBehaviour class Each workflow process is implemented by a Java class that extends directly or indirectly the com tilab wade performer WorkflowBehaviour base class The WorkflowBehaviour class on its turn extends the JADE FSMBehaviour class and provides on top of it an API consistent with the meta model presented in 3 1 In
60. sociated condition this is implemented by a boolean method of the workflow class The Transition object is just responsible for invoking that method when the transition condition must be evaluated The name of the method implementing a condition is constructed by adding the check prefix to the condition name Figure 13 summarizes the above correspondences 23 WADE USER GUIDE package coffee processes public class CoffeeProcess extends WorkflowBehaviour public static final String GRIND_ACTIVITY Grind COFFEE PROCESS public static final String PREPARE ACTIVITY Prepare public static final String POUR ACTIVI z Pour public static final String ERROR ACTIVITY amp rror o private void defineActivities private void defineTransitions registerTransition new Transition NotEpd ughCoffee LI CodeExecutionBehaviour ceb z n w CodeExecutionBehaviourTSRIND ACTIVITY this i registerActivity ceb INITIAL ToolExecutionBehaviour teb new ToolExecutionBehaviour PREPRARE ACTIVI this v te Su sd RouteActivityBehaviour rab new RouteActivityBehaviour EBR R ra registerActivity rab FINAL b addApplication b setError coffee applications PrepareCoffee Grind registerActivity teb bflowDelegationBehaviour sdb new SubflowDelegationBehaviour POUR ACA this b setSubflow coffee processes PourCoffee registerActivity sdb FINAL NotEndughCoff
61. ssary to request the CFA to perform the ShutdownPlatform action of the Configuration Ontology This has the effect of killing all containers but the Main Container At any time it is possible to request the CFA to export the target configuration ExportConfiguration action of the Configuration Ontology to an application configuration XML file Figure 6 summarizes the main actions of the Configuration Ontology and their effect on application configurations X L Application N configurations Main Container available for import Container 1 Container 2 Configuration CN Container 3 Target SaveConfiguration i configuration Running configuration j y Figure 6 Managing application configurations 2 3 Getting started with the platform Having described the architecture of WADE based applications and the main management actions in this section we describe how to launch the WADE platform and start playing with it 2 3 1 WADE Distribution structure overview WADE does not require any installation procedure a part from un zipping the distribution zip file Having done that somewhere on your disk this is how the resulting directory tree should look like 13 WADE USER GUIDE wadeSuite wade build xml startMain bat startBootDaemon bat gtartMain sh startBootDaemon sh cfg main properties types xml configuration sam
62. t must be shared by all agents of a given type role can be specified once for all by means of agent type role properties WADE provides a number of utility methods provided by the DFUt ils class to easily discover agents at runtime on the basis of their type role 2 4 1 Using environment variables When specifying values for properties of agent types and roles it is possible to refer to environment variables using the syntax variable name 18 WADE USER GUIDE For instance the following snippet sets the directory where the CFA searches for application configurations to be imported exported to the applicationConfigurations directory under the home directory of a project pointed to by the project home environment variable lt agentType description Configuration Agent className com tilab wade cfa ConfigurationAgent role Administrator gt lt property name configurationsPath value project home applicationConfigurations gt lt agentType gt 2 5 WADE Agents In order for the management and fault tolerance mechanisms provided by WADE to work properly agents in a WADE based application must follow a set of rules regarding for instance how to register with the DF These rules are automatically managed by the com tilab wade commons WadeAgentImpl class Therefore WADE developers are recommended to extend it rather than the jade core Agent class directly The WadeAgentImpl class already implements the setup method of the
63. unch the agent that will be requested to execute it and the actual parameters if any 38 WADE USER GUIDE 5 Advanced features This section describes some advanced features that belong to the set of mechanisms provided by WADE to manage the complexity of the distribution but were not presented in chapter 2 to make that chapter easier to read and understand 5 1 Agent Pools In many cases especially when an application has to serve a heavy load of requests it is useful to have a set of agents of the same type to distribute the requests on Since in many cases such sets can count tens hundreds or even thousands of agents specifying them all one by one in the application configuration file as described in section 2 2 can be really annoying In order to deal with these situations in a friendly way WADE supports the notion of Agent Pool Agent Pools are defined in application configuration files as exemplified below platform name Test pool hosts hosts lt agentPools gt agentPool name testPool size 10 type Workflow Engine Agent gt lt parameters gt lt parameter key testParameter gt lt value gt test value lt value gt lt parameter gt lt parameters gt lt agentPool gt lt agentPools gt lt platform gt The above snippet indicates that 10 agents of type Workflow Engine Agent will have to be launched Such agents will be called agent pool name n and each of them will receive an

Download Pdf Manuals

Related Search

Related Contents

VERTU Ti User Guide  UH 700 - Hilti  Haier PBFS21EDAE-U User's Manual  HRV6610 Limpiador Ultrasónico Digital  MANUAL DE USUARIO      KDM-055  取扱説明書  Manuale  

Copyright © All rights reserved. Failed to retrieve file