Class OtpMbox
- java.lang.Object
- 
- com.ericsson.otp.erlang.OtpMbox
 
- 
 public class OtpMbox extends java.lang.ObjectProvides a simple mechanism for exchanging messages with Erlang processes or other instances of this class. Each mailbox is associated with a unique pidthat contains information necessary for delivery of messages. When sending messages to named processes or mailboxes, the sender pid is made available to the recipient of the message. When sending messages to other mailboxes, the recipient can only respond if the sender includes the pid as part of the message contents. The sender can determine his own pid by callingself().Mailboxes can be named, either at creation or later. Messages can be sent to named mailboxes and named Erlang processes without knowing the pidthat identifies the mailbox. This is necessary in order to set up initial communication between parts of an application. Each mailbox can have at most one name.Since this class was intended for communication with Erlang, all of the send methods take OtpErlangObjectarguments. However this class can also be used to transmit arbitrary Java objects (as long as they implement one of java.io.Serializable or java.io.Externalizable) by encapsulating the object in aOtpErlangBinary.Messages to remote nodes are externalized for transmission, and as a result the recipient receives a copy of the original Java object. To ensure consistent behaviour when messages are sent between local mailboxes, such messages are cloned before delivery. Additionally, mailboxes can be linked in much the same way as Erlang processes. If a link is active when a mailbox is closed, any linked Erlang processes or OtpMboxes will be sent an exit signal. As well, exit signals will be (eventually) sent if a mailbox goes out of scope and itsfinalize()method called. However due to the nature of finalization (i.e. Java makes no guarantees about whenfinalize()will be called) it is recommended that you always explicitly close mailboxes if you are using links instead of relying on finalization to notify other parties in a timely manner.When retrieving messages from a mailbox that has received an exit signal, an OtpErlangExitexception will be raised. Note that the exception is queued in the mailbox along with other messages, and will not be raised until it reaches the head of the queue and is about to be retrieved.
- 
- 
Method SummaryAll Methods Instance Methods Concrete Methods Modifier and Type Method Description voidclose()Close this mailbox.booleanequals(java.lang.Object o)Determine if two mailboxes are equal.voidexit(OtpErlangObject reason)Close this mailbox with the given reason.voidexit(OtpErlangPid to, OtpErlangObject reason)Send an exit signal to a remotepid.voidexit(OtpErlangPid to, java.lang.String reason)Equivalent toexit(to, new OtpErlangAtom(reason)).voidexit(java.lang.String reason)Equivalent toexit(new OtpErlangAtom(reason)).protected voidfinalize()java.lang.StringgetName()Get the registered name of this mailbox.java.lang.String[]getNames()Get a list of all known registered names on the samenodeas this mailbox.inthashCode()voidlink(OtpErlangPid to)Link to a remote mailbox or Erlang process.OtpErlangPid[]linked()Get information about all processes and/or mail boxes currently linked to this mail box.booleanping(java.lang.String node, long timeout)Create a connection to a remote node.OtpErlangObjectreceive()Block until a message arrives for this mailbox.OtpErlangObjectreceive(long timeout)Wait for a message to arrive for this mailbox.OtpInputStreamreceiveBuf()Block until a message arrives for this mailbox.OtpInputStreamreceiveBuf(long timeout)Wait for a message to arrive for this mailbox.OtpMsgreceiveMsg()Block until a message arrives for this mailbox.OtpMsgreceiveMsg(long timeout)Wait for a message to arrive for this mailbox.booleanregisterName(java.lang.String aname)Register or remove a name for this mailbox.OtpErlangPidself()Get the identifyingpidassociated with this mailbox.voidsend(OtpErlangPid to, OtpErlangObject msg)voidsend(java.lang.String aname, OtpErlangObject msg)Send a message to a named mailbox created from the same node as this mailbox.voidsend(java.lang.String aname, java.lang.String node, OtpErlangObject msg)Send a message to a named mailbox created from another node.voidunlink(OtpErlangPid to)Remove a link to a remote mailbox or Erlang process.OtpErlangPidwhereis(java.lang.String aname)
 
- 
- 
- 
Method Detail- 
selfpublic OtpErlangPid self() Get the identifying pidassociated with this mailbox.The pidassociated with this mailbox uniquely identifies the mailbox and can be used to address the mailbox. You can send thepidto a remote communicating part so that he can know where to send his response.- Returns:
- the self pid for this mailbox.
 
 - 
registerNamepublic boolean registerName(java.lang.String aname) Register or remove a name for this mailbox. Registering a name for a mailbox enables others to send messages without knowing the pidof the mailbox. A mailbox can have at most one name; if the mailbox already had a name, calling this method will supersede that name.- Parameters:
- aname- the name to register for the mailbox. Specify null to unregister the existing name from this mailbox.
- Returns:
- true if the name was available, or false otherwise.
 
 - 
getNamepublic java.lang.String getName() Get the registered name of this mailbox.- Returns:
- the registered name of this mailbox, or null if the mailbox had no registered name.
 
 - 
receivepublic OtpErlangObject receive() throws OtpErlangExit, OtpErlangDecodeException Block until a message arrives for this mailbox.- Returns:
- an OtpErlangObjectrepresenting the body of the next message waiting in this mailbox.
- Throws:
- OtpErlangDecodeException- if the message cannot be decoded.
- OtpErlangExit- if a linked- pidhas exited or has sent an exit signal to this mailbox.
 
 - 
receivepublic OtpErlangObject receive(long timeout) throws OtpErlangExit, OtpErlangDecodeException Wait for a message to arrive for this mailbox.- Parameters:
- timeout- the time, in milliseconds, to wait for a message before returning null.
- Returns:
- an OtpErlangObjectrepresenting the body of the next message waiting in this mailbox.
- Throws:
- OtpErlangDecodeException- if the message cannot be decoded.
- OtpErlangExit- if a linked- pidhas exited or has sent an exit signal to this mailbox.
 
 - 
receiveBufpublic OtpInputStream receiveBuf() throws OtpErlangExit Block until a message arrives for this mailbox.- Returns:
- a byte array representing the still-encoded body of the next message waiting in this mailbox.
- Throws:
- OtpErlangExit- if a linked- pidhas exited or has sent an exit signal to this mailbox.
 
 - 
receiveBufpublic OtpInputStream receiveBuf(long timeout) throws java.lang.InterruptedException, OtpErlangExit Wait for a message to arrive for this mailbox.- Parameters:
- timeout- the time, in milliseconds, to wait for a message before returning null.
- Returns:
- a byte array representing the still-encoded body of the next message waiting in this mailbox.
- Throws:
- OtpErlangExit- if a linked- pidhas exited or has sent an exit signal to this mailbox.
- java.lang.InterruptedException- if no message if the method times out before a message becomes available.
 
 - 
receiveMsgpublic OtpMsg receiveMsg() throws OtpErlangExit Block until a message arrives for this mailbox.- Returns:
- an OtpMsgcontaining the header information as well as the body of the next message waiting in this mailbox.
- Throws:
- OtpErlangExit- if a linked- pidhas exited or has sent an exit signal to this mailbox.
 
 - 
receiveMsgpublic OtpMsg receiveMsg(long timeout) throws java.lang.InterruptedException, OtpErlangExit Wait for a message to arrive for this mailbox.- Parameters:
- timeout- the time, in milliseconds, to wait for a message.
- Returns:
- an OtpMsgcontaining the header information as well as the body of the next message waiting in this mailbox.
- Throws:
- OtpErlangExit- if a linked- pidhas exited or has sent an exit signal to this mailbox.
- java.lang.InterruptedException- if no message if the method times out before a message becomes available.
 
 - 
sendpublic void send(OtpErlangPid to, OtpErlangObject msg) - Parameters:
- to- the- pididentifying the intended recipient of the message.
- msg- the body of the message to send.
 
 - 
sendpublic void send(java.lang.String aname, OtpErlangObject msg)Send a message to a named mailbox created from the same node as this mailbox.- Parameters:
- aname- the registered name of recipient mailbox.
- msg- the body of the message to send.
 
 - 
sendpublic void send(java.lang.String aname, java.lang.String node, OtpErlangObject msg)Send a message to a named mailbox created from another node.- Parameters:
- aname- the registered name of recipient mailbox.
- node- the name of the remote node where the recipient mailbox is registered.
- msg- the body of the message to send.
 
 - 
exitpublic void exit(OtpErlangObject reason) Close this mailbox with the given reason.After this operation, the mailbox will no longer be able to receive messages. Any delivered but as yet unretrieved messages can still be retrieved however. If there are links from this mailbox to other pids, they will be broken when this method is called and exit signals will be sent.- Parameters:
- reason- an Erlang term describing the reason for the exit.
 
 - 
exitpublic void exit(java.lang.String reason) Equivalent toexit(new OtpErlangAtom(reason)).- See Also:
- exit(OtpErlangObject)
 
 - 
exitpublic void exit(OtpErlangPid to, OtpErlangObject reason) Send an exit signal to a remote pid. This method does not cause any links to be broken, except indirectly if the remotepidexits as a result of this exit signal.- Parameters:
- to- the- pidto which the exit signal should be sent.
- reason- an Erlang term indicating the reason for the exit.
 
 - 
exitpublic void exit(OtpErlangPid to, java.lang.String reason) Equivalent to exit(to, new OtpErlangAtom(reason)).- See Also:
- exit(OtpErlangPid, OtpErlangObject)
 
 - 
linkpublic void link(OtpErlangPid to) throws OtpErlangExit Link to a remote mailbox or Erlang process. Links are idempotent, calling this method multiple times will not result in more than one link being created. If the remote process subsequently exits or the mailbox is closed, a subsequent attempt to retrieve a message through this mailbox will cause an OtpErlangExitexception to be raised. Similarly, if the sending mailbox is closed, the linked mailbox or process will receive an exit signal.If the remote process cannot be reached in order to set the link, the exception is raised immediately. - Parameters:
- to- the- pidrepresenting the object to link to.
- Throws:
- OtpErlangExit- if the- pidreferred to does not exist or could not be reached.
 
 - 
unlinkpublic void unlink(OtpErlangPid to) Remove a link to a remote mailbox or Erlang process. This method removes a link created with link(). Links are idempotent; calling this method once will remove all links between this mailbox and the remotepid.- Parameters:
- to- the- pidrepresenting the object to unlink from.
 
 - 
linkedpublic OtpErlangPid[] linked() Get information about all processes and/or mail boxes currently linked to this mail box. - Returns:
- an array of all pids currently linked to this mail box.
 
 - 
pingpublic boolean ping(java.lang.String node, long timeout)Create a connection to a remote node. Strictly speaking, this method is not necessary simply to set up a connection, since connections are created automatically first time a message is sent to a pidon the remote node.This method makes it possible to wait for a node to come up, however, or check that a node is still alive. This method calls a method with the same name in Otpnodebut is provided here for convenience.- Parameters:
- node- the name of the node to ping.
- timeout- the time, in milliseconds, before reporting failure.
 
 - 
getNamespublic java.lang.String[] getNames() Get a list of all known registered names on the same nodeas this mailbox.This method calls a method with the same name in Otpnodebut is provided here for convenience.- Returns:
- an array of Strings containing all registered names on this
         node.
 
 - 
whereispublic OtpErlangPid whereis(java.lang.String aname) Determine thepidcorresponding to a registered name on thisnode.This method calls a method with the same name in Otpnodebut is provided here for convenience.- Returns:
- the pidcorresponding to the registered name, or null if the name is not known on this node.
 
 - 
closepublic void close() Close this mailbox.After this operation, the mailbox will no longer be able to receive messages. Any delivered but as yet unretrieved messages can still be retrieved however. If there are links from this mailbox to other pids, they will be broken when this method is called and exit signals with reason 'normal' will be sent.This is equivalent to exit("normal").
 - 
finalizeprotected void finalize() - Overrides:
- finalizein class- java.lang.Object
 
 - 
equalspublic boolean equals(java.lang.Object o) Determine if two mailboxes are equal.- Overrides:
- equalsin class- java.lang.Object
- Returns:
- true if both Objects are mailboxes with the same identifying
         pids.
 
 - 
hashCodepublic int hashCode() - Overrides:
- hashCodein class- java.lang.Object
 
 
- 
 
-