Switching to Enterprise-Scale Databases in Sun Java System Portal Server for Collaboration

Print-friendly Version

Sun Java System Portal Server 7.1 (henceforth, Portal Server), part of Sun Java Enterprise System 5, offers a collaboration capability, which is a combination of communities and collaborative service applications hosted by the communities. This article is a guideline for deploying that collaboration capability in a production environment in which you can establish an enterprise-scale community. Such a community must be supported by a solid data storage system—a database—that guarantees high availability, as governed by the following:

• Fault tolerance: No single point of failure and automatic or well-defined recovery mechanism
  
  
• High scalability: Provision for nonintrusive addition of resources, such as servers and disks

Portal Server bundles Derby, a lightweight, open-source database. In this article, you learn how to replace Derby with the more enterprise-scale Oracle database so as to take advantage of the high-availability feature offered by the Oracle Real Application Clusters (RAC). Although this article focuses on Oracle, it can also serve as a stepping stone for integrating Portal Server with other relational database management systems (RDBMS).

Note: The following subjects are outside the scope of this article:

• How to migrate data from Derby or other databases to a different database
• How to tune Derby to perform as an enterprise-class database
• How to set up the Oracle RAC

To deploy the community-collaboration capability on the Oracle database, you must first install the following software:

• Portal Server 7.1 or a later release
• The collaboration capability, enabled and functional on Portal Server
• Oracle Database 10g Release 2

From the early days of designing the collaboration capabilities in Portal Server, the ability to switch the underlying datastore has been a main focus. Every effort has been made to ensure that all collaboration components can operate in a database-neutral way. The following examples demonstrate those design decisions:

• Implementation of community membership and configuration by means of Java data objects (JDO)
  
  
• Adoption of Java Database Connectivity (JDBC) technology and Java Naming and Directory Interface (JNDI) in collaboration services
  
  
• A customization framework of portlet applications that enables reconfiguration and redeployment of collaboration services

As shipped, you use databases in collaboration in a couple of areas:

• Community membership and configuration (communitymc) — This information persists in the database.
  
  
• Collaboration services — These are community-aware, Java Specification Request (JSR) 168-based portlet applications, such as Fileshare, Surveys/Polls, and Wiki, which use databases for persistent storage.

The idea of replacing a database is to use the data access layer (JDBC resource) as a switching point. By modifying or creating JDBC resources, collaboration components can connect to various databases.

First, each of the collaboration components connects to the database through a JDBC resource, which is looked up with JNDI. That resource encapsulates database-specific connection parameters, such as the target database type, host name, port number, and authentication credentials. Once the connection is made, each component invokes the appropriate database-specific JDBC operations.

Figure 1 and Figure 2 illustrate the process.

Figure 1: Collaboration Components Accessing Derby Database (Out-of-Box Configuration)

Figure 2: Collaboration Components Accessing Oracle Database

This section summarizes the procedure for replacing Derby with another database and details the steps for switching from Derby to Oracle.

Here is a summary of the procedure for replacing Derby with another database:

1. Prepare the new database.
   
   
   1. Install an RDBMS or identify one that is already on the system.
      
      
   2. Create a database instance (or a tablespace in the case of Oracle) for collaboration.
      
      
   3. Create the appropriate database user accounts.
      
      
   4. Establish the appropriate privileges for the user accounts.
   
   
2. Prepare the Web container for the new database.
   
   
   1. Locate the JDBC driver and add it to the Web container's Java virtual machine classpath.
      
      
   2. Add the Java virtual machine option -Djdbc.drivers=jdbc-driver.
   
   
3. Set up the community membership and configuration.
   
   
   1. Set up the communitymc database configuration file (PortalServer-DataDir/portals/portal-ID/config/portal.dbadmin).
      
      
   2. Delete the Derby-specific property in the PortalServer-DataDir/portals/portal-ID/config/communitymc.properties file.
      
      
   3. Load the schema into the database.
      
      
   4. Edit the JDBC resource file (jdbc/communitymc) to point to the new database.
      
      Note: Some Web containers might require that you edit the corresponding JDBC connection pool instead of the JDBC resource.
   
   
4. Configure and install the portlet applications.
   
   
   1. Locate the portlet applications under PortalServer-DataDir/portals/portal-ID/portletapps.
      
      
   2. Configure the portlet applications to use the new database by revising the tokens_xxx.properties file.
      
      
   3. From the administration console or the command line, create a JDBC resource for each of the portlet applications with the following values from the tokens_xxx.properties file:
      
      

      Resource JNDI Name	jdbc/db-JNDI-name
      Resource Type	javax.sql.ConnectionPoolDataSource
      DataSource class name	db-datasource
      User	db-user-name
      Password	db-password
      URL	db-URL

       
      Note: Some Web containers might require that you set up the connection pool before the JDBC resource.
      
      
   4. Undeploy the existing portlets, that is, the ones that use Derby as their datastore.
      
      
   5. Deploy the newly configured portlet applications.

This section describes the steps for replacing Derby with the Oracle database.

1. Install Oracle Database 10g Release 2.
   
   
2. Create a database instance named portal, that is, SID=portal.
   
   
3. Log in to Oracle Enterprise Manager, usually at http://hostname:5500/em, as SYSTEM.
   
   
4. Create a tablespace communitymc_portal-ID, for example, communitymc_portal1.
   
   
5. Create a user account with the following properties:
   
   

   User Name	portal
   Password	password
   Default Tablespace	communitymc_portal-ID
   Roles	CONNECT and RESOURCE

1. Locate the Oracle JDBC driver (ojdbc14.jar).
   
   On the machine where Oracle is installed, the driver normally resides at $ORACLE_HOME/jdbc/lib/ojdbc14.jar. Alternatively, you can download the driver from the Oracle site. Be sure that the version that you download is compatible with the Oracle RDBMS you plan to use.
   
   
2. From the administration console or the command line, add the driver (ojdbc14.jar) to the Java virtual machine classpath and then add the Java virtual machine option -Djdbc.drivers=oracle.jdbc.OracleDriver.

1. Edit the communitymc configuration file at PortalServer-DataDir/portals/portal-ID/config/portal.dbadmin and edit the db.driver, db.driver.classpath, and community.db.url lines to read as follows:
   
   db.driver=oracle.jdbc.OracleDriver
db.driver.classpath=path-to-JDBC-driver/ojdbc14.jar
community.db.url=jdbc:oracle:thin:@//Oraclehost.domain:Oracleportnumber/Oracleservicename
   
   Alternatively, use the Oracle Net connection descriptor format, as follows:
   
   community.db.url=jdbc:oracle:thin:@(DESCRIPTION\=(LOAD_BALANCE\=on)
(ADDRESS_LIST=(ADDRESS\=(PROTOCOL=TCP)(HOST\=Oraclehost1.domain)
(PORT\=Oracleportnumber))(ADDRESS\=(PROTOCOL\=TCP)(HOST\=Oraclehost2.domain)
(PORT\=Oracleportnumber)))(CONNECT_DATA\=(SERVICE_NAME\=Oracleservicename)))
   
   
2. Delete or comment out the following property from the communitymc properties file (PortalServer-DataDir/portals/portal-ID/config/communitymc.properties):
   
   #javax.jdo.option.Mapping=derby
   
   
3. Load the community schema into the Oracle database. Type:
   
   % cd PortalServer-DataDir/portals/portal-ID/config
% ant -Dportal.id=portal-ID -f config.xml configure
   
   
4. Edit the JDBC resource file (jdbc/communitymc) to point to Oracle.
   
   
   1. Log in to the Web container's administration console.
   2. Locate the JDBC resource named jdbc/communitymc.
   3. Set the DataSource class name to oracle.jdbc.pool.OracleConnectionPoolDataSource.
   4. Set the following properties:
      
      

      User:	portal
      Password:	password
      URL:	jdbc:oracle:thin:@//Oraclehost.domain:Oracleportnumber/Oracleservicename

       
      Alternatively, use the Oracle Net connection descriptor format, as follows:
      
      jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)
(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=Oraclehost1.domain)
(PORT=Oracleportnumber))(ADDRESS=(PROTOCOL=TCP)(HOST=Oraclehost2.domain)
(PORT=Oracleportnumber)))(CONNECT_DATA=(SERVICE_NAME=Oracleservicename)))
      
      Note: Some Web containers might require that you edit the corresponding JDBC connection pool instead of the JDBC resource.

Each Web container has its own way of defining JDBC resources and the terminology might vary between Web containers. Use the following procedure as a guideline only.

1. Locate the Fileshare portlet application at PortalServer-DataDir/portals/portal-ID/portletapps/filesharing.
   
   
2. Edit the tokens_ora.properties file, as follows.
   
   

   Token	Sample Value	Remarks
   DB_ADMIN_DRIVER_CLASSPATH	/app/oracle/product/10.2.0/db_1/jdbc/lib/ojdbc14.jar	This is the information about the database connection during the initial loading of the schema.
   DB_ADMIN_URL	jdbc:oracle:thin:@Oraclehost.domain: Oracleportnumber/Oracleservicename Alternatively, use the Oracle Net connection descriptor format: jdbc:oracle:thin:@(DESCRIPTION\=(LOAD_BALANCE\=on) (ADDRESS_LIST=(ADDRESS\=(PROTOCOL=TCP) (HOST\=Oraclehost1.domain) (PORT\=Oracleportnumber))(ADDRESS\=(PROTOCOL\=TCP) (HOST\=Oraclehost2.domain)(PORT\=Oracleportnumber))) (CONNECT_DATA\=(SERVICE_NAME\=Oracleservicename)))
   DB_ADMIN_USER	system
   DB_ADMIN_PASSWORD	Oracle-system-password
   DB_URL	jdbc:oracle:thin:@Oraclehost.domain: Oracleportnumber/Oracleservicename Alternatively, use the Oracle Net connection descriptor format: jdbc:oracle:thin:@(DESCRIPTION\=(LOAD_BALANCE\=on) (ADDRESS_LIST=(ADDRESS\=(PROTOCOL=TCP) (HOST\=Oraclehost1.domain) (PORT\=Oracleportnumber))(ADDRESS\(PROTOCOL\=TCP) (HOST\=Oraclehost2.domain) (PORT\=Oracleportnumber))) (CONNECT_DATA\=(SERVICE_NAME\=Oracleservicename)))	This is the information about the database connection during the runtime of the application.
   DB_USER	portalfs
   DB_PASSWORD	password
   DB_DRIVER_JAR	/app/oracle/product/10.2.0/db_1/jdbc/lib/ojdbc14.jar
   DB_TABLESPACE_NAME	filesharingdb_portal-ID	This is the information for creating a new tablespace.
   DB_TABLESPACE_DATAFILE	/app/oracle/oradata/portal/filesharingdb_portal-ID
   DB_TABLESPACE_INIT_SIZE	100M

   
   
   
3. From the admin console or the command line in the Web container, create a JDBC resource with the values from the tokens_ora.properties file, as follows.
   
   

   Property	Value	Remarks
   Resource JNDI Name	jdbc/OracleFileSharingDB	This value must match the DB_JNDI_Name value in tokens_ora_properties.
   Resource Type	javax.sql.ConnectionPoolDataSource
   DataSource Class Name	oracle.jdbc.pool.OracleConnectionPoolDataSource	This value must match the DB_DATASOURCE value in tokens_ora_properties.
   User Name	portalfs	This value must match the DB_USER value in tokens_ora_properties.
   Password	password	This value must match the DB_PASSWORD value in tokens_ora_properties.
   URL	jdbc:oracle:thin:@Oraclehost.domain:Oracleportnumber/Oracleservicename Alternatively, use the Oracle Net connection descriptor format: jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on) (ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP) (HOST=Oraclehost1.domain) (PORT=Oracleportnumber))(ADDRESS=(PROTOCOL=TCP) (HOST=Oraclehost2.domain)(PORT=Oracleportnumber))) (CONNECT_DATA=(SERVICE_NAME=Oracleservicename)))	This value must match the DB_URL value in tokens_ora_properties.

   
   
   Note: Some Web containers might require that you set up the JDBC connection pool before the JDBC resource.
   
   
4. Undeploy the existing filesharing portlet, that is, the one that uses Derby as its datastore. Type, for example:
   
   % /opt/SUNWportal/bin/psadmin undeploy-portlet -u \
uid=amadmin,ou=people,dc=acme,dc=com -f password-filename \
   -p portal-ID -i portal-instance-name filesharing
   
   
5. Deploy the newly configured filesharing portlet. Type:
   
   % cd PortalServer-DataDir/portals/portal-ID/portletapps/filesharing
% ant -Dapp.version=ora
   
   Behind the scenes, the ant command performs several tasks, including regenerating the .war image, loading the schema into the database, and deploying the newly built portlet.
   
   If ant fails while loading the schema and you would like to unload the schema, type:
   
   % ant -Dapp.version=ora unconfig_backend
   
   
6. Repeat steps 1 through 5 for the other portlet applications: Surveys/Polls and Wiki.

You must repeat part of the preceding procedure for any additional Portal Server instances on the system, as follows:

• Preparing the Oracle Database: None
• Preparing the Web Container for the New Database: All the steps
• Setting Up Community Membership and Configuration: Step 4 only
• Configuring and Installing Portal Applications: Step 3 only

Figure 3 illustrates the seamless integration of Portal Server's multiple-instance deployment into Oracle's RAC for high availability.

Figure 3: Configuration of High Availability

Note these troubleshooting tips:

• Use an SQL tool, such as SQuirreL SQL, to ensure that you can connect to the database and access portal schemas.
  
  
• In case of errors, raise the logging level and check the log files for clues:
  
  
  1. Edit the debug.com.sun.portal.level property in the PortalServer-DataDir/portals/portal-ID/config/PSLogConfig.properties file.
     
     
  2. Restart the Web container for the new level to take effect.
     
     
  3. Browse the log files that are located under the PortalServer-DataDir/portals/portal-ID/logs/portal-instance-name directory.

• Sun Java System Portal Server
  • Main page
  • Developer home
  • Software Forum
  • Documentation
  • The Portal Post
  
  
• Java Database Connectivity (JDBC) technology
  
  
• Java Naming and Directory Interface (JNDI)
  
  
• Oracle 10g Real Application Clusters (RAC)
  
  
• Oracle 10g Documentation Library