Package org.odpi.openmetadata.accessservices.datamanager.api

Interface FilesAndFoldersInterface

All Known Implementing Classes:
FilesAndFoldersClient
public interface FilesAndFoldersInterface
FilesAndFoldersInterface is the interface used to record metadata about files and folders. It can be used to create metadata both on behalf of a file system or a file manager application. If this is being used for files and folders in a file system, leave the fileManagerCapabilityGUID and fileManagerCapabilityName parameters as null. If the files and folders are owned by a file manager application and you want the corresponding assets in the catalog to be locked read only to all but the integration technology managing the metadata then set fileManagerCapabilityGUID and fileManagerCapabilityName to the GUId and qualified name of a software server capability that represents the file manager.

  • Method Details

    • createNestedFolders

      List<String> createNestedFolders(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String parentGUID, String pathName) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Creates a new folder asset for each element in the pathName that is linked from the parent entity. For example, a pathName of "one/two/three" creates 3 new folder assets, one called "one", the next called "one/two" and the last one called "one/two/three".
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      parentGUID - unique identifier of root object to connect the folder to (fileSystemGUID or folderGUID)
      pathName - pathname of the folder (or folders)
      Returns:
      list of GUIDs from the top level to the leaf of the supplied pathname
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • attachTopLevelFolder

      void attachTopLevelFolder(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String fileSystemGUID, String folderGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Links a folder to a file system. The folder is not changed.
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      fileSystemGUID - unique identifier of the file system to connect folder to
      folderGUID - unique identifier of the folder in the catalog
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • detachTopLevelFolder

      void detachTopLevelFolder(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String fileSystemGUID, String folderGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Removed the link between a folder and a file system.
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      fileSystemGUID - unique identifier of the file system to disconnect folder from
      folderGUID - unique identifier of the folder in the catalog
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • addDataFileToCatalog

      List<String> addDataFileToCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, DataFileProperties dataFileProperties, String connectorProviderName) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Creates a new file asset and links it to the folder structure implied in the path name. If the folder structure is not catalogued already, this is created automatically using the createFolderStructureInCatalog() method. For example, a pathName of "one/two/three/MyFile.txt" potentially creates 3 new folder assets, one called "one", the next called "one/two" and the last one called "one/two/three" plus a file asset called "one/two/three/MyFile.txt".
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      dataFileProperties - details of the data file to add to the catalog as an asset
      connectorProviderName - class name of connector provider for connector to access this asset
      Returns:
      list of asset GUIDs from the top level to the root of the pathname
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • addDataFileToCatalogFromTemplate

      List<String> addDataFileToCatalogFromTemplate(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String templateGUID, TemplateProperties templateProperties) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Add an asset description a file based on the content of a template object. Link this new asset to the folder structure implied in the path name. If the folder structure is not catalogued already, this is created automatically using the createFolderStructureInCatalog() method. For example, a pathName of "one/two/three/MyFile.txt" potentially creates 3 new folder assets, one called "one", the next called "one/two" and the last one called "one/two/three" plus a file asset called "one/two/three/MyFile.txt".
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      templateGUID - unique identifier of the file asset to copy
      templateProperties - override properties for the asset
      Returns:
      list of GUIDs from the top level to the root of the pathname
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • updateDataFileInCatalog

      void updateDataFileInCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String dataFileGUID, boolean isMergeUpdate, DataFileProperties dataFileProperties) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Update the file asset description in the catalog.
      Parameters:
      userId - calling user (assumed to be the owner)
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      dataFileGUID - unique identifier of the data file asset
      isMergeUpdate - should the supplied properties completely override the existing properties or augment them?
      dataFileProperties - properties for the asset
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • archiveDataFileInCatalog

      void archiveDataFileInCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String dataFileGUID, ArchiveProperties archiveProperties) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Remove the file asset description from the catalog.
      Parameters:
      userId - calling user (assumed to be the owner)
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      dataFileGUID - unique identifier of the data file asset
      archiveProperties - properties to help locate the archive copy
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • deleteDataFileFromCatalog

      void deleteDataFileFromCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String dataFileGUID, String fullPathname) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Remove the file asset description from the catalog.
      Parameters:
      userId - calling user (assumed to be the owner)
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      dataFileGUID - unique identifier of the data file asset
      fullPathname - unique path and file name for file
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • addDataFolderToCatalog

      List<String> addDataFolderToCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, FileFolderProperties fileFolderProperties, String connectorProviderName) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Creates a new folder asset that is identified as a data asset. This means the files and sub-folders within it collectively make up the contents of the data asset. As with other types of file-based asset, links are made to the folder structure implied in the path name. If the folder structure is not catalogued already, this is created automatically using the createFolderStructureInCatalog() method. For example, a pathName of "one/two/three/MyDataFolder" potentially creates 3 new folder assets, one called "one", the next called "one/two" and the last one called "one/two/three" plus a DataFolder asset called "one/two/three/MyDataFolder".
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      fileFolderProperties - properties to describe the folder properties
      connectorProviderName - class name of connector provider for connector to access this asset
      Returns:
      list of GUIDs from the top level to the root of the pathname
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • addDataFolderToCatalogFromTemplate

      List<String> addDataFolderToCatalogFromTemplate(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String templateGUID, TemplateProperties templateProperties) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Creates a new folder asset that is identified as a data asset using a template. This means the files and sub-folders within it collectively make up the contents of the data asset. As with other types of file-based asset, links are made to the folder structure implied in the path name. If the folder structure is not catalogued already, this is created automatically using the createFolderStructureInCatalog() method. For example, a pathName of "one/two/three/MyDataFolder" potentially creates 3 new folder assets, one called "one", the next called "one/two" and the last one called "one/two/three" plus a DataFolder asset called "one/two/three/MyDataFolder".
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      templateGUID - unique identifier of the file asset to copy
      templateProperties - override properties for the asset
      Returns:
      list of GUIDs from the top level to the root of the pathname
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • updateDataFolderInCatalog

      void updateDataFolderInCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String dataFolderGUID, boolean isMergeUpdate, FileFolderProperties fileFolderProperties) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Update the data folder asset description in the catalog.
      Parameters:
      userId - calling user (assumed to be the owner)
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      dataFolderGUID - unique identifier of the data folder asset
      isMergeUpdate - should the supplied properties completely override the existing properties or augment them?
      fileFolderProperties - properties for the asset
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • archiveDataFolderInCatalog

      void archiveDataFolderInCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String dataFolderGUID, ArchiveProperties archiveProperties) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Mark the data folder asset description in the catalog as archived.
      Parameters:
      userId - calling user (assumed to be the owner)
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      dataFolderGUID - unique identifier of the data folder asset
      archiveProperties - properties to help locate the archive copy
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • deleteDataFolderFromCatalog

      void deleteDataFolderFromCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String dataFolderGUID, String fullPathname) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Remove the data folder asset description from the catalog.
      Parameters:
      userId - calling user (assumed to be the owner)
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      dataFolderGUID - unique identifier of the data folder asset
      fullPathname - unique path and file name for file
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • attachDataFileAssetToFolder

      void attachDataFileAssetToFolder(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String folderGUID, String fileGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Link an existing file asset to a folder. The file is not changed as this is used to create a logical link to the folder.
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      folderGUID - unique identifier of the folder
      fileGUID - unique identifier of the file
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • detachDataFileAssetFromFolder

      void detachDataFileAssetFromFolder(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String folderGUID, String fileGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Remove a link between a file asset and a folder. The file is not changed. Use moveDataFileInCatalog to record the fact that the physical file has moved. Use attachDataFileAssetToFolder to create logical link to a new folder.
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      folderGUID - unique identifier of the folder
      fileGUID - unique identifier of the file
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • moveDataFileInCatalog

      void moveDataFileInCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String folderGUID, String fileGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Move a data file from its current parent folder to a new parent folder - this changes the file's qualified name but not its unique identifier (guid). Similarly to the endpoint in the connection object.
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      folderGUID - unique identifier of the folder
      fileGUID - unique identifier of the file
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • moveDataFolderInCatalog

      void moveDataFolderInCatalog(String userId, String fileManagerCapabilityGUID, String fileManagerCapabilityName, String folderGUID, String dataFolderGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Move a data folder from its current parent folder to a new parent folder - this changes the folder's qualified name but not its unique identifier (guid). Similarly to the endpoint in the connection object.
      Parameters:
      userId - calling user
      fileManagerCapabilityGUID - unique identifier of the software server capability representing an owning external file manager or null
      fileManagerCapabilityName - unique name of the software server capability representing an owning external file manager or null
      folderGUID - unique identifier of the folder
      dataFolderGUID - unique identifier of the data folder to move
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getFolderByGUID

      FileFolderElement getFolderByGUID(String userId, String folderGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Retrieve a FileFolderProperties asset by its unique identifier (GUID).
      Parameters:
      userId - calling user
      folderGUID - unique identifier used to locate the folder
      Returns:
      FileFolderProperties properties
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getFolderByPathName

      FileFolderElement getFolderByPathName(String userId, String pathName) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Retrieve a folder by its fully qualified path name.
      Parameters:
      userId - calling user
      pathName - path name
      Returns:
      FileFolderProperties properties
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getTopLevelFolders

      List<FileFolderElement> getTopLevelFolders(String userId, String fileSystemGUID, int startFrom, int pageSize) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Return the list of folders linked to the file server capability.
      Parameters:
      userId - calling user
      fileSystemGUID - unique identifier of the software server capability representing the file system
      startFrom - starting point in the list
      pageSize - maximum number of results
      Returns:
      list of folder properties (null means no nested folders)
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getNestedFolders

      List<FileFolderElement> getNestedFolders(String userId, String parentFolderGUID, int startFrom, int pageSize) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Return the list of folders nested inside a folder.
      Parameters:
      userId - calling user
      parentFolderGUID - unique identifier of the parent folder or file system
      startFrom - starting point in the list
      pageSize - maximum number of results
      Returns:
      list of folder properties (null means no nested folders)
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getTopLevelDataFiles

      List<DataFileElement> getTopLevelDataFiles(String userId, String fileSystemGUID, int startFrom, int pageSize) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Return the list of folders nested inside a folder.
      Parameters:
      userId - calling user
      fileSystemGUID - unique identifier of the software server capability representing the file system
      startFrom - starting point in the list
      pageSize - maximum number of results
      Returns:
      list of file properties (null means no top-level files)
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getFolderFiles

      List<DataFileElement> getFolderFiles(String userId, String folderGUID, int startFrom, int pageSize) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Get the data files inside a folder - both those that are nested and those that are linked.
      Parameters:
      userId - calling user
      folderGUID - unique identifier of the parent folder
      startFrom - starting point in the list
      pageSize - maximum number of results
      Returns:
      list of file properties (null means no files)
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getFileByGUID

      DataFileElement getFileByGUID(String userId, String fileGUID) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Retrieve a FileFolderProperties asset by its unique identifier (GUID).
      Parameters:
      userId - calling user
      fileGUID - unique identifier used to locate the folder
      Returns:
      File properties
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getFileByPathName

      DataFileElement getFileByPathName(String userId, String pathName) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Retrieve a folder by its fully qualified path name.
      Parameters:
      userId - calling user
      pathName - path name
      Returns:
      File properties
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • getFilesByPathName

      List<DataFileElement> getFilesByPathName(String userId, String pathName, int startFrom, int pageSize) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Find data file by a full or partial path name. The wildcard is specified using regular expressions (RegEx) and the method matches on the pathName property.
      Parameters:
      userId - calling user
      pathName - path name
      startFrom - starting point in the list
      pageSize - maximum number of results
      Returns:
      list of matching file properties
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem

    • findFilesByPathName

      List<DataFileElement> findFilesByPathName(String userId, String pathName, int startFrom, int pageSize) throws InvalidParameterException, UserNotAuthorizedException, PropertyServerException
      Retrieve data files by the supplied wildcard name. The wildcard is specified using regular expressions (RegEx) and the method matches on the qualifiedName, name and pathName property.
      Parameters:
      userId - calling user
      pathName - path name
      startFrom - starting point in the list
      pageSize - maximum number of results
      Returns:
      list of matching file properties
      Throws:
      InvalidParameterException - one of the parameters is null or invalid
      PropertyServerException - problem accessing property server
      UserNotAuthorizedException - security access problem