org.rosuda.JRclient
Class Rconnection

java.lang.Object
  org.rosuda.JRclient.Rconnection

public class Rconnection
extends java.lang.Object

class providing TCP/IP connection to an Rserve

Version:

$Id: Rconnection.java 2737 2007-04-30 22:25:30Z 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.

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, double[] val) assign values of an array of doubles to a symbol in R (creating as vector of numbers).
void	assign(java.lang.String sym, int[] val) assign values of an array of integers to a symbol in R (creating as vector of numbers).
void	assign(java.lang.String sym, REXP r) assign a content of a REXP to a symbol in R.
void	assign(java.lang.String sym, java.lang.String ct) assign a string value to a symbol in R.
void	close() closes current connection
RFileOutputStream	createFile(java.lang.String fn) create a file on the Rserve for writing
RSession	detach() detaches the session and closes the connection (requires Rserve 0.4+).
REXP	eval(java.lang.String cmd) evaluates the given command and retrieves the result
void	finalize()
java.lang.String	getLastError() get last error string
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
RFileInputStream	openFile(java.lang.String fn) open a file on the Rserve for reading
void	removeFile(java.lang.String fn) remove a file on the Rserve
void	setSendBufferSize(long sbs) Sets send buffer size of the Rserve (in bytes) for the current connection.
void	shutdown() shutdown remote Rserv.
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 java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, 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 RSrvException

make a new local connection on default port (6311)

Throws:

RSrvException

Rconnection

public Rconnection(java.lang.String host)
            throws RSrvException

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

Parameters:

host - host name/IP

Throws:

RSrvException

Rconnection

public Rconnection(java.lang.String host,
                   int port)
            throws RSrvException

make a new connection to specified host and given port. Make sure you check isConnected() and/or #isOk.

Parameters:

host - host name/IP

port - TCP port

Throws:

RSrvException

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 void close()

closes current connection

voidEval

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

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

Parameters:

cmd - command/expression string

Throws:

RSrvException

voidEvalDetach

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

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:

RSrvException

eval

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

evaluates the given command and retrieves the result

Parameters:

cmd - command/expression string

Returns:

R-xpression or null if an error occured

Throws:

RSrvException

assign

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

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

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:

RSrvException

assign

public void assign(java.lang.String sym,
                   REXP r)
            throws RSrvException

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. 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. currently only basic types (int, double, int[], double[]) are supported.

Throws:

RSrvException

assign

public void assign(java.lang.String sym,
                   double[] val)
            throws RSrvException

assign values of an array of doubles to a symbol in R (creating as vector of numbers).
equals to calling assign(String, REXP)

Throws:

RSrvException

assign

public void assign(java.lang.String sym,
                   int[] val)
            throws RSrvException

assign values of an array of integers to a symbol in R (creating as vector of numbers).
equals to calling assign(String, REXP)

Throws:

RSrvException

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 RSrvException

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:

RSrvException

shutdown

public void shutdown()
              throws RSrvException

shutdown remote Rserv. Note that some Rserves cannot be shut down from client side (forked version).

Throws:

RSrvException

setSendBufferSize

public void setSendBufferSize(long sbs)
                       throws RSrvException

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:

RSrvException

login

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

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

Parameters:

user - username

pwd - password

Throws:

RSrvException

detach

public RSession detach()
                throws RSrvException

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

Throws:

RSrvException

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