Add auto-renaming of linked files on entry data change

[paudelritij]

Closes #11316

This PR introduces an option to automatically rename linked files when the associated entry data is modified. The feature is configurable in Preferences under Linked files -> Linked file name conventions, with a default setting of false. It also includes handling for entries with multiple attached files and adds relevant test cases.

Steps to test

1. Open JabRef and go to Preferences > Linked files.
2. Enable [ ] Auto rename files if entry changes.
3. Create a new entry and attach a file.
4. Modify any field in the entry.
5. Check that the linked file's name updates to match the new citation key.
6. Test with multiple files to ensure all are renamed.

Mandatory checks

• I own the copyright of the code submitted and I license it under the MIT license
• Change in CHANGELOG.md described in a way that is understandable for the average user (if change is visible to the user)
• Tests created for changes (if applicable)
• Manually tested changed features in running JabRef (always required)
• Screenshots added in PR description (if change is visible to the user)
• Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
• Checked documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request to the documentation repository.

[koppor]

Ensure if the target file exists, do not use that name, use FileNameUniqueness.getNonOverWritingFileName(targetDirectory, targetFileName) to ensure that there is a unique other file name.

(Note to us: File should be kept even there are binary equal files. Otherwise, it gets complicated. E.g., if the same file is attached to another entry).

[paudelritij]

Ensure if the target file exists, do not use that name, use FileNameUniqueness.getNonOverWritingFileName(targetDirectory, targetFileName) to ensure that there is a unique other file name.

(Note to us: File should be kept even there are binary equal files. Otherwise, it gets complicated. E.g., if the same file is attached to another entry).

I am trying implementing it in org.jabref.logic.externalfiles.LinkedFileHandler#renameToSuggestedName to put uniqueFileName. However, I'm encountering an issue with org.jabref.logic.search.indexing.DocumentReader#addMetaData, which is causing errors when reading timestamps. There may be creation of a loop where file changes name from e.g. abc.pdf to abc(1).pdf to abc.pdf again repeatedly. Any insights on how to resolve this would be greatly appreciated.

" ERROR: Could not read timestamp for /Users//Documents/JabRef/Gen28_ - Hands on Machine Learning with Scikit Learn, Keras, and TensorFlow.pdf: java.nio.file.NoSuchFileException: /Users//Documents/JabRef/Gen28_ - Hands on Machine Learning with Scikit Learn, Keras, and TensorFlow.pdf "

[koppor]

@LoayGhreeb Do you have some hints maybe?

[LoayGhreeb]

I am trying implementing it in org.jabref.logic.externalfiles.LinkedFileHandler#renameToSuggestedName to put uniqueFileName. However, I'm encountering an issue with org.jabref.logic.search.indexing.DocumentReader#addMetaData, which is causing errors when reading timestamps. There may be creation of a loop where file changes name from e.g. abc.pdf to abc(1).pdf to abc.pdf again repeatedly. Any insights on how to resolve this would be greatly appreciated.

I don't think the problem is with the indexing itself. The NoSuchFileException means it's trying to access a file that doesn't exist, maybe it's still trying to use the old name, or the new one, but since there's a loop renaming the file back and forth, the file might not be available at the expected time during indexing.

I guess this loop could be happening if the same file is linked to two different entries. Could that be the case?

Please try to investigate further by adding some breakpoints to understand why, and where this loop is happening. Also, if possible, please push the commits that reproduce this issue, either here or in a new branch so we can take a proper look and help without guessing what's going on.

[trag-bot]

Method accepts null parameter 'fileAlreadyInUse' which violates modern Java practices of avoiding null parameters. Should use Optional instead.

[paudelritij]

when using FileNameUniqueness.getNonOverWritingFileName(), a loop was occurring why?

• Example: The original file name is paper_2082.pdf.
• After renaming, the new name becomes paper1_2082.pdf. This triggers a file field change event.
• On the next iteration, getSuggestedFileName() generates paper1_2082.pdf as the suggested name.
• Since the file paper1_2082.pdf already exists (only we know that it is already linked to same entry), FileNameUniqueness.getNonOverWritingFileName() renames it to paper1_2082 (1).pdf.
• This triggers another file field change event by generating file name again as paper1_2082.pdf (as it was in 1st place), and the process repeats, causing an infinite loop.

Solution Implemented

Case 1: File Exists but is Not Linked to the Entry: A new unique file name is suggested.
Case 2: File Exists and is Linked to the Entry: The file name change is discarded to prevent unnecessary renaming and event triggering.

[koppor]

I think, the loop comes from org.jabref.logic.cleanup.RenamePdfCleanup#cleanup

you can add some LOGGER.trace calls and adjust the log level (locally) to trace as desribed at https://devdocs.jabref.org/code-howtos/logging.html

[koppor]

I got following exceptions in the log if I had opened the PDF - therefore, I removed the exception at the log

[koppor]

I wired the listener to our CoarseGraindListener, because not at every single letter changes, the file should be renamed.

I also fixed the logger output - not each fired event should be logged as default. More reading on logging available at https://devdocs.jabref.org/code-howtos/logging.html.

Finally, I fixed the patterns for (2) suffixes etc. There should be tests, but I think I captered this wish at JabRef#719.

[trag-bot]

@trag-bot didn't find any issues in the code! ✅✨

[koppor]

Introduces some test failres on Windows, but I don't know yet why. Just documenting --> #13766