diff options
author | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
---|---|---|
committer | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
commit | 84adefa331c4159d432d22840663c38f155cd4c1 (patch) | |
tree | bff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/jinterface/java_src/com/ericsson/otp/erlang/OtpMsg.java | |
download | otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2 otp-84adefa331c4159d432d22840663c38f155cd4c1.zip |
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/jinterface/java_src/com/ericsson/otp/erlang/OtpMsg.java')
-rw-r--r-- | lib/jinterface/java_src/com/ericsson/otp/erlang/OtpMsg.java | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/lib/jinterface/java_src/com/ericsson/otp/erlang/OtpMsg.java b/lib/jinterface/java_src/com/ericsson/otp/erlang/OtpMsg.java new file mode 100644 index 0000000000..80d8a5ccae --- /dev/null +++ b/lib/jinterface/java_src/com/ericsson/otp/erlang/OtpMsg.java @@ -0,0 +1,291 @@ +/* + * %CopyrightBegin% + * + * Copyright Ericsson AB 2000-2009. All Rights Reserved. + * + * The contents of this file are subject to the Erlang Public License, + * Version 1.1, (the "License"); you may not use this file except in + * compliance with the License. You should have received a copy of the + * Erlang Public License along with this software. If not, it can be + * retrieved online at http://www.erlang.org/. + * + * Software distributed under the License is distributed on an "AS IS" + * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + * the License for the specific language governing rights and limitations + * under the License. + * + * %CopyrightEnd% + */ +package com.ericsson.otp.erlang; + +/** + * <p> + * Provides a carrier for Erlang messages. + * </p> + * + * <p> + * 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 {@link OtpMbox#receiveMsg receiveMsg()}. + * </p> + * + * <p> + * The header information that is available is as follows: <lu> + * <li> a tag indicating the type of message + * <li> the intended recipient of the message, either as a + * {@link OtpErlangPid pid} or as a String, but never both. + * <li> (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 {@link OtpMsg#regSendTag regSendTag} contain sender information. </lu> + * + * <p> + * Message are sent using the Erlang external format (see separate + * documentation). When a message is received and delivered to the recipient + * {@link OtpMbox mailbox}, the body of the message is still in this external + * representation until {@link #getMsg 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 {@link #getMsg getMsg()} do not require that the + * message be decoded a second time. + * </p> + */ +public class OtpMsg { + public static final int linkTag = 1; + public static final int sendTag = 2; + public static final int exitTag = 3; + public static final int unlinkTag = 4; + /* public static final int nodeLinkTag = 5; */ + public static final int regSendTag = 6; + /* public static final int groupLeaderTag = 7; */ + public static final int exit2Tag = 8; + + protected int tag; // what type of message is this (send, link, exit etc) + protected OtpInputStream paybuf; + protected OtpErlangObject payload; + + protected OtpErlangPid from; + protected OtpErlangPid to; + protected String toName; + + // send has receiver pid but no sender information + OtpMsg(final OtpErlangPid to, final OtpInputStream paybuf) { + tag = sendTag; + from = null; + this.to = to; + toName = null; + this.paybuf = paybuf; + payload = null; + } + + // send has receiver pid but no sender information + OtpMsg(final OtpErlangPid to, final OtpErlangObject payload) { + tag = sendTag; + from = null; + this.to = to; + toName = null; + paybuf = null; + this.payload = payload; + } + + // send_reg has sender pid and receiver name + OtpMsg(final OtpErlangPid from, final String toName, + final OtpInputStream paybuf) { + tag = regSendTag; + this.from = from; + this.toName = toName; + to = null; + this.paybuf = paybuf; + payload = null; + } + + // send_reg has sender pid and receiver name + OtpMsg(final OtpErlangPid from, final String toName, + final OtpErlangObject payload) { + tag = regSendTag; + this.from = from; + this.toName = toName; + to = null; + paybuf = null; + this.payload = payload; + } + + // exit (etc) has from, to, reason + OtpMsg(final int tag, final OtpErlangPid from, final OtpErlangPid to, + final OtpErlangObject reason) { + this.tag = tag; + this.from = from; + this.to = to; + paybuf = null; + payload = reason; + } + + // special case when reason is an atom (i.e. most of the time) + OtpMsg(final int tag, final OtpErlangPid from, final OtpErlangPid to, + final String reason) { + this.tag = tag; + this.from = from; + this.to = to; + paybuf = null; + payload = new OtpErlangAtom(reason); + } + + // other message types (link, unlink) + OtpMsg(int tag, final OtpErlangPid from, final OtpErlangPid to) { + // convert TT-tags to equiv non-TT versions + if (tag > 10) { + tag -= 10; + } + + this.tag = tag; + this.from = from; + this.to = to; + } + + /** + * Get the payload from this message without deserializing it. + * + * @return the serialized Erlang term contained in this message. + * + */ + OtpInputStream getMsgBuf() { + return paybuf; + } + + /** + * <p> + * 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. + * </p> + * + * <p> + * 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: + * </p> + * + * <ul> + * <li> sendTag identifies a "normal" message. The recipient is a + * {@link OtpErlangPid Pid} and it is available through {@link + * #getRecipientPid getRecipientPid()}. Sender information is not available. + * The message body can be retrieved with {@link #getMsg getMsg()}. </li> + * + * <li> regSendTag also identifies a "normal" message. The recipient here is + * a String and it is available through {@link #getRecipientName + * getRecipientName()}. Sender information is available through + * #getSenderPid getSenderPid()}. The message body can be retrieved with + * {@link #getMsg getMsg()}. </li> + * + * <li> linkTag identifies a link request. The Pid of the sender is + * available, as well as the Pid to which the link should be made. </li> + * + * <li> 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 + * {@link #getMsg getMsg()}. </li> + * </ul> + */ + public int type() { + return tag; + } + + /** + * <p> + * Deserialize and return a new copy of the message contained in this + * OtpMsg. + * </p> + * + * <p> + * 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 cuase the message to be deserialized additional times, instead the + * same Erlang term object will be returned. + * </p> + * + * @return an Erlang term. + * + * @exception OtpErlangDecodeException + * if the byte stream could not be deserialized. + * + */ + public OtpErlangObject getMsg() throws OtpErlangDecodeException { + if (payload == null) { + payload = paybuf.read_any(); + } + return payload; + } + + /** + * <p> + * Get the name of the recipient for this message. + * </p> + * + * <p> + * Messages are sent to Pids or names. If this message was sent to a name + * then the name is returned by this method. + * </p> + * + * @return the name of the recipient, or null if the recipient was in fact a + * Pid. + */ + public String getRecipientName() { + return toName; + } + + /** + * <p> + * Get the Pid of the recipient for this message, if it is a sendTag + * message. + * </p> + * + * <p> + * 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. + * </p> + * + * @return the Pid of the recipient, or null if the recipient was in fact a + * name. + */ + public OtpErlangPid getRecipientPid() { + return to; + } + + /** + * <p> + * Get the name of the recipient for this message, if it is a regSendTag + * message. + * </p> + * + * <p> + * Messages are sent to Pids or names. If this message was sent to a name + * then the name is returned by this method. + * </p> + * + * @return the Pid of the recipient, or null if the recipient was in fact a + * name. + */ + public Object getRecipient() { + if (toName != null) { + return toName; + } + return to; + } + + /** + * <p> + * Get the Pid of the sender of this message. + * </p> + * + * <p> + * 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. + * </p> + * + * @return the Pid of the sender, or null if it was not available. + */ + public OtpErlangPid getSenderPid() { + return from; + } +} |