Introduction

The standard installation of WebSphere^TM Studio products, such as WebSphere Studio Application Developer, does not include Java^TM SDK documentation. Although you can use the SDK documentation in Javadoc form, it's not really practical to do so, because it offers no search functionality and requires constant switching between browser and Workbench. However, since WebSphere Studio is built on top of the extendable, open-source Eclipse project, it is possible to integrate external documentation into the WebSphere Studio help system. This article contains an illustration of such integration, showing step-by-step how to prepare and install Java 2 SDK documentation.

The technique described below can be used to integrate any kind of user documentation that you might need during the development process, such as coding guidelines or architectural templates. By providing you with customized, searchable documentation, this kind of integration can help facilitate and standardize the development process. A downloadable plug-in is provided below as a sample of using Javadoc inside of WebSphere Studio. A second download file contains a utility for generating a navigation tree of help topics from Javadoc.

Back to top

Integration procedure

To integrate Javadoc SDK documentation into WebSphere Studio, follow the steps below.

1. Prepare the documentation .zip file:

Create a .zip file called doc.zip containing all the Javadoc-output HTML files (the filename doc.zip is mandatory). You can add multiple Javadoc documentation sets to one .zip file, if needed. The sample doc.zip in the download file contains Java 2 SDK documentation and has the structure shown in Figure 1 below. Separate folders are used for Java 2 SDK EE and Java 2 SDK SE documentation.

2. Create a plugin.xml file to serve as an entry point to your help plug-in:

<?xml version="1.0" encoding="UTF-8"?>
<!-- ================================================= -->
<!-- This is the plugin for declaring the help -->
<!-- contributions of a Java 2 SDK. -->
<!-- ================================================= -->
<plugin
  name = " Java2_1.3 Help "
  id = "org.java2_1.3.doc"
  version = "1.0"
  provider-name = "Help Sample">
<!-- ================================================= -->
<!-- Define help solution and its views -->
<!-- ================================================= -->
<extension point="org.eclipse.help.contributions">
  <infoset name="infoset.xml"/>
</extension>
<!-- ================================================= -->
<!-- Define and Wire in content for contents view -->
<!-- ================================================= -->
<extension point="org.eclipse.help.contributions">
  <topics name="Java2EE_topics.xml" />
  <topics name="Java2SE_topics.xml" />
  <actions name="actions_All.xml" />
</extension>
</plugin>			

3. Create an infoset.xml file containing the description of the help solution:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Defines the help web for a "solution" plugin. -->
<!-- A "solution" plugin from the perspective of the Help System 
-->
<!-- is a pluging that defines an infoset. -->
<infoset id="JDKinfoset" label="JAVA 2 Platform Documentation">
  <infoview id="view_Contents" label="Contents"/>
</infoset>

4. Create Java2EE_topics.xml and Java2SE_topics.xml files to contain the content description. Small parts of these two files are shown below -- complete versions of these files are provided in the download file.

<?xml version="1.0" encoding="UTF-8"?>
<!-- ================================================= -->
<!-- Define topics for the references -->
<!-- Topics for JAVA 2 EE documentation -->
<!-- ================================================= -->
<topics id="Java2EE_topics">
<topic id="Java2EE_root" label="Java 2 SDK, EE Documentation" 
  href="Java2EE/index.html" >
<topic label="JavaEE Documentation" 
  href="Java2EE/api/overview-summary.html">
  <topic label="javax.activation"
    href="Java2EE/api/javax/activation/package-summary.html"/>
  <topic label="javax.ejb"
    href="Java2EE/api/javax/ejb/package-summary.html"/>
  <topic label="javax.ejb.spi"
    href="Java2EE/api/javax/ejb/spi/package-summary.html"/>
  <topic label="javax.jms"
    href="Java2EE/api/javax/jms/package-summary.html"/>
</topic>
</topic>
</topics>
<?xml version="1.0" encoding="UTF-8"?>
<!-- ================================================= -->
<!-- Define topics for the references -->
<!-- Topics for JAVA 2 SE documentation -->
<!-- ================================================= -->
<topics id="Java2SE_topics">
<topic id="Java2SE_root" label=" Java 2 SDK, SE Documentation"
  href="Java2SE/index.html" >
<topic label="JavaSE Documentation" 
  href="Java2SE/api/overview-summary.html">
  <topic label="java.io"
    href="Java2SE/api/java/io/package-summary.html"/>
  <topic label="java.lang"
    href="Java2SE/api/java/lang/package-summary.html"/>
  <topic label="java.lang.ref"
    href="Java2SE/api/java/lang/ref/package-summary.html"/>
  <topic label="java.lang.reflect"
    href="Java2SE/api/java/lang/reflect/package-summary.html"/>
</topic>
</topic>
</topics>
			

5. Create an actions_All.xml file to connect help content to the top-level topics:

<?xml version="1.0" encoding="UTF-8"?>
<!-- ======================================================= -->
<!-- Add topics to the top level topics of the contents view -->
<!-- ======================================================= -->
<actions infoview="org.java2_1.3.doc.view_Contents">
  <insert
    from="org.java2_1.3.doc.Java2EE_root"
    to="org.java2_1.3.doc.view_Contents"
    as="child"/>
  <insert
    from="org.java2_1.3.doc.Java2SE_root"
    to="org.java2_1.3.doc.view_Contents"
    as="child"/>
</actions>

6. Place everything in the folder WS_InstallDir/plugins/org.java2_1.3.doc . The folder should contain these files:

doc.zip
plugin.xml
infoset.xml
java2EE_doc.xml
java2SE_doc.xml
actions_All.xml

At this point, you should be able to test your work by starting or restarting WebSphere Studio and looking at the Help Perspective. You should see your work by selecting the Java 2 Platform Documentation infoset in the Help Perspective (see Figure 4 below).

Because WebSphere Studio caches the current help configuration and does not always check for new versions of help, you may need to delete this cache before starting WebSphere Studio. To make sure your help changes will be activated, always delete the WS_InstallDir/workspace/.metadata/.plugins/org.eclipse.help.ui directory after making changes to the help configuration or help navigation files (see Figure 2 below).

Back to top

Including class description files

The WebSphere Studio search engine indexes only those topics that appear in the navigation tree of the current infoset. The navigation tree we built above contains only the package description files, and therefore the class description files will not be searched. You can add them to the search index by adding them to the navigation tree.

Modify the Java2EE_topics.xml and Java2SE_topics.xml files to add the class description files in the tree. For example, the following code shows the classes in the javax.servlet.http package node:

<topic label="javax.servlet.http" 
  href="Java2EE/api/javax/servlet/http/package-summary.html">
<!-- these entries allow search capabilities in classes descriptions -->
  <topic label="Cookie" 
    href="Java2EE/api/javax/servlet/http/Cookie.html"/>
  <topic label="HttpServlet" 
    href="Java2EE/api/javax/servlet/http/HttpServlet.html"/>
  <topic label="HttpServletRequestWrapper" 
    href="Java2EE/api/javax/servlet/http/HttpServletRequestWrapper.html"/>
  <topic label="HttpServletResponseWrapper" 
    href="Java2EE/api/javax/servlet/http/HttpServletResponseWrapper.html"/>
  <topic label="HttpSessionBindingEvent" 
    href="Java2EE/api/javax/servlet/http/HttpSessionBindingEvent.html"/>
  <topic label="HttpSessionEvent" 
    href="Java2EE/api/javax/servlet/http/HttpSessionEvent.html"/>
  <topic label="HttpUtils" 
    href="Java2EE/api/javax/servlet/http/HttpUtils.html"/>
</topic>
			

The class description files are now added to the navigation tree, and Search will search them.

Back to top

Generating a content description

The second download file below contains the GetTopics utility. You can use this program to generate a navigation tree from the doc.zip file. In our sample, this utility produces Java2EE_topics.xml and Java2SE_topics.xml . You can use this utility to work with any documentation produced by the Javadoc documentation tool. The utility will produce complete navigation trees, including packages and classes.

Back to top

Installing and verifying the Java documentation plug-in

To install the provided plug-in, follow these steps:

1. Download javaDocPlugIn.zip below .
2. Extract this file into the WS_InstallDir/plugins folder.
3. Verify that a new WS_InstallDir/plugins/org.java2_1.3.doc folder has been created.
4. Restart WebSphere Studio.
5. Go to the Help Perspective.
6. You should be able to select the Java 2 Platform Documentation information set from the drop-down list in the top left corner (see Figure 4 below).

Back to top

Related information

You can learn more about help in WebSphere Studio looking at the sample that is provided but not activated: WS_InstallDir/plugins/org.eclipse.help.examples.ex1 .

For descriptions of help plug-ins, see WS_InstallDir /plugins/org.eclipse.help/doc.

Also, read the article Help - Part 1: Contributing a Little Help from eclipse.org.

Back to top

Downloads

Name	Size	Download method
javaDocPlugIn.zip	24 MB	FTP|HTTP
GetTopics.zip	3 MB	FTP|HTTP

Information about download methods

About the authors

Neven Burazor is a IT-Architect at the IBM Business Innovation Services in Vienna. He holds BCS degree in Computer Science on Electro technical Faculty of Zagreb, with a focus on operating Systems and Networking. Prior to joining IBM in 1996 he worked on many customer banking applications using structural programming languages on a different systems like OS/390, DOS and OS/2 platforms. From 1999 he changed to web development area, and at present, he is performing technical project management role in customer projects, skill transfer, architecture's advises, development, troubleshooting, and performance tuning services to IBM customers. Neven can be reached at nburazor@at.ibm.com.

Michail Matjuchin is a software developer at the IBM Business Innovation Services in Vienna. He holds M.D. in Computer and Information Science, with a focus on optimization theory. Previously, prior to joining IBM in 1996 he has worked on different customer applications using C++ on Windows platforms. At present, his areas of expertise include design and development of applications using J2EE technologies. He provides skill transfer, architecture€™s advises, development, troubleshooting, and performance tuning services to IBM customers. Michail can be reached at michail_matjuchin@at.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Integration procedure
• Including class description files
• Generating a content description
• Installing and verifying the Java documentation plug-in
• Related information
• Downloads
• About the authors
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers