HypersonicSQL

Contents of 01 Installation --> 05 Database --> 01 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.

JAR Configuration

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

<dependency>
    <groupId>hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <version>1.8.0.7</version>
</dependency>

Opening /uPortal/pom.xml there is a section about 90 lines down that reads:

<!-- The JDBC Driver used by uPortal -->
<jdbc.groupId>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.

JDBC Configuration

Edit /uPortal/uportal-impl/src/main/resources/properties/rdbm.properties and uncomment the lines for hsql Modify the URL, username and password as appropriate:

##### Hypersonic SQL - Server mode
##### Requires first starting Hypersonic SQL with the command:
##### "ant hsql"
hibernate.connection.driver_class=org.hsqldb.jdbcDriver
hibernate.connection.url=jdbc:hsqldb:hsql://localhost:8887
hibernate.connection.username=sa
hibernate.connection.password=
hibernate.dialect=org.hibernate.dialect.HSQLDialect

The /uPortal/uportal-impl/src/main/resources/properties/dbloader.xml properties file may also need to be modified. This file is used by the DbLoader tool to create the uPortal database tables and populate the database. It contains several sample entries which create db-type-mappings for different databases. Find the tags for an HypersonicSQL database and modify the db-version, driver-name, and driver-version as necessary. For example:

<db-type-mapping>
    <db-name>HSQL Database Engine</db-name>
    <db-version>1.8.0</db-version>
    <driver-name>HSQL Database Engine Driver</driver-name>
    <driver-version>1.8.0</driver-version>
    <type><generic>INTEGER</generic><local>INTEGER</local></type>
    <type><generic>VARCHAR</generic><local>VARCHAR</local></type>
    <type><generic>LONGVARCHAR</generic><local>LONGVARCHAR</local></type>
    <!-- map more types here -->
</db-type-mapping>

If using a different version of HSQL you will need to modify there strings for db-version and driver-version

Testing the Configuration

Start Postgres 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 dbloader.xml exactly.

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. See the HSQL OutOfMemoryError for a description of this 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