*** 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:
   	<<parameters>> 
	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

