Nuxeo Core Developer Guide

Temporary Files

Updated: March 18, 2024

org.nuxeo.runtime.api.Framework provides utility methods for temporary file and folder management.

Nuxeo Temporary Directory

Nuxeo uses the directory set by the configuration parameter nuxeo.tmp.dir (Environment.NUXEO_TMP_DIR). By default (with launcher.override.java.tmpdir == true), Nuxeo will set java.io.tmpdir = ${nuxeo.tmp.dir}.

Code needing a temporary file or folder must create it in nuxeo.tmp.dir or Environment.getDefault().getTemp() then ensure it will be deleted after use.

On Linux environments, we recommend not to use the system temporary folder /tmp because this one can be cleaned up. This is the case on Red Hat Enterprise Linux in particular, where systemd-tmpfiles service is deleting old files from /tmp.

Creating a Temporary File or Folder

Temporary files or folders are usually created with java.io.File.createTempFile(), java.nio.file.Files.createTempFile() or java.nio.file.Files.createTempDirectory(). However those methods may use a wrong folder:

  • If they are called without an explicit parent directory where to create the temporary resource, then they fall back on the value of java.io.tmpdir on JVM start.
  • If the temporary directory location is set or changed after the JVM start, then the final location will be wrong (unit tests are a common failure case).

The org.nuxeo.runtime.api.Framework provides three dedicated methods:

  • Framework.createTempFile()
  • Framework.createTempFilePath()
  • Framework.createTempDirectory()

java.io.File

Do not use java.io.File.createTempFile(String, String). Instead, you can use one of the two following:

  • Framework.createTempFile(String, String)
  • File.createTempFile(String, String, Environment.getDefault().getTemp())

The Framework method performs additional checks, directory creation and fall back to java.io.tmpdir if needed.

java.nio.file.Files

Do not use java.nio.file.Files.createTempFile(String, String, FileAttribute<?>...). Instead, you can use one of the two following:

  • Framework.createTempFilePath(String, String, FileAttribute<?>...)
  • Files.createTempFile(Environment.getDefault().getTemp().toPath(), String, String, FileAttribute<?>...)

Do not use java.nio.file.Files.createTempDirectory(String, FileAttribute<?>...). Instead, you can use one of the two following:

  • Framework.createTempDirectory(String, FileAttribute<?>...)
  • Files.createTempDirectory(Environment.getDefault().getTemp().toPath(), String, FileAttribute<?>...)

The Framework methods perform additional checks, directory creation and fall back to java.io.tmpdir if needed.

Code Using java.io.tmpdir

Any third-party code storing the temporary folder in a static variable is an issue: it is not thread-safe and may use a deprecated path, optionally already deleted. Here is a non exhaustive list:

  • javax.imageio.ImageIO.CacheInfo.getCacheDirectory() internal method, used by ImageIO.read() Workaround: precede with ImageIO.setCacheDirectory(Environment.getDefault().getTemp());

Deleting Temporary Resource After Use

The java.io.File.deleteOnExit() method has a few caveats:

  • Deletion will be attempted only for normal termination of the virtual machine.
  • Temporary resources will live far too longer than needed.
  • No check is performed on the file being deleted.

Instead, use the Framework.trackFile(File, Object) method which leverages the use of org.apache.commons.io.FileCleaningTracker, keeping track of the file awaiting deletion, and deleting it when the associated marker object is reclaimed by the garbage collector. Additionally it uses a FileEventTracker.SafeFileDeleteStrategy which will not delete files contained in some protected directories: by default, the binaries are protected from such an automatic deletion.