[LUCENE-6056] JavaDocs of Directory.renameFile are misleading

• Type: Bug
• Status: Resolved
• Priority: Minor
• Resolution: Not A Problem
• Component/s: general/javadocs
• Lucene Fields: New
• Assignee: Unassigned
• Reporter: Boaz Leskes
• Created: 10/Nov/14 10:24
• Updated: 28/Aug/22 14:19
• Resolved: 10/Nov/14 10:27

Description

The java docs of org.apache.lucene.store.Directory#renameFile read:

• Renames {@code source}

  to

  {@code dest} as an atomic operation,
  * where {@code dest}

  does not yet exist in the directory.

However in FSDirectory we do:

Files.move(directory.resolve(source), directory.resolve(dest), StandardCopyOption.ATOMIC_MOVE);

That one does not give us the documented behavior. From the javadocs of Files.move, with StandardCopyOption.ATOMIC_MOVE:
The move is performed as an atomic file system operation and all other options are ignored. If the target file exists then it is implementation specific if the existing file is replaced or this method fails by throwing an IOException.

I think the use of atomic moves is good here but it means the java docs of the Directory.renameFiles should be changed and relax the guarantee.