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}