matlabcontrol
Class LoggingMatlabProxy

java.lang.Object
  extended by matlabcontrol.MatlabProxy
      extended by matlabcontrol.LoggingMatlabProxy
All Implemented Interfaces:
MatlabOperations

public final class LoggingMatlabProxy
extends MatlabProxy

Wraps around a MatlabProxy to provide a log of interactions. The data is not altered. This logger is useful for determining the Java types and structure of data returned from MATLAB.

Interaction with all methods, except those defined in Object and not overridden, is logged. Entering a method, exiting a method, and throwing an exception are logged. Method parameters and return values are logged. The contents of a returned array will be recursively explored and its contents logged. As is convention, all of these interactions are logged at Level.FINER. If the logging system has not been otherwise configured, then the ConsoleHandler which prints log messages to the console will not show these log messages as their level is too low. To configure the ConsoleHandler to show these log messages, call showInConsoleHandler().

This class is unconditionally thread-safe.

Since:
4.1.0

Nested Class Summary
 
Nested classes/interfaces inherited from class matlabcontrol.MatlabProxy
MatlabProxy.DisconnectionListener, MatlabProxy.Identifier, MatlabProxy.MatlabThreadCallable<T>, MatlabProxy.MatlabThreadProxy
 
Constructor Summary
LoggingMatlabProxy(MatlabProxy delegateProxy)
          Constructs the logging proxy.
 
Method Summary
 void addDisconnectionListener(MatlabProxy.DisconnectionListener listener)
          Adds a disconnection listener that will be notified when this proxy becomes disconnected from MATLAB.
 boolean disconnect()
          Disconnects the proxy from MATLAB.
 void eval(java.lang.String command)
          Evaluates a command in MATLAB.
 void exit()
          Exits MATLAB.
 void feval(java.lang.String functionName, java.lang.Object... args)
          Calls a MATLAB function with the name functionName, returning the result.
 MatlabProxy.Identifier getIdentifier()
          Returns the unique identifier for this proxy.
 java.lang.Object getVariable(java.lang.String variableName)
          Gets the value of variableName in MATLAB.
<U> U
invokeAndWait(MatlabProxy.MatlabThreadCallable<U> callable)
          Runs the callable on MATLAB's main thread and waits for it to return its result.
 boolean isConnected()
          Whether this proxy is connected to MATLAB.
 boolean isExistingSession()
          Whether this proxy is connected to a session of MATLAB that was running previous to the request to create this proxy.
 boolean isRunningInsideMatlab()
          Whether this proxy is running inside of MATLAB.
 void removeDisconnectionListener(MatlabProxy.DisconnectionListener listener)
          Removes a disconnection listener.
 java.lang.Object[] returningEval(java.lang.String command, int nargout)
          Evaluates a command in MATLAB, returning the result.
 java.lang.Object[] returningFeval(java.lang.String functionName, int nargout, java.lang.Object... args)
          Calls a MATLAB function with the name functionName, returning the result.
 void setVariable(java.lang.String variableName, java.lang.Object value)
          Sets variableName to value in MATLAB, creating the variable if it does not yet exist.
static void showInConsoleHandler()
          Configures the ConsoleHandler responsible for showing logging records to show the records that are logged by this proxy.
 java.lang.String toString()
          Returns a brief description of this proxy.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LoggingMatlabProxy

public LoggingMatlabProxy(MatlabProxy delegateProxy)
Constructs the logging proxy. All methods defined in MatlabProxy will be delegated to delegateProxy.

Parameters:
delegateProxy -
Method Detail

showInConsoleHandler

public static void showInConsoleHandler()
Configures the ConsoleHandler responsible for showing logging records to show the records that are logged by this proxy. This behavior is useful if you have not otherwise configured logging in your application.


eval

public void eval(java.lang.String command)
          throws MatlabInvocationException
Description copied from interface: MatlabOperations
Evaluates a command in MATLAB. This is equivalent to MATLAB's eval('command').

Parameters:
command - the command to be evaluated in MATLAB
Throws:
MatlabInvocationException

returningEval

public java.lang.Object[] returningEval(java.lang.String command,
                                        int nargout)
                                 throws MatlabInvocationException
Description copied from interface: MatlabOperations
Evaluates a command in MATLAB, returning the result. This is equivalent to MATLAB's eval('command').

In order for the result of this command to be returned the number of arguments to be returned must be specified by nargout. This is equivalent in MATLAB to the number of variables placed on the left hand side of an expression. For example, in MATLAB the inmem function may be used with either 1, 2, or 3 return values each resulting in a different behavior:
 M = inmem;
 [M, X] = inmem;
 [M, X, J] = inmem;
 
 
The returned Object array will be of length nargout with each return argument placed into the corresponding array position.

If the command cannot return the number of arguments specified by nargout then an exception will be thrown.

Parameters:
command - the command to be evaluated in MATLAB
nargout - the number of arguments that will be returned from evaluating command
Returns:
result of MATLAB command, the length of the array will be nargout
Throws:
MatlabInvocationException

feval

public void feval(java.lang.String functionName,
                  java.lang.Object... args)
           throws MatlabInvocationException
Description copied from interface: MatlabOperations
Calls a MATLAB function with the name functionName, returning the result. Arguments to the function may be provided as args, but are not required if the function needs no arguments.

The function arguments will be converted into MATLAB equivalents as appropriate. Importantly, this means that a String will be converted to a MATLAB char array, not a variable name.

Parameters:
functionName - the name of the MATLAB function to call
args - the arguments to the function
Throws:
MatlabInvocationException

returningFeval

public java.lang.Object[] returningFeval(java.lang.String functionName,
                                         int nargout,
                                         java.lang.Object... args)
                                  throws MatlabInvocationException
Description copied from interface: MatlabOperations
Calls a MATLAB function with the name functionName, returning the result. Arguments to the function may be provided as args, but are not required if the function needs no arguments.

The function arguments will be converted into MATLAB equivalents as appropriate. Importantly, this means that a String will be converted to a MATLAB char array, not a variable name.

In order for the result of this function to be returned the number of arguments to be returned must be specified by nargout. This is equivalent in MATLAB to the number of variables placed on the left hand side of an expression. For example, in MATLAB the inmem function may be used with either 1, 2, or 3 return values each resulting in a different behavior:
 M = inmem;
 [M, X] = inmem;
 [M, X, J] = inmem;
 
 
The returned Object array will be of length nargout with each return argument placed into the corresponding array position.

If the function is not capable of returning the number of arguments specified by nargout then an exception will be thrown.

Parameters:
functionName - the name of the MATLAB function to call
nargout - the number of arguments that will be returned by functionName
args - the arguments to the function
Returns:
result of MATLAB function, the length of the array will be nargout
Throws:
MatlabInvocationException

setVariable

public void setVariable(java.lang.String variableName,
                        java.lang.Object value)
                 throws MatlabInvocationException
Description copied from interface: MatlabOperations
Sets variableName to value in MATLAB, creating the variable if it does not yet exist.

Throws:
MatlabInvocationException

getVariable

public java.lang.Object getVariable(java.lang.String variableName)
                             throws MatlabInvocationException
Description copied from interface: MatlabOperations
Gets the value of variableName in MATLAB.

Returns:
value
Throws:
MatlabInvocationException

invokeAndWait

public <U> U invokeAndWait(MatlabProxy.MatlabThreadCallable<U> callable)
                throws MatlabInvocationException
Description copied from class: MatlabProxy
Runs the callable on MATLAB's main thread and waits for it to return its result. This method allows for uninterrupted access to MATLAB's main thread between two or more interactions with MATLAB.

If running outside MATLAB the callable must be Serializable; it may not be Remote.

Specified by:
invokeAndWait in class MatlabProxy
Returns:
result of the callable
Throws:
MatlabInvocationException

addDisconnectionListener

public void addDisconnectionListener(MatlabProxy.DisconnectionListener listener)
Description copied from class: MatlabProxy
Adds a disconnection listener that will be notified when this proxy becomes disconnected from MATLAB.

Overrides:
addDisconnectionListener in class MatlabProxy

removeDisconnectionListener

public void removeDisconnectionListener(MatlabProxy.DisconnectionListener listener)
Description copied from class: MatlabProxy
Removes a disconnection listener. It will no longer be notified.

Overrides:
removeDisconnectionListener in class MatlabProxy

disconnect

public boolean disconnect()
Description copied from class: MatlabProxy
Disconnects the proxy from MATLAB. MATLAB will not exit. After disconnecting, any method sent to MATLAB will throw an exception. A proxy cannot be reconnected. Returns true if the proxy is now disconnected, false otherwise.

Specified by:
disconnect in class MatlabProxy
Returns:
if disconnected
See Also:
MatlabProxy.exit(), MatlabProxy.isConnected()

isExistingSession

public boolean isExistingSession()
Description copied from class: MatlabProxy
Whether this proxy is connected to a session of MATLAB that was running previous to the request to create this proxy.

Overrides:
isExistingSession in class MatlabProxy
Returns:
if existing session

isRunningInsideMatlab

public boolean isRunningInsideMatlab()
Description copied from class: MatlabProxy
Whether this proxy is running inside of MATLAB.

Specified by:
isRunningInsideMatlab in class MatlabProxy
Returns:

isConnected

public boolean isConnected()
Description copied from class: MatlabProxy
Whether this proxy is connected to MATLAB.

The most likely reasons for this method to return false are if the proxy has been disconnected via MatlabProxy.disconnect() or MATLAB has been closed (when running outside MATLAB).

Specified by:
isConnected in class MatlabProxy
Returns:
if connected
See Also:
MatlabProxy.disconnect(), MatlabProxy.exit()

getIdentifier

public MatlabProxy.Identifier getIdentifier()
Description copied from class: MatlabProxy
Returns the unique identifier for this proxy.

Overrides:
getIdentifier in class MatlabProxy
Returns:
identifier

exit

public void exit()
          throws MatlabInvocationException
Description copied from class: MatlabProxy
Exits MATLAB. Attempting to exit MATLAB with either a eval or feval command will cause MATLAB to hang indefinitely.

Specified by:
exit in class MatlabProxy
Throws:
MatlabInvocationException
See Also:
MatlabProxy.disconnect(), MatlabProxy.isConnected()

toString

public java.lang.String toString()
Description copied from class: MatlabProxy
Returns a brief description of this proxy. The exact details of this representation are unspecified and are subject to change.

Overrides:
toString in class MatlabProxy