*** auml2wsbpel installation and execution notes *** 1 DOWNLOAD AND INSTALL JAVA 1.4 SDK Your first step is to download and install Java 1.4 See the following site for download and installation information: JDK 1.4 http://java.sun.com/j2se/1.4/download.html. Be sure to download the full Software Development Kit (SDK), not just the Java Runtime Environment(JRE). Once you have installed Java, check that everything including your PATH is configured properly by opening a DOS window and typing "java -version" and "javac -help". A message stating the version of your SDK, and a list of usage options for the javac compiler, respectively, should be printed on the standard output. 2 DOWNLOAD AND INSTALL POSEIDON (Poseidon For UML Community Edition 4.0.1) See the following site for download and installation information: POSEIDON http://gentleware.com/index.php auml2wsbpel has been tested with “Poseidon For UML Community Edition 4.0.1”. It should be also possible to use successive versions. 3 HOW TO USE POSEIDON TO CREATE AGENT INTERACTION PROTOCOL (AIP) DIAGRAM Poseidon allows you to create UML 2.0 diagrams. It is also possible, with Poseidon, to create Agent Interaction Protocol (AIP) diagrams based on UML sequence diagrams, compliant with the auml2bpel software, following these instructions: - Open Poseidon, delete the proposed default “class diagram” and create a "sequence diagram". To create an AIP diagram compliant with auml2bpel software you MUST follow these rules: - The sequence diagram must contain only two lifelines. The leftmost represents the publisher's lifeline while the other represents the reader's lifeline. - The lifeline attribute “Name” must contain the agent's name, role and class in the format agent_name/agent_role:agent_class. - All the messages exchanged must be asynchronous messages. The first message must be sent by the reader. The message property "Call" must be used to set the FIPA performative of the message while the Documentation Property (in the source mode) must be used to set the content of the message. The FIPA performatives are: accept-proposal, agree, cfp, confirm, disconfirm, inform, inform-if, inform-ref, not-understood, propagate, propose, proxy, query-if, query-ref, refuse, reject-proposal, request, request-whenever, subscribe. Finally you must use the “Documentation” tab in the “source view” mode to write the message content. - It is possible to include in the diagram the following "Combined Fragment" elements: seq, alt, loop, option. - The diagram must include a comment, containging the AIP diagram parameters, with the “name” attribute set to "parameters" and a content like the following: <> ontology = "ontology-name" CL = "content-language-name" - Once the diagram has been created it must be exported into the xmi format using the “File” menu. Some AIP diagrams are included in the folder “samples”. The best way to quickly start working with auml2bpel is viewing and modifying the provided examples. NOTE: if you want to automatically generate Prolog agents (see section 5 below) you must respect some more constraints. In particular, IT IS MANDATORY to enclose any sequence of activities into a "seq" combined fragment, otherwise the generation of the Prolog code will fail. Make sure your diagram meets this constraint; the diagrams in the samples directory, do. 4 HOW TO USE AUMLTOWSBPEL Extract the file aumltowsbpel.zip Modify and execute the extracted aumltobpel.bat file In the aumltobpel.bat file you must write the path of the xmi input file to translate (currently, it is set to samples/fruitseller.xmi). In the DOS shell, move to the aumlbpelsoftware directory generated by the unzipping of the aumltowsbpel.zip file, and type aumltobpel In the same folder where the xmi input was found, the aumltobpel software will create five files with the following extensions: - .xml: an intermediate xml representation of the AIP diagram - .txt: the AIP diagram represented in Winikoff's extended notation - .wsdl and .bpel: the AUML AIP diagram represented as a WS-BPEL process - .fol: A Prolog term representing the protocol, used by the Prolog agents that we implement in JADE, to generate their own code compliant to the protocol 5 HOW TO CREATE PROLOG AGENTS AND INTEGRATE THEM INTO JADE Follow the instructions for downloading and installing DCaseLP http://www.disi.unige.it/person/MascardiV/Software/DCaseLP.html You will only need the facilities offered by "tuPInJADE"; neither "UMLInJADE" nor "jessInJADE" will be necessary, so do not worry about them and do not download Jess. Move to the aumlbpelsoftware\PrologAgents and open both the publisherAgent.pl and the readerAgent.pl files in a text editor. Also, open the .fol file generated by the aumltobpel translator (make sure that your Poseidon diagram met the constraints stated in the note of section 3). Copy the entire content of the .fol file at the end of the publisherAgent.pl and readerAgent.pl files (the place where you should paste it is clearly identified by comments). Rename publisherAgent.pl and readerAgent.pl as you want. We assume that you have renamed them p.pl and r.pl. After having inserted the content of the .fol file in the right place, make sure you insert the correct Jade address of both of the reader and the publisher inside r.pl and p.pl, respectively (you must edit BOTH files and insert the correct JADE adrress in both, as described in the next paragraph). You must edit the subterms agent_publisher(short_name('name-of-the-publisher@address'), long_name('......')), and agent_reader(short_name('name-of-the-reader@address'), long_name('.....')) and substitute only the "address" string with the string "name-of-your-computer:1099/JADE", where obviously "name-of-your-computer" must be instantiated with the actual name of your computer. Let us suppose that the two agents are named r (reader) and p (publisher) and that your computer is named myPC. The above strings will become agent_publisher(short_name('p@myPC:1099/JADE')....) and agent_reader(short_name('r@myPC:1099/JADE')....) respectively Let us recall that the two prolog files are named r.pl and p.pl respectively. Open a DOS shell and move to the aumlbpelsoftware\PrologAgents directory. From there, type java jade.Boot r:tuPInJADE.JadeShell42P(r.pl) p:tuPInJADE.JadeShell42P(p.pl) This command, if the installation of DCaseLP libraries and of JADE was correct, will create a multiagent system where the reader and publisher agents interact according to the protocol initially expressed in AUML, and then translated into the formats that ensure interoperability. A log of the activities of the reader and the publisher will be created into the two files "last_reader_output.txt" and "last_publisher_output.txt", that can be opened in any text editor for inspection. 6 EXTRA FUNNCTIONALITY: HOW TO CREATE THE .FOL FILE STARTING FROM THE WSDL AND WS-BPEL FILES An extra functionality of our software is the ability to create the .fol file used in section 5 for implementing the Prolog agents that work inside JADE, directly from the wsdl and ws-bpel specifications. To take advantage of this extra functionality, just run the wsdlbpel2fol.bat batch file from a DOS shell, after having eventually changed the file names and paths that appear inside it. ============================================================================================== Please report questions and bugs either to casella@disi.unige.it or to mascardi@disi.unige.it