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.

The first step is to generate the SQL statements that are specific for your target database vendor. The SQL statements will generate four 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 http://jakarta.apache.org/turbine/torque/index.html It can be found under the build/torque directory. 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 build/torque/build.properties. Choose your target database. Here are your current choices for version 1.3a2:

	# ------------------------------------------------------------------- # # T A R G E T D A T A B A S E # # ------------------------------------------------------------------- # This is the target database, only considered when generating # the SQL for your Turbine project. Your possible choices are # # db2 # hypersonic # mysql # oracle # postgresql # mssql # # Default: none # ------------------------------------------------------------------- database=hypersonic

Save the build.properties file. From the command line in the build/torque directory, run the Torque build script by typing "ant". (Ensure that Jakarta Ant version 1.4 or greater is in your system path.) Torque will then generate your database-specific SQL commands. The PSML database definitions are stored in a vendor-neutral XML-format in the file build/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 src/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 and Turbine. (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. The User database is based on the Turbine Security model. See Turbine Schema You will need to run the "turbine" and "populate" scripts for your database. For example, with Oracle, first run "turbine-oracle.sql" to create the database tables, and then "populate-oracle.sql" to populate the tables.

Jetspeed needs to be configured to access a PSML database. You do this by editing the file webapp/WEB-INF/conf/TurbineResources.properties. The default settings are:

	database.default.driver=org.hsql.jdbcDriver database.default.url=jdbc:HypersonicSQL:${webappRoot}/WEB-INF/db/jetspeed database.default.username=sa database.default.password= database.adaptor=DBHypersonicSQL database.adaptor.DBHypersonicSQL=org.hsql.jdbcDriver

Modify these for your specific database driver. For example, Oracle my look something like this:

	database.default.driver = oracle.jdbc.driver.OracleDriver database.default.url = jdbc:oracle:thin:@host:1521:sid database.default.username=jetspeed database.default.password=jetspeed database.adaptor=DBOracle database.adaptor.DBOracle = oracle.jdbc.driver.OracleDriver

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, the following settings will need to be modified in the JetspeedResources.properties. Here are the default settings:

	services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService #services.PsmlImportManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService #services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.db.DatabasePsmlManagerService

To use the Database PSML service, comment out the 1st line (CastorPsmlManagerService) and then uncomment the 2nd and 3rd line. The 3rd line sets the DatabasePsmlManagerService as the default service. The 2nd line enables the PsmlImporter, which is run the very first time that you start the DatabasePsmlManagerService. It imports all the PSML files located in the WEB-INF/psml directory tree into the database. The importer is only ran once, the first time that the Database PSML Manager detects that the database is empty. This is what your entries should look to use the Database PSML service:

	#services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService services.PsmlImportManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.db.DatabasePsmlManagerService

This feature is implemented, but has not yet been enabled. In order to run it, you will need to modify the CastorPsmlManagerService to import on startup. Reference the Database PSML Manager for an example of how to do this.

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

Hypersonic	Version 1.4	Works with the default Jetspeed system as of version 1.3a2
Oracle	Version 8i	Works with the default Jetspeed system as of version 1.3a2