Package com.comsol.api.database

Interface FileItemVersion

  • public interface FileItemVersion

    A specific version of a file item in a Model Manager database.

    Use one of the plain value-returning methods to query the database for a specific data value of the file version. Use the optimized get() method to return all data values of the file version using a single database query operation.

    Saving a new version of the corresponding file item is done via a branch in a repository.

    See Also:
    BranchFileItem

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.util.Collection<ItemKey> assignedTagKeys()
      Query the database for the identifying keys of the tags assigned to the file item at the instant in time when the file version was saved.
      java.util.Collection<AssignedTagResult> assignedTags()
      Query the database for the tags assigned to the file item (their keys and titles) at the instant in time when the file version was saved.
      Branch branch()
      Get the branch that the file version belongs to.
      BranchFileItem branchItem()
      Get the latest version of the file item on the same branch that the current version belongs to.
      BranchKey branchKey()
      Get the identifying key of the branch that the file version belongs to.
      Commit commit()
      Get the commit that the file version was saved in.
      java.lang.String commitComment()
      Query the database for the associated commit comment written when the file version was saved.
      CommitKey commitKey()
      Query the database for the identifying key of the commit that the file version was saved in.
      Database database()
      Get the database the file version belongs to.
      DatabaseKey databaseKey()
      Get the identifying key of the database that the file version belongs to.
      java.lang.String description()
      Query the database for the description of the file version, or null if no description has been set.
      boolean exists()
      Returns true if the file version exists in the database.
      ExportFileItemVersionResult export​(ExportFileItemVersionParam exportFileItemVersionParam)
      Export file resource contents of the file version.
      ExportFileItemVersionResult exportToDirectory​(java.lang.String targetDirectoryLocation)
      Export all of the underlying file resource contents of the file version to a target directory.
      java.lang.String fileLocationUri​(FileResourcePath fileResourcePath)
      Get a file location URI that can be used to reference a file resource, or a directory of file resources, for the file version.
      default java.lang.String fileLocationUri​(java.lang.String... fileResourcePathSegments)
      Get a file location URI that can be used to reference a file resource, or a directory of file resources, for the file version.
      java.util.Collection<FileResourceResult> fileResources()
      Query the database for the data values of the underlying file resources of the file item (may be several in the case of a fileset).
      FileResourceResult firstFileResourceOrNull()
      Query the database for the data values of the underlying file resource of the file version.
      GetFileItemVersionResult get()
      Get all of the current data values of the file version using a single database query operation.
      FileItem item()
      Get the file item in the database that the file version belongs to.
      ItemKey itemKey()
      Get the identifying key of the file item in the database that the version belongs to.
      ItemSaveType itemSaveType()
      Get the save type of the file item that the version belongs to.
      ItemVersionKey itemVersionKey()
      Query the database for the identifying key of the file version.
      ItemVersionType itemVersionType()
      Query the database for the item version type of the file version.
      ItemKey originItemKey()
      Get the identifying key of a file item in the database that the item originates from.
      java.lang.String owner()
      Query the database for the current display name of the user that is set as the owner of the file item.
      QueryItemVersionReferenceResultStream queryVersionReferences()
      Query the item version references for the file version using default input parameters.
      QueryItemVersionReferenceResultStream queryVersionReferences​(QueryItemVersionReferencesParam queryItemVersionReferencesParam)
      Query the item versions that are either referenced by the file version or that are referencing the file version.
      Repository repository()
      Get the repository that the file version belongs to.
      RepositoryKey repositoryKey()
      Get the identifying key of the repository that the file version belongs to.
      long saved()
      Query the database for the point-in-time instant when the file version was saved in UNIX epoch milliseconds.
      java.lang.String savedBy()
      Query the database for the current display name of the user that saved the file version.
      java.lang.String title()
      Query the database for the title of the file version.

    • Method Detail

      • databaseKey

        DatabaseKey databaseKey()
        Get the identifying key of the database that the file version belongs to.
        Returns:
        The identifying key of the database that the file version belongs to.

      • database

        Database database()
        Get the database the file version belongs to.
        Returns:
        The database that the file version belongs to.

      • repositoryKey

        RepositoryKey repositoryKey()
        Get the identifying key of the repository that the file version belongs to.
        Returns:
        The identifying key of the repository that the file version belongs to.

      • repository

        Repository repository()
        Get the repository that the file version belongs to.
        Returns:
        The repository that the file version belongs to.

      • branchKey

        BranchKey branchKey()
        Get the identifying key of the branch that the file version belongs to.
        Returns:
        The identifying key of the branch that the file version belongs to.

      • branch

        Branch branch()
        Get the branch that the file version belongs to.
        Returns:
        The branch that the file version belongs to.

      • commitKey

        CommitKey commitKey()
        Query the database for the identifying key of the commit that the file version was saved in.
        Returns:
        The identifying key of the commit that the file version was saved in.

      • commit

        Commit commit()
        Get the commit that the file version was saved in.
        Returns:
        The commit that the file version was saved in.

      • itemKey

        ItemKey itemKey()
        Get the identifying key of the file item in the database that the version belongs to.
        Returns:
        The identifying key of the file item in the database.

      • item

        FileItem item()
        Get the file item in the database that the file version belongs to.
        Returns:
        The file item in the database that the file version belongs to.

      • branchItem

        BranchFileItem branchItem()
        Get the latest version of the file item on the same branch that the current version belongs to.
        Returns:
        The latest version of the file item on the same branch that the current version belongs to.

      • itemVersionType

        ItemVersionType itemVersionType()
        Query the database for the item version type of the file version.
        Returns:
        The item version type of the file version.

      • itemSaveType

        ItemSaveType itemSaveType()
        Get the save type of the file item that the version belongs to.
        Returns:
        The save type of the file item that the version belongs to.

      • originItemKey

        ItemKey originItemKey()
        Get the identifying key of a file item in the database that the item originates from. Returns null if the file item does not originate from another file item in the database.
        Returns:
        The identifying key of a file item in the database that the item originates from, or null.

      • itemVersionKey

        ItemVersionKey itemVersionKey()
        Query the database for the identifying key of the file version.
        Returns:
        The identifying key of the file version.

      • saved

        long saved()
        Query the database for the point-in-time instant when the file version was saved in UNIX epoch milliseconds.
        Returns:
        The point-in-time instant when the file version was saved in UNIX epoch milliseconds.

      • savedBy

        java.lang.String savedBy()
        Query the database for the current display name of the user that saved the file version.
        Returns:
        The current display name of the user that saved the file version.

      • owner

        java.lang.String owner()
        Query the database for the current display name of the user that is set as the owner of the file item.
        Returns:
        The current display name of the user that is set as the owner of the file item.

      • title

        java.lang.String title()
        Query the database for the title of the file version.
        Returns:
        The title of the file version.

      • description

        java.lang.String description()
        Query the database for the description of the file version, or null if no description has been set.
        Returns:
        The description of the file version, or null if no description has been set.

      • firstFileResourceOrNull

        FileResourceResult firstFileResourceOrNull()
        Query the database for the data values of the underlying file resource of the file version. For a fileset, the first encountered file resource is returned. Returns null if the file version does not have any underlying file resources at all.
        Returns:
        Data values for the underlying file resource of the file version, or null.

      • fileResources

        java.util.Collection<FileResourceResult> fileResources()
        Query the database for the data values of the underlying file resources of the file item (may be several in the case of a fileset).
        Returns:
        Data values for the underlying file resources of the file item.

      • fileLocationUri

        default java.lang.String fileLocationUri​(java.lang.String... fileResourcePathSegments)

        Get a file location URI that can be used to reference a file resource, or a directory of file resources, for the file version. The file resources need not exist in the database (as could be the case, for example, for a working copy of the file version).

        The returned URI uses the so-called dbfile file scheme with the format dbfile:///<path-segment1>/<path-segment2>/.../<path-segmentN>?<query-parameters>, with the path segment placeholders given by the provided file resource path segments.

        Parameters:
        fileResourcePathSegments - File resource path segments identifying a file resource or a directory of file resources.
        Returns:
        A file location URI that can be used to reference a file resource, or a directory of file resources, for the file version.
        Since:
        6.4

      • fileLocationUri

        java.lang.String fileLocationUri​(FileResourcePath fileResourcePath)

        Get a file location URI that can be used to reference a file resource, or a directory of file resources, for the file version. The file resources need not exist in the database (as could be the case, for example, for a working copy of the file version).

        The returned URI uses the so-called dbfile file scheme with the format dbfile:///<path-segment1>/<path-segment2>/.../<path-segmentN>?<query-parameters>, with the path segment placeholders corresponding to a file resource path.

        Parameters:
        fileResourcePath - A file resource path identifying a file resource or a directory of file resources.
        Returns:
        A file location URI that can be used to reference a file resource, or a directory of file resources, for the file version.
        Since:
        6.4

      • assignedTagKeys

        java.util.Collection<ItemKey> assignedTagKeys()
        Query the database for the identifying keys of the tags assigned to the file item at the instant in time when the file version was saved.
        Returns:
        The identifying keys of the tags assigned to the file item at the instant in time when the file version was saved.

      • assignedTags

        java.util.Collection<AssignedTagResult> assignedTags()
        Query the database for the tags assigned to the file item (their keys and titles) at the instant in time when the file version was saved.
        Returns:
        The tags assigned to the file item (their keys and titles) at the instant in time when the file version was saved.

      • commitComment

        java.lang.String commitComment()
        Query the database for the associated commit comment written when the file version was saved. May be null.
        Returns:
        The associated comment for the commit corresponding to the file version. May be null.

      • exists

        boolean exists()

        Returns true if the file version exists in the database.

        Testing for existence may be useful, for example, when this instance is obtained as the return value of Database.fileVersionByKey(ItemVersionKey).

        Returns:
        True if the file version exists in the database, otherwise false.
        Since:
        6.4

      • get

        GetFileItemVersionResult get()

        Get all of the current data values of the file version using a single database query operation.

        The data values held by the returned instance are collectively retrieved from the database already when this method is invoked. Using this method therefore offers better performance over the sibling query methods on this interface whenever multiple data values need to be retrieved for the file version.

        Returns:
        The data values for the file version as returned by the database.

      • queryVersionReferences

        QueryItemVersionReferenceResultStream queryVersionReferences()

        Query the item version references for the file version using default input parameters. The returned versions are sorted chronologically with newer versions appearing before older versions.

        The query returns a result stream of data values for matching reference versions whose individual stream elements are fetched on demand from the database as needed. This includes, for example, iterating through the elements via a "for-each loop" statement, converting the stream into a list or array of fixed size, or requesting the first element in the stream.

        Use the key returned by ItemVersionResult.itemVersionKey() of a data element in the result stream to access a specific version in the database — see ItemVersionKey.itemType(), Database.modelVersionByKey(ItemVersionKey) and Database.fileVersionByKey(ItemVersionKey).

        Returns:
        A result stream with the data values for the item version references that matched the query.
        See Also:
        DatabaseApiResultStream

      • queryVersionReferences

        QueryItemVersionReferenceResultStream queryVersionReferences​(QueryItemVersionReferencesParam queryItemVersionReferencesParam)

        Query the item versions that are either referenced by the file version or that are referencing the file version. The returned versions are sorted chronologically with newer versions appearing before older versions.

        Set desired input options on the generator returned by DatabaseApiUtil.param().forQueryItemVersionReferences() and then pass the generator as the sole argument to this method.

        The query returns a result stream of data values for matching reference versions whose individual stream elements are fetched on demand from the database as needed. This includes, for example, iterating through the elements via a "for-each loop" statement, converting the stream into a list or array of fixed size, or requesting the first element in the stream.

        Use the key returned by ItemVersionResult.itemVersionKey() of a data element in the result stream to access a specific version in the database — see ItemVersionKey.itemType(), Database.modelVersionByKey(ItemVersionKey) and Database.fileVersionByKey(ItemVersionKey).

        Parameters:
        queryItemVersionReferencesParam - Input parameters for the query.
        Returns:
        A result stream with the data values for the item version references that matched the query.
        See Also:
        DatabaseApiResultStream

      • exportToDirectory

        ExportFileItemVersionResult exportToDirectory​(java.lang.String targetDirectoryLocation)

        Export all of the underlying file resource contents of the file version to a target directory.

        If the intent is to update the exported file resource contents and then save it back as a new version of the corresponding file item, the caller must keep track of the file version's ItemVersionKey.

        An exception is thrown if a file already exists at the export target location.

        Parameters:
        targetDirectoryLocation - The absolute path of the target directory for the export. May be expressed as a file system path, a common file scheme path, or a user file scheme path.
        Returns:
        The result of the export, including the absolute paths of all exported files.

      • export

        ExportFileItemVersionResult export​(ExportFileItemVersionParam exportFileItemVersionParam)

        Export file resource contents of the file version.

        The target location for the export may either be specified as a file system path or as a file scheme path. Some of the supported file schemes also require that a model is specified via its model tag identifier. That model implicitly determines the root directory for the export target location.

        Set desired input options on the generator returned by DatabaseApiUtil.param().forExportFileVersion() and then pass the generator as the sole argument to this method.

        If the intent is to update the exported file resource contents and then save it back as a new version of the corresponding file item, the caller must keep track of the file version's ItemVersionKey.

        Parameters:
        exportFileItemVersionParam - Input parameters identifying the file resource contents to be exported.
        Returns:
        The result of the export, including the absolute paths of all exported files.