1 /* 2 * %CopyrightBegin% 3 * 4 * Copyright Ericsson AB 2000-2016. All Rights Reserved. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * %CopyrightEnd% 19 */ 20 package com.ericsson.otp.erlang; 21 22 /** 23 * <p> 24 * Provides a carrier for Erlang messages. 25 * </p> 26 * 27 * <p> 28 * Instances of this class are created to package header and payload information 29 * in received Erlang messages so that the recipient can obtain both parts with 30 * a single call to {@link OtpMbox#receiveMsg receiveMsg()}. 31 * </p> 32 * 33 * <p> 34 * The header information that is available is as follows: 35 * <ul> 36 * <li>a tag indicating the type of message 37 * <li>the intended recipient of the message, either as a {@link OtpErlangPid 38 * pid} or as a String, but never both. 39 * <li>(sometimes) the sender of the message. Due to some eccentric 40 * characteristics of the Erlang distribution protocol, not all messages have 41 * information about the sending process. In particular, only messages whose tag 42 * is {@link OtpMsg#regSendTag regSendTag} contain sender information. 43 * </ul> 44 * 45 * <p> 46 * Message are sent using the Erlang external format (see separate 47 * documentation). When a message is received and delivered to the recipient 48 * {@link OtpMbox mailbox}, the body of the message is still in this external 49 * representation until {@link #getMsg getMsg()} is called, at which point the 50 * message is decoded. A copy of the decoded message is stored in the OtpMsg so 51 * that subsequent calls to {@link #getMsg getMsg()} do not require that the 52 * message be decoded a second time. 53 * </p> 54 */ 55 public class OtpMsg { 56 public static final int linkTag = 1; 57 public static final int sendTag = 2; 58 public static final int exitTag = 3; 59 public static final int unlinkTag = 4; 60 public static final int regSendTag = 6; 61 /* public static final int groupLeaderTag = 7; */ 62 public static final int exit2Tag = 8; 63 64 protected int tag; // what type of message is this (send, link, exit etc) 65 protected OtpInputStream paybuf; 66 protected OtpErlangObject payload; 67 68 protected OtpErlangPid from; 69 protected OtpErlangPid to; 70 protected String toName; 71 72 // send has receiver pid but no sender information OtpMsg(final OtpErlangPid to, final OtpInputStream paybuf)73 OtpMsg(final OtpErlangPid to, final OtpInputStream paybuf) { 74 tag = sendTag; 75 from = null; 76 this.to = to; 77 toName = null; 78 this.paybuf = paybuf; 79 payload = null; 80 } 81 82 // send has receiver pid but no sender information OtpMsg(final OtpErlangPid to, final OtpErlangObject payload)83 OtpMsg(final OtpErlangPid to, final OtpErlangObject payload) { 84 tag = sendTag; 85 from = null; 86 this.to = to; 87 toName = null; 88 paybuf = null; 89 this.payload = payload; 90 } 91 92 // send_reg has sender pid and receiver name OtpMsg(final OtpErlangPid from, final String toName, final OtpInputStream paybuf)93 OtpMsg(final OtpErlangPid from, final String toName, 94 final OtpInputStream paybuf) { 95 tag = regSendTag; 96 this.from = from; 97 this.toName = toName; 98 to = null; 99 this.paybuf = paybuf; 100 payload = null; 101 } 102 103 // send_reg has sender pid and receiver name OtpMsg(final OtpErlangPid from, final String toName, final OtpErlangObject payload)104 OtpMsg(final OtpErlangPid from, final String toName, 105 final OtpErlangObject payload) { 106 tag = regSendTag; 107 this.from = from; 108 this.toName = toName; 109 to = null; 110 paybuf = null; 111 this.payload = payload; 112 } 113 114 // exit (etc) has from, to, reason OtpMsg(final int tag, final OtpErlangPid from, final OtpErlangPid to, final OtpErlangObject reason)115 OtpMsg(final int tag, final OtpErlangPid from, final OtpErlangPid to, 116 final OtpErlangObject reason) { 117 this.tag = tag; 118 this.from = from; 119 this.to = to; 120 paybuf = null; 121 payload = reason; 122 } 123 124 // 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)125 OtpMsg(final int tag, final OtpErlangPid from, final OtpErlangPid to, 126 final String reason) { 127 this.tag = tag; 128 this.from = from; 129 this.to = to; 130 paybuf = null; 131 payload = new OtpErlangAtom(reason); 132 } 133 134 // other message types (link, unlink) OtpMsg(final int tag, final OtpErlangPid from, final OtpErlangPid to)135 OtpMsg(final int tag, final OtpErlangPid from, final OtpErlangPid to) { 136 // convert TT-tags to equiv non-TT versions 137 int atag = tag; 138 if (tag > 10) { 139 atag -= 10; 140 } 141 142 this.tag = atag; 143 this.from = from; 144 this.to = to; 145 } 146 147 /** 148 * Get the payload from this message without deserializing it. 149 * 150 * @return the serialized Erlang term contained in this message. 151 * 152 */ getMsgBuf()153 OtpInputStream getMsgBuf() { 154 return paybuf; 155 } 156 157 /** 158 * <p> 159 * Get the type marker from this message. The type marker identifies the 160 * type of message. Valid values are the ``tag'' constants defined in this 161 * class. 162 * </p> 163 * 164 * <p> 165 * The tab identifies not only the type of message but also the content of 166 * the OtpMsg object, since different messages have different components, as 167 * follows: 168 * </p> 169 * 170 * <ul> 171 * <li>sendTag identifies a "normal" message. The recipient is a 172 * {@link OtpErlangPid Pid} and it is available through 173 * {@link #getRecipientPid getRecipientPid()}. Sender information is not 174 * available. The message body can be retrieved with {@link #getMsg 175 * getMsg()}.</li> 176 * 177 * <li>regSendTag also identifies a "normal" message. The recipient here is 178 * a String and it is available through {@link #getRecipientName 179 * getRecipientName()}. Sender information is available through 180 * #getSenderPid getSenderPid()}. The message body can be retrieved with 181 * {@link #getMsg getMsg()}.</li> 182 * 183 * <li>linkTag identifies a link request. The Pid of the sender is 184 * available, as well as the Pid to which the link should be made.</li> 185 * 186 * <li>exitTag and exit2Tag messages are sent as a result of broken links. 187 * Both sender and recipient Pids and are available through the 188 * corresponding methods, and the "reason" is available through 189 * {@link #getMsg getMsg()}.</li> 190 * </ul> 191 */ type()192 public int type() { 193 return tag; 194 } 195 196 /** 197 * <p> 198 * Deserialize and return a new copy of the message contained in this 199 * OtpMsg. 200 * </p> 201 * 202 * <p> 203 * The first time this method is called the actual payload is deserialized 204 * and the Erlang term is created. Calling this method subsequent times will 205 * not cuase the message to be deserialized additional times, instead the 206 * same Erlang term object will be returned. 207 * </p> 208 * 209 * @return an Erlang term. 210 * 211 * @exception OtpErlangDecodeException 212 * if the byte stream could not be deserialized. 213 * 214 */ getMsg()215 public OtpErlangObject getMsg() throws OtpErlangDecodeException { 216 if (payload == null) { 217 payload = paybuf.read_any(); 218 } 219 return payload; 220 } 221 222 /** 223 * <p> 224 * Get the name of the recipient for this message. 225 * </p> 226 * 227 * <p> 228 * Messages are sent to Pids or names. If this message was sent to a name 229 * then the name is returned by this method. 230 * </p> 231 * 232 * @return the name of the recipient, or null if the recipient was in fact a 233 * Pid. 234 */ getRecipientName()235 public String getRecipientName() { 236 return toName; 237 } 238 239 /** 240 * <p> 241 * Get the Pid of the recipient for this message, if it is a sendTag 242 * message. 243 * </p> 244 * 245 * <p> 246 * Messages are sent to Pids or names. If this message was sent to a Pid 247 * then the Pid is returned by this method. The recipient Pid is also 248 * available for link, unlink and exit messages. 249 * </p> 250 * 251 * @return the Pid of the recipient, or null if the recipient was in fact a 252 * name. 253 */ getRecipientPid()254 public OtpErlangPid getRecipientPid() { 255 return to; 256 } 257 258 /** 259 * <p> 260 * Get the name of the recipient for this message, if it is a regSendTag 261 * message. 262 * </p> 263 * 264 * <p> 265 * Messages are sent to Pids or names. If this message was sent to a name 266 * then the name is returned by this method. 267 * </p> 268 * 269 * @return the Pid of the recipient, or null if the recipient was in fact a 270 * name. 271 */ getRecipient()272 public Object getRecipient() { 273 if (toName != null) { 274 return toName; 275 } 276 return to; 277 } 278 279 /** 280 * <p> 281 * Get the Pid of the sender of this message. 282 * </p> 283 * 284 * <p> 285 * For messages sent to names, the Pid of the sender is included with the 286 * message. The sender Pid is also available for link, unlink and exit 287 * messages. It is not available for sendTag messages sent to Pids. 288 * </p> 289 * 290 * @return the Pid of the sender, or null if it was not available. 291 */ getSenderPid()292 public OtpErlangPid getSenderPid() { 293 return from; 294 } 295 } 296