User Tools

Site Tools


java:infocenter

This is an old revision of the document!


InfoCenter -- Let's go for the third attempt

I always found interesting the eclipse infocenter: it's the help system of eclipse, and can be shipped independently of eclipse, as an standalone web application.

I find this very useful in order to get some documentation available and with a search engine, for a documentation of a corporate website or for instance for documenting the help of an application.

First step: install eclipse

Here are the installation instructions. In a nutshell:

  • Go to http://www.eclipse.org/downloads and locate the eclipse platform runtime library
  • To create an infocenter you will need the complete eclipse installation, because the eclipse documentation doesn't specify how to separate the help system from eclipse itself

To start the infocenter you must run an specific program that is documented here, but I think that it is somewhat cumbersome, so I decided to wrap in my own command, that I've called launcher.sh:

#
# launcher.sh
#
#!/bin/sh
 
if [ -z "$1" ] ; then
  command=start
else
  command=$1
fi
 
eclipsehome=/home/rluna/tmp/eclipse-juno
pluginshome=$eclipsehome/plugins
classpath=$pluginshome/org.eclipse.help.base_3.6.100.v201206081400.jar
classpath=$classpath:$pluginshome/org.eclipse.help.ui_3.5.200.v20120521-2344.jar
classpath=$classpath:$pluginshome/org.eclipse.help.webapp_3.6.100.v20120521-2344.jar
port=8081
 
java -classpath $classpath org.eclipse.help.standalone.Infocenter \
  -eclipsehome $eclipsehome \
  -command $command -eclipsehome $eclipsehome -port $port \
  -Dorg.eclipse.help.HELP_DATA=$eclipsehome/myHelp/helpData.xml

As you might see, you have to provide this line:

eclipsehome=/home/rluna/tmp/eclipse-juno

With the correct one of your configuration and these lines:

classpath=$pluginshome/org.eclipse.help.base_3.6.100.v201206081400.jar
classpath=$classpath:$pluginshome/org.eclipse.help.ui_3.5.200.v20120521-2344.jar
classpath=$classpath:$pluginshome/org.eclipse.help.webapp_3.6.100.v20120521-2344.jar

With the correct versions of your eclipse version.

Second step: run your own infocenter with the help documents of eclipse

Let's run our own command and see if the infocenter starts, but now with the default contents.

$ launcher.sh

As it is said here, you have to point your browser to http://localhost:8081/help/index.jsp. You should see something like this:

Third step: Adding your onw data to the existing data

The help documentation is stored in the plugin information of the eclipse. The infocenter software scans all the plugins for a file called plugin.xml and use the information stored in it to display one of the contents.

Adding our own content is easy:

3.1 Move to the plugins directory (in my case /home/rluna/tmp/eclipse-juno/plugins) and create a directory for your contents:

$ mkdir com.supermanhamuerto.doc-1.0.0

I've called this directory upon this website, but you can pick up whatever name you want.

3.2 Create a plugin.xml file with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<plugin 
   name="La tortilla de patatas, ese desconocido" 
   id="com.supermanhamuerto.doc"
   version="1.0.0" 
   provider-name="Superman Ha Muerto" >
   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" type="toc" primary="true" />
   </extension>
</plugin>

Of course, the values “name”, “id”, “version”, etc. can be configured with your own values.

3.3 create this toc.xml file referred in the previous section. I've put the following content:

<?xml version="1.0" encoding="UTF-8"?>
<toc label="La tortilla de patatas" href='toplevel.html'>
  <topic label="Section 1" href="section1.html"/>
</toc>

3.4 And finally provide this toplevel.html and section1.html elements. They are usual html pages.

My directory has the following files:

~/tmp/eclipse-juno/plugins/com.supermanhamuerto.doc_1.0.0$ ls
plugin.xml  section1.html  toc.xml  toplevel.html

AQUI ME LLEGO

InfoCenter -- Second Try and Failed

Resume of achievements

Doesn't work. I've tried to deploy in a Jboss and it fails: probably it lacks content, but something should appear on screen instead of an error, isn't??? I am starting to think that this is due to an error: possible I am missing something in the deployment or the instructions aren't so complete as they seem. Anyway, I will focus on these readings I've found in internet and if they doesn't work, I will declare this project as ended and failed.

Introduction

I run into several problems in the first attempt to create an infocenter for myself. As you may know, the “infocenter” is the eclipse help system, and I want to run my own infocenter, in other words, with my own content.

The problem in the first approximation (to empty the eclipse and installing a plugin with my help contents) is that it is not easy to delete the contents of eclipse. You can learn here from my own errors.

But alas! There is a posibility to run the infocenter as a web application. At the end, the infocenter is a web application… it would be fantastic to extract that application from eclipse and run it as an standalone application in a webserver isn't?? At the end, the security guys will be pleased for not deploy an entire eclipse into production –even if is the internal server–.

Such solution exists, and better than that, is backed up by eclipse. See this:

http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/ua_help_war.htm

I will detail here the steps I've done to achieve such a high end:

I've used the eclipse helios version in a Windows XP platform. I don't if the platform affect to the result, but just to be sure….

To the point

I've assumed that eclipse is installed in the directory ECLIPSE_HOME.

You have to identify the version of eclipse you are running. To do so, the usual eclipse → about eclipse. Take those “Build id:” numbers that appear. In may case are of the form “20100917-0705”.

Locate the resources needed

You will need to point your browser to the equinox download site: http://download.eclipse.org/equinox/. Therefore, you will have to download two files: org.eclipse.equinox.http.servletbridge_VERSION.jar and org.eclipse.equinox.servletbridge_VERSION.jar. To locate those files you will have to do the following:

  1. Locate the version of equinox sdk that more closely matches with your version of eclipse. In my case, 3.5.2, because is the only one of 2010.
  2. Download all the package “equinox-sdk-VERSION.zip”
  3. Unzip the contents and locate the jar files you need
  4. Reserve them for later use

As the document says, locate the jar file “org.eclipse.help.webapp_NUMBER_VERSION.jar” in the plugins directory ECLIPSE_HOME/plugins.

Copy it to another directory and uncompress it1).

You will find a directory web-archive. Under web-archive, a directory org.eclipse.help.infocenter-feature.

Import it as a project in eclipse. Here are the steps, no so well commented in the eclipse documentation:

  • File → Import
  • Select “import existing project into workspace”
  • In the window that appears, select “Select root directory”

A new project will appear in you eclipse, clled org.eclipse.help.infocenter-feature.

Following the instructions, I've right-clicked on the created project and check export → select “plug-in develpment → deployable features”. When it request a directory, select YOUR_DECOMPRESSED_JAR/web-archive/help/WEB-INF. Click on finish.

Now, you have to move the file org.eclipse.equinox.servletbridge_VERSION.jar to the directory web-archive\help\WEB-INF\lib. If the directory “lib” doesn't exist, you have to create.

And then, you have to move the file org.eclipse.equinox.http.servletbridge_1.0.100.v20090520-1800.jar to the web-archive\help\WEB-INF\plugins directory.

Creating a WAR file

All the contents under help constitute a WAR file. You can use it to deploy to whatever appserver you want. I've used jboss, and just did the following:

  • Copy the help file under JBOSS_HOME/server/xxx/deploy and rename the directory to help.war
  • Point my browser to http://localhost:8080/help

~~DISCUSSION~~

1)
To uncompress, just rename it from .jar → .jar.zip) and extract all the files
java/infocenter.1397585143.txt.gz · Last modified: 2022/12/02 22:02 (external edit)