Skip to main content

uPortal Development, Part 1

Posted by gsporar on February 27, 2006 at 8:56 PM PST

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:

ant hsql

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.

addDb.png

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):

newDbConnection.png

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:

upPersonDir.png

4. Create a project

  1. Select File > New Project and then under Categories select
    Web and under Projects select Web Application with Existing Ant Script.
    Click the Next button.
  2. 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:

    projectName.png

    Click the Next button to continue.

  3. 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.
  4. 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:

    projectSources.png

    Click the Next button to continue.

  5. 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
    below.

    projectLibs.png

    Click the Next button to continue.

  6. There are no changes needed for the web sources classpath, so click Finish in order to create the project.

5. Build and Deploy

  1. Right-click the uPortal entry in the IDE's Projects window and then select Build Project

    buildProject.png

  2. 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:
    F:\tools\windows\dev\netbeans\5.0\ga\userdir
    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:

    tomcatBase.png

  3. Right-click the uPortal entry in the IDE's Projects window and then select Redeploy Project.

6. Start Tomcat

  1. In the Runtime window, right-click the entry for Tomcat and then select Start.
  2. 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:

    openInBrowser.png

    The IDE will open a browser window and set the URL for uPortal. You should get an error
    message that looks like this:

    uPortalError.png

7. Setting up the data sources

  1. 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.
  2. 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:

    webXml.png

    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.

  3. 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
    F:\tools\windows\dev\netbeans\5.0\ga\userdir\jakarta-tomcat-5.5.9_base\conf\tomcat-users.xml
    .
  4. 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 :

    datasource1.png

    The JNDI name for the second one is jdbc/PersonDb. All other parameters are the same for both.

  5. 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,
    F:\tools\windows\dev\netbeans\5.0\ga\enterprise2\jakarta-tomcat-5.5.9\common\lib.
  6. Right-click the entry for Tomcat in the Runtime window and select Restart.
  7. 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:

    initUPortal.png

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.