Ghidra is a software reverse engineering (SRE) framework
/* ###
* IP: GHIDRA
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package help;
import java.io.IOException;
import java.io.InputStream;
import java.net.*;
import java.util.Enumeration;
import java.util.Map.Entry;
import java.util.Set;
import javax.help.*;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import ghidra.util.SystemUtilities;
import help.validator.JavaHelpValidator;
/**
* Ghidra help set that creates a GhidraHelpBroker, installs some custom HTML handling code via
* the GHelpHTMLEditorKit, and most importantly, changes how the JavaHelp system works with
* regard to integrating Help Sets.
* <p>
* The HelpSet class uses a javax.help.Map object to locate HTML files by javax.help.map.ID objects.
* This class has overridden that basic usage of the Map object to allow ID lookups to take
* place across GHelpSet objects. We need to do this due to how we merge help set content
* across modules. More specifically, in order to merge, we have to make all {@code <tocitem>} xml tags
* the same, including the target HTML file they may reference. Well, when a module uses a
* {@code <tocitem>} tag that references an HTML file <b>not inside of it's module</b>, then JavaHelp
* considers this an error and does not correctly merge the HelpSets that share the reference.
* Further, it does not properly locate the shared HTML file reference. This class allows lookups
* across modules by overridden the lookup functionality done by the map object. More specifically,
* we override {@link #getCombinedMap()} and {@link #getLocalMap()} to use a custom delegate map
* object that knows how to do this "cross-module" help lookup.
*
*
*@see GHelpHTMLEditorKit
*/
public class GHelpSet extends HelpSet {
/** <b>static</b> map that contains all known help sets in the system. */
private static java.util.Map<HelpSet, Map> helpSetsToCombinedMaps = new java.util.HashMap<>();
private static java.util.Map<HelpSet, Map> helpSetsToLocalMaps = new java.util.HashMap<>();
private Logger LOG = LogManager.getLogger(GHelpSet.class);
private GHelpMap combinedMapWrapper;
private GHelpMap localMapWrapper;
public GHelpSet(ClassLoader loader, URL helpset) throws HelpSetException {
super(loader, helpset);
init();
}
private void init() {
// swap in Ghidra's editor kit, which is an overridden version of Java's
String type = "text/html";
String editorKit = GHelpHTMLEditorKit.class.getName();
ClassLoader classLoader = getClass().getClassLoader();
setKeyData(kitTypeRegistry, type, editorKit);
setKeyData(kitLoaderRegistry, type, classLoader);
initializeCombinedMapWrapper();
}
@Override
public HelpBroker createHelpBroker() {
return new GHelpBroker(this);
}
@Override
public Map getLocalMap() {
Map localMap = super.getLocalMap();
if (localMap == null) {
return null;
}
initializeLocalMapWrapper();
return localMapWrapper;
}
private void initializeLocalMapWrapper() {
if (localMapWrapper == null) {
Map localMap = super.getLocalMap();
helpSetsToLocalMaps.put(this, localMap);
localMapWrapper = new GHelpMap(localMap);
}
}
@Override
public Map getCombinedMap() {
return combinedMapWrapper;
}
private void initializeCombinedMapWrapper() {
if (combinedMapWrapper == null) {
Map combinedMap = super.getCombinedMap();
helpSetsToCombinedMaps.put(this, combinedMap);
combinedMapWrapper = new GHelpMap(combinedMap);
}
}
@Override
public String toString() {
return getHelpSetURL().toString();
}
//==================================================================================================
// Inner Classes
//==================================================================================================
/** A special class to allow us to handle help ID lookups across help sets */
private class GHelpMap implements Map {
private final Map mapDelegate;
private GHelpMap(Map mapDelegate) {
this.mapDelegate = mapDelegate;
}
@Override
public Enumeration<?> getAllIDs() {
return mapDelegate.getAllIDs();
}
@Override
public ID getClosestID(URL url) {
ID closestID = mapDelegate.getClosestID(url);
if (closestID != null) {
return closestID; // it's in our map
}
LOG.trace("Help Set \"" + GHelpSet.this + "\" does not contain ID for URL: " + url);
Set<Entry<HelpSet, Map>> entrySet = helpSetsToCombinedMaps.entrySet();
for (Entry<HelpSet, Map> entry : entrySet) {
Map map = entry.getValue();
closestID = map.getClosestID(url);
if (closestID != null) {
return closestID;
}
}
LOG.trace("No ID found in any HelpSet for URL: " + url);
return null;
}
@Override
public ID getIDFromURL(URL url) {
return mapDelegate.getIDFromURL(url);
}
@Override
public Enumeration<?> getIDs(URL url) {
return mapDelegate.getIDs(url);
}
@Override
public URL getURLFromID(ID id) throws MalformedURLException {
URL URL = mapDelegate.getURLFromID(id);
if (URL != null) {
return URL; // it's in our map
}
Set<Entry<HelpSet, Map>> entrySet = helpSetsToCombinedMaps.entrySet();
for (Entry<HelpSet, Map> entry : entrySet) {
Map map = entry.getValue();
URL = map.getURLFromID(id);
if (URL != null) {
return URL;
}
}
LOG.trace("No URL found in any HelpSet for ID: " + id);
URL = tryToCreateURLFromID(id.id);
if (URL != null) {
return URL;
}
return null;
}
/**
* This is meant for help files that are not included in the standard help system. Their
* id paths are expected to be relative to the application install directory.
* @param rawId the help id.
* @return the URL to the help file.
*/
private URL tryToCreateURLFromID(String rawId) {
String idText = rawId;
if (rawId.startsWith(JavaHelpValidator.EXTERNAL_PREFIX)) {
idText = rawId.substring(JavaHelpValidator.EXTERNAL_PREFIX.length());
}
URL fileUrl = HelpBuildUtils.findApplicationUrl(idText);
if (fileUrl != null) {
return fileUrl;
}
URL rawURL = createRawURL(idText);
return rawURL;
}
private URL createRawURL(String id) {
URL url = null;
try {
url = new URI(id).toURL();
}
catch (IllegalArgumentException | MalformedURLException | URISyntaxException e) {
LOG.trace("ID is not a URL; tried to make URL from string: " + id);
return null;
}
try {
InputStream inputStream = url.openStream();
inputStream.close();
return url; // it is valid
}
catch (IOException e) {
LOG.trace("ID is not a URL; unable to read URL: " + url);
}
return null;
}
@Override
public boolean isID(URL url) {
return mapDelegate.isID(url);
}
@Override
public boolean isValidID(String id, HelpSet hs) {
HelpService service = Help.getHelpService();
if (!service.helpExists()) {
// Treat everything as valid until all help is loaded, otherwise, we
// can't be sure that when something is missing, it is just not yet merged in.
return true;
}
boolean isValid = mapDelegate.isValidID(id, hs);
if (isValid) {
return true;
}
Set<Entry<HelpSet, Map>> entrySet = helpSetsToCombinedMaps.entrySet();
for (Entry<HelpSet, Map> entry : entrySet) {
Map map = entry.getValue();
if (map.isValidID(id, hs)) {
return true;
}
}
// This can happen for help files that are generated during the build,
// such as 'What's New'; return true here so the values will still be loaded into
// the help system; handle the error condition later.
if (ignoreExternalHelp(id)) {
return true;
}
return false;
}
private boolean ignoreExternalHelp(String id) {
if (id.startsWith("help/topics")) {
return false; // not external help location
}
URL url = tryToCreateURLFromID(id);
if (url != null) {
return true; // ignore this id; it is valid
}
// no url for ID
if (SystemUtilities.isInDevelopmentMode()) {
// ignore external files that do not exist in dev mode
return true;
}
return false;
}
}
}