org.rosuda.JRclient
Class Rconnection

java.lang.Object
  extended by 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