diff --git a/test/lib/jdk/test/lib/SecurityTools.java b/test/lib/jdk/test/lib/SecurityTools.java
index 9568ade17f7..45a6623b801 100644
--- a/test/lib/jdk/test/lib/SecurityTools.java
+++ b/test/lib/jdk/test/lib/SecurityTools.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2018, 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
@@ -36,10 +36,23 @@
import jdk.test.lib.process.OutputAnalyzer;
import jdk.test.lib.process.ProcessTools;
+/**
+ * Run security tools (including jarsigner and keytool) in a new process.
+ * The en_US locale is always used so a test can always match output to
+ * English text. {@code /dev/urandom} is used as entropy source so tool will
+ * not block because of entropy scarcity. {@code -Jvm-options} is supported
+ * as an argument.
+ */
public class SecurityTools {
+ /**
+ * The response file name for keytool. Use {@link #setResponse} to
+ * create one. Do NOT manipulate it directly.
+ */
public static final String RESPONSE_FILE = "security_tools_response.txt";
+ private SecurityTools() {}
+
private static ProcessBuilder getProcessBuilder(String tool, List<String> args) {
JDKToolLauncher launcher = JDKToolLauncher.createUsingTestJDK(tool)
.addVMArg("-Duser.language=en")
@@ -57,8 +70,13 @@ private static ProcessBuilder getProcessBuilder(String tool, List<String> args)
return new ProcessBuilder(launcher.getCommand());
}
- // keytool
-
+ /**
+ * Runs keytool.
+ *
+ * @param args arguments to keytool
+ * @return an {@link OutputAnalyzer} object
+ * @throws Exception if there is an error
+ */
public static OutputAnalyzer keytool(List<String> args)
throws Exception {
@@ -77,15 +95,46 @@ public static OutputAnalyzer keytool(List<String> args)
}
}
- // Only call this if there is no white space in every argument
+ /**
+ * Runs keytool.
+ *
+ * @param args arguments to keytool in a single string. Only call this if
+ * there is no white space inside an argument. This string will
+ * be split with {@code \s+}.
+ * @return an {@link OutputAnalyzer} object
+ * @throws Exception if there is an error
+ */
public static OutputAnalyzer keytool(String args) throws Exception {
return keytool(args.split("\\s+"));
}
+ /**
+ * Runs keytool.
+ *
+ * @param args arguments to keytool
+ * @return an {@link OutputAnalyzer} object
+ * @throws Exception if there is an error
+ */
public static OutputAnalyzer keytool(String... args) throws Exception {
return keytool(List.of(args));
}
+
+ /**
+ * Sets the responses (user input) for keytool.
+ * <p>
+ * For example, if keytool requires entering a password twice, call
+ * {@code setResponse("password", "password")}. Do NOT append a newline
+ * character to each response. If there are useless responses at the end,
+ * they will be discarded silently. If there are less responses than
+ * necessary, keytool will read EOF. The responses will be written into
+ * {@linkplain #RESPONSE_FILE a local file} and will only be used by the
+ * next keytool run. After the run, the file is removed. Calling this
+ * method will always overwrite the previous response file (if exists).
+ *
+ * @param responses response to keytool
+ * @throws IOException if there is an error
+ */
public static void setResponse(String... responses) throws IOException {
String text;
if (responses.length > 0) {
@@ -97,8 +146,13 @@ public static void setResponse(String... responses) throws IOException {
Files.write(Paths.get(RESPONSE_FILE), text.getBytes());
}
- // jarsigner
-
+ /**
+ * Runs jarsigner.
+ *
+ * @param args arguments to jarsigner
+ * @return an {@link OutputAnalyzer} object
+ * @throws Exception if there is an error
+ */
public static OutputAnalyzer jarsigner(List<String> args)
throws Exception {
return execute(getProcessBuilder("jarsigner", args));
@@ -118,12 +172,27 @@ private static OutputAnalyzer execute(ProcessBuilder pb) throws Exception {
}
}
- // Only call this if there is no white space in every argument
+ /**
+ * Runs jarsigner.
+ *
+ * @param args arguments to jarsigner in a single string. Only call this if
+ * there is no white space inside an argument. This string will
+ * be split with {@code \s+}.
+ * @return an {@link OutputAnalyzer} object
+ * @throws Exception if there is an error
+ */
public static OutputAnalyzer jarsigner(String args) throws Exception {
return jarsigner(args.split("\\s+"));
}
+ /**
+ * Runs jarsigner.
+ *
+ * @param args arguments to jarsigner
+ * @return an {@link OutputAnalyzer} object
+ * @throws Exception if there is an error
+ */
public static OutputAnalyzer jarsigner(String... args) throws Exception {
return jarsigner(List.of(args));
}
diff --git a/test/lib/jdk/test/lib/util/JarUtils.java b/test/lib/jdk/test/lib/util/JarUtils.java
index 8f8d0d9ffb0..8e16cc1cf6c 100644
--- a/test/lib/jdk/test/lib/util/JarUtils.java
+++ b/test/lib/jdk/test/lib/util/JarUtils.java
@@ -153,6 +153,7 @@ public static void createJar(String dest, String... files)
* be either updated or added. The files in the 2nd group
* will be removed. If no "-" exists, all files belong to
* the 1st group.
+ * @throws IOException if there is an error
*/
public static void updateJar(String src, String dest, String... files)
throws IOException {
@@ -189,7 +190,7 @@ public static void updateJar(String src, String dest, String... files)
* Value can be Path, byte[] or String. If key exists in
* src but value is Boolean FALSE. The entry is removed.
* Existing entries in src not a key is unmodified.
- * @throws IOException
+ * @throws IOException if there is an error
*/
public static void updateJar(String src, String dest,
Map<String,Object> changes)