Package com.comsol.api.database.param

Interface SourceFileParamGenerator

  • All Superinterfaces:
    DatabaseApiValue, SourceFileParam
    public interface SourceFileParamGenerator
extends SourceFileParam

    A generator for input parameters used to specify one or more source files to be used as file resources for a saved file version.

    The source files may be specified using one of the following options:

    1. An absolute path to a source location expressed as either a file system path or a file scheme path. 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. See withLocation(String), withLocationModel(String), and withItemVersionWorkingCopy(java.lang.String, java.lang.String).
    2. A file resource path identifying one or more file resources belonging to an existing file version in a Model Manager database. The path may either correspond to a specific file resource or to a parent directory of file resources. The source file version need not be stored in the same database as the one the new file version will be saved to. See withFileResourcePath(java.lang.String...), withItemVersionKey(ItemVersionKey) and withDatabaseKey(DatabaseKey).

    The file resource paths for the file resources saved with the file version are constructed using the following rules:

    A few examples:

    • Source location: C:\\my_folder\my_file.txt. No custom target path. Result path: my_file.txt.
    • Source location: common:///my_folder/my_file.txt. No custom target path. Resul patht: my_file.txt.
    • Source location: C:\\my_folder, with the folder containing file1.txt, file2.txt, and my_subfolder\\file3.txt. No custom target path. Result paths: file1.txt, file2.txt, my_subfolder/file3.txt.
    • Source location: C:\\my_folder\my_file.txt. Custom target path: my_renamed_file.txt. Result path: my_renamed_file.txt.
    • Source location: common:///my_folder, with the folder containing file1.txt, file2.txt, and my_subfolder/file3.txt. Custom target path: custom_subfolder. Result paths: custom_subfolder/file1.txt, custom_subfolder/file2.txt, custom_subfolder/my_subfolder/file3.txt.

    • Method Detail

      • withLocation

        SourceFileParamGenerator withLocation​(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 withLocationModel(String). The dbfile file scheme is used when saving the contents of a working copy directory for a file version — prefer using the specialized withItemVersionWorkingCopy(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.

      • withLocationModel

        SourceFileParamGenerator withLocationModel​(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 withTargetFileResourcePath(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.

      • withItemVersionWorkingCopy

        default SourceFileParamGenerator withItemVersionWorkingCopy​(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 withTargetFileResourcePath(java.lang.String...), any model object feature in the model identified via withLocationModel(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 withLocation(String) and withLocationModel(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.

      • withItemVersionWorkingCopy

        default SourceFileParamGenerator withItemVersionWorkingCopy​(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 withTargetFileResourcePath(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 withLocationModel(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 withLocation(String) and withLocationModel(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.

      • withFileResourcePath

        default SourceFileParamGenerator withFileResourcePath​(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 withItemVersionKey(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.

      • withFileResourcePath

        SourceFileParamGenerator withFileResourcePath​(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 withItemVersionKey(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.

      • withDatabaseKey

        SourceFileParamGenerator withDatabaseKey​(DatabaseKey databaseKey)
        Set the identifying key of the Model Manager database containing the file version set via withItemVersionKey(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.

      • withTargetFileResourcePath

        default SourceFileParamGenerator withTargetFileResourcePath​(java.lang.String... fileResourcePathSegments)

        Set the relative path segments for the saved file resources. May be skipped if the file resource path should be automatically inferred from the source.

        If the source corresponds to a single file, the path will be used for the saved file resource as-is. If the source corresponds to a directory, the path will be used as the root directory for saved file resources.

        Parameters:
        fileResourcePathSegments - The relative path segments to be used for the saved file resources.
        Returns:
        A copy of this instance.

      • withTargetFileResourcePath

        SourceFileParamGenerator withTargetFileResourcePath​(FileResourcePath fileResourcePath)

        Set the file resource path for the saved file resources. May be skipped if the file resource path should be automatically inferred from the source.

        If the source corresponds to a single file, the path will be used for the saved file resource as-is. If the source corresponds to a directory, the path will be used as the root directory for saved file resources.

        Parameters:
        fileResourcePath - The file resource path to be used for the saved file resources.
        Returns:
        A copy of this instance.