Essentials Overview Features License Installation FAQ Sample Sites Resources Todo Changes Download Binaries Source Code Supporting Projects Documentation Configuration Guide Javadocs Development Portlet Howto Portlet Catalog Jetspeed Trailmap Components Registry Security Syndication WAP Customization Cache PSML Get Involved Contributors CVS Repository CVS Branches Coding Spec Bug Database |
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 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/dbpsml.properties. Choose your target database. Here are your current choices for version 1.4b1:
>     # -------------------------------------------------------------------
>     #
>     #  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 dbpsml.properties file. From the command line in the build directory, run the standard Jetspeed build by typing ant or build. 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 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
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 build/torque/build.properties file 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 src/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/TorqueResources.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.
Converting from PSML files to a PSML Database
> 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 /build directory, type:
>     ant 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:
>     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 /build directory, type:
>     ant import
PSML Database Maintance
Backup and datase optimization is not done by Jetspeed. These type of activitities must be performed outside of Jetspeed.
Tested Configurations
> 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
Copyright © 1999-2002, Apache Software Foundation