001/**
002 * Copyright 2017, Digi International Inc.
003 *
004 * This Source Code Form is subject to the terms of the Mozilla Public
005 * License, v. 2.0. If a copy of the MPL was not distributed with this
006 * file, you can obtain one at http://mozilla.org/MPL/2.0/.
007 *
008 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 
009 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 
010 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 
011 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
012 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
013 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
014 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
015 */
016package com.digi.xbee.api.models;
017
018import com.digi.xbee.api.RemoteXBeeDevice;
019
020/**
021 * This class represents an XBee message containing the remote XBee device the 
022 * message belongs to, the content (data) of the message and a flag indicating 
023 * if the message is a broadcast message (was received or is being sent via 
024 * broadcast). 
025 * 
026 * <p>This class is used within the XBee Java Library to read data sent by 
027 * remote devices.</p>
028 */
029public class XBeeMessage {
030
031        // Variables.
032        private final RemoteXBeeDevice remoteXBeeDevice;
033        private final byte[] data;
034        private boolean isBroadcast;
035        
036        /**
037         * Class constructor. Instantiates a new object of type 
038         * {@code XBeeMessage} with the given parameters.
039         * 
040         * @param remoteXBeeDevice The remote XBee device the message belongs to.
041         * @param data Byte array containing the data of the message.
042         * 
043         * @throws NullPointerException if {@code remoteXBeeDevice == null} or
044         *                              if {@code data == null}.
045         * 
046         * @see com.digi.xbee.api.RemoteXBeeDevice
047         */
048        public XBeeMessage(RemoteXBeeDevice remoteXBeeDevice, byte[] data) {
049                this(remoteXBeeDevice, data, false);
050        }
051        
052        /**
053         * Class constructor. Instantiates a new object of type 
054         * {@code XBeeMessage} with the given parameters.
055         * 
056         * @param remoteXBeeDevice The remote XBee device the message belongs to.
057         * @param data Byte array containing the data of the message.
058         * @param isBroadcast Indicates if the message was received via broadcast.
059         * 
060         * @throws NullPointerException if {@code remoteXBeeDevice == null} or
061         *                              if {@code data == null}.
062         * 
063         * @see com.digi.xbee.api.RemoteXBeeDevice
064         */
065        public XBeeMessage(RemoteXBeeDevice remoteXBeeDevice, byte[] data, boolean isBroadcast) {
066                if (remoteXBeeDevice == null)
067                        throw new NullPointerException("Remote XBee device cannot be null.");
068                if (data == null)
069                        throw new NullPointerException("Data cannot be null.");
070                
071                this.remoteXBeeDevice = remoteXBeeDevice;
072                this.data = data;
073                this.isBroadcast = isBroadcast;
074        }
075        
076        /**
077         * Returns the remote XBee device this message is associated to.
078         * 
079         * @return The remote XBee device this message is associated to.
080         * 
081         * @see com.digi.xbee.api.RemoteXBeeDevice
082         */
083        public RemoteXBeeDevice getDevice() {
084                return remoteXBeeDevice;
085        }
086        
087        /**
088         * Returns the a byte array containing the data of the message.
089         * 
090         * @return A byte array containing the data of the message.
091         */
092        public byte[] getData() {
093                return data;
094        }
095        
096        /**
097         * Returns the data of the message in string format.
098         * 
099         * @return The data of the message in string format.
100         */
101        public String getDataString() {
102                return new String(data);
103        }
104        
105        /**
106         * Returns whether or not the message was received via broadcast.
107         * 
108         * @return {@code true} if the message was received via broadcast, 
109         *         {@code false} otherwise.
110         */
111        public boolean isBroadcast() {
112                return isBroadcast;
113        }
114}