weka.core

Class RSessionImpl

java.lang.Object

weka.core.RSessionImpl

All Implemented Interfaces:

org.rosuda.REngine.REngineCallbacks, org.rosuda.REngine.REngineOutputInterface, RSessionAPI

public class RSessionImpl
extends java.lang.Object
implements RSessionAPI, org.rosuda.REngine.REngineCallbacks, org.rosuda.REngine.REngineOutputInterface

Maintains a singleton object for managing R sessions. Because only one instance of R is allowed by JRI, and R is single threaded, we have to make sure that only one client has access to the R runtime at any one time.

This class should not be used directly. Instead, the weka.core.RSession class should be used - especially if running inside a system where multiple class loaders/plugins are used. This will ensure that the native libraries and supporting JRI classes get loaded by the root class loader and are thus available to all child class loaders.

For R to be available to Weka it is necessary for the user to:

1. Install the rJava (http://www.rforge.net/rJava/) package in R: install.packages("rJava")
2. Make sure that R is on the PATH
3. Make sure that the R_HOME environment variable points to the directory where the R executable is
4. Make sure that the R executable is in the PATH environment variable
5. Under Windows, R will prefer to install libraries into a personal library directory under the user's home directory. This is for security reasons and the user may not have write access for packages to be installed in the system-wide R install directory. It is essential that, after manually installing rJava, the user set the environment variable R_LIBS_USER to point to this directory as Weka will ask R to install certain packages
6. The package will try loading the native library from a known location under various OS's
   under Mac OSX this is in /Library/Frameworks/R.framework/Resources/library/rJava/jri/
   The user can override this by setting the property jri.native.library to point to the native library when starting Weka

More information on configuring Java to access JRI under various OS can be found at http://www.rforge.net/JRI/

Version:

$Revision: 12941 $

Author:

Mark Hall (mhall{[at]}pentaho{[dot]}com)

Constructor Summary

Constructors

Constructor and Description
RSessionImpl()

Method Summary

Modifier and Type	Method and Description
static RSessionAPI	acquireSession(java.lang.Object requester) Acquire the session for the requester
void	assign(java.lang.Object requester, java.lang.String var, byte[] val) Wraps REngine.assign
void	assign(java.lang.Object requester, java.lang.String var, double[] val) Wraps REngine.assign
void	assign(java.lang.Object requester, java.lang.String var, int[] val) Wraps REngine.assign
void	assign(java.lang.Object requester, java.lang.String var, org.rosuda.REngine.REXP val) Wraps REngine.assign
void	assign(java.lang.Object requester, java.lang.String var, java.lang.String[] val) Wraps REngine.assign
void	clearConsoleBuffer(java.lang.Object requester) Clear the contents of the R console buffer
void	close()
org.rosuda.REngine.REXP	createReference(java.lang.Object requester, org.rosuda.REngine.REXP source) Pushes an REXP back into R and, if successful, returns a reference REXP that points to the pushed object in R.
void	dropSession(java.lang.Object requester)
org.rosuda.REngine.REXP	get(java.lang.Object requester, java.lang.String var) Get a named object from R.
java.lang.String	getConsoleBuffer(java.lang.Object requester) Get the contents of the R console buffer
RSessionAPI	getSession(java.lang.Object requester)
static RSessionAPI	getSessionSingleton() Get the reference to the singleton.
RSessionAPI	init() Initialization routine.
boolean	installLibrary(java.lang.Object requester, java.lang.String libraryName) Convenience method for getting R to install a library.
boolean	installLibrary(java.lang.Object requester, java.lang.String libraryName, java.lang.String repos) Convenience method for getting R to install a library.
boolean	isVariableSet(java.lang.Object requester, java.lang.String var) Check if a named variable is set in the R environment
boolean	loadLibrary(java.lang.Object requester, java.lang.String libraryName) Convenience method for getting R to load a named library.
org.rosuda.REngine.REXP	parseAndEval(java.lang.Object requester, java.lang.String cmd) Wraps REngine.parseAndEval.
static boolean	rAvailable() Checks if R is available
static void	releaseSession(java.lang.Object requester) Release the session so that other clients can obtain it.
void	RFlushConsole(org.rosuda.REngine.REngine eng) called by R to flush (display) any pending console output.
void	RShowMessage(org.rosuda.REngine.REngine eng, java.lang.String text) called when R wants to show a warning/error message box (not console-related).
void	RWriteConsole(org.rosuda.REngine.REngine eng, java.lang.String text, int oType) called when R prints output to the console.
void	setLog(java.lang.Object requester, RLoggerAPI log) Set the logger to use

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RSessionImpl

public RSessionImpl()

Method Detail

init

public RSessionAPI init()
                 throws java.lang.Exception

Initialization routine. Attempts to load the JRI native library via weka.core.JRINativeLoader using reflection. This method is itself called through reflection by RSession via JRILoader. This somewhat convoluted process ensures that the JRI native library is loaded in the root classloader only (and is thus visible to all child classloaders). Furthermore, JRILoader makes sure that the bytecode for various core JRI, REngine and JavaGD classes gets injected into the root classloader. This ensures that there is just one singleton JRIEngine/Rengine available to all clients (potentially loaded in different classloaders), thus maintaining the single-threaded access to the underlying R engine.

Specified by:

init in interface RSessionAPI

Throws:

java.lang.Exception

getSessionSingleton

public static RSessionAPI getSessionSingleton()

Get the reference to the singleton. Used by proxy RSession's to obtain a reference.

Returns:

the singleton

setLog

public void setLog(java.lang.Object requester,
                   RLoggerAPI log)
            throws RSessionException

Set the logger to use

Specified by:

setLog in interface RSessionAPI

Parameters:

requester - the object registering the log (must be the current session holder)

log - the log to use

Throws:

RSessionException - if the requester is not the current session holder

clearConsoleBuffer

public void clearConsoleBuffer(java.lang.Object requester)
                        throws RSessionException

Clear the contents of the R console buffer

Specified by:

clearConsoleBuffer in interface RSessionAPI

Parameters:

requester - the requesting object (must be the session holder)

Throws:

RSessionException - if the requester is not the session holder

getConsoleBuffer

public java.lang.String getConsoleBuffer(java.lang.Object requester)
                                  throws RSessionException

Get the contents of the R console buffer

Specified by:

getConsoleBuffer in interface RSessionAPI

Parameters:

requester - the requesting object (must be the session holder)

Returns:

the contents of the console buffer as a string

Throws:

RSessionException - if the requester is not the session holder

getSession

public RSessionAPI getSession(java.lang.Object requester)
                       throws java.lang.Exception

Specified by:

getSession in interface RSessionAPI

Throws:

java.lang.Exception

dropSession

public void dropSession(java.lang.Object requester)

Specified by:

dropSession in interface RSessionAPI

rAvailable

public static boolean rAvailable()

Checks if R is available

Returns:

true if R is available

acquireSession

public static RSessionAPI acquireSession(java.lang.Object requester)
                                  throws java.lang.Exception

Acquire the session for the requester

Parameters:

requester - the object requesting the session

Returns:

the session singleton

Throws:

java.lang.Exception - if the session is currently held by another client

releaseSession

public static void releaseSession(java.lang.Object requester)

Release the session so that other clients can obtain it. This method does nothing if the requester is not the current session holder

Parameters:

requester - the session holder

loadLibrary

public boolean loadLibrary(java.lang.Object requester,
                           java.lang.String libraryName)
                    throws RSessionException,
                           org.rosuda.REngine.REngineException,
                           org.rosuda.REngine.REXPMismatchException

Convenience method for getting R to load a named library.

Specified by:

loadLibrary in interface RSessionAPI

Parameters:

requester - the requesting object

libraryName - the name of the library to load

Returns:

true if the library was loaded successfully

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

org.rosuda.REngine.REXPMismatchException - if a problem occurs on the R end

installLibrary

public boolean installLibrary(java.lang.Object requester,
                              java.lang.String libraryName)
                       throws RSessionException,
                              org.rosuda.REngine.REngineException,
                              org.rosuda.REngine.REXPMismatchException

Convenience method for getting R to install a library.

Specified by:

installLibrary in interface RSessionAPI

Parameters:

requester - the requesting object

libraryName - the name of the library to install

Returns:

true if the library was installed successfully

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

org.rosuda.REngine.REXPMismatchException - if a problem occurs on the R end

installLibrary

public boolean installLibrary(java.lang.Object requester,
                              java.lang.String libraryName,
                              java.lang.String repos)
                       throws RSessionException,
                              org.rosuda.REngine.REngineException,
                              org.rosuda.REngine.REXPMismatchException

Convenience method for getting R to install a library.

Specified by:

installLibrary in interface RSessionAPI

Parameters:

requester - the requesting object

libraryName - the name of the library to install

repos - the repository(s) to use

Returns:

true if the library was installed successfully

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

org.rosuda.REngine.REXPMismatchException - if a problem occurs on the R end

isVariableSet

public boolean isVariableSet(java.lang.Object requester,
                             java.lang.String var)
                      throws RSessionException,
                             org.rosuda.REngine.REngineException,
                             org.rosuda.REngine.REXPMismatchException

Check if a named variable is set in the R environment

Specified by:

isVariableSet in interface RSessionAPI

Parameters:

requester - the requesting object

var - the name of the variable to check

Returns:

true if the variable is set in the R environment

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R side

org.rosuda.REngine.REXPMismatchException - if a problem occurs on the R side

createReference

public org.rosuda.REngine.REXP createReference(java.lang.Object requester,
                                               org.rosuda.REngine.REXP source)
                                        throws RSessionException,
                                               org.rosuda.REngine.REngineException,
                                               org.rosuda.REngine.REXPMismatchException

Pushes an REXP back into R and, if successful, returns a reference REXP that points to the pushed object in R. The reference can be used in an assign() to assign a variable to the object.

Specified by:

createReference in interface RSessionAPI

Parameters:

requester - the requesting object

source - the source object to push into R

Returns:

a reference to the object in R

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

org.rosuda.REngine.REXPMismatchException - if a problem occurs on the R end

get

public org.rosuda.REngine.REXP get(java.lang.Object requester,
                                   java.lang.String var)
                            throws RSessionException,
                                   org.rosuda.REngine.REngineException,
                                   org.rosuda.REngine.REXPMismatchException

Get a named object from R. If the object is a reference (pointer) then this will return a fully dereferenced REXP.

Specified by:

get in interface RSessionAPI

Parameters:

requester - the requesting object

var - the name of the variable in R to get

Returns:

the fully dereferenced R object corresponding to var

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

org.rosuda.REngine.REXPMismatchException - if a problem occurs on the R end

assign

public void assign(java.lang.Object requester,
                   java.lang.String var,
                   org.rosuda.REngine.REXP val)
            throws RSessionException,
                   org.rosuda.REngine.REngineException,
                   org.rosuda.REngine.REXPMismatchException

Wraps REngine.assign

Specified by:

assign in interface RSessionAPI

Parameters:

requester - the requesting object

var - the name of the variable to assign to

val - an REXP object

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

org.rosuda.REngine.REXPMismatchException

assign

public void assign(java.lang.Object requester,
                   java.lang.String var,
                   byte[] val)
            throws RSessionException,
                   org.rosuda.REngine.REngineException

Wraps REngine.assign

Specified by:

assign in interface RSessionAPI

Parameters:

requester - the requesting object

var - the name of the variable to assign to

val - a byte[] value

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

assign

public void assign(java.lang.Object requester,
                   java.lang.String var,
                   double[] val)
            throws RSessionException,
                   org.rosuda.REngine.REngineException

Wraps REngine.assign

Specified by:

assign in interface RSessionAPI

Parameters:

requester - the requesting object

var - the name of the variable to assign to

val - a double[] value

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

assign

public void assign(java.lang.Object requester,
                   java.lang.String var,
                   int[] val)
            throws RSessionException,
                   org.rosuda.REngine.REngineException

Wraps REngine.assign

Specified by:

assign in interface RSessionAPI

Parameters:

requester - the requesting object

var - the name of the variable to assign to

val - a int[] value

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

assign

public void assign(java.lang.Object requester,
                   java.lang.String var,
                   java.lang.String[] val)
            throws RSessionException,
                   org.rosuda.REngine.REngineException

Wraps REngine.assign

Specified by:

assign in interface RSessionAPI

Parameters:

requester - the requesting object

var - the name of the variable to assign to

val - a String[] value

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

parseAndEval

public org.rosuda.REngine.REXP parseAndEval(java.lang.Object requester,
                                            java.lang.String cmd)
                                     throws RSessionException,
                                            org.rosuda.REngine.REngineException,
                                            org.rosuda.REngine.REXPMismatchException

Wraps REngine.parseAndEval. Evaluates one or more R commands as a script.

Specified by:

parseAndEval in interface RSessionAPI

Parameters:

requester - the requesting object

cmd - the command(s)

Returns:

the REXP object containing the results

Throws:

RSessionException - if the requester is not the current session holder

org.rosuda.REngine.REngineException - if a problem occurs on the R end

org.rosuda.REngine.REXPMismatchException - if a problem occurs on the R end

RFlushConsole

public void RFlushConsole(org.rosuda.REngine.REngine eng)

called by R to flush (display) any pending console output.

Specified by:

RFlushConsole in interface org.rosuda.REngine.REngineOutputInterface

Parameters:

eng - calling engine

RShowMessage

public void RShowMessage(org.rosuda.REngine.REngine eng,
                         java.lang.String text)

called when R wants to show a warning/error message box (not console-related).

Specified by:

RShowMessage in interface org.rosuda.REngine.REngineOutputInterface

Parameters:

eng - calling engine

text - text to display in the message

RWriteConsole

public void RWriteConsole(org.rosuda.REngine.REngine eng,
                          java.lang.String text,
                          int oType)

called when R prints output to the console.

Specified by:

RWriteConsole in interface org.rosuda.REngine.REngineOutputInterface

Parameters:

eng - calling engine

text - text to display in the console

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

close

public void close()

Specified by:

close in interface RSessionAPI