OtpMsg (Java-Erlang Interface Library)

Package com.ericsson.otp.erlang

## Class OtpMsg

- java.lang.Object
- - com.ericsson.otp.erlang.OtpMsg

-     public class OtpMsg
      extends java.lang.Object

  Provides a carrier for Erlang messages.

  Instances of this class are created to package header and payload information in received Erlang messages so that the recipient can obtain both parts with a single call to `receiveMsg()`.

  The header information that is available is as follows:

  - a tag indicating the type of message
  - the intended recipient of the message, either as a `pid` or as a String, but never both.
  - (sometimes) the sender of the message. Due to some eccentric characteristics of the Erlang distribution protocol, not all messages have information about the sending process. In particular, only messages whose tag is `regSendTag` contain sender information.

  Message are sent using the Erlang external format (see separate documentation). When a message is received and delivered to the recipient `mailbox`, the body of the message is still in this external representation until `getMsg()` is called, at which point the message is decoded. A copy of the decoded message is stored in the OtpMsg so that subsequent calls to `getMsg()` do not require that the message be decoded a second time.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `exit2Tag` |
    `static int` | `exitTag` |
    `protected OtpErlangPid` | `from` |
    `static int` | `linkTag` |
    `protected OtpInputStream` | `paybuf` |
    `protected OtpErlangObject` | `payload` |
    `static int` | `regSendTag` |
    `static int` | `sendTag` |
    `protected int` | `tag` |
    `protected OtpErlangPid` | `to` |
    `protected java.lang.String` | `toName` |
    `protected long` | `unlink_id` |
    `static int` | `unlinkTag` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `OtpErlangObject` | `getMsg()` | Deserialize and return a new copy of the message contained in this OtpMsg.
    `java.lang.Object` | `getRecipient()` | Get the name of the recipient for this message, if it is a regSendTag message.
    `java.lang.String` | `getRecipientName()` | Get the name of the recipient for this message.
    `OtpErlangPid` | `getRecipientPid()` | Get the Pid of the recipient for this message, if it is a sendTag message.
    `OtpErlangPid` | `getSenderPid()` | Get the Pid of the sender of this message.
    `int` | `type()` | Get the type marker from this message.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### linkTag

          public static final int linkTag

      See Also:
        Constant Field Values

    - #### sendTag

          public static final int sendTag

      See Also:
        Constant Field Values

    - #### exitTag

          public static final int exitTag

      See Also:
        Constant Field Values

    - #### unlinkTag

          public static final int unlinkTag

      See Also:
        Constant Field Values

    - #### regSendTag

          public static final int regSendTag

      See Also:
        Constant Field Values

    - #### exit2Tag

          public static final int exit2Tag

      See Also:
        Constant Field Values

    - #### tag

          protected int tag

    - #### paybuf

          protected OtpInputStream paybuf

    - #### payload

          protected OtpErlangObject payload

    - #### from

          protected OtpErlangPid from

    - #### to

          protected OtpErlangPid to

    - #### toName

          protected java.lang.String toName

    - #### unlink_id

          protected long unlink_id

  - ### Method Detail

    - #### type

          public int type()

      Get the type marker from this message. The type marker identifies the type of message. Valid values are the ``tag'' constants defined in this class.

      The tab identifies not only the type of message but also the content of the OtpMsg object, since different messages have different components, as follows:

      - sendTag identifies a "normal" message. The recipient is a `Pid` and it is available through `getRecipientPid()`. Sender information is not available. The message body can be retrieved with `getMsg()`.
      - regSendTag also identifies a "normal" message. The recipient here is a String and it is available through `getRecipientName()`. Sender information is available through #getSenderPid getSenderPid()}. The message body can be retrieved with `getMsg()`.
      - linkTag identifies a link request. The Pid of the sender is available, as well as the Pid to which the link should be made.
      - exitTag and exit2Tag messages are sent as a result of broken links. Both sender and recipient Pids and are available through the corresponding methods, and the "reason" is available through `getMsg()`.

    - #### getMsg

          public OtpErlangObject getMsg()
                                 throws OtpErlangDecodeException

      Deserialize and return a new copy of the message contained in this OtpMsg.

      The first time this method is called the actual payload is deserialized and the Erlang term is created. Calling this method subsequent times will not cause the message to be deserialized additional times, instead the same Erlang term object will be returned.

      Returns:
        an Erlang term.
      Throws:
        `OtpErlangDecodeException` - if the byte stream could not be deserialized.

    - #### getRecipientName

          public java.lang.String getRecipientName()

      Get the name of the recipient for this message.

      Messages are sent to Pids or names. If this message was sent to a name then the name is returned by this method.

      Returns:
        the name of the recipient, or null if the recipient was in fact a Pid.

    - #### getRecipientPid

          public OtpErlangPid getRecipientPid()

      Get the Pid of the recipient for this message, if it is a sendTag message.

      Messages are sent to Pids or names. If this message was sent to a Pid then the Pid is returned by this method. The recipient Pid is also available for link, unlink and exit messages.

      Returns:
        the Pid of the recipient, or null if the recipient was in fact a name.

    - #### getRecipient

          public java.lang.Object getRecipient()

      Get the name of the recipient for this message, if it is a regSendTag message.

      Messages are sent to Pids or names. If this message was sent to a name then the name is returned by this method.

      Returns:
        the Pid of the recipient, or null if the recipient was in fact a name.

    - #### getSenderPid

          public OtpErlangPid getSenderPid()

      Get the Pid of the sender of this message.

      For messages sent to names, the Pid of the sender is included with the message. The sender Pid is also available for link, unlink and exit messages. It is not available for sendTag messages sent to Pids.

      Returns:
        the Pid of the sender, or null if it was not available.