| 
 | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectcom.ericsson.otp.erlang.OtpMbox
public class OtpMbox
Provides a simple mechanism for exchanging messages with Erlang processes or other instances of this class.
 Each mailbox is associated with a unique pid that
 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 calling
 self().
 
 Mailboxes can be named, either at creation or later. Messages can be sent to
 named mailboxes and named Erlang processes without knowing the
 pid that identifies the mailbox. This is neccessary 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 OtpErlangObject arguments. 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 a OtpErlangBinary.
 
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 its
 finalize() method called. However due to the nature of
 finalization (i.e. Java makes no guarantees about when finalize() 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
 OtpErlangExit exception 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 Summary | |
|---|---|
|  void | close()Close this mailbox. | 
|  boolean | equals(java.lang.Object o)Determine if two mailboxes are equal. | 
|  void | exit(OtpErlangObject reason)Close this mailbox with the given reason. | 
|  void | exit(OtpErlangPid to,
     OtpErlangObject reason)Send an exit signal to a remote pid. | 
|  void | exit(OtpErlangPid to,
     java.lang.String reason)Equivalent to exit(to, new
 OtpErlangAtom(reason)). | 
|  void | exit(java.lang.String reason)Equivalent to exit(new OtpErlangAtom(reason)). | 
| protected  void | finalize() | 
|  java.lang.String | getName()Get the registered name of this mailbox. | 
|  java.lang.String[] | getNames()Get a list of all known registered names on the same nodeas this mailbox. | 
|  int | hashCode() | 
|  void | link(OtpErlangPid to)Link to a remote mailbox or Erlang process. | 
|  boolean | ping(java.lang.String node,
     long timeout)Create a connection to a remote node. | 
|  OtpErlangObject | receive()Block until a message arrives for this mailbox. | 
|  OtpErlangObject | receive(long timeout)Wait for a message to arrive for this mailbox. | 
|  OtpInputStream | receiveBuf()Block until a message arrives for this mailbox. | 
|  OtpInputStream | receiveBuf(long timeout)Wait for a message to arrive for this mailbox. | 
|  OtpMsg | receiveMsg()Block until a message arrives for this mailbox. | 
|  OtpMsg | receiveMsg(long timeout)Wait for a message to arrive for this mailbox. | 
|  boolean | registerName(java.lang.String aname)Register or remove a name for this mailbox. | 
|  OtpErlangPid | self()Get the identifying pidassociated with this
 mailbox. | 
|  void | send(OtpErlangPid to,
     OtpErlangObject msg)Send a message to a remote pid, representing either
 anothermailboxor an Erlang process. | 
|  void | send(java.lang.String aname,
     OtpErlangObject msg)Send a message to a named mailbox created from the same node as this mailbox. | 
|  void | send(java.lang.String aname,
     java.lang.String node,
     OtpErlangObject msg)Send a message to a named mailbox created from another node. | 
|  void | unlink(OtpErlangPid to)Remove a link to a remote mailbox or Erlang process. | 
|  OtpErlangPid | whereis(java.lang.String aname)Determine the pidcorresponding to a registered name
 on thisnode. | 
| Methods inherited from class java.lang.Object | 
|---|
| clone, getClass, notify, notifyAll, toString, wait, wait, wait | 
| Method Detail | 
|---|
public OtpErlangPid self()
 Get the identifying pid associated with this
 mailbox.
 
 The pid associated with this mailbox uniquely
 identifies the mailbox and can be used to address the mailbox. You can
 send the pid to a remote communicating part so that
 he can know where to send his response.
 
public 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
 pid of the mailbox. A mailbox can have at most one
 name; if the mailbox already had a name, calling this method will
 supercede that name.
 
aname - the name to register for the mailbox. Specify null to
            unregister the existing name from this mailbox.
public java.lang.String getName()
public OtpErlangObject receive()
                        throws OtpErlangExit,
                               OtpErlangDecodeException
OtpErlangObject representing the body
         of the next message waiting in this mailbox.
OtpErlangDecodeException - if the message can not be decoded.
OtpErlangExit - if a linked pid has exited or has
                sent an exit signal to this mailbox.
public OtpErlangObject receive(long timeout)
                        throws OtpErlangExit,
                               OtpErlangDecodeException
timeout - the time, in milliseconds, to wait for a message before
            returning null.
OtpErlangObject representing the body
         of the next message waiting in this mailbox.
OtpErlangDecodeException - if the message can not be decoded.
OtpErlangExit - if a linked pid has exited or has
                sent an exit signal to this mailbox.
public OtpInputStream receiveBuf()
                          throws OtpErlangExit
OtpErlangExit - if a linked pid has exited or has
                sent an exit signal to this mailbox.
public OtpInputStream receiveBuf(long timeout)
                          throws java.lang.InterruptedException,
                                 OtpErlangExit
timeout - the time, in milliseconds, to wait for a message before
            returning null.
OtpErlangExit - if a linked pid has 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.
public OtpMsg receiveMsg()
                  throws OtpErlangExit
OtpMsg containing the header information as
         well as the body of the next message waiting in this mailbox.
OtpErlangExit - if a linked pid has exited or has
                sent an exit signal to this mailbox.
public OtpMsg receiveMsg(long timeout)
                  throws java.lang.InterruptedException,
                         OtpErlangExit
timeout - the time, in milliseconds, to wait for a message.
OtpMsg containing the header information as
         well as the body of the next message waiting in this mailbox.
OtpErlangExit - if a linked pid has 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.
public void send(OtpErlangPid to,
                 OtpErlangObject msg)
pid, representing either
 another mailbox or an Erlang process.
to - the pid identifying the intended
            recipient of the message.msg - the body of the message to send.
public void send(java.lang.String aname,
                 OtpErlangObject msg)
aname - the registered name of recipient mailbox.msg - the body of the message to send.
public void send(java.lang.String aname,
                 java.lang.String node,
                 OtpErlangObject msg)
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.public void exit(OtpErlangObject 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.
 
reason - an Erlang term describing the reason for the exit.public void exit(java.lang.String reason)
exit(new OtpErlangAtom(reason)).
exit(OtpErlangObject)
public 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 remote
 pid exits as a result of this exit signal.
 
to - the pid to which the exit signal should
            be sent.reason - an Erlang term indicating the reason for the exit.
public void exit(OtpErlangPid to,
                 java.lang.String reason)
 Equivalent to exit(to, new
 OtpErlangAtom(reason)).
 
exit(OtpErlangPid, OtpErlangObject)
public 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 OtpErlangExit exception 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.
to - the pid representing the object to link
            to.
OtpErlangExit - if the pid referred to does not exist
                or could not be reached.public 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
 remote pid.
 
to - the pid representing the object to unlink
            from.
public 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 pid on 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 Otpnode but is provided here for convenience.
 
node - the name of the node to ping.timeout - the time, in milliseconds, before reporting failure.public java.lang.String[] getNames()
 Get a list of all known registered names on the same node
 as this mailbox.
 
 This method calls a method with the same name in Otpnode but is provided here for convenience.
 
node.public OtpErlangPid whereis(java.lang.String aname)
pid corresponding to a registered name
 on this node.
 
 This method calls a method with the same name in Otpnode but is provided here for convenience.
 
pid corresponding to the registered
         name, or null if the name is not known on this node.public void close()
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").
 
protected void finalize()
finalize in class java.lang.Objectpublic boolean equals(java.lang.Object o)
equals in class java.lang.Objectpids.public int hashCode()
hashCode in class java.lang.Object| 
 | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||