Merge
authorduke
Wed, 05 Jul 2017 21:20:39 +0200
changeset 35813 2fc9abeff0d5
parent 35812 6a6ca0bd3c14 (diff)
parent 35805 a460a860cdb0 (current diff)
child 35814 6c644cca3f3f
Merge
jdk/src/java.base/share/classes/sun/misc/InnocuousThread.java
jdk/src/java.base/share/classes/sun/misc/LRUCache.java
--- a/langtools/.hgtags	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/.hgtags	Wed Jul 05 21:20:39 2017 +0200
@@ -347,3 +347,4 @@
 6149fc30cd710eb3484dc9863d8837ecaedb96b6 jdk-9+102
 94cfc50c1b8a74fd7b0ed2e9e4f4a9dab4f2c6a1 jdk-9+103
 3f60a4808377a276f6398ff19e61c1b9086f4d97 jdk-9+104
+81bd82222f8a1f2b291a44a49e063973caa4e73b jdk-9+105
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Lint.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Lint.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2016, 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
@@ -218,11 +218,6 @@
         STATIC("static"),
 
         /**
-         * Warn about proprietary API that may be removed in a future release.
-         */
-        SUNAPI("sunapi", true),
-
-        /**
          * Warn about issues relating to use of try blocks (i.e. try-with-resources)
          */
         TRY("try"),
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, 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
@@ -83,7 +83,6 @@
     private final JCDiagnostic.Factory diags;
     private boolean warnOnSyntheticConflicts;
     private boolean suppressAbortOnBadClassFile;
-    private boolean enableSunApiLintControl;
     private final JavaFileManager fileManager;
     private final Source source;
     private final Profile profile;
@@ -131,10 +130,8 @@
         allowStrictMethodClashCheck = source.allowStrictMethodClashCheck();
         allowPrivateSafeVarargs = source.allowPrivateSafeVarargs();
         allowDiamondWithAnonymousClassCreation = source.allowDiamondWithAnonymousClassCreation();
-        complexInference = options.isSet("complexinference");
         warnOnSyntheticConflicts = options.isSet("warnOnSyntheticConflicts");
         suppressAbortOnBadClassFile = options.isSet("suppressAbortOnBadClassFile");
-        enableSunApiLintControl = options.isSet("enableSunApiLintControl");
         warnOnAccessToSensitiveMembers = options.isSet("warnOnAccessToSensitiveMembers");
 
         Target target = Target.instance(context);
@@ -144,14 +141,13 @@
 
         boolean verboseDeprecated = lint.isEnabled(LintCategory.DEPRECATION);
         boolean verboseUnchecked = lint.isEnabled(LintCategory.UNCHECKED);
-        boolean verboseSunApi = lint.isEnabled(LintCategory.SUNAPI);
         boolean enforceMandatoryWarnings = true;
 
         deprecationHandler = new MandatoryWarningHandler(log, verboseDeprecated,
                 enforceMandatoryWarnings, "deprecated", LintCategory.DEPRECATION);
         uncheckedHandler = new MandatoryWarningHandler(log, verboseUnchecked,
                 enforceMandatoryWarnings, "unchecked", LintCategory.UNCHECKED);
-        sunApiHandler = new MandatoryWarningHandler(log, verboseSunApi,
+        sunApiHandler = new MandatoryWarningHandler(log, false,
                 enforceMandatoryWarnings, "sunapi", null);
 
         deferredLintHandler = DeferredLintHandler.instance(context);
@@ -177,10 +173,6 @@
      */
     boolean allowDiamondWithAnonymousClassCreation;
 
-    /** Switch: -complexinference option set?
-     */
-    boolean complexInference;
-
     /** Character for synthetic names
      */
     char syntheticNameChar;
@@ -248,15 +240,6 @@
             log.warning(LintCategory.VARARGS, pos, key, args);
     }
 
-    /** Warn about using proprietary API.
-     *  @param pos        Position to be used for error reporting.
-     *  @param msg        A string describing the problem.
-     */
-    public void warnSunApi(DiagnosticPosition pos, String msg, Object... args) {
-        if (!lint.isSuppressed(LintCategory.SUNAPI))
-            sunApiHandler.report(pos, msg, args);
-    }
-
     public void warnStatic(DiagnosticPosition pos, String msg, Object... args) {
         if (lint.isEnabled(LintCategory.STATIC))
             log.warning(LintCategory.STATIC, pos, msg, args);
@@ -3226,13 +3209,8 @@
 
     void checkSunAPI(final DiagnosticPosition pos, final Symbol s) {
         if ((s.flags() & PROPRIETARY) != 0) {
-            deferredLintHandler.report(new DeferredLintHandler.LintLogger() {
-                public void report() {
-                    if (enableSunApiLintControl)
-                      warnSunApi(pos, "sun.proprietary", s);
-                    else
-                      log.mandatoryWarning(pos, "sun.proprietary", s);
-                }
+            deferredLintHandler.report(() -> {
+                log.mandatoryWarning(pos, "sun.proprietary", s);
             });
         }
     }
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Resolve.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Resolve.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, 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
@@ -94,7 +94,6 @@
     public final boolean allowMethodHandles;
     public final boolean allowFunctionalInterfaceMostSpecific;
     public final boolean checkVarargsAccessAfterResolution;
-    private final boolean debugResolve;
     private final boolean compactMethodDiags;
     final EnumSet<VerboseResolutionMode> verboseResolutionMode;
 
@@ -120,7 +119,6 @@
         diags = JCDiagnostic.Factory.instance(context);
         Source source = Source.instance(context);
         Options options = Options.instance(context);
-        debugResolve = options.isSet("debugresolve");
         compactMethodDiags = options.isSet(Option.XDIAGS, "compact") ||
                 options.isUnset(Option.XDIAGS) && options.isUnset("rawDiagnostics");
         verboseResolutionMode = VerboseResolutionMode.getVerboseResolutionMode(options);
@@ -3897,8 +3895,6 @@
             super(HIDDEN, sym, "access error");
             this.env = env;
             this.site = site;
-            if (debugResolve)
-                log.error("proc.messager", sym + " @ " + site + " is inaccessible.");
         }
 
         @Override
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/BaseFileManager.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/BaseFileManager.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2016, 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
@@ -55,8 +55,6 @@
 
 import com.sun.tools.javac.code.Lint;
 import com.sun.tools.javac.code.Source;
-import com.sun.tools.javac.file.FSInfo;
-import com.sun.tools.javac.file.Locations;
 import com.sun.tools.javac.main.Option;
 import com.sun.tools.javac.main.OptionHelper;
 import com.sun.tools.javac.main.OptionHelper.GrumpyHelper;
@@ -88,6 +86,27 @@
         options = Options.instance(context);
         classLoaderClass = options.get("procloader");
         locations.update(log, Lint.instance(context), FSInfo.instance(context));
+
+        // Setting this option is an indication that close() should defer actually closing
+        // the file manager until after a specified period of inactivity.
+        // This is to accomodate clients which save references to Symbols created for use
+        // within doclets or annotation processors, and which then attempt to use those
+        // references after the tool exits, having closed any internally managed file manager.
+        // Ideally, such clients should run the tool via the javax.tools API, providing their
+        // own file manager, which can be closed by the client when all use of that file
+        // manager is complete.
+        // If the option has a numeric value, it will be interpreted as the duration,
+        // in seconds, of the period of inactivity to wait for, before the file manager
+        // is actually closed.
+        // See also deferredClose().
+        String s = options.get("fileManager.deferClose");
+        if (s != null) {
+            try {
+                deferredCloseTimeout = (int) (Float.parseFloat(s) * 1000);
+            } catch (NumberFormatException e) {
+                deferredCloseTimeout = 60 * 1000;  // default: one minute, in millis
+            }
+        }
     }
 
     protected Locations createLocations() {
@@ -116,6 +135,42 @@
      */
     public boolean autoClose;
 
+    /**
+     * Wait for a period of inactivity before calling close().
+     * The length of the period of inactivity is given by {@code deferredCloseTimeout}
+     */
+    protected void deferredClose() {
+        Thread t = new Thread(getClass().getName() + " DeferredClose") {
+            @Override
+            public void run() {
+                try {
+                    synchronized (BaseFileManager.this) {
+                        long now = System.currentTimeMillis();
+                        while (now < lastUsedTime + deferredCloseTimeout) {
+                            BaseFileManager.this.wait(lastUsedTime + deferredCloseTimeout - now);
+                            now = System.currentTimeMillis();
+                        }
+                        deferredCloseTimeout = 0;
+                        close();
+                    }
+                } catch (InterruptedException e) {
+                } catch (IOException e) {
+                }
+            }
+        };
+        t.setDaemon(true);
+        t.start();
+    }
+
+    synchronized void updateLastUsedTime() {
+        if (deferredCloseTimeout > 0) { // avoid updating the time unnecessarily
+            lastUsedTime = System.currentTimeMillis();
+        }
+    }
+
+    private long lastUsedTime = System.currentTimeMillis();
+    protected long deferredCloseTimeout = 0;
+
     protected Source getSource() {
         String sourceName = options.get(Option.SOURCE);
         Source source = null;
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/JavacFileManager.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/JavacFileManager.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2016, 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
@@ -525,8 +525,16 @@
      */
     @Override @DefinedBy(Api.COMPILER)
     public void close() throws IOException {
-        for (FileSystem fs: fileSystems.values())
+        if (deferredCloseTimeout > 0) {
+            deferredClose();
+            return;
+        }
+
+        for (FileSystem fs: fileSystems.values()) {
             fs.close();
+        }
+        fileSystems.clear();
+        contentCache.clear();
     }
 
     @Override @DefinedBy(Api.COMPILER)
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/PathFileObject.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/PathFileObject.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2016, 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
@@ -432,11 +432,13 @@
 
     @Override @DefinedBy(Api.COMPILER)
     public InputStream openInputStream() throws IOException {
+        fileManager.updateLastUsedTime();
         return Files.newInputStream(path);
     }
 
     @Override @DefinedBy(Api.COMPILER)
     public OutputStream openOutputStream() throws IOException {
+        fileManager.updateLastUsedTime();
         fileManager.flushCache(this);
         ensureParentDirectoriesExist();
         return Files.newOutputStream(path);
@@ -471,6 +473,7 @@
 
     @Override @DefinedBy(Api.COMPILER)
     public Writer openWriter() throws IOException {
+        fileManager.updateLastUsedTime();
         fileManager.flushCache(this);
         ensureParentDirectoriesExist();
         return new OutputStreamWriter(Files.newOutputStream(path), fileManager.getEncodingName());
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/ClassReader.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/ClassReader.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, 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
@@ -91,11 +91,6 @@
      */
     boolean verbose;
 
-    /** Switch: check class file for correct minor version, unrecognized
-     *  attributes.
-     */
-    boolean checkClassFile;
-
     /** Switch: read constant pool and code sections. This switch is initially
      *  set to false but can be turned on from outside.
      */
@@ -230,7 +225,6 @@
 
         Options options = Options.instance(context);
         verbose         = options.isSet(VERBOSE);
-        checkClassFile  = options.isSet("-checkclassfile");
 
         Source source = Source.instance(context);
         allowSimplifiedVarargs = source.allowSimplifiedVarargs();
@@ -1148,15 +1142,6 @@
             attributeReaders.put(r.name, r);
     }
 
-    /** Report unrecognized attribute.
-     */
-    void unrecognized(Name attrName) {
-        if (checkClassFile)
-            printCCF("ccf.unrecognized.attribute", attrName);
-    }
-
-
-
     protected void readEnclosingMethodAttr(Symbol sym) {
         // sym is a nested class with an "Enclosing Method" attribute
         // remove sym from it's current owners scope and place it in
@@ -1279,7 +1264,6 @@
             if (r != null && r.accepts(kind))
                 r.read(sym, attrLen);
             else  {
-                unrecognized(attrName);
                 bp = bp + attrLen;
             }
         }
@@ -2315,8 +2299,7 @@
         int maxMinor = Version.MAX().minor;
         if (majorVersion > maxMajor ||
             majorVersion * 1000 + minorVersion <
-            Version.MIN().major * 1000 + Version.MIN().minor)
-        {
+            Version.MIN().major * 1000 + Version.MIN().minor) {
             if (majorVersion == (maxMajor + 1))
                 log.warning("big.major.version",
                             currentClassFile,
@@ -2329,13 +2312,7 @@
                                    Integer.toString(maxMajor),
                                    Integer.toString(maxMinor));
         }
-        else if (checkClassFile &&
-                 majorVersion == maxMajor &&
-                 minorVersion > maxMinor)
-        {
-            printCCF("found.later.version",
-                     Integer.toString(minorVersion));
-        }
+
         indexPool();
         if (signatureBuffer.length < bp) {
             int ns = Integer.highestOneBit(bp) << 1;
@@ -2455,14 +2432,6 @@
         return flags & ~ACC_SUPER; // SUPER and SYNCHRONIZED bits overloaded
     }
 
-    /** Output for "-checkclassfile" option.
-     *  @param key The key to look up the correct internationalized string.
-     *  @param arg An argument for substitution into the output string.
-     */
-    private void printCCF(String key, Object arg) {
-        log.printLines(key, arg);
-    }
-
     /**
      * A subclass of JavaFileObject for the sourcefile attribute found in a classfile.
      * The attribute is only the last component of the original filename, so is unlikely
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/main/JavaCompiler.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/main/JavaCompiler.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, 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
@@ -373,7 +373,6 @@
                 throw new Abort();
         }
         source = Source.instance(context);
-        Target target = Target.instance(context);
         attr = Attr.instance(context);
         chk = Check.instance(context);
         gen = Gen.instance(context);
@@ -393,7 +392,6 @@
         stubOutput    = options.isSet("-stubs");
         relax         = options.isSet("-relax");
         printFlat     = options.isSet("-printflat");
-        attrParseOnly = options.isSet("-attrparseonly");
         encoding      = options.get(ENCODING);
         lineDebugInfo = options.isUnset(G_CUSTOM) ||
                         options.isSet(G_CUSTOM, "lines");
@@ -405,7 +403,8 @@
 
         verboseCompilePolicy = options.isSet("verboseCompilePolicy");
 
-        if (attrParseOnly)
+        if (options.isSet("shouldStopPolicy") &&
+            CompileState.valueOf(options.get("shouldStopPolicy")) == CompileState.ATTR)
             compilePolicy = CompilePolicy.ATTR_ONLY;
         else
             compilePolicy = CompilePolicy.decode(options.get("compilePolicy"));
@@ -452,10 +451,6 @@
      */
     public boolean stubOutput;
 
-    /** Generate attributed parse tree only.
-     */
-    public boolean attrParseOnly;
-
     /** Switch: relax some constraints for producing the jsr14 prototype.
      */
     boolean relax;
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/processing/JavacProcessingEnvironment.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/processing/JavacProcessingEnvironment.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2016, 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
@@ -766,10 +766,6 @@
 
         // Run contributing processors that haven't run yet
         psi.runContributingProcs(renv);
-
-        // Debugging
-        if (options.isSet("displayFilerState"))
-            filer.displayState();
     }
 
     /**
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties	Wed Jul 05 21:20:39 2017 +0200
@@ -1,6 +1,6 @@
 
 #
-# Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1999, 2016, 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
@@ -1284,24 +1284,6 @@
 compiler.note.unchecked.plural.additional=\
     Some input files additionally use unchecked or unsafe operations.
 
-# 0: file name
-compiler.note.sunapi.filename=\
-    {0} uses internal proprietary API that may be removed in a future release.
-
-compiler.note.sunapi.plural=\
-    Some input files use internal proprietary API that may be removed in a future release.
-
-# The following string may appear after one of the above sunapi messages.
-compiler.note.sunapi.recompile=\
-    Recompile with -Xlint:sunapi for details.
-
-# 0: file name
-compiler.note.sunapi.filename.additional=\
-    {0} uses additional internal proprietary API that may be removed in a future release.
-
-compiler.note.sunapi.plural.additional=\
-    Some input files additionally use internal proprietary API that may be removed in a future release.
-
 # Notes related to annotation processing
 
 # Print a client-generated note; assumed to be localized, no translation required
@@ -1375,13 +1357,6 @@
 compiler.misc.verbose.classpath=\
     [search path for class files: {0}]
 
-## extra output when using -checkclassfile (code/ClassReader)
-compiler.misc.ccf.found.later.version=\
-    class file has later version than expected: {0}
-
-compiler.misc.ccf.unrecognized.attribute=\
-    unrecognized attribute: {0}
-
 ## extra output when using -prompt (util/Log)
 compiler.misc.resume.abort=\
     R)esume, A)bort>
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1999, 2016, 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
@@ -208,9 +208,6 @@
 javac.opt.Xlint.desc.static=\
     Warn about accessing a static member using an instance.
 
-javac.opt.Xlint.desc.sunapi=\
-    Warn about proprietary API that may be removed in a future release.
-
 javac.opt.Xlint.desc.try=\
     Warn about issues relating to use of try blocks (i.e. try-with-resources).
 
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/sjavac/options/Options.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/sjavac/options/Options.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2016, 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
@@ -34,6 +34,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.HashSet;
+import java.util.StringJoiner;
 
 import com.sun.tools.sjavac.Transformer;
 import com.sun.tools.sjavac.Util;
@@ -225,10 +226,7 @@
             }
 
             String getResult() {
-                String result = "";
-                for (String s : args)
-                    result += s + " ";
-                return result.trim();
+                return String.join(" ", args);
             }
 
             public void addAll(Collection<String> toAdd) {
@@ -337,10 +335,11 @@
     // Helper method to join a list of source locations separated by
     // File.pathSeparator
     private static String concatenateSourceLocations(List<SourceLocation> locs) {
-        String s = "";
-        for (SourceLocation loc : locs)
-            s += (s.isEmpty() ? "" : java.io.File.pathSeparator) + loc.getPath();
-        return s;
+        StringJoiner joiner = new StringJoiner(java.io.File.pathSeparator);
+        for (SourceLocation loc : locs) {
+            joiner.add(loc.getPath().toString());
+        }
+        return joiner.toString();
     }
 
     // OptionHelper that records the traversed options in this Options instance.
--- a/langtools/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/ExternalEditor.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/ExternalEditor.java	Wed Jul 05 21:20:39 2017 +0200
@@ -33,6 +33,7 @@
 import java.nio.file.Path;
 import java.nio.file.WatchKey;
 import java.nio.file.WatchService;
+import java.util.Arrays;
 import java.util.function.Consumer;
 import java.util.stream.Collectors;
 import static java.nio.file.StandardWatchEventKinds.ENTRY_CREATE;
@@ -58,7 +59,7 @@
         this.input = input;
     }
 
-    private void edit(String cmd, String initialText) {
+    private void edit(String[] cmd, String initialText) {
         try {
             setupWatch(initialText);
             launch(cmd);
@@ -106,8 +107,10 @@
         watchedThread.start();
     }
 
-    private void launch(String cmd) throws IOException {
-        ProcessBuilder pb = new ProcessBuilder(cmd, tmpfile.toString());
+    private void launch(String[] cmd) throws IOException {
+        String[] params = Arrays.copyOf(cmd, cmd.length + 1);
+        params[cmd.length] = tmpfile.toString();
+        ProcessBuilder pb = new ProcessBuilder(params);
         pb = pb.inheritIO();
 
         try {
@@ -139,7 +142,7 @@
         }
     }
 
-    static void edit(String cmd, Consumer<String> errorHandler, String initialText,
+    static void edit(String[] cmd, Consumer<String> errorHandler, String initialText,
             Consumer<String> saveHandler, IOContext input) {
         ExternalEditor ed = new ExternalEditor(errorHandler,  saveHandler, input);
         ed.edit(cmd, initialText);
--- a/langtools/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/JShellTool.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/JShellTool.java	Wed Jul 05 21:20:39 2017 +0200
@@ -35,6 +35,7 @@
 import java.io.InputStream;
 import java.io.PrintStream;
 import java.io.Reader;
+import java.io.StreamTokenizer;
 import java.io.StringReader;
 import java.nio.charset.Charset;
 import java.nio.file.AccessDeniedException;
@@ -152,7 +153,7 @@
     private Feedback feedback = Feedback.Default;
     private String cmdlineClasspath = null;
     private String cmdlineStartup = null;
-    private String editor = null;
+    private String[] editor = null;
 
     // Commands and snippets which should be replayed
     private List<String> replayableHistory;
@@ -537,7 +538,7 @@
             arg = cmd.substring(idx + 1).trim();
             cmd = cmd.substring(0, idx);
         }
-        Command[] candidates = findCommand(cmd, c -> c.kind != CommandKind.HELP_ONLY);
+        Command[] candidates = findCommand(cmd, c -> c.kind.isRealCommand);
         if (candidates.length == 0) {
             if (!rerunHistoryEntryById(cmd.substring(1))) {
                 hard("No such command or snippet id: %s", cmd);
@@ -579,18 +580,33 @@
         public final String command;
         public final String params;
         public final String description;
+        public final String help;
         public final Function<String,Boolean> run;
         public final CompletionProvider completions;
         public final CommandKind kind;
 
-        public Command(String command, String params, String description, Function<String,Boolean> run, CompletionProvider completions) {
-            this(command, params, description, run, completions, CommandKind.NORMAL);
+        // NORMAL Commands
+        public Command(String command, String params, String description, String help,
+                Function<String,Boolean> run, CompletionProvider completions) {
+            this(command, params, description, help,
+                    run, completions, CommandKind.NORMAL);
         }
 
-        public Command(String command, String params, String description, Function<String,Boolean> run, CompletionProvider completions, CommandKind kind) {
+        // Documentation pseudo-commands
+        public Command(String command, String description, String help,
+                CommandKind kind) {
+            this(command, null, description, help,
+                    arg -> { throw new IllegalStateException(); },
+                    EMPTY_COMPLETION_PROVIDER,
+                    kind);
+        }
+
+        public Command(String command, String params, String description, String help,
+                Function<String,Boolean> run, CompletionProvider completions, CommandKind kind) {
             this.command = command;
             this.params = params;
             this.description = description;
+            this.help = help;
             this.run = run;
             this.completions = completions;
             this.kind = kind;
@@ -603,10 +619,59 @@
     }
 
     enum CommandKind {
-        NORMAL,
-        REPLAY,
-        HIDDEN,
-        HELP_ONLY;
+        NORMAL(true, true, true),
+        REPLAY(true, true, true),
+        HIDDEN(true, false, false),
+        HELP_ONLY(false, true, false),
+        HELP_SUBJECT(false, false, false);
+
+        final boolean isRealCommand;
+        final boolean showInHelp;
+        final boolean shouldSuggestCompletions;
+        private CommandKind(boolean isRealCommand, boolean showInHelp, boolean shouldSuggestCompletions) {
+            this.isRealCommand = isRealCommand;
+            this.showInHelp = showInHelp;
+            this.shouldSuggestCompletions = shouldSuggestCompletions;
+        }
+    }
+
+    class ArgTokenizer extends StreamTokenizer {
+
+        ArgTokenizer(String arg) {
+            super(new StringReader(arg));
+            resetSyntax();
+            wordChars(0x00, 0xFF);
+            quoteChar('"');
+            quoteChar('\'');
+
+            whitespaceChars(0x09, 0x0D);
+            whitespaceChars(0x1C, 0x20);
+            whitespaceChars(0x85, 0x85);
+            whitespaceChars(0xA0, 0xA0);
+            whitespaceChars(0x1680, 0x1680);
+            whitespaceChars(0x180E, 0x180E);
+            whitespaceChars(0x2000, 0x200A);
+            whitespaceChars(0x202F, 0x202F);
+            whitespaceChars(0x205F, 0x205F);
+            whitespaceChars(0x3000, 0x3000);
+        }
+
+        String next() {
+            try {
+                nextToken();
+            } catch (Throwable t) {
+                return null;
+            }
+            return sval;
+        }
+
+        String val() {
+            return sval;
+        }
+
+        boolean isQuoted() {
+            return ttype == '\'' || ttype == '"';
+        }
     }
 
     static final class FixedCompletionProvider implements CompletionProvider {
@@ -722,86 +787,215 @@
     // Table of commands -- with command forms, argument kinds, help message, implementation, ...
 
     {
-        registerCommand(new Command("/list", "[all|start|history|<name or id>]", "list the source you have typed",
-                                    arg -> cmdList(arg),
-                                    editKeywordCompletion()));
-        registerCommand(new Command("/seteditor", "<executable>", "set the external editor command to use",
-                                    arg -> cmdSetEditor(arg),
-                                    EMPTY_COMPLETION_PROVIDER));
+        registerCommand(new Command("/list", "[all|start|<name or id>]", "list the source you have typed",
+                "Show the source of snippets, prefaced with the snippet id.\n\n" +
+                "/list\n" +
+                "  -- List the currently active snippets of code that you typed or read with /open\n" +
+                "/list start\n" +
+                "  -- List the automatically evaluated start-up snippets\n" +
+                "/list all\n" +
+                "  -- List all snippets including failed, overwritten, dropped, and start-up\n" +
+                "/list <name>\n" +
+                "  -- List snippets with the specified name (preference for active snippets)\n" +
+                "/list <id>\n" +
+                "  -- List the snippet with the specified snippet id\n",
+                arg -> cmdList(arg),
+                editKeywordCompletion()));
+        registerCommand(new Command("/seteditor", "<command>", "set the external editor command to use",
+                "Specify the command to launch for the /edit command.\n" +
+                "The command is an operating system dependent string.\n" +
+                "The command may include space-separated arguments (such as flags).\n" +
+                "When /edit is used, temporary file to edit will be appended as the last argument.\n",
+                arg -> cmdSetEditor(arg),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/edit", "<name or id>", "edit a source entry referenced by name or id",
-                                    arg -> cmdEdit(arg),
-                                    editCompletion()));
+                "Edit a snippet or snippets of source in an external editor.\n" +
+                "The editor to use is set with /seteditor.\n" +
+                "If no editor has been set, a simple editor will be launched.\n\n" +
+                "/edit <name>\n" +
+                "  -- Edit the snippet or snippets with the specified name (preference for active snippets)\n" +
+                "/edit <id>\n" +
+                "  -- Edit the snippet with the specified snippet id\n" +
+                "/edit\n" +
+                "  -- Edit the currently active snippets of code that you typed or read with /open\n",
+                arg -> cmdEdit(arg),
+                editCompletion()));
         registerCommand(new Command("/drop", "<name or id>", "delete a source entry referenced by name or id",
-                                    arg -> cmdDrop(arg),
-                                    editCompletion(),
-                                    CommandKind.REPLAY));
-        registerCommand(new Command("/save", "[all|history|start] <file>", "save: <none> - current source;\n" +
-                                                                           "      all - source including overwritten, failed, and start-up code;\n" +
-                                                                           "      history - editing history;\n" +
-                                                                           "      start - default start-up definitions",
-                                    arg -> cmdSave(arg),
-                                    saveCompletion()));
+                "Drop a snippet -- making it inactive.\n\n" +
+                "/drop <name>\n" +
+                "  -- Drop the snippet with the specified name\n" +
+                "/drop <id>\n" +
+                "  -- Drop the snippet with the specified snippet id\n",
+                arg -> cmdDrop(arg),
+                editCompletion(),
+                CommandKind.REPLAY));
+        registerCommand(new Command("/save", "[all|history|start] <file>", "Save snippet source to a file.",
+                "Save the specified snippets and/or commands to the specified file.\n\n" +
+                "/save <file>\n" +
+                "  -- Save the source of current active snippets to the file\n" +
+                "/save all <file>\n" +
+                "  -- Save the source of all snippets to the file\n" +
+                "     Includes source including overwritten, failed, and start-up code\n" +
+                "/save history <file>\n" +
+                "  -- Save the sequential history of all commands and snippets entered since jshell was launched\n" +
+                "/save start <file>\n" +
+                "  -- Save the default start-up definitions to the file\n",
+                arg -> cmdSave(arg),
+                saveCompletion()));
         registerCommand(new Command("/open", "<file>", "open a file as source input",
-                                    arg -> cmdOpen(arg),
-                                    FILE_COMPLETION_PROVIDER));
+                "Open a file and read its contents as snippets and commands.\n\n" +
+                "/open <file>\n" +
+                "  -- Read the specified file as jshell input.\n",
+                arg -> cmdOpen(arg),
+                FILE_COMPLETION_PROVIDER));
         registerCommand(new Command("/vars", null, "list the declared variables and their values",
-                                    arg -> cmdVars(),
-                                    EMPTY_COMPLETION_PROVIDER));
+                "List the type, name, and value of the current active jshell variables.\n",
+                arg -> cmdVars(),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/methods", null, "list the declared methods and their signatures",
-                                    arg -> cmdMethods(),
-                                    EMPTY_COMPLETION_PROVIDER));
+                "List the name, parameter types, and return type of the current active jshell methods.\n",
+                arg -> cmdMethods(),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/classes", null, "list the declared classes",
-                                    arg -> cmdClasses(),
-                                    EMPTY_COMPLETION_PROVIDER));
+                "List the current active jshell classes, interfaces, and enums.\n",
+                arg -> cmdClasses(),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/imports", null, "list the imported items",
-                                    arg -> cmdImports(),
-                                    EMPTY_COMPLETION_PROVIDER));
-        registerCommand(new Command("/exit", null, "exit the REPL",
-                                    arg -> cmdExit(),
-                                    EMPTY_COMPLETION_PROVIDER));
-        registerCommand(new Command("/reset", null, "reset everything in the REPL",
-                                    arg -> cmdReset(),
-                                    EMPTY_COMPLETION_PROVIDER));
+                "List the current active jshell imports.\n",
+                arg -> cmdImports(),
+                EMPTY_COMPLETION_PROVIDER));
+        registerCommand(new Command("/exit", null, "exit jshell",
+                "Leave the jshell tool.  No work is saved.\n" +
+                "Save any work before using this command\n",
+                arg -> cmdExit(),
+                EMPTY_COMPLETION_PROVIDER));
+        registerCommand(new Command("/reset", null, "reset jshell",
+                "Reset the jshell tool code and execution state:\n" +
+                "   * All entered code is lost.\n" +
+                "   * Start-up code is re-executed.\n" +
+                "   * The execution state is restarted.\n" +
+                "   * The classpath is cleared.\n" +
+                "Tool settings are maintained: /feedback, /prompt, and /seteditor\n" +
+                "Save any work before using this command\n",
+                arg -> cmdReset(),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/reload", "[restore] [quiet]", "reset and replay relevant history -- current or previous (restore)",
-                                    arg -> cmdReload(arg),
-                                    reloadCompletion()));
+                "Reset the jshell tool code and execution state then replay each\n" +
+                "jshell valid command and valid snippet in the order they were entered.\n\n" +
+                "/reload\n" +
+                "  -- Reset and replay the valid history since jshell was entered, or\n" +
+                "     a /reset, or /reload command was executed -- whichever is most\n" +
+                "     recent.\n" +
+                "/reload restore\n" +
+                "  -- Reset and replay the valid history between the previous and most\n" +
+                "     recent time that jshell was entered, or a /reset, or /reload\n" +
+                "     command was executed. This can thus be used to restore a previous\n" +
+                "     jshell tool sesson.\n" +
+                "/reload [restore] quiet\n" +
+                "  -- With the 'quiet' argument the replay is not shown.  Errors will display.\n",
+                arg -> cmdReload(arg),
+                reloadCompletion()));
         registerCommand(new Command("/feedback", "<level>", "feedback information: off, concise, normal, verbose, default, or ?",
-                                    arg -> cmdFeedback(arg),
-                                    new FixedCompletionProvider("off", "concise", "normal", "verbose", "default", "?")));
+                "Set the level of feedback describing the effect of commands and snippets.\n\n" +
+                "/feedback off\n" +
+                "  -- Give no feedback\n" +
+                "/feedback concise\n" +
+                "  -- Brief and generally symbolic feedback\n" +
+                "/feedback normal\n" +
+                "  -- Give a natural language description of the actions\n" +
+                "/feedback verbose\n" +
+                "  -- Like normal but with side-effects described\n" +
+                "/feedback default\n" +
+                "  -- Same as normal for user input, off for input from a file\n",
+                arg -> cmdFeedback(arg),
+                new FixedCompletionProvider("off", "concise", "normal", "verbose", "default", "?")));
         registerCommand(new Command("/prompt", null, "toggle display of a prompt",
-                                    arg -> cmdPrompt(),
-                                    EMPTY_COMPLETION_PROVIDER));
+                "Toggle between displaying an input prompt and not displaying a prompt.\n" +
+                "Particularly useful when pasting large amounts of text.\n",
+                arg -> cmdPrompt(),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/classpath", "<path>", "add a path to the classpath",
-                                    arg -> cmdClasspath(arg),
-                                    classPathCompletion(),
-                                    CommandKind.REPLAY));
+                "Append a additional path to the classpath.\n",
+                arg -> cmdClasspath(arg),
+                classPathCompletion(),
+                CommandKind.REPLAY));
         registerCommand(new Command("/history", null, "history of what you have typed",
-                                    arg -> cmdHistory(),
-                                    EMPTY_COMPLETION_PROVIDER));
+                "Display the history of snippet and command input since this jshell was launched.\n",
+                arg -> cmdHistory(),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/setstart", "<file>", "read file and set as the new start-up definitions",
-                                    arg -> cmdSetStart(arg),
-                                    FILE_COMPLETION_PROVIDER));
-        registerCommand(new Command("/debug", "", "toggle debugging of the REPL",
-                                    arg -> cmdDebug(arg),
-                                    EMPTY_COMPLETION_PROVIDER,
-                                    CommandKind.HIDDEN));
-        registerCommand(new Command("/help", "", "this help message",
-                                    arg -> cmdHelp(),
-                                    EMPTY_COMPLETION_PROVIDER));
-        registerCommand(new Command("/?", "", "this help message",
-                                    arg -> cmdHelp(),
-                                    EMPTY_COMPLETION_PROVIDER));
+                "The contents of the specified file become the default start-up snippets and commands.\n",
+                arg -> cmdSetStart(arg),
+                FILE_COMPLETION_PROVIDER));
+        registerCommand(new Command("/debug", null, "toggle debugging of the jshell",
+                "Display debugging information for the jshelll implementation.\n" +
+                "0: Debugging off\n" +
+                "r: Debugging on\n" +
+                "g: General debugging on\n" +
+                "f: File manager debugging on\n" +
+                "c': Completion analysis debugging on\n" +
+                "d': Dependency debugging on\n" +
+                "e': Event debugging on\n",
+                arg -> cmdDebug(arg),
+                EMPTY_COMPLETION_PROVIDER,
+                CommandKind.HIDDEN));
+        registerCommand(new Command("/help", "[<command>|<subject>]", "get information about jshell",
+                "Display information about jshell.\n" +
+                "/help\n" +
+                "  -- List the jshell commands and help subjects.\n" +
+                "/help <command>\n" +
+                "  -- Display information about the specified comand. The slash must be included.\n" +
+                "     Only the first few letters of the command are needed -- if more than one\n" +
+                "     each will be displayed.  Example:  /help /li\n" +
+                "/help <subject>\n" +
+                "  -- Display information about the specified help subject. Example: /help intro\n",
+                arg -> cmdHelp(arg),
+                EMPTY_COMPLETION_PROVIDER));
+        registerCommand(new Command("/?", "", "get information about jshell",
+                "Display information about jshell (abbreviation for /help).\n" +
+                "/?\n" +
+                "  -- Display list of commands and help subjects.\n" +
+                "/? <command>\n" +
+                "  -- Display information about the specified comand. The slash must be included.\n" +
+                "     Only the first few letters of the command are needed -- if more than one\n" +
+                "     match, each will be displayed.  Example:  /? /li\n" +
+                "/? <subject>\n" +
+                "  -- Display information about the specified help subject. Example: /? intro\n",
+                arg -> cmdHelp(arg),
+                EMPTY_COMPLETION_PROVIDER));
         registerCommand(new Command("/!", "", "re-run last snippet",
-                                    arg -> cmdUseHistoryEntry(-1),
-                                    EMPTY_COMPLETION_PROVIDER));
-        registerCommand(new Command("/<id>", "", "re-run snippet by id",
-                                    arg -> { throw new IllegalStateException(); },
-                                    EMPTY_COMPLETION_PROVIDER,
-                                    CommandKind.HELP_ONLY));
-        registerCommand(new Command("/-<n>", "", "re-run n-th previous snippet",
-                                    arg -> { throw new IllegalStateException(); },
-                                    EMPTY_COMPLETION_PROVIDER,
-                                    CommandKind.HELP_ONLY));
+                "Reevaluate the most recently entered snippet.\n",
+                arg -> cmdUseHistoryEntry(-1),
+                EMPTY_COMPLETION_PROVIDER));
+
+        // Documentation pseudo-commands
+
+        registerCommand(new Command("/<id>", "re-run snippet by id",
+                "",
+                CommandKind.HELP_ONLY));
+        registerCommand(new Command("/-<n>", "re-run n-th previous snippet",
+                "",
+                CommandKind.HELP_ONLY));
+        registerCommand(new Command("intro", "An introduction to the jshell tool",
+                "The jshell tool allows you to execute Java code, getting immediate results.\n" +
+                "You can enter a Java definition (variable, method, class, etc), like:  int x = 8\n" +
+                "or a Java expression, like:  x + x\n" +
+                "or a Java statement or import.\n" +
+                "These little chunks of Java code are called 'snippets'.\n\n" +
+                "There are also jshell commands that allow you to understand and\n" +
+                "control what you are doing, like:  /list\n\n" +
+                "For a list of commands: /help",
+                CommandKind.HELP_SUBJECT));
+        registerCommand(new Command("shortcuts", "Describe shortcuts",
+                "Supported shortcuts include:\n\n" +
+                "<tab>       -- After entering the first few letters of a Java identifier,\n" +
+                "               a jshell command, or, in some cases, a jshell command argument,\n" +
+                "               press the <tab> key to complete the input.\n" +
+                "               If there is more than one completion, show possible completions.\n" +
+                "Shift-<tab> -- After the name and open parenthesis of a method or constructor invocation,\n" +
+                "               hold the <shift> key and press the <tab> to see a synopsis of all\n" +
+                "               matching methods/constructors.\n",
+                CommandKind.HELP_SUBJECT));
     }
 
     public List<Suggestion> commandCompletionSuggestions(String code, int cursor, int[] anchor) {
@@ -813,7 +1007,7 @@
             result = commands.values()
                              .stream()
                              .distinct()
-                             .filter(cmd -> cmd.kind != CommandKind.HIDDEN && cmd.kind != CommandKind.HELP_ONLY)
+                             .filter(cmd -> cmd.kind.shouldSuggestCompletions)
                              .map(cmd -> cmd.command)
                              .filter(key -> key.startsWith(prefix))
                              .map(key -> new Suggestion(key + " ", false));
@@ -856,7 +1050,11 @@
             hard("/seteditor requires a path argument");
             return false;
         } else {
-            editor = arg;
+            List<String> ed = new ArrayList<>();
+            ArgTokenizer at = new ArgTokenizer(arg);
+            String n;
+            while ((n = at.next()) != null) ed.add(n);
+            editor = ed.toArray(new String[ed.size()]);
             fluff("Editor set to: %s", arg);
             return true;
         }
@@ -971,11 +1169,28 @@
         return true;
     }
 
-    boolean cmdHelp() {
+    boolean cmdHelp(String arg) {
+        if (!arg.isEmpty()) {
+            StringBuilder sb = new StringBuilder();
+            commands.values().stream()
+                    .filter(c -> c.command.startsWith(arg))
+                    .forEach(c -> {
+                        sb.append("\n");
+                        sb.append(c.command);
+                        sb.append("\n\n");
+                        sb.append(c.help);
+                        sb.append("\n");
+                    });
+            if (sb.length() > 0) {
+                cmdout.print(sb);
+                return true;
+            }
+            cmdout.printf("No commands or subjects start with the provided argument: %s\n\n", arg);
+        }
         int synopsisLen = 0;
         Map<String, String> synopsis2Description = new LinkedHashMap<>();
         for (Command cmd : new LinkedHashSet<>(commands.values())) {
-            if (cmd.kind == CommandKind.HIDDEN)
+            if (!cmd.kind.showInHelp)
                 continue;
             StringBuilder synopsis = new StringBuilder();
             synopsis.append(cmd.command);
@@ -994,9 +1209,13 @@
             cmdout.println(e.getValue().replace("\n", indentedNewLine));
         }
         cmdout.println();
-        cmdout.println("Supported shortcuts include:");
-        cmdout.println("<tab>       -- show possible completions for the current text");
-        cmdout.println("Shift-<tab> -- for current method or constructor invocation, show a synopsis of the method/constructor");
+        cmdout.println("For more information type '/help' followed by the name of command or a subject.");
+        cmdout.println("For example '/help /list' or '/help intro'.  Subjects:\n");
+        commands.values().stream()
+                .filter(c -> c.kind == CommandKind.HELP_SUBJECT)
+                .forEach(c -> {
+            cmdout.printf("%-12s -- %s\n", c.command, c.description);
+        });
         return true;
     }
 
@@ -1033,8 +1252,16 @@
         return null;
     }
 
+    private boolean inStartUp(Snippet sn) {
+        return mapSnippet.get(sn).space == startNamespace;
+    }
+
+    private boolean isActive(Snippet sn) {
+        return state.status(sn).isActive;
+    }
+
     private boolean mainActive(Snippet sn) {
-        return notInStartUp(sn) && state.status(sn).isActive;
+        return !inStartUp(sn) && isActive(sn);
     }
 
     private boolean matchingDeclaration(Snippet sn, String name) {
@@ -1054,6 +1281,10 @@
         if (allowAll && arg.equals("all")) {
             // all snippets including start-up, failed, and overwritten
             return snippets.stream();
+        } else if (allowAll && arg.equals("start")) {
+            // start-up snippets
+            return snippets.stream()
+                    .filter(this::inStartUp);
         } else if (arg.isEmpty()) {
             // Default is all active user snippets
             return snippets.stream()
@@ -1063,7 +1294,7 @@
                     nonEmptyStream(
                             () -> snippets.stream(),
                             // look for active user declarations matching the name
-                            sn -> mainActive(sn) && matchingDeclaration(sn, arg),
+                            sn -> isActive(sn) && matchingDeclaration(sn, arg),
                             // else, look for any declarations matching the name
                             sn -> matchingDeclaration(sn, arg),
                             // else, look for an id of this name
@@ -1839,10 +2070,6 @@
         return feedback;
     }
 
-    boolean notInStartUp(Snippet sn) {
-        return mapSnippet.get(sn).space != startNamespace;
-    }
-
     /** The current version number as a string.
      */
     static String version() {
--- a/langtools/test/Makefile	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/Makefile	Wed Jul 05 21:20:39 2017 +0200
@@ -278,7 +278,7 @@
 	@mkdir -p $(JTREG_OUTPUT_DIR)
 	JT_JAVA=$(JT_JAVA) $(JTREG) \
 	  -J-Xmx512m \
-	  -vmoption:-Xmx1024m \
+	  -vmoption:-Xmx768m \
 	  -a -ignore:quiet $(if $(JTREG_VERBOSE),-v:$(JTREG_VERBOSE)) \
           -r:$(JTREG_OUTPUT_DIR)/JTreport \
           -w:$(JTREG_OUTPUT_DIR)/JTwork \
--- a/langtools/test/jdk/jshell/ToolBasicTest.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/jdk/jshell/ToolBasicTest.java	Wed Jul 05 21:20:39 2017 +0200
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 8143037 8142447 8144095 8140265 8144906
+ * @bug 8143037 8142447 8144095 8140265 8144906 8146138 8147887 8147886
  * @requires os.family != "solaris"
  * @summary Tests for Basic tests for REPL tool
  * @library /tools/lib
@@ -306,19 +306,38 @@
         );
     }
 
-    public void testHelp() {
+    public void testHelpLength() {
         Consumer<String> testOutput = (s) -> {
             List<String> ss = Stream.of(s.split("\n"))
                     .filter(l -> !l.isEmpty())
                     .collect(Collectors.toList());
-            assertTrue(ss.size() >= 5, "Help does not print enough lines:\n" + s);
+            assertTrue(ss.size() >= 10, "Help does not print enough lines:\n" + s);
         };
         test(
                 (a) -> assertCommandCheckOutput(a, "/?", testOutput),
-                (a) -> assertCommandCheckOutput(a, "/help", testOutput)
+                (a) -> assertCommandCheckOutput(a, "/help", testOutput),
+                (a) -> assertCommandCheckOutput(a, "/help /list", testOutput)
         );
     }
 
+    public void testHelp() {
+        test(
+                (a) -> assertHelp(a, "/?", "/list", "/help", "/exit", "intro"),
+                (a) -> assertHelp(a, "/help", "/list", "/help", "/exit", "intro"),
+                (a) -> assertHelp(a, "/help short", "shortcuts", "<tab>"),
+                (a) -> assertHelp(a, "/? /li", "/list all", "snippets"),
+                (a) -> assertHelp(a, "/help /help", "/help <command>")
+        );
+    }
+
+    private void assertHelp(boolean a, String command, String... find) {
+        assertCommandCheckOutput(a, command, s -> {
+            for (String f : find) {
+                assertTrue(s.contains(f), "Expected output of " + command + " to contain: " + f);
+            }
+        });
+    }
+
     public void oneLineOfError() {
         test(
                 (a) -> assertCommand(a, "12+", null),
@@ -682,10 +701,12 @@
                 a -> assertVariable(a, "int", "aardvark"),
                 a -> assertCommandCheckOutput(a, "/list aardvark",
                         s -> assertTrue(s.contains("aardvark"))),
+                a -> assertCommandCheckOutput(a, "/list start",
+                        s -> checkLineToList(s, START_UP)),
                 a -> assertCommandCheckOutput(a, "/list all",
                         s -> checkLineToList(s, startVarList)),
-                a -> assertCommandCheckOutput(a, "/list history",
-                        s -> assertTrue(s.split("\n").length >= 4, s)),
+                a -> assertCommandCheckOutput(a, "/list printf",
+                        s -> assertTrue(s.contains("void printf"))),
                 a -> assertCommandCheckOutput(a, "/list " + arg,
                         s -> assertEquals(s, "|  No definition or id named " + arg +
                                 " found.  Try /list without arguments.\n"))
--- a/langtools/test/jdk/jshell/ToolReloadTest.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/jdk/jshell/ToolReloadTest.java	Wed Jul 05 21:20:39 2017 +0200
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 8081845
+ * @bug 8081845 8147898
  * @summary Tests for /reload in JShell tool
  * @modules jdk.compiler/com.sun.tools.javac.api
  *          jdk.compiler/com.sun.tools.javac.main
@@ -110,6 +110,23 @@
         );
     }
 
+    public void testReloadQuiet() {
+        test(false, new String[]{"-nostartup"},
+                a -> assertVariable(a, "int", "a"),
+                a -> dropVariable(a, "/dr 1", "int a = 0"),
+                a -> assertMethod(a, "int b() { return 0; }", "()I", "b"),
+                a -> dropMethod(a, "/drop b", "b ()I"),
+                a -> assertClass(a, "class A {}", "class", "A"),
+                a -> dropClass(a, "/dr A", "class A"),
+                a -> assertCommand(a, "/reload quiet",
+                        "|  Restarting and restoring state.\n"),
+                a -> assertCommandCheckOutput(a, "/vars", assertVariables()),
+                a -> assertCommandCheckOutput(a, "/methods", assertMethods()),
+                a -> assertCommandCheckOutput(a, "/classes", assertClasses()),
+                a -> assertCommandCheckOutput(a, "/imports", assertImports())
+        );
+    }
+
     public void testReloadRepeat() {
         test(false, new String[]{"-nostartup"},
                 (a) -> assertVariable(a, "int", "c", "7", "7"),
--- a/langtools/test/tools/javac/T6873845.java	Wed Jul 05 21:20:31 2017 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,87 +0,0 @@
-/*
- * @test /nodynamiccopyright/
- * @bug 6873845
- * @summary refine access to symbol file
- * @modules java.base/sun.misc
- *          jdk.compiler
- */
-
-import java.io.*;
-import java.util.*;
-
-import sun.misc.*;
-
-public class T6873845 {
-    public static void main(String... args) throws Exception {
-        new T6873845().run();
-    }
-
-    public void run() throws Exception {
-        String out = compile(Arrays.asList("-XDrawDiagnostics", "-X"));
-        if (out.contains("sunapi"))
-            throw new Exception("unexpected output for -X");
-
-        String warn1 = "T6873845.java:75:9: compiler.warn.sun.proprietary: sun.misc.Unsafe" + newline;
-        String warn2 = "T6873845.java:80:9: compiler.warn.sun.proprietary: sun.misc.Unsafe" + newline;
-        String note1 = "- compiler.note.sunapi.filename: T6873845.java" + newline;
-        String note2 = "- compiler.note.sunapi.recompile" + newline;
-
-        test(opts(),
-                warn1 + warn2 + "2 warnings" + newline);
-        test(opts("-XDenableSunApiLintControl"),
-                note1 + note2);
-        test(opts("-XDenableSunApiLintControl", "-XDsuppressNotes"),
-                "");
-        test(opts("-XDenableSunApiLintControl", "-Xlint:sunapi"),
-                warn1 + "1 warning" + newline);
-        test(opts("-XDenableSunApiLintControl", "-Xlint:all"),
-                warn1 + "1 warning" + newline);
-        test(opts("-XDenableSunApiLintControl", "-Xlint:all,-sunapi"),
-                note1 + note2);
-    }
-
-    List<String> opts(String... opts) {
-        return Arrays.asList(opts);
-    }
-
-    void test(List<String> opts, String expect) throws Exception {
-        List<String> args = new ArrayList<String>();
-        args.addAll(opts);
-        args.add("-d");
-        args.add(testClasses.getPath());
-        args.add(new File(testSrc, "T6873845.java").getPath());
-        compile(args); // to verify resource strings exist
-        args.add(0, "-XDrawDiagnostics");
-        String out = compile(args);
-        if (!out.equals(expect))
-            throw new Exception("unexpected output from compiler; expected: " + expect +
-                    "\n  found: " + out);
-    }
-
-    String compile(List<String> args) throws Exception{
-        StringWriter sw = new StringWriter();
-        PrintWriter pw = new PrintWriter(sw);
-        System.out.println("compile: " + args);
-        int rc = com.sun.tools.javac.Main.compile(args.toArray(new String[args.size()]), pw);
-        pw.close();
-        String out = sw.toString();
-        System.out.println(out);
-        if (rc != 0)
-            throw new Exception("compilation failed unexpectedly");
-        return out;
-    }
-
-    void m1() {
-        Unsafe.getUnsafe();
-    }
-
-    @SuppressWarnings("sunapi")
-    void m2() {
-        Unsafe.getUnsafe();
-    }
-
-    private File testSrc = new File(System.getProperty("test.src", "."));
-    private File testClasses = new File(System.getProperty("test.classes", "."));
-    private String newline = System.getProperty("line.separator");
-}
-
--- a/langtools/test/tools/javac/diags/CheckResourceKeys.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/diags/CheckResourceKeys.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2016, 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
@@ -182,7 +182,7 @@
      * have a significant recognizable substring to look for.
      */
     private boolean isMandatoryWarningString(String s) {
-        String[] bases = { "deprecated", "unchecked", "varargs", "sunapi" };
+        String[] bases = { "deprecated", "unchecked", "varargs" };
         String[] tails = { ".filename", ".filename.additional", ".plural", ".plural.additional", ".recompile" };
         for (String b: bases) {
             if (s.startsWith(b)) {
@@ -229,7 +229,6 @@
         "compiler.err.signature.doesnt.match.supertype",    // UNUSED
         "compiler.err.type.var.more.than.once",             // UNUSED
         "compiler.err.type.var.more.than.once.in.result",   // UNUSED
-        "compiler.misc.ccf.found.later.version",            // UNUSED
         "compiler.misc.non.denotable.type",                 // UNUSED
         "compiler.misc.unnamed.package",                    // should be required, CR 6964147
         "compiler.misc.verbose.retro",                      // UNUSED
@@ -289,6 +288,7 @@
             // -XD option names
             "process.packages",
             "ignore.symbol.file",
+            "fileManager.deferClose",
             // prefix/embedded strings
             "compiler.",
             "compiler.misc.",
--- a/langtools/test/tools/javac/diags/examples.not-yet.txt	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/diags/examples.not-yet.txt	Wed Jul 05 21:20:39 2017 +0200
@@ -49,8 +49,6 @@
 compiler.misc.bad.signature                             # bad class file
 compiler.misc.bad.type.annotation.value
 compiler.misc.base.membership                           # UNUSED
-compiler.misc.ccf.found.later.version
-compiler.misc.ccf.unrecognized.attribute
 compiler.misc.class.file.not.found                      # ClassReader
 compiler.misc.class.file.wrong.class
 compiler.misc.fatal.err.cant.locate.ctor                # Resolve, from Lower
--- a/langtools/test/tools/javac/diags/examples/SunApiFilename.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/diags/examples/SunApiFilename.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2016, 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
@@ -21,9 +21,7 @@
  * questions.
  */
 
-// key: compiler.note.sunapi.filename
-// key: compiler.note.sunapi.recompile
-// options: -XDenableSunApiLintControl
+// key: compiler.warn.sun.proprietary
 
 class SunApiFilename {
     sun.misc.Unsafe x;
--- a/langtools/test/tools/javac/diags/examples/SunApiFilenameAdditional.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/diags/examples/SunApiFilenameAdditional.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2016, 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
@@ -21,9 +21,7 @@
  * questions.
  */
 
-// key: compiler.note.sunapi.filename.additional
 // key: compiler.warn.sun.proprietary
-// options: -XDenableSunApiLintControl -Xlint:sunapi -Xmaxwarns 1
 
 class SunApiFilenameAdditional {
     sun.misc.Unsafe x1;
--- a/langtools/test/tools/javac/diags/examples/SunApiPlural/SunApiPlural.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/diags/examples/SunApiPlural/SunApiPlural.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2016, 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
@@ -21,9 +21,7 @@
  * questions.
  */
 
-// key: compiler.note.sunapi.plural
-// key: compiler.note.sunapi.recompile
-// options: -XDenableSunApiLintControl
+// key: compiler.warn.sun.proprietary
 
 class SunApiPlural {
     sun.misc.Unsafe x;
--- a/langtools/test/tools/javac/diags/examples/SunApiPluralAdditional/SunApiPluralAdditional.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/diags/examples/SunApiPluralAdditional/SunApiPluralAdditional.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2016, 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
@@ -21,9 +21,7 @@
  * questions.
  */
 
-// key: compiler.note.sunapi.plural.additional
 // key: compiler.warn.sun.proprietary
-// options: -XDenableSunApiLintControl -Xlint:sunapi -Xmaxwarns 1
 
 class SunApiPluralAdditional {
     sun.misc.Unsafe x;
--- a/langtools/test/tools/javac/lambda/Conditional01.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/lambda/Conditional01.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2016, 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
@@ -26,7 +26,7 @@
  * @bug 8003280
  * @summary Add lambda tests
  *  conditional and varargs
- * @compile -XDcomplexinference Conditional01.java
+ * @compile Conditional01.java
  */
 
 import java.util.*;
--- a/langtools/test/tools/javac/lambda/Conditional02.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/lambda/Conditional02.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2016, 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
@@ -26,7 +26,7 @@
  * @bug 8003280
  * @summary Add lambda tests
  *  inference and conditionals
- * @compile -XDcomplexinference Conditional02.java
+ * @compile Conditional02.java
  */
 
 class Conditional02 {
--- a/langtools/test/tools/javac/lambda/Conditional03.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/lambda/Conditional03.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2016, 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
@@ -26,7 +26,7 @@
  * @bug 8003280
  * @summary Add lambda tests
  *  conditionals and boxing
- * @compile -XDcomplexinference Conditional03.java
+ * @compile Conditional03.java
  */
 
 class Conditional03 {
--- a/langtools/test/tools/javac/lambda/TargetType27.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/lambda/TargetType27.java	Wed Jul 05 21:20:39 2017 +0200
@@ -4,7 +4,7 @@
  * @summary Add lambda tests
  *  complex case of cyclic type inference (lambda returned where inference var expected)
  * @compile/fail/ref=TargetType27.out -XDrawDiagnostics TargetType27.java
- * @compile/fail/ref=TargetType27.out -XDrawDiagnostics -XDcomplexinference TargetType27.java
+ * @compile/fail/ref=TargetType27.out -XDrawDiagnostics TargetType27.java
  */
 
 class TargetType27 {
--- a/langtools/test/tools/javac/lambda/TargetType34.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/javac/lambda/TargetType34.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2016, 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
@@ -26,7 +26,7 @@
  * @bug 8003280
  * @summary Add lambda tests
  *  spurious resolution diagnostics when diamond constructor contains poly expression
- * @compile -XDcomplexinference TargetType34.java
+ * @compile TargetType34.java
  */
 
 class TargetType34<X> {
--- a/langtools/test/tools/javac/warnings/6594914/T6594914b.java	Wed Jul 05 21:20:31 2017 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,32 +0,0 @@
-/**
- * @test /nodynamiccopyright/
- * @bug 6594914
- * @summary \\@SuppressWarnings("deprecation") does not not work for the type of a variable
- * @modules java.base/sun.security.x509
- * @compile/ref=T6594914b.out -XDenableSunApiLintControl -XDrawDiagnostics -Xlint:sunapi T6594914b.java
- */
-
-
-class T6747671b {
-
-    sun.security.x509.X509CertInfo a1; //warn
-
-    @SuppressWarnings("sunapi")
-    sun.security.x509.X509CertInfo a2;
-
-    <X extends sun.security.x509.X509CertInfo>
-    sun.security.x509.X509CertInfo m1(sun.security.x509.X509CertInfo a)
-            throws sun.security.x509.CertException { return null; } //warn
-
-    @SuppressWarnings("sunapi")
-    <X extends sun.security.x509.X509CertInfo>
-    sun.security.x509.X509CertInfo m2(sun.security.x509.X509CertInfo a)
-            throws sun.security.x509.CertException { return null; }
-
-    void test() {
-        sun.security.x509.X509CertInfo a1; //warn
-
-        @SuppressWarnings("sunapi")
-        sun.security.x509.X509CertInfo a2;
-    }
-}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/tools/javadoc/8147801/T8147801.java	Wed Jul 05 21:20:39 2017 +0200
@@ -0,0 +1,160 @@
+/*
+ * Copyright (c) 2016, 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 8147801
+ * @summary java.nio.file.ClosedFileSystemException when using Javadoc API's in JDK9
+ * @modules jdk.javadoc/com.sun.tools.javadoc
+ * @library jarsrc
+ * @build lib.* p.*
+ * @run main T8147801
+ */
+
+import java.io.IOException;
+import java.nio.file.ClosedFileSystemException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.jar.JarEntry;
+import java.util.jar.JarOutputStream;
+
+import com.sun.javadoc.ClassDoc;
+import com.sun.javadoc.FieldDoc;
+import com.sun.javadoc.RootDoc;
+
+/*
+ * This test verifies the use of the hidden fileManager.deferClose
+ * option, to work around the limitation that javadoc objects
+ * (like RootDoc and related types) should cannot normally be used
+ * after javadoc exits, closing its file manager (if it opened it.)
+ *
+ * The test runs javadoc on a chain of classes, 1 in source form,
+ * and 2 in a jar file. javadoc/javac will "complete" classes found
+ * in source, but will eagerly "classes" in class form.
+ * The chain is p/Test.java -> lib/Lib1.class -> lib/Lib2.class.
+ * After javadoc exits, the classes are examined, to finally force
+ * the classes to be completed, possibly causing javac to try and access
+ * references into a .jar file system which has now been closed.
+ *
+ * The test runs two test cases -- one without the workaround option,
+ * to test the validity of the test case, and one with the workaround
+ * option, to test that it works as expected.
+ */
+public class T8147801 {
+    public static void main(String... args) throws Exception {
+        new T8147801().run();
+    }
+
+    void run() throws Exception {
+        initJar();
+        test(false);
+        test(true);
+        if (errors > 0) {
+            throw new Exception(errors + " errors occurred");
+        }
+    }
+
+    void test(boolean withOption) {
+        System.err.println("Testing " + (withOption ? "with" : "without") + " option");
+        try {
+            RootDoc root = getRootDoc(withOption);
+            for (ClassDoc cd: root.specifiedClasses()) {
+                dump("", cd);
+            }
+            if (!withOption) {
+                error("expected option did not occur");
+            }
+        } catch (ClosedFileSystemException e) {
+            if (withOption) {
+                error("Unexpected exception: " + e);
+            } else {
+                System.err.println("Exception received as expected: " + e);
+            }
+        }
+        System.err.println();
+    }
+
+    RootDoc getRootDoc(boolean withOption) {
+        List<String> opts = new ArrayList<>();
+        if (withOption)
+            opts.add("-XDfileManager.deferClose=10");
+        opts.add("-doclet");
+        opts.add(getClass().getName());
+        opts.add("-classpath");
+        opts.add(jarPath.toString());
+        opts.add(Paths.get(System.getProperty("test.src"), "p", "Test.java").toString());
+        System.err.println("javadoc opts: " + opts);
+        int rc = com.sun.tools.javadoc.Main.execute(
+                "javadoc",
+                // by specifying our own class loader, we get the same Class instance as this
+                getClass().getClassLoader(),
+                opts.toArray(new String[opts.size()]));
+        if (rc != 0) {
+            error("unexpected exit from javadoc or doclet: " + rc);
+        }
+        return cachedRoot;
+    }
+
+    void dump(String prefix, ClassDoc cd) {
+        System.err.println(prefix + "class: " + cd);
+        for (FieldDoc fd: cd.fields()) {
+            System.err.println(fd);
+            if (fd.type().asClassDoc() != null) {
+                dump(prefix + "  ", fd.type().asClassDoc());
+            }
+        }
+    }
+
+    void initJar() throws IOException {
+        Path testClasses = Paths.get(System.getProperty("test.classes"));
+        jarPath = Paths.get("lib.jar");
+        try (JarOutputStream out = new JarOutputStream(Files.newOutputStream(jarPath))) {
+            String[] classNames = {"Lib1.class", "Lib2.class"};
+            for (String cn : classNames) {
+                out.putNextEntry(new JarEntry("lib/" + cn));
+                Path libClass = testClasses.resolve("jarsrc").resolve("lib").resolve(cn);
+                out.write(Files.readAllBytes(libClass));
+            }
+        }
+    }
+
+    void error(String msg) {
+        System.err.println("Error: " + msg);
+        errors++;
+    }
+
+    Path jarPath;
+    int errors;
+
+    // Bad doclet caches the RootDoc for later use
+
+    static RootDoc cachedRoot;
+
+    public static boolean start(RootDoc root) {
+        cachedRoot = root;
+        return true;
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/tools/javadoc/8147801/jarsrc/lib/Lib1.java	Wed Jul 05 21:20:39 2017 +0200
@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2016, 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.
+ */
+
+package lib;
+
+public class Lib1 {
+    public Lib2 lib2;
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/tools/javadoc/8147801/jarsrc/lib/Lib2.java	Wed Jul 05 21:20:39 2017 +0200
@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2016, 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.
+ */
+
+package lib;
+
+public class Lib2 {
+    int i;
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/tools/javadoc/8147801/p/Test.java	Wed Jul 05 21:20:39 2017 +0200
@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2016, 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.
+ */
+
+package p;
+
+public class Test {
+    public lib.Lib1 lib1;
+}
+
--- a/langtools/test/tools/sjavac/JavacOptionPrep.java	Wed Jul 05 21:20:31 2017 +0200
+++ b/langtools/test/tools/sjavac/JavacOptionPrep.java	Wed Jul 05 21:20:39 2017 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2016, 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
@@ -65,7 +65,7 @@
         //  - Sources provided without preceding option (SRC2)
         //  - An unrecognized option which is to be passed on to javac
         String sjavacArgs = "-cp " + TestPath.CP1 + SEP + TestPath.CP2 +
-                            " -d dest " +
+                            " -d dest" +
                             " -h header" +
                             " -sourcepath " + TestPath.SOURCEPATH1 +
                             " -src " + TestPath.SRC1 +