<< Eclipse Help / Infocenter - Workbench Mode | Home | OSGi - Just another fad? >>

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.

 

Tags : ,
Social Bookmarks :  Add this post to Slashdot    Add this post to Digg    Add this post to Reddit    Add this post to Delicious    Add this post to Stumble it    Add this post to Google    Add this post to Technorati    Add this post to Bloglines    Add this post to Facebook    Add this post to Furl    Add this post to Windows Live    Add this post to Yahoo!


Re: Eclipse Help / Infocenter - External Web Application Mode

It would be useful if you could show your functioning war expanded to see how it lays out.  They way the post references some of the directories is a little confusing.

Re: Eclipse Help / Infocenter - External Web Application Mode

Hi,
Your tutorial is realy good but, though my help plugin reach the lazy status, the servlet doesn't work :I 've always got a tomcat 404 error message. So close to the end, that's totally frustrating...
Could you link your .war file on your page for me to understand where I'm going wrong ?

Re: Eclipse Help / Infocenter - External Web Application Mode

Mr. Ant,
Thanks for this info on getting a WAR up and running in the 3.4 Infocenter -- helpful!. I'm hoping you can field a question relating to Infocenter search functionality. Do you know of a way for Infocenter to search on metadata --tag attribute values-- within the HTML (in addition to the full-text search via search scope)?

Thanks in advance,
Sean Healy

Re: Eclipse Help / Infocenter - External Web Application Mode

Thank you for an excellent tutorial, which allowed me to get the Infocenter WAR up and running under Tomcat 5.5.

Our product, ActiveVOS (www.activevos.com),  also supports JBoss, Websphere, and WebLogic.

I'm running into JBoss problems, getting the 404 error. The osgi command doesn't seem to work.  Any suggestions for debugging?

Re: Eclipse Help / Infocenter - External Web Application Mode

Hi,

Your tutorial is realy good.

I wanna ask aquestion: how can I view help system contents in fixed order. _in general they appears sorted by name_

thanks in advance

N

old plugins can stick around in the 'work' directory

Thanks SO much for this blog, could not have done this without it!  My problem at the end turned out to be plugins hanging around in the 'work' directory of catalina, that is --

<catalina-install-directory>/work/Catalina/hostname

under here are the webapps.  So my webapp was named help -- I just blew away that directory, restart catalina, and suddenly my fresh and clean plugins were all happily working!

Re: Eclipse Help / Infocenter - External Web Application Mode

Very Good, it's work. Congratulations! But my documents (pages) are pt-br html. I would like translate the labels, but I stay gleeful if the serch engine found character. (sorry I don't speak english)

Re: Eclipse Help / Infocenter - External Web Application Mode

thanks a lot.. the OSGI command line was very helpful..

Re: Eclipse Help / Infocenter - External Web Application Mode

great tutorial. Thanks! Can you comment on scalability on the infocenter and standalone methods?

Re: Eclipse Help / Infocenter - External Web Application Mode

This article was very helpful in getting my Infocenter web archive up and running. But, I had fits getting the customization to work. I already had set up a standard Infocenter with customizations (overrides for home_page.html, banner.jpg, etc.) and all customization worked as expected. I successfully created a web archive folder and deployed it the Tomcat 5.5.25. The archive contained my product plugin, with the appropriate customization files. The URL http://localhost:8080/warfileName/index.jsp revealed the infocenter UI as expected — but with no customization. I tried every permutation I could think of for the eclipse.product= value in the config.ini file. Heh. It turns out that the config.ini file in your web archive (e.g. warFilename\WEB-INF\configuration\config.ini) is, apparently, completely ignored. The config.ini file you want to work with (in Tomcat, anyway) is: installDIR\work\Catalina\localhost\warFileName\eclipse\configuration\config.ini After I finally figured out which config.ini file to use, I set eclipse.product=pluginName.helpProduct. Everything fell into place then. I was finally tipped off by examining the .log file in installDIR\\work\Catalina\localhost\warFileName\eclipse\workspace\.metadata\.log It was reporting “Product org.eclipse.productname could not be found.”, indicating that the default value in some other config.ini file was being used. This second location is referred to in the note at the end of the Eclipse Help instructions, but if you don’t read carefully (like me) you’ll end up editing the wrong file.

Add a comment Send a TrackBack