Start developing portals with JA-SIG uPortal

Learn how to get the open source uPortal framework up and running

As our organizations grow, we often find ourselves looking for new ways of informing our employees about changes, procedures, and new policies. We want our employees and administrations to be well informed about our corporations' missions, goals, and corporate events. Furthermore, we want to present as much information to our employees as possible and not limit it to specific systems. The use of the Internet as a tool to disseminate relevant information seems to be a good start, but can our target audience sift through the hefty amounts of data on most corporate intranets?

In an educational context, we are faced with similar challenges. How do we keep the administration, faculty, staff, and students well informed about institutional policies and procedures? How do we ensure the student body receives accurate and up-to-date information to help them achieve their educational and career goals? In addition, we hope to build learning communities—communities of students, instructors, administration, faculty, and staff all collaborating and constructing strong relationships that provide the foundation for students to achieve their goals with greater success. We also want to promote information sharing so users can build on their experiences at the institution. Plus, we want to provide seamless integration with legacy and other applications.

One solution to these goals is to provide a support tool for such learning through a Web portal. This portal should provide all users with valuable information about their personal details and interests, and about the institution. However, building a portal is no small task, especially when you consider the shrinking budgets and limited resources in today's economy.

A good solution might be one of the available out-of-the-box portals. However, if customization, direction, and cost are a concern, you might want to look at uPortal by Java in Administration Special Interest Group (JA-SIG). uPortal is a free open source portal project built on Java, XML, and XSL (Extensible Stylesheet Language). Current releases include support for Web services channels, permissions, and group managers, which were absent from the initial releases. uPortal gives you the flexibility to open your favorite Java editor and implement any new features you or your institution might need. The portal is specifically focused at higher-education institutions, although some businesses and high schools use it as a framework for building collaborative communities. The framework has pluggable components known as channels that deliver focused information to the user. Users can select what channels they want to view based on their roles in the institution and customize the site's look and feel to their preferences.

uPortal is free; however, there is an investment cost incurred by the development team in learning Java, XML, XSL, and the portal framework itself. This article focuses on reducing that investment by helping you get uPortal up and running. In addition, it shows how to configure the portal with a production database and explains its basic authentication methods.

Quick start

To get the ball rolling, you must first download uPortal from the JA-SIG Website. You have a couple of downloads to choose from. You can download the portal as a quick-start distribution or as a portal-only distribution. Keep in mind that you will also need JDK 1.3 or higher.

The quick-start distribution is for those who do not have a production environment to deploy the portal. This distribution allows users to download a zip file that contains a Java database (HypersonicSQL), a servlet container (Apache Tomcat), a build tool (Apache Ant), the portal source code, and configuration files. The quick-start distribution is directed towards developers who want to get the portal up and running in relatively no time at all. Quick start gives you a basic idea of the portal's features and abilities. Since this distribution comes with everything you need, there is no delay for configuration or deployment.

To get this version working, you must extract the zip file in a directory of your choice. For the remainder of this article, I reference my installation in the root path c:\uportal_2-1\. Looking into this directory, we see the directories for Ant, HypersonicSQL, Tomcat, and the portal source code. A brief overview of each of the directories follows:

  • Ant: a Java-based build tool from the Apache organization. The Ant tool consists of Ant tasks. Tasks can be programmed to invoke the Java compiler to generate Java classfiles, modify configuration files for a particular test or production environment, invoke javadoc to create documentation, run unit tests, and much more. uPortal uses Ant to start and stop the Web container, build the portal and documentation, create the database tables, add users, and add stylesheets.
  • HypersonicSQL: an open source Java database that uPortal uses for the creation of its database tables. Though HypersonicSQL is free, most production environments utilize more proven databases like Oracle, MySQL, or Microsoft SQL Server. However, HypersonicSQL is easy to use and not a bad choice for internal portal demonstrations.
  • Tomcat: the Web container that will host all of the portal's servlets and JSP (JavaServer Pages) pages. Apache Tomcat is the reference implementation for Sun Microsystems' Web application specification. Tomcat supports the Servlet 2.3 specification and JSP 1.2.

Now let's get this site up and running. First, we need to start the database by issuing the ant command. From your command prompt, go to the directory where your portal is installed and type ant hsql. You should see the following:

C:\uPortal_2-1>ant hsql
Buildfile: build.xml
     [echo] Starting HSQL
     [java] Server 1.6 is running
     [java] Press [Ctrl]+[C] to abort

Once the database is available, you can start Tomcat and access your portal. You can start Tomcat by issuing the command ant tomcatstart:

C:\uPortal_2-1>ant tomcatstart

Now that both the database and the Web application server are running, you can view the portal at http://localhost:8080/uPortal/. By default, JA-SIG has provided the following users for you to log into the portal and view different layouts and channels:

Default portal users

Username Password

Source distribution

uPortal's second distribution is for those who have an existing J2EE (Java 2 Platform, Enterprise Edition) environment and database in production. This distribution consists of only the uPortal source code and configuration files for building the source, creating the database tables, and generating the documentation. It is recommended for those who have extensive experience with Java application servers and relational databases. This distribution requires users to configure the portal for their environments.


uPortal comes with a very small (100 KB) Java database called HypersonicSQL. This relational database management system (RDBMS) is easy to use and free. HypersonicSQL supports indexes, transactions, joins, referential integrity, Java stored procedures and functions, and user security. The database also includes a database manager that resembles a scaled-down version of Microsoft's SQL Analyzer that comes with SQL Server. However, HypersonicSQL is still in development, and it is recommended that portal solutions be deployed with a proven backend solution. Since most organizations already have databases available, uPortal makes interfacing with other databases relatively easy.

Moving to a production database

Now that you have used the portal and seen some of the features, you probably want to move the datastore to a more robust and stable RDBMS. The portal's org.jasig.portal.RDBMServices class provides database services. Initial versions of uPortal shipped with PoolMan, an open source object pool. Current versions use RDBMServices, which provides connection pooling via the driver's implementation of javax.sql.DataSource. The portal's database access can be configured from the file in the properties directory. Replace the default database properties for HypersonicSQL in Listing 1 with your database properties. You can view my properties in Listing 2. Notice the driver, URL, username, and password will vary depending on your environment. For more information on connecting to Microsoft SQL Server 2000 with Microsoft's JDBC (Java Database Connectivity) drivers, please see the sidebar "Microsoft SQL Server Setup with Microsoft JDBC Drivers."

Listing 1


My configuration resembles:

Listing 2


My configuration consists of two databases. I use one for the main portal tables and the other for the portal channels. All channels connect to the uportal_channels database, and the portal framework connects to the uportal database for layout information, permissions, and other framework-related information.

In addition to adding the properties to, since we use a third-party JDBC driver, we add the jar to the portal's lib directory and add the following to the file in the uPortal_rel-2-1-1 directory:


Replace [yourJDBCDriver].jar with your database driver. The jdbcDriver.jar is configured to use hsqldb.jar when you first receive uportal. Once you have configured the database driver to use another database, you must build the portal and deploy it to the Web container. Do that by typing the following:

c:\uportal_2-1\ uPortal_rel-2-1-1\ant deploy

If the build succeeds, you can verify the database connection with the command:

C:\uPortal_2-1-1\uPortal_rel-2-1-1>ant dbtest

Once the connection has been defined, you can create the tables by entering this command in your command prompt:

c:\uportal_2-1\uPortal_rel-2-1-1\ant db

This command will start uPortal's database loader, which will create all the tables needed to run the portal with your database. The database loader uses a few XML files in the portal's properties directory to create and populate the database:

  • data.xml: contains the data that will be inserted into the database once it is created. It contains information on all the channels, users, and layout to get the portal running.
  • dbloader.xml: contains configurations for the dbloader. It determines whether the loader should drop all tables in the database, create the new tables, and/or populate the tables with the data in data.xml. This file also contains information about mapping generic types to specific database types where the metadata is unavailable.
  • tables.xml: contains the database schema.

At this point, you should be able to view the portal as it appeared when you first started the quick-start version. However, now the portal should be connecting to your database back end and not using the HypersonicSQL that came with the portal distribution.

Built-in authentication

The uPortal database provides uPortal's basic authentication. Usernames and passwords are stored and retrieved from the UP_PERSON_DIR table. Passwords are stored as an MD5 (Message Digest 5) encryption. Although most environments probably have a user base stored in some other system like LDAP (lightweight directory access protocol) or NT ACLs (access control lists), uPortal provides a basic structure for creating portal users and permissions for those users. To create a new user in uPortal, you must use another Ant task called md5passwd. From the command prompt, type:

ant md5passwd -Dusername=brippe

You should receive a prompt asking for the password. The task will then encrypt the password and insert the user information into the UP_PERSON_DIR table. At this point, the user should be able to log into the portal. The portal uses the information in UP_PERSON_DIR to authenticate the user. My version of uPortal had a glitch in the md5passwd Ant task. The specified classpath excluded xercesImp.jar and xml-apis.jar. To correct that from the md5passwd Ant task, I replaced the classpath tags with:

   <pathelement path="${build.home}"/>
   <pathelement path="${build.home}/WEB-INF/classes"/>
   <pathelement path="${jdbcDriver.jar}"/>
   <pathelement path="${log4j.jar}"/>
   <pathelement path="${xercesImpl.jar}"/>
   <pathelement path="${xml-apis.jar}"/>

The Xerces jar contains the Xerces XML parser. The xml-apis.jar is just that, Java APIs for XML. It includes SAX (Simple API for XML), DOM (Document Object Model), and the other XML APIs included with Java 2 Platform, Standard Edition 1.4.

As a side note, once the user logs into the portal, layout information is inserted into the UP_USER table. This table stores information about which layout the user will see.

1 2 Page 1