uPortal Development, Part 1
When I went to the 2005 Java Architectures Special Interest Group (JA-SIG)
winter conference I met some uPortal developers. Some
were already using the NetBeans
IDE for doing uPortal development and others
expressed interest in giving it a try. So in this series of blog entries (which I had hoped
to have posted weeks ago) I'll
show how to setup a project for uPortal in the NetBeans IDE.
1. Get the software
After installing the JDK and the NetBeans IDE, I started the IDE and then unzipped
the uPortal Quickstart file.
2. Start the HSQL database
The uPortal Quickstart includes a copy of HSQL and a populated sample database. From a command
line in the unzipped Quickstart directory, I verified that I had the JAVA_HOME environment variable set and that Ant was on my
PATH environment variable (note that Ant is included with the NetBeans IDE and
with the uPortal Quickstart). Then to start HSQL all I had to do was type:
Later in this series of blog entries, I'll show you how to do this from
within the NetBeans IDE.
3. Take a look at the sample data (optional)
The NetBeans IDE includes a database explorer which makes it easy to look at data
in any database that has a JDBC driver. Choosing Window > Runtime brings
up a display of servers, processes, databases, etc. Expand the Databases entry and then
right-click the Drivers entry under it. Select Add Driver from the context menu
and then click the Add button. Select the hsqldb.jar file from the lib subdirectory
of HSQL in order to add support for HSQL.
Clicking the OK button causes the IDE to add an entry for HSQL under Drivers.
Now that the IDE understands HSQL, to use the database explorer just right-click
the HSQL entry under Drivers and select Connect Using.... Specify
localhost:8887 and a userid of sa (leave the password blank):
Clicking OK establishes a connection and then clicking OK again
closes the dialog. There should now be an entry under Databases for the uPortal
database. Expand it and then expand its list of tables. Right-click a table
and then choose View Data. The UP_PERSON_DIR table is shown below:
4. Create a project
Select File > New Project and then under Categories select
Web and under Projects select Web Application with Existing Ant Script.
Click the Next button.
Click the Browse button next to the Location field. Specify the uPortal_rel-2-5-1
subdirectory that was created when the uPortal v2.5.1 Quickstart was unzipped. The IDE will then fill in the
rest, in particular the name of the build.xml file that it finds in that directory. The end result should look
something like this:
Click the Next button to continue.
The IDE parses the build.xml and assigns what it thinks are the appropriate targets to its built-in
menu commands. It gets most of them right - but there is one that is wrong. For the Test Project
entry the correct target is runtests. So change that entry and then click Next to continue.
The IDE correctly locates the web sources folder, so
click Next again.
For the source package folders, the IDE correctly locates the source, but not the test folder. In the
Test Package Folders section of the dialog, click the Add Folder button. Specify the tests
subdirectory. The end result should look like:
Click the Next button to continue.
To help the IDE's editor with code completion the next dialog provides a way to specify library .jar files. The
uPortal Quickstart includes all of the necessary libraries under the lib subdirectory. Note, however, that the
lib subdirectory itself contains subdirectories; it is important that all .jar files in those subdirectories get
added. This result is a fairly long list of .jar files being specified; an example of the end result is shown
Click the Next button to continue.
- There are no changes needed for the web sources classpath, so click Finish in order to create the project.
5. Build and Deploy
Right-click the uPortal entry in the IDE's Projects window and then select Build Project
The application has been built, but not deployed. There is a build.properties file that controls
where the build.xml file places the deployed application. To edit it, click on the IDE's Files tab
and then expand the uPortal entry. Double-click the build.properties entry to open it in an editor.
The uPortal Quickstart includes a copy of Tomcat, but I prefer to use the copy of Tomcat that is included
with the NetBeans IDE. That means the server.home property must be set to the base directory
for the Tomcat server that is bundled with the NetBeans IDE. That Tomcat base directory is under the IDE's
user directory. By default, on Unix-based systems the IDE's user directory is created in a /.netbeans folder
under the user's home directory. On Windows, the default location for the user directory is under
/Documents and Settings/<userid>/netbeans. I always change my user directory from the default,
however, so for this series of blog entries the user directory will always be:
For more information on the IDE's user directory, take a look at this entry in the NetBeans IDE FAQ.
An example change to the server.home property looks like this:
- Right-click the uPortal entry in the IDE's Projects window and then select Redeploy Project.
6. Start Tomcat
- In the Runtime window, right-click the entry for Tomcat and then select Start.
Expand the entries under Tomcat until you get to the list of web applications. Right-click
the entry for uPortal and select Open In Browser:
The IDE will open a browser window and set the URL for uPortal. You should get an error
message that looks like this:
7. Setting up the data sources
In the Projects window, expand the entry for uPortal and then expand its Web Pages entry and then
the WEB-INF entry that is under it. Double-click the entry for web.xml.
The IDE will open a graphical editor for web.xml. Click on the References tab and you will see
that uPortal needs a couple of data sources defined:
The Tomcat that comes with the uPortal QuickStart has these data sources configured, but
not surprisingly, the Tomcat installation included with the NetBeans IDE does not.
Adding them is not difficult, however.
In the Runtime window right-click the entry for Tomcat and then select View Admin Console.
The IDE starts a browser and sets the URL to the Admin console logon screen for Tomcat. A username
and password are required for login. The IDE created a username of "ide" with a randomly generated
password the first time that its installation of Tomcat was started. The "ide" user has administrative privileges,
so that's the username to specify. The password for the "ide" username is specified in the tomcat-users.xml
file, which is located under the IDE's user directory. For example, in
In the Tomcat Administration Tool click the Data Sources entry and then choose
Create New Data Source. The JNDI name for the first one is jdbc/PortalDb :
The JNDI name for the second one is jdbc/PersonDb. All other parameters are the same for both.
In order for the data sources to work, Tomcat will need access to the JDBC driver for HSQL.
Copy hsqldb.jar from the HSQL /lib folder to Tomcat's /common/lib folder. The /common/lib folder
is under the IDE's Tomcat installation folder. For example,
- Right-click the entry for Tomcat in the Runtime window and select Restart.
After Tomcat restarts, expand the entries under it until the uPortal application is listed.
Right-click it and select Open in Browser.
The uPortal main window displays:
uPortal is running! But there are some things that still are not quite right - additional
configuration is required. Those details will be described in
Part 2 of this series.