7131021: [macosx] Consider using system properties to pass arguments from the launcher to AWT/SplashScreen

Document the environment variables and add tests

Reviewed-by: ksrini

jdk/src/macosx/bin/java_md_macosx.c

@@ -906,11 +906,41 @@ SetXDockArgForAWT(const char *arg)
 {
     char envVar[80];
     if (strstr(arg, "-Xdock:name=") == arg) {
+        /*
+         * The APP_NAME_<pid> environment variable is used to pass
+         * an application name as specified with the -Xdock:name command
+         * line option from Java launcher code to the AWT code in order
+         * to assign this name to the app's dock tile on the Mac.
+         * The _<pid> part is added to avoid collisions with child processes.
+         *
+         * WARNING: This environment variable is an implementation detail and
+         * isn't meant for use outside of the core platform. The mechanism for
+         * passing this information from Java launcher to other modules may
+         * change drastically between update release, and it may even be
+         * removed or replaced with another mechanism.
+         *
+         * NOTE: It is used by SWT, and JavaFX.
+         */
         snprintf(envVar, sizeof(envVar), "APP_NAME_%d", getpid());
         setenv(envVar, (arg + 12), 1);
     }
 
     if (strstr(arg, "-Xdock:icon=") == arg) {
+        /*
+         * The APP_ICON_<pid> environment variable is used to pass
+         * an application icon as specified with the -Xdock:icon command
+         * line option from Java launcher code to the AWT code in order
+         * to assign this icon to the app's dock tile on the Mac.
+         * The _<pid> part is added to avoid collisions with child processes.
+         *
+         * WARNING: This environment variable is an implementation detail and
+         * isn't meant for use outside of the core platform. The mechanism for
+         * passing this information from Java launcher to other modules may
+         * change drastically between update release, and it may even be
+         * removed or replaced with another mechanism.
+         *
+         * NOTE: It is used by SWT, and JavaFX.
+         */
         snprintf(envVar, sizeof(envVar), "APP_ICON_%d", getpid());
         setenv(envVar, (arg + 12), 1);
     }
@@ -931,6 +961,22 @@ SetMainClassForAWT(JNIEnv *env, jclass mainClass) {
     NULL_CHECK(mainClassName = (*env)->GetStringUTFChars(env, mainClassString, NULL));
 
     char envVar[80];
+    /*
+     * The JAVA_MAIN_CLASS_<pid> environment variable is used to pass
+     * the name of a Java class whose main() method is invoked by
+     * the Java launcher code to start the application, to the AWT code
+     * in order to assign the name to the Apple menu bar when the app
+     * is active on the Mac.
+     * The _<pid> part is added to avoid collisions with child processes.
+     *
+     * WARNING: This environment variable is an implementation detail and
+     * isn't meant for use outside of the core platform. The mechanism for
+     * passing this information from Java launcher to other modules may
+     * change drastically between update release, and it may even be
+     * removed or replaced with another mechanism.
+     *
+     * NOTE: It is used by SWT, and JavaFX.
+     */
     snprintf(envVar, sizeof(envVar), "JAVA_MAIN_CLASS_%d", getpid());
     setenv(envVar, mainClassName, 1);
 

jdk/test/tools/launcher/EnvironmentVariables.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * see TestSpecialArgs.java
+ * bug 7131021
+ * summary Checks for environment variables set by the launcher
+ * author anthony.petrov@oracle.com: area=launcher
+ */
+
+public class EnvironmentVariables {
+    public static void main(String[] args) {
+        if (args.length != 2) {
+            throw new RuntimeException("ERROR: two command line arguments expected");
+        }
+
+        String name = args[0];
+        String expect = args[1];
+        String key = null;
+
+        if (!name.endsWith("*")) {
+            key = name;
+        } else {
+            name = name.split("\\*")[0];
+
+            for (String s : System.getenv().keySet()) {
+                if (s.startsWith(name)) {
+                    if (key == null) {
+                        key = s;
+                    } else {
+                        System.err.println("WARNING: more variables match: " + s);
+                    }
+                }
+            }
+
+            if (key == null) {
+                throw new RuntimeException("ERROR: unable to find a match for: " + name);
+            }
+        }
+
+        System.err.println("Will check the variable named: '" + key +
+                "' expecting the value: '" + expect + "'");
+
+        if (!System.getenv().containsKey(key)) {
+            throw new RuntimeException("ERROR: the variable '" + key +
+                    "' is not present in the environment");
+        }
+
+        if (!expect.equals(System.getenv().get(key))) {
+            throw new RuntimeException("ERROR: expected: '" + expect +
+                    "', got: '" + System.getenv().get(key) + "'");
+        }
+        for (String x : args) {
+            System.err.print(x + " ");
+        }
+        System.err.println("-----> Passed!");
+    }
+}
+

jdk/test/tools/launcher/TestHelper.java

@@ -21,6 +21,7 @@
  * questions.
  */
 
+import java.util.Set;
 import java.io.BufferedReader;
 import java.io.File;
 import java.io.FileFilter;
@@ -316,19 +317,28 @@ public class TestHelper {
     }
 
     static TestResult doExec(String...cmds) {
-        return doExec(null, cmds);
+        return doExec(null, null, cmds);
     }
 
+    static TestResult doExec(Map<String, String> envToSet, String...cmds) {
+        return doExec(envToSet, null, cmds);
+    }
     /*
      * A method which executes a java cmd and returns the results in a container
      */
-    static TestResult doExec(Map<String, String> envToSet, String...cmds) {
+    static TestResult doExec(Map<String, String> envToSet,
+                             Set<String> envToRemove, String...cmds) {
         String cmdStr = "";
         for (String x : cmds) {
             cmdStr = cmdStr.concat(x + " ");
         }
         ProcessBuilder pb = new ProcessBuilder(cmds);
         Map<String, String> env = pb.environment();
+        if (envToRemove != null) {
+            for (String key : envToRemove) {
+                env.remove(key);
+            }
+        }
         if (envToSet != null) {
             env.putAll(envToSet);
         }

jdk/test/tools/launcher/TestSpecialArgs.java

@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 7124089 7131021
+ * @summary Checks for MacOSX specific flags are accepted or rejected, and
+ *          MacOSX platforms specific environment is consistent.
+ * @compile -XDignore.symbol.file TestSpecialArgs.java EnvironmentVariables.java
+ * @run main TestSpecialArgs
+ */
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+
+public class TestSpecialArgs extends TestHelper {
+
+    public static void main(String... args) {
+        final Map<String, String> envMap = new HashMap<>();
+        envMap.put("_JAVA_LAUNCHER_DEBUG", "true");
+
+        TestResult tr = doExec(envMap, javaCmd, "-XstartOnFirstThread", "-version");
+        if (isMacOSX) {
+            if (!tr.contains("In same thread")) {
+                System.out.println(tr);
+                throw new RuntimeException("Error: not running in the same thread ?");
+            }
+            if (!tr.isOK()) {
+                System.out.println(tr);
+                throw new RuntimeException("Error: arg was rejected ????");
+            }
+        } else {
+            if (tr.isOK()) {
+                System.out.println(tr);
+                throw new RuntimeException("Error: argument was accepted ????");
+            }
+        }
+
+        tr = doExec(javaCmd, "-Xdock:/tmp/not-available", "-version");
+        if (isMacOSX) {
+            if (!tr.isOK()) {
+                System.out.println(tr);
+                throw new RuntimeException("Error: arg was rejected ????");
+            }
+        } else {
+            if (tr.isOK()) {
+                System.out.println(tr);
+                throw new RuntimeException("Error: argument was accepted ????");
+            }
+        }
+        // MacOSX specific tests ensue......
+        if (!isMacOSX)
+            return;
+        Set<String> envToRemove = new HashSet<>();
+        Map<String, String> map = System.getenv();
+        for (String s : map.keySet()) {
+            if (s.startsWith("JAVA_MAIN_CLASS_")
+                    || s.startsWith("APP_NAME_")
+                    || s.startsWith("APP_ICON_")) {
+                envToRemove.add(s);
+            }
+        }
+        runTest(envToRemove, javaCmd, "-cp", TEST_CLASSES_DIR.getAbsolutePath(),
+                "EnvironmentVariables", "JAVA_MAIN_CLASS_*",
+                "EnvironmentVariables");
+
+        runTest(envToRemove, javaCmd, "-cp", TEST_CLASSES_DIR.getAbsolutePath(),
+                "-Xdock:name=TestAppName", "EnvironmentVariables",
+                "APP_NAME_*", "TestAppName");
+
+        runTest(envToRemove, javaCmd, "-cp", TEST_CLASSES_DIR.getAbsolutePath(),
+                "-Xdock:icon=TestAppIcon", "EnvironmentVariables",
+                "APP_ICON_*", "TestAppIcon");
+    }
+
+    static void runTest(Set<String> envToRemove, String... args) {
+        TestResult tr = doExec(null, envToRemove, args);
+        if (!tr.isOK()) {
+            System.err.println(tr.toString());
+            throw new RuntimeException("Test Fails");
+        }
+    }
+}