001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui.help;
003
004import java.io.BufferedReader;
005import java.io.IOException;
006import java.net.MalformedURLException;
007import java.net.URL;
008
009import org.openstreetmap.josm.tools.HttpClient;
010import org.openstreetmap.josm.tools.WikiReader;
011
012/**
013 * Reads help content from the JOSM Wiki and prepares it for rendering in the internal
014 * help browser.
015 *
016 * The help content has to be <strong>filtered</strong> because only the main content <code>&lt;div&gt;</code>
017 * of a Wiki help page is displayed in the internal help browser.
018 *
019 * It also has to be <strong>transformed</strong> because the internal help browser required slightly
020 * different HTML than what is provided by the Wiki.
021 */
022public class HelpContentReader extends WikiReader {
023
024    /**
025     * Constructs a new {@code HelpContentReader}.
026     *
027     * @param baseUrl the base url of the JOSM help wiki, i.e. https://josm.openstreetmap.org
028     */
029    public HelpContentReader(String baseUrl) {
030        super(baseUrl);
031    }
032
033    /**
034     * Fetches the content of a help topic from the JOSM wiki.
035     *
036     * @param helpTopicUrl  the absolute help topic URL
037     * @param dotest if {@code true}, checks if help content is empty
038     * @return the content, filtered and transformed for being displayed in the internal help browser
039     * @throws HelpContentReaderException if problem occurs
040     * @throws MissingHelpContentException if this helpTopicUrl doesn't point to an existing Wiki help page
041     */
042    public String fetchHelpTopicContent(String helpTopicUrl, boolean dotest) throws HelpContentReaderException {
043        if (helpTopicUrl == null)
044            throw new MissingHelpContentException("helpTopicUrl is null");
045        HttpClient.Response con = null;
046        try {
047            URL u = new URL(helpTopicUrl);
048            con = HttpClient.create(u).connect();
049            try (BufferedReader in = con.getContentReader()) {
050                return prepareHelpContent(in, dotest, u);
051            }
052        } catch (MalformedURLException e) {
053            throw new HelpContentReaderException(e, 0);
054        } catch (IOException e) {
055            throw new HelpContentReaderException(e, con != null ? con.getResponseCode() : 0);
056        }
057    }
058
059    /**
060     * Reads help content from the input stream and prepares it to be rendered later
061     * in the internal help browser.
062     *
063     * Throws a {@link MissingHelpContentException} if the content read from the stream
064     * most likely represents a stub help page.
065     *
066     * @param in the input stream
067     * @param dotest if {@code true}, checks if help content is empty
068     * @param url help topic URL
069     * @return the content
070     * @throws HelpContentReaderException if an exception occurs
071     * @throws MissingHelpContentException if the content read isn't a help page
072     * @since 5936
073     */
074    protected String prepareHelpContent(BufferedReader in, boolean dotest, URL url) throws HelpContentReaderException {
075        String s = "";
076        try {
077            s = readFromTrac(in, url);
078        } catch (IOException e) {
079            throw new HelpContentReaderException(e, 0);
080        }
081        if (dotest && s.isEmpty())
082            throw new MissingHelpContentException(s);
083        return s;
084    }
085}