PSML Database

PSML, an XML-based portal markup language, defines the presentation, layout and content of portal views. PSML was originally stored on the file system. To define or configure PSML, the portal administrator was required to edit the files on the file system with a text or XML editor. As of version 1.3a2, the Jetspeed Customizer feature allows editing and creation of PSML resources without knowledge of the PSML structure. Version 1.3a2 also introduces the PSML Database feature, allowing for the storage of PSML resources in JDBC-compliant databases.

When you configure your system to use a PSML Database, all of the PSML resources are stored in the database, and indexed on the standard runtime parameters:

  • User
  • Role
  • Group
  • Media Type
  • Language
  • Country
  • Page Name

The default Jetspeed installation is configured to use the PSML File System service. The PSML files can be found under the WEB-INF/psml directory tree. To convert to a PSML Database, you will need to first create the database schema in your target database (see: Creating PSML Database), and then import PSML files from the file system to the database (see: Configuring Jetspeed to use a PSML Database).

Why and when should a PSML Database be used

  • Large number of users (n+ user)
  • To increase performance and distribute processing.
  • To integrate Jetspeed Security with an existing database system.
  • To consolidate all portal information in a common, secure datastore.

Down side of using PSML Database

  • Jetspeed is dependent on the database to be up and running.
  • Jetspeed performance can be degraded by a slow database.
  • Added complexity
  • You must use the customizer to edit your PSML, and you will be dependent on the customizer supporting all PSML features. It is possible to export the PSML to the file system, and then import it back in. Alternatively, you can manipulate the PSML with SQL commands.

Creating PSML Database

The first step is to generate the SQL statements that are specific for your target database vendor. The SQL statements will generate three tables and their corresponding indices.

Using the Default Hypersonic Database

Jetspeed is distributed with a default Hypersonic database. The Hypersonic database is found in the WEB-INF/db directory of the web application, and comes with the four PSML tables pre-installed. To continue with the default Hypersonic configuration, skip to the next section: Configuring Jetspeed to use a PSML Database.

The Jetspeed distribution includes a object-relational database mapping tool: Torque Torque generates the SQL statements that you will use to create the PSML tables in your database. You will need to manually run these SQL statements from a tool provided by your database vendor. For example with Oracle, use SQL*Plus to run the scripts.

Generating the SQL file is very easy. First, edit the file in the root jetspeed source directory. Choose your target database. Here are your current choices for version 1.5:

# -------------------------------------------------------------------
#  T A R G E T  D A T A B A S E
# -------------------------------------------------------------------
# db2
# hypersonic
# mysql
# oracle
# postgresql
# mssql
# sybase
# -------------------------------------------------------------------

Save the file. From the command line in the root jetspeed directory, run the standard Jetspeed build by typing maven. Building DB-PSML is a part of the standard Jetspeed build. Torque will then generate your database-specific SQL commands. The PSML database definitions are stored in a vendor-neutral XML-format in the file src/torque-schema/dbpsml-schema.xml. Torque takes these definitions, and generates a file containing the vendor-specific SQL commands that will create the PSML tables in your database.

The SQL Script

The SQL Script is written to the file target/classes/sql/dbpsml-schema.sql. It contains the vendor-specific SQL commands. These commands create the PSML tables in your database. You will need to run the commands using a tool provided by your database vendor, such as SQL*PLUS with Oracle. Taking Oracle as an example, go to a command line, make sure that SQLPLUS is in your classpath, and type (from the jetspeed-root directory):

cd src/sql				 
sqlplus jetspeed/jetspeed @dbpsml-schema.sql				 

Of course you will need to create a user in Oracle named 'jetspeed' with the 'jetspeed' password. We are also assuming that you have already populated the Oracle database with the base Jetspeed tables. For instructions on doing so see Jetspeed Database Configuration

Configuring Jetspeed to use a PSML Database

To use DB-PSML, you will first need to setup your User database with Torque. (If you are using the default Hypersonic DB, these steps are not necessary since the database is pre-populated). Scripts are provided in the /src/sql/external directory to populate your database with the necessary default rows. The default scripts to populate for example, Oracle, is "populate-oracle.sql". You will need to run the "populate" scripts for your database. But first generate the DDL statements for your target database. This is done by modifying the file in the root directory of the Jetspeed source to select the target database system. Edit the 'database' property and set it to the target database of your choice. Then simply build Jetspeed. It will automatically generate the DDL script, which can be found in target/classes/sql/security-schema.sql You can then run this script in your database environment, and then run the populate script to populate the default tables. Then you are ready to create the DB-PSML tables as described above.

Jetspeed also needs to be configured to access any other database besides Hypersonic. You do this by editing the file webapp/WEB-INF/conf/ The default settings are:

torque.dsfactory.default.connection.driver = org.hsqldb.jdbcDriver
torque.dsfactory.default.connection.url = jdbc:hsqldb:${webappRoot}/WEB-INF/db/jetspeed
torque.dsfactory.default.connection.user = sa 
torque.dsfactory.default.connection.password = 

Modify these for your specific database driver. For example, for MySQL it will look something like this:

torque.dsfactory.default.connection.driver =
torque.dsfactory.default.connection.url = jdbc:mysql://localhost:3306/jetspeed
torque.dsfactory.default.connection.user =  root
torque.dsfactory.default.connection.password = 

Don't forget to put the JDBC driver's JAR file in your classpath or in the webapp/WEB-INF/lib directory. With Oracle, the driver may be named something like ''. This file is really a JAR, and can safely be renamed to classes12.jar. If you are placing the driver in Tomcat's /webapps/jetspeed/WEB-INF/lib directory, then it must be renamed to .JAR or it will not be found.

Converting from PSML files to a PSML Database

To switch to the Database PSML Manager, modify the PSML Manager settings in the You can select your active PSML Manager service by uncommenting it. There can only be one PSML Service active. The default is the file-based service: 'CastorPsmlManagerService'. If you uncomment one service, you must comment the other service. Here are the default setting:

To switch to the Database PSML service, you will need to change the settings in the Comment out the default, file-based PSML service:

And then un-comment the Database PSML service:

Next you will need to select the appropriate Importer Service. When exporting from the file system to the database, choose the File-based service to manage the importing. Its the PsmlImportManager service that manages the import process, actually exporting from its datastore to the consumer datastore.

Finally, run the import process. From the root Jetspeed directory, type:

maven import

Converting from a PSML Database to PSML files

You may need export your PSML from the database to the file system. Here are the steps to do so. Choose the File-based PSML manager:

Next you will need to select the Database PSML service as your Importer Service.

Choose the location on your file system where you'd like to export to:


Finally, run the import process. From the root Jetspeed directory, type:

maven import

PSML Database Maintance

Backup and database optimization is not done by Jetspeed. These type of activitities must be performed outside of Jetspeed.

Tested Configurations

HypersonicVersion 1.7.1Works with the default Jetspeed system as of version 1.3a2
OracleVersion 8iWorks with the default Jetspeed system as of version 1.3a2