com.ericsson.otp.erlang
Class OtpConnection

java.lang.Object
  |
  +--com.ericsson.otp.erlang.OtpConnection

public class OtpConnection
extends java.lang.Object

Maintains a connection between a Java process and a remote Erlang, Java or C node. The object maintains connection state and allows data to be sent to and received from the peer.

Once a connection is established between the local node and a remote node, the connection object can be used to send and receive messages between the nodes.

The various receive methods are all blocking and will return only when a valid message has been received or an exception is raised.

If an exception occurs in any of the methods in this class, the connection will be closed and must be reopened in order to resume communication with the peer.

If the remote node is an Erlang node, it is important to not let the connection fall idle for more than a few seconds at a time. Erlang monitors connection activity and when no messages have been sent for a short time (normally 15 seconds), it sends a 'tick' message to which it expects a response within a short time. If the response does not arrive in time, the node is assumed to have died and the connection will be closed by Erlang. In order to prevent this, make sure that one of the receive methods is called on a regular basis. These methods will automatically respond to 'tick' messages, returning only when a proper Erlang message has been received.

For this reason, if you are doing other work while connected to an Erlang node or have long message processing times, it is advisable to let a separate Thread continuously maintain the connection.

It is not possible to create an instance of this class directly. OtpConnection objects are returned by OtpSelf.connect() and OtpServer.accept().

Communication can be traced by setting the Java property OtpConnection.trace to some non-zero value before the class is loaded. Setting 0 turns off tracing, and more information is shown at each level up to 3. Currrently it is not possible to trace individual connections, as the trace level is set only once when the class is loaded, and affects all connections.


Method Summary
 void close()
          Close the connection to the remote node.
 void exit(OtpErlangPid dest, java.lang.String reason)
          Send an exit signal to a remote process.
 boolean isConnected()
          Determine if the connection is still alive.
 void link(OtpErlangPid dest)
          Create a link between the local node and the specified process on the remote node.
 OtpPeer peer()
          Get information about the node at the peer end of this connection.
 OtpErlangObject receive()
          Receive a message from a remote process.
 OtpInputStream receiveBuf()
          Receive a raw (still encoded) message from a remote process.
 OtpErlangObject receiveRPC()
          Receive an RPC reply from the remote Erlang node.
 OtpSelf self()
          Get information about the node at the local end of this connection.
 void send(OtpErlangPid dest, OtpErlangObject msg)
          Send a message to a process on a remote node.
 void send(java.lang.String dest, OtpErlangObject msg)
          Send a message to a named process on a remote node.
 void sendBuf(OtpErlangPid dest, OtpOutputStream payload)
          Send a pre-encoded message to a process on a remote node.
 void sendBuf(java.lang.String dest, OtpOutputStream payload)
          Send a pre-encoded message to a named process on a remote node.
 void sendRPC(java.lang.String mod, java.lang.String fun, OtpErlangList args)
          Send an RPC request to the remote Erlang node.
 void sendRPC(java.lang.String mod, java.lang.String fun, OtpErlangObject[] args)
          Send an RPC request to the remote Erlang node.
 void unlink(OtpErlangPid dest)
          Remove a link between the local node and the specified process on the remote node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

send

public void send(java.lang.String dest,
                 OtpErlangObject msg)
          throws java.io.IOException,
                 OtpErlangDataException
Send a message to a named process on a remote node.
Parameters:
dest - the name of the remote process.
msg - the message to send.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the message.

sendBuf

public void sendBuf(java.lang.String dest,
                    OtpOutputStream payload)
             throws java.io.IOException,
                    OtpErlangDataException
Send a pre-encoded message to a named process on a remote node.
Parameters:
dest - the name of the remote process.
payload - the encoded message to send.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the message.

send

public void send(OtpErlangPid dest,
                 OtpErlangObject msg)
          throws java.io.IOException,
                 OtpErlangDataException
Send a message to a process on a remote node.
Parameters:
dest - the Erlang PID of the remote process.
msg - the message to send.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the message.

sendBuf

public void sendBuf(OtpErlangPid dest,
                    OtpOutputStream payload)
             throws java.io.IOException,
                    OtpErlangDataException
Send a pre-encoded message to a process on a remote node.
Parameters:
dest - the Erlang PID of the remote process.
msg - the encoded message to send.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the message.

sendRPC

public void sendRPC(java.lang.String mod,
                    java.lang.String fun,
                    OtpErlangObject[] args)
             throws java.io.IOException,
                    OtpErlangDataException
Send an RPC request to the remote Erlang node. This convenience function creates the following message and sends it to 'rex' on the remote node:
 { self, { call, Mod, Fun, Args, user }}
 
Parameters:
mod - the name of the Erlang module containing the function to be called.
fun - the name of the function to call.
args - an array of Erlang terms, to be used as arguments to the function.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the message.

sendRPC

public void sendRPC(java.lang.String mod,
                    java.lang.String fun,
                    OtpErlangList args)
             throws java.io.IOException,
                    OtpErlangDataException
Send an RPC request to the remote Erlang node. This convenience function creates the following message and sends it to 'rex' on the remote node:
 { self, { call, Mod, Fun, Args, user }}
 
Parameters:
mod - the name of the Erlang module containing the function to be called.
fun - the name of the function to call.
args - a list of Erlang terms, to be used as arguments to the function.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the message.

receiveRPC

public OtpErlangObject receiveRPC()
                           throws java.io.IOException,
                                  OtpErlangExit,
                                  OtpAuthException
Receive an RPC reply from the remote Erlang node. This convenience function receives a message from the remote node, and expects it to have the following format:
 {rex, Term}
 
Returns:
the second element of the tuple if the received message is a two-tuple, otherwise null. No further error checking is performed.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangExit - if an exit signal is received from a process on the peer node.
OtpAuthException - if the remote node sends a message containing an invalid cookie.

link

public void link(OtpErlangPid dest)
          throws java.io.IOException,
                 OtpErlangDataException
Create a link between the local node and the specified process on the remote node. If the link is still active when the remote process terminates, an exit signal will be sent to this connection. Use unlink() to remove the link.
Parameters:
dest - the Erlang PID of the remote process.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the link message.

unlink

public void unlink(OtpErlangPid dest)
            throws java.io.IOException,
                   OtpErlangDataException
Remove a link between the local node and the specified process on the remote node. This method deactivates links created with link().
Parameters:
dest - the Erlang PID of the remote process.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the unlink message.

exit

public void exit(OtpErlangPid dest,
                 java.lang.String reason)
          throws java.io.IOException,
                 OtpErlangDataException
Send an exit signal to a remote process.
Parameters:
dest - the Erlang PID of the remote process.
reason - a string describing the exit reason.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangDataException - if there are errors encoding the exit message.

receive

public OtpErlangObject receive()
                        throws java.io.IOException,
                               OtpErlangExit,
                               OtpAuthException
Receive a message from a remote process. This method blocks until a valid message is received or an exception is raised.

If the remote node sends a message that cannot be decoded properly, the connection is closed and the method throws an exception.

Returns:
an object containing a single Erlang term.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangExit - if an exit signal is received from a process on the peer node.
OtpAuthException - if the remote node sends a message containing an invalid cookie.

receiveBuf

public OtpInputStream receiveBuf()
                          throws java.io.IOException,
                                 OtpErlangExit,
                                 OtpAuthException
Receive a raw (still encoded) message from a remote process. This message blocks until a valid message is received or an exception is raised.

If the remote node sends a message that cannot be decoded properly, the connection is closed and the method throws an exception.

Returns:
an object containing a raw (still encoded) Erlang term.
Throws:
java.io.IOException - if the connection is not active or a communication error occurs.
OtpErlangExit - if an exit signal is received from a process on the peer node.
OtpAuthException - if the remote node sends a message containing an invalid cookie.

close

public void close()
Close the connection to the remote node.

isConnected

public boolean isConnected()
Determine if the connection is still alive.
Returns:
true if the connection is alive.

peer

public OtpPeer peer()
Get information about the node at the peer end of this connection.
Returns:
the OtpNode representing the peer node.

self

public OtpSelf self()
Get information about the node at the local end of this connection.
Returns:
the OtpNode representing the local node.