= 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] 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. 


= Technical insides =
This section deals with the techniques inside the parties server and may be relevant when you need to communicate directly with it, e.g. when you build your own GUI or start up your own parties from a script.

== Communication protocol
The parties server is a component in the bigger genius2 framework. Its mains function are discussed in the following subsections. 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 parties 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;
}}}

These fields are automatically generated from the parties contained in the jar files in the {{{partiesserver/partiesrepo}}} directory that was mentioned above.

A new list is sent over the websocket every time the list changes.

=== Create new running instance of a party
The following steps are needed to create a new running instance of a party.

* create an running instance of a party when a certain address on the server is requested
* It then returns the address of a a websocket on which the party can be contacted. Usually this websocket will be on the same computer, but it might be elsewhere)
* The websocket connection implements 
 * 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)

In Genius2, this is implemented in the RunParty class. The class {{{Connection<Inform, Action>}}} (see the references module in genius2 core) represents an abstract connection, the actual conversion is done with Jackson in RunParty.

However different services could be implemented based on different languages, as long as the procedure above is met.

== Using the source code ==
You can download the source repository. Note that you don't need this if you just want to use the parties server.

{{{
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.





== Create new party instance 

A new instance of a party can be created by connecting to  {{{partiesserver/run/<party name>}}}, for instance


http://localhost:8080/partiesserver/run/randomparty-1.0.0


There are two possible responses from the party server:

1. a URL. This is the URL of the websocket behind which the newly instantiated party can be contacted.
2. error code 503 "Service Unavailable" if there is no room on the partiesserver at this moment to instantiate another party