[TIKA-1726] Augment public methods that use a java.io.File with methods that use a java.nio.file.Path

• Type: Improvement
• Status: Resolved
• Priority: Minor
• Resolution: Fixed
• Fix Version/s: 1.11
• Component/s: batch, core, gui, parser, translation
• Labels: java7
• Flags: Patch
• Assignee: Chris A. Mattmann
• Reporter: Yaniv Kunda
• Created: 01/Sep/15 12:42
• Updated: 19/Oct/15 05:36
• Resolved: 19/Oct/15 05:36

Description

In light of Java 7 already EOL, it's high time we add support for the new java.nio.file.Path class introduced with it, which, together with support methods in java.nio.file.Files and others, provide a better file I/O framework than java.io.File.

In just two cases, we have public methods in tika that only return a File object, and cannot be overloaded, so a different name for the new method must be created:

• org.apache.tika.io.TemporaryResources#createTemporaryFile()
  Suggestions:
  • addTemporaryFile
  • addTempFile
  • createTempFile
  • createTemporaryPath
• org.apache.tika.io.TikaInputStream#getFile()
  Suggestions:
  • asFile
  • toPath
  • getPath

In other cases, the methods accept a File as an argument, and should remain as tika users might be using them - so an overloaded method that accepts a Path instead should be added, referencing the new method from the old one (using the @see tag) until java.io.File itself is deprecated or otherwise becomes obsolete.
Here is the full list of other methods:
tika-app:

• org.apache.tika.gui.TikaGUI#openFile(File)

tika-batch:

• org.apache.tika.batch.fs.FSUtil#getOutputFile(File, String, HANDLE_EXISTING, String)
• org.apache.tika.util.PropsUtil#getFile(String, File)
• org.apache.tika.batch.fs.FSDirectoryCrawler constructors
• org.apache.tika.batch.fs.FSDirectoryCrawler#handleFirstFileInDirectory(File)
• org.apache.tika.batch.fs.FSFileResource constructor
• org.apache.tika.batch.fs.FSListCrawler constructor
• org.apache.tika.batch.fs.FSOutputStreamFactory constructor
• org.apache.tika.batch.fs.FSUtil#checkThisIsAncestorOfOrSameAsThat(File, File)
• org.apache.tika.batch.fs.FSUtil#checkThisIsAncestorOfThat(File, File)
• org.apache.tika.batch.fs.strawman.StrawManTikaAppDriver constructor

tika-core:

• org.apache.tika.Tika#detect(File)
• org.apache.tika.Tika#parse(File)
• org.apache.tika.Tika#parseToString(File)
• org.apache.tika.config.TikaConfig constructors
• org.apache.tika.detect.NNExampleModelDetector constructor
• org.apache.tika.detect.TrainedModelDetector#loadDefaultModels(File)
• org.apache.tika.io.TemporaryResources#setTemporaryFileDirectory(File)
• org.apache.tika.io.TikaInputStream#get(File)
• org.apache.tika.io.TikaInputStream#get(File, Metadata)
• org.apache.tika.parser.ParsingReader constructor

tika-parsers:

• org.apache.tika.parser.image.ImageMetadataExtractor#parseJpeg(File)
• org.apache.tika.parser.image.ImageMetadataExtractor#parseWebP(File)
• org.apache.tika.parser.mp4.DirectFileReadDataSource constructor

tika-translate:

• org.apache.tika.language.translate.ExternalTranslator#runAndGetOutput(String, String[], File)

Due to lack of evidence, all public methods in public non-test classes (and not in tika-example) are deemed part of a public API - although there's no formal definition of such.
If anyone knows of a public method which isn't accessed publicly and can be defined as package-private, or for another reason, please comment.