Package com.comsol.model.util

Class ModelUtil

  • public class ModelUtil
extends java.lang.Object
    Class with static methods for managing models.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static com.comsol.model.util.impl.IModelUtilImpl clientImpl
      Implementation delegate.
      private static com.comsol.model.util.impl.IModelUtilImpl methodExecImpl
      Implementation delegate.
      private static com.comsol.model.util.impl.IModelUtilImpl serverImpl
      Implementation delegate.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ModelUtil()
      Static class not intended to be instantiated.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void blockOtherClients​(boolean blockOtherClients)
      Tells the server to block or unblock other clients.
      static boolean checkoutLicense​(java.lang.String... product)
      Check out one license for each of the specified products.
      static boolean checkoutLicenseForFile​(java.lang.String file)
      Check out required products for an mph file.
      static boolean checkoutLicenseForFileOnServer​(java.lang.String file)
      Check out required products for an mph file located on the server filesystem.
      static void clear()
      Tries to remove all models.
      static void closeWindow​(java.lang.String tag)
      Closes a specific graphics window on the server.
      static void closeWindows()
      Closes all graphics windows on the server.
      static void connect()
      Connects to a server.
      static void connect​(java.lang.String host, int port)
      Connects to a server using the specified host and port.
      static void connect​(java.lang.String host, int port, boolean encryption)
      Connects to a server using the specified host, port, and encryption.
      static void connect​(java.lang.String host, int port, boolean encryption, java.lang.String user, java.lang.String passWord)
      Connects to a server using the specified host, port, encryption, user, and password.
      static void connect​(java.lang.String host, int port, java.lang.String user, java.lang.String passWord)
      Connects to a server using the specified host, port, user, and password.
      static Model create​(java.lang.String tag)
      Create a model.
      static Model createUnique​(java.lang.String prefix)
      Create a model with a unique tag that begins with a prefix.
      static void disconnect()
      Disconnects from the server.
      static java.lang.String getComsolVersion()
      Returns the current version of COMSOL.
      static java.lang.String getDefaultGeometryKernel()
      Return the default geometry kernel.
      static java.lang.String getEntityPath​(PrimitiveModelEntity entity, java.lang.String divider)
      Creates the path from the root of the model object for the given entity.
      static java.lang.String getOpenGeometryKernel()
      Returns the geometry kernel to use when opening a model.
      static java.lang.String getPreference​(java.lang.String prefName)
      Returns the value of a preference.
      static java.lang.String getRecoveryDir​(java.lang.String tag)
      Returns a path to the recovery directory for a model.
      static java.lang.String[] getStringArrayPreference​(java.lang.String prefName)
      Returns the value of a string array preference.
      static boolean hasProduct​(java.lang.String... product)
      Return true if the license allows to run the specified products.
      static boolean hasProductForFile​(java.lang.String file)
      Return true if the license contains products required to open an mph file.
      static boolean hasProductForFileOnServer​(java.lang.String file)
      Return true if the license contains products required to open an mph file located on the server filesystem.
      (package private) static com.comsol.model.util.impl.IModelUtilImpl impl()  
      static void initStandalone​(boolean guiSupport)
      Initializes the environment for using the COMSOL API from a Java application.
      static void initStandalone​(boolean guiInSupport, java.lang.String graphicsToolkit)
      Initializes the environment for using the COMSOL API from a Java application.
      static java.lang.String listPreferences()
      Returns a string which lists the preferences's names and their description.
      static Model load​(java.lang.String tag, java.lang.String modelLocation)
      Load a model from a model location, either a file path or a dbmodel URI.
      static Model loadCopy​(java.lang.String tag, java.lang.String filename)
      Load a copy of a model.
      static Model loadOnServer​(java.lang.String tag, java.lang.String filename)
      Load a model from a server file.
      static void loadPreferences()
      Loads the COMSOL preferences file.
      static Model loadProtected​(java.lang.String tag, java.lang.String filename, java.lang.String password)
      Load a model with password protection.
      static Model loadProtectedOnServer​(java.lang.String tag, java.lang.String filename, java.lang.String password)
      Load a model with password protection from a server file.
      static Model loadRecovery​(java.lang.String tag, java.lang.String foldername)
      Load a model from a recovery directory/folder structure.
      static Model model​(java.lang.String tag)
      Returns the model with a specified tag.
      static java.lang.String[] modelsUsedByOtherClients()
      Returns the tags of the models in use by other clients.
      static void remove​(java.lang.String tag)
      Tries to remove the model with the specified tag.
      static void savePreferences()
      Saves the COMSOL preferences file.
      static java.lang.String[][] scanModel​(java.lang.String filename, java.lang.String type, java.lang.String... extraAttributes)
      An advanced tool that scans the raw data (XML) of the model file for a certain node type and collect the tag and label of all found nodes.
      static java.lang.String[][] scanProtectedModel​(java.lang.String filename, java.lang.String type, java.lang.String password, java.lang.String... extraAttributes)
      Scans the protected model file for a certain node type.
      static void serverDisplay​(java.lang.String message)
      Prints a message in the server terminal window.
      static void serverLog​(java.lang.String message)
      Prints a message in COMSOL's log file on the server.
      static void setDefaultGeometryKernel​(java.lang.String defaultKernel)
      Specifies the default geometry kernel to use.
      (package private) static void setMethodExecImpl​(com.comsol.model.util.impl.IModelUtilImpl impl)
      Set the methodExecImpl instance.
      static void setModelChangedHandler​(ModelChangedHandler modelChangedHandler)
      Register a handler of changes to models made by other clients.
      static void setOpenGeometryKernel​(java.lang.String openKernel)
      Specifies geometry kernel to use when opening a model.
      static void setPreference​(java.lang.String prefName, java.lang.String value)
      Sets a preference value.
      static void setPreference​(java.lang.String prefName, java.lang.String[] value)
      Sets a string array preference value.
      static void setServerBusyHandler​(ServerBusyHandler serverBusyHandler)
      Several clients can be connected to the same server, but only one client at a time can ask the server to perform an operation.
      static void showPlots​(boolean show)
      Specifies whether to show plots when connected to a graphics server.
      static boolean showProgress​(boolean progress)
      Specifies if progress should be shown on the server.
      static void showProgress​(java.lang.String fileName)
      Specifies file to log progress to.
      static java.lang.String[] tags()
      Return the tags of all models.
      static java.lang.String uniquetag​(java.lang.String prefix)
      Create a tag that is not in use by any model.
      static boolean useRecovery()
      Checks if usage of recovery file is enabled.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • clientImpl

        private static com.comsol.model.util.impl.IModelUtilImpl clientImpl
        Implementation delegate.

      • serverImpl

        private static com.comsol.model.util.impl.IModelUtilImpl serverImpl
        Implementation delegate.

      • methodExecImpl

        private static com.comsol.model.util.impl.IModelUtilImpl methodExecImpl
        Implementation delegate.

    • Constructor Detail

      • ModelUtil

        private ModelUtil()
        Static class not intended to be instantiated.

    • Method Detail

      • impl

        static com.comsol.model.util.impl.IModelUtilImpl impl()

      • setMethodExecImpl

        static void setMethodExecImpl​(com.comsol.model.util.impl.IModelUtilImpl impl)
        Set the methodExecImpl instance.

      • create

        public static Model create​(java.lang.String tag)
        Create a model.
        Parameters:
        tag - The model's tag. If there is already another model with this tag, that model will be removed. This unless the old model is in use by another client. If that is the case an exception is thrown.
        Returns:
        The new model.

      • createUnique

        public static Model createUnique​(java.lang.String prefix)
        Create a model with a unique tag that begins with a prefix.
        Parameters:
        prefix - The tag prefix.
        Returns:
        The new model.

      • remove

        public static void remove​(java.lang.String tag)
        Tries to remove the model with the specified tag. If the model is not in use by any other client the model is removed immediately. If another client uses the model, the model is retained but is marked that this client no longer use it. When the last client request a removal of the model, it is finally removed.
        Parameters:
        tag - The model's tag.

      • clear

        public static void clear()
        Tries to remove all models. All models not in use by any other client the model are removed immediately. If another client uses any model, that model is retained but is marked that this client no longer use it. When the last client request a removal of the model, it is finally removed.

      • tags

        public static java.lang.String[] tags()
        Return the tags of all models.
        Returns:
        The model tags.

      • uniquetag

        public static java.lang.String uniquetag​(java.lang.String prefix)
        Create a tag that is not in use by any model.
        Parameters:
        prefix - The prefix which the tag should begin with.
        Returns:
        The tag.

      • getEntityPath

        public static java.lang.String getEntityPath​(PrimitiveModelEntity entity,
                                             java.lang.String divider)
        Creates the path from the root of the model object for the given entity.
        Parameters:
        entity - The entity to get the path for.
        divider - Divider to use between entities in path.

      • modelsUsedByOtherClients

        public static java.lang.String[] modelsUsedByOtherClients()
        Returns the tags of the models in use by other clients. These tags cannot be used when creating or loading a model.
        Returns:
        Model tags.

      • model

        public static Model model​(java.lang.String tag)
        Returns the model with a specified tag.
        Parameters:
        tag - The model's tag.
        Returns:
        The model.

      • load

        public static Model load​(java.lang.String tag,
                         java.lang.String modelLocation)
                  throws java.io.IOException
        Load a model from a model location, either a file path or a dbmodel URI.
        Parameters:
        tag - The model's tag. If there is already another model with this tag, that model will be removed. This unless the old model is in use by another client. If that is the case an exception is thrown.
        modelLocation - The location of the model, either a file path or a dbmodel URI.
        Returns:
        The loaded model.
        Throws:
        java.io.IOException - if the file cannot be read.

      • loadOnServer

        public static Model loadOnServer​(java.lang.String tag,
                                 java.lang.String filename)
                          throws java.io.IOException
        Load a model from a server file.
        Parameters:
        tag - The model's tag. If there is already another model with this tag, that model will be removed. This unless the old model is in use by another client. If that is the case an exception is thrown.
        filename - The model file path on the server.
        Returns:
        The loaded model.
        Throws:
        java.io.IOException - if the file cannot be read.

      • loadProtected

        public static Model loadProtected​(java.lang.String tag,
                                  java.lang.String filename,
                                  java.lang.String password)
                           throws java.io.IOException
        Load a model with password protection.
        Parameters:
        tag - The model's tag. If there is already another model with this tag, that model will be removed. This unless the old model is in use by another client. If that is the case an exception is thrown.
        filename - The model file path.
        password - The password required to load the model.
        Returns:
        The loaded model.
        Throws:
        java.io.IOException - if the file cannot be read.

      • loadProtectedOnServer

        public static Model loadProtectedOnServer​(java.lang.String tag,
                                          java.lang.String filename,
                                          java.lang.String password)
                                   throws java.io.IOException
        Load a model with password protection from a server file.
        Parameters:
        tag - The model's tag. If there is already another model with this tag, that model will be removed. This unless the old model is in use by another client. If that is the case an exception is thrown.
        filename - The model file path on the server.
        password - The password required to load the model.
        Returns:
        The loaded model.
        Throws:
        java.io.IOException - if the file cannot be read.

      • loadCopy

        public static Model loadCopy​(java.lang.String tag,
                             java.lang.String filename)
                      throws java.io.IOException
        Load a copy of a model. To save the model a new filename much be provided.
        Parameters:
        tag - The model's tag. If there is already another model with this tag, that model will be removed. This unless the old model is in use by another client. If that is the case an exception is thrown.
        filename - The model file path.
        Returns:
        The loaded model.
        Throws:
        java.io.IOException - if the file cannot be read.

      • loadRecovery

        public static Model loadRecovery​(java.lang.String tag,
                                 java.lang.String foldername)
                          throws java.io.IOException
        Load a model from a recovery directory/folder structure.
        Parameters:
        tag - The model's tag. If there is already another model with this tag, that model will be removed. This unless the old model is in use by another client. If that is the case an exception is thrown.
        foldername - The recovery folder path.
        Returns:
        The loaded model.
        Throws:
        java.io.IOException - if the file cannot be read.

      • connect

        public static void connect()
        Connects to a server.

      • connect

        public static void connect​(java.lang.String host,
                           int port)
        Connects to a server using the specified host and port.
        Parameters:
        host - The server host computer.
        port - The port to use.

      • connect

        public static void connect​(java.lang.String host,
                           int port,
                           boolean encryption)
        Connects to a server using the specified host, port, and encryption.
        Parameters:
        host - The server host computer.
        port - The port to use.
        encryption - If true, use a secure connection.

      • connect

        public static void connect​(java.lang.String host,
                           int port,
                           java.lang.String user,
                           java.lang.String passWord)
        Connects to a server using the specified host, port, user, and password.
        Parameters:
        host - The server host computer.
        port - The port.
        user - The user name.
        passWord - The password.

      • connect

        public static void connect​(java.lang.String host,
                           int port,
                           boolean encryption,
                           java.lang.String user,
                           java.lang.String passWord)
        Connects to a server using the specified host, port, encryption, user, and password.
        Parameters:
        host - The server host computer.
        port - The port.
        encryption - If true, use a secure connection.
        user - The user name.
        passWord - The password.

      • disconnect

        public static void disconnect()
        Disconnects from the server.

      • closeWindows

        public static void closeWindows()
        Closes all graphics windows on the server.

      • closeWindow

        public static void closeWindow​(java.lang.String tag)
        Closes a specific graphics window on the server.
        Parameters:
        tag - The window's tag.

      • showProgress

        public static boolean showProgress​(boolean progress)
        Specifies if progress should be shown on the server.
        Parameters:
        progress - Whether to show progress.
        Returns:
        true if change of progress display was applied successfully.

      • showProgress

        public static void showProgress​(java.lang.String fileName)
        Specifies file to log progress to.
        Parameters:
        fileName - name of file.

      • showPlots

        public static void showPlots​(boolean show)
        Specifies whether to show plots when connected to a graphics server. When not connected to a graphics server, this method does nothing.

        ModelUtil.showPlots(false) does not close any open windows. To close windows, use closeWindow(String) or closeWindows().

        Parameters:
        show - Whether or not to show plots.

      • setOpenGeometryKernel

        public static void setOpenGeometryKernel​(java.lang.String openKernel)
        Specifies geometry kernel to use when opening a model. Valid values are "model" and "comsol".
        Parameters:
        openKernel - The geometry kernel.

      • getOpenGeometryKernel

        public static java.lang.String getOpenGeometryKernel()
        Returns the geometry kernel to use when opening a model. Valid values are "model" and "comsol".
        Returns:
        The geometry kernel.

      • setDefaultGeometryKernel

        public static void setDefaultGeometryKernel​(java.lang.String defaultKernel)
        Specifies the default geometry kernel to use. Valid values are "comsol" and "cadps".
        Parameters:
        defaultKernel - The geometry kernel.

      • getDefaultGeometryKernel

        public static java.lang.String getDefaultGeometryKernel()
        Return the default geometry kernel. Valid values are "comsol" and "cadps".
        Returns:
        The geometry kernel.

      • setServerBusyHandler

        public static void setServerBusyHandler​(ServerBusyHandler serverBusyHandler)
        Several clients can be connected to the same server, but only one client at a time can ask the server to perform an operation. The default behavior when attempting to call the server when it is busy is to throw an exception. By registering a ServerBusyHandler it is possible to make the client wait until the server is free again, and to set a time-out for how long to wait.
        Parameters:
        serverBusyHandler - The server busy handler.

      • setModelChangedHandler

        public static void setModelChangedHandler​(ModelChangedHandler modelChangedHandler)
        Register a handler of changes to models made by other clients. If any other client changes any model in use by this client, the model change handler is notified.
        Parameters:
        modelChangedHandler - The handler of model changes.

      • blockOtherClients

        public static void blockOtherClients​(boolean blockOtherClients)
        Tells the server to block or unblock other clients. Other clients while blocked will not be able to send any messages to the server and will not receive any notifications that any model has changed on the server. Such notification will be sent once the blocking is released.

        It is the responsibility of the client requesting the blocking to release it. There is no time-out.

        If the client disconnects from the server without releasing the blocking it will be automatically released.

      • initStandalone

        public static void initStandalone​(boolean guiSupport)
        Initializes the environment for using the COMSOL API from a Java application.
        Parameters:
        guiSupport - is true if support for plotting in a GUI should be available. The GUI will support creating widgets using Swing components.

      • initStandalone

        public static void initStandalone​(boolean guiInSupport,
                                  java.lang.String graphicsToolkit)
        Initializes the environment for using the COMSOL API from a Java application.
        Parameters:
        guiInSupport - is true if support for plotting in a GUI should be available.
        graphicsToolkit - "swing" or "swt" depending on if creating a Swing or a SWT GUI should be supported.

      • loadPreferences

        public static void loadPreferences()
        Loads the COMSOL preferences file. Use this method in standalone java applications, which do not automatically load the preferences on launch.

      • savePreferences

        public static void savePreferences()
        Saves the COMSOL preferences file.

      • getPreference

        public static java.lang.String getPreference​(java.lang.String prefName)
        Returns the value of a preference.
        Parameters:
        prefName - The preference name. For a list of the preferences names, use listPreferences().
        Returns:
        The preference's value.

      • getStringArrayPreference

        public static java.lang.String[] getStringArrayPreference​(java.lang.String prefName)
        Returns the value of a string array preference.
        Parameters:
        prefName - The preference name. For a list of the preferences names, use listPreferences().
        Returns:
        The preference's value.

      • setPreference

        public static void setPreference​(java.lang.String prefName,
                                 java.lang.String value)
        Sets a preference value.
        Parameters:
        prefName - The preference name. For a list of the preferences names, use listPreferences().
        value - The new preference value.

      • setPreference

        public static void setPreference​(java.lang.String prefName,
                                 java.lang.String[] value)
        Sets a string array preference value.
        Parameters:
        prefName - The preference name. For a list of the preferences names, use listPreferences().
        value - The new preference value.

      • listPreferences

        public static java.lang.String listPreferences()
        Returns a string which lists the preferences's names and their description.
        Returns:
        A list of the preferences's names and their description.

      • serverDisplay

        public static void serverDisplay​(java.lang.String message)
        Prints a message in the server terminal window.
        Parameters:
        message - The message to print.

      • serverLog

        public static void serverLog​(java.lang.String message)
        Prints a message in COMSOL's log file on the server.
        Parameters:
        message - The message to print.

      • hasProduct

        public static boolean hasProduct​(java.lang.String... product)
        Return true if the license allows to run the specified products. This test is done by checking the vendor string in licenseinfo.ini. No license checkout is performed.
        Parameters:
        product - The names of the license features to test.

      • hasProductForFile

        public static boolean hasProductForFile​(java.lang.String file)
                                 throws java.io.IOException
        Return true if the license contains products required to open an mph file. This test is done by checking the vendor string in licenseinfo.ini. No license product checkout is performed.
        Parameters:
        file - The mph file specifying the license features to test.
        Throws:
        java.io.IOException - if the file cannot be read.

      • hasProductForFileOnServer

        public static boolean hasProductForFileOnServer​(java.lang.String file)
                                         throws java.io.IOException
        Return true if the license contains products required to open an mph file located on the server filesystem. This test is done by checking the vendor string in licenseinfo.ini. No license product checkout is performed.
        Parameters:
        file - The mph file specifying the license features to test.
        Throws:
        java.io.IOException - if the file cannot be read.

      • checkoutLicense

        public static boolean checkoutLicense​(java.lang.String... product)
        Check out one license for each of the specified products. If not all required products can be checked out, no products are checked out.
        Parameters:
        product - The names of the license features to check out.
        Returns:
        True if license checkout succeeded.

      • checkoutLicenseForFile

        public static boolean checkoutLicenseForFile​(java.lang.String file)
                                      throws java.io.IOException
        Check out required products for an mph file. If not all required products can be checked out, no products are checked out.
        Parameters:
        file - The mph file to check out licenses for.
        Returns:
        True if license checkout succeeded.
        Throws:
        java.io.IOException - if the file cannot be read.

      • checkoutLicenseForFileOnServer

        public static boolean checkoutLicenseForFileOnServer​(java.lang.String file)
                                              throws java.io.IOException
        Check out required products for an mph file located on the server filesystem. If not all required products can be checked out, no products are checked out.
        Parameters:
        file - The mph file to check out licenses for.
        Returns:
        True if license checkout succeeded.
        Throws:
        java.io.IOException - if the file cannot be read.

      • useRecovery

        public static boolean useRecovery()
        Checks if usage of recovery file is enabled.
        Returns:
        True if usage of recovery file is enabled.

      • getRecoveryDir

        public static java.lang.String getRecoveryDir​(java.lang.String tag)
                                       throws java.io.IOException
        Returns a path to the recovery directory for a model.
        Parameters:
        tag - The model's tag.
        Returns:
        A path to the recovery directory
        Throws:
        java.io.IOException - if failed to create the directory

      • getComsolVersion

        public static java.lang.String getComsolVersion()
        Returns the current version of COMSOL.
        Returns:
        The version as a string.

      • scanModel

        public static java.lang.String[][] scanModel​(java.lang.String filename,
                                             java.lang.String type,
                                             java.lang.String... extraAttributes)
        An advanced tool that scans the raw data (XML) of the model file for a certain node type and collect the tag and label of all found nodes. In most cases the node type argument is the same as the corresponding API class name of the node. The reason for using this tool is to quickly scan several MPH files for simple information, such as a list of available materials or functions. If you need more sophisticated access to the model, it is easier to open the model and process the content. Although you pay for the extra time to open the model, scanning with this tool is very limited. It cannot handle backward compatibility for example, so scanning of older files may not work.
        As an option it is possible to include values of other attributes to the result, but the name of such attributes can be difficult to extract. You may need to open and view the XML content of an MPH file (extract dmodel.xml using an unzip tool), so it is a complicated process.
        The example below uses "op", which corresponds to the string return by the "getType()" method that some node types support (for example PropFeature.getType().
        Other examples of extra attribute are "entityComments" and "entityAuthor", returning the comment and author of each node.
        The method do not support returning values of settings, for example from "getString(name)" methods.
        The returned result is a double string array with all found nodes in the outer level, and the sequence of found attributes in the inner, starting with tag and label. The optional attributes follow after the tag and label.
        Example: 
         String[][] materials = scanModel("mymodel.mph", "Material", "op");
 String[][] functions = scanModel("mymodel.mph", "FunctionFeature", "op");
        will produce an output like: 
         materials = [["mat1", "Material 1", "Common"],["mat2", "Material 2", "Common"]]
 functions = [["an1", "Analytic 1", "Analytic"],["int1", "Interpolation 1", "Interpolation"]]
        Parameters:
        filename - The file path to the model
        type - The type of the node to search for
        extraAttributes - A list of attributes in addition to the tag and label to include in the result.
        Returns:
        A double string array with the result.

      • scanProtectedModel

        public static java.lang.String[][] scanProtectedModel​(java.lang.String filename,
                                                      java.lang.String type,
                                                      java.lang.String password,
                                                      java.lang.String... extraAttributes)
        Scans the protected model file for a certain node type.
        Parameters:
        filename - The file path to the model.
        type - The type of the node to search for.
        password - The password required to open the file.
        extraAttributes - A list of attributes in addition to the tag and label to include in the result.
        Returns:
        A double string array with the result.
        See Also:
        scanModel(String, String, String...)