Configure - User Data Repository

These instructions explain how to set up the User Data Repository to use a relational database such as MySQL, Oracle or SQL Server.

Before starting, make sure you have installed SuperWEB2 and verified that it is working correctly.

Step 1 - Create the User Data Repository Database and Database User

The first step is to create a database for the User Data Repository in your chosen RDBMS. To complete this step you may need to install a suitable database server or obtain access to an existing database server:

Create a new database. For example, you might call the database UDR_SuperWEB2.
Create a dedicated database user account and set the account password.
Grant your new user account full privileges over your new database.

Step 2 - Install a JDBC Driver

JDBC (Java Database Connectivity) is a programming interface that lets Java applications access a relational database. You need to install a JDBC driver for your RDBMS, so that SuperWEB2 can communicate with the User Data Repository database.

Download the appropriate JDBC driver for your database:

RDBMS	Recommended Driver	Example of JAR File	Driver Class	Download From
MySQL	Connector/J	mysql-connector-java-5.1.7-bin.jar	com.mysql.jdbc.Driver	http://www.mysql.com/downloads/connector/j/
Oracle	ojdbc6.jar	ojdbc6.jar	oracle.jdbc.driver.OracleDriver	http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html
SQL Server	Microsoft JDBC Driver	sqljdbc4.jar	com.microsoft.sqlserver.jdbc.SQLServerDriver	http://www.microsoft.com/en-au/download/details.aspx?id=11774

Copy the driver .jar file to <tomcat_home>\lib. If you are using the standard Space-Time Research installation location, this will be C:\ProgramData\STR\SuperWEB2\Tomcat\lib

Step 3 - Configure the Data Source

The next step is to configure the data source by making changes to two configuration files: server.xml and context.xml.

server.xml

Open the file <tomcat_home>\conf\server.xml in a text editor.

Locate the <GlobalNamingResources> ... </GlobalNamingResources> section of the configuration:

XML

<GlobalNamingResources>
    <!-- Editable user database that can also be used by
         UserDatabaseRealm to authenticate users
    -->
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />
</GlobalNamingResources>

Add the following section before the closing </GlobalNamingResources> tag:

XML

<Resource name="ds/superstar-udr" auth="Container"
          type="javax.sql.DataSource"
          maxActive="100"
          maxIdle="30"  
          maxWait="10000"  
          username="USERNAME"
          password="PASSWORD"
          driverClassName="CLASSNAME"  
          url="URL"/>

You will need to customise this as follows:

Replace USERNAME and PASSWORD with the username and password of your new database user.
Replace CLASSNAME with the driver class for the database you are using (see the table above to find the correct value for your database driver).
Replace URL with the JDBC connection string for your database.

Following are some examples for the different database systems:

Click here to see an example for MySQL...

The following example is for MySQL. In this example:

mydatabasehost is the hostname of the machine running the MySQL database.
3306 is the port number.
udr_superweb_2 is the name of the new database we created in Step 1.

XML

<Resource name="ds/superstar-udr" auth="Container"
          type="javax.sql.DataSource"
          maxActive="100"
          maxIdle="30"  
          maxWait="10000"  
          username="udr_user"
          password="udr_password"
          driverClassName="com.mysql.jdbc.Driver"  
          url="jdbc:mysql://mydatabasehost:3306/udr_superweb2"/>

Click here to see an example for Oracle...

The following example is for Oracle. In this example:

mydatabasehost is the hostname of the machine running the Oracle database.
1521 is the port number.
UDR_SuperWEB_2 is the name of the new database we created in Step 1.

XML

<Resource name="ds/superstar-udr" auth="Container"
          type="javax.sql.DataSource"
          maxActive="100"
          maxIdle="30"  
          maxWait="10000"  
          username="udr_user"
          password="udr_password"
          driverClassName="oracle.jdbc.driver.OracleDriver"  
          url="jdbc:oracle:thin:@mydatabasehost:1521:UDR_SuperWEB2"/>

Click here to see an example for SQL Server...

The following example is for SQL Server. In this example:

mydatabasehost is the hostname of the machine running the SQL Server database.
1433 is the port number.
UDR_SuperWEB_2 is the name of the new database we created in Step 1.

XML

<Resource name="ds/superstar-udr" auth="Container"
          type="javax.sql.DataSource"
          maxActive="100"
          maxIdle="30"  
          maxWait="10000"  
          username="udr_user"
          password="udr_password"
          driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"  
          url="jdbc:sqlserver://mydatabasehost:1433;databaseName=UDR_SuperWEB2"/>

Save your changes to server.xml.

context.xml

Open the file <tomcat_home>\conf\context.xml in a text editor.

Add the following section before the closing </Context> tag:

XML

<ResourceLink
 global="ds/superstar-udr"
 name="ds/superstar-udr"
 type="javax.sql.DataSource"/>

Save your changes to context.xml.

Step 4 - Start SuperWEB2 and Verify UDR Configuration

Now that you have completed the configuration, start the Tomcat/SuperWEB2 service. This will automatically create the empty UDR tables in the database.

When you have done this, follow these instructions to verify that UDR is setup correctly.