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:
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).
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.
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 http://db.apache.org/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 project.properties 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
# -------------------------------------------------------------------
database=hypersonic
Save the project.properties 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 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
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 project.properties 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/Torque.properties The default settings are:
torque.database.default.adapter=hypersonic
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.database.default.adapter=mysql torque.dsfactory.default.connection.driver = org.gjt.mm.mysql.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 'classes12.zip'. 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.
To switch to the Database PSML Manager, modify the PSML Manager settings in the JetspeedResources.properties. 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:
services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService
To switch to the Database PSML service, you will need to change the settings in the JetspeedResources.properties. Comment out the default, file-based PSML service:
#services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService
And then un-comment the Database PSML service:
services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.db.DatabasePsmlManagerService
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.
services.PsmlImportManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService
Finally, run the import process. From the root Jetspeed directory, type:
maven import
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:
services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService
#services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.db.DatabasePsmlManagerService
Next you will need to select the Database PSML service as your Importer Service.
services.PsmlImportManager.classname=org.apache.jetspeed.services.psmlmanager.db.DatabasePsmlManagerService
Choose the location on your file system where you'd like to export to:
services.PsmlManager.root=/tmp/psml7
Finally, run the import process. From the root Jetspeed directory, type:
maven import