Deploy War Portlet Help

Contents

Deploying portlets
Redeploying portlets
Undeploying portlets
Troubleshooting

Deploying portlets

The Deploy War Portlet is used to deploy new portlet applications to Pluto packaged in a war file. Deployment involves unzippling the war file into Pluto's webapps directory and adding records to the registry files located in /webapps/pluto/WEB-INF/data ( portletentityregistry.xml, pageregistry.xml and portletcontexts.txt). Use the following steps to deploy a custom portlet:

  1. Build a valid war file containing the portlet application to be deployed including a portlet.xml and web.xml file in the WEB-INF directory. DO NOT modify web.xml to include a reference to the PortletServlet. The deployer will add servlet and servlet-mapping elements related to PortletServlet.
  2. Select the war file using the Browse button in the Deploy War portlet.
  3. Click submit. The war will be deployed to Pluto's webapps directory and a record added to portletentityregistry.xml and portletcontexts.txt in webapp/pluto/WEB-INF/data.
  4. Fill in the portlet's title, which will be used as a navigation link in the portal, and the number of rows and columns needed to display all portlets in the application. If the portlet app only contains one portlet, then keep the default one row, one column. The description field on that page is optional. JavaScript validation is done on this page to make sure that the layout (rows and columns) can accomodate the number of portlets in the portlet application that is being deployed.
  5. Click submit. The Define Page Layout page should be displayed next.
  6. In each row/column cell, select the portlet that will be displayed there.
  7. Click Submit. The pageregistry.xml file should be updated and the first page of the Deploy War portlet displayed. You will also notice new records in the Portlet Entity Registry and Page Registry portlets.
  8. Click on the "Hot deploy 'myportlet' portlet application" link to hot deploy the portlet. The new portlet and navigation link will then appear.

Redeploying portlets

Redeployment of previously deployed portlets can be done, but the results can be somewhat flaky due to caching of portlet content by the Pluto portal. To redeploy select the war file with its new contents using the Browse button and click Submit. The new war file will be uploaded, but no changes will be made to the porletentityregistry.xml or portletcontexts.txt. You should skip the following two pages that set page layout because they cannot be changed at this time.

Click the 'Deploy War home' link to return to the Deploy War start page. On that page click on the 'Hot deploy . . .' link on the bottom of the portlet to be redirected to the redeployed portlet application. If the portlet is not refreshed, try clearing your browser cache and/or restarting Pluto. Pluto's portal, which uses Tomcat, also contains a cache of the portlet contents within its 'work' directory. This can be deleted after the portal is shutdown to clear the old content.

Undeploying portlets

The admin portlet app does not currently support undeployment of portlets. To undeploy a portlet, manually remove the record for the portlet from portletentityregistry.xml, pageregistry.xml and portletcontexts.txt in the webapps/pluto/WEB-INF/data directory and restart Pluto.

Troubleshooting

The date-stamped pluto.log file in the logs directory is the source of any error information when things go wrong in Pluto. That is the first thing you should check out if you have a problem. Other log files in that directory might also be helpful. It's a good idea to look at the timestamp of the log files and check them in reverse chronological order.

The main problem with deployments using the Deploy War Portlet has to do with an improperly formatted portlet.xml file. The deployment process validates portlet.xml against the official XML schema. This schema validation checks portlet.xml for the required XML elements and the order of those elements specified by the schema. See PLT.21.5 in the JSR-168 specification for details on the XML schema for portlet.xml.

In order for the XML Schema validation to occur correctly, the portlet.xml file must have a root element (web-app) with all the proper attributes. The following is an example of a correct web-app element:
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"/>

If hot deployment of a portlet causes the new portlet to not appear in the Pluto portal, check the pluto log file and the portlet's web.xml in webapps/<myportlet>/WEB-INF to make sure that the PortletServlet record has been properly added to the file and it has not been corrupted. Manually undeploy the portlet and restart Pluto when you fix the problems.

If deployment of a new portlet causes an error that breaks Pluto, manually undeploy the portlet and restart Pluto. Make sure that your web.xml and portlet.xml file is correct and retry the deployment after you fix any problems.