Package com.comsol.api.database

Interface BranchFileItem

  • public interface BranchFileItem

    A dynamic representation of the latest version of a file item with respect to a branch.

    The instance may be used to query the version history of the file item with respect to the branch, update the file item by saving a new latest version, change the current tag assignments of the file item, or export the latest version to the file system.

    The instance is dynamic in the sense that, after saving a new version of the file item or changing its assigned tags, this instance will continue to automatically refer to the latest version and the latest assigned tags. This is unlike, for example, FileItemVersion that always targets a fixed version of the file item.

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

    See Also:
    FileItemVersion

    • 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 that 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 latest file version was saved in.
        Returns:
        The identifying key of the commit that the latest file version was saved in.

      • commit

        Commit commit()
        Get the commit that the latest file version was saved in.
        Returns:
        The commit that the latest 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.

      • itemVersionKey

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

      • itemVersion

        FileItemVersion itemVersion()
        Get the latest version of the file on the branch.
        Returns:
        The latest version of the file on the branch.

      • itemVersionType

        ItemVersionType itemVersionType()
        Query the database for the item version type of the latest file version.
        Returns:
        The item version type of the latest 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.

      • saved

        long saved()
        Query the database for the point-in-time instant when the latest file version was saved in UNIX epoch milliseconds.
        Returns:
        The point-in-time instant when the latest 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 latest file version.
        Returns:
        The current display name of the user that saved the latest 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 latest file version.
        Returns:
        The title of the latest file version.

      • description

        java.lang.String description()
        Query the database for the description of the latest file version, or null if no description has been set.
        Returns:
        The description of the latest 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.

      • assignedTagKeys

        java.util.Collection<ItemKey> assignedTagKeys()
        Query the database for the identifying keys of the tags assigned to the file item.
        Returns:
        The identifying keys of the tags assigned to the file item.

      • assignedTags

        java.util.Collection<AssignedTagResult> assignedTags()
        Query the database for the tags assigned to the file item (their keys and titles).
        Returns:
        The tags assigned to the file item (their keys and titles).

      • commitComment

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

      • get

        GetFileItemVersionResult get()

        Get all of the current data values of the version that is currently the latest version of the file item with respect to the branch 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 (at the risk of the data values becoming stale if a new latest version is saved),

        Returns:
        The current data values for the latest version version of the file item in the branch.

      • updateTitle

        FileItemVersion updateTitle​(java.lang.String title,
                            java.lang.String commitComment)

        Set a new title for the file. A new file version will be saved to the branch.

        This does not change any of the filenames of the underlying file resources associated with the file item.

        Parameters:
        title - The new title of the file item.
        commitComment - An optional comment for the associated commit. Pass null to not write a commit comment.
        Returns:
        The saved file version.

      • update

        FileItemVersion update​(UpdateFileItemParam updateFileItemParam,
                       java.lang.String commitComment)
        Save a new version of the file by updating, for example, its title or assigned tags.
        Parameters:
        updateFileItemParam - Input parameters for the save.
        commitComment - An optional comment for the associated commit. Pass null to not write a commit comment.
        Returns:
        The saved file version.

      • assignTag

        Commit assignTag​(ItemKey itemKey,
                 java.lang.String commitComment)

        Assign a tag to the file. Any currently assigned tags will be left unmodified.

        The root tag is automatically unassigned when other tags are assigned to the file. Explicitly assigning the root tag is not allowed.

        Parameters:
        itemKey - The identifying key of the tag that will be assigned to the file.
        commitComment - An optional comment for the associated commit. Pass null to not write a commit comment.
        Returns:
        The saved commit.

      • setAssignedTags

        Commit setAssignedTags​(SetAssignedTagsParam setAssignedTagsParam,
                       java.lang.String commitComment)

        Modify the assigned tags of the file.

        The root tag is automatically assigned if no other tags are assigned to the file, and automatically unassigned when other tags are assigned to the file. Explicitly specifying the root tag when modifying the assigned tags of the file is not allowed.

        Parameters:
        setAssignedTagsParam - Input parameters for the tag reassignment.
        commitComment - An optional comment for the associated commit. Pass null to not write a commit comment.
        Returns:
        The saved commit.

      • delete

        Commit delete​(java.lang.String commitComment)
        Delete the file on the branch.
        Parameters:
        commitComment - An optional comment for the associated commit. Pass null to not write a commit comment.
        Returns:
        The saved commit.

      • queryVersionHistory

        QueryItemVersionHistoryResultStream queryVersionHistory()

        Query the version history of the file with respect to the current branch. The returned versions are sorted chronologically with newer versions appearing before older versions. If the branch was created from a parent branch, versions saved on that parent branch before the branch was created are appended last to the stream. This continues until reaching the first branch in the repository. If the file itself was created from another, origin, file via 'Save as New', the version history of the origin file saved before the current file was created are then appended last to the stream. This also continues until reaching a file without an origin.

        The query returns a result stream of data values for matching 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 — Database.fileVersionByKey(ItemVersionKey).

        To query all versions of the file, irrespective of repository and branch, see FileItem.queryVersions().

        Returns:
        A result stream with the data values for the historical file versions that matched the query.
        See Also:
        DatabaseApiResultStream

      • queryVersionReferences

        QueryItemVersionReferenceResultStream queryVersionReferences()

        Query the item version references for the latest file version (with respect to the current branch) 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 latest file version or that are referencing the latest file version (with respect to the current branch). 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 latest version of the file item 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 latest version of the file item.

        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.