[Exist-development] NIO.2

[Adam R. <ad...@ex...>]

Hey devs,

We have now switched to using NIO.2 in a large proportion of the core
code base. There may be a few places where java.io.File and friends
are still in use, if you find these, feel free to clean them up.

The commit is here -
https://github.com/eXist-db/exist/commit/d06a425f6d3f9ad607bf93e05816e5e0e58b7b5e

So I would ask that in future there are a few rules that should be
followed to keep us clean with regards to NIO.2.

1. Always use java.nio.file.Path instead of java.io.File.
1.1 If you are working with a 3rd party library that demands a
java.io.File, then call .toFile on the Path at the last possible
moment, i.e. in the method call to that library. This will allow us to
easily identify non NIO.2 code in future.

2. For constructing paths, use `Paths.get` for new paths,
`Path.resolve` and `Path.resolveSibling` for child and sibling paths
respectively, and Path.relativise for `relative` paths.

3. Use java.nio.file.Files for filesystem ops. Do not use Apache
Commons IO. If you want "quiet" versions of the NIO.2 Files methods
then see org.exist.util.FileUtils.
3.1 Pay attention to StandardCopyOptions; e.g. if you are doing a
Files.move, you most likely want it to be MOVE_ATOMIC.

4. When you want to open a reader/writer or input/outputStream
(buffered or un-buffered) on a file, use Files.newInputStream and
friends instead of the java.io.FileInputStream and friends
constructors.
4.1 ALWAYS do this inside a try-with-resources statement.
4.2 Pay attention to the StandardOpenOptions; e.g. if you want fsync
then use SYNC.
4.3 You can often use FIles.newSeekableByteChannel instead of
java.io.RandomAccessFile. See the history of
org.exist.storage.FileLock for an example of this switch.

5. When you want to list files, consider whether Files.find might be
more efficient than Files.list. Note that Files.find on a directory
will include the directory itself, if you don't want that then add a
.filter. Try and operate on the Stream as a Stream, rather than
calling .collect. Remember, that the Stream can only be read once.

6. If you want the just name of the file (most likely only for
serialization purposes) then call
org.exist.util.FileUtils.fileName(path).
6.1 path.getFileName().endsWith(".ext") most likely does not do what
you think it does! You probably wanted
path.getFileName().toString().endsWith(".ext"), but instead please use
the shortcut FileUtils.fileName(path).endsWith(".ext")

Cheers Adam.

-- 
Adam Retter

eXist Developer
{ United Kingdom }
ad...@ex...
irc://irc.freenode.net/existdb