org.rosuda.REngine
Class REngine

java.lang.Object
  org.rosuda.REngine.REngine

Direct Known Subclasses:

JRIEngine, RConnection

public abstract class REngine
extends java.lang.Object

REngine is an abstract base class for all implementations of R engines. Subclasses can implement interfaces to R in many different ways. Clients should always use methods this class instead of its direct subclasses in order to maintian compatibility with any R engine implementation. The canonical way of obtaining a new engine is to call engineForClass(java.lang.String). All subclasses must implement createEngine() method.

Field Summary

protected static REngine

lastEngine last created engine or null if there is none

Constructor Summary

REngine()

Method Summary

void	assign(java.lang.String symbol, byte[] d) convenience method equivalent to assign(symbol, new REXPRaw(d), null) (see assign(String, REXP, REXP))
void	assign(java.lang.String symbol, double[] d) convenience method equivalent to assign(symbol, new REXPDouble(d), null) (see assign(String, REXP, REXP))
void	assign(java.lang.String symbol, int[] d) convenience method equivalent to assign(symbol, new REXPInteger(d), null) (see assign(String, REXP, REXP))
void	assign(java.lang.String symbol, REXP value) convenience method equivalent to assign(symbol, value, null) (see assign(String, REXP, REXP))
abstract void	assign(java.lang.String symbol, REXP value, REXP env) assign into an environment
void	assign(java.lang.String symbol, java.lang.String d) convenience method equivalent to assign(symbol, new REXPString(d), null) (see assign(String, REXP, REXP))
void	assign(java.lang.String symbol, java.lang.String[] d) convenience method equivalent to assign(symbol, new REXPString(d), null) (see assign(String, REXP, REXP))
boolean	close() performs a close operation on engines that support it.
abstract REXP	createReference(REXP value) create a reference by pushing local data to R and returning a reference to the data.
static REngine	engineForClass(java.lang.String klass) this is the designated constructor for REngine classes.
static REngine	engineForClass(java.lang.String klass, java.lang.String[] args, REngineCallbacks callbacks, boolean runREPL) This is the extended constructor for REngine classes.
abstract REXP	eval(REXP what, REXP where, boolean resolve) evaluate an expression vector
abstract void	finalizeReference(REXP ref) removes reference from the R side.
abstract REXP	get(java.lang.String symbol, REXP env, boolean resolve) get a value from an environment
static REngine	getLastEngine() retrieve the last created engine
abstract REXP	getParentEnvironment(REXP env, boolean resolve) get the parent environemnt of an environemnt
int	lock() obtains a lock for this R engine, waiting until it becomes available.
abstract REXP	newEnvironment(REXP parent, boolean resolve) create a new environemnt
abstract REXP	parse(java.lang.String text, boolean resolve) parse a string into an expression vector
REXP	parseAndEval(java.lang.String cmd) convenince method equivalent to eval(parse(cmd, false), null, true);
REXP	parseAndEval(java.lang.String text, REXP where, boolean resolve) convenince method equivalent to eval(parse(text, false), where, resolve);
abstract REXP	resolveReference(REXP ref) fetch the contents of the given reference.
boolean	supportsEnvironments() check whether this engine supports handing of environments (if not, eval(org.rosuda.REngine.REXP, org.rosuda.REngine.REXP, boolean) and assign(java.lang.String, org.rosuda.REngine.REXP, org.rosuda.REngine.REXP) only support the global environment denoted by null).
boolean	supportsLocking() check whether this engine supports locking (lock(), tryLock() and unlock(int)).
boolean	supportsReferences() check whether this engine supports references to R objects
boolean	supportsREPL() check whether this engine supports REPL (Read-Evaluate-Print-Loop) and corresponding callbacks.
java.lang.String	toString()
int	tryLock() attempts to obtain a lock for this R engine synchronously (without waiting for it).
void	unlock(int lockValue) releases a lock previously obtained by lock() or tryLock().
REXP	wrap(java.lang.Object o)

Methods inherited from class java.lang.Object

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

Field Detail

lastEngine

protected static REngine lastEngine

last created engine or null if there is none

Constructor Detail

REngine

public REngine()

Method Detail

engineForClass

public static REngine engineForClass(java.lang.String klass)
                              throws java.lang.ClassNotFoundException,
                                     java.lang.NoSuchMethodException,
                                     java.lang.IllegalAccessException,
                                     java.lang.reflect.InvocationTargetException

this is the designated constructor for REngine classes. It uses reflection to call createEngine method on the given REngine class.

Parameters:

klass - fully qualified class-name of a REngine implementation

Returns:

REngine implementation or null if createEngine invokation failed

Throws:

java.lang.ClassNotFoundException

java.lang.NoSuchMethodException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

engineForClass

public static REngine engineForClass(java.lang.String klass,
                                     java.lang.String[] args,
                                     REngineCallbacks callbacks,
                                     boolean runREPL)
                              throws java.lang.ClassNotFoundException,
                                     java.lang.NoSuchMethodException,
                                     java.lang.IllegalAccessException,
                                     java.lang.reflect.InvocationTargetException

This is the extended constructor for REngine classes. It uses reflection to call createEngine method on the given REngine class with some additional control over the engine. Note that not all engines may support the extended version.

Parameters:

klass - fully qualified class-name of a REngine implementation

args - arguments to pass to R for initialization

callbacks - delegate for REngine callbacks or null if callbacks won't be serviced (engine may not support callbacks)

runREPL - if true then REPL will be started (if supported by the engine)

Returns:

REngine implementation or null if createEngine invokation failed

Throws:

java.lang.ClassNotFoundException

java.lang.NoSuchMethodException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getLastEngine

public static REngine getLastEngine()

retrieve the last created engine

Returns:

last created engine or null if no engine was created yet

parse

public abstract REXP parse(java.lang.String text,
                           boolean resolve)
                    throws REngineException

parse a string into an expression vector

Parameters:

text - string to parse

resolve - resolve the resulting REXP (true) or just return a reference (false)

Returns:

parsed expression

Throws:

REngineException

eval

public abstract REXP eval(REXP what,
                          REXP where,
                          boolean resolve)
                   throws REngineException,
                          REXPMismatchException

evaluate an expression vector

Parameters:

what - an expression (or vector of such) to evaluate

where - environment to evaluate in (use null for the global environemnt and/or if environments are not supported by the engine)

resolve - resolve the resulting REXP or just return a reference

Returns:

the result of the evaluation of the last expression

Throws:

REngineException

REXPMismatchException

assign

public abstract void assign(java.lang.String symbol,
                            REXP value,
                            REXP env)
                     throws REngineException,
                            REXPMismatchException

assign into an environment

Parameters:

symbol - symbol name

value - value to assign

env - environment to assign to (use null for the global environemnt and/or if environments are not supported by the engine)

Throws:

REngineException

REXPMismatchException

get

public abstract REXP get(java.lang.String symbol,
                         REXP env,
                         boolean resolve)
                  throws REngineException,
                         REXPMismatchException

get a value from an environment

Parameters:

symbol - symbol name

env - environment (use null for the global environemnt and/or if environments are not supported by the engine)

resolve - resolve the resulting REXP or just return a reference

Returns:

value

Throws:

REngineException

REXPMismatchException

resolveReference

public abstract REXP resolveReference(REXP ref)
                               throws REngineException,
                                      REXPMismatchException

fetch the contents of the given reference. The resulting REXP may never be REXPReference. The engine should raise a #REngineException exception if supportsReferences() returns false.

Parameters:

ref - reference to resolve

Returns:

resolved reference

Throws:

REngineException

REXPMismatchException

createReference

public abstract REXP createReference(REXP value)
                              throws REngineException,
                                     REXPMismatchException

create a reference by pushing local data to R and returning a reference to the data. If ref is a reference it is returned as-is. The engine should raise a #REngineException exception if supportsReferences() returns false.

Parameters:

value - to create reference to

Returns:

reference to the value

Throws:

REngineException

REXPMismatchException

finalizeReference

public abstract void finalizeReference(REXP ref)
                                throws REngineException,
                                       REXPMismatchException

removes reference from the R side. This method is called automatically by the finalizer of REXPReference and should never be called directly.

Parameters:

ref - reference to finalize

Throws:

REngineException

REXPMismatchException

getParentEnvironment

public abstract REXP getParentEnvironment(REXP env,
                                          boolean resolve)
                                   throws REngineException,
                                          REXPMismatchException

get the parent environemnt of an environemnt

Parameters:

env - environment to query

resolve - whether to resolve the resulting environment reference

Returns:

parent environemnt of env

Throws:

REngineException

REXPMismatchException

newEnvironment

public abstract REXP newEnvironment(REXP parent,
                                    boolean resolve)
                             throws REngineException,
                                    REXPMismatchException

create a new environemnt

Parameters:

parent - parent environment

resolve - whether to resolve the reference to the environemnt (usually false since the returned environment will be empty)

Returns:

resulting environment

Throws:

REngineException

REXPMismatchException

parseAndEval

public REXP parseAndEval(java.lang.String text,
                         REXP where,
                         boolean resolve)
                  throws REngineException,
                         REXPMismatchException

convenince method equivalent to eval(parse(text, false), where, resolve);

Parameters:

text - to parse (see parse(java.lang.String, boolean))

where - environment to evaluate in (see eval(org.rosuda.REngine.REXP, org.rosuda.REngine.REXP, boolean))

resolve - whether to resolve the resulting reference or not (see eval(org.rosuda.REngine.REXP, org.rosuda.REngine.REXP, boolean))

Returns:

result

Throws:

REngineException

REXPMismatchException

parseAndEval

public REXP parseAndEval(java.lang.String cmd)
                  throws REngineException,
                         REXPMismatchException

convenince method equivalent to eval(parse(cmd, false), null, true);

Parameters:

cmd - expression to parse (see parse(java.lang.String, boolean))

Returns:

result

Throws:

REngineException

REXPMismatchException

close

public boolean close()

performs a close operation on engines that support it. The engine may not be used after close() returned true. This operation is optional and will always return false if not implemented.

Returns:

true if the close opetaion was successful, false otherwise.

supportsReferences

public boolean supportsReferences()

check whether this engine supports references to R objects

Returns:

true if this engine supports references, false/code> otherwise

supportsEnvironments

public boolean supportsEnvironments()

check whether this engine supports handing of environments (if not, eval(org.rosuda.REngine.REXP, org.rosuda.REngine.REXP, boolean) and assign(java.lang.String, org.rosuda.REngine.REXP, org.rosuda.REngine.REXP) only support the global environment denoted by null).

Returns:

true if this engine supports environments, false/code> otherwise

supportsREPL

public boolean supportsREPL()

check whether this engine supports REPL (Read-Evaluate-Print-Loop) and corresponding callbacks.

Returns:

true if this engine supports REPL, false/code> otherwise

supportsLocking

public boolean supportsLocking()

check whether this engine supports locking (lock(), tryLock() and unlock(int)).

Returns:

true if this engine supports REPL, false/code> otherwise

assign

public void assign(java.lang.String symbol,
                   double[] d)
            throws REngineException

convenience method equivalent to assign(symbol, new REXPDouble(d), null) (see assign(String, REXP, REXP))

Parameters:

symbol - symbol name to assign to

d - values to assign

Throws:

REngineException

assign

public void assign(java.lang.String symbol,
                   int[] d)
            throws REngineException

convenience method equivalent to assign(symbol, new REXPInteger(d), null) (see assign(String, REXP, REXP))

Parameters:

symbol - symbol name to assign to

d - values to assign

Throws:

REngineException

assign

public void assign(java.lang.String symbol,
                   java.lang.String[] d)
            throws REngineException

convenience method equivalent to assign(symbol, new REXPString(d), null) (see assign(String, REXP, REXP))

Parameters:

symbol - symbol name to assign to

d - values to assign

Throws:

REngineException

assign

public void assign(java.lang.String symbol,
                   byte[] d)
            throws REngineException

convenience method equivalent to assign(symbol, new REXPRaw(d), null) (see assign(String, REXP, REXP))

Parameters:

symbol - symbol name to assign to

d - values to assign

Throws:

REngineException

assign

public void assign(java.lang.String symbol,
                   java.lang.String d)
            throws REngineException

convenience method equivalent to assign(symbol, new REXPString(d), null) (see assign(String, REXP, REXP))

Parameters:

symbol - symbol name to assign to

d - value to assign

Throws:

REngineException

assign

public void assign(java.lang.String symbol,
                   REXP value)
            throws REngineException,
                   REXPMismatchException

convenience method equivalent to assign(symbol, value, null) (see assign(String, REXP, REXP))

Parameters:

symbol - symbol name to assign to

value - values to assign

Throws:

REngineException

REXPMismatchException

tryLock

public int tryLock()

attempts to obtain a lock for this R engine synchronously (without waiting for it).
Note: check for supportsLocking() before relying on this capability. If not implemented, always returns 0.

Returns:

0 if the lock could not be obtained (R engine is busy) and some other value otherwise -- the returned value must be used in a matching call to unlock(int).

lock

public int lock()

obtains a lock for this R engine, waiting until it becomes available.
Note: check for supportsLocking() before relying on this capability. If not implemented, always returns 0.

Returns:

value that must be passed to unlock(int) in order to release the lock

unlock

public void unlock(int lockValue)

releases a lock previously obtained by lock() or tryLock().
Note: check for supportsLocking() before relying on this capability. If not implemented, has no effect.

Parameters:

lockValue - value returned by lock() or tryLock().

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

wrap

public REXP wrap(java.lang.Object o)