aboutsummaryrefslogtreecommitdiffstats
path: root/lib/jinterface/java_src/com/ericsson/otp/erlang/OtpMsg.java
blob: 5bbcf2ab9ee1c1284d0dc403838b0b62b152d931 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
/*
 * %CopyrightBegin%
 *
 * Copyright Ericsson AB 2000-2016. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions 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:
 * <ul>
 * <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.
 * </ul>
 *
 * <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 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(final int tag, final OtpErlangPid from, final OtpErlangPid to) {
        // convert TT-tags to equiv non-TT versions
        int atag = tag;
        if (tag > 10) {
            atag -= 10;
        }

        this.tag = atag;
        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;
    }
}