Dealing with Helpsets from 3rd Party JARs

Let's say you have an application on top of the NetBeans Platform. One of the application's modules does nothing more than wrap a 3rd party library. However, within that 3rd party library is a helpset that you'd like to integrate into your own application's helpset. How do you integrate that helpset, i.e., one that is within a 3rd party JAR, into your own application?

You could, of course, simply manually copy the help files from the 3rd party helpset and paste them into one of the modules in your suite that already provides a helpset. That solution presents two problems, however. Firstly, you now have the same HTML files in two places—within the 3rd party JAR as well as within the module that integrates them into the application's helpset. That's not very convenient and your application is now potentially much larger than it needs to be. Secondly, what happens when the JAR is updated? The helpset is then potentially modified and you'll need to copy them over again, again manually. Not convenient either.

So the better solution is to add an Ant script to your build process. The Ant script will, at whatever point in your build process that it is convenient to do so, unjar the 3rd pary JAR, create a scratch folder, copy the complete content of the 3rd party JAR into the scratch folder, and then copy the relevant folder (i.e., the 'help' folder) into the module that will provide the helpset. So long as the "helpsetref" tag in your helpset.xml file points to the "hs" file that is expanded into the module, everything will work seamlessly and you'll have a single source for the helpset. In other words, you'll not check any help topics into your CVS. Instead, you'll recreate the helpset on the fly, as needed, and the HTML files will always be within the JAR file:

<target name="create-marvin-help" description="Get help topics from JAR">

    <property name="help.dir" location="../modules/MarvinHelp/javahelp/com/im/ijc/marvinhelp/help"/>
    <property name="scratch.dir" location="../modules/MarvinHelp/scratch"/>

    <delete dir="${help.dir}"/>
    <mkdir dir="${help.dir}"/>

    <mkdir dir="${scratch.dir}"/>
    <unjar  src="../libraries/JChem/release/modules/ext/jchem.jar" dest="${scratch.dir}"/>
    <copy todir="${help.dir}">
        <fileset dir="${scratch.dir}/help">
            <include name="\*\*"/>
    <delete dir="${scratch.dir}"/>


The downside of this approach is that you now have no control over the helpset at all, since you're simply unjarring it on the fly. In other words, you need to take the settings and content provided by the JAR as given, there's no way for you to change them. For example, if 'expand=false' is not set in the TOC, and you don't want the top node to be expanded, there's nothing you can do since you're using the TOC from the JAR, rather than one you have control over within your module.


Better still would be to leave the original JAR completely untouched. Most easily: create a library wrapper module for the JAR, make it not be autoload, add a dep on the token org.netbeans.api.javahelp.Help, and add the one-liner XML file to the module's layer that registers the helpset. Done - no custom build.xml.

Posted by Jesse Glick on September 08, 2008 at 01:57 AM PDT #

Sure, that would be the ideal solution. But the help files are still inside the JAR. So how would they end up in the library wrapper module's helpset?

Posted by Geertjan on September 08, 2008 at 02:01 AM PDT #

Because making a lib wrapper module automatically adds the lib to the module's "classpath", meaning you can refer to the .hs file using a regular Java resource path (nbresloc URL protocol, for example).

Posted by Jesse Glick on September 08, 2008 at 02:12 AM PDT #

Thanks a lot. That works perfectly. Much (much) better solution than mine.

Posted by Geertjan on September 10, 2008 at 12:05 AM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed

Geertjan Wielenga (@geertjanw) is a Principal Product Manager in the Oracle Developer Tools group living & working in Amsterdam. He is a Java technology enthusiast, evangelist, trainer, speaker, and writer. He blogs here daily.

The focus of this blog is mostly on NetBeans (a development tool primarily for Java programmers), with an occasional reference to NetBeans, and sometimes diverging to topics relating to NetBeans. And then there are days when NetBeans is mentioned, just for a change.


« July 2016