[platform-help-dev] Infocenter and stand-alone help architecture change

[konradk@xxxxxxxxxx]

With Eclipse 2.0, we provided the first extension of the Eclipse help as
both an info-center and stand alone help system. Installation and runtime
behavior seemed to be affected by various unknowns in the operating
environment (Java versions, web servers, XML parsers, URL Handlers, etc.)
so we decided to take a different approach in which there is a  more
predictable environment for running help and eclipse code.

Limitations of the old design:
------------------------------------------

The code in "org.eclipse.help.webapp" plug-in runs as an Eclipse plug-in in
workbench and stand-alone scenario.
In the Infocenter scenario, a copy of this plug-in is specially packaged as
a .war file that runs solely as a web application on the user's server, and
not as an Eclipse plug-in.  This limits what the web application can do and
adds a complex layer of code to manage communication with the eclipse
environment. It is also difficult to provide extension points in the help
web application.

In the infocenter scenario, the eclipse platform is launched by a servlet
and it executes within server's VM, in the environment, class loader
structure and context provided by a servlet container of a server used
(despite Eclipse being unzipped outside of the server installation tree).

In the stand alone scenario, eclipse platform is launched by a Help API
class and is executes within the same VM as the application, and it its
environment.  Since it is in the same process as the application, it cannot
run its own UI event loop.  Command line stand alone not implemented since
inter-process communication does not exists, and is required for opening
other documents without launching new instance of eclipse for each request.


Proposed redesign:
-------------------------------

1)  org.eclipse.help.webapp always executes under Eclipse and is not placed
directly on a web server

2)  In the infocenter scenario, web server runs just one dispatcher servlet
or a proxy module that delegates all the requests to a running instance of
a headless Eclipse.   Headless Eclipse with running help system and help
server is started and stopped from command line, independently from the web
server.   Help system works more like a system service or a database rather
than a huge servlet.

3)  Stand alone Help class launches headless Eclipse in a separate process.
Subsequent calls to display help, shutdown e.t.c. communicate with the same
Eclipse. process.  Stand-alone help communicates with Eclipse using already
running help server.  From the product point of view there is no change to
the API used.

4)  To start/stop eclipse on the infocenter server, administrator uses the
same mechanism as is used for the stand alone - infocenter help launcher
sends control command to the help server.  Redirect servlet running on the
web server does not forward requests to the URL used to control Eclipse.


Cons of new design:
-----------------------------

1)  Infocenter:  in addition to installing .war on a server, or configuring
a proxy module, and unzipping eclipse( as before), server administrator
will need to call eclipse help application launcher from command line (or
configure it to run at the machine start-up or run as a system service) to
start Eclipse.

2)  Infocenter:  Machine running Eclipse will have an additional port open
to which proxy servlets on the server redirects.  In the old infocenter
implementation the embedded help server was not running.

Pros of new design:
----------------------------

1)  Infocenter and stand alone: Eliminates collisions between Eclipse
classes and server or application classes and names.  Will not require
deletion of Xerces libraries that are part the web servers, or require that
stand-alone application uses certain version of libraries.
 21488 Infocenter ClassCastException in Xerces
 22353 Can't set up Infocenter with Eclipse V2

2)  Infocenter and stand alone: Allows removal of temporary hacks that will
not work in the next version of web servers, Eclipse, or JDK.  As long as
Eclipse can be run on a machine, the infocenter will be able work.

3)  Infocenter and stand alone:  We will be able to stop overusing Eclipse
URL handlers, since direct access to Eclipse classes becomes possible.  We
will be able to rely on Eclipse plug-in start-up and shutdown order.
26000 URL handlers and plug-in shutdown need be synchronized.

4)  Infocenter and stand-alone:  Will no longer need to edit server
classpaths to inject URL handlers factory, will allow more than one
infocenter running on the same server
22278 Infocenter; only one infocenter web app works on a server.

5)  Infocenter:  Allow for many to many association of web server
application with help system.  Allows upgrades, restarts of web server
independently from the Eclipse help system installation.  Implementing
Eclipse or server load balancing becomes possible.  Allows upgrades,
restarts of web server independently from the Eclipse help system.
Eliminates need to restart the whole server when misconfiguration of web
application occurs
22324 Infocenter, .lock file prevents start-up.

6)  Stand alone: Command line driven stand alone available
21455 No cmd line interface for starting stand-alone help

7)  Stand alone: F1 infopop using can be implemented.

8)  All: Eclipse extension points, other plug-in and fragments can be used
as additional web application or resources to augment help webapp in order
to customize, or extend it.

9)  Infocenter and stand-alone:  Command line parameters can be passed to
Eclipse.  This allows specifying arbitrary JDK to run Eclipse, launch one
Eclipse installation with different workspaces, enabling arbitrary
features, providing product and preferences overrides, specifying JDK
options, turning on debugging e.t.c.

10)  Infocenter.  Allows installing Eclipse on a different machine than a
web server

11)  Infocenter: Eclipse workbench can be launched, and Eclipse Update
Manager can be used.
17461 Infocenter should use the update manager

12)  All: Can use Eclipse APIs to find NL resources in the webapp.
Can use Eclipse preferences, logging and other facilities easily.

13)  Infocenter and stand-alone: Easier development, as only simple
launcher program and possibly single servlet is run outside of Eclipse.

14)  Infocenter and stand-alone:  It is now possible to easy debug the
Infocenter, as Eclipse is not running within the server container.

15)  Stand alone: Command line driven stand-alone help might be left
running after the main application exits.  Subsequent launch of the
application will use the same running help system.

16)  Stand alone: User might use command line driven stand-alone help to
display documents without explicitly calling start.  A desktop shortcut to
open a help document will cause help system to be started when necessary.


We have a working implementation of this solution (released into our
refactoring branch), but not released into the HEAD stream for inclusion in
the builds.
If anyone is concerned that the new solution can have negative impact in
their ability to use Eclipse infocenter, sees a major problem, or wants it
released asap, please comment.

Konrad Kolosowski
Eclipse Help System