org.rosuda.REngine.JRI
Class JRIEngine

java.lang.Object
  org.rosuda.REngine.REngine
      org.rosuda.REngine.JRI.JRIEngine

All Implemented Interfaces:

RMainLoopCallbacks

public class JRIEngine
extends REngine
implements RMainLoopCallbacks

JRIEngine is a REngine implementation using JRI (Java/R Interface).

Note that at most one JRI instance can exist in a given JVM process, because R does not support multiple threads. JRIEngine itself is thread-safe, so it is possible to invoke its methods from any thread. However, this is achieved by serializing all entries into R, so be aware of possible deadlock conditions if your R code calls back into Java (JRIEngine is re-entrant from the same thread so deadlock issues can arise only with multiple threads inteacting thorugh R).

Field Summary

REXPReference	baseEnv special, global references
REXPReference	emptyEnv special, global references
REXPReference	globalEnv special, global references
REXPNull	nullValue canonical NULL object
REXPReference	nullValueRef special, global references
static long	requiredAPIversion minimal JRI API version that is required by this class in order to work properly (currently API 1.10, corresponding to JRI 0.5-1 or higher)

Fields inherited from class org.rosuda.REngine.REngine

lastEngine

Constructor Summary

JRIEngine()
default constructor - this constructor is also used via createEngine factory call and implies --no-save R argument, no callbacks and no REPL.

JRIEngine(Rengine eng)
WARNING: legacy fallback for hooking from R into an existing Rengine - do NOT use for creating a new Rengine - it will go away eventually

JRIEngine(java.lang.String[] args)
create JRIEngine with specified R command line arguments, no callbacks and no REPL.

JRIEngine(java.lang.String[] args, REngineCallbacks callbacks, boolean runREPL)
creates a JRI engine with specified delegate for callbacks

JRIEngine(java.lang.String[] args, RMainLoopCallbacks callbacks)
creates a JRI engine with specified delegate for callbacks (JRI compatibility mode ONLY!).

JRIEngine(java.lang.String[] args, RMainLoopCallbacks callbacks, boolean runREPL)
creates a JRI engine with specified delegate for callbacks (JRI compatibility mode ONLY!

Method Summary

void	assign(java.lang.String symbol, REXP value, REXP env) assign into an environment
boolean	close() performs a close operation on engines that support it.
static REngine	createEngine() factory method called by engineForClass
static REngine	createEngine(java.lang.String[] args, REngineCallbacks callbacks, boolean runREPL)
REXP	createReference(REXP value) create a reference by pushing local data to R and returning a reference to the data.
REXPReference	createRJavaRef(java.lang.Object o) creates a jobjRef reference in R via rJava.
REXP	eval(REXP what, REXP where, boolean resolve) evaluate an expression vector
void	finalizeReference(REXP ref) removes reference from the R side.
REXP	get(java.lang.String symbol, REXP env, boolean resolve) get a value from an environment
REXP	getParentEnvironment(REXP env, boolean resolve) get the parent environemnt of an environemnt
Rengine	getRni()
int	lock() obains a lock for this R engine, waiting until it becomes available.
REXP	newEnvironment(REXP parent, boolean resolve) create a new environemnt
REXP	parse(java.lang.String text, boolean resolve) parse a string into an expression vector
void	rBusy(Rengine re, int which) called when R enters or exits a longer evaluation.
java.lang.String	rChooseFile(Rengine re, int newFile) called when R expects the user to choose a file
REXP	resolveReference(REXP ref) fetch the contents of the given reference.
void	rFlushConsole(Rengine re) called when R requests the console to flush any buffered output
void	rLoadHistory(Rengine re, java.lang.String filename) called to load the contents of the history
java.lang.String	rReadConsole(Rengine re, java.lang.String prompt, int addToHistory) called when R waits for user input.
void	rSaveHistory(Rengine re, java.lang.String filename) called to save the contents of the history (the implementation is responsible of keeping track of the history)
void	rShowMessage(Rengine re, java.lang.String message) called when R want to show a warning/error message (not to be confused with messages displayed in the console output)
void	rWriteConsole(Rengine re, java.lang.String text, int oType) JRI callbacks forwarding
boolean	supportsEnvironments() check whether this engine supports handing of environments (if not, REngine.eval(org.rosuda.REngine.REXP, org.rosuda.REngine.REXP, boolean) and REngine.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 (REngine.lock(), REngine.tryLock() and REngine.unlock(int)).
boolean	supportsReferences() check whether this engine supports references to R objects
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().

Methods inherited from class org.rosuda.REngine.REngine

assign, assign, assign, assign, assign, assign, engineForClass, engineForClass, getLastEngine, parseAndEval, parseAndEval, supportsREPL, toString, wrap

Methods inherited from class java.lang.Object

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

Field Detail

requiredAPIversion

public static final long requiredAPIversion

minimal JRI API version that is required by this class in order to work properly (currently API 1.10, corresponding to JRI 0.5-1 or higher)

See Also:

Constant Field Values

globalEnv

public REXPReference globalEnv

special, global references

emptyEnv

public REXPReference emptyEnv

special, global references

baseEnv

public REXPReference baseEnv

special, global references

nullValueRef

public REXPReference nullValueRef

special, global references

nullValue

public REXPNull nullValue

canonical NULL object

Constructor Detail

JRIEngine

public JRIEngine()
          throws REngineException

default constructor - this constructor is also used via createEngine factory call and implies --no-save R argument, no callbacks and no REPL.

This is equivalent to JRIEngine(new String[] { "--no-save" }, null, false)

Throws:

REngineException

JRIEngine

public JRIEngine(java.lang.String[] args)
          throws REngineException

create JRIEngine with specified R command line arguments, no callbacks and no REPL.

This is equivalent to JRIEngine(args, null, false)

Throws:

REngineException

JRIEngine

public JRIEngine(java.lang.String[] args,
                 RMainLoopCallbacks callbacks)
          throws REngineException

creates a JRI engine with specified delegate for callbacks (JRI compatibility mode ONLY!). The event loop is started if callbacks in not null.

Parameters:

args - arguments to pass to R (note that R usually requires something like --no-save!)

callbacks - delegate class to process event loop callback from R or null if no event loop is desired

Throws:

REngineException

JRIEngine

public JRIEngine(java.lang.String[] args,
                 REngineCallbacks callbacks,
                 boolean runREPL)
          throws REngineException

creates a JRI engine with specified delegate for callbacks

Parameters:

args - arguments to pass to R (note that R usually requires something like --no-save!)

callback - delegate class to process callbacks from R or null if no callbacks are desired

runREPL - if set to true then the event loop (REPL) will be started, otherwise the engine is in direct operation mode.

Throws:

REngineException

JRIEngine

public JRIEngine(java.lang.String[] args,
                 RMainLoopCallbacks callbacks,
                 boolean runREPL)
          throws REngineException

creates a JRI engine with specified delegate for callbacks (JRI compatibility mode ONLY! Will be deprecated soon!)

Parameters:

args - arguments to pass to R (note that R usually requires something like --no-save!)

callback - delegate class to process callbacks from R or null if no callbacks are desired

runREPL - if set to true then the event loop (REPL) will be started, otherwise the engine is in direct operation mode.

Throws:

REngineException

JRIEngine

public JRIEngine(Rengine eng)
          throws REngineException

WARNING: legacy fallback for hooking from R into an existing Rengine - do NOT use for creating a new Rengine - it will go away eventually

Throws:

REngineException

Method Detail

createEngine

public static REngine createEngine()
                            throws REngineException

factory method called by engineForClass

Returns:

new or current engine (new if there is none, current otherwise since R allows only one engine at any time)

Throws:

REngineException

createEngine

public static REngine createEngine(java.lang.String[] args,
                                   REngineCallbacks callbacks,
                                   boolean runREPL)
                            throws REngineException

Throws:

REngineException

getRni

public Rengine getRni()

parse

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

Description copied from class: REngine

parse a string into an expression vector

Specified by:

parse in class REngine

Parameters:

text - string to parse

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

Returns:

parsed expression

Throws:

REngineException

eval

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

Description copied from class: REngine

evaluate an expression vector

Specified by:

eval in class REngine

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 void assign(java.lang.String symbol,
                   REXP value,
                   REXP env)
            throws REngineException,
                   REXPMismatchException

Description copied from class: REngine

assign into an environment

Specified by:

assign in class REngine

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 REXP get(java.lang.String symbol,
                REXP env,
                boolean resolve)
         throws REngineException,
                REXPMismatchException

Description copied from class: REngine

get a value from an environment

Specified by:

get in class REngine

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 REXP resolveReference(REXP ref)
                      throws REngineException,
                             REXPMismatchException

Description copied from class: REngine

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

Specified by:

resolveReference in class REngine

Parameters:

ref - reference to resolve

Returns:

resolved reference

Throws:

REngineException

REXPMismatchException

createReference

public REXP createReference(REXP value)
                     throws REngineException,
                            REXPMismatchException

Description copied from class: REngine

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 REngine.supportsReferences() returns false.

Specified by:

createReference in class REngine

Parameters:

value - to create reference to

Returns:

reference to the value

Throws:

REngineException

REXPMismatchException

finalizeReference

public void finalizeReference(REXP ref)
                       throws REngineException,
                              REXPMismatchException

Description copied from class: REngine

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

Specified by:

finalizeReference in class REngine

Parameters:

ref - reference to finalize

Throws:

REngineException

REXPMismatchException

getParentEnvironment

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

Description copied from class: REngine

get the parent environemnt of an environemnt

Specified by:

getParentEnvironment in class REngine

Parameters:

env - environment to query

resolve - whether to resolve the resulting environment reference

Returns:

parent environemnt of env

Throws:

REngineException

REXPMismatchException

newEnvironment

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

Description copied from class: REngine

create a new environemnt

Specified by:

newEnvironment in class REngine

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:

REXPMismatchException

REngineException

close

public boolean close()

Description copied from class: REngine

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.

Overrides:

close in class REngine

Returns:

true if the close opetaion was successful, false otherwise.

tryLock

public int tryLock()

attempts to obtain a lock for this R engine synchronously (without waiting for it).

Overrides:

tryLock in class REngine

Returns:

0 if the lock could not be obtained (R is busy) and some other value otherwise (1 = lock obtained, 2 = the current thread already holds a lock) -- the returned value must be used in a matching call to unlock(int).

lock

public int lock()

obains a lock for this R engine, waiting until it becomes available.

Overrides:

lock in class REngine

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

Overrides:

unlock in class REngine

Parameters:

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

supportsReferences

public boolean supportsReferences()

Description copied from class: REngine

check whether this engine supports references to R objects

Overrides:

supportsReferences in class REngine

Returns:

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

supportsEnvironments

public boolean supportsEnvironments()

Description copied from class: REngine

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

Overrides:

supportsEnvironments in class REngine

Returns:

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

supportsLocking

public boolean supportsLocking()

Description copied from class: REngine

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

Overrides:

supportsLocking in class REngine

Returns:

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

createRJavaRef

public REXPReference createRJavaRef(java.lang.Object o)
                             throws REngineException

creates a jobjRef reference in R via rJava.
Important: rJava must be loaded and intialized in R (e.g. via eval("{library(rJava);.jinit()}",false), otherwise this will fail. Requires rJava 0.4-13 or higher!

Parameters:

o - object to push to R

Returns:

unresolved REXPReference of the newly created jobjRef object or null upon failure

Throws:

REngineException

rWriteConsole

public void rWriteConsole(Rengine re,
                          java.lang.String text,
                          int oType)

JRI callbacks forwarding

Specified by:

rWriteConsole in interface RMainLoopCallbacks

Parameters:

re - calling engine

text - text to display in the console

oType - output type (0=regular, 1=error/warning)

rBusy

public void rBusy(Rengine re,
                  int which)

Description copied from interface: RMainLoopCallbacks

called when R enters or exits a longer evaluation. It is usually a good idea to signal this state to the user, e.g. by changing the cursor to a "hourglass" and back.

Specified by:

rBusy in interface RMainLoopCallbacks

Parameters:

re - calling engine

which - identifies whether R enters (1) or exits (0) the busy state

rReadConsole

public java.lang.String rReadConsole(Rengine re,
                                     java.lang.String prompt,
                                     int addToHistory)

Description copied from interface: RMainLoopCallbacks

called when R waits for user input. During the duration of this callback it is safe to re-enter R, and very often it is also the only time. The implementation is free to block on this call until the user hits Enter, but in JRI it is a good idea to call Rengine.rniIdle() occasionally to allow other event handlers (e.g graphics device UIs) to run. Implementations should NEVER return immediately even if there is no input - such behavior will result in a fast cycling event loop which makes the use of R pretty much impossible.

Specified by:

rReadConsole in interface RMainLoopCallbacks

Parameters:

re - calling engine

prompt - prompt to be displayed at the console prior to user's input

addToHistory - flag telling the handler whether the input should be considered for adding to history (!=0) or not (0)

Returns:

user's input to be passed to R for evaluation

rShowMessage

public void rShowMessage(Rengine re,
                         java.lang.String message)

Description copied from interface: RMainLoopCallbacks

called when R want to show a warning/error message (not to be confused with messages displayed in the console output)

Specified by:

rShowMessage in interface RMainLoopCallbacks

Parameters:

re - calling engine

message - message to display

rChooseFile

public java.lang.String rChooseFile(Rengine re,
                                    int newFile)

Description copied from interface: RMainLoopCallbacks

called when R expects the user to choose a file

Specified by:

rChooseFile in interface RMainLoopCallbacks

Parameters:

re - calling engine

newFile - flag determining whether an existing or new file is to be selecteed

Returns:

path/name of the selected file

rFlushConsole

public void rFlushConsole(Rengine re)

Description copied from interface: RMainLoopCallbacks

called when R requests the console to flush any buffered output

Specified by:

rFlushConsole in interface RMainLoopCallbacks

Parameters:

re - calling engine

rSaveHistory

public void rSaveHistory(Rengine re,
                         java.lang.String filename)

Description copied from interface: RMainLoopCallbacks

called to save the contents of the history (the implementation is responsible of keeping track of the history)

Specified by:

rSaveHistory in interface RMainLoopCallbacks

Parameters:

re - calling engine

filename - name of the history file

rLoadHistory

public void rLoadHistory(Rengine re,
                         java.lang.String filename)

Description copied from interface: RMainLoopCallbacks

called to load the contents of the history

Specified by:

rLoadHistory in interface RMainLoopCallbacks

Parameters:

re - calling engine

filename - name of the history file