[[PageOutline]]

= Genius2 Parties Server =

This is the homepage of the Genius2 parties server.
This server can provide a list of runnable parties, and create running instances of specified parties on a HTPT GET request. When an instance is made, a websocket link to the running party is provided to the caller.

The Genius2 main page is [https://tracinsy.ewi.tudelft.nl/trac/Genius2 here].


The Parties server runs on Tomcat 8 and is developed with Eclipse EE.

== Installation ==
* Install your apache-tomcat 8 installation ​https://tomcat.apache.org/download-80.cgi. You can re-use an existing installation. 
* Download the parties server war file from [http://artifactory.ewi.tudelft.nl/artifactory/webapp/#/artifacts/browse/tree/General/libs-release-local/genius2/partiesserver the artifactory]. Go into the latest version of the partiesserver and download (right click) the war file. NOTICE: your browser must have cookies enabled to access the artifactory.
* Copy the downloaded war file into the tomcat webapps directory
* (Re)start tomcat 

Now your local partiesserver should be up and running. 

== Using ==
After installing and starting, go to [http://localhost:8080/partiesserver-XXX] (replace XXX with the version you installed) to see if it works.

Example parties can be found in [https://tracinsy.ewi.tudelft.nl/trac/Genius2/browser/exampleparties/ genius core repo: example parties]. 

To deploy a party, the party jar file (with dependencies) is simply copied into the the {{{tomcat/webapps/partiesserver/partiesrepo}}} directory. This directory is created by tomcat when started.

To remove or rename a party, you can simply remove or rename the jar file. 


= Communication protocol
This section deals with the communication protocols of the  partiesserver. This is relevant if you need to communicate directly with it, e.g. when you build your own GUI or start up your own parties from a script.

Other implementations of a partiesserver should adhere to the same communication protocols to ensure compatibility with genius2.

=== Provide a list of available parties on the server
When a client accesses the partiesserver at {{{ws:...partiesserver/websocket/available}}}, a websocket is created. This websocket sends the clients list as a JSON list, each list element containing a GeneralPartyInfo object. 

A GeneralPartyInfo object contains the following: 
{{{
	URI                        uri;
	genius2.party.Capabilities capabilities;
	String                     description;
}}}

The uri contains a http address that, when accessed, starts up a new instance of the party. This is discussed in more detail in the next section. 

A full, updated list is sent over the websocket every time the list changes.

In the genius2 java implementation these fields are automatically generated from the parties contained in the jar files in the {{{partiesserver/partiesrepo}}} directory that was mentioned above. Other implementations might use a different scheme.

* On the server implementation provided here, the urls look like {{{http://...:8080/partiesserver/run/<party name>}}} 

=== Create new running instance of a party
When a client does a http get with an URI as provided in the GeneralPartyInfo field above, the server tries to create a running instance of that party. There are two possible responses from the party server:

* If the party was launched sucessfully: the http get returns a websocket address (ws:...) as plain text on which the party can be contacted.
* If the party could not be launched (eg, not enough resources) the server returns error code 503 "Service Unavailable". The 503 includes a message like {{{retry later at 1556631286760}}}. The message is kept human readable but the last element of the message must be a unix timestamp containing the time at which to retry. To create this message, the server can either create a default (e.g. let the client retry after a fixed set time) or actually use the estimated termination times of the parties. The current available server does the latter.

If the connection was succesful and thus the response was a websocket address, the websocket connection implements a {{{Connection<Inform, Action>}}}. This connection has the following protocol:
 * it accepts JSON-formatted Inform objects and these are passed into the party (see the the party module in genius2 core)
 * can send JSON-formatted Action objects as requested by the agent (see the events module in genius2 core)

== Detecting termination of a party
The partiesserver does not have a separate communication protocol to hear when parties have been terminated. Instead, the PartySocket (that the partiesserver provides for communication between the party and the server) is sniffed for characteristic termination events. The following events are considered indicative for termination:
1. The socket breaks, eg because one of the parties closes it, some network failure, etc.
2. The socket has reached its time-out. The time-out is initially set to 3 seconds which is assumed to be ample for setting up and configuring a party. When the socket detects a Settings object being sent to the party, it sets the time-out to settings.getProgress().getTerminationTime().
3. A "Finished" Inform object being sent to the party.

== Using the source code ==
You can download the source repository of rhe java implementation. Note that you don't need this if you just want to use the parties server to host your parties or to compile parties.

{{{
svn checkout https://tracinsy.ewi.tudelft.nl/svn/Genius2PartiesServer/
}}}

Since this is a tomcat web application, you need Eclipse Enterprise edition if you want to run this from Eclipse. 
Also, to checkout from Eclipse, you need to prepare Eclipse for this. Check https://tracinsy.ewi.tudelft.nl/trac/Genius2/wiki/WikiStart

It is maven based so you only need maven to compile the code.