Package eu.simuline.octave

Class OctaveEngine

  • public final class OctaveEngine
extends Object
    The connection to an octave process. This is inspired by the javax.script.ScriptEngine interface.

    • Field Detail

      • KNOWN_OCTAVE_VERSIONS

        private static final Set<String> KNOWN_OCTAVE_VERSIONS
        The set of known versions of octave, i.e. those for which javaoctave shall work.

      • octaveExec

        private final OctaveExec octaveExec
        The executor of this octave engine.

      • octaveIO

        private final OctaveIO octaveIO

      • writer

        private Writer writer
        The writer to write output from evaluation of a script. Initially this wraps System.out. This may also be null which indicates a 'do nothing functor'

      • random

        private final Random random
        Describe variable random here.

      • PATTERN_NAME_TYPE_FILE

        private static final Pattern PATTERN_NAME_TYPE_FILE
        The pattern for the answer to the command which <name> which is implemented by getDescForName(String).

      • JAVA_FUN

        private static final String JAVA_FUN
        A command in the package 'java'. This is used to determine both the installation home directory and the java home directory, which is the location of the m-file for JAVA_FUN.
        See Also:
        Constant Field Values

      • PATTERN_HOMEDIR

        private static final String PATTERN_HOMEDIR
        A pattern of the m-file for command JAVA_FUN in package java, defining the installation home directory as returned by getInstHomeDir() as its group with number two and the java home directory as its group number one. The pattern is made independent of the octave version and of the specific command.

    • Constructor Detail

      • OctaveEngine

        OctaveEngine​(OctaveEngineFactory factory,
             int numThreadsReuse,
             Writer octaveInputLog,
             Writer errorWriter,
             Charset charset,
             String[] cmdArray,
             String[] environment,
             File workingDir)
        Creates an octave engine with the given parameters. The first one is nowhere used and the others are handed over to OctaveExec(int,Writer,Writer,Charset,String[],String[],File).
        Parameters:
        factory - the factory used to create this engine.
        numThreadsReuse - TBC
        octaveInputLog - a writer to log octave's standard output to, if not null.
        errorWriter - a writer to log octave's error output to ,if not null.
        charset - the charset used for communication with the octave process.
        cmdArray - an array with 0th entry the command and the rest (optional) command line parameters.

    • Method Detail

      • getReadFunctor

        private ReadFunctor getReadFunctor()
        Returns the according read functor: If writer is non-null, wrap it into a WriterReadFunctor. Otherwise, create functor from a reader which reads empty, i.e. without action, as long as the reader is empty.

      • unsafeEval

        public void unsafeEval​(Reader script)
        Execute the given script.
        Parameters:
        script - the script to execute
        Throws:
        OctaveIOException - if the script fails, this will kill the engine

      • unsafeEval

        public void unsafeEval​(String script)
        Execute the given script.
        Parameters:
        script - the script to execute
        Throws:
        OctaveIOException - if the script fails, this will kill the engine

      • eval

        public void eval​(String script)
        A safe eval that will not break the engine on syntax errors or other errors.
        Parameters:
        script - the script to execute
        Throws:
        OctaveEvalException - if the script fails

      • put

        public void put​(String key,
                OctaveObject value)
        Sets a value in octave.
        Parameters:
        key - the name of the variable to be set to value value.
        value - the value to set for the variable key

      • putAll

        public void putAll​(Map<String,​OctaveObject> vars)
        Sets all the mappings in the specified map as variables in octave. These mappings replace any variable that octave had for any of the keys currently in the specified map.
        Parameters:
        vars - a map from variable names to according values o be stored in the according variables in octave.

      • get

        public OctaveObject get​(String key)
        Parameters:
        key - the name of the variable
        Returns:
        the value from octave or null if the variable does not exist

      • get

        public <T extends OctaveObject> T get​(Class<T> castClass,
                                      String key)
        Type Parameters:
        T - the class of the return value
        Parameters:
        castClass - Class to cast to
        key - the name of the variable
        Returns:
        shallow copy of value for this key, or null if key isn't there.
        Throws:
        OctaveClassCastException - if the object can not be cast to a castClass

      • getFactory

        public OctaveEngineFactory getFactory()
        Deprecated.
        Returns:
        the factory that created this object

      • setWriter

        public void setWriter​(Writer writer)
        Set the writer that the scripts output will be written to. This method is usually placed in ScriptContext. It is used also for tests.
        Parameters:
        writer - the writer to set This may be null which means that no writer is used.

      • setErrorWriter

        public void setErrorWriter​(Writer errorWriter)
        Set the writer that the scripts error output will be written to. This method is usually placed in ScriptContext.
        Parameters:
        errorWriter - the errorWriter to set

      • close

        public void close()
        Close the octave process in an orderly fashion.

      • destroy

        public void destroy()
        Kill the octave process without remorse.

      • getVersion

        public String getVersion()
        Deprecated.
        use getOctaveVersion() instead.
        Return the version of the octave implementation. E.g. a string like "3.0.5" or "3.2.3".
        Returns:
        the version of the underlying octave program as a string.

      • getVendor

        public String getVendor()
        Returns the vendor of this octave bridge as a string.
        Returns:
        The vendor of this octave bridge as a string.

      • getOctaveInJavaVersion

        public String getOctaveInJavaVersion()
        Returns the version of this octave bridge as a string.
        Returns:
        The version of this octave bridge as a string.
        See Also:
        getOctaveVersion()

      • getOctaveVersion

        public String getOctaveVersion()
        Return the version of the octave implementation invoked by this bridge. E.g. a string like "3.0.5" or "3.2.3".
        Returns:
        The version of octave as a string.
        See Also:
        getOctaveInJavaVersion()

      • isOctaveVersionAllowed

        public boolean isOctaveVersionAllowed()
        Returns whether the version of the current octave installation given by getOctaveVersion() is supported by this octavejava bridge.
        Returns:
        whether the version of the current octave installation is supported by this octavejava bridge.
        See Also:
        KNOWN_OCTAVE_VERSIONS

      • getFilesep

        public String getFilesep()
        Returns the file separator of this os given by the expression filesep().
        Returns:
        the file-separator for this os.

      • getStringCellFromAns

        private Collection<String> getStringCellFromAns()
        Returns value in variable ANS which is expected to be a cell array of strings, as a collection of strings.
        Returns:
        ANS as a collection of strings.

      • getNamesOfPackagesInstalled

        public Collection<String> getNamesOfPackagesInstalled()
        Returns a collection of names of installed packages.
        Returns:
        a collection of names of installed packages.
        See Also:
        getPackagesInstalled()

      • getPackagesInstalled

        public Map<String,​OctaveEngine.PackageDesc> getPackagesInstalled()
        Returns a map mapping the names of the installed packages to the description of the according package.
        Returns:
        a map from the names to the description of the packages installed.
        See Also:
        getNamesOfPackagesInstalled()

      • getVarNames

        public Collection<String> getVarNames()
        Returns a collection of variables defined excluding variables like NARGIN and ANS but also those that are most likely to be created by this software. TBD: clarification
        Returns:
        collection of variables

      • getDescForName

        public OctaveEngine.NameDesc getDescForName​(String name)
        Returns the description tied to the name name in a way, the command 'which' does in octave.
        Parameters:
        name - the name which may, e.g. be a variable or a file or a function or even nothing known.
        Returns:
        The description for the given name name, indicating its category in OctaveEngine.NameDesc.category and providing many interesting pieces of information.

      • getHomeDir

        private File getHomeDir​(String nameGrp)

      • getInstHomeDir

        public File getInstHomeDir()
        Returns the installation home directory, in the manual sometimes called octave-home. CAUTION: Initially, this is OCTAVE_HOME, but the latter can be overwritten.
        Returns:
        octave's installation home directory.

      • getJavaHomeDir

        public File getJavaHomeDir()
        Returns the java home directory, which contains the m files of the java interface like JAVA_FUN but is also a search directory for files javaclasspath.txt (deprecated classpath.txt) but also the configuration file java.opt. CAUTION: Initially, this is OCTAVE_JAVA_DIR, but the latter can be overwritten.
        Returns:
        octave's java home directory.