Storage

When running simulations you will likely want to store the data. Presage2 provides an abstract API through which you can store key-value data associated with agents and the environment at any timestep of the simulation. The StorageService provides an entry point to this API.

We provide a couple of different implementations of this API depending on what database software you wish to use. We will describe how to set up your projects to use each of these implementations when running presage2.

PostgreSQL

PostgreSQL is a high performance and fully featured RDBMS. Our implementation uses the hstore extension to provide key/value columns which match Presage2's storage API.

Installing

You will need PostgreSQL 9.1 or greater.

Debian/Ubuntu

From https://help.ubuntu.com/community/PostgreSQL):

[sudo] apt-get install postgresql-9.1 postgresql-contrib-9.1

Mac OSX

With homebrew:

brew install postgresql
initdb /usr/local/var/postgres
# start server
pg_ctl -D /usr/local/var/postgres -l logfile start

Windows

With the installer.

Configuring

Note: On Debian/Ubuntu systems you will have to prefix the shell commands in this section with sudo -u postgres in order to run them as the postgres user. On Mac OSX this is not necessary as your user account will have superuser privileges.

First you need to set up a login for the postgres administrator account. Login via psql command:

psql postgres

Set password for "postgres" database role:

\password postgres

Type Control+D to exit the prompt.

Now create a database and a user for presage2.

createuser -D -R -S presage_user
createdb -O presage_user presage

Finally log into the newly created database and set up the user's password and the hstore extension:

psql presage

\password presage_user
CREATE EXTENSION hstore;

Setting up Presage2

Firstly you will need to add the presage2-sqldb jar to your dependencies. If using Maven add the following to the dependencies section of your pom.xml:

<dependency>
	<groupId>uk.ac.imperial.presage2</groupId>
	<artifactId>presage2-sqldb</artifactId>
	<version>${presage.version}</version>
</dependency>

Presage2 reads a db.properties file to determine how to load a database on startup. This file should be in your classpath. If you are following a standard maven2 file structure you can put it in the src/main/resources folder. You should add the following to your db.properties:

module=uk.ac.imperial.presage2.db.sql.SqlModule
url=jdbc:postgresql://localhost/presage
user=presage_user
password={password}

Obviously insert the relevant values for url, user and password for your installation.

MongoDB

Mongodb is a document based storage engine. It is very fast and ideally suited to the structure of the presage2 API.

Installing the software

On Debian systems:

[sudo] apt-get install mongodb

Setting up Presage2

Add presage2-mongodb to your dependencies in your pom.xml:

<dependency>
	<groupId>uk.ac.imperial.presage2</groupId>
	<artifactId>presage2-mongodb</artifactId>
	<version>${presage.version}</version>
</dependency>

Add the following to your db.properties:

module=uk.ac.imperial.presage2.db.mongodb.MongoModule
mongo.host={my.mongodb.host}
mongo.user={presage}
mongo.pass={password}

The mongo.* fields are optional. They will default to connecting to localhost with no user credentials given.

Hibernate

Hibernate is a object relational mapping library. It allows Java objects to be mapped to tables in a relational database. Supported databases include mysql, postgresql and sqlite.

General setup

Add presage2-hibernatedb to your dependencies in your pom.xml:

<dependency>
	<groupId>uk.ac.imperial.presage2</groupId>
	<artifactId>presage2-hibernatedb</artifactId>
	<version>${presage.version}</version>
</dependency>

As with mongoDB you will need a db.properties file in src/main/resources. This should simply reference the hibernate module:

module=uk.ac.imperial.presage2.db.hibernate.HibernateModule

Additionally you will need a hibernate.cfg.xml file in the same folder. This file specifies the settings to hibernate including the DBMS to use, it's JDBC driver, host and login credentials for the server and other internal settings. An example config for mysql is available in mysql.hibernate.cfg.xml.

Mysql

To use the Mysql driver with hibernate you will need to add the mysql JDBC driver as a dependency, then use the example hibernate.cfg.xml for mysql. Add the following to your pom.xml dependencies:

<dependency>
	<groupId>mysql</groupId>
	<artifactId>mysql-connector-java</artifactId>
	<version>5.1.6</version>
</dependency>

Then copy the contents of mysql.hibernate.cfg.xml to src/main/resources/hibernate.cfg.xml. Finally change the connection url, username and password in this file to the values for your database. Note that you will have to create the database in mysql before hibernate will be able to start using it; it will not create it for you.