org.rosuda.JRclient
Class Rconnection

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

public class Rconnection

extends Object

class providing TCP/IP connection to an Rserv

Version:

$Id: Rconnection.java,v 1.1 2005/10/05 20:20:16 eytanadar Exp $

Field Summary

static int	AT_crypt authorization type: unix crypt
static int	AT_plain authorization type: plain text
static 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(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, double[] val) assign values of an array of doubles to a symbol in R (creating as vector of numbers). equals to calling assign(String, REXP)
void	assign(String sym, int[] val) assign values of an array of integers to a symbol in R (creating as vector of numbers). equals to calling assign(String, REXP)
void	assign(String sym, REXP r) assign a content of a REXP to a symbol in R.
void	assign(String sym, String ct) assign a string value to a symbol in R.
void	close() closes current connection
RFileOutputStream	createFile(String fn) create a file on the Rserve for writing
REXP	eval(String cmd) evaluates the given command and retrieves the result
void	finalize()
String	getLastError() get last error string
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
RFileInputStream	openFile(String fn) open a file on the Rserve for reading
void	removeFile(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(String cmd) evaluates the given command, but does not fetch the result (useful for assignment operations)

Methods inherited from class java.lang.Object

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

Constructor Detail

Rconnection

public Rconnection()
            throws RSrvException

make a new local connection on default port (6311)

Rconnection

public Rconnection(String host)
            throws RSrvException

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

Parameters:

host - host name/IP

Rconnection

public Rconnection(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

Method Detail

finalize

public void finalize()

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(String cmd)
              throws RSrvException

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

Parameters:

cmd - command/expression string

Returns:

true if successful

Throws:

RSrvException

eval

public REXP eval(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(String sym,
                   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

Returns:

true on success, otherwise false

Throws:

RSrvException

assign

public void assign(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").

Returns:

true on success, otherwise false

Throws:

RSrvException

assign

public void assign(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(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(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 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.

Returns:

true on success, false otherwise

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(String user,
                  String pwd)
           throws RSrvException

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

Parameters:

user - username

pwd - password

Returns:

returns true on success

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 String getLastError()

get last error string

Returns:

last error string