javax.help.HelpSet Java Examples

private void loadHelpSets() {

		externalHelpSets = new ArrayList<>();
		for (HelpModuleLocation location : helpLocations) {
			if (location.isHelpInputSource()) {
				continue; // help sets only exist in pre-built help 
			}

			HelpSet helpSet = location.getHelpSet();
			externalHelpSets.add(helpSet);
		}

		if (externalHelpSets.isEmpty()) {
			return;
		}
	}
 

@Override
public Map<String, TOCItemExternal> getTOCItemExternalsByDisplayMapping() {
	Map<String, TOCItemExternal> map = new HashMap<>();

	if (externalHelpSets.isEmpty()) {
		return map;
	}

	for (HelpSet helpSet : externalHelpSets) {
		TOCView view = (TOCView) helpSet.getNavigatorView("TOC");
		DefaultMutableTreeNode node = view.getDataAsTree();
		URL url = helpSet.getHelpSetURL();
		try {
			URL dataURL = new URL(url, (String) view.getParameters().get("data"));
			Path path = Paths.get(dataURL.toURI());
			addPrebuiltItem(node, path, map);
		}
		catch (MalformedURLException | URISyntaxException e) {
			throw new RuntimeException("Internal error", e);
		}
	}
	return map;
}
 

@Nullable
private static HelpSet createHelpSet() {
  String urlToHelp = ApplicationInfo.getInstance().getHelpURL() + "/" + HELP_HS;
  HelpSet mainHelpSet = loadHelpSet(urlToHelp);
  if (mainHelpSet == null) return null;

  // merge plugins help sets
  PluginDescriptor[] pluginDescriptors = PluginManagerCore.getPlugins();
  for (PluginDescriptor pluginDescriptor : pluginDescriptors) {
    Collection<HelpSetPath> sets = pluginDescriptor.getHelpSets();
    for (HelpSetPath hsPath : sets) {
      String url = "jar:file:///" + pluginDescriptor.getPath().getAbsolutePath() + "/help/" + hsPath.getFile() + "!";
      if (!hsPath.getPath().startsWith("/")) {
        url += "/";
      }
      url += hsPath.getPath();
      HelpSet pluginHelpSet = loadHelpSet(url);
      if (pluginHelpSet != null) {
        mainHelpSet.add(pluginHelpSet);
      }
    }
  }

  return mainHelpSet;
}
 

/**
 * PATCHED VERSION OF SUPER CONSTRUCTOR
 */
public IdeaJHelp(HelpSet hs) {
  super(new DefaultHelpModel(hs));

  navigators = new Vector();
  navDisplayed = true;

  // HERE -- need to do something about doc title changes....

  this.contentViewer = new IdeaJHelpContentViewer(helpModel);

  setModel(helpModel);
  if (helpModel != null) {
    setupNavigators();
  }

  updateUI();
}
 

/** Get all available help sets.
 * Pay attention to {@link #helpSetsChanged} to see
 * when this set will change.
 * @return a collection of HelpSet
 */    
protected final Collection<? extends HelpSet> getHelpSets() {
    if (helpsets == null) {
        Installer.log.fine("searching for instances of HelpSet...");
        helpsets = Lookup.getDefault().lookupResult(HelpSet.class);
        helpsets.addLookupListener(new LookupListener() {
            public void resultChanged(LookupEvent ev) {
                helpSetsChanged();
            }
        });
        fireChangeEvent(); // since someone may be listening to whether they are ready
    }
    Collection<? extends HelpSet> c = helpsets.allInstances();
    if (Installer.log.isLoggable(Level.FINE)) {
        List<String> l = new ArrayList<String>(Math.min(1, c.size()));
        for (HelpSet hs: c) {
            l.add(hs.getTitle());
        }
        Installer.log.fine("listing helpsets: " + l);
    }
    return c;
}
 

private JHelp createAndDisplayJHelp( HelpSet hs ) {
    JHelp jh = createJHelp(hs);
    if (jh == null) {
        return null;
    }

    if (isModalExcludedSupported()) {
        displayHelpInFrame(jh);
    } else {
        if (currentModalDialog() == null) {
            Installer.log.fine("showing as non-dialog");
            displayHelpInFrame(jh);
        } else {
            Installer.log.fine("showing as dialog");
            displayHelpInDialog(jh);
        }
    }
    return jh;
}
 

/**
 * 
 * @return SearchEngine for QuickSearch
 */
synchronized SearchEngine createSearchEngine() {
    //this is not very nice but i didn't any better way to create search engine
    MergingSearchEngine result = null;
    Collection<? extends HelpSet> sets = getHelpSets();
    for (HelpSet hs: sets) {
        if (shouldMerge(hs)) {
            NavigatorView nv = findNavigatorView(hs);
            if( null == nv )
                continue;
            if( null == result ) {
                result = new MergingSearchEngine( nv );
            } else {
                result.merge( nv );
            }
        }
    }
    return result;
}
 

/**
 * @param hs
 * @return 'Search' NavigatorView from the given HelpSet
 */
private static NavigatorView findNavigatorView( HelpSet hs ) {
    for( NavigatorView nv : hs.getNavigatorViews() ) {
        if( null != nv.getParameters() && nv.getParameters().get("engine") != null) { //NOI18N
            return nv;
        }
    }
    return null;
}
 

@Nullable
private static HelpSet loadHelpSet(final String url) {
  try {
    return new HelpSet(null, new URL(url));
  }
  catch (Exception e) {
    LOG.info("Failed to load help set from '" + url + "'", e);
    return null;
  }
}
 

@Test
public void testMergeCustomHelpset() {
    HelpSet hs = new HelpSet();
    HelpUtils.mergeCustomHelpset(hs);
    assertEquals(true, hs.getKeyData(HelpConstants.HELPSET_MERGE_CONTEXT,
            HelpConstants.HELPSET_MERGE_ATTR));
}
 

/** Create & return a JHelp with the supplied help set.
 * In the case of the master help, will show the home page for
 * the distinguished help set if there is exactly one such,
 * or in the case of exactly one home page, will show that.
 * Caches the result and the result may be a reused JHelp.
 * @return the new JHelp
 * @param hs the help set to show
 */
private JHelp createJHelp(HelpSet hs) {
    if (hs == null) throw new NullPointerException();
    JHelp jh;
    synchronized (availableJHelps) {
        Reference<JHelp> r = availableJHelps.get(hs);
        if (r != null) {
            jh = r.get();
            if (jh != null) {
                return jh;
            }
        }
    }
    String title = null; // for debugging purposes
    try {
        title = hs.getTitle();
        assert SwingUtilities.isEventDispatchThread() :
            "Please, re-open Bug #168973"; // NOI18N
        jh = new JHelp(hs);
        adjust(jh);
    } catch (RuntimeException e) {
        Installer.log.log(Level.WARNING, "While trying to display: " + title, e); // NOI18N
        return null;
    }
    synchronized (availableJHelps) {
        availableJHelps.put(hs, new SoftReference<JHelp>(jh));
    }
    try {
        javax.help.Map.ID home = hs.getHomeID();
        if (home != null) {
            jh.setCurrentID(home);
        }
    } catch (Exception e) {
        Installer.log.log(Level.WARNING, null, e);
    }
    return jh;
}
 

public Boolean isValidID(String id, boolean force) {
    if (force || helpSetsReady()) {
        Iterator it = getHelpSets().iterator();
        if (MASTER_ID.equals(id)) {
            if (it.hasNext()) {
                Installer.log.fine("master id, and >=1 help set");
                return Boolean.TRUE;
            } else {
                Installer.log.fine("master id, and 0 help sets");
                return Boolean.FALSE;
            }
        } else {
            // Regular ID.
            while (it.hasNext()) {
                HelpSet hs = (HelpSet)it.next();
                if (hs.getCombinedMap().isValidID(id, hs)) {
                    Installer.log.fine("found normal valid id " + id + " in " + hs.getTitle());
                    return Boolean.TRUE;
                }
            }
            Installer.log.log(force ? Level.INFO : Level.FINE,
                    "did not find id {0}", id);                     //NOI18N
            return Boolean.FALSE;
        }
    } else {
        Installer.log.fine("not checking " + id + " specifically");
        return null;
    }
}
 

/** Find the proper help set for an ID.
* @param id the ID to look up (may be null)
* @return the proper help set (master if not otherwise found)
*/
private HelpSet findHelpSetForID(String id) {
    if (id != null) {
        Iterator it = getHelpSets().iterator();
        while (it.hasNext()) {
            HelpSet hs = (HelpSet)it.next();
            if (hs.getCombinedMap().isValidID(id, hs))
                return hs;
        }
        warnBadID(id);
    }
    return getMaster();
}
 

@Override
public void processMapRef(HelpSet hs, @SuppressWarnings("rawtypes") Hashtable attrs) {
    try {
        URL map = new URL(hs.getHelpSetURL(), (String)attrs.get("location"));
        SAXParserFactory factory = SAXParserFactory.newInstance();
        factory.setValidating(false);
        factory.setNamespaceAware(false);
        SAXParser parser = factory.newSAXParser();
        parser.parse(new InputSource(map.toExternalForm()), new Handler(map.getFile()));
    } catch (Exception e) {
        e.printStackTrace();
    }
}
 

@Override
public TreeItem createItem(String str, @SuppressWarnings("rawtypes") Hashtable hashtable, HelpSet helpSet, Locale locale) {
    String target = (String)hashtable.get("target");
    if (target != null) {
        if (! map.isValidID(target, hs)) {
            log(navfile + ": invalid map ID: " + target, Project.MSG_WARN);
        } else {
            log("OK map ID: " + target, Project.MSG_VERBOSE);
        }
    }
    return createItem();
}
 

private static URL findMasterHelpSetUrl() {

		GHelpClassLoader helpClassLoader = new GHelpClassLoader(null);
		URL url = HelpSet.findHelpSet(helpClassLoader, MASTER_HELP_SET_HS);
		if (url != null) {
			return url;
		}

		Msg.error(GhidraHelpService.class,
			"Failed to locate the primary Help Set.  Try building help to resolve the issue");
		return ResourceManager.getResource("help/" + HelpService.DUMMY_HELP_SET_NAME);
	}
 

@Override
public HelpSet loadHelpSet() {

	// Our convention is to name the help set after the module
	File jarFile = getJarFile();
	String moduleName = getModuleName(jarFile);
	Path hsPath = helpDir.resolve(moduleName + "_HelpSet.hs");
	try {
		return new GHelpSet(null, hsPath.toUri().toURL());
	}
	catch (MalformedURLException | HelpSetException e) {
		throw new AssertException(
			"Pre-built help jar file is missing it's help set: " + helpDir, e);
	}
}
 

@Override
public HelpSet loadHelpSet() {
	// help sets are generated from a directory module structure, thus one does not exist here
	return null;
}
 

@Override
public void processPI(HelpSet helpSet, String str, String str2) {
}
 

public VerifyTIFactory(HelpSet hs, javax.help.Map map, File navfile, boolean toc) {
    this.hs = hs;
    this.map = map;
    this.navfile = navfile;
    this.toc = toc;
}
 

private void checkHelpSet(File hsfile) throws Exception {
    log("Checking helpset: " + hsfile);
    HelpSet hs = new HelpSet(null, hsfile.toURI().toURL());
    javax.help.Map map = hs.getCombinedMap();
    log("Parsed helpset, checking map IDs in TOC/Index navigators...");
    NavigatorView[] navs = hs.getNavigatorViews();
    for (int i = 0; i < navs.length; i++) {
        String name = navs[i].getName();
        File navfile = new File(hsfile.getParentFile(), (String)navs[i].getParameters().get("data"));
        if (! navfile.exists()) throw new BuildException("Navigator " + name + " not found", new Location(navfile.getAbsolutePath()));
        if (navs[i] instanceof IndexView) {
            log("Checking index navigator " + name, Project.MSG_VERBOSE);
            IndexView.parse(navfile.toURI().toURL(), hs, Locale.getDefault(), new VerifyTIFactory(hs, map, navfile, false));
        } else if (navs[i] instanceof TOCView) {
            log("Checking TOC navigator " + name, Project.MSG_VERBOSE);
            TOCView.parse(navfile.toURI().toURL(), hs, Locale.getDefault(), new VerifyTIFactory(hs, map, navfile, true));
        } else {
            log("Skipping non-TOC/Index view: " + name, Project.MSG_VERBOSE);
        }
    }
    log("Checking for duplicate map IDs...");
    HelpSet.parse(hsfile.toURI().toURL(), null, new VerifyHSFactory());
    log("Checking links from help map and between HTML files...");
    @SuppressWarnings("unchecked")
    Enumeration<javax.help.Map.ID> e = map.getAllIDs();
    Set<URI> okurls = new HashSet<>(1000);
    Set<URI> badurls = new HashSet<>(1000);
    Set<URI> cleanurls = new HashSet<>(1000);
    while (e.hasMoreElements()) {
        javax.help.Map.ID id = e.nextElement();
        URL u = map.getURLFromID(id);
        if (u == null) {
            throw new BuildException("Bogus map ID: " + id.id, new Location(hsfile.getAbsolutePath()));
        }
        log("Checking ID " + id.id, Project.MSG_VERBOSE);
        List<String> errors = new ArrayList<>();
        CheckLinks.scan(this, null, null, id.id, "", 
        u.toURI(), okurls, badurls, cleanurls, false, false, false, 2, 
        Collections.<Mapper>emptyList(), errors);
        for (String error : errors) {
            log(error, Project.MSG_WARN);
        }
    }
}
 

@Override
public HelpSet loadHelpSet() {
	return null;
}
 

private void initialize_help(java.util.Locale p_locale)
{
    // try to find the helpset and create a HelpBroker object
    if (BoardFrame.help_broker == null)
    {
        String language = p_locale.getLanguage();
        String helpset_name;
        if (language.equalsIgnoreCase("de"))
        {
            helpset_name = "helpset/de/Help.hs";
        }
        else
        {
            helpset_name = "helpset/en/Help.hs";
        }
        try
        {
            URL hsURL = HelpSet.findHelpSet(this.getClass().getClassLoader(), helpset_name);
            if (hsURL == null)
            {
                System.out.println("HelpSet " + helpset_name + " not found.");
            }
            else
            {
                BoardFrame.help_set = new HelpSet(null, hsURL);
            }
        }
        catch (HelpSetException ee)
        {
            System.out.println("HelpSet " + helpset_name + " could not be opened.");
            System.out.println(ee.getMessage());
        }
        if (BoardFrame.help_set != null)
        {
            BoardFrame.help_broker = BoardFrame.help_set.createHelpBroker();
        }
        if (BoardFrame.help_broker != null)
        {
            // CSH.DisplayHelpFromSource is a convenience class to display the helpset
            contents_help = new CSH.DisplayHelpFromSource(BoardFrame.help_broker);
            direct_help = new CSH.DisplayHelpAfterTracking(BoardFrame.help_broker);
        }
    }
}
 

private void initialize_help(java.util.Locale p_locale)
{
    // try to find the helpset and create a HelpBroker object
    if (BoardFrame.help_broker == null)
    {
        String language = p_locale.getLanguage();
        String helpset_name;
        if (language.equalsIgnoreCase("de"))
        {
            helpset_name = "/eu/mihosoft/freerouting/helpset/de/Help.hs";
        }
        else
        {
            helpset_name = "/eu/mihosoft/freerouting/helpset/en/Help.hs";
        }
        try
        {
            // original author tries to get language specific url
            // via HelpSet utility methods which does not work that well
            // and doesn't really make sense if the language is specified
            // manually
            // TODO find out why previous approach does not work reliably
            URL hsURL = getClass().getResource(helpset_name);
            if (hsURL == null)
            {
                FRLogger.warn("HelpSet " + helpset_name + " not found.");
            }
            else
            {
                BoardFrame.help_set = new HelpSet(null, hsURL);
            }
        }
        catch (HelpSetException ee)
        {
            FRLogger.error("HelpSet " + helpset_name + " could not be opened.", ee);
        }
        if (BoardFrame.help_set != null)
        {
            BoardFrame.help_broker = BoardFrame.help_set.createHelpBroker();
        }
        if (BoardFrame.help_broker != null)
        {
            // CSH.DisplayHelpFromSource is a convenience class to display the helpset
            contents_help = new CSH.DisplayHelpFromSource(BoardFrame.help_broker);
            direct_help = new CSH.DisplayHelpAfterTracking(BoardFrame.help_broker);
        }
    }
}
 

HelpSet getHelpSet() {
	return helpSet;
}
 

/**
 * Merge a custom helpset to the master helpset.
 * <p>
 * Merge helpsets registered using e.g.
 * {@code @ServiceProvider(service=HelpSet.class)} to the master helpset.
 * </p>
 * <p>
 * You may need this method if you create helpsets that use some special
 * sources of data, e.g. the web. See bug 234144.
 * </p>
 *
 * @param customHelpSet The custom help set.
 */
public static void mergeCustomHelpset(HelpSet customHelpSet) {
    customHelpSet.setKeyData(
            HelpConstants.HELPSET_MERGE_CONTEXT,
            HelpConstants.HELPSET_MERGE_ATTR,
            true);
}
 

/** Whether a given help set is supposed to be merged
 * into the master set.
 * @param hs the help set
 * @return true if so
 */    
protected final boolean shouldMerge(HelpSet hs) {
    Boolean b = (Boolean)hs.getKeyData(HELPSET_MERGE_CONTEXT, HELPSET_MERGE_ATTR);
    return (b == null) || b.booleanValue();
}
 

public abstract HelpSet loadHelpSet();