Rengine

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.rosuda.JRI
Class Rengine

java.lang.Object
  java.lang.Thread
      org.rosuda.JRI.Rengine

All Implemented Interfaces:: java.lang.Runnable

public class Rengine
extends java.lang.Thread
extends java.lang.Thread

Rengine class is the interface between an instance of R and the Java VM. Due to the fact that R has no threading support, you can run only one instance of R withing a multi-threaded application. There are two ways to use R from Java: individual call and full event loop. See the Rengine constructor for details.

Important note: All methods starting with rni (R Native Interface) are low-level native methods that should be avoided if a high-level methods exists. They do NOT attempt any synchronization, so it is the duty of the calling program to ensure that the invocation is safe (see getRsync() for details). At some point in the future when the high-level API is complete they should become private. However, currently this high-level layer is not complete, so they are available for now.

All rni methods use long type to reference SEXPs on R side. Those reference should never be modified or used in arithmetics - the only reason for not using an extra interface class to wrap those references is that rni methods are all native methods and therefore it would be too expensive to handle the unwrapping on the C side.

jri methods are called internally by R and invoke the corresponding method from the even loop handler. Those methods should usualy not be called directly.

Since 0.5 a failure to load the JRI naitve library will not be fatal if jri.ignore.ule=yes system preference is set. Rengine will still not work, but that gives a chance to GUI programs to report the error in a more meaningful way (use jriLoaded to check the availability of JRI).

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread
`java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler`

Field Summary
`static int`	`DEBUG` debug flag.
`int`	`idleDelay` this value specifies the time (in ms) to spend sleeping between checks for R shutdown requests if R event loop is not used.
`static boolean`	`jriLoaded` this flags is set to `true` if the native code was successfully loaded.
`static int`	`SO_BaseEnv` constant to be used in `rniSpecialObject(int)` to return `R_baseEnv` reference
`static int`	`SO_BlankString` constant to be used in `rniSpecialObject(int)` to return `R_BlankString` reference
`static int`	`SO_EmptyEnv` constant to be used in `rniSpecialObject(int)` to return `R_EmptyEnv` reference
`static int`	`SO_GlobalEnv` constant to be used in `rniSpecialObject(int)` to return `R_GlobalEnv` reference
`static int`	`SO_MissingArg` constant to be used in `rniSpecialObject(int)` to return `R_MissingArg` reference
`static int`	`SO_NaString` constant to be used in `rniSpecialObject(int)` to return `R_NaString` reference
`static int`	`SO_NilValue` constant to be used in `rniSpecialObject(int)` to return `R_NilValue` reference
`static int`	`SO_UnboundValue` constant to be used in `rniSpecialObject(int)` to return `R_UnboundValue` reference

Fields inherited from class java.lang.Thread
`MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

Constructor Summary
`Rengine()` create a new engine by hooking into an existing, initialized R instance which is calling this constructor.
`Rengine(java.lang.String[] args, boolean runMainLoop, RMainLoopCallbacks initialCallbacks)` create and start a new instance of R.

Method Summary
`void`	`addMainLoopCallbacks(RMainLoopCallbacks c)` Add a handler for R callbacks.
`boolean`	`assign(java.lang.String sym, boolean[] val)` assign values of an array of booleans to a symbol in R (creating a logical vector).
`boolean`	`assign(java.lang.String sym, double[] val)` assign values of an array of doubles to a symbol in R (creating an integer vector).
`boolean`	`assign(java.lang.String sym, int[] val)` assign values of an array of integers to a symbol in R (creating a numeric vector).
`boolean`	`assign(java.lang.String sym, REXP r)` assign a content of a REXP to a symbol in R.
`boolean`	`assign(java.lang.String sym, java.lang.String ct)` assign a string value to a symbol in R.
`boolean`	`assign(java.lang.String sym, java.lang.String[] val)` assign values of an array of strings to a symbol in R (creating a character vector).
`REXP`	`createRJavaRef(java.lang.Object o)` creates a `jobjRef` reference in R via rJava.
`void`	`end()` attempt to shut down R.
`REXP`	`eval(java.lang.String s)` Parses and evaluates an R expression and returns the result.
`REXP`	`eval(java.lang.String s, boolean convert)` Parses and evaluates an R expression and returns the result.
`static Rengine`	`getMainEngine()` return the current main R engine instance.
`Mutex`	`getRsync()` returns the synchronization mutex for this engine.
`static long`	`getVersion()` API version of the Rengine itself; see also rniGetVersion() for binary version.
`REXP`	`idleEval(java.lang.String s)` This method is very much like `eval(String)`, except that it is non-blocking and returns `null` if the engine is busy.
`REXP`	`idleEval(java.lang.String s, boolean convert)` This method is very much like `eval(String,boolean)`, except that it is non-blocking and returns `null` if the engine is busy.
`static boolean`	`inMainRThread()` returns `true` if the current thread is the main R thread, `false` otherwise
`boolean`	`isStandAlone()` returns `true` if this engine was started as a stand-alone Java application or `false` if this engine was hooked into an existing R instance
`void`	`jriBusy(int which)` JRI: R_Busy call-back from R
`java.lang.String`	`jriChooseFile(int newFile)` JRI: R_ChooseFile call-back from R
`void`	`jriFlushConsole()` JRI: R_FlushConsole call-back from R
`void`	`jriLoadHistory(java.lang.String filename)` JRI: R_loadhistory call-back from R
`java.lang.String`	`jriReadConsole(java.lang.String prompt, int addToHistory)` JRI: R_ReadConsole call-back from R.
`void`	`jriSaveHistory(java.lang.String filename)` JRI: R_savehistory call-back from R
`void`	`jriShowMessage(java.lang.String message)` JRI: R_ShowMessage call-back from R
`void`	`jriWriteConsole(java.lang.String text, int oType)` JRI: R_WriteConsole call-back from R
`boolean`	`rniAssign(java.lang.String name, long exp, long rho)` RNI: assign a value to an environment
`long`	`rniCAR(long exp)` RNI: get CAR of a dotted-pair list (LISTSXP)
`long`	`rniCDR(long exp)` RNI: get CDR of a dotted-pair list (LISTSXP)
`long`	`rniCons(long head, long tail)` RNI: create a dotted-pair list (LISTSXP)
`long`	`rniCons(long head, long tail, long tag, boolean lang)` RNI: create a dotted-pair list (LISTSXP or LANGSXP)
`long`	`rniEval(long exp, long rho)` RNI: evaluate R expression (do NOT use directly unless you know exactly what you're doing, where possible use `eval(java.lang.String)` instead).
`int`	`rniExpType(long exp)` RNI: get the SEXP type
`long`	`rniFindVar(java.lang.String sym, long rho)` RNI: find variable in an environment
`long`	`rniGetAttr(long exp, java.lang.String name)` RNI: get an attribute
`java.lang.String[]`	`rniGetAttrNames(long exp)` RNI: get attribute names
`int[]`	`rniGetBoolArrayI(long exp)` RNI: get the contents of a logical vector in its integer array form
`double[]`	`rniGetDoubleArray(long exp)` RNI: get the contents of a numeric vector
`int[]`	`rniGetIntArray(long exp)` RNI: get the contents of an integer vector
`long[]`	`rniGetList(long exp)` RNI: retrieve CAR part of a dotted-part list recursively as an array of references
`byte[]`	`rniGetRawArray(long exp)` RNI: get the contents of a raw vector
`java.lang.String`	`rniGetString(long exp)` RNI: get the contents of the first entry of a character vector
`java.lang.String[]`	`rniGetStringArray(long exp)` RNI: get the contents of a character vector
`java.lang.String`	`rniGetSymbolName(long sym)` RNI: retrieve name of a symbol (c.f.
`long[]`	`rniGetVector(long exp)` RNI: get the contents of a generic vector (aka list)
`static long`	`rniGetVersion()` RNI: return the API version of the native library
`void`	`rniIdle()` RNI: run other event handlers in R
`boolean`	`rniInherits(long exp, java.lang.String cName)` RNI: determines whether an R object instance inherits from a specific class (S3 for now)
`long`	`rniInstallSymbol(java.lang.String sym)` RNI: install a symbol name
`long`	`rniJavaToXref(java.lang.Object o)` RNI: convert Java object to EXTPTRSEXP
`long`	`rniLCons(long head, long tail)` RNI: create a dotted-pair language list (LANGSXP)
`long`	`rniListEnv(long exp, boolean all)` RNI: return the list of variable names of an environment
`long`	`rniParentEnv(long exp)` RNI: return the parent environment
`long`	`rniParse(java.lang.String s, int parts)` RNI: parses a string into R expressions (do NOT use directly unless you know exactly what you're doing, where possible use `eval(java.lang.String)` instead).
`void`	`rniPreserve(long exp)` RNI: preserve object (prevent grabage collection in R) until rniRelease is called.
`void`	`rniPrint(java.lang.String s, int oType)` RNI: print.
`void`	`rniPrintValue(long exp)` RNI: print the value of a given R object (via print or show method) to the console
`void`	`rniProtect(long exp)` RNI: protect an R object (c.f.
`long`	`rniPutBoolArray(boolean[] a)` RNI: create a boolean vector
`long`	`rniPutBoolArrayI(int[] a)` RNI: create a boolean vector from an integer vector
`long`	`rniPutDoubleArray(double[] a)` RNI: create a numeric vector
`long`	`rniPutIntArray(int[] a)` RNI: create an integer vector
`long`	`rniPutList(long[] cont)` RNI: create a dotted-pair list (LISTSXP)
`long`	`rniPutRawArray(byte[] a)` RNI: create a raw vector
`long`	`rniPutString(java.lang.String s)` RNI: create a character vector of the length 1
`long`	`rniPutStringArray(java.lang.String[] a)` RNI: create a character vector
`long`	`rniPutVector(long[] exps)` RNI: create a generic vector (aka a list)
`void`	`rniRelease(long exp)` RNI: release object previously preserved via rniPreserve.
`int`	`rniRJavaLock()` RNI: lock rJava to allow callbacks - this interrupts R event loop until @link{rniRJavaUnlock} is called.
`int`	`rniRJavaUnlock()` RNI: unlock rJava - resumes R event loop.
`void`	`rniRunMainLoop()` RNI: run the main loop.
`void`	`rniSetAttr(long exp, java.lang.String name, long attr)` RNI: set an attribute
`int`	`rniSetupRJava(int _in, int _out)` RNI: setup IPC with RJava.
`long`	`rniSpecialObject(int which)` RNI: return a special object reference.
`int`	`rniStop(int flag)` RNI: interrupt the R process (if possible).
`long`	`rniTAG(long exp)` RNI: get TAG of a dotted-pair list (LISTSXP)
`void`	`rniUnprotect(int count)` RNI: unprotect last `count` references (c.f.
`java.lang.Object`	`rniXrefToJava(long exp)` RNI: convert EXTPTRSEXP to Java object - make sure the pointer is really what you expect, otherwise you'll crash the JVM!
`void`	`run()` The implementation of the R thread.
`void`	`startMainLoop()` if Rengine was initialized with `runMainLoop=false` then this method can be used to start the main loop at a later point.
`static boolean`	`versionCheck()` check API version of this class and the native binary.
`boolean`	`waitForR()` check the state of R

Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

jriLoaded

public static boolean jriLoaded

this flags is set to true if the native code was successfully loaded. If this flag is false then none of the rni methods are available. Previous

Since:: API 1.9, JRI 0.5

SO_NilValue

public static final int SO_NilValue

constant to be used in rniSpecialObject(int) to return R_NilValue reference

See Also:: Constant Field Values

SO_GlobalEnv

public static final int SO_GlobalEnv

constant to be used in rniSpecialObject(int) to return R_GlobalEnv reference

See Also:: Constant Field Values

SO_EmptyEnv

public static final int SO_EmptyEnv

constant to be used in rniSpecialObject(int) to return R_EmptyEnv reference

See Also:: Constant Field Values

SO_BaseEnv

public static final int SO_BaseEnv

constant to be used in rniSpecialObject(int) to return R_baseEnv reference

See Also:: Constant Field Values

SO_UnboundValue

public static final int SO_UnboundValue

constant to be used in rniSpecialObject(int) to return R_UnboundValue reference

See Also:: Constant Field Values

SO_MissingArg

public static final int SO_MissingArg

constant to be used in rniSpecialObject(int) to return R_MissingArg reference

See Also:: Constant Field Values

SO_NaString

public static final int SO_NaString

constant to be used in rniSpecialObject(int) to return R_NaString reference

See Also:: Constant Field Values

SO_BlankString

public static final int SO_BlankString

constant to be used in rniSpecialObject(int) to return R_BlankString reference

See Also:: Constant Field Values

DEBUG

public static int DEBUG

debug flag. Set to value >0 to enable debugging messages. The verbosity increases with increasing number

idleDelay

public int idleDelay

this value specifies the time (in ms) to spend sleeping between checks for R shutdown requests if R event loop is not used. The default is 200ms. Higher values lower the CPU usage but may make R less responsive to shutdown attempts (in theory it should not matter because Thread.stop() uses interrupt to awake from the idle sleep immediately, but some implementation may not honor that).

Since:: JRI 0.3

Constructor Detail

Rengine

public Rengine(java.lang.String[] args,
               boolean runMainLoop,
               RMainLoopCallbacks initialCallbacks)

create and start a new instance of R.

Parameters:: args - arguments to be passed to R. Please note that R requires the presence of certain arguments (e.g. --save or --no-save or equivalents), so passing an empty list usually doesn't work.; runMainLoop - if set to true the the event loop will be started as soon as possible, otherwise no event loop is started. Running loop requires initialCallbacks to be set correspondingly as well.; initialCallbacks - an instance implementing the RMainLoopCallbacks interface that provides methods to be called by R

Rengine

public Rengine()

create a new engine by hooking into an existing, initialized R instance which is calling this constructor. Currently JRI won't influence this R instance other than disabling stack checks (i.e. no callbacks can be registered etc.). It is *not* the designated constructor and it should be used *only* from withing rJava.

Since:: JRI 0.4

Method Detail

getVersion

public static long getVersion()

API version of the Rengine itself; see also rniGetVersion() for binary version. It's a good idea for the calling program to check the versions of both and abort if they don't match. This should be done using versionCheck()

Returns:: version number as long in the form 0xMMmm

versionCheck

public static boolean versionCheck()

check API version of this class and the native binary. This is usually a good idea to ensure consistency.

Returns:: true if the API version of the Java code and the native library matches, false otherwise

getMainEngine

public static Rengine getMainEngine()

return the current main R engine instance. Since there can be only one true R instance at a time, this is also the only instance. This may not be true for future versions, though.

Returns:: current instance of the R engine or null if no R engine was started yet.

inMainRThread

public static boolean inMainRThread()

returns true if the current thread is the main R thread, false otherwise

Since:: JRI 0.4

isStandAlone

public boolean isStandAlone()

returns true if this engine was started as a stand-alone Java application or false if this engine was hooked into an existing R instance

Since:: JRI 0.4

rniSetupRJava

public int rniSetupRJava(int _in,
                         int _out)

RNI: setup IPC with RJava. This method is used by rJava to pass the IPC information to the JRI engine for synchronization

Since:: experimental, not in the public API!

rniRJavaLock

public int rniRJavaLock()

RNI: lock rJava to allow callbacks - this interrupts R event loop until @link{rniRJavaUnlock} is called.

Returns:: 0 = lock failed, 1 = locked via IPC (you must use rniRJavaUnlock subsequently), 2 = rJava is already locked

rniRJavaUnlock

public int rniRJavaUnlock()

RNI: unlock rJava - resumes R event loop. Please note that unlocking without a previously successful lock may cause fatal errors, because it may release a lock issued by another thread which may not have finished yet.

rniParse

public long rniParse(java.lang.String s,
                     int parts)

RNI: parses a string into R expressions (do NOT use directly unless you know exactly what you're doing, where possible use eval(java.lang.String) instead). Note that no synchronization is performed!

Parameters:: s - string to parse; parts - number of expressions contained in the string
Returns:: reference to the resulting list of expressions

rniEval

public long rniEval(long exp,
                    long rho)

RNI: evaluate R expression (do NOT use directly unless you know exactly what you're doing, where possible use eval(java.lang.String) instead). Note that no synchronization is performed!

Parameters:: exp - reference to the expression to evaluate; rho - environment to use for evaluation (or 0 for global environemnt)
Returns:: result of the evaluation or 0 if an error occurred

rniProtect

public void rniProtect(long exp)

RNI: protect an R object (c.f. PROTECT macro in C)

Parameters:: exp - reference to protect
Since:: API 1.5, JRI 0.3

rniUnprotect

public void rniUnprotect(int count)

RNI: unprotect last count references (c.f. UNPROTECT in C)

Parameters:: count - number of references to unprotect
Since:: API 1.5, JRI 0.3

rniGetString

public java.lang.String rniGetString(long exp)

RNI: get the contents of the first entry of a character vector

Parameters:: exp - reference to STRSXP
Returns:: contents or null if the reference is not STRSXP

rniGetStringArray

public java.lang.String[] rniGetStringArray(long exp)

RNI: get the contents of a character vector

Parameters:: exp - reference to STRSXP
Returns:: contents or null if the reference is not STRSXP

rniGetIntArray

public int[] rniGetIntArray(long exp)

RNI: get the contents of an integer vector

Parameters:: exp - reference to INTSXP
Returns:: contents or null if the reference is not INTSXP

rniGetBoolArrayI

public int[] rniGetBoolArrayI(long exp)

RNI: get the contents of a logical vector in its integer array form

Parameters:: exp - reference to LGLSXP
Returns:: contents or null if the reference is not LGLSXP
Since:: API 1.6, JRI 0.3-2

rniGetDoubleArray

public double[] rniGetDoubleArray(long exp)

RNI: get the contents of a numeric vector

Parameters:: exp - reference to REALSXP
Returns:: contents or null if the reference is not REALSXP

rniGetRawArray

public byte[] rniGetRawArray(long exp)

RNI: get the contents of a raw vector

Parameters:: exp - reference to RAWSXP
Returns:: contents or null if the reference is not RAWSXP
Since:: API 1.9, JRI 0.5

rniGetVector

public long[] rniGetVector(long exp)

RNI: get the contents of a generic vector (aka list)

Parameters:: exp - reference to VECSXP
Returns:: contents as an array of references or null if the reference is not VECSXP

rniPutString

public long rniPutString(java.lang.String s)

RNI: create a character vector of the length 1

Parameters:: s - initial contents of the first entry
Returns:: reference to the resulting STRSXP

rniPutStringArray

public long rniPutStringArray(java.lang.String[] a)

RNI: create a character vector

Parameters:: a - initial contents of the vector
Returns:: reference to the resulting STRSXP

rniPutIntArray

public long rniPutIntArray(int[] a)

RNI: create an integer vector

Parameters:: a - initial contents of the vector
Returns:: reference to the resulting INTSXP

rniPutBoolArrayI

public long rniPutBoolArrayI(int[] a)

RNI: create a boolean vector from an integer vector

Parameters:: a - initial contents of the vector
Returns:: reference to the resulting LGLSXP
Since:: API 1.6, JRI 0.3-2

rniPutBoolArray

public long rniPutBoolArray(boolean[] a)

RNI: create a boolean vector

Parameters:: a - initial contents of the vector
Returns:: reference to the resulting LGLSXP
Since:: API 1.6, JRI 0.3-2

rniPutDoubleArray

public long rniPutDoubleArray(double[] a)

RNI: create a numeric vector

Parameters:: a - initial contents of the vector
Returns:: reference to the resulting REALSXP

rniPutRawArray

public long rniPutRawArray(byte[] a)

RNI: create a raw vector

Parameters:: a - initial contents of the vector
Returns:: reference to the resulting RAWSXP
Since:: API 1.9, JRI 0.5

rniPutVector

public long rniPutVector(long[] exps)

RNI: create a generic vector (aka a list)

Parameters:: exps - initial contents of the vector consisiting of an array of references
Returns:: reference to the resulting VECSXP

rniGetAttr

public long rniGetAttr(long exp,
                       java.lang.String name)

RNI: get an attribute

Parameters:: exp - reference to the object whose attribute is requested; name - name of the attribute
Returns:: reference to the attribute or 0 if there is none

rniGetAttrNames

public java.lang.String[] rniGetAttrNames(long exp)

RNI: get attribute names

Parameters:: exp - reference to the object whose attributes are requested
Returns:: a list of strings naming all attributes or null if there are none
Since:: API 1.9, JRI 0.5

rniSetAttr

public void rniSetAttr(long exp,
                       java.lang.String name,
                       long attr)

RNI: set an attribute

Parameters:: exp - reference to the object whose attribute is to be modified; name - attribute name; attr - reference to the object to be used as the contents of the attribute

rniInherits

public boolean rniInherits(long exp,
                           java.lang.String cName)

RNI: determines whether an R object instance inherits from a specific class (S3 for now)

Parameters:: exp - reference to an object; cName - name of the class to check
Returns:: true if cName inherits from class cName (see inherits in R)
Since:: API 1.5, JRI 0.3

rniCons

public long rniCons(long head,
                    long tail,
                    long tag,
                    boolean lang)

RNI: create a dotted-pair list (LISTSXP or LANGSXP)

Parameters:: head - CAR; tail - CDR (must be a reference to LISTSXP or 0); tag - TAG; lang - if true then LANGSXP is created, otherwise LISTSXP.
Returns:: reference to the newly created LISTSXP/LANGSXP
Since:: API 1.7, JRI 0.3-7

rniCons

public long rniCons(long head,
                    long tail)

RNI: create a dotted-pair list (LISTSXP)

Parameters:: head - CAR; tail - CDR (must be a reference to LISTSXP or 0)
Returns:: reference to the newly created LISTSXP

rniLCons

public long rniLCons(long head,
                     long tail)

RNI: create a dotted-pair language list (LANGSXP)

Parameters:: head - CAR; tail - CDR (must be a reference to LANGSXP or 0)
Returns:: reference to the newly created LANGSXP
Since:: API 1.7, JRI 0.3-7

rniCAR

public long rniCAR(long exp)

RNI: get CAR of a dotted-pair list (LISTSXP)

Parameters:: exp - reference to the list
Returns:: reference to CAR of the list (head)

rniCDR

public long rniCDR(long exp)

RNI: get CDR of a dotted-pair list (LISTSXP)

Parameters:: exp - reference to the list
Returns:: reference to CDR of the list (tail)

rniTAG

public long rniTAG(long exp)

RNI: get TAG of a dotted-pair list (LISTSXP)

Parameters:: exp - reference to the list
Returns:: reference to TAG of the list (tail)

rniPutList

public long rniPutList(long[] cont)

RNI: create a dotted-pair list (LISTSXP)

Parameters:: cont - contents as an array of references
Returns:: reference to the newly created LISTSXP
Since:: API 1.5, JRI 0.3

rniGetList

public long[] rniGetList(long exp)

RNI: retrieve CAR part of a dotted-part list recursively as an array of references

Parameters:: exp - reference to a dotted-pair list (LISTSXP)
Returns:: contents of the list as an array of references

rniGetSymbolName

public java.lang.String rniGetSymbolName(long sym)

RNI: retrieve name of a symbol (c.f. PRINTNAME)

Parameters:: sym - reference to a symbol
Returns:: name of the symbol or null on error or if exp is no symbol
Since:: API 1.5, JRI 0.3

rniInstallSymbol

public long rniInstallSymbol(java.lang.String sym)

RNI: install a symbol name

Parameters:: sym - symbol name
Returns:: reference to SYMSXP referencing the symbol
Since:: API 1.5, JRI 0.3

rniPrint

public void rniPrint(java.lang.String s,
                     int oType)

RNI: print.

Note: May NOT be called inside any WriteConsole callback as it would cause an infinite loop.

Parameters:: s - string to print (as-is); oType - output type (see R for exact references, but 0 should be regular output and 1 error/warning)
Since:: API 1.8, JRI 0.4

rniPrintValue

public void rniPrintValue(long exp)

RNI: print the value of a given R object (via print or show method) to the console

Parameters:: exp - reference to an R object
Since:: API 1.9, JRI 0.5

rniPreserve

public void rniPreserve(long exp)

RNI: preserve object (prevent grabage collection in R) until rniRelease is called.

Parameters:: exp - reference to an R object
Since:: API 1.9, JRI 0.5

rniRelease

public void rniRelease(long exp)

RNI: release object previously preserved via rniPreserve.

Note: releasing an obejct that was not preserved is an error and results in an undefined behavior.

Parameters:: exp - reference to an R object
Since:: API 1.9, JRI 0.5

rniParentEnv

public long rniParentEnv(long exp)

RNI: return the parent environment

Parameters:: exp - reference to environment
Returns:: parent environment
Since:: API 1.9, JRI 0.5

rniFindVar

public long rniFindVar(java.lang.String sym,
                       long rho)

RNI: find variable in an environment

Parameters:: sym - symbol name; rho - reference to environment
Returns:: reference to the value or UnboundValue if not found
Since:: API 1.9, JRI 0.5

rniListEnv

public long rniListEnv(long exp,
                       boolean all)

RNI: return the list of variable names of an environment

Parameters:: exp - reference to the environment; all - if set to true then all objects will be shown, otherwise hidden objects will be omitted
Returns:: reference to a string vector of names in the environment
Since:: API 1.9, JRI 0.5

rniSpecialObject

public long rniSpecialObject(int which)

RNI: return a special object reference. Note that all such references are constants valid for the entire session and cannot be protected/preserved (they are persistent already).

Parameters:: which - constant referring to a particular special object (see SO_xxx constants)
Returns:: reference to a special object or 0 if the kind of object it unknown/unsupported
Since:: API 1.9, JRI 0.5

rniJavaToXref

public long rniJavaToXref(java.lang.Object o)

RNI: convert Java object to EXTPTRSEXP

Parameters:: o - arbitrary Java object
Returns:: new EXTPTRSEXP pointing to the Java object
Since:: API 1.5, JRI 0.3

rniXrefToJava

public java.lang.Object rniXrefToJava(long exp)

RNI: convert EXTPTRSEXP to Java object - make sure the pointer is really what you expect, otherwise you'll crash the JVM!

Parameters:: exp - reference to EXTPTRSEXP pointing to a Java object
Returns:: resulting Java object
Since:: API 1.5, JRI 0.3

rniGetVersion

public static long rniGetVersion()

RNI: return the API version of the native library

Returns:: API version of the native library

rniStop

public int rniStop(int flag)

RNI: interrupt the R process (if possible). Note that R handles interrupt requests in (R-thread-)synchronous, co-operative fashion as it wants to make sure that the interrupted state is recoverable. If interrupting from another thread while using blocking ReadConsole REPL make sure you also interrupt your ReadConsole call after rniStop such that R can act on the signalled interrupt.

Parameters:: flag - determines how to attempt to inform R about the interrput. For normal (safe) operation using flag signalling must be 0. Other options are 1 (SIGINT for compatibility with older JRI API) and 2 (Rf_onintr call - use only on the R thread and only if you know what it means). Values other than 0 are only supported since JRI 0.5-4.
Returns:: result code (currently 0)

rniAssign

public boolean rniAssign(java.lang.String name,
                         long exp,
                         long rho)

RNI: assign a value to an environment

Parameters:: name - name; exp - value; rho - environment (use 0 for the global environment)
Returns:: true if successful, false on failure (usually this means that the binding is locked)
Since:: API 1.10, JRI 0.5-1 (existed before but returned void)

rniExpType

public int rniExpType(long exp)

RNI: get the SEXP type

Parameters:: exp - reference to a SEXP
Returns:: type of the expression (see xxxSEXP constants)

rniRunMainLoop

public void rniRunMainLoop()

RNI: run the main loop.
Note: this is an internal method and it doesn't return until the loop exits. Don't use directly!

rniIdle

public void rniIdle()

RNI: run other event handlers in R

addMainLoopCallbacks

public void addMainLoopCallbacks(RMainLoopCallbacks c)

Add a handler for R callbacks. The current implementation supports only one handler at a time, so call to this function implicitly removes any previous handlers

startMainLoop

public void startMainLoop()

if Rengine was initialized with runMainLoop=false then this method can be used to start the main loop at a later point. It has no effect if the loop is running already. This method returns immediately but the loop will be started once the engine is ready. Please note that there is currently no way of stopping the R thread if the R event loop is running other than using quit command in R which closes the entire application.

jriWriteConsole

public void jriWriteConsole(java.lang.String text,
                            int oType)

JRI: R_WriteConsole call-back from R

Parameters:: text - text to disply

jriBusy

public void jriBusy(int which)

JRI: R_Busy call-back from R

Parameters:: which - state

jriReadConsole

public java.lang.String jriReadConsole(java.lang.String prompt,
                                       int addToHistory)

JRI: R_ReadConsole call-back from R.

Parameters:: prompt - prompt to display before waiting for the input.
Note: implementations should block for input. Returning immediately is usually a bad idea, because the loop will be cycling.; addToHistory - flag specifying whether the entered contents should be added to history
Returns:: content entered by the user. Returning null corresponds to an EOF and usually causes R to exit (as in q()).





jriShowMessage
public void jriShowMessage(java.lang.String message)

JRI: R_ShowMessage call-back from R


Parameters:
message - message





jriLoadHistory
public void jriLoadHistory(java.lang.String filename)

JRI: R_loadhistory call-back from R


Parameters:
filename - name of the history file





jriSaveHistory
public void jriSaveHistory(java.lang.String filename)

JRI: R_savehistory call-back from R


Parameters:
filename - name of the history file





jriChooseFile
public java.lang.String jriChooseFile(int newFile)

JRI: R_ChooseFile call-back from R


Parameters:
newFile - flag specifying whether an existing or new file is requested
Returns:
name of the selected file or null if cancelled





jriFlushConsole
public void jriFlushConsole()

JRI: R_FlushConsole call-back from R








eval
public REXP eval(java.lang.String s)

Parses and evaluates an R expression and returns the result. Has the same effect as calling eval(s, true).


Parameters:
s - expression (as string) to parse and evaluate
Returns:
resulting expression or null if something wnet wrong





eval
public REXP eval(java.lang.String s,
                 boolean convert)

Parses and evaluates an R expression and returns the result.


Parameters:
s - expression (as string) to parse and evaluate
convert - if set to true the resulting REXP will contain native representation of the contents, otherwise an empty REXP will be returned. Depending on the back-end an empty REXP may or may not be used to convert the result at a later point.
Returns:
resulting expression or null if something wnet wrong
Since:
  JRI 0.3






idleEval
public REXP idleEval(java.lang.String s)

This method is very much like eval(String), except that it is non-blocking and returns null if the engine is busy.


Parameters:
s - string to evaluate
Returns:
result of the evaluation or null if the engine is busy





idleEval
public REXP idleEval(java.lang.String s,
                     boolean convert)

This method is very much like eval(String,boolean), except that it is non-blocking and returns null if the engine is busy.


Parameters:
s - string to evaluate
convert - flag denoting whether an empty or fully-converted REXP should be returned (see eval(String,boolean) for details)
Returns:
result of the evaluation or null if the engine is busy
Since:
  JRI 0.3






getRsync
public Mutex getRsync()

returns the synchronization mutex for this engine. If an external code needs to use RNI calls, it should do so only in properly protected environment secured by this mutex. Usually the procedure should be as follows:        boolean obtainedLock = e.getRsync().safeLock();
        try {
                // use RNI here ...
        } finally {
                if (obtainedLock) e.getRsync().unlock();
        }
        



Returns:
synchronization mutex
Since:
  JRI 0.3






waitForR
public boolean waitForR()

check the state of R



Returns:
true if R is alive and false if R died or exitted





end
public void end()

attempt to shut down R. This method is asynchronous.








run
public void run()

The implementation of the R thread. This method should not be called directly.


Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread








assign
public boolean assign(java.lang.String sym,
                      java.lang.String ct)

assign a string value to a symbol in R. The symbol is created if it doesn't exist already.


Parameters:
sym - symbol name.  The symbol name is used as-is, i.e. as if it was quoted in R code (for example assigning to "foo$bar" has the same effect as `foo$bar`<- and NOT foo$bar<-).
ct - contents
Returns:
true if successful, false otherwise
Since:
  JRI 0.3 (return value changed to boolean in JRI 0.5-1)






assign
public boolean assign(java.lang.String sym,
                      REXP r)

assign a content of a REXP to a symbol in R. The symbol is created if it doesn't exist already.


Parameters:
sym - symbol name. The symbol name is used as-is, i.e. as if it was quoted in R code (for example assigning to "foo$bar" has the same effect as `foo$bar`<- and NOT foo$bar<-).
r - contents as REXP. currently only raw references and basic types (int, double, int[], double[], boolean[]) are supported.
Returns:
true if successful, false otherwise (usually locked binding or unsupported REXP)
Since:
  JRI 0.3 (return value changed to boolean in JRI 0.5-1)






assign
public boolean assign(java.lang.String sym,
                      double[] val)

assign values of an array of doubles to a symbol in R (creating an integer vector).

        equals to calling assign(String, REXP).


Parameters:
sym - symbol name
val - double array to assign
Returns:
true if successful, false otherwise
Since:
  JRI 0.3 (return value changed to boolean in JRI 0.5-1)






assign
public boolean assign(java.lang.String sym,
                      int[] val)

assign values of an array of integers to a symbol in R (creating a numeric vector).

        equals to calling assign(String, REXP).


Parameters:
sym - symbol name
val - integer array to assign
Returns:
true if successful, false otherwise
Since:
  JRI 0.3 (return value changed to boolean in JRI 0.5-1)






assign
public boolean assign(java.lang.String sym,
                      boolean[] val)

assign values of an array of booleans to a symbol in R (creating a logical vector).

        equals to calling assign(String, REXP).


Parameters:
sym - symbol name
val - boolean array to assign
Returns:
true if successful, false otherwise
Since:
  JRI 0.3-2 (return value changed to boolean in JRI 0.5-1)






assign
public boolean assign(java.lang.String sym,
                      java.lang.String[] val)

assign values of an array of strings to a symbol in R (creating a character vector).

        equals to calling assign(String, REXP).


Parameters:
sym - symbol name
val - string array to assign
Returns:
true if successful, false otherwise
Since:
  JRI 0.3 (return value changed to boolean in JRI 0.5-1)






createRJavaRef
public REXP createRJavaRef(java.lang.Object o)

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
Returns:
Pure REXP reference of the newly created jobjRef object or null upon failure. It will have the type XT_NONE such that it can be used in @link{assign(String, REXP)}.
Since:
  JRI 0.3-7















  
      Overview 
      Package 
    Class 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.rosuda.JRI Class Rengine

jriLoaded

SO_NilValue

SO_GlobalEnv

SO_EmptyEnv

SO_BaseEnv

SO_UnboundValue

SO_MissingArg

SO_NaString

SO_BlankString

DEBUG

idleDelay

Rengine

Rengine

getVersion

versionCheck

getMainEngine

inMainRThread

isStandAlone

rniSetupRJava

rniRJavaLock

rniRJavaUnlock

rniParse

rniEval

rniProtect

rniUnprotect

rniGetString

rniGetStringArray

rniGetIntArray

rniGetBoolArrayI

rniGetDoubleArray

rniGetRawArray

rniGetVector

rniPutString

rniPutStringArray

rniPutIntArray

rniPutBoolArrayI

rniPutBoolArray

rniPutDoubleArray

rniPutRawArray

rniPutVector

rniGetAttr

rniGetAttrNames

rniSetAttr

rniInherits

rniCons

rniCons

rniLCons

rniCAR

rniCDR

rniTAG

rniPutList

rniGetList

rniGetSymbolName

rniInstallSymbol

rniPrint

rniPrintValue

rniPreserve

rniRelease

rniParentEnv

rniFindVar

rniListEnv

rniSpecialObject

rniJavaToXref

rniXrefToJava

rniGetVersion

rniStop

rniAssign

rniExpType

rniRunMainLoop

rniIdle

addMainLoopCallbacks

startMainLoop

jriWriteConsole

jriBusy

jriReadConsole

jriShowMessage

jriLoadHistory

jriSaveHistory

jriChooseFile

org.rosuda.JRI
Class Rengine