Typos and small issues in "File Operations Basics" and "Putting It All Together" articles of "The Java I/O API" tutorial ( https://dev.java/learn/java-io/reading-writing/ and https://dev.java/learn/java-io/putting-it-all-together/ )

[willy-b]

Hello dev.java team!

As the lengthy review of the "File System Basics" section concludes in #210 , I am filing here a separate issue to track the few typos found in the relatively much shorter "File Operations Basics" and "Putting It All Together" sections remaining in the "The Java I/O API" tutorial ( https://dev.java/learn/java-io/reading-writing/ and https://dev.java/learn/java-io/putting-it-all-together/ ).

Just a few items this time that may be of interest to fix.

---

In the latest version of https://dev.java/learn/java-io/reading-writing/
(archived as is at https://web.archive.org/web/20260425231842/https://dev.java/learn/java-io/reading-writing/ ),

• In the sentences

  This part covers the writing and reading of files. It makes the difference between small files that you can load in memory, and large files that you need to access through buffers.

  "It makes the difference between small files [...] and large files [...]" should probably be "It explains the difference between small files [...] and large files [...]."

---

In the latest version of https://dev.java/learn/java-io/reading-writing/common-operations/ (archived as is at https://web.archive.org/web/20260425231924/https://dev.java/learn/java-io/reading-writing/common-operations/ ),

• In the sentence

  Leaving resources unclose will cause your application to crash in the long run.

  "unclose" should be "open" or "unclosed".

• Trivial thing but FWIW, in the sentence

  For example, in the following method signature, the ellipses notation after the CopyOption argument indicates that the method accepts a variable number of arguments, or varargs, as they are typically called

  "the ellipses notation" should probably be "the ellipsis notation" (ellipses is plural of ellipsis, but there is a single one, though this is a minor thing).

  [Compare https://www.merriam-webster.com/dictionary/ellipsis and https://www.merriam-webster.com/dictionary/ellipses ]

• In the code snippet

  UserPrincipal group =
  file.getFileSystem()
  .getUserPrincipalLookupService()
  .lookupPrincipalByName("me");

  It would be recommended by this humble reader to declare the variable file here in this snippet. Since the variable file is not defined, the user is left to guess what it was declared as (e.g. File or Path? Spoiler: It is a Path).
  Since it has the method "getFileSystem" it must be a java.nio.file.Path and NOT a java.io.File (as the name might suggest) , so
  the variable name "file" is slightly confusing, especially as in an earlier snippet on the same page there was a "file" variable declared of type java.io.File.
  Additionally, the variable name "group" for a UserPrincipal may be confusing, as the entity returned may be a user, e.g. of type sun.nio.fs.UnixUserPrincipals$User.

---

In the latest version of https://dev.java/learn/java-io/reading-writing/small-files/ (archived as is at https://web.archive.org/web/20260425231939/https://dev.java/learn/java-io/reading-writing/small-files/ ),

• In the sentence

  When you see an ellipses notation after the type of the argument, it indicates that the method accepts a variable number of arguments, or varargs.

  "ellipses" should probably be "ellipsis"

• In the sentence

  POSIX File Permissions has an example that uses createFile(Path, FileAttribute<?>) to create a file with pre-set permissions.

  Should "POSIX File Permissions" be hyperlinked?

• In the sentence

  Reading and Writing Files With Channel I/O shows that the Path.newByteChannel() methods return an instance of a SeekableByteChannel.

  Should "Reading and Writing Files With Channel I/O" be hyperlinked?

---

In the latest version of https://dev.java/learn/java-io/putting-it-all-together/ (archived as is at https://web.archive.org/web/20260426192003/https://dev.java/learn/java-io/putting-it-all-together/?cache=false ),

• In the sentence

  It is very unlikely that Shakespeare writes any more sonnet (he died in 1616), but you still need to write this number here.

  "writes any more sonnet" should be "writes any more sonnets".

• In the sentence

  The readNextSonnet() method read the text of the sonnet.

  "read" should be "reads".

• In the sentence

  The first part of this code loops through all the sonnets and compress them to a first array of bytes.

  "compress" should be "compresses".

---

Thanks so much for these excellent articles. (As always, my motivation is that sharing the typos I find is the least I can do to give back.)

[JosePaumard]

Thank you again for your report! I just pushed a fix.
As for the POSIX File Permissions: I removed the reference, because the example is nowhere to be found. Same for Reading and Writing Files With Channel I/O.

[willy-b]

Thanks! I see some of the fixes.

However, I think you did not yet remove the reference to a section on "POSIX File Permissions" from https://dev.java/learn/java-io/reading-writing/small-files/ yet (archived as is at https://web.archive.org/web/20260427225747/https://dev.java/learn/java-io/reading-writing/small-files/?cache=false ) as stated, though you did remove the reference to "Reading and Writing Files With Channel I/O".

Another question re: https://dev.java/learn/java-io/reading-writing/small-files/ is, did the team leave the "Writing" column in the "Choosing the Right I/O Method" table blank intentionally for the last two rows? (e.g. newByteChannel() and FileChannel ). I assume this is meant to imply that those techniques, like FileChannel, are for both reading and writing? If so, maybe the two columns should just have the same content in that case with a note, or something.

---

In the latest https://dev.java/learn/java-io/reading-writing/common-operations/ (archived as is at https://web.archive.org/web/20260427225722/https://dev.java/learn/java-io/reading-writing/common-operations/?cache=false ),

one of your fixes seems to have accidentally added a line that is irrelevant to the code block that contains it.

I had previously written (re the last snapshot at https://web.archive.org/web/20260425231924/https://dev.java/learn/java-io/reading-writing/common-operations/ )

In the code snippet

UserPrincipal group =
file.getFileSystem()
.getUserPrincipalLookupService()
.lookupPrincipalByName("me");

It would be recommended by this humble reader to declare the variable file here in this snippet. Since the variable file is not defined, the user is left to guess what it was declared as (e.g. File or Path? Spoiler: It is a Path).
Since it has the method "getFileSystem" it must be a java.nio.file.Path and NOT a java.io.File (as the name might suggest) , so
the variable name "file" is slightly confusing, especially as in an earlier snippet on the same page there was a "file" variable declared of type java.io.File.
Additionally, the variable name "group" for a UserPrincipal may be confusing, as the entity returned may be a user, e.g. of type sun.nio.fs.UnixUserPrincipals$User.

That code snippet was updated to (with comments "//" from me added)

Path path = Path.of(...); // create a path //<-- this is good
String value = Charset.defaultCharset().decode(buf).toString(); // <-- this new line is unnecessary
UserPrincipal userPrincipal = // <-- this change is good
   path.getFileSystem() // <-- this change is good
       .getUserPrincipalLookupService()
       .lookupPrincipalByName("me");

which includes one new unnecessary line on "String value" (should be removed).

---

Thanks again!

[JosePaumard]

Thank you again for your report! I just pushed a fix.

[willy-b]

Thanks!

Two out of three items reported in the last comment appear to be resolved.

---

In https://dev.java/learn/java-io/reading-writing/common-operations/ (archived as is at https://dev.java/learn/java-io/reading-writing/common-operations/ ),

the unnecessary line added to one of the code snippets has been removed:

Path path = Path.of(...); // create a path //<-- this was a good addition, to declare "path"
// [removed] String value = Charset.defaultCharset().decode(buf).toString(); // <-- this new line was unnecessary, **and is now removed**
UserPrincipal userPrincipal = // <-- this change was good, to not call this "group"
   path.getFileSystem() // <-- this change was good, using variable named "path" rather than "file" (since it is an instance of Path)
      .getUserPrincipalLookupService()
      .lookupPrincipalByName("me");

---

Also confirmed: In https://dev.java/learn/java-io/reading-writing/small-files/ (archived as is: https://web.archive.org/web/20260501012333/https://dev.java/learn/java-io/reading-writing/small-files/), the reference to a separate section on "POSIX File Permissions" within this tutorial was removed as you had stated you wanted to do earlier at #235 (comment) .

Note that though you said:

As for the POSIX File Permissions: I removed the reference, because the example is nowhere to be found.

There is a "POSIX File Permissions" section with a relevant example in the previous sub-tutorial (File System Basics rather than File Operations Basics; Metadata article) at https://dev.java/learn/java-io/file-system/metadata/#posix if you wanted to have a hyperlink on the original sentence (archived at https://web.archive.org/web/20260425231939/https://dev.java/learn/java-io/reading-writing/small-files/ )

POSIX File Permissions has an example that uses createFile(Path, FileAttribute<?>) to create a file with pre-set permissions.

("POSIX File Permissions" could link to https://dev.java/learn/java-io/file-system/metadata/#posix )

---

Separately in https://dev.java/learn/java-io/reading-writing/small-files/ (archived as is: https://web.archive.org/web/20260501012333/https://dev.java/learn/java-io/reading-writing/small-files/)
there is one item possibly not completely fixed yet -
I had written:

Another question re: https://dev.java/learn/java-io/reading-writing/small-files/ is, did the team leave the "Writing" column in the "Choosing the Right I/O Method" table blank intentionally for the last two rows? (e.g. newByteChannel() and FileChannel ). I assume this is meant to imply that those techniques, like FileChannel, are for both reading and writing? If so, maybe the two columns should just have the same content in that case with a note, or something.

The second to last row, in the "Choosing the Right I/O Method" table, has been fixed to include the methods/classes in both the "Reading" and "Writing" columns where the same methods/classes perform both (newByteChannel(), SeekableByteChannel, ByteBuffer ).

But the last row, in the "Choosing the Right I/O Method" table, featuring FileChannel , has FileChannel in the "Reading" column with nothing listed in the "Writing" column -- shouldn't it also be listed in both?

Also, the labeling is still a little confusing on this table in that it says "Choosing the Right I/O Method" (emphasis on "Method") when it lists both Files API Methods and Classes/Interfaces that are helpful.
The intro sentence for the table also mentions "methods" without mentioning classes/interfaces will be included:

To help make sense of the API, the following table shows the file I/O methods available on the Files class and their use cases.

Perhaps it should say "the following table shows some broadly useful file I/O methods available on the Files class and some classes/interfaces returned by or used with those methods." Also the last row FileChannel can be returned in some cases by the method listed in the previous row and that row is the only row without a Files method and only an interface/class.

---

Thanks!

[JosePaumard]

Thank you for your comment! I just pushed a fix.
I reorganized the File I/O methods for Reading and Writing table and split it in Reading and Writing operations. It's probably more clear like that. Again, thank you!

[willy-b]

Thanks! I can confirm that in https://dev.java/learn/java-io/reading-writing/small-files/ (archived as is at https://web.archive.org/web/20260501141513/https://dev.java/learn/java-io/reading-writing/small-files/ ) , you have radically improved the "Choosing the Right I/O Method" table and completed it by separating methods for reading from methods for writing, and making the left column the Files I/O method and the middle column the return type.

The only remaining issue is the sidebar title doesn't match the heading, and it may be worthwhile to include the "lines()" method with return type "Stream<String>" (optional change) (as that features in some of the Oracle learning content on I/O):

Also I can confirm the POSIX File Permissions section from earlier in the series is linked now (as of https://web.archive.org/web/20260501141513/https://dev.java/learn/java-io/reading-writing/small-files/ ):

The section POSIX File Permissions has an example that uses createFile(Path, FileAttribute<?>) to create a file with pre-set permissions.

[willy-b]

[Edited my last comment only to fix the formatting of

may be worthwhile to include the "lines()" method with return type Stream<String> (optional change)

because the <String> had disappeared after formatting, and "lines()" had been replaced with "files()"]

[JosePaumard]

Thank you again for your comments! I just pusehd a fix.

[willy-b]

Excellent!

Confirmed: In the latest https://dev.java/learn/java-io/reading-writing/small-files/ (archived as is at https://web.archive.org/web/20260507021337/https://dev.java/learn/java-io/reading-writing/small-files/ ):
the sidebar was fixed and Files.lines was added to the table of methods for reading.

---

In the latest version of the table of contents for the "File Operations" section at https://dev.java/learn/java-io/reading-writing/ (archived as is at https://web.archive.org/web/20260507014148/https://dev.java/learn/java-io/reading-writing/ ),

• The "Releasing Resources and Catching Exceptions" section seems to have the wrong description (it is not focused on the Files class but rather releasing resources, exception handling, method chaining, and other topics; illustrated sometimes with and sometimes without using the Files class):

  Releasing Resources and Catching Exceptions
  The Files class is the other primary entrypoint of the java.nio.file package. This class offers a rich set of static methods for reading, writing, and manipulating files and directories. The Files methods work on instances of Path objects.

• The descriptions for Reading and Writing Small Files and for Reading and Writing Binary Files
  are both identical, seemingly unintentionally, and both have the description "This section discusses the details of reading, writing, creating, and opening files."

---

Thanks!