Eclipse Help / Infocenter – External Web Application Mode

Previously in this blog, the Eclipse Help / Infocenter was discussed and details on how to set up the help for an RCP application were given. But often you want to have your help for an application online as well as part of the product, for example if the customer does not have the latest version of the product installed. Indeed the IBM and Eclipse web sites have what they call an Infocenter – an online version of their help system. In reality, when the Eclipse Help System is running, it runs as an embedded web server within your application. So in theory, it should be possible to deploy that as a standard web application.

Quoting the Eclipse Help, “The help system can run in three modes: workbench (normal), infocenter, and standalone.” Normal is when it is part of your application. Infocenter is when it runs as a seperate process acting as a web server. Standalone is when it is used outside of an RCP application.

In fact, from Eclipse 3.4 upwards, it can also be deployed as a standard Java EE web application. The following blog shows how to deploy that help to a standard Java EE web server, namely Tomcat 5.5.

Unfortunately, at the time of writing, there is no simple way to get this running. Neither is there any good tutorial showing how to overcome the pitfalls of the descriptions provided in the Eclipse 3.4 Help (search for WAR and you will get the details). Those details are repeated here, as starting steps (I hope this does not breach copyright, but the aim of this tutorial is to give a complete guide to getting help to work as a web application):

Deploying the infocenter as a Web Archive

Using Eclipse 3.4 or later it is possible to configure the help plugins to be deployed as a web archive (war file) which will act as a fully functioning infocenter. The instructions below assume a Tomcat server has been installed, but with minor modifications these steps should work for any full featured server.

  • In your Eclipse 3.4 installation locate the plugin org.eclipse.help.webapp..jar and copy it to a temporary directory, unzip the copy into that folder.
  • In the webapp plugin locate the web-archive directory and underneath that there will be two directories titled “help” and “org.eclipse.help.infocenter-feature”.
  • Import the org.eclipse.help.infocenter-feature using File->Import->Existing Project.
    .
    . (Note A – see below)
    .
  • Export org.eclipse.help.infocenter-feature as a deployable feature and set the destination to be web-archive/help/WEB-INF/eclipse in the area where org.eclipse.help.webapp.<version>.jar was unzipped.
  • Download org.eclipse.equinox.http.servletbridge_<version>.jar and org.eclipse.equinox.servletbridge_<version>.jar from the equinox download site. Select a version of Equinox that matches the version of Eclipse you are running to take you to the downloads page.
  • Extract servletbridge.jar from org.eclipse.equinox.servletbridge_<version>.jar.
  • Add the file servletbridge.jar to the help/WEB-INF/lib directory. You may need to create this directory.
  • Add the file org.eclipse.equinox.http.servletbridge_<version>.jar to the help/WEB-INF/eclipse/plugins directory
    .
    . (Note B – see below)
    .

Note A: The documents state “Add some documentation plugins to the webapps/help/WEB-INF/eclipse/plugins directory. ” This has provided some confusion among the postings that I found on the internet. Basically there are two choices. The first is to take your plugin which contains the help folder, and put it into the folder named above. It can be put there as a deflated / flat folder (that is, unjarred), or as the standard exported plugin jar which the export wizard creates for you. The second choice is to create you help contents within a second plugin, seperate to your application, and to place that exported plugin into the above named folder. The advantage of the second approach is that you do not have to deploy all the dependencies which your plugin has, which are not related to help. I however, went for the first option, simply because it then only need to do one export and each time I export my plugin in order to create a new release / upgrade to the application, I simply take that exported plugin and pop it onto my webserver.

Note B: Once you have completed Note A and all the other steps in the citation above, you can continue with the last steps of the documentation: “At this stage you can create a war file from the help directory or you can copy the directory and its contents to the webapps folder of your Tomcat installation.

If your’e lucky, it all works and your online help looks great! If however, you are more like me, then you just get a blank help screen. OK, not too bad, the solution to this is that instead of the URL being http://yourdomain.com/help, it needs to have the index page appended: http://yourdomain.com/help/index.jsp.

In the web.xml of the help webapp, there was no welcome page descriptor. I added one, but that didn’t help! I think it is because the web app parses the requested URL and then works with a virtual file system. But why Tomcat doesn’t step in before hand if it sees no requested page, I do not understand. Anyway…

The next bit didn’t fully work for me either. The infocenter loaded nicely, but the contents was empty. It only took a few hours of fiddeling, and here is what I discovered:

The web application loads the Eclipse workbench behind the scenes. This is based upon the Eclipse Equinox implementation of OSGi, which has a neat little command line where you can find out what services are deployed in the workbench.

Within the web.xml of the help webapp, there is a servlet start parameter which is commented out. Some postings that I found online even say that it MUST be commented out. Well not in this instance. Ensure the following is not commented out in your web descriptor:

  <servlet id="iehs">
    <servlet-name>equinoxbridgeservlet</servlet-name>
    <display-name>Equinox Bridge Servlet</display-name>
    <description>Equinox Bridge Servlet</description>
    <servlet-class>
      org.eclipse.equinox.servletbridge.BridgeServlet
    </servlet-class>
    .
    .
    .
    <!-- the following parameter enables 
            the OSGi command line!!
        -->
    <init-param>
      <param-name>commandline</param-name>
      <param-value>-console</param-value>
    </init-param>
    .
    .
    .
  </servlet>

Restart Tomcat, from a command line, without starting the process in the background (that is on say linux, do not add the & command after . catalina.sh run.

Once it has started and gives you the commandline message saying Server startup in x seconds, hit return. As if by magic, an OSGi prompt appears. On this prompt you can type help (or any unrecognised command) to get help. The ss command will list installed services with their state. Doing so gives the following output (click image for a larger picture), where BookStore_1.0.0 is my plugin containing the help contents.

Click for full size
My plugin (ID 6) is installed!! Great. But actually it needs to be active before it is of any use to me. So the next command I type is start 6, which should start my plugin, since it was listed with ID 6 (click image for a larger picture).

Click for full size
In the above picture, I have highlighted the problem. My plugin is dependent upon org.eclipse.tomcat and that is a missing resource. Well you might think that it is strange that the webapp is running in Tomcat and Tomcat is missing, but it is actually the Tomcat plugin that is missing in the Eclipse workbench environment, namely under the WEB-INF/eclipse/plugins directory. Add this plugin from your Eclipse plugins directory (or indeed your RCP application export plugins directory), as well as any other plugins upon which your plugin is dependent, restart Tomcat and everything should work.

If it still does not work, try stopping Tomcat, deleting the <tomcat-install-directory>/work directory, and restarting Tomcat. Tomcat has a working directory where it caches webapps and in this case it is not very good at cleaning up the Eclipse workbench environment (either during hot deploys or during restarts).

If that still does not work, iteratively use the OSGi command line to until your plugin has a state of <<LAZY>>. This state is fine, since it will get started when you call up the URL. In fact the lazy status may never change, but it is sufficient to indicate that your plugin is now loaded and ready to run in the help system.

Before deploying this webapp to a production environment, don’t forget to comment out the OSGi command line parameter in the web.xml file.