HelpSetter

• Description
• Source Code

Description

The only small piece of Java code (so far) written specifically for the JWS based launch of JavaHelp is HelpSetter.java. This code is closely based on the HelpButton applet, since the security constraints applied to the applet and JWS launch are much the same. Except for displaying the intermediate JButton on the applet (which has been replaced by an HTML link with 'pseudo-button' styling, in these examples) they function much the same.

Note that HelpSetter also allows the JWS launched HelpSet to be used by plain applets or desktop applications, so long as they can 'display an URL'. For example:

• Applets might use the (very unreliable, nowadays) Applet.getAppletContext().showDocument(URL) method. Alternately, include a link to 'help' in the applet web page.
• 1.6+ desktop applications (or signed applets), can use Desktop.browse(URI).
• Pre 1.6 J2SE versions might use 3rd party APIs like BrowserLauncher2.
• JWS based applications can simply call BasicService.showDocument(URL). This works for any J2SE version, and for fully sandboxed apps. as well. In Java 1.6+, the Plug-In will recognise the JNLP file and hand it directly to JWS, with no intermediary browser window.

The alternative (and more common method) to using JavaHelp would be to add the JWS based components to the application classpath. This would allow much closer control of the help windows, and is the only way to achieve embedded (e.g. context sensitive) help as shown in the IDE Demo.

* To be used for embedded help, the libs of the JNLP API can be referenced directly from within the main apps. JNLP file, but the developer can also 'factor them out' into a separate JNLP if it makes sense to do so (for example if using a common subset of the JavaHelp API across many applications, it might pay to put all the references into a single component-desc that is referenced by each app. - this is what we do for the HelpSets of the IDE Demo).

On the other hand, HelpSetter is an application in its own right (and thereby requires an application-desc JNLP). It is this second application-desc JNLP (required for every app. that uses HelpSetter) that gives us the option for a separate link and desktop integration, but the downside is that it also means more JNLP files to create and maintain.

Source Code

The (HTML formatted) source code of HelpSetter.java.

/*
 * @(#)HelpSetter.java 1.0 08/01/30
 * Based on HelpButton
 *
 * Copyright (c) 2008 Sun Microsystems, Inc.  All Rights Reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistribution of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistribution in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in
 *   the documentation and/or other materials provided with the
 *   distribution.
 *
 * Neither the name of Sun Microsystems, Inc. or the names of
 * contributors may be used to endorse or promote products derived
 * from this software without specific prior written permission.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
 * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
 * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
 * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
 * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * You acknowledge that this software is not designed, licensed or
 * intended for use in the design, construction, operation or
 * maintenance of any nuclear facility.
 */

package org.physci.javahelp.helpsetter;

import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;

import javax.swing.JTextArea;
import javax.swing.JOptionPane;
import javax.swing.JFrame;
import javax.swing.SwingUtilities;
import javax.swing.UIManager;

import java.net.URL;
import java.net.MalformedURLException;

import javax.help.DefaultHelpBroker;
import javax.help.HelpSet;

/** HelpSetter is a basic HelpSet viewer launcher.  It is based
on the HelpButton applet, but opts for a 'direct launch' without
displaying the intermediate JButton.

@author Andrew Thompson
@version 2008/01/07 */
public class HelpSetter {

  /** Stores the path/name of a HelpSet that is on the
  application classpath. */
  private String helpSetName;

  /** Stores the URL to a HelpSet that is contained in
  loose files on the server, located relative to
  the codebase of the application. */
  private String helpSetURL;

  /** Stores the codebase from which to obtain loose
  HelpSets, assuming it is different from the codebase
  of the application. */
  private String helpSetCodebase;

  private HelpSet hs;
  private DefaultHelpBroker hb;

  public HelpSetter(String hsName) {
    this(hsName, null);
  }

  public HelpSetter(String hsName, String hsURL) {
    this(hsName, hsURL, null);
  }

  public HelpSetter(String hsName, String hsURL, String hsCodeBase) {
    helpSetName = hsName;
    helpSetURL = hsURL;
    helpSetCodebase = hsCodeBase;
  }

  public void initAndDisplay(){
    if (hs == null) {
      createHelpSet();
      hb = (DefaultHelpBroker)hs.createHelpBroker();

      hb.initPresentation();
      JFrame root = (JFrame)hb.
        getWindowPresentation().getHelpWindow();
      /* The frame would normally be destroyed when the application
      exits, or the applet dispose() method is called.  For our
      use, we need to add a listener directly to the help viewer */
      root.addWindowListener( new WindowAdapter() {
          public void windowClosing(WindowEvent we) {
            System.exit(0);
          }
        } );
      /* Simplistic attempt to set the PLAF. Seems to
      work, but causes exceptions. */
      if (System.getProperty("jnlp.native.plaf")!=null) {
        try {
          UIManager.setLookAndFeel(
            UIManager.getSystemLookAndFeelClassName());
          SwingUtilities.updateComponentTreeUI(root);
        } catch (Exception e) {
          System.err.println(
            "Internal Look And Feel Setting Error.");
          System.err.println(e);
        }
      }
    }

    hb.setDisplayed(true);
  }

  private void createHelpSet() {
    ClassLoader loader =
      Thread.currentThread().getContextClassLoader();
    URL url = null;
    try {
      if (helpSetName!=null) {
        url = HelpSet.findHelpSet(loader, helpSetName);
      }
      System.out.println("findHelpSet url=" + url);
      if (url == null) {
        try {
          URL codebase = new URL( helpSetCodebase );
          url = new URL(codebase, helpSetURL);
          System.out.println("codeBase url=" + url);
        } catch(MalformedURLException murle) {
          System.err.println( "Could not form URL from '" +
            helpSetCodebase + "'");
          murle.printStackTrace();
        }
      }
      hs = new HelpSet(loader, url);
    } catch (Exception ee) {
      System.err.println ("Trouble in createHelpSet");
      ee.printStackTrace();
    }
  }

  public static String getUsageString() {
    return
      "Usage:\n" +
      "java HelpSetter hsName [hsURL] [hsCodeBase]\n" +
      "\thsName The name of the helpset\n" +
      "\t[hsURL] [optional] The URL to the helpset\n" +
      "\t[hsCodeBase] [optional] hsCodebase" +
      " if different from 'default'";
  }

  /** Display a HelpSet in the viewer.
  @param args An array of 1-3 arguments, hsName [hsURL] [hsCodebase]
  */
  public static void main(final String args[]) {
    Runnable r = new Runnable() {
      public void run() {
        if (args.length<1 || args.length>3) {
          System.err.println( getUsageString() );
          JOptionPane.showMessageDialog(
            null,
            new JTextArea( getUsageString() ),
            "Usage Error!",
            JOptionPane.ERROR_MESSAGE
            );
          System.exit(-1);
        } else if (args.length==1) {
          HelpSetter hs =
            new HelpSetter(args[0]);
          hs.initAndDisplay();
        } else if (args.length==2) {
          HelpSetter hs =
            new HelpSetter(args[0], args[1]);
          hs.initAndDisplay();
        } else {
          // three args
          HelpSetter hs =
            new HelpSetter(args[0], args[1], args[2]);
          hs.initAndDisplay();
        }
      }
    };
    SwingUtilities.invokeLater(r);
  }
}