    001/**
    002 * Copyright (c) 2014 Digi International Inc.,
    003 * All rights not expressly granted are reserved.
    004 *
    005 * This Source Code Form is subject to the terms of the Mozilla Public
    006 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
    007 * You can obtain one at http://mozilla.org/MPL/2.0/.
    008 *
    009 * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
    010 * =======================================================================
    011 */
    012package com.digi.xbee.api.connection;
    013
    014import java.io.IOException;
    015import java.io.InputStream;
    016import java.io.OutputStream;
    017
    018import com.digi.xbee.api.exceptions.InterfaceInUseException;
    019import com.digi.xbee.api.exceptions.InvalidConfigurationException;
    020import com.digi.xbee.api.exceptions.InvalidInterfaceException;
    021import com.digi.xbee.api.exceptions.PermissionDeniedException;
    022
    023/**
    024 * This interface represents a protocol independent connection with an XBee
    025 * device.
    026 *
    027 * <p>The connection can be made using sockets, serial port, etc.</p>
    028 *
    029 * <p>As an important point, the class implementing this interface must call
    030 * {@code this.notify()} whenever new data is available to read. Not doing this
    031 * will make the {@code DataReader} class to wait forever for new data.</p>
    032 */
    033public interface IConnectionInterface {
    034
    035        /**
    036         * Attempts to open the connection interface.
    037         *
    038         * @throws InterfaceInUseException if the interface is in use by other
    039         *                                 application(s).
    040         * @throws InvalidConfigurationException if the configuration used to open
    041         *                                       the interface is invalid.
    042         * @throws InvalidInterfaceException if the interface is invalid or does
    043         *                                   not exist.
    044         * @throws PermissionDeniedException if you do not have permissions to
    045         *                                   access the interface.
    046         *
    047         * @see #close()
    048         * @see #isOpen()
    049         */
    050        public void open() throws InterfaceInUseException, InvalidInterfaceException, InvalidConfigurationException, PermissionDeniedException;
    051
    052        /**
    053         * Attempts to close the connection interface.
    054         *
    055         * @see #isOpen()
    056         * @see #open()
    057         */
    058        public void close();
    059
    060        /**
    061         * Returns whether the connection interface is open or not.
    062         *
    063         * @return {@code true} if the connection interface is open, {@code false}
    064         *         otherwise.
    065         *
    066         * @see #close()
    067         * @see #open()
    068         */
    069        public boolean isOpen();
    070
    071        /**
    072         * Returns the connection interface input stream to read data from.
    073         *
    074         * @return The connection interface input stream to read data from.
    075         *
    076         * @see #getOutputStream()
    077         * @see java.io.InputStream
    078         */
    079        public InputStream getInputStream();
    080
    081        /**
    082         * Returns the connection interface output stream to write data to.
    083         *
    084         * @return The connection interface output stream to write data to.
    085         *
    086         * @see #getInputStream()
    087         * @see java.io.OutputStream
    088         */
    089        public OutputStream getOutputStream();
    090
    091        /**
    092         * Writes the given data in the connection interface.
    093         *
    094         * @param data The data to be written in the connection interface.
    095         *
    096         * @throws IOException if there is any problem writing to the output stream.
    097         * @throws NullPointerException if {@code data == null}.
    098         *
    099         * @see #writeData(byte[], int, int)
    100         */
    101        public void writeData(byte[] data) throws IOException;
    102
    103        /**
    104         * Writes the given data in the connection interface.
    105         *
    106         * @param data The data to be written in the connection interface.
    107         * @param offset The start offset in the data to write.
    108         * @param length The number of bytes to write.
    109         *
    110         * @throws IllegalArgumentException if {@code offset < 0} or
    111         *                                  if {@code length < 1} or
    112         *                                  if {@code offset >= data.length} or
    113         *                                  if {@code offset + length > data.length}.
    114         * @throws IOException if there is any problem writing to the output stream.
    115         * @throws NullPointerException if {@code data == null}.
    116         *
    117         * @see #writeData(byte[])
    118         */
    119        public void writeData(byte[] data, int offset, int length) throws IOException;
    120
    121        /**
    122         * Reads data from the connection interface and stores it in the provided
    123         * byte array returning the number of read bytes.
    124         *
    125         * @param data The byte array to store the read data.
    126         *
    127         * @return The number of bytes read.
    128         *
    129         * @throws IOException if there is any problem reading from the input stream.
    130         * @throws NullPointerException if {@code data == null}.
    131         *
    132         * @see #readData(byte[], int, int)
    133         */
    134        public int readData(byte[] data) throws IOException;
    135
    136        /**
    137         * Reads the given number of bytes at the given offset from the connection
    138         * interface and stores it in the provided byte array returning the number
    139         * of read bytes.
    140         *
    141         * @param data The byte array to store the read data.
    142         * @param offset The start offset in data array at which the data is written.
    143         * @param length Maximum number of bytes to read.
    144         *
    145         * @return The number of bytes read.
    146         *
    147         * @throws IllegalArgumentException if {@code offset < 0} or
    148         *                                  if {@code length < 1} or
    149         *                                  if {@code offset >= data.length} or
    150         *                                  if {@code offset + length > data.length}.
    151         * @throws IOException if there is any problem reading from the input stream.
    152         * @throws NullPointerException if {@code data == null}.
    153         *
    154         * @see #readData(byte[])
    155         */
    156        public int readData(byte[] data, int offset, int length) throws IOException;
    157}