org.rosuda.REngine.Rserve
Class RConnection

java.lang.Object
  org.rosuda.REngine.REngine
      org.rosuda.REngine.Rserve.RConnection

public class RConnection
extends REngine

class providing TCP/IP connection to an Rserve

Version:

$Id: RConnection.java 3404 2011-07-28 14:57:31Z urbanek $

Field Summary

static int	AT_crypt authorization type: unix crypt
static int	AT_plain authorization type: plain text
protected int	rsrvVersion version of the server (as reported in IDstring just after Rsrv)
static java.lang.String	transferCharset This static variable specifies the character set used to encode string for transfer.

Fields inherited from class org.rosuda.REngine.REngine

lastEngine

Constructor Summary

RConnection()
make a new local connection on default port (6311)

RConnection(java.lang.String host)
make a new connection to specified host on default port (6311)

RConnection(java.lang.String host, int port)
make a new connection to specified host and given port.

Method Summary

void	assign(java.lang.String sym, REXP rexp) assign a content of a REXP to a symbol in R.
void	assign(java.lang.String symbol, REXP value, REXP env) assign into an environment
void	assign(java.lang.String sym, java.lang.String ct) assign a string value to a symbol in R.
boolean	close() closes current connection
RFileOutputStream	createFile(java.lang.String fn) create a file on the Rserve for writing
REXP	createReference(REXP ref) create a reference by pushing local data to R and returning a reference to the data.
RSession	detach() detaches the session and closes the connection (requires Rserve 0.4+).
REXP	eval(REXP what, REXP where, boolean resolve) evaluate an expression vector
REXP	eval(java.lang.String cmd) evaluates the given command and retrieves the result
void	finalize()
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
java.lang.String	getLastError() get last error string
REXP	getParentEnvironment(REXP env, boolean resolve) get the parent environemnt of an environemnt
int	getServerVersion() get server version as reported during the handshake.
boolean	isConnected() check connection state.
void	login(java.lang.String user, java.lang.String pwd) login using supplied user/pwd.
boolean	needLogin() check authentication requirement sent by server
REXP	newEnvironment(REXP parent, boolean resolve) create a new environemnt
RFileInputStream	openFile(java.lang.String fn) open a file on the Rserve for reading
REXP	parse(java.lang.String text, boolean resolve) parse a string into an expression vector
REXP	parseAndEval(java.lang.String text, REXP where, boolean resolve) convenince method equivalent to eval(parse(text, false), where, resolve);
void	removeFile(java.lang.String fn) remove a file on the Rserve
REXP	resolveReference(REXP ref) fetch the contents of the given reference.
void	serverEval(java.lang.String cmd) evaluates the given command in the master server process asynchronously (control command).
void	serverShutdown() attempt to shut down the server process cleanly.
void	serverSource(java.lang.String serverFile) sources the given file (the path must be local to the server!)
void	setSendBufferSize(long sbs) Sets send buffer size of the Rserve (in bytes) for the current connection.
void	setStringEncoding(java.lang.String enc) set string encoding for this session.
void	shutdown() shutdown remote Rserve.
void	voidEval(java.lang.String cmd) evaluates the given command, but does not fetch the result (useful for assignment operations)
RSession	voidEvalDetach(java.lang.String cmd) evaluates the given command, detaches the session (see @link{detach()}) and closes connection while the command is being evaluted (requires Rserve 0.4+).

Methods inherited from class org.rosuda.REngine.REngine

assign, assign, assign, assign, engineForClass, engineForClass, getLastEngine, lock, parseAndEval, supportsEnvironments, supportsLocking, supportsReferences, supportsREPL, toString, tryLock, unlock, wrap

Methods inherited from class java.lang.Object

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

Field Detail

transferCharset

public static java.lang.String transferCharset

This static variable specifies the character set used to encode string for transfer. Under normal circumstances there should be no reason for changing this variable. The default is UTF-8, which makes sure that 7-bit ASCII characters are sent in a backward-compatible fashion. Currently (Rserve 0.1-7) there is no further conversion on Rserve's side, i.e. the strings are passed to R without re-coding. If necessary the setting should be changed before connecting to the Rserve in case later Rserves will provide a possibility of setting the encoding during the handshake.

AT_plain

public static final int AT_plain

authorization type: plain text

See Also:

Constant Field Values

AT_crypt

public static final int AT_crypt

authorization type: unix crypt

See Also:

Constant Field Values

rsrvVersion

protected int rsrvVersion

version of the server (as reported in IDstring just after Rsrv)

Constructor Detail

RConnection

public RConnection()
            throws RserveException

make a new local connection on default port (6311)

Throws:

RserveException

RConnection

public RConnection(java.lang.String host)
            throws RserveException

make a new connection to specified host on default port (6311)

Parameters:

host - host name/IP

Throws:

RserveException

RConnection

public RConnection(java.lang.String host,
                   int port)
            throws RserveException

make a new connection to specified host and given port. Make sure you check isConnected() to ensure the connection was successfully created.

Parameters:

host - host name/IP

port - TCP port

Throws:

RserveException

Method Detail

finalize

public void finalize()

Overrides:

finalize in class java.lang.Object

getServerVersion

public int getServerVersion()

get server version as reported during the handshake.

Returns:

server version as integer (Rsrv0100 will return 100)

close

public boolean close()

closes current connection

Overrides:

close in class REngine

Returns:

true if the close opetaion was successful, false otherwise.

voidEval

public void voidEval(java.lang.String cmd)
              throws RserveException

evaluates the given command, but does not fetch the result (useful for assignment operations)

Parameters:

cmd - command/expression string

Throws:

RserveException

voidEvalDetach

public RSession voidEvalDetach(java.lang.String cmd)
                        throws RserveException

evaluates the given command, detaches the session (see @link{detach()}) and closes connection while the command is being evaluted (requires Rserve 0.4+). Note that a session cannot be attached again until the commad was successfully processed. Techincally the session is put into listening mode while the command is being evaluated but accept is called only after the command was evaluated. One commonly used techique to monitor detached working sessions is to use second connection to poll the status (e.g. create a temporary file and return the full path before detaching thus allowing new connections to read it).

Parameters:

cmd - command/expression string

Returns:

session object that can be use to attach back to the session once the command completed

Throws:

RserveException

eval

public REXP eval(java.lang.String cmd)
          throws RserveException

evaluates the given command and retrieves the result

Parameters:

cmd - command/expression string

Returns:

R-xpression or null if an error occured

Throws:

RserveException

assign

public void assign(java.lang.String sym,
                   java.lang.String ct)
            throws RserveException

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

Overrides:

assign in class REngine

Parameters:

sym - symbol name. Currently assign uses CMD_setSEXP command of Rserve, i.e. the symbol value is NOT parsed. It is the responsibility of the user to make sure that the symbol name is valid in R (recall the difference between a symbol and an expression!). In fact R will always create the symbol, but it may not be accessible (examples: "bar\nfoo" or "bar$foo").

ct - contents

Throws:

RserveException

assign

public void assign(java.lang.String sym,
                   REXP rexp)
            throws RserveException

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

Overrides:

assign in class REngine

Parameters:

sym - symbol name. Currently assign uses CMD_setSEXP command of Rserve, i.e. the symbol value is NOT parsed. It is the responsibility of the user to make sure that the symbol name is valid in R (recall the difference between a symbol and an expression!). In fact R will always create the symbol, but it may not be accessible (examples: "bar\nfoo" or "bar$foo").

rexp - contents

Throws:

RserveException

openFile

public RFileInputStream openFile(java.lang.String fn)
                          throws java.io.IOException

open a file on the Rserve for reading

Parameters:

fn - file name. should not contain any path delimiters, since Rserve may restrict the access to local working directory.

Returns:

input stream to be used for reading. Note that the stream is read-once only, there is no support for seek or rewind.

Throws:

java.io.IOException

createFile

public RFileOutputStream createFile(java.lang.String fn)
                             throws java.io.IOException

create a file on the Rserve for writing

Parameters:

fn - file name. should not contain any path delimiters, since Rserve may restrict the access to local working directory.

Returns:

output stream to be used for writinging. Note that the stream is write-once only, there is no support for seek or rewind.

Throws:

java.io.IOException

removeFile

public void removeFile(java.lang.String fn)
                throws RserveException

remove a file on the Rserve

Parameters:

fn - file name. should not contain any path delimiters, since Rserve may restrict the access to local working directory.

Throws:

RserveException

shutdown

public void shutdown()
              throws RserveException

shutdown remote Rserve. Note that some Rserves cannot be shut down from the client side.

Throws:

RserveException

setSendBufferSize

public void setSendBufferSize(long sbs)
                       throws RserveException

Sets send buffer size of the Rserve (in bytes) for the current connection. All responses send by Rserve are stored in the send buffer before transmitting. This means that any objects you want to get from the Rserve need to fit into that buffer. By default the size of the send buffer is 2MB. If you need to receive larger objects from Rserve, you will need to use this function to enlarge the buffer. In order to save memory, you can also reduce the buffer size once it's not used anymore. Currently the buffer size is only limited by the memory available and/or 1GB (whichever is smaller). Current Rserve implementations won't go below buffer sizes of 32kb though. If the specified buffer size results in 'out of memory' on the server, the corresponding error is sent and the connection is terminated.
Note: This command may go away in future versions of Rserve which will use dynamic send buffer allocation.

Parameters:

sbs - send buffer size (in bytes) min=32k, max=1GB

Throws:

RserveException

setStringEncoding

public void setStringEncoding(java.lang.String enc)
                       throws RserveException

set string encoding for this session. It is strongly recommended to make sure the encoding is always set to UTF-8 because that is the only encoding supported by this Java client. It can be done either by uisng the encoding option in the server or by calling setStringEncoding("utf8") at the beginning of a session (but after login).

Parameters:

enc - name of the encoding as defined by Rserve - as of Rserve version 0.5-3 valid values are "utf8", "latin1" and "native" (case-sensitive)

Throws:

RserveException

Since:

Rserve 0.5-3

login

public void login(java.lang.String user,
                  java.lang.String pwd)
           throws RserveException

login using supplied user/pwd. Note that login must be the first command if used

Parameters:

user - username

pwd - password

Throws:

RserveException

detach

public RSession detach()
                throws RserveException

detaches the session and closes the connection (requires Rserve 0.4+). The session can be only resumed by calling @link{RSession.attach}

Throws:

RserveException

isConnected

public boolean isConnected()

check connection state. Note that currently this state is not checked on-the-spot, that is if connection went down by an outside event this is not reflected by the flag

Returns:

true if this connection is alive

needLogin

public boolean needLogin()

check authentication requirement sent by server

Returns:

true is server requires authentication. In such case first command after connecting must be login(java.lang.String, java.lang.String).

getLastError

public java.lang.String getLastError()

get last error string

Returns:

last error string

serverEval

public void serverEval(java.lang.String cmd)
                throws RserveException

evaluates the given command in the master server process asynchronously (control command). Note that control commands are always asynchronous, i.e., the expression is enqueued for evaluation in the master process and the method returns before the expression is evaluated (in non-parallel builds the client has to close the connection before the expression can be evaluated). There is no way to check for errors and control commands should be sent with utmost care as they can abort the server process. The evaluation has no immediate effect on the client session.

Parameters:

cmd - command/expression string

Throws:

RserveException

Since:

Rserve 0.6-0

serverSource

public void serverSource(java.lang.String serverFile)
                  throws RserveException

sources the given file (the path must be local to the server!) in the master server process asynchronously (control command). See #serverEval() for details on control commands.

Parameters:

serverFile - path to a file on the server (it is recommended to always use full paths, because the server process has a different working directory than the client child process!).

Throws:

RserveException

Since:

Rserve 0.6-0

serverShutdown

public void serverShutdown()
                    throws RserveException

attempt to shut down the server process cleanly. Note that there is a fundamental difference between the shutdown() method and this method: serverShutdown() is a proper control command and thus fully authentication controllable, whereas shutdown() is a client-side command sent to the client child process and thus relying on the ability of the client to signal the server process which may be disabled. Therefore serverShutdown() is preferred and more reliable for Rserve 0.6-0 and higher.

Throws:

RserveException

Since:

Rserve 0.6-0

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

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

parseAndEval

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

Description copied from class: REngine

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

Overrides:

parseAndEval in class REngine

Parameters:

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

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

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

Returns:

result

Throws:

REngineException

assign

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

assign into an environment

Specified by:

assign in class REngine

Parameters:

symbol - symbol name

value - value to assign

env - environment to assign to

Throws:

REngineException

get

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

get a value from an environment

Specified by:

get in class REngine

Parameters:

symbol - symbol name

env - environment

resolve - resolve the resulting REXP or just return a reference

Returns:

value

Throws:

REngineException

resolveReference

public REXP resolveReference(REXP ref)
                      throws REngineException

fetch the contents of the given reference. The resulting REXP may never be REXPReference.

Specified by:

resolveReference in class REngine

Parameters:

ref - reference to resolve

Returns:

resolved reference

Throws:

REngineException

createReference

public REXP createReference(REXP ref)
                     throws REngineException

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:

ref - to create reference to

Returns:

reference to the value

Throws:

REngineException

finalizeReference

public void finalizeReference(REXP ref)
                       throws REngineException

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

getParentEnvironment

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

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

newEnvironment

public REXP newEnvironment(REXP parent,
                           boolean resolve)
                    throws 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:

REngineException