eteration.com

Eteration is an executive consulting partner for Vignette(OpenText).  For development on Vignette Application Portal (VAP), we frequently use Eclipse WTP .  A few have asked me to share how we do it,  so I decided to setup an environment from scratch to start, stop, debug VAP and  do some basic Portlet development with WTP using VAP.

Installation

To start with we need to install VAP and WTP.  I have used the latest releases to date:  VAP 7.4.2 and WTP Galileo.   Eclipse installation is pretty straightforward, just download a copy from the eclipse.org site and unzip.  Vignette installation requires a few extra steps such as having a Database and Application server ready.  I have used Oracle Express Edition (XE), and Apache Tomcat 6.0.20 as my choices.  I use Ubuntu Linux as my daily working environment on my laptop, so I used folders under my account  (i.e. /home/ndai/vignettehome)  as the default locations for vignette and tomcat:

$ ls -al /home/ndai/vignettehome
drwxr-xr-x  9 ndai ndai    4096 2009-09-15 10:07 apache-tomcat-6.0.20
drwxr-xr-x  3 ndai ndai    4096 2009-09-15 10:08 Vignette 

Note owners of these folder. Choose a place where you can write, so that you will not need to have root access or use sudo to install or run applications. Vignette suggests other default locations (/opt) that are meaningful for a production installation but for development I prefer to own the folders.  VAP installer is a straightforward wizard. It comes as portal_7.4_unix.jar with a script to launch it: portal_7.4_unix.sh.  Run  portal_7.4_unix.sh and to start the wizard.  Follow the instructions and you should not have a problem.  One thing to watch for is the version of java that VAP needs, and it is Java 1.5.x (Java SE 5).  If you do not use a compatible version, you will get lots of weird problems.  On a linux box you can do this by:

JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun<br />
JRE_HOME=/usr/lib/jvm/java-1.5.0-sun/jre

when the installation is complete change into the /opt/apache-tomcat-6.0.20/bin folder and change the contents of the setvapenv.sh to:

JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun
JRE_HOME=/usr/lib/jvm/java-1.5.0-sun/jre
VAP_HOME=/home/ndai/vignettehome/Vignette/Portal
CATALINA_OPTS=$CATALINA_OPTS' -Xms256m -Xmx512m -Dcom.vignette.portal.installdir.path='$VAP_HOME'

If all went fine you will be able to start VAP with /opt/apache-tomcat-6.0.20/bin/startup.sh. Point your browser to http://localhost:8080/portal/console you should get the portal login page. If there are any errors, you should be able to see them in /home/ndai/vignettehome/apache-tomcat-6.0.20/logs/localhost.[some date].log file.

Setting up the Server Runtime

Now we can move into eclipse.  VAP is a standard Web Application that is packaged as a war file.  During the installation, it is deployed under the webapps folder of the tomcat application server.  Running VAP inside eclipse is simply setting up the Tomcat that we have used for Vignette installation as a server runtime, adding the portal.war as a module and changing a few startup options.  This is what we will do:

1. Add a Java Runtime Environment that is supported by Vignette Application Portal (JDK 1.5.x).
2. Add a new Server Runtime (apache tomcat 6.0.20) that was used during VAP installation.  VAP installation adds some libraries and changes settings such as catalina.properties file.
3. Add a new Server using the Server Runtime we have defined in step 2.
4. Add the portal.war as a Web module to the server.
5. Make the portal module cross-context aware.
6. Change the run configuration to add startup options that can be found in setvapenv.sh
7. Start and test the server.

Add a Java Runtime Environment

JDK version 1.5.x is the supported Java platform for VAP.  Start eclipse, choose Window > Preferences menu and open to Java Installed JREs tab.  Make sure that you have a JDK 1.5.x as your default Java runtime.  If it is not, use the Add button to define one.

Add a new Server Runtime

Use Window > Preferences menu again, and open to Server > Runtime Environment tab.  Click Add…, Choose Apache Tomcat v6, click next and set the Tomcat Installation path to /home/ndai/dev/vignettehome/apache-tomcat-6.0.20.  You must select the same Tomcat installation that was used during the Vignette installation.  This is important.  Choose the correct JRE and click Finish.

Add a new Server

This step has a few  more steps than our usual create server. We will create a server, add the portal.war as module and then modify its startup option in Run Configurations.

• Move to the JavaEE perspective and using the Servers View, use the popup menu to choose New > Server  to add a new server.  Select the Tomcat v6 as the server runtime.  You can give it a suitable name such as “Vignette Application Portal v7.4 at localhost”.  Click Finish.  This will create a server configuration but we need to complete the next few steps before we can use it .  The servers view now lists or server definition.

Add the portal.war as a Web module

• Now we will add the Vignette Application Portal web application that is defined in the portal.war to our server definition. Double click on the Server  named “Vignette Application Portal v7.4 at localhost” to open the Server editor.  At the bottom of the editor view you will see two tabs.  Click on “Modules”.  This will switch to the “Web Modules” tab.  Click on “Add External Web Module…”.  Browse to select the “[tomcat]/webapps/portal” folder under the Tomcat installation.    Use /portal as the application path.  Click OK, and use File > Save to update the server definition.

CrossContext Access: Portal must access other Web Applications

At this point VAP will start and stop without a problem. There is a tiny bit of modification we will need to make to the Web module “portal” we have added earlier. This is the portal container and it needs to interact with other Web applications such as JSR 168 portlets. By default, all Web modules run in their own sandbox, and they are not able to access other Web applications. We will need to allow the portal to access others. This bit is an application server specific setup, so we will need to change Tomcat server configuration. Portal application is defined as a context in server.xml file. In the project explorer edit the file server.xml in the “/Servers/Vignette Application Portal v7.4 at localhost-config” folder. Add an attribute to the “Context” for portal to make it crossContext=”true” as follows:

<Server/>
<!-- Lots of code deleted to make this readable -->
<Engine>
<!-- Lots of code deleted to make this readable -->
<Context crossContext="true" docBase="/home/ndai/dev/vighome/apache-tomcat-6.0.20/webapps/portal" path="/portal" reloadable="false"/>
</Engine>  </Service></Server>

Modify the Run Configuration for startup options

VAP needs to know where the Vignette installation is.  When we run VAP outside eclipse (i.e. using apache/bin/startup.sh), these options are set by the setvapenv.sh.  We will need to make sure that these java VM arguments are also set when we run VAP inside eclipse.  The process is easy.  Before changing the Run Configuration for VAP server, we need to create one.  The easiest way to create a Run Configuration is to start the Server we just created, stop it and make the modifications.  Of course, before we make these modifications the start process will not complete successfully.

• Start the Server “Vignette Application Portal v7.4 at localhost” .
• You will see some error messages on the console such as:

 ** Could not find the vignette install path. **<br />Vignette Portal relies on the java system 'com.vignette.portal.installdir.path' property.<br />i.e. -Dcom.vignette.portal.installdir.path=$PORTALSERVER_DIR<br />Please correct the startup environment and re-try.

• Stop the Server.
• Use  Run > Run Configurations… menu to open the launch configurations dialog.   Select the “Vignette Application Portal v7.4 at localhost” launch configuration.  In the Arguments Tab, add the extra configuration parameters.  Click Apply.  Of course you must change the path to match your installation.

 -Xms256m -Xmx512m -Dcom.vignette.portal.installdir.path="home/ndai/dev/vignettehome/Vignette/Portal"

Developing a Portlet

All this setup to run VAP with eclipse WTP would be wasted if we cannot do the all familiar eclipse style development. So, here comes the fun part. Developing an Ajax Portlet