Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Plug-in Developer Guide
Previous Page Home Next Page
Platform Plug-in Developer Guide Programmer's Guide User assistance support Help Configuration/setup

Infocenter

You can allow your users to access the help system over the Internet or an intranet by installing an infocenter and the documentation plug-ins on a server. Clients view help by navigating to a URL, and the help system is shown in their Web browser. The infocenter help system can be used for both client and web applications, either of which can have their help accessed remotely. All features of help system except context help, active help, command support, and the help view are supported.

The infocenter help system allows passing number of options that can be used to customize various aspects of the infocenter. The following options are supported:

  • -eclipsehome eclipseInstallPath - specifies the Eclipse installation directory. This directory is the parent of the plugins directory and Eclipse executable. The option must be provided when the current directory from which the infocenter is launched is not the same as the Eclipse installation directory.
  • -data instanceArea - specifies a path that Eclipse can use to write instance data. The value can be the absolute path of a directory or a path relative to Eclipse installation directory. The option must be provided when Eclipse is installed in a read only location, or has been customized to override the osgi.instance.area or osgi.instance.area.default properties.
  • -host helpServerHost - specifies the host name of the interface that the help server will use. This overrides the host name specified in the application server plugin preferences.
  • -port helpServerPort - specifies the port number that the help server will use. This overrides the port number specified in the application server plugin preferences.
  • -locales localeList - specifies a list of locales that the infocenter will recognize and provide customized content for. If the option is not specified, the infocenter will build navigation and index documents for each preferred locale of the browsers accessing the infocenter. When the option is present, locales from browser requests will be matched with locales in the list. If no browser preferred locale exists in the list, but its language part does, it will be used instead. Subsequently, additional browser locales in decreased order of preference will be matched against the list. If none of the browser locales (or its language part) match any locale on the list, the client will be served content in the default locale - server locale or locale passed with -nl option. For example, using options -nl en -locales de en es fr it ja ko pt_BR zh_CN zh_TW will cause infocenter to operate in 10 locales. All other locales will receive content from the en locale.
  • -dir ltr or -dir rtl - forces left-to-right or right-to-left rendering direction of the help UI in the browser for all languages. By default, the direction is determined by the browser locale.
  • -noexec - indicates that the Eclipse executable should not be used. You need to use this option when running on a platform for which the Eclipse executable is not available.
  • Additionally, most options accepted by the Eclipse executable are allowed. They are especially useful during debugging and for applying customization to Eclipse. For example, passing options -vmargs -Xmx256M increases memory available to the infocenter and will allow serving of a larger book collection.

Installation/packaging

These steps are for the help system integrator and are not meant to address all the possible scenarios. It is assumed that all your documentation is delivered as Eclipse plug-ins and, in general, you are familiar with the eclipse help system.

  1. Download the Eclipse Platform Runtime Binary driver from eclipse.org.
  2. Install (unzip) the driver in a directory, say d:\myApp. This will create an eclipse sub-directory, d:\myApp\eclipse that contains the code required for the Eclipse platform (which includes the help system).

How to start or stop infocenter from command line

The org.eclipse.help.standalone.Infocenter class has a main() method that you can use to launch the infocenter from the command line. The command line argument syntax is: 

-command start | shutdown | [-eclipsehome eclipseInstallPath] [-data instanceArea] [-host helpServerHost] [-locales localeList] [-port helpServerPort] [-dir rtl] [-noexec] [platform options] [-vmargs JavaVMarguments]

To start an infocenter on port 8081, issue a start command by running 

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Infocenter -command start -eclipsehome d:\myApp\eclipse -port 8081

To shut down the infocenter issue a shutdown command by running 

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Infocenter -command shutdown -eclipsehome d:\myApp\eclipse

Using the infocenter

Start the infocenter using the instructions above. Point a web browser to the "/help/index.jsp" starting point for the Web application running on the port specified when starting the infocenter (e.g. 8081). For example, from the machine on which the infocenter is installed, this would be https://localhost:8081/help/index.jsp.

How to start and stop an infocenter from Java

When including an infocenter as part of another application, it may be more convenient to start it and stop it using Java API calls instead of system commands. If this is the case, follow the steps:

  1. Make sure d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar is on your application's classpath. The class you use to start and shut down the infocenter is org.eclipse.help.standalone.Infocenter .
  2. Create an array of String objects containing options that you want to pass to the infocenter. Typically, the eclipsehome and port options are needed. 
    String[] options = new String[] { "-eclipsehome", "d:\\myApp\\eclipse" , "-port", "8081" };
  3. In your application, create an instance of the Help class by passing in the options. 
    Infocenter infocenter = new Help(options);
  4. To start the help system: 
    infocenter.start();
  5. To shut down the infocenter: 
    infocenter.shutdown();

Making infocenter available on the web

Eclipse contains a complete infocenter and does not require any other server software to run. However, in an unsecure environment like the Internet, it is not recommended to allow direct access by the clients, but instead made available through an HTTP server or an application server. Most servers come with modules or servlets for delegating certain request to other Web resources. For example, one may configure a proxy module of the Apache HTTP Server to redirect requests made to https://mycompany.com/myproduct/infocenter to https://internalserver:8081/help that runs an infocenter. Adding the lines 

LoadModule proxy_module modules/ApacheModuleProxy.dll
ProxyPass /myproduct/infocenter https://internalserver:8081/help
ProxyPassReverse /myproduct/infocenter https://internalserver:8081/help

to the conf/httpd.conf file of Apache server running the mycompany web site accomplishes this.

Some versions of the Apache HTTP server may contain an AddDefaultCharset directive enabled in configuration file. Remove the directive or replace it with 

AddDefaultCharset Off

to have browsers display documents using correct character set.

Running multiple instances of an infocenter

Multiple instances of an infocenter can be run on a machine from one installation. Each started instance must use its own port and must be provided with a workspace, hence the -port and -data options must be specified. The instances can serve documentation from different sets of plug-ins by providing a valid platform configuration with the -configuration option.

If -configuration is not used and the configuration directory is shared among multiple infocenter instances with overlapping sets of locales, you must be ensure that all search indexes are created by one infocenter instance before another instance is started. Indexes are saved in the configuration directory, and write access is not synchronized across infocenter instances.

Filtering

Filtering support is turned off when running in infocenter mode, causing all content, including filtered content, to be visible. If you intent to host your documentation in both workbench and infocenter modes, you should use filters in a way that makes sense even if filtering is turned off.

[Optional] Installing a minimal set of plug-ins

The infocenter does not require the entire Eclipse Platform package. It is possible to run an infocenter with the following plug-ins (located in the eclipse\plugins directory):

org.apache.lucene
org.eclipse.core.runtime
org.eclipse.help
org.eclipse.help.appserver
org.eclipse.help.base
org.eclipse.help.webapp
org.eclipse.osgi
org.eclipse.tomcat
org.eclipse.update.configurator

Some documentation plug-ins may have dependencies on other plug-ins, usually by specifying the required plug-ins in their bundle manifest. The dependent plug-ins need to be installed on the infocenter as well.

See the Product customization topic for more information on customizing the help system.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire