matlabcontrol

Class MatlabProxyFactoryOptions.Builder

java.lang.Object

matlabcontrol.MatlabProxyFactoryOptions.Builder

Enclosing class:

MatlabProxyFactoryOptions

public static class MatlabProxyFactoryOptions.Builder
extends Object

Creates instances of MatlabProxyFactoryOptions. Any and all of these properties may be left unset, if so then a default will be used. Depending on how the factory operates, not all properties may be used. Currently all properties are used only when running outside MATLAB, but future releases may add additional options.

Calls on this class may be chained together to easily create factory options. Example usage:

 
 MatlabProxyFactoryOptions options = new MatlabProxyFactoryOptions.Builder()
                                         .setHidden(true)
                                         .setProxyTimeout(30000L)
                                         .build();
 
 

This class is unconditionally thread-safe.

Since:

4.0.0

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
MatlabProxyFactoryOptions	build() Builds a MatlabProxyFactoryOptions instance.
MatlabProxyFactoryOptions.Builder	setCopyPasteCallback(MatlabProxyFactory.CopyPasteCallback copyPasteCallback) If this is set, then the factory will pass some MATLAB code to the given callback, which should be pasted into the MATLAB command prompt to initiate the connection.
MatlabProxyFactoryOptions.Builder	setErrorWriter(Writer errorWriter) Sets the error writer where the error output of the created matlab process is written to.
MatlabProxyFactoryOptions.Builder	setHidden(boolean hidden) Sets whether MATLAB should appear hidden.
MatlabProxyFactoryOptions.Builder	setJavaDebugger(int portnumber) Sets whether to enable use of the Java debugger on the MATLAB session using port portnumber.
MatlabProxyFactoryOptions.Builder	setLicenseFile(String licenseFile) Sets the license file used by MATLAB.
MatlabProxyFactoryOptions.Builder	setLogFile(String logFile) Sets whether to have MATLAB log any output to the MATLAB Command Window (including crash reports) to the file specified by logFile.
MatlabProxyFactoryOptions.Builder	setMatlabLocation(String matlabLocation) Sets the location of the MATLAB executable or script that will launch MATLAB.
MatlabProxyFactoryOptions.Builder	setMatlabStartingDirectory(File dir) Sets the starting directory for MATLAB.
MatlabProxyFactoryOptions.Builder	setOSGiClassloaderFriendly(boolean osgiClassloaderFriendly) If this is set, then RMI will be initiated in a way that doesn't get bogged down by OSGi.
MatlabProxyFactoryOptions.Builder	setOutputWriter(Writer outputWriter) Sets the output writer where the standard output of the created matlab process is written to.
MatlabProxyFactoryOptions.Builder	setPort(int port) Sets the port matlabcontrol uses to communicate with MATLAB.
MatlabProxyFactoryOptions.Builder	setProxyTimeout(long timeout) Sets the amount of time in milliseconds to wait for a proxy to be created when requested via the blocking method MatlabProxyFactory.getProxy().
MatlabProxyFactoryOptions.Builder	setUsePreviouslyControlledSession(boolean usePreviouslyControlled) Sets whether the factory should attempt to create a proxy that is connected to a running session of MATLAB.
MatlabProxyFactoryOptions.Builder	setUseSingleComputationalThread(boolean useSingleCompThread) Sets whether to limit MATLAB to a single computational thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder()

Method Detail

setMatlabLocation

public final MatlabProxyFactoryOptions.Builder setMatlabLocation(String matlabLocation)

Sets the location of the MATLAB executable or script that will launch MATLAB. If the value set cannot be successfully used to launch MATLAB, an exception will be thrown when attempting to create a proxy.

The absolute path to the MATLAB executable can be determined by running MATLAB. On OS X or Linux, evaluate [matlabroot '/bin/matlab'] in the Command Window. On Windows, evaluate [matlabroot '/bin/matlab.exe'] in the Command Window. The location provided does not have to be an absolute path so long as the operating system can resolve the path.

Windows
Locations relative to the following will be understood:

• The current working directory
• The Windows directory only (no subdirectories are searched)
• The Windows\System32 directory
• Directories listed in the PATH environment variable
• App Paths defined in the registry with key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths

By default on Windows, MATLAB adds itself to the PATH environment variable as well as places an App Path entry in the registry so that matlab can be used to launch MATLAB. If this property is not set, then the PATH environment variable or the App Path entry will be used.

OS X
Locations relative to the following will be understood:

• The current working directory
• Directories listed in the PATH environment variable

On OS X, MATLAB is installed in /Applications/ as an application bundle. If this property is not set, the executable inside of the application bundle will be used.

Linux
Locations relative to the following will be understood:

• The current working directory
• Directories listed in the PATH environment variable

During the installation process on Linux, MATLAB can create a symbolic link named matlab that can be used to launch MATLAB. If this property is not set, this symbolic link will be used.

Parameters:

matlabLocation -

setMatlabStartingDirectory

public final MatlabProxyFactoryOptions.Builder setMatlabStartingDirectory(File dir)

Sets the starting directory for MATLAB.

Parameters:

dir -

Throws:

NullPointerException - if dir is null

IllegalArgumentException - if dir does not exist or is not a directory

setHidden

public final MatlabProxyFactoryOptions.Builder setHidden(boolean hidden)

Sets whether MATLAB should appear hidden. By default this property is set to false. If set to true then the splash screen will not be shown and:

Windows
The MATLAB Command Window will appear fully minimized.

OS X
MATLAB will be entirely hidden. The MATLAB session will terminate when the Java application terminates.

Linux
MATLAB will be entirely hidden. The MATLAB session will terminate when the Java application terminates.

Parameters:

hidden -

setLogFile

public final MatlabProxyFactoryOptions.Builder setLogFile(String logFile)

Sets whether to have MATLAB log any output to the MATLAB Command Window (including crash reports) to the file specified by logFile. The validity of logFile is not checked by matlabcontrol. By default output is not logged.

Parameters:

logFile -

setJavaDebugger

public final MatlabProxyFactoryOptions.Builder setJavaDebugger(int portnumber)

Sets whether to enable use of the Java debugger on the MATLAB session using port portnumber. The portnumber may be in the range 0-65535 so long as it is not reserved or otherwise in use. By default the Java debugger is not enabled.

Parameters:

portnumber -

Throws:

IllegalArgumentException - if portnumber is not in the range 0-65535

setLicenseFile

public final MatlabProxyFactoryOptions.Builder setLicenseFile(String licenseFile)

Sets the license file used by MATLAB. By default no license file is specified. On Linux and OS X licenseFile may have the form port@host or a colon-separated list of license filenames. On Windows licenseFile may have the form port@host. Setting this option causes the LM_LICENSE_FILE and MLM_LICENSE_FILE environment variables to be ignored. The validity of licenseFile is not checked by matlabcontrol.

Parameters:

licenseFile -

setUsePreviouslyControlledSession

public final MatlabProxyFactoryOptions.Builder setUsePreviouslyControlledSession(boolean usePreviouslyControlled)

Sets whether the factory should attempt to create a proxy that is connected to a running session of MATLAB. By default this property is set to false.

When this property is true all options which configure MATLAB such as being hidden or logging are ignored. The only criterion used is whether a session of MATLAB is available for connection. In order for the factory to connect to the session of MATLAB, it must know about the session. This will be the case if a factory started the session of MATLAB and that factory was configured to use the same port as specified by setPort(int) (or both are using the default port). The factory will only connect to a session that does not currently have a proxy controlling it from outside of MATLAB.

To determine if the proxy created is connected to an existing session of MATLAB call MatlabProxy.isExistingSession(). You may wish to clear MATLAB's environment using clear. Doing so will not in anyway interfere with matlabcontrol (including executing clear java).

If a running session of MATLAB previously loaded classes defined in the controlling application, issues can arise. If your application does send to MATLAB or retrieve from MATLAB custom Serializable or Remote classes then these issues do not apply.

MATLAB sessions launched by matlabcontrol are able to load classes defined in the controlling application. When an existing session of MATLAB is connected to by a newly controlling application it will now be able to load classes defined by the newly controlling application but not the previous one. Several problems may arise due to this behavior. If an attempt is made to use a class defined in a previously controlling session that was not loaded while the application was controlling MATLAB then it will fail with a ClassNotFoundException if it is not also defined in the newly controlling application. If the class is defined it will fail to load it if the serializable definition is not compatible. A similar issue is if the newly controlling application attempts to send to MATLAB an instance of a class that was also defined by the previously controlling application but the serializable definition is not compatible. These above issues can easily be encountered when developing an application while changing Serializable or Remote classes and using the same session of MATLAB repeatedly. This will particularly be the case if the classes do not define a serialVersionUID. If multiple instances of the same application do not vary in their definition of Serializable and Remote classes then connecting to a previously controlled session of MATLAB will not cause any issues in this regard.

Parameters:

usePreviouslyControlled -

setOSGiClassloaderFriendly

public final MatlabProxyFactoryOptions.Builder setOSGiClassloaderFriendly(boolean osgiClassloaderFriendly)

If this is set, then RMI will be initiated in a way that doesn't get bogged down by OSGi.

setCopyPasteCallback

public final MatlabProxyFactoryOptions.Builder setCopyPasteCallback(MatlabProxyFactory.CopyPasteCallback copyPasteCallback)

If this is set, then the factory will pass some MATLAB code to the given callback, which should be pasted into the MATLAB command prompt to initiate the connection. This trumps every other property besides setProxyTimeout().

setProxyTimeout

public final MatlabProxyFactoryOptions.Builder setProxyTimeout(long timeout)

Sets the amount of time in milliseconds to wait for a proxy to be created when requested via the blocking method MatlabProxyFactory.getProxy(). By default this property is set to 180000 milliseconds.

Parameters:

timeout -

Throws:

IllegalArgumentException - if timeout is negative

setUseSingleComputationalThread

public final MatlabProxyFactoryOptions.Builder setUseSingleComputationalThread(boolean useSingleCompThread)

Sets whether to limit MATLAB to a single computational thread. By default this property is set to false.

Parameters:

useSingleCompThread -

setPort

public final MatlabProxyFactoryOptions.Builder setPort(int port)

Sets the port matlabcontrol uses to communicate with MATLAB. By default port 2100 is used. The port value may not be negative. It is recommended to be in the range of 1024 to 49151, but this range is not enforced. The port should be otherwise unused; however, any number of MatlabProxyFactory instances (even those running in completely separate applications) may use the same port. A MatlabProxyFactory will only be able to connect to a previously controlled running session that was started by a factory using the same port.

Parameters:

port -

Throws:

IllegalArgumentException - if port is negative

setOutputWriter

public final MatlabProxyFactoryOptions.Builder setOutputWriter(Writer outputWriter)

Sets the output writer where the standard output of the created matlab process is written to. This is only used when an actual process is spawned for the matlab proxy instance.

Parameters:

outputWriter -

setErrorWriter

public final MatlabProxyFactoryOptions.Builder setErrorWriter(Writer errorWriter)

Sets the error writer where the error output of the created matlab process is written to. This is only used when an actual process is spawned for the matlab proxy instance.

Parameters:

errorWriter -

build

public final MatlabProxyFactoryOptions build()

Builds a MatlabProxyFactoryOptions instance.

Returns:

factory options