GeniusWeb ProfilesServer

This is the home page of the GeniusWeb profiles server. This server serves domain and profile files to interested parties, and can inform them of changes.

The profilesserver only serves profiles, it does not define them. To define profiles, check the geniusweb core pages.

The GeniusWeb core/main page is ​here.

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 ​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 profilesserver should be up and running.

NOTICE: The server provides URIs to connect with profiles. These URI's contain hard IP numbers that are determined automatically using InetAddress.getLocalHost. If you have multiple network adapters, unexpected IP numbers may be generated.

Upgrade

To upgrade,

• Stop tomcat
• remove the old war file plus the unzipped version (if exists) from the tomcat webapps directory
• repeat the installation as above

Using the GUI

After installing and starting, go to ​http://localhost:8080/profilesserver-1.0.0 (replace 1.0.0 with the version you installed) to see if it works. You should get a GUI like this

You can then click on the provided links to view the available profiles and to look into their exact contents. Also the server can now be approached by parties to get a websocket stream of a profile, which facilitates real-time reporting of any changes made to the profile.

Adding or changing a Profile

To change a profile or add a new profile,

• Make sure the profiles server has been run (apache will unzip the war file)
• Locate the unzipped profilesserver folder inside your tomcat webapps directory
• locate the domainsrepo directory inside that folder. This folder contains all current profiles
• Copy your new version of a profile over an existing one.
• To create a new profile, make a new folder with a name matching the name of the domain
• Copy the domain description into the folder
• Copy the profile(s) into the folder.
• The files should now show up in the "list of domain and profile files" on the server webpage. Make sure you force refresh the page as some browsers show only old cached data.
• If the file is visible in that list, but does not show up in "list of currently available profiles" then the files do not contain a valid profile. Check the apache tomcat logs to see why the files have been rejected.

Custom profiles directory

By default, the profiles server determines the profiles directory by searching for a "domainsrepo" folde rinside your tomcat webapps directory. However, this may be inconvenient as this directory might be reset to the default contents when you install a new version of the profilesserver war file. Also, using a custom directory might be more secure. It is possible to use a custom profiles repository directory by setting the system environment variable PROFILES_ROOTDIR. This path must contain a full absolute path to the alternative domainsrepo directory. Its name can be different from "domainsrepo".

JSON structure of profile

The structure of a profile is part of the core and described on the ​genius main wiki.

Communication protocol

This section describes the communication protocols with the profilesserver.

Other implementations of a profilesserver should adhere to the same communication protocols to ensure compatibility with geniusweb.

List of available profiles

Clients can receive the list of available profiles as follows

• create a websocket to the server at ws:...profilesserver/websocket/liststream
• The server sends the clients a JSON map. The keys in the map are the websocket URI of the domain description. The values in the map are a list of available profiles for this domain, again websocket URIs. This map looks like this in JSON

   {"ws://...:8080/profilesserver/websocket/get/jobs":
     [  "ws://...:8080/profilesserver/websocket/get/jobs/jobs1",
        "ws://...:8080/profilesserver/websocket/get/jobs/jobs2"
     ]
   }
  

• A new, full list is sent every time something changes in the list.

The java implementation provided here continuously checks the files inside the apache-tomcat directory webapps/profilesserverXXX/domainsrepo. If you drop or rename files in there, it is detected automatically, the files are (re) parsed and made available.

This implementation also contains default profiles:

domain	profile
jobs	jobs1, jobs2
7issues	7issues1, 7issues2
party	party1, party2, party3, party4, party1partial
laptop	laptopBuyer, laptopSeller

Get a profile

Clients can get the profile or domain description as follows

• create a websocket to the address contained in the received profiles list (above).
• The websocket receives the profile from the server in json format.
• parse the json format either as Profile or as Domain, see the java example below.

Get a filtered profile

A client can get a filtered version of a profile by setting query arguments to the websocket URL. The following filter options are available

filter option	query value	explanation
partial	integer N>=0	a query key that is assigned a natural number N (0 or larger). If set, the profile is converted into a Partial Profile with the given number of points. If N>0, the maximum utility bid is included .If N>1, the minimum utility bid is included. The other bids are picked at random. This filtering mechanism only works if the profile is {@link LinearAdditive} space.

For example, the query to the profiles server using this url ws://localhost:8080/profilesserver/websocket/get/7issues/7issues2?partial=3 will return a DefaultPartialOrdering derived from the 7issues2 profile, but containing only 3 bids.

Downloading a profile programatically

This section gives an example on how to use the websocket to get a profile. To download a profile in your agent, create a websocket and fetch the profile.

There are java examples available here. Basically you just open a websocket and read the incoming profile like this (NOTICE: this is using neovisionaries WebSocketAdapter which is an external library; but we recommend the java built-in javax.websocket, see the examples)

WebSocketFactory factory = new WebSocketFactory().setConnectionTimeout(5000);
WebSocket ws = factory.createSocket("ws://localhost:8080/profilesserver/websocket/get/jobs/jobs1");
ws.addListener(this);

...

@Override
public void onTextMessage(WebSocket websocket, String json) throws Exception {
	System.out.println("received profile: " + new ObjectMapper().readValue(json, Profile.class));
}

or, similarly in python

class PythonDownloadProfile(WebSocketAdapter):
...
        factory = WebSocketFactory()
        factory.setConnectionTimeout(5000)
        ws = factory.createSocket("ws://localhost:8080/profilesserver/websocket/get/jobs/jobs1")
        ws.addListener(self)

    def onTextMessage(self, websocket, json):
        print "received message: "+json

or, using a shell command

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: localhost:8080" -H "Sec-WebSocket-Version: 13" -H 'Sec-WebSocket-Key: +onQ3ZxjWlkNa0na6ydhNg==' -H "Origin: localhost:8080" http://localhost:8080/profilesserver-1.4.0/websocket/get/jobs/jobs1

(notice you will need to fix 1.4.0 to the correct version!)

Using the source code

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

svn checkout https://tracinsy.ewi.tudelft.nl/pub/svn/GeniusWebProfilesServer/

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/pubtrac/GeniusWeb/wiki/WikiStart

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