Package com.comsol.api.database.param

Interface SaveFileItemParamGenerator

  • All Superinterfaces:
    DatabaseApiValue, SaveFileItemParam, SaveItemParam
    public interface SaveFileItemParamGenerator
extends SaveFileItemParam

    A generator for input parameters used when saving a file item in a Model Manager database. This includes both creating a new file item and updating an existing file item. A new version of the file item will be saved on the targeted branch.

    The various input parameters used when saving a file item fall into three categories:

    1. Simple data parameters that can be used to explicitly set various fields on the saved file. Examples include the title, description, or tag assignments of the file. These parameters may be skipped, in which case the corresponding field values are automatically inferred from the source or target of the save (see the other categories).
    2. Parameters that specify a source for field values and file resources for the saved file version. Examples include the identifying key of a file version (not necessarily found in the same Model Manager database as being saved to), the locations of one or more data files stored on the file system, or file resources belonging to the latest version of the file item to be saved. If no source is specified, only simple fields as specified by the previous category will be updated by the save.
    3. Parameters that specify the file item that will be the target of the save. May be skipped, in which case an attempt is made to automatically infer the target from the source (see the previous category).

    The file resources of the saved file version may be specified using one of the following options:

    1. A collection of input parameters of type SourceFileParam identifying one or more individual sources for the file resources. The sources may, for example, include files on the file system or file resources belonging to other file versions, possibly in other databases. See withSourceFiles(Collection). Files on the file system may be specified using either file system paths or file scheme paths. An important special case are files exported from a model object to a so-called item version working copy, see withSourceItemVersionWorkingCopy(java.lang.String, java.lang.String, com.comsol.api.database.FileResourcePath...).
    2. An existing source file version stored in a Model Manager database. All file resources belonging to that file version will be reused in their entirety for the new file version. The source file version need not be stored in the same database as the new file version will be saved to. See withSourceItemVersionKey(ItemVersionKey) and withSourceDatabaseKey(DatabaseKey).
    3. A collection of input parameters of type TargetFileResourceParam identifying one or more file resources to update or delete among the existing file resources for the latest version of the saved file item. File resources remaining after such updates and deletes will be included for the saved file version.

    The target file for the save, unless it is to be implicitly inferred by a source file version, may be specified using one of the following options:

    1. Explicitly setting the identifying key of the file that will be updated. See withTargetItemKey(ItemKey). The target file need not be the same as the source file.
    2. Forcing the creation of a new file item. See withTargetItemSaveMode(TargetItemSaveMode).

    A new file item will be created in the database if neither a target has been explicitly set, nor can it be implicitly inferred by the source file version.

    By default, version conflicts will automatically fail the save in its entirety. Use withIgnoreConflicts() to force the save to go through despite conflicts.

    See Also:
    SourceFileParamGenerator

    • Method Detail

      • withTitle

        SaveFileItemParamGenerator withTitle​(java.lang.String title)

        Set the title to use for the saved file version. May be skipped if the current title should not be explicitly modified (for the case when the file already exists in the target branch) or if the title should be automatically inferred from the source of the save. Must be explicitly set when saving a fileset and a title cannot be uniquely inferred from the source of the save.

        An example when the title is automatically inferred is when saving a file item from a source file version, possibly located in another database.

        Note that the title of the targeted file item is kept unmodified if only updating an existing file item with a new file resource. The title is not automatically set to the filename of the new file resource. Use this method to override that behavior.

        Parameters:
        title - The title to use for the saved file version.
        Returns:
        A copy of this instance.

      • withDescription

        SaveFileItemParamGenerator withDescription​(java.lang.String description)

        Set the description to use for the saved file version. May be skipped if the current description should not be explicitly modified (for the case when the file already exists in the target branch) or if the description should be automatically inferred from the source of the save.

        An example when the description is automatically inferred is when saving a file item from a source file version, possibly located in another database.

        Parameters:
        description - The description to use for the saved file version.
        Returns:
        A copy of this instance.

      • withAssignedTagKeys

        default SaveFileItemParamGenerator withAssignedTagKeys​(ItemKey... itemKeys)

        Provide the identifying keys of all tags that will be set as assigned to the file (with respect to the corresponding commit saved on the target branch). Tags that are currently assigned and whose item keys are not present in the returned collection will be removed (unassigned). Tags that are currently not assigned but whose keys are present in the collection will be added (assigned). May be skipped if the current tag assignments should not be modified (for the case when the file already exists in the target branch). Skipping when creating a new file will automatically assign the root tag to the created file.

        Assigning both the root tag and other tags at the same time is not allowed.

        Parameters:
        itemKeys - The identifying keys of tags.
        Returns:
        A copy of this instance.

      • withAssignedTagKeys

        SaveFileItemParamGenerator withAssignedTagKeys​(java.util.Collection<ItemKey> itemKeys)

        Provide the identifying keys of all tags that will be set as assigned to the file (with respect to the corresponding commit saved on the target branch). Tags that are currently assigned and whose item keys are not present in the returned collection will be removed (unassigned). Tags that are currently not assigned but whose keys are present in the collection will be added (assigned). May be skipped if the current tag assignments should not be modified (for the case when the file already exists in the target branch). Skipping when creating a new file will automatically assign the root tag to the created file.

        Assigning both the root tag and other tags at the same time is not allowed.

        Parameters:
        itemKeys - The identifying keys of tags.
        Returns:
        A copy of this instance.

      • withItemKey

        SaveFileItemParamGenerator withItemKey​(ItemKey itemKey)
        Set the identifying key that will be assigned to the created item when saving a new file item in the database. May be skipped, in which case the key will be derived by the save process. This includes, for example, automatically reusing the source item's key when saving from a source database to a target database. The provided key is ignored when updating an existing file item.
        Parameters:
        itemKey - The identifying item key to assign to the created file item.
        Returns:
        A copy of this instance.
        Since:
        6.3
        See Also:
        ItemKey.generate(ItemType)

      • withItemVersionKey

        SaveFileItemParamGenerator withItemVersionKey​(ItemVersionKey itemVersionKey)
        Set the identifying key that will be assigned to the saved version. May be skipped, in which case an item version key will be automatically generated.
        Parameters:
        itemVersionKey - The identifying item version key to assign to the saved version.
        Returns:
        A copy of this instance.
        Since:
        6.3
        See Also:
        ItemVersionKey.generate(ItemType)

      • withSourceLocations

        default SaveFileItemParamGenerator withSourceLocations​(java.lang.String... locations)

        Set absolute paths locating file resources for the file version to be saved. A path may either point to a single file or to a directory. For the latter case, all files in the directory, and its subdirectories, will be included in the save. A common use case is to pass the absolute path of a single file resource.

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

        Use withSourceFiles(com.comsol.api.database.param.SourceFileParam...) if there is a need to both specify the location of an individual source file and to specify a custom FileResourcePath within the saved file version, or if the source files are specified using model-dependent file schemes (that is, the dbfile, embedded, temp, or upload file schemes). Prefer withSourceItemVersionWorkingCopy(java.lang.String, java.lang.String, com.comsol.api.database.FileResourcePath...) if the source files are all found in the working copy directory of a version-controlled file item (as specified using the dbfile file scheme).

        This method is a special case of withSourceFiles(com.comsol.api.database.param.SourceFileParam...) that delegates to SourceFileParamGenerator.withLocation(String) to create one SourceFileParam per location.

        Parameters:
        locations - Absolute paths locating file resources for the file version to be saved. A path may either point to a single file or to a directory. For the latter case, all files in the directory, and its subdirectories, will be included in the save. A location may be expressed as a file system path, a common file scheme path, or a user file scheme path.
        Returns:
        A copy of this instance.

      • withSourceItemVersionWorkingCopy

        default SaveFileItemParamGenerator withSourceItemVersionWorkingCopy​(java.lang.String modelTag,
                                                                    java.lang.String fileLocationUri,
                                                                    FileResourcePath... fileResourcePaths)

        Set a reference to a working copy of a file version containing one or more source files to be used as file resources for a saved file version. These files 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.

        Any model object feature in the model identified by the provided modelTag 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 withSourceFiles(com.comsol.api.database.param.SourceFileParam...) that delegates to SourceFileParamGenerator.withItemVersionWorkingCopy(java.lang.String, java.lang.String) to create one or more SourceFileParam instances depending on the number of fileResourcePaths arguments.

        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 written using the dbfile file scheme. See also FileResourceResult.fileLocationUri() and Branch.newFileLocationUri(java.lang.String).
        fileResourcePaths - Paths used to match file resources in the working copy that should be included in the save. A path that corresponds to a directory in the working copy directory will match on all file resources inside that directory. Otherwise the path will match on the corresponding path of a file resource. Skip providing any arguments to include all file resources in the working copy.
        Returns:
        A copy of this instance.

      • withSourceFiles

        default SaveFileItemParamGenerator withSourceFiles​(SourceFileParam... sourceFiles)

        Set input parameters specifying the collection of file resources to be saved with the file version.

        The provided SourceFileParam instances may specify file resources using file system paths, file scheme paths (using the common, dbfile, embedded, temp, upload, or user file schemes), or as belonging to file versions in databases.

        Parameters:
        sourceFiles - Input parameters specifying file resources for the file version to be saved.
        Returns:
        A copy of this instance.

      • withSourceFiles

        SaveFileItemParamGenerator withSourceFiles​(java.util.Collection<SourceFileParam> sourceFiles)

        Set input parameters specifying the collection of file resources to be saved with the file version.

        The provided SourceFileParam instances may specify file resources using file system paths, file scheme paths (using the common, dbfile, embedded, temp, upload, or user file schemes), or as belonging to file versions in databases.

        Parameters:
        sourceFiles - Input parameters specifying file resources for the file version to be saved.
        Returns:
        A copy of this instance.

      • withSourceItemVersionKey

        SaveFileItemParamGenerator withSourceItemVersionKey​(ItemVersionKey itemVersionKey)
        Set the identifying key of an existing file version to be used as the source for the save. The file resources belonging to that file version will be used for the saved file version in their entirety. May be combined with a database key set via withSourceDatabaseKey(com.comsol.api.database.DatabaseKey) in case the source file version is found in a database different from the one being saved to. The title and description of the source file version will be used for the saved file version unless explicitly provided as input.
        Parameters:
        itemVersionKey - The identifying key of a file version. The file version may belong to another file item than the target file, also known as save as other.
        Returns:
        A copy of this instance.

      • withSourceDatabaseKey

        SaveFileItemParamGenerator withSourceDatabaseKey​(DatabaseKey databaseKey)
        Set the identifying key of a Model Manager database. This database contains the source file version (as identified by the key set via withSourceItemVersionKey(com.comsol.api.database.ItemVersionKey)) whose file resources will be used as input for the saved file version. May be skipped 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.

      • withTargetFileResources

        default SaveFileItemParamGenerator withTargetFileResources​(TargetFileResourceParam... targetFileResources)

        Set input parameters specifying target file resources to be updated or deleted among the existing file resources found for the latest version of the saved file item.

        The provided TargetFileResourceParam instances may specify file resources using file system paths, file scheme paths (using the common, dbfile, embedded, temp, upload, or user file schemes), or as belonging to file versions in databases.

        Note that the target file resources are not guaranteed to be processed in the provided order. An exception is thrown if there is a collision or overlap for the update and removal of file resources.

        Parameters:
        targetFileResources - Input parameters specifying target file resources to update or delete for the file version.
        Returns:
        A copy of this instance.
        Since:
        6.4

      • withTargetFileResources

        SaveFileItemParamGenerator withTargetFileResources​(java.util.Collection<TargetFileResourceParam> targetFileResources)

        Set input parameters specifying target file resources to be updated or deleted among the existing file resources found for the latest version of the saved file item.

        The provided TargetFileResourceParam instances may specify file resources using file system paths, file scheme paths (using the common, dbfile, embedded, temp, upload, or user file schemes), or as belonging to file versions in databases.

        Note that the target file resources are not guaranteed to be processed in the provided order. An exception is thrown if there is a collision or overlap for the update and removal of file resources.

        Parameters:
        targetFileResources - Input parameters specifying target file resources to update or delete for the file version.
        Returns:
        A copy of this instance.
        Since:
        6.4

      • withTargetItemKey

        SaveFileItemParamGenerator withTargetItemKey​(ItemKey targetItemKey)

        Set the identifying key of a file item in the target database that will be updated by the save. May be skipped if the file item should be identified by the source file version set via withSourceItemVersionKey(com.comsol.api.database.ItemVersionKey), if it should be (uniquely) identified by a file version corresponding to one of the source files set via withSourceFiles(com.comsol.api.database.param.SourceFileParam...), or if a new file is to be created.

        A new file item will be created using the provided key as its assigned key if the target file item is not found in the database, as long as a source for field values and file resources has been provided via other input parameters. A latest version of the target file item must exist on the branch if no such source data is provided, otherwise an exception is thrown.

        Parameters:
        targetItemKey - The identifying key of a file item.
        Returns:
        A copy of this instance.

      • withTargetAsNew

        default SaveFileItemParamGenerator withTargetAsNew()
        Set that a new file item should be forcibly created in the database even if a target file item has been implicitly inferred by the source of the save. Must not be set if a target file has been explicitly set to be updated by the save via withTargetItemKey(ItemKey).
        Returns:
        A copy of this instance.

      • withTargetItemSaveMode

        SaveFileItemParamGenerator withTargetItemSaveMode​(TargetItemSaveMode targetItemSaveMode)
        Set the save mode for the target file item of the save. May be used to optionally force the creation of a new file item in the database even if a target file item may be implicitly inferred by the source of the save. Must not be set if a target file has been explicitly set to be updated by the save via withTargetItemKey(ItemKey).
        Parameters:
        targetItemSaveMode - The save mode for the target file item of the save.
        Returns:
        A copy of this instance.

      • withIgnoreConflicts

        default SaveFileItemParamGenerator withIgnoreConflicts()

        Set that any version conflicts encountered when saving should be ignored.

        A version conflict arises, for example, if the file version identified by one of the various source-methods does not correspond to the latest version of its file, and that same file is also the target for the save.

        Returns:
        A copy of this instance.

      • withTargetItemConflictMode

        SaveFileItemParamGenerator withTargetItemConflictMode​(TargetItemConflictMode targetItemConflictMode)

        Specify what should happen if any version conflicts are encountered when saving. Defaults to TargetItemConflictMode.THROW_ON_CONFLICT if not set (in which case the save will be automatically cancelled if a conflict is encountered).

        A version conflict arises, for example, if the file version identified by one of the various source-methods does not correspond to the latest version of its file, and that same file is also the target for the save.

        Parameters:
        targetItemConflictMode - The mode for handling version conflicts with the target file item.
        Returns:
        A copy of this instance.