Package com.collibra.dgc.core.api.component.file

# Interface FileApi

public interface FileApi
Public API for the management of temporary files. Default retention is 8 hours. This API is not designed for long-term storage and low retention times should be preferred.

Note: Resources are always referenced by their id, represented as a `UUID`. A resource id is a UUID which uniquely identifies the resource.
When the resource is referenced differently (not with the id) it will be specified in the parameter name and its documentation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FileInfo`
  `addFile(AddFileRequest addFileRequest)`
  Add a new file with a default retention period of 8 hours.
  `FileInfo`
  `addFile(String fileName, File file, boolean skipSecurity)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  This method is deprecated for removal.
  `void`
  `cleanTemporaryDirectory(long timeToLive)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `cleanupExpiredFiles()`.
  `void`
  `cleanupExpiredFiles()`
  Deletes files having passed their expiration time.
  `void`
  `deleteFile(UUID fileId)`
  Delete file with ID
  `boolean`
  `exists(UUID fileId)`
  Returns true if a file with given ID exists.
  `InputStream`
  `getFileAsStream(UUID fileId)`
  Returns the content of given file or attachment as an input stream.
  `byte[]`
  `getFileContent(UUID fileId)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  This method can fill the memory of the application if used for large files, please use `getFileAsStream(UUID)` instead.
  `File`
  `getFileDirectory()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  The directory returned is not linked to the implementation of this API, temporary directory should be retrieved through other means.
  `FileInfo`
  `getFileInfo(UUID fileId)`
  Returns the information about a file with its ID.
  `FileInfo`
  `getFileInfoFromUrl(String fileUrl)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  This cannot be guaranteed to support all files.
  `String`
  `getFileName(UUID fileId)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Please use `getFileInfo(UUID)` instead.
  `NewFileResponse`
  `newFileOutputStream(String fileName)`
  Creates a new file and returns an `OutputStream` to write its content, along with the file ID.
  `Instant`
  `retainFor(UUID fileId, long duration, TemporalUnit unit)`
  Sets the retention for specified file to the given duration, starting from current time.
  `void`
  `touchFile(UUID fileId)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Please use `retainFor(UUID, long, TemporalUnit)` instead.

- ## Method Details

  - ### newFileOutputStream

    NewFileResponse newFileOutputStream(String fileName)
    Creates a new file and returns an `OutputStream` to write its content, along with the file ID. The caller is responsible for closing the `OutputStream`. The file has a default retention period of 8 hours.
    Parameters:
      `fileName` - the name of the file to create
    Returns:
      a `NewFileResponse` containing the file ID and the `OutputStream` to write to

  - ### addFile

    FileInfo addFile(AddFileRequest addFileRequest)
    Add a new file with a default retention period of 8 hours.
    Parameters:
      `addFileRequest` - the properties of the file to be added
    Returns:
      The `FileInfo` containing metadata for the file

  - ### addFile

    @Deprecated(forRemoval=true, since="2026.04") FileInfo addFile(String fileName, File file, boolean skipSecurity)
    Deprecated, for removal: This API element is subject to removal in a future version.
    This method is deprecated for removal. Use `addFile(AddFileRequest)`
    Add a new file with a default retention period of 8 hours.
    Parameters:
      `fileName` - the name of the file in UUID format to add
      `file` - the local file to add
      `skipSecurity` - This parameter is now ignored
    Returns:
      The `FileInfo` containing metadata for the file

  - ### getFileAsStream

    InputStream getFileAsStream(UUID fileId)
    Returns the content of given file or attachment as an input stream. Keep in mind to use `AttachmentApi.getAttachmentContent(java.util.UUID)` instead of this endpoint when you want to get the file of an attachment. A File and its id can be temporary so it's possible this endpoint will not get you the desired file.
    Parameters:
      `fileId` - the ID of the file
    Returns:
      the content as `InputStream`

  - ### getFileDirectory

    @Deprecated(forRemoval=true, since="2026.04") File getFileDirectory()
    Deprecated, for removal: This API element is subject to removal in a future version.
    The directory returned is not linked to the implementation of this API, temporary directory should be retrieved through other means.
    Returns the temporary directory of DGC.
    Returns:
      the directory

  - ### getFileInfo

    FileInfo getFileInfo(UUID fileId)
    Returns the information about a file with its ID.
    Parameters:
      `fileId` - The ID of the file represented as a `UUID`
    Returns:
      The information about the file

  - ### getFileContent

    @Deprecated(forRemoval=true, since="2026.04") byte[] getFileContent(UUID fileId)
    Deprecated, for removal: This API element is subject to removal in a future version.
    This method can fill the memory of the application if used for large files, please use `getFileAsStream(UUID)` instead.
    Returns contents of a file
    Parameters:
      `fileId` - The ID of the file represented as a `UUID`
    Returns:
      a
      invalid reference

          byte[]

  - ### getFileInfoFromUrl

    @Deprecated(forRemoval=true, since="2026.04") FileInfo getFileInfoFromUrl(String fileUrl)
    Deprecated, for removal: This API element is subject to removal in a future version.
    This cannot be guaranteed to support all files. Please extract the file ID instead to retrieve its metadata.
    Returns the information about the file for the given url.
    Parameters:
      `fileUrl` - the url of the file to get
    Returns:
      the `FileInfo`

  - ### getFileName

    @Deprecated(forRemoval=true, since="2026.04") String getFileName(UUID fileId)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Please use `getFileInfo(UUID)` instead.
    Returns the name of the file.
    Parameters:
      `fileId` - The ID of the file for which to get name
    Returns:
      a file name

  - ### cleanTemporaryDirectory

    @Deprecated(forRemoval=true, since="2026.04") void cleanTemporaryDirectory(long timeToLive)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `cleanupExpiredFiles()`.
    Deletes files having passed their expiration time. Cleanup being based on individual file retention, this endpoint will be removed in the future.
    Parameters:
      `timeToLive` - deprecated parameter which is now ignored

  - ### cleanupExpiredFiles

    void cleanupExpiredFiles()
    Deletes files having passed their expiration time.

  - ### exists

    boolean exists(UUID fileId)
    Returns true if a file with given ID exists.
    Parameters:
      `fileId` - the ID of the issue
    Returns:
      true if a file with given ID exists, false otherwise

  - ### touchFile

    @Deprecated(forRemoval=true, since="2026.07") void touchFile(UUID fileId)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Please use `retainFor(UUID, long, TemporalUnit)` instead.
    Retains the specified file for the default duration of 8 hours, starting from current time.
    Parameters:
      `fileId` - the ID of the file

  - ### retainFor

    Instant retainFor(UUID fileId, long duration, TemporalUnit unit)
    Sets the retention for specified file to the given duration, starting from current time. After the retention period, the file will be marked for deletion. If the duration is above maximum value allowed, it will be set to the maximum. Negative durations are not supported and will be ignored. Legacy implementation of this API will always ignore the duration and retain the file for the default duration (8 hours).
    Parameters:
      `fileId` - The ID of the file
      `duration` - amount of time before expiration
      `unit` - unit of the duration parameter
    Returns:
      The Instant at which the file will be marked for deletion

  - ### deleteFile

    void deleteFile(UUID fileId)
    Delete file with ID
    Parameters:
      `fileId` - the ID of the file