Shark工具代理
关于工具代理（从WFMC文档上的引用）
应用接口调用定义了一个位于工作流管理系统合其他应用程序之间的装置接口。然而他和其他的合并接口定义还是不同的。调用一个应用不是一个工作流指定的功能，但是一个工作流管理系统却不能没有这个功能。
这个接口从事与工作流系统向任何第三方软件的输出。基于不同的通信技术，被称作“工具代理”的能够操纵应用程序控制和信息转换。这些工具代理表现为至少一个指定的调用技术。例如一个工具代理提供了DDE命令，其他的能够和基于OLE或者CORBA或者任何其它概念通信。
这个技术能够在工具代理和依赖于潜在结构的应用程序间互操作，或者是指定接口的应用程序，而这些应用还依赖于工具代理自己的管理。这个建议的接口定义了工具代理能够被工作流应用使用的方法，例如，一个worklist句柄，或者工作流引擎。最后，工具代理的目的将会和标准软件组件的目的比较。
应用程序接口函数的设置提供了工具代理服务，用来联合指定的workItem调用和控制应用程序。
调用的应用程序接口定义了一个API设置，这已经交付给工作流系统组建使用（引擎和客户端应用程序），来控制专门的应用程序驱动，叫做工具代理。这个工具代理将最终负责启动和关闭应用程序，通过工作流和应用程序的相关信息。因此，应用程序接口调用API仅仅对准一个工具代理。然而，额外的工作流信息能够被应用程序通过工具代理使用标准WAPI函数被请求。同样，应用程序接口调用应该应用双向请求（请求可以从应用中来也可以到应用中去），他依赖于接口和如何同工具代理互操作的应用程序结构。
这个接口将允许请求和更新应用程序数据和运行时相关功能。
工作流系统自己不得不了解已经安装的工具代理。工具代理的基本结构是比较一个驱动程序—接口，ODBC或者其他接口定义，在这个接口定义里，在工具代理和工作流系统之间没有更进一步的通信机制是必要的。
工具代理接口的shark实现
shark作为内在接口定义了工具代理接口，这对客户端来说是透明的。
我们可以为工具代理接口定义我们自己的java接口，只要这些接口符合wfmc规范，它被定义在了Shark API module中的org.enhydra.shark.interal.toolagent包中。这些工具代理API有很好的文档支持，并且这些文档能够在tool agent api section中找到。
如何在shark server中使用工具代理
shark server只知道工具代理接口。它不知道任何的特殊工具代理实现。当一些工具类型的自动活动被执行时，shark将查找一个适当的工具代理：
l 如果活动的应用程序的映射信息存在（Admin首先映射应用程序定义到工具代理），shark找到这个映射，然后得到工具代理调用的信息和调用参数。然后shark尝试连接工具代理并得到他的句柄。然后它调用工具代理重的invokeApplication()方法和相关参数（一些参数包含在映射信息中）。在这之后，它调用方法requestAppStatus()来检查工具代理的状态并返回结果，设置适当的活动变量。
l 如果映射信息不存在，shark调用默认工具代理，他的类名称在shark配置文件中被定义。
当为AppParameter数组中的第一个AppParameter调用工具代理invokeApplication()方法时，shark总是通过一个字符串来声明相应的XPDL应用程序扩展属性部分，从XPDL定义中突然露出。
<ExtendedAttributes>
<ExtendedAttribute Name="ToolAgentClass" Value="org.enhydra.shark.toolagent.JavaScriptToolAgent"/>
<ExtendedAttribute Name="Script" Value="c=a-b;"/>
</ExtendedAttributes>
向先前所提到的，shark没能找到映射信息，他执行默认的工具代理。默认的工具代理能可靠地执行适当的工具代理实现如果他发现工具代理执行的扩展属性。默认工具代理从XPDL应用扩展属性中得到他的数据，在扩展属性中他名为：ToolAgentClass并且他的值为你想要的工具代理类名全称。其他的扩展属性被期望又来读取工具代理指定的操作。
注意：在下列条件下，shark自动开始工具活动：
1． 如果活动是工具类型的活动，并且他的执行者是SYSTEM类型的参与者，并且活动的开始和结束方式都为自动
2． 如果活动是工具类型的活动，并且他的执行者是空异常（没有活动者），并且活动的开始和结束方式都是自动的。
3． 如果活动是工具类型的活动，并且他有一个不同于SYSTEM类型的参与者，他的开始是MANUAL，结束是AUTOMATIC的。如果最后一个是事件，这个活动将首先分配给一个参与者，当他完成以后，通过工具代理调用，工具指定shark自动执行。
Shark工具代理例子
我们已经开发了6个有用的工具代理（加上默认的工具代理），下面给你提供如何开发你自己的工具代理的例子，那些可能是更复杂的工具代理。我们的工具代理的源代码你能够在modules/SharkToolAgent目录下找到。
l JavaClassToolAgent-通过调用他的静态方法execute，这个工具代理执行java类。当调用这个工具代理的invokeApplication()方法时，application名称变量应该是类名的全称，这个类应能够被这个代理执行。到目前为止，我们定义了一些简单算术运算的类，生成随机数的类，和一个执行等待的类，另外还有两个类由Paloma Trigueros Cabezon捐赠 ，他们能够发送email。
通过下列名称，这个工具代理能够了解扩展属性：
Ø AppName—这个属性的值，表现为被执行的类名
l RuntimeApplicationToolAgent—用来执行一些系统应用，如记事本或者其他可执行应用程序。这个功能是十分重要的，他能够在shark运行时，从机器的系统路径下调用这些应用程序。
如果你使用0模式的应用程序，工具代理将等待知道应用程序执行完成，如果你选择的应用程序状态不是0，工具代理将在执行应用程序的同时开始工作，并且shark将流程转移到下一个活动，即使是可执行的应用程序仍然在执行。（对于外部应用程序来说这是异步执行的）
这个工具代理接受参数（AppParameter类实例），但是他不能做任何改变。这个参数发送到这个工具代理中，（相应的应用定义形参是IN类型，他的数据类型为String）作为后缀添加到应用程序名称后面，然后应用程序作为结果被启动，例如：notepad c:\Shark\readme
这个工具代理能够通过下面的名称知道扩展属性：
Ø AppName-这个属性的值应该表现为被工具代理执行的，可执行的应用程序名称
Ø AppMode-这个属性的值应该表现为执行模式，如果设置为0，公举代理将等待，直到可执行应用程序运行中止。
JavaScriptToolAgent-执行javascript。如果你设置应用程序模式为0，公举代理将会通过applicationName参数搜索JavaScript文件（这个文件必须在classpath里），如果找到了，则执行它，如果没找到，他将参考applicationName参数值为script文件名称的值，然后执行它。到目前为止，我们定义了一些执行简单算术运算的脚本，生成随机数的脚本和执行等待的脚本。
AppName-这个属性的值表现为要执行的脚本文件的名称（这个文件必须在classpath里）
Script-这个值表现为要执行的脚本，例如下面的例子：
<ExtendedAttribute Name="Script" Value="c=a-b;"/>
（上述文本中的a,b,c是XPDL应用定义中的形参ID）
BshToolAgent-执行java语法编写的脚本。如果你设置应用程序模式为0，工具代理将根据applicationName属性搜索脚本文件（这个文件必须在classpath中），如果找到了，则执行它，否则，将认为applicationName参数值为脚本文件名称，并且执行它。到目前为止，我们没有定义任何脚本文件。
这个工具代理能够通过下面的名称得到扩展属性：
Ø AppName-这个属性的值表现为执行的脚本文件名称
Ø Script-这个属性的值表现为要执行的脚本：
<ExtendedAttribute Name="Script" Value="c=new java.lang.Long (a.longValue() - b.longValue());"/>
（上面文本中的a,b,c都是XPDL应用定义中的形参ID）
l SOAPToolAgent-执行WebService操作
当你映射一个XPDL应用到这个工具代理时，你应该设置这个应用的名称来定位定义WebService调用的WSDL文件的位置。当然，这个工具代理需要XPDL应用中的表现为WebService调用名称形参的第一个参数被定义。这个工具代理能够通过以下名称得到扩展属性
Ø AppName-这个属性的值用来表示WebService定义的WSDL文件的位置。
l MailToolAgent-发送和接受邮件信息。
这里有一个MailMessageHandler接口被定义用来操作邮件。我们给出了该接口的默认实现，但是你也可以创建你自己的实现。这个接口是特意为工具代理定义的，当时他不是SharkAPI的一部分。
当执行映射时，你应该设置应用程序名称为MailMessageHandler接口实现类的全称。
为了能让我们的DefaultMailMessageHandler工作，你必须定义一些属性，下面是在shark配置文件Shark.conf总的配置片断：
#
# the properties for our default implementation of MailMessageHandler interface
# required by MailToolAgent
#
# the parameters for retrieving mails, possible values for protocol are "pop3" and "imap"
DefaultMailMessageHandler.IncomingMailServer=someserver.co.yu
DefaultMailMessageHandler.IncomingMailProtocol=pop3
DefaultMailMessageHandler.StoreFolderName=INBOX
DefaultMailMessageHandler.IMAPPortNo=143
DefaultMailMessageHandler.POP3PortNo=110
# the parameters for sending mails
DefaultMailMessageHandler.SMTPMailServer=someserver.co.yu
DefaultMailMessageHandler.SMTPPortNo=25
DefaultMailMessageHandler.SourceAddress=shark@objectweb.org
# credentials
DefaultMailMessageHandler.Login=shark
DefaultMailMessageHandler.Password=sharkspwd
这个工具代理能够通过下面的名字知道扩展属性：
Ø AppName-这个属性的值用来描述MailMessageHandler接口实现类的全称。
Ø AppMode-这个属性的值用来描述执行得模式，如果设置为0，工具代理将发送邮件，如果设置为1则接受邮件
如何使用Admin Application执行工具代理影射
你可以通过一些工具代理影射包和包的流程应用到一个真实应用。现在六个代理（加上默认代理）随同shark已同分发。
映射应用程序定义到工具代理应用中，你不得不到admin application的application映射片断中，按add按钮。一个对话框出现了，你可以选择左面对话框的应用程序定义和右面对话框中的工具代理。然后你可以为工具代理确定一下的映射参数：
Username和password-在shark中是没必要的参数，在有些工具代理中，调用应用程序时需要登录操作的，需要设置这两个参数。
l Application name-应用的名称，他能够被一个工具代理开始（对于JavaClassToolAgent来说他是要执行的类名全称，对于RuntimeApplicationToolAgent来说，它是要执行的文件的名称，这个文件要放在工具代理所在的机器路径下，对于JavaScripteToolAgent和BshToolAgent来说，它要么是java scripte文件名称，要么是java script自己，这依赖于模式属性的值。对于SOAPToolAgent来说，它是WSDL文件的位置，由它来定义web service，对于MailToolAgent来说，它是MailMsssageHandler接口实现的名称）
l Application mode-不同的工具代理使用这个属性有不同的作用。也就是说，RuntimeApplicationToolAgent使用mode 0 来指示代理等待知道系统应用结束（另外，它将启动系统应用并且完成她的执行，活动不必为系统应用的结束等待，刘程将流向下一个活动），JavaScriptToolAgent 和BshToolAgent使用mode 0来指示是否查找sript文件（如果不是，则application name将用来存储用于执行的脚本），对于MailToolAgent来说，使用mode 0 来指示mail是发送的，mode 1 来指示mail是用来接收的。
在XPDL中使用ToolAgent的例子
如果你通过Admin application加载test-javascript.xpdl（或者test-BeanShell.xpdl）,你能够找到如何使用Tool agent的方法。
这个XPDL为应用程序定义定义了扩展属性集，并且这个属性包含了被调用适当工具代理所需的数据来映射信息（这个工具代理通过默认代理被调用，用来读取扩展属性参数）。在开始shark引擎以前，你需要做的唯一的事情是配置shark.conf文件，来定义适当的DefaulMailMessageHandler设置，但是即使你不定义它，这个例子仍然能够工作，因为在MailToolAgent失败后，他将会执行DEFAULT_EXCEPTION迁移。
如果你想要做你自己的映射，他将要覆盖默认的配置在应用的XPDL扩展属性中，因为shark首先寻找映射信息，并且如果他不能找到他，他将调用默认工具代理，他将读取扩展属性。你能做下面的事情观察映射是如何工作的：
开始Shark_Admin应用并且到application mapping片断
映射如下：
Ø Addition->org.enhydra.shark.JavaClassToolAgent(为application名称定义为AdditionProc)
Ø Arbitrarymathop->org.enhydra.shark.SOPTToolAgent(为application名称定义为http://samples.gotdotnet.com/quickstart/aspplus/samples/services/MathService/ VB/MathService.asmx?WSDL)
Ø Division->org.enhydra.shark.JavaScriptToolAgent(为application名字定义为c=a/b,并且application mode为1)
Ø Multiplication->org.enhydra.shark.BshToolAgent(为application名字定义为c=new Long(a.longValue()*b.longValue());application mode为1)
Ø Notepad->org.enhydra.shark.RuntimeApplicationToolAgent(为应用程序名称定义为notepad，application mode为1 )：如果shark运行在windows上，这个应用将被执行。
Ø Send_mail->org.enhydra.shark.JavaClassToolAgent(定义应用程序名称为email.MailProc)
Ø Send_mail2->org.enhydra.shark.MailToolAgent(定义应用程序名称为org.enhydra.shark.toolagent.DefaultMailMessageHandler并且application mode 为0)
Ø Substraction->org.enhydra.shark.JavaScriptToolAgent(定义应用程序名称为SubstractionProc.js,并且application mode为0)
Ø Vi->org.enhydra.shark.RuntimeApplicationToolAgent（为应用程序名称定义为xtern –e vi,application mode 为0）如果shark运行在*nix上（linux,unix……）,这个应用将被执行。
Ø Waiting->org.enhydra.shark.JavaClassToolAgent(定义应用程序名称为WaitProc)
Ø 实例化”Do math”流程
Ø 执行workitem
这个流程包含两个循环：
第一个循环从子流程活动“Calculate”中执行算数运算。当你执行“enter math parameters”活动时，键入一些参数，也就是”addition”,”44”,”33”当子流程活动”Calculate”完成以后，你应该能看到相加的结果77。在这里你能够决定是否循环计算。如果你决定不再循环，则系统进入最后活动，但是他不能够完成，知道第二个循环退出。
第二个循环是非常有趣的，它执行两个操作：
Ø 执行任意的算数操作
Ø 执行等待过程
当两个操作都已经完成继续循环，任何的数学操作都被调用WebService执行，并且等待方法是用java的sleep方法。
例如，如果你键入参数”Add”,”100.3”,”10.2”,”10000”，计算的结果为当操作结束时得到110.5。既可以执行活动来显示你的数学操作结果，当10秒钟过去以后，会询问你是否要让流程循环。
当你决定退出两个循环时，流程调用Notepad或者Vieditor活动，这个调用依赖于引擎工作的操作系统环境，一个适当的文本编辑器 将由RuntimeApplicationToolAgent调用运行在shark机器上。
现在你可以键入一些参数来发送e-mail来通知某些人，例如如下所写：
Txt_mas->Do math process is finished
Subject->Do math process status
Destination_address->shark@enhydra.org
在这以后，邮件将被使用MailToolAgent发送，然后流程将会结束。如果他不能工作的话，则这意味着你没有给出适当的参数在Shark.conf文件中，所以在工具代理中的异常将会发生，当时由于XPDL已经定义了DEFAULT_EXCEPTION迁移，所以流程将进入异常处理路径->活动”Enter Aditional Mail Params”。现在你应该键入为email.MailProc用来发送邮件所需要的额外的参数。
Ø Source_address->admin@together.at
Ø User_auth->admin
Ø Pwd_auth->mypassword
Ø Server->myserver
Ø Port->25
此后，流程将会结束，无论你键入的参数是否合适。
现在你可以运转这个映射了，例如你为执行数学操作键入不同的javascript文本，键入不同的参数值，。。。。。。
