OtpConnection (Java-Erlang Interface Library)

Package com.ericsson.otp.erlang

## Class OtpConnection

- java.lang.Object
- - java.lang.Thread
  - - com.ericsson.otp.erlang.AbstractConnection
    - - com.ericsson.otp.erlang.OtpConnection

- All Implemented Interfaces:
    `java.lang.Runnable`

      public class OtpConnection
      extends AbstractConnection

  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 and make rpc calls (assuming that the remote node is a real Erlang node).

  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 explicitly reopened in order to resume communication with the peer.

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

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class java.lang.Thread

      `java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected com.ericsson.otp.erlang.Links` | `links` |
    `protected GenericQueue` | `queue` |
    `protected OtpSelf` | `self` |

    - ### Fields inherited from class com.ericsson.otp.erlang.AbstractConnection

      `ChallengeAck, ChallengeReply, ChallengeStatus, connected, cookieOk, ctrlThreshold, defaultLevel, exit2Tag, exit2TTTag, exitTag, exitTTTag, groupLeaderTag, handshakeThreshold, headerLen, linkTag, localNode, passThrough, peer, random, regSendTag, regSendTTTag, sendCookie, sendTag, sendThreshold, sendTTTag, socket, traceLevel, unlinkIdAckTag, unlinkIdTag, unlinkTag, version`

    - ### Fields inherited from class java.lang.Thread

      `MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `deliver​(OtpMsg msg)` | Deliver messages to the recipient.
    `void` | `deliver​(java.lang.Exception e)` | Deliver communication exceptions to the recipient.
    `void` | `exit​(OtpErlangPid dest, OtpErlangObject reason)` | Send an exit signal to a remote process.
    `void` | `link​(OtpErlangPid dest)` | Create a link between the local node and the specified process on the remote node.
    `int` | `msgCount()` | Return the number of messages currently waiting in the receive queue for this connection.
    `OtpPeer` | `peer()` | Get information about the node at the peer end of this connection.
    `OtpErlangObject` | `receive()` | Receive a message from a remote process.
    `OtpErlangObject` | `receive​(long timeout)` | Receive a message from a remote process.
    `OtpInputStream` | `receiveBuf()` | Receive a raw (still encoded) message from a remote process.
    `OtpInputStream` | `receiveBuf​(long timeout)` | Receive a raw (still encoded) message from a remote process.
    `OtpMsg` | `receiveMsg()` | Receive a message complete with sender and recipient information.
    `OtpMsg` | `receiveMsg​(long timeout)` | Receive a message complete with sender and recipient information.
    `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 com.ericsson.otp.erlang.AbstractConnection

      `close, do_send, do_send, doAccept, doConnect, doGenericConnect, doPortConnect, finalize, genChallenge, genDigest, getFlags, getTraceLevel, headerType, isConnected, read2BytePackage, readSock, recvChallenge, recvChallengeAck, recvChallengeReply, recvComplement, recvName, recvStatus, run, sendBuf, sendBuf, sendChallenge, sendChallengeAck, sendChallengeReply, sendExit, sendExit2, sendLink, sendName, sendStatus, sendUnlink, sendUnlinkAck, setFlags, setTraceLevel`

    - ### Methods inherited from class java.lang.Thread

      `activeCount, checkAccess, clone, countStackFrames, currentThread, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, suspend, toString, yield`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### self

          protected OtpSelf self

    - #### queue

          protected GenericQueue queue

    - #### links

          protected com.ericsson.otp.erlang.Links links

  - ### Method Detail

    - #### deliver

          public void deliver​(java.lang.Exception e)

      Description copied from class: `AbstractConnection`
      Deliver communication exceptions to the recipient.
      Specified by:
        `deliver` in class `AbstractConnection`

    - #### deliver

          public void deliver​(OtpMsg msg)

      Description copied from class: `AbstractConnection`
      Deliver messages to the recipient.
      Specified by:
        `deliver` in class `AbstractConnection`

    - #### peer

          public OtpPeer peer()

      Get information about the node at the peer end of this connection.
      Returns:
        the `Node` representing the peer node.

    - #### self

          public OtpSelf self()

      Get information about the node at the local end of this connection.
      Returns:
        the `Node` representing the local node.

    - #### msgCount

          public int msgCount()

      Return the number of messages currently waiting in the receive queue for this connection.

    - #### 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.

    - #### receive

          public OtpErlangObject receive​(long timeout)
                                  throws java.lang.InterruptedException,
                                         java.io.IOException,
                                         OtpErlangExit,
                                         OtpAuthException

      Receive a message from a remote process. This method blocks at most for the specified time, 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.

      Parameters:
        `timeout` - the time in milliseconds that this operation will block. Specify 0 to poll the queue.
      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.
        `java.lang.InterruptedException` - if no message if the method times out before a message becomes available.

    - #### 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, or if the connection is lost for any reason.
        `OtpAuthException` - if the remote node sends a message containing an invalid cookie.

    - #### receiveBuf

          public OtpInputStream receiveBuf​(long timeout)
                                    throws java.lang.InterruptedException,
                                           java.io.IOException,
                                           OtpErlangExit,
                                           OtpAuthException

      Receive a raw (still encoded) message from a remote process. This message blocks at most for the specified time 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.

      Parameters:
        `timeout` - the time in milliseconds that this operation will block. Specify 0 to poll the queue.
      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, or if the connection is lost for any reason.
        `OtpAuthException` - if the remote node sends a message containing an invalid cookie.
        `java.lang.InterruptedException` - if no message if the method times out before a message becomes available.

    - #### receiveMsg

          public OtpMsg receiveMsg()
                            throws java.io.IOException,
                                   OtpErlangExit,
                                   OtpAuthException

      Receive a message complete with sender and recipient information.
      Returns:
        an `OtpMsg` containing the header information about the sender and recipient, as well as the actual message contents.
      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, or if the connection is lost for any reason.
        `OtpAuthException` - if the remote node sends a message containing an invalid cookie.

    - #### receiveMsg

          public OtpMsg receiveMsg​(long timeout)
                            throws java.lang.InterruptedException,
                                   java.io.IOException,
                                   OtpErlangExit,
                                   OtpAuthException

      Receive a message complete with sender and recipient information. This method blocks at most for the specified time.
      Parameters:
        `timeout` - the time in milliseconds that this operation will block. Specify 0 to poll the queue.
      Returns:
        an `OtpMsg` containing the header information about the sender and recipient, as well as the actual message contents.
      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, or if the connection is lost for any reason.
        `OtpAuthException` - if the remote node sends a message containing an invalid cookie.
        `java.lang.InterruptedException` - if no message if the method times out before a message becomes available.

    - #### send

          public void send​(OtpErlangPid dest,
                           OtpErlangObject msg)
                    throws java.io.IOException

      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.

    - #### send

          public void send​(java.lang.String dest,
                           OtpErlangObject msg)
                    throws java.io.IOException

      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.

    - #### sendBuf

          public void sendBuf​(java.lang.String dest,
                              OtpOutputStream payload)
                       throws java.io.IOException

      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.

    - #### sendBuf

          public void sendBuf​(OtpErlangPid dest,
                              OtpOutputStream payload)
                       throws java.io.IOException

      Send a pre-encoded message to a process on a remote node.
      Parameters:
        `dest` - the Erlang PID 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.

    - #### sendRPC

          public void sendRPC​(java.lang.String mod,
                              java.lang.String fun,
                              OtpErlangObject[] args)
                       throws java.io.IOException

      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 } }

      Note that this method has unpredicatble results if the remote node is not an Erlang node.

      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.

    - #### sendRPC

          public void sendRPC​(java.lang.String mod,
                              java.lang.String fun,
                              OtpErlangList args)
                       throws java.io.IOException

      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 } }

      Note that this method has unpredicatble results if the remote node is not an Erlang node.

      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.

    - #### 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

      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.

    - #### unlink

          public void unlink​(OtpErlangPid dest)
                      throws java.io.IOException

      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.

    - #### exit

          public void exit​(OtpErlangPid dest,
                           OtpErlangObject reason)
                    throws java.io.IOException

      Send an exit signal to a remote process.
      Parameters:
        `dest` - the Erlang PID of the remote process.
        `reason` - an Erlang term describing the exit reason.
      Throws:
        `java.io.IOException` - if the connection is not active or a communication error occurs.