uPortal Notes

* Started with vanilla install of the Quick Start version. I recommend doing this since you a) realize you have
to run the DB server separately (not well documented in the full build stuff), and b) you can see what it is
supposed to do.

* Doing vanilla install of the "uportal only" distribution of 2.3.3.

* Got Hypersonic from http://sourceforge.net/projects/hsqldb.

* Had some documentation issues. Finally settled on the instructions in the distribution's
README, but also the ones below. The README worked but had an important omission about starting the
database as a separate process. You need to run this command from the hsqldb/lib directory:
java -cp hsqldb.jar org.hsqldb.Server -database uPortal2 -port 8887

* Note you should (always) explicitly state your classpath (as in the above line) or you will regret it.

* You also must change out the version of hsqldb.jar in the uportal lib directory if using hsqldb-1.7 or later.

* For some reason, I had problems with localhost: I had to change localhost in rdbm.properties's jdbcUrl variable
to the full machine name before uPortal would build.

* The other installation documents had problems--wrong version of Tomcat, etc.
- Found lots of documentation at http://www.uportal.org/administrators/index.html, using
http://www.fair-portal.hull.ac.uk/downloads/uPortalGuide1.pdf. But it had some problems--for
the pre-JSR 168, version.
- There is also the install guide from http://www.uportal.org/administrators/install_v2.html, but it
suffers from excessive hyperlinks, didn't have a printer friendly version of the whole thing.

* Also ran into some Tomcat issues: 5.0.19 DID NOT WORK but 5.0.27 was OK. I note that 5.0.18 comes with
Quick Start, so 5.0.19 must have broken something. And in fact I now see everywhere (including the Pluto site)
that it has a well known bug.

* The portlet war files are located in lib/portlets and include the pluto testsuite and some other stuff. These
do not include the Pluto testsuite source code, so to look at this I had to get them from the pluto site using

[prompt> cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
[prompt> cvs -z3 -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co jakarta-pluto

* Useful Links: there are tons of documentation, a lot of which is on non-jasisg sites, so you should download and save
locally--the links were often broken while I was surfing. Of all the stuff, I found the following useful for
these specific things:
a) Adding tabs, portlets/channels, and content: http://mis105.mis.udel.edu/ja-sig/docs/uPortal_Documentation_Chapter_1.pdf.
Quick and dumb. Don't forget to save those changes.
b) Changing the ugly default (guest) layout and adding users: http://www.uportal.org/implementors/usermgmt.html
c) 168 Portlets in uPortal: http://www.uportal.org/implementors/portlets/workingWithPortlets.html

* Adding portlets is a bit tricky, as described in the above link. You have to get the name correct when editing uPortal's
channels. This is somewhat scruffy:
a) The first set of forms, used for naming the portal, don't matter too much and are probably for human consumption.
b) The second set of forms, "portlet definition", has to be done this way: [war_file_name].[porlet_name], where
[war_file_name] is the name of the war/webapp that contains the portlet code, and portlet_name is the value
of the value of portlet.xml's tag.
c) So for the proxy manager portlet, proxymanager-portlet.war, the name to enter into the uportal form to propertly
create this channel is "proxymanager-portlet.ProxyManagerPortlet".


* Experimenting with adding a portlet: edited the testsuite's portlet.xml file to include TestPortlet3, a clone of TestPorlet1 and 2.
- Restarted Tomcat just in case and logged in as developer/developer.
- Added a new, empty tab for this.
- Clicked the channel manager and went through the steps
- Then edited the blank tab to add the new portlet/channel (it appeared correctly on the list).
- Don't forget to save the changes.

* And it failed--skip ahead to see how to do this correctly.
I got this error:
Channel ID: 53
Message: IChannelRenderer.completeRendering() threw
Error type: Channel failed to render (code 1)
Problem type:
Error message Initialization of the portlet container failed.

* The stackTrace gave
java.lang.NullPointerException
at org.apache.pluto.invoker.impl.PortletInvokerImpl.invoke(PortletInvokerImpl.java:109)
at org.apache.pluto.invoker.impl.PortletInvokerImpl.load(PortletInvokerImpl.java:80)
at org.apache.pluto.PortletContainerImpl.portletLoad(PortletContainerImpl.java:205)
at org.jasig.portal.channels.portlet.CPortletAdapter.initPortletWindow(CPortletAdapter.java:261)
at org.jasig.portal.channels.portlet.CPortletAdapter.renderCharacters(CPortletAdapter.java:453)
at org.jasig.portal.MultithreadedCharacterChannelAdapter.renderCharacters(MultithreadedCharacterChannelAdapter.java:71)
at org.jasig.portal.ChannelRenderer$Worker.run(ChannelRenderer.java:481)
at org.jasig.portal.utils.threading.Worker.run(Worker.java:88)

* Neither logging out/in nor restarting the server helped.

* Also, I could add TestPortal2 with no problem.

* Noticed I had added two different versions of Test Portal #3. Redid everything and now get
Channel ID: 61
Message:IChannelRenderer.completeRendering() threw
Error type: Channel failed to render (code 1)
Problem type:
Error message Initialization of the portlet container failed.

* The stack trace from Pluto was essentially the same as above, despite the different uPortal error. In fact, the
same Pluto error seemed to cause several different uPortal errors.

* So, after a tip from Eric, I redeployed and that worked. I unpacked testsuite.war, edited the portlet.xml file to
add test portlet #3, recreated the war (jar -cf) and redeployed using
ant deployPortletApp -DportletApp=./lib/portlets/testsuite.war
(the usual way) from the uPortal directory. Restarted Tomcat, published the channel, then subscribed and all was well.