HypersonicSQL

Overview

Hypersonic SQL is an open source Java database engine with a standard SQL and JDBC interface. It is available from Sourceforge.

uPortal ships with a HSQL database to be used for basic development and testing. HsqlDb is not suitable for qa or production environments.

The uPortal release is initially configured to use HypersonicSQL so configuration of properties most likely will not be necessary. The information provided here is mostly provided for verification that the system is set up correctly.

Step 1: Add the Dependency

The first step is to determine the correct information to use in uPortal-4.x.x/pom.xml. Using a Maven Artifact Search Site and searching for "org.hsqldb" we find the following Maven dependency declaration here.

<dependency>
    <groupId>org.hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <version>2.2.8</version>
</dependency>

From the uPortal source directory, open uPortal-4.x.x/pom.xml, there is a section about 90 lines down that reads:

<!-- The JDBC Driver used by uPortal -->
<jdbc.groupId>org.hsqldb</jdbc.groupId>
<jdbc.artifactId>hsqldb</jdbc.artifactId>
<jdbc.version>${hsqldb.version}</jdbc.version>

The ${hsqldb.version} string refers to a property set in uPortal/pom.xml, dependency versions are centralized in this pom to ensure they stay consistent between child modules in the project.

Step 2: Configure the Database Filter

1. In the filters folder, locate the default local.properties file under uPortal-4.x.x/filters/local.properties and configure the Database Connection Settings

uPortal/filters/local.properties

# HSQL Configuration
environment.build.hsql.port=8887

# Database Connection Settings (Uncomment the Maven Filters section in rdbm.properties)
environment.build.hibernate.connection.driver_class=org.hsqldb.jdbc.JDBCDriver
environment.build.hibernate.connection.url=jdbc:hsqldb:hsql://localhost:${environment.build.hsql.port}/uPortal
environment.build.hibernate.connection.username=sa
environment.build.hibernate.connection.password=
environment.build.hibernate.dialect=org.hibernate.dialect.HSQLDialect

Step 3: Test the Configuration

Start hsqldb and then in your portal development directory, issue the command:

ant dbtest

If your configuration is correct the output should look very similar to:

Buildfile: build.xml

dbtest:

install-parent-pom:
[artifact:install] [INFO] Installing /home/edalquist/JavaClasses/workspace_33/uPortal/pom.xml to
/home/edalquist/.m2/repository/org/jasig/portal/uportal-parent/3.0.0/uportal-parent-3.0.0.pom
    [touch] Creating /tmp/uportal-parent.pom-2117287939-marker
[artifact:dependencies] Downloading: javax/script/script-api/1.0/script-api-1.0.pom from jasig-repository
[artifact:dependencies] Downloading: javax/script/script-api/1.0/script-api-1.0.pom from central
[artifact:dependencies] Downloading: groovy/groovy-all/1.0/groovy-all-1.0.pom from jasig-repository
[artifact:dependencies] Downloading: groovy/groovy-all/1.0/groovy-all-1.0.pom from central
[artifact:dependencies] Downloading: javax/script/groovy-engine/1.0/groovy-engine-1.0.pom from jasig-repository
[artifact:dependencies] Downloading: javax/script/groovy-engine/1.0/groovy-engine-1.0.pom from central
     [echo] Artifact '/home/edalquist/JavaClasses/workspace_33/uPortal_trunk/uportal-impl/target/uportal-impl-3.0.0.jar' is up-to-date
[artifact:install] [INFO] Installing /home/edalquist/JavaClasses/workspace_33/uPortal_trunk/uportal-impl/target/uportal-impl-3.0.0.jar to
/home/edalquist/.m2/repository/org/jasig/portal/uportal-impl/3.0.0/uportal-impl-3.0.0.jar
     [echo] Invoking DbTest
     [java]  INFO [main] spring.PortalApplicationContextLocator Mar/20 14:51:48.149 - Creating new lazily initialized GenericApplication...
     [java]  INFO [main] jpa.HibernateJpaVendorAdapter Mar/20 14:51:50.907 - Setting CacheProvider 'org.jasig.portal.utils.cache....
     [java] AbandonedObjectPool is used (org.apache.commons.dbcp.AbandonedObjectPool@42a6eb)
     [java]    LogAbandoned: true
     [java]    RemoveAbandoned: true
     [java]    RemoveAbandonedTimeout: 300
     [java]  INFO [main] jndi.DisposableMemoryContextFactory Mar/20 14:51:52.937 - Created new MemoryContext with environment ...
     [java]  INFO [main] properties.PropertiesManager Mar/20 14:51:52.973 - Property [org.jasig.portal.car.CarResources.directory] ...
     [java]  INFO [main] car.CarResources Mar/20 14:51:52.973 - CAR directory property 'org.jasig.portal.car.CarResources.directory'...
Defaulting to well-known directory '/WEB-INF/cars'.
     [java]  INFO [main] jndi.JndiManagerImpl Mar/20 14:51:53.081 - Initialized portal JNDI context
     [java]  INFO [main] spring.PortalApplicationContextLocator Mar/20 14:51:53.099 - Created new lazily initialized GenericApplication...
     [java] Parsing jar:file:/home/edalquist/JavaClasses/workspace_33/uPortal_trunk/uportal-impl/target/uportal-impl-3.0.0.jar!/properties/...
     [java]  WARN [main] rdbm.DatabaseMetaDataImpl Mar/20 14:51:53.269 - The uPortal database is not initialized, the database tests ...
     [java]  INFO [main] rdbm.DatabaseMetaDataImpl Mar/20 14:51:53.270 - HSQL Database Engine (1.8.0) / HSQL Database Engine Driver (1.8.0)...
     [java]     Connected To: jdbc:hsqldb:hsql://localhost:8887
     [java]     WARNING: uPortal tables do no exist, not all meta-data tests were executed.

     [java] Database name:    'HSQL Database Engine'
     [java] Database version: '1.8.0'
     [java] Driver name:      'HSQL Database Engine Driver'
     [java] Driver version:   '1.8.0'
     [java] Driver class:     'HSQL Database Engine Driver'
     [java] Connection URL:   'jdbc:hsqldb:hsql://localhost:8887'
     [java] User:             'SA'

     [java] Type Mappings: [Type[genericType=VARCHAR,local=VARCHAR], Type[genericType=INTEGER,local=INTEGER],...

     [java] supportsANSI92EntryLevelSQL: false
     [java] supportsANSI92FullSQL:       false
     [java] supportsCoreSQLGrammar:     true
     [java] supportsExtendedSQLGrammar: false

     [java] supportsTransactions:         true
     [java] supportsMultipleTransactions: true
     [java] supportsOpenCursorsAcrossCommit:      false
     [java] supportsOpenCursorsAcrossRollback:    false
     [java] supportsOpenStatementsAcrossCommit:   true
     [java] supportsOpenStatementsAcrossRollback: true

     [java] supportsStoredProcedures:     true
     [java] supportsOuterJoins:           true
     [java] supportsFullOuterJoins:       false
     [java] supportsLimitedOuterJoins:    true
     [java] supportsBatchUpdates:         true
     [java] supportsColumnAliasing:       true
     [java] supportsExpressionsInOrderBy: true
     [java] supportsOrderByUnrelated:     true
     [java] supportsPositionedDelete:     false
     [java] supportsSelectForUpdate:      false
     [java] supportsUnion:                true
     [java] supportsUnionAll:             true

     [java] getMaxColumnNameLength: 0
     [java] getMaxColumnsInIndex:   0
     [java] getMaxColumnsInOrderBy: 0
     [java] getMaxColumnsInSelect:  0
     [java] getMaxColumnsInTable:   0
     [java] getMaxConnections:      0
     [java] getMaxCursorNameLength: 0
     [java] getMaxIndexLength:      0
     [java] getMaxRowSize:          0
     [java] getMaxStatements:       0
     [java] getMaxTableNameLength:  0
     [java] getMaxTablesInSelect:   0
     [java] getMaxUserNameLength:   0
     [java] getSearchStringEscape:  \
     [java] getStringFunctions:     ASCII,BIT_LENGTH,CHAR,CHAR_LENGTH,CHARACTER_LENGTH,CONCAT,DIFFERENCE,HEXTORAW,...
     [java] getSystemFunctions:     DATABASE,USER,IDENTITY
     [java] getTimeDateFunctions:   CURDATE,CURTIME,DATEDIFF,DAYNAME,DAY,DAYOFMONTH,DAYOFWEEK,DAYOFYEAR,HOUR,MINUTE,...

     [java] Table Types: GLOBAL TEMPORARY,SYSTEM TABLE,TABLE,VIEW
     [java] SQL Types:   TINYINT,BIGINT,LONGVARBINARY,VARBINARY,BINARY,LONGVARCHAR,CHAR,NUMERIC,DECIMAL,INTEGER,SMALLINT,...

BUILD SUCCESSFUL
Total time: 11 seconds

Verify the values on the Database name, Database version, Driver name, Driver version match those entered in local.properties exactly.

Step 4: Build and Deploy

Following a successful test, you can execute the command below to build the database tables and copy files to your servlet container.

Note: Executing the command "ant clean initportal" will drop and recreate the database tables and all existing data will be lost. This will result in a clean uPortal database structure. If you want to keep the contents of your existing database, use "ant clean deploy-war"

ant clean initportal

Step 5: Restart Tomcat

Additional notes

With the quick-start distribution the ant 'start' and 'stop' targets start and stop both the hsqldb instance uPortal uses and the Tomcat instance uPortal is deployed to.

For the uPortal only distribution "ant hsql" will start the database and the "ant hsql-shutdown" target will stop it. Doing a CTRL^C in the window running the hsql database will also stop the database. The "-Dspawn=true" option can be specified with "ant hsql" to start the database in the background.

Issues and Known Bugs

Some people have encountered a problem with HypersonicSQL where the database fills up with thousands of rows in the UP_USER table with a user id of "0" and user name of "system" with the rest of the fields as null values. Deleting these rows seems to fix the problem.

HypersonicSQL is considered a lightweight database that is not recommended for production use in a large installation.

Having problems with these instructions?

Please send us feedback at uportal-user@lists.ja-sig.org