001package com.pi4j.io.serial.impl;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  AbstractSerialDataReader.java
009 *
010 * This file is part of the Pi4J project. More information about
011 * this project can be found here:  https://www.pi4j.com/
012 * **********************************************************************
013 * %%
014 * Copyright (C) 2012 - 2019 Pi4J
015 * %%
016 * This program is free software: you can redistribute it and/or modify
017 * it under the terms of the GNU Lesser General Public License as
018 * published by the Free Software Foundation, either version 3 of the
019 * License, or (at your option) any later version.
020 *
021 * This program is distributed in the hope that it will be useful,
022 * but WITHOUT ANY WARRANTY; without even the implied warranty of
023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
024 * GNU General Lesser Public License for more details.
025 *
026 * You should have received a copy of the GNU General Lesser Public
027 * License along with this program.  If not, see
028 * <http://www.gnu.org/licenses/lgpl-3.0.html>.
029 * #L%
030 */
031
032import com.pi4j.io.serial.SerialDataReader;
033
034import java.io.IOException;
035import java.io.OutputStream;
036import java.io.Writer;
037import java.nio.ByteBuffer;
038import java.nio.CharBuffer;
039import java.nio.charset.Charset;
040import java.util.Collection;
041
042public abstract class AbstractSerialDataReader implements SerialDataReader {
043
044
045    // ----------------------------------------
046    // READ OPERATIONS
047    // ----------------------------------------
048
049    /**
050     * <p>Get the number of bytes available in the serial data receive buffer.</p>
051     *
052     * @return Returns number of bytes available.
053     */
054    @Override
055    public abstract int available() throws IllegalStateException, IOException;
056
057    /**
058     * <p>Reads all available bytes bytes from the port/serial device.</p>
059     *
060     * @return Returns a byte array with the data read from the serial port.
061     */
062    public abstract byte[] read() throws IllegalStateException, IOException;
063
064    /**
065     * <p>discard/drain all available bytes from the serial port/device.</p>
066     */
067    public void discardData() throws IllegalStateException, IOException{
068        read(); // simply read all bytes and do nothing with them to drain the buffer
069    }
070
071    /**
072     * <p>Reads a length of bytes from the port/serial device.</p>
073     *
074     * @param length
075     *          The number of bytes to get from the serial port/device.
076     *          This number must not be higher than the number of available bytes.
077     *
078     * @return Returns a byte array with the data read from the serial port.
079     */
080    public abstract byte[] read(int length) throws IllegalStateException, IOException;
081
082    /**
083     * <p>Reads all available bytes from the serial device into a provided ByteBuffer.</p>
084     *
085     * @param buffer
086     *          The ByteBuffer object to write to.
087     */
088    public void read(ByteBuffer buffer) throws IllegalStateException, IOException {
089        buffer.put(read());
090    }
091
092    /**
093     * <p>Reads a length bytes from the serial port/device into a provided ByteBuffer.</p>
094     *
095     * @param length
096     *          The number of bytes to get from the serial port/device.
097     *          This number must not be higher than the number of available bytes.
098     * @param buffer
099     *          The ByteBuffer object to write to.
100     *
101     */
102    public void read(int length, ByteBuffer buffer) throws IllegalStateException, IOException {
103        buffer.put(read(length));
104    }
105
106    /**
107     * <p>Reads all available bytes from the serial device into a provided OutputStream.</p>
108     *
109     * @param stream
110     *          The OutputStream object to write to.
111     */
112    public void read(OutputStream stream) throws IllegalStateException, IOException {
113        stream.write(read());
114    }
115
116    /**
117     * <p>Reads a length bytes from the serial port/device into a provided OutputStream.</p>
118     *
119     * @param length
120     *          The number of bytes to get from the serial port/device.
121     *          This number must not be higher than the number of available bytes.
122     * @param stream
123     *          The OutputStream object to write to.
124     *
125     */
126    public void read(int length, OutputStream stream) throws IllegalStateException, IOException {
127        stream.write(read(length));
128    }
129
130    /**
131     * <p>Reads all available bytes from the serial port/device into a provided collection of ByteBuffer objects.</p>
132     *
133     * @param collection
134     *          The collection of CharSequence objects to append to.
135     *
136     */
137    public void read(Collection<ByteBuffer> collection) throws IllegalStateException, IOException {
138        collection.add(ByteBuffer.wrap(read()));
139    }
140
141    /**
142     * <p>Reads a length of bytes from the serial port/device into a provided collection of ByteBuffer objects.</p>
143     *
144     * @param length
145     *          The number of bytes to get from the serial port/device.
146     *          This number must not be higher than the number of available bytes.
147     * @param collection
148     *          The collection of CharSequence objects to append to.
149     *
150     */
151    public void read(int length, Collection<ByteBuffer> collection) throws IllegalStateException, IOException {
152        collection.add(ByteBuffer.wrap(read()));
153    }
154
155    /**
156     * <p>Reads all available bytes from the port/serial device and returns a CharBuffer from the decoded bytes.</p>
157     *
158     * @param charset
159     *          The character set to use for encoding/decoding bytes to/from text characters
160     *
161     * @return Returns a character set with the data read from the serial port.
162     */
163    public CharBuffer read(Charset charset) throws IllegalStateException, IOException {
164        return charset.decode(ByteBuffer.wrap(read()));
165    }
166
167    /**
168     * <p>Reads a length of bytes from the port/serial device and returns a CharBuffer from the decoded bytes.</p>
169     *
170     * @param length
171     *          The number of bytes to get from the serial port/device.
172     *          This number must not be higher than the number of available bytes.
173     * @param charset
174     *          The character set to use for encoding/decoding bytes to/from text characters
175     *
176     * @return Returns a character set with the data read from the serial port.
177     */
178    public CharBuffer read(int length, Charset charset) throws IllegalStateException, IOException{
179        return charset.decode(ByteBuffer.wrap(read(length)));
180    }
181
182    /**
183     * <p>Reads all available bytes from the serial port/device into a provided Writer.</p>
184     *
185     * @param charset
186     *          The character set to use for encoding/decoding bytes to/from text characters
187     * @param writer
188     *          The Writer object to write to.
189     *
190     */
191    public void read(Charset charset, Writer writer) throws IllegalStateException, IOException {
192        writer.write(read(charset).toString());
193    }
194
195    /**
196     * <p>Reads a length bytes from the serial port/device into a provided Writer.</p>
197     *
198     * @param length
199     *          The number of bytes to get from the serial port/device.
200     *          This number must not be higher than the number of available bytes.
201     * @param charset
202     *          The character set to use for encoding/decoding bytes to/from text characters
203     * @param writer
204     *          The Writer object to write to.
205     *
206     */
207    public void read(int length, Charset charset, Writer writer) throws IllegalStateException, IOException {
208        writer.write(read(length, charset).toString());
209    }
210}