001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.tools;
003
004import static org.openstreetmap.josm.tools.I18n.tr;
005
006import java.awt.GraphicsEnvironment;
007import java.awt.Toolkit;
008import java.awt.event.InputEvent;
009import java.io.BufferedReader;
010import java.io.File;
011import java.io.IOException;
012import java.io.InputStreamReader;
013import java.lang.management.ManagementFactory;
014import java.nio.charset.StandardCharsets;
015import java.security.KeyStoreException;
016import java.security.NoSuchAlgorithmException;
017import java.security.cert.CertificateException;
018import java.security.cert.X509Certificate;
019import java.util.ArrayList;
020import java.util.Collection;
021import java.util.Collections;
022import java.util.List;
023
024import org.openstreetmap.josm.data.projection.datum.NTV2Proj4DirGridShiftFileSource;
025import org.openstreetmap.josm.io.CertificateAmendment.NativeCertAmend;
026import org.openstreetmap.josm.spi.preferences.Config;
027
028/**
029 * This interface allows platform (operating system) dependent code
030 * to be bundled into self-contained classes.
031 * @since 1023
032 */
033public interface PlatformHook {
034
035    /**
036     * Visitor to construct a PlatformHook from a given {@link Platform} object.
037     */
038    PlatformVisitor<PlatformHook> CONSTRUCT_FROM_PLATFORM = new PlatformVisitor<>() {
039        @Override
040        public PlatformHook visitUnixoid() {
041            return new PlatformHookUnixoid();
042        }
043
044        @Override
045        public PlatformHook visitWindows() {
046            return new PlatformHookWindows();
047        }
048
049        @Override
050        public PlatformHook visitOsx() {
051            return new PlatformHookOsx();
052        }
053    };
054
055    /**
056     * Get the platform corresponding to this platform hook.
057     * @return the platform corresponding to this platform hook
058     */
059    Platform getPlatform();
060
061    /**
062      * The preStartupHook will be called extremely early. It is
063      * guaranteed to be called before the GUI setup has started.
064      * <p>
065      * Reason: On OSX we need to inform the Swing libraries
066      * that we want to be integrated with the OS before we setup our GUI.
067      */
068    default void preStartupHook() {
069        // Do nothing
070    }
071
072    /**
073      * The afterPrefStartupHook will be called early, but after
074      * the preferences have been loaded and basic processing of
075      * command line arguments is finished.
076      * It is guaranteed to be called before the GUI setup has started.
077      */
078    default void afterPrefStartupHook() {
079        // Do nothing
080    }
081
082    /**
083     * The startupHook will be called early, but after the GUI
084     * setup has started.
085     * <p>
086     * Reason: On OSX we need to register some callbacks with the
087     * OS, so we'll receive events from the system menu.
088     * @param javaCallback Java expiration callback, providing GUI feedback
089     * @param sanityCheckCallback Sanity check callback, providing GUI feedback
090     * @since 18985
091     */
092    default void startupHook(JavaExpirationCallback javaCallback, SanityCheckCallback sanityCheckCallback) {
093        startupSanityChecks(sanityCheckCallback);
094    }
095
096    /**
097      * The openURL hook will be used to open a URL in the
098      * default web browser.
099     * @param url The URL to open
100     * @throws IOException if any I/O error occurs
101      */
102    void openUrl(String url) throws IOException;
103
104    /**
105      * The initSystemShortcuts hook will be called by the
106      * Shortcut class after the modifier groups have been read
107      * from the config, but before any shortcuts are read from
108      * it or registered from within the application.
109      * <p>
110      * Please note that you are not allowed to register any
111      * shortcuts from this hook, but only "systemCuts"!
112      * <p>
113      * BTW: SystemCuts should be named "system:&lt;whatever&gt;",
114      * and it'd be best if you'd recycle the names already used
115      * by the Windows and OSX hooks. Especially the latter has
116      * really many of them.
117      * <p>
118      * You should also register any and all shortcuts that the
119      * operating system handles itself to block JOSM from trying
120      * to use them---as that would just not work. Call setAutomatic
121      * on them to prevent the keyboard preferences from allowing the
122      * user to change them.
123      */
124    void initSystemShortcuts();
125
126    /**
127     * Returns the default LAF to be used on this platform to look almost as a native application.
128     * @return The default native LAF for this platform
129     */
130    String getDefaultStyle();
131
132    /**
133     * Determines if the platform allows full-screen.
134     * @return {@code true} if full screen is allowed, {@code false} otherwise
135     */
136    default boolean canFullscreen() {
137        return !GraphicsEnvironment.isHeadless() &&
138                GraphicsEnvironment.getLocalGraphicsEnvironment().getDefaultScreenDevice().isFullScreenSupported();
139    }
140
141    /**
142     * Renames a file.
143     * @param from Source file
144     * @param to Target file
145     * @return {@code true} if the file has been renamed, {@code false} otherwise
146     */
147    default boolean rename(File from, File to) {
148        return from.renameTo(to);
149    }
150
151    /**
152     * Returns a detailed OS description (at least family + version).
153     * @return A detailed OS description.
154     * @since 5850
155     */
156    String getOSDescription();
157
158    /**
159     * Returns OS build number.
160     * @return OS build number.
161     * @since 12217
162     */
163    default String getOSBuildNumber() {
164        return "";
165    }
166
167    /**
168     * Returns the {@code X509Certificate} matching the given certificate amendment information.
169     * @param certAmend certificate amendment
170     * @return the {@code X509Certificate} matching the given certificate amendment information, or {@code null}
171     * @throws KeyStoreException in case of error
172     * @throws IOException in case of error
173     * @throws CertificateException in case of error
174     * @throws NoSuchAlgorithmException in case of error
175     * @since 13450
176     */
177    default X509Certificate getX509Certificate(NativeCertAmend certAmend)
178            throws KeyStoreException, NoSuchAlgorithmException, CertificateException, IOException {
179        return null;
180    }
181
182    /**
183     * Executes a native command and returns the first line of standard output.
184     * @param command array containing the command to call and its arguments.
185     * @return first stripped line of standard output
186     * @throws IOException if an I/O error occurs
187     * @since 12217
188     */
189    default String exec(String... command) throws IOException {
190        Process p = Runtime.getRuntime().exec(command);
191        try (BufferedReader input = new BufferedReader(new InputStreamReader(p.getInputStream(), StandardCharsets.UTF_8))) {
192            return Utils.strip(input.readLine());
193        }
194    }
195
196    /**
197     * Returns the platform-dependent default cache directory.
198     * @return the platform-dependent default cache directory
199     * @since 7829
200     */
201    File getDefaultCacheDirectory();
202
203    /**
204     * Returns the platform-dependent default preferences directory.
205     * @return the platform-dependent default preferences directory
206     * @since 7831
207     */
208    File getDefaultPrefDirectory();
209
210    /**
211     * Returns the platform-dependent default user data directory.
212     * @return the platform-dependent default user data directory
213     * @since 7834
214     */
215    File getDefaultUserDataDirectory();
216
217    /**
218     * Returns the list of platform-dependent default datum shifting directories for the PROJ.4 library.
219     * @return the list of platform-dependent default datum shifting directories for the PROJ.4 library
220     * @since 11642
221     */
222    default List<File> getDefaultProj4NadshiftDirectories() {
223        return getPlatform().accept(NTV2Proj4DirGridShiftFileSource.getInstance());
224    }
225
226    /**
227     * Determines if the JVM is OpenJDK-based.
228     * @return {@code true} if {@code java.home} contains "openjdk", {@code false} otherwise
229     * @since 12219
230     */
231    default boolean isOpenJDK() {
232        String javaHome = Utils.getSystemProperty("java.home");
233        return javaHome != null && javaHome.contains("openjdk");
234    }
235
236    /**
237     * Determines if HTML rendering is supported in menu tooltips.
238     * @return {@code true} if HTML rendering is supported in menu tooltips
239     * @since 18116
240     */
241    default boolean isHtmlSupportedInMenuTooltips() {
242        return true;
243    }
244
245    /**
246     * Returns extended modifier key used as the appropriate accelerator key for menu shortcuts.
247     * It was advised everywhere to use {@link Toolkit#getMenuShortcutKeyMask()} to get the cross-platform modifier, but:
248     * <ul>
249     * <li>it returns KeyEvent.CTRL_MASK instead of KeyEvent.CTRL_DOWN_MASK. We used the extended
250     *    modifier for years, and Oracle recommends to use it instead, so it's best to keep it</li>
251     * <li>the method throws a HeadlessException ! So we would need to handle it for unit tests anyway</li>
252     * </ul>
253     * @return extended modifier key used as the appropriate accelerator key for menu shortcuts
254     * @since 12748 (as a replacement to {@code GuiHelper.getMenuShortcutKeyMaskEx()})
255     */
256    default int getMenuShortcutKeyMaskEx() {
257        if (!GraphicsEnvironment.isHeadless()) {
258            return Toolkit.getDefaultToolkit().getMenuShortcutKeyMaskEx();
259        }
260        return InputEvent.CTRL_DOWN_MASK;
261    }
262
263    /**
264     * Called when an outdated version of Java is detected at startup.
265     * @since 12270
266     */
267    @FunctionalInterface
268    interface JavaExpirationCallback {
269        /**
270         * Asks user to update its version of Java.
271         * @param updVersion target update version
272         * @param url download URL
273         * @param major true for a migration towards a major version of Java (8:9), false otherwise
274         * @param eolDate the EOL/expiration date
275         */
276        void askUpdateJava(String updVersion, String url, String eolDate, boolean major);
277    }
278
279    /**
280     * Inform the user that a sanity check or checks failed
281     */
282    @FunctionalInterface
283    interface SanityCheckCallback {
284        /**
285         * Tells the user that a sanity check failed
286         * @param title The title of the message to show
287         * @param canContinue {@code true} if the failed sanity check(s) will not instantly kill JOSM when the user edits
288         * @param message The message parts to show the user (as a list)
289         */
290        void sanityCheckFailed(String title, boolean canContinue, String... message);
291    }
292
293    /**
294     * Checks if we will soon not be supporting the running version of Java
295     * @param callback Java expiration callback
296     * @since 18580
297     */
298    default void warnSoonToBeUnsupportedJava(JavaExpirationCallback callback) {
299        // Java 17 is our next minimum version, and OpenWebStart should be replacing Oracle WebStart
300        if (Utils.getJavaVersion() < 17 && !Utils.isRunningWebStart()) {
301            String latestVersion = Utils.getJavaLatestVersion();
302            String currentVersion = Utils.getSystemProperty("java.version");
303            // #17831 WebStart may be launched with an expired JRE but then launching JOSM with up-to-date JRE
304            if (latestVersion == null || !latestVersion.equalsIgnoreCase(currentVersion)) {
305                callback.askUpdateJava(latestVersion != null ? latestVersion : "latest",
306                        Config.getPref().get("java.update.url", getJavaUrl()),
307                        null, Utils.getJavaVersion() < 17);
308            }
309        }
310    }
311
312    /**
313     * Get the Java download URL (really shouldn't be used outside of JOSM startup checks)
314     * @return The download URL to use.
315     * @since 18580
316     */
317    default String getJavaUrl() {
318        StringBuilder defaultDownloadUrl = new StringBuilder("https://www.azul.com/downloads/?version=java-21-lts");
319        if (PlatformManager.isPlatformWindows()) {
320            defaultDownloadUrl.append("&os=windows");
321        } else if (PlatformManager.isPlatformOsx()) {
322            defaultDownloadUrl.append("&os=macos");
323        } // else probably `linux`, but they should be using a package manager.
324        // For available architectures, see
325        // https://github.com/openjdk/jdk/blob/master/src/jdk.hotspot.agent/share/classes/sun/jvm/hotspot/utilities/PlatformInfo.java#L53
326        String osArch = System.getProperty("os.arch");
327        if (osArch != null) {
328            // See https://learn.microsoft.com/en-us/windows/win32/winprog64/wow64-implementation-details#environment-variables
329            // for PROCESSOR_ARCHITEW6432
330            if ("x86_64".equals(osArch) || "amd64".equals(osArch)
331                    || "AMD64".equalsIgnoreCase(System.getenv("PROCESSOR_ARCHITEW6432"))) {
332                defaultDownloadUrl.append("&architecture=x86-64-bit").append("&package=jdk-fx"); // jdk-fx has an installer
333            } else if ("aarch64".equals(osArch)) {
334                defaultDownloadUrl.append("&architecture=arm-64-bit").append("&package=jdk-fx"); // jdk-fx has an installer
335            } else if ("x86".equals(osArch)) {
336                // Honestly, just about everyone should be on x86_64 at this point. But just in case someone
337                // is running JOSM on a 10-year-old computer. They'd probably be better off running a RPi.
338                defaultDownloadUrl.append("&architecture=x86-32-bit").append("&package=jdk"); // jdk has an installer
339            } // else user will have to figure it out themselves.
340        }
341        defaultDownloadUrl.append("#zulu"); // Scrolls to download section
342        return defaultDownloadUrl.toString();
343    }
344
345    /**
346     * Check startup preconditions
347     * @param sanityCheckCallback The callback to inform the user about failed checks
348     */
349    default void startupSanityChecks(SanityCheckCallback sanityCheckCallback) {
350        final String arch = System.getProperty("os.arch");
351        final List<String> messages = new ArrayList<>();
352        final String jvmArch = System.getProperty("sun.arch.data.model");
353        boolean canContinue = true;
354        if (Utils.getJavaVersion() < 11) {
355            canContinue = false;
356            messages.add(tr("You must update Java to Java {0} or later in order to run this version of JOSM", 17));
357            // Reset webstart/java update prompts
358            Config.getPref().put("askUpdateWebStart", null);
359            Config.getPref().put("askUpdateJava" + Utils.getJavaLatestVersion(), null);
360            Config.getPref().put("askUpdateJavalatest", null);
361        }
362        if (!"x86".equals(arch) && "32".equals(jvmArch)) {
363            messages.add(tr("Please use a 64 bit version of Java -- this will avoid out of memory errors"));
364        }
365        // Note: these might be able to be removed with the appropriate module-info.java settings.
366        final String[] expectedJvmArguments = {
367                "--add-exports=java.base/sun.security.action=ALL-UNNAMED",
368                "--add-exports=java.desktop/com.sun.imageio.plugins.jpeg=ALL-UNNAMED",
369                "--add-exports=java.desktop/com.sun.imageio.spi=ALL-UNNAMED"
370        };
371        final List<String> vmArguments = ManagementFactory.getRuntimeMXBean().getInputArguments();
372        final StringBuilder missingArguments = new StringBuilder();
373        for (String arg : expectedJvmArguments) {
374            if (vmArguments.stream().noneMatch(s -> s.contains(arg))) {
375                if (missingArguments.length() > 0) {
376                    missingArguments.append("<br>");
377                }
378                missingArguments.append(arg);
379            }
380        }
381        if (missingArguments.length() > 0) {
382            final String args = missingArguments.toString();
383            messages.add(tr("Missing JVM Arguments:<br>{0}<br>" +
384                    "These arguments should be added in the command line or start script before the -jar parameter.", args));
385        }
386        if (!messages.isEmpty()) {
387            if (canContinue) {
388                sanityCheckCallback.sanityCheckFailed(tr("JOSM may work improperly"), true,
389                        messages.toArray(new String[0]));
390            } else {
391                sanityCheckCallback.sanityCheckFailed(tr("JOSM will be unable to work properly and will exit"), false,
392                        messages.toArray(new String[0]));
393            }
394        }
395    }
396
397    /**
398     * Called when interfacing with native OS functions. Currently only used with macOS.
399     * The callback must perform all GUI-related tasks associated to an OS request.
400     * The non-GUI, platform-specific tasks, are usually performed by the {@code PlatformHook}.
401     * @since 12695
402     */
403    interface NativeOsCallback {
404        /**
405         * macOS: Called when JOSM is asked to open a list of files.
406         * @param files list of files to open
407         */
408        void openFiles(List<File> files);
409
410        /**
411         * macOS: Invoked when JOSM is asked to quit.
412         * @return {@code true} if JOSM has been closed, {@code false} if the user has cancelled the operation.
413         */
414        boolean handleQuitRequest();
415
416        /**
417         * macOS: Called when JOSM is asked to show it's about dialog.
418         */
419        void handleAbout();
420
421        /**
422         * macOS: Called when JOSM is asked to show it's preferences UI.
423         */
424        void handlePreferences();
425    }
426
427    /**
428     * Registers the native OS callback. Currently only needed for macOS.
429     * @param callback the native OS callback
430     * @since 12695
431     */
432    default void setNativeOsCallback(NativeOsCallback callback) {
433        // To be implemented if needed
434    }
435
436    /**
437     * Resolves a file link to its destination file.
438     * @param file file (link or regular file)
439     * @return destination file in case of a file link, file if regular
440     * @since 13691
441     */
442    default File resolveFileLink(File file) {
443        // Override if needed
444        return file;
445    }
446
447    /**
448     * Returns a set of possible platform specific directories where resources could be stored.
449     * @return A set of possible platform specific directories where resources could be stored.
450     * @since 14144
451     */
452    default Collection<String> getPossiblePreferenceDirs() {
453        return Collections.emptyList();
454    }
455}