Package com.comsol.api.database.param

Interface TargetFileResourceParamGenerator

  • All Superinterfaces:
    DatabaseApiValue, TargetFileResourceParam
    public interface TargetFileResourceParamGenerator
extends TargetFileResourceParam

    A generator for input parameters used to specify a target file resource, or a directory of target file resources, to be either updated or deleted among the existing file resources found for the latest version of a file item when saving a new file version.

    Providing input parameters via a TargetFileResourceParamGenerator when saving a file item differs from providing parameters via a SourceFileParamGenerator in that the former allows for partial updates to the current collection of file resources, while the latter always overwrites with a new collection. If a source file is specified via one of the input parameters, the target file resource will be updated in the collection. If no source file is specified, the target file resource is instead deleted from the collection. The behavior when a target file resource expected to be either updated or deleted is not found in the current collection is determined by the TargetFileResourceUpdateMode passed to withUpdateMode(TargetFileResourceUpdateMode).

    Since:
    6.4

    • Method Detail

      • withSourceLocation

        TargetFileResourceParamGenerator withSourceLocation​(java.lang.String location)

        Set the absolute path to a source location containing files to be saved with the file version. The location may either point to a single file or to a directory. For the latter case, all files in the directory, or its subdirectories, will be included in the save.

        If the location corresponds to a single file, its filename will be used to create the corresponding FileResourcePath. If the location corresponds to a directory, the relative path of a file found inside the directory will be used to create the corresponding FileResourcePath.

        The location may either be a file system path or a file scheme path. Supported file schemes are:

        • common
        • dbfile
        • embedded
        • temp
        • upload
        • user

        The dbfile, embedded, temp, and upload file schemes all require that a model tag identifier of a model has been specified via withSourceLocationModel(String). The dbfile file scheme is used when saving the contents of a working copy directory for a file version — prefer using the specialized withSourceItemVersionWorkingCopy(java.lang.String, java.lang.String) for that case.

        See also the section File Schemes and File Handling in the chapter Working with Methods in the Application Builder Reference Manual.

        Parameters:
        location - An absolute path to a file or directory as either a file system path or a file scheme path.
        Returns:
        A copy of this instance.

      • withSourceLocationModel

        TargetFileResourceParamGenerator withSourceLocationModel​(java.lang.String modelTag)

        Set the model tag identifying a model that implicitly determines the root directory for the source location whenever the latter is expressed by a file scheme.

        If the source location corresponds to a working copy root directory — that is, it uses the dbfile file scheme — and a custom target path has not been set via withFileResourcePath(java.lang.String...), any model object feature in the model that reference the source files will be automatically updated to instead reference the file resources in the saved file version. If the model itself is also saved as a new version in the same commit — that is, saving via Branch.saveCommit(com.comsol.api.database.param.SaveCommitParam) — the model object is updated before it is saved to the database.

        Parameters:
        modelTag - The tag identifier of a model. See also ModelEntity.tag(). Note, this string identifier should not be confused with a tag item found in the database.
        Returns:
        A copy of this instance.

      • withSourceItemVersionWorkingCopy

        default TargetFileResourceParamGenerator withSourceItemVersionWorkingCopy​(java.lang.String modelTag,
                                                                          java.lang.String fileLocationUri)

        Set a reference to a working copy of a file version containing file resources for the file version to be saved. These file resources may, for example, have been exported as output by a feature in the model object.

        A file version referenced as auxiliary data by a model object — either as an input source or an output target — are loaded on-demand from the database to a temporary working copy directory located on the computer running COMSOL Multiphysics. Any input read by the model, and any output written by the model, goes via files in this directory. The reference is typically specified by providing a file location URI as the argument for a filename property on a model object feature. The file location URI itself is either obtained from FileResourceResult.fileLocationUri() in the case of an existing file version or from Branch.newFileLocationUri(java.lang.String) in the case of a new, but not yet created, file item.

        If a custom target path has not been set via withFileResourcePath(java.lang.String...), any model object feature in the model identified via withSourceLocationModel(String) that reference the source files will be automatically updated to instead reference the file resources in the saved file version. If the model itself is also saved as a new version in the same commit — that is, saving via Branch.saveCommit(com.comsol.api.database.param.SaveCommitParam) — the model object is updated before it is saved to the database.

        This method is a special case of combining withSourceLocation(String) and withSourceLocationModel(String) such that the source location corresponds to the working copy root directory itself.

        Parameters:
        modelTag - The model tag of a model that is currently loaded in COMSOL Multiphysics and that is associated with the working copy. The model may, for example, have exported files to the working copy's root directory or one its subdirectories. See also ModelEntity.tag(). Note, this should not be confused with a tag item found in the Model Manager database.
        fileLocationUri - A location URI identifier for the file version. See also FileResourceResult.fileLocationUri() and Branch.newFileLocationUri(java.lang.String).
        Returns:
        A copy of this instance.

      • withSourceItemVersionWorkingCopy

        default TargetFileResourceParamGenerator withSourceItemVersionWorkingCopy​(java.lang.String modelTag,
                                                                          java.lang.String fileLocationUri,
                                                                          FileResourcePath fileResourcePath)

        Set a reference to a working copy of a file version containing file resources for the file version to be saved. These file resources may, for example, have been exported as output by a feature in the model object.

        A file version referenced as auxiliary data by a model object — either as an input source or an output target — are loaded on-demand from the database to a temporary working copy directory located on the computer running COMSOL Multiphysics. Any input read by the model, and any output written by the model, goes via files in this directory. The reference is typically specified by providing a file location URI as the argument for a filename property on a model object feature. The file location URI itself is either obtained from FileResourceResult.fileLocationUri() in the case of an existing file version or from Branch.newFileLocationUri(java.lang.String) in the case of a new, but not yet created, file item.

        If a custom target path has not been set via withFileResourcePath(java.lang.String...) and the provided fileResourcePath is either null or the working copy root directory, any model object feature in the model identified via withSourceLocationModel(String) that reference the source files will be automatically updated to instead reference the file resources in the saved file version. If the model itself is also saved as a new version in the same commit — that is, saving via Branch.saveCommit(com.comsol.api.database.param.SaveCommitParam) — the model object is updated before it is saved to the database.

        This method is a special case of combining withSourceLocation(String) and withSourceLocationModel(String) such that the source location corresponds to a path inside the working copy directory. That path may either match a specific file resource or a parent directory to file resources.

        Parameters:
        modelTag - The model tag of a model that is currently loaded in COMSOL Multiphysics and that is associated with the working copy. The model may, for example, have exported files to the working copy's root directory or one its subdirectories. See also ModelEntity.tag(). Note, this should not be confused with a tag item found in the Model Manager database.
        fileLocationUri - A location URI identifier for the file version. See also FileResourceResult.fileLocationUri() and Branch.newFileLocationUri(java.lang.String).
        fileResourcePath - A path matching file resources in the working copy. The path may either correspond to a specific file resource or to a parent directory of file resources. Pass null to match the working copy root directory itself.
        Returns:
        A copy of this instance.

      • withSourceFileResourcePath

        default TargetFileResourceParamGenerator withSourceFileResourcePath​(java.lang.String... fileResourcePathSegments)

        Set the relative path segments identifying one or more file resources belonging to a file version stored in a Model Manager database. Those file resources will be used as the source for the saved file resources. The file version itself is identified by the item version key set via withSourceItemVersionKey(ItemVersionKey).

        May be skipped if all file resources of the file version should be automatically included.

        Parameters:
        fileResourcePathSegments - The relative path segments identifying one or more file resources belonging to a file version. The path may either correspond to a specific file resource or to a parent directory of file resources.
        Returns:
        A copy of this instance.

      • withSourceFileResourcePath

        TargetFileResourceParamGenerator withSourceFileResourcePath​(FileResourcePath fileResourcePath)
        Set the file resource path identifying one or more file resources belonging to a file version stored in a Model Manager database. Those file resources will be used as the source for the saved file resources. The file version itself is identified by the item version key set via withSourceItemVersionKey(ItemVersionKey). May be skipped if all file resource of the file version should be included with the save.
        Parameters:
        fileResourcePath - A file resource path identifying one or more file resources belonging to a file version. The path may either correspond to a specific file resource or to a parent directory of file resources.
        Returns:
        A copy of this instance.

      • withSourceDatabaseKey

        TargetFileResourceParamGenerator withSourceDatabaseKey​(DatabaseKey databaseKey)
        Set the identifying key of the Model Manager database containing the file version set via withSourceItemVersionKey(ItemVersionKey). May be skipped if the source is specified by a location or if the source file version is found in the target database for the save.
        Parameters:
        databaseKey - The identifying key of a Model Manager database.
        Returns:
        A copy of this instance.

      • withFileResourcePath

        default TargetFileResourceParamGenerator withFileResourcePath​(java.lang.String... fileResourcePathSegments)

        Set the relative path segments for the file resource path identifying the target file resource, or directory of target file resources, to update or delete in the collection of existing file resources. May be skipped if the file resource path should be automatically inferred from the source.

        Parameters:
        fileResourcePathSegments - The relative path segments for the file resource path that identifies the target file resources.
        Returns:
        A copy of this instance.

      • withFileResourcePath

        TargetFileResourceParamGenerator withFileResourcePath​(FileResourcePath fileResourcePath)

        Set the file resource path identifying the target file resource, or directory of target file resources, to update or delete in the collection of existing file resources. May be skipped if the file resource path should be automatically inferred from the source.

        Parameters:
        fileResourcePath - The file resource path that identifies the target file resources.
        Returns:
        A copy of this instance.

      • withCreateIfNotExists

        default TargetFileResourceParamGenerator withCreateIfNotExists()
        Set the update mode to create a file resource that does not exist, or replace the file resource if it does exist.
        Returns:
        A copy of this instance.

      • withCreateNew

        default TargetFileResourceParamGenerator withCreateNew()
        Set the update mode to create a file resource that does not exist, or throw if the file resource does exist.
        Returns:
        A copy of this instance.

      • withDeleteIfExists

        default TargetFileResourceParamGenerator withDeleteIfExists()
        Set the update mode to delete a file resource that exists, or do nothing if the file resource does not exist.
        Returns:
        A copy of this instance.

      • withDeleteExisting

        default TargetFileResourceParamGenerator withDeleteExisting()
        Set the update mode to delete a file resource that exists, or throw if the file resource does not exist.
        Returns:
        A copy of this instance.

      • withReplaceExisting

        default TargetFileResourceParamGenerator withReplaceExisting()
        Set the update mode to replace a file resource that exists, or throw if the file resource does not exist.
        Returns:
        A copy of this instance.