001/*
002 * Copyright 2017-2019, 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;
017
018import java.net.Inet6Address;
019
020import com.digi.xbee.api.exceptions.InterfaceNotOpenException;
021import com.digi.xbee.api.exceptions.TimeoutException;
022import com.digi.xbee.api.exceptions.XBeeException;
023import com.digi.xbee.api.models.AssociationIndicationStatus;
024import com.digi.xbee.api.models.ThreadAssociationIndicationStatus;
025import com.digi.xbee.api.models.XBee16BitAddress;
026import com.digi.xbee.api.models.XBee64BitAddress;
027import com.digi.xbee.api.models.XBeeProtocol;
028import com.digi.xbee.api.utils.ByteUtils;
029
030/**
031 * This class represents a remote Thread device.
032 * 
033 * @see RemoteDigiMeshDevice
034 * @see RemoteDigiPointDevice
035 * @see RemoteRaw802Device
036 * @see RemoteXBeeDevice
037 * @see RemoteZigBeeDevice
038 * 
039 * @since 1.2.1
040 */
041public class RemoteThreadDevice extends RemoteXBeeDevice {
042
043        // Constants
044        private static final String OPERATION_EXCEPTION = "Operation not supported in Thread protocol.";
045        
046        /**
047         * Class constructor. Instantiates a new {@code RemoteThreadDevice} object 
048         * with the given local {@code ThreadDevice} which contains the connection 
049         * interface to be used.
050         * 
051         * @param localXBeeDevice The local Thread device that will behave as 
052         *                        connection interface to communicate with this 
053         *                        remote Thread device.
054         * @param ipv6Addr The IPv6 address to identify this remote Thread device.
055         * 
056         * @throws IllegalArgumentException if {@code localXBeeDevice.isRemote() == true}.
057         * @throws NullPointerException if {@code localXBeeDevice == null} or
058         *                              if {@code ipv6addr == null}.
059         * 
060         * @see #RemoteThreadDevice(AbstractXBeeDevice, Inet6Address)
061         * @see #RemoteThreadDevice(AbstractXBeeDevice, Inet6Address, String)
062         * @see com.digi.xbee.api.ThreadDevice
063         * @see java.net.Inet6Address
064         */
065        public RemoteThreadDevice(ThreadDevice localXBeeDevice, Inet6Address ipv6Addr) {
066                super(localXBeeDevice, ipv6Addr);
067        }
068        
069        /**
070         * Class constructor. Instantiates a new {@code RemoteThreadDevice} object 
071         * with the given local {@code XBeeDevice} which contains the connection 
072         * interface to be used.
073         * 
074         * @param localXBeeDevice The local XBee device that will behave as 
075         *                        connection interface to communicate with this 
076         *                        remote Thread device.
077         * @param ipv6Addr The IPv6 address to identify this remote Thread device.
078         * 
079         * @throws IllegalArgumentException if {@code localXBeeDevice.isRemote() == true} or 
080         *                                  if {@code localXBeeDevice.getXBeeProtocol() != XBeeProtocol.THREAD}.
081         * @throws NullPointerException if {@code localXBeeDevice == null} or
082         *                              if {@code ipv6addr == null}.
083         * 
084         * @see #RemoteThreadDevice(ThreadDevice, Inet6Address)
085         * @see #RemoteThreadDevice(AbstractXBeeDevice, Inet6Address, String)
086         * @see com.digi.xbee.api.XBeeDevice
087         * @see java.net.Inet6Address
088         */
089        public RemoteThreadDevice(AbstractXBeeDevice localXBeeDevice, Inet6Address ipv6Addr) {
090                super(localXBeeDevice, ipv6Addr);
091                
092                // Verify the local device has Thread protocol.
093                if (localXBeeDevice.getXBeeProtocol() != XBeeProtocol.THREAD)
094                        throw new IllegalArgumentException("The protocol of the local XBee device is not " + XBeeProtocol.THREAD.getDescription() + ".");
095        }
096        
097        /**
098         * Class constructor. Instantiates a new {@code RemoteThreadDevice} object 
099         * with the given local {@code XBeeDevice} which contains the connection 
100         * interface to be used.
101         * 
102         * @param localXBeeDevice The local XBee device that will behave as 
103         *                        connection interface to communicate with this 
104         *                        remote Thread device.
105         * @param ipv6Addr The IPv6 address to identify this remote Thread device.
106         * @param ni The node identifier of this remote Thread device. It might be 
107         *           {@code null}.
108         * 
109         * @throws IllegalArgumentException if {@code localXBeeDevice.isRemote() == true} or 
110         *                                  if {@code localXBeeDevice.getXBeeProtocol() != XBeeProtocol.THREAD}.
111         * @throws NullPointerException if {@code localXBeeDevice == null} or
112         *                              if {@code ipv6Address == null}.
113         * 
114         * @see #RemoteThreadDevice(ThreadDevice, Inet6Address)
115         * @see #RemoteThreadDevice(AbstractXBeeDevice, Inet6Address)
116         * @see com.digi.xbee.api.XBeeDevice
117         * @see java.net.Inet6Address
118         */
119        public RemoteThreadDevice(AbstractXBeeDevice localXBeeDevice, Inet6Address ipv6Addr, String ni) {
120                super(localXBeeDevice, ipv6Addr, ni);
121                
122                // Verify the local device has Thread protocol.
123                if (localXBeeDevice.getXBeeProtocol() != XBeeProtocol.THREAD)
124                        throw new IllegalArgumentException("The protocol of the local XBee device is not " + XBeeProtocol.THREAD.getDescription() + ".");
125        }
126        
127        /*
128         * (non-Javadoc)
129         * @see com.digi.xbee.api.AbstractXBeeDevice#getXBeeProtocol()
130         */
131        @Override
132        public XBeeProtocol getXBeeProtocol() {
133                return XBeeProtocol.THREAD;
134        }
135        
136        /**
137         * @deprecated Operation not supported in Thread protocol. This method
138         *             will raise an {@link UnsupportedOperationException}.
139         */
140        @Override
141        protected AssociationIndicationStatus getAssociationIndicationStatus()
142                        throws TimeoutException, XBeeException {
143                // Not supported in Thread.
144                throw new UnsupportedOperationException(OPERATION_EXCEPTION);
145        }
146        
147        /**
148         * Returns the current association status of this Thread device.
149         * 
150         * @return The association indication status of the Thread device.
151         * 
152         * @throws InterfaceNotOpenException if this device connection is not open.
153         * @throws TimeoutException if there is a timeout getting the association 
154         *                          indication status.
155         * @throws XBeeException if there is any other XBee related exception.
156         * 
157         * @see com.digi.xbee.api.models.ThreadAssociationIndicationStatus
158         */
159        public ThreadAssociationIndicationStatus getThreadAssociationIndicationStatus() throws TimeoutException, 
160                        XBeeException {
161                byte[] associationIndicationValue = getParameter("AI");
162                return ThreadAssociationIndicationStatus.get(ByteUtils.byteArrayToInt(associationIndicationValue));
163        }
164        
165        /*
166         * (non-Javadoc)
167         * @see com.digi.xbee.api.AbstractXBeeDevice#forceDisassociate()
168         */
169        @Override
170        public void forceDisassociate() throws TimeoutException, XBeeException {
171                super.forceDisassociate();
172        }
173        
174        /**
175         * @deprecated This protocol does not have an associated 16-bit address.
176         */
177        @Override
178        public XBee16BitAddress get16BitAddress() {
179                // IPv6 modules do not have 16-bit address.
180                return null;
181        }
182        
183        /**
184         * @deprecated Operation not supported in this protocol. Use
185         *             {@link #getIPv6DestinationAddress()} instead.
186         *             This method will raise an 
187         *             {@link UnsupportedOperationException}.
188         */
189        @Override
190        public XBee64BitAddress getDestinationAddress() throws TimeoutException,
191                        XBeeException {
192                // Not supported in IPv6 modules.
193                throw new UnsupportedOperationException(OPERATION_EXCEPTION);
194        }
195        
196        /**
197         * @deprecated Operation not supported in this protocol. Use
198         *             {@link #setIPv6DestinationAddress(Inet6Address)} instead.
199         *             This method will raise an 
200         *             {@link UnsupportedOperationException}.
201         */
202        @Override
203        public void setDestinationAddress(XBee64BitAddress xbee64BitAddress)
204                        throws TimeoutException, XBeeException {
205                // Not supported in IPv6 modules.
206                throw new UnsupportedOperationException(OPERATION_EXCEPTION);
207        }
208}