com.comsol.model.util

Class ModelUtil

java.lang.Object

com.comsol.model.util.ModelUtil

public class ModelUtil
extends java.lang.Object

Class with static methods for managing models.

Field Summary

Fields

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

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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 filename) Load a model.
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.
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.

Constructor Detail

ModelUtil

private ModelUtil()

Static class not intended to be instantiated.

Method Detail

impl

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

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 filename)
                  throws java.io.IOException

Load 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.

filename - The model file path.

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.

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...)