org.rosuda.REngine.Rserve
Class RConnection

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

public class RConnection
extends org.rosuda.REngine.REngine

class providing TCP/IP connection to an Rserve

Version:

$Id$

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 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(Socket sock)
create a connection based on a previously obtained socket.

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

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

Method Summary

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

RConnection

public RConnection(Socket sock)
            throws RserveException

create a connection based on a previously obtained socket. This constructor allows the use of other communication protocols than TCP/IP (if a Socket implementation exists) or tunneling through other protocols that expose socket insteface (such as SSL).

Parameters:

sock - connected socket

Throws:

RserveException

Method Detail

finalize

public void finalize()

Overrides:

finalize in class 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 org.rosuda.REngine.REngine

voidEval

public void voidEval(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(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 org.rosuda.REngine.REXP eval(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(String sym,
                   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 org.rosuda.REngine.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(String sym,
                   org.rosuda.REngine.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 org.rosuda.REngine.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(String fn)
                          throws 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:

IOException

createFile

public RFileOutputStream createFile(String fn)
                             throws 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:

IOException

removeFile

public void removeFile(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(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(String user,
                  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 String getLastError()

get last error string

Returns:

last error string

serverEval

public void serverEval(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(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 org.rosuda.REngine.REXP parse(String text,
                                     boolean resolve)
                              throws org.rosuda.REngine.REngineException

Specified by:

parse in class org.rosuda.REngine.REngine

Throws:

org.rosuda.REngine.REngineException

eval

public org.rosuda.REngine.REXP eval(org.rosuda.REngine.REXP what,
                                    org.rosuda.REngine.REXP where,
                                    boolean resolve)
                             throws org.rosuda.REngine.REngineException

Specified by:

eval in class org.rosuda.REngine.REngine

Throws:

org.rosuda.REngine.REngineException

parseAndEval

public org.rosuda.REngine.REXP parseAndEval(String text,
                                            org.rosuda.REngine.REXP where,
                                            boolean resolve)
                                     throws org.rosuda.REngine.REngineException

Overrides:

parseAndEval in class org.rosuda.REngine.REngine

Throws:

org.rosuda.REngine.REngineException

assign

public void assign(String symbol,
                   org.rosuda.REngine.REXP value,
                   org.rosuda.REngine.REXP env)
            throws org.rosuda.REngine.REngineException

assign into an environment

Specified by:

assign in class org.rosuda.REngine.REngine

Parameters:

symbol - symbol name

value - value to assign

env - environment to assign to

Throws:

org.rosuda.REngine.REngineException

get

public org.rosuda.REngine.REXP get(String symbol,
                                   org.rosuda.REngine.REXP env,
                                   boolean resolve)
                            throws org.rosuda.REngine.REngineException

get a value from an environment

Specified by:

get in class org.rosuda.REngine.REngine

Parameters:

symbol - symbol name

env - environment

resolve - resolve the resulting REXP or just return a reference

Returns:

value

Throws:

org.rosuda.REngine.REngineException

resolveReference

public org.rosuda.REngine.REXP resolveReference(org.rosuda.REngine.REXP ref)
                                         throws org.rosuda.REngine.REngineException

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

Specified by:

resolveReference in class org.rosuda.REngine.REngine

Parameters:

ref - reference to resolve

Returns:

resolved reference

Throws:

org.rosuda.REngine.REngineException

createReference

public org.rosuda.REngine.REXP createReference(org.rosuda.REngine.REXP ref)
                                        throws org.rosuda.REngine.REngineException

Specified by:

createReference in class org.rosuda.REngine.REngine

Throws:

org.rosuda.REngine.REngineException

finalizeReference

public void finalizeReference(org.rosuda.REngine.REXP ref)
                       throws org.rosuda.REngine.REngineException

Specified by:

finalizeReference in class org.rosuda.REngine.REngine

Throws:

org.rosuda.REngine.REngineException

getParentEnvironment

public org.rosuda.REngine.REXP getParentEnvironment(org.rosuda.REngine.REXP env,
                                                    boolean resolve)
                                             throws org.rosuda.REngine.REngineException

Specified by:

getParentEnvironment in class org.rosuda.REngine.REngine

Throws:

org.rosuda.REngine.REngineException

newEnvironment

public org.rosuda.REngine.REXP newEnvironment(org.rosuda.REngine.REXP parent,
                                              boolean resolve)
                                       throws org.rosuda.REngine.REngineException

Specified by:

newEnvironment in class org.rosuda.REngine.REngine

Throws:

org.rosuda.REngine.REngineException