Summary

Clarify about how the directory parameter of java.io.File.createTempFile(String prefix, String suffix, File directory) is handled.

Problem

The specification of java.io.createTempFile(String,String,File) does not provide enough detail about how the third parameter, the directory in which to create the temporary file, is handled.

Solution

Add some verbiage more accurately describing how the target directory is handled.

Specification

--- a/src/java.base/share/classes/java/io/File.java
+++ b/src/java.base/share/classes/java/io/File.java
@@ -2103,38 +2103,46 @@ public class File
      * <p> If the {@code directory} argument is {@code null} then the
      * system-dependent default temporary-file directory will be used.  The
      * default temporary-file directory is specified by the system property
      * {@code java.io.tmpdir}.  On UNIX systems the default value of this
      * property is typically {@code "/tmp"} or {@code "/var/tmp"}; on
      * Microsoft Windows systems it is typically {@code "C:\\WINNT\\TEMP"}.  A different
      * value may be given to this system property when the Java virtual machine
      * is invoked, but programmatic changes to this property are not guaranteed
      * to have any effect upon the temporary directory used by this method.
      *
+     * <p> If the {@code directory} argument is not {@code null} and its
+     * abstract pathname is valid and denotes an existing, writable directory,
+     * then the file will be created in that directory. Otherwise the file will
+     * not be created and an {@code IOException} will be thrown.  Under no
+     * circumstances will a directory be created at the location specified by
+     * the {@code directory} argument.
+     *
      * @param  prefix     The prefix string to be used in generating the file's
      *                    name; must be at least three characters long
      *
      * @param  suffix     The suffix string to be used in generating the file's
      *                    name; may be {@code null}, in which case the
      *                    suffix {@code ".tmp"} will be used
      *
      * @param  directory  The directory in which the file is to be created, or
      *                    {@code null} if the default temporary-file
      *                    directory is to be used
      *
      * @return  An abstract pathname denoting a newly-created empty file
      *
      * @throws  IllegalArgumentException
      *          If the {@code prefix} argument contains fewer than three
      *          characters
      *
-     * @throws  IOException  If a file could not be created
+     * @throws  IOException
+     *          If a file could not be created
      *
      * @throws  SecurityException
      *          If a security manager exists and its {@link
      *          java.lang.SecurityManager#checkWrite(java.lang.String)}
      *          method does not allow a file to be created
      *
      * @since 1.2
      */
     public static File createTempFile(String prefix, String suffix,
                                       File directory)