org.rosuda.REngine.Rserve
Class RConnection

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