HEAD

Appendix B
Database Setup

The JMatter framework taps the power of database systems. JMatter employs the excellent Hibernate "O/R Mapping" framework which affords it database independence. That is, you're not constrained to using a specific database system. Options include PostgresQL, MySQL, Oracle, DB2, Sybase, Informix, SAP DB, and many more.

JMatter is tested primarily with PostgresQL and H2 (see http://www.h2database.org/), and has been verified to work with Oracle and MySQL.

We recommend either H2: a full-featured, minimal administration, fast, Java-implemented database, or PostgresQL: a mature, stable and open source database.

The JMatter distribution pre-bundles JDBC drivers for PostgreSQL, MySQL, and H2 and hsqldb. If you choose to use a different database vendor, you will need to obtain the corresponding JDBC driver jar file and place it in the jmatter/lib/runtime/jdbc directory.

B.1 Configuring your own database for the ContactMgr Tutorial Application

B.1.1 Create a Database

We'll use PostgresQL as an example.

To create a database in PostgresQL, invoke a command similar to this one:

: $ createdb -U postgres contactmgr

The -U flag is used to specify the name of the user who is creating the database. The username you should use depends on your specific installation (consult the PostgresQL documentation).

You might also want to create a user specifically for this application²⁶:

: $ createuser -U postgres contactmgr

B.1.2 Specify the Database Connection Information

Make sure that you're in the ContactMgr folder before proceeding. Edit the file resources/hibernate.properties. Modify these three lines accordingly²⁷:

: #
hibernate.connection.url=jdbc:postgresql://localhost/contactmgr
hibernate.connection.username=contactmgr
hibernate.connection.password=

If you're using a database other than PostgresQL, you'll also need to revise these two lines:

: #
hibernate.connection.driver_class=org.postgresql.Driver
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

Save the file.

B.1.3 Generate the Database Schema

From the ContactMgr base directory, invoke this command:

: $ ant schema-export

B.1.4 Browsing the database schema with psql

: $ psql contactmgr
contactmgr=> dt
                 List of relations
Schema -         Name          - Type   -    Owner
--------+---------------------+-------+------------
public - business             - table - contactmgr
public - commandrestriction   - table - contactmgr
public - complextype          - table - contactmgr
public - compositequery       - table - contactmgr
public - contactmethod        - table - contactmgr
public - fieldrestriction     - table - contactmgr
public - folder               - table - contactmgr
public - folder_items         - table - contactmgr
public - loggedevent          - table - contactmgr
public - person               - table - contactmgr
public - queryspecifications - table - contactmgr
public - restriction          - table - contactmgr
public - role                 - table - contactmgr
public - users                - table - contactmgr
public - usstate              - table - contactmgr
(15 rows)