001package com.pi4j.io.serial; 002 003/* 004 * #%L 005 * ********************************************************************** 006 * ORGANIZATION : Pi4J 007 * PROJECT : Pi4J :: Java Library (Core) 008 * FILENAME : SerialDataReader.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 java.io.IOException; 033import java.io.OutputStream; 034import java.io.Writer; 035import java.nio.ByteBuffer; 036import java.nio.CharBuffer; 037import java.nio.charset.Charset; 038import java.util.Collection; 039 040 041public interface SerialDataReader { 042 043 /** 044 * Gets the number of bytes available for reading, or -1 for any error condition. 045 * 046 * @return Returns the number of bytes available for reading, or -1 for any error 047 */ 048 public int available() throws IllegalStateException, IOException; 049 050 051 // ---------------------------------------- 052 // READ OPERATIONS 053 // ---------------------------------------- 054 055 /** 056 * <p>discard/drain all available bytes from the serial port/device.</p> 057 */ 058 public void discardData() throws IllegalStateException, IOException; 059 060 /** 061 * <p>Reads all available bytes from the serial port/device.</p> 062 * 063 * @return Returns a byte array with the data read from the serial port. 064 */ 065 public byte[] read() throws IllegalStateException, IOException; 066 067 /** 068 * <p>Reads a length of bytes from the port/serial device.</p> 069 * 070 * @param length 071 * The number of bytes to get from the serial port/device. 072 * This number must not be higher than the number of available bytes. 073 * 074 * @return Returns a byte array with the data read from the serial port. 075 */ 076 public byte[] read(int length) throws IllegalStateException, IOException; 077 078 /** 079 * <p>Reads all available bytes from the serial device into a provided ByteBuffer.</p> 080 * 081 * @param buffer 082 * The ByteBuffer object to write to. 083 */ 084 public void read(ByteBuffer buffer) throws IllegalStateException, IOException; 085 086 /** 087 * <p>Reads a length bytes from the serial port/device into a provided ByteBuffer.</p> 088 * 089 * @param length 090 * The number of bytes to get from the serial port/device. 091 * This number must not be higher than the number of available bytes. 092 * @param buffer 093 * The ByteBuffer object to write to. 094 * 095 */ 096 public void read(int length, ByteBuffer buffer) throws IllegalStateException, IOException; 097 098 /** 099 * <p>Reads all available bytes from the serial device into a provided OutputStream.</p> 100 * 101 * @param stream 102 * The OutputStream object to write to. 103 */ 104 public void read(OutputStream stream) throws IllegalStateException, IOException; 105 /** 106 * <p>Reads a length bytes from the serial port/device into a provided OutputStream.</p> 107 * 108 * @param length 109 * The number of bytes to get from the serial port/device. 110 * This number must not be higher than the number of available bytes. 111 * @param stream 112 * The OutputStream object to write to. 113 * 114 */ 115 public void read(int length, OutputStream stream) throws IllegalStateException, IOException; 116 117 /** 118 * <p>Reads all available bytes from the serial port/device into a provided collection of ByteBuffer objects.</p> 119 * 120 * @param collection 121 * The collection of CharSequence objects to append to. 122 * 123 */ 124 public void read(Collection<ByteBuffer> collection) throws IllegalStateException, IOException; 125 126 /** 127 * <p>Reads a length of bytes from the serial port/device into a provided collection of ByteBuffer objects.</p> 128 * 129 * @param length 130 * The number of bytes to get from the serial port/device. 131 * This number must not be higher than the number of available bytes. 132 * @param collection 133 * The collection of CharSequence objects to append to. 134 * 135 */ 136 public void read(int length, Collection<ByteBuffer> collection) throws IllegalStateException, IOException; 137 138 /** 139 * <p>Reads all available bytes from the port/serial device and returns a CharBuffer from the decoded bytes.</p> 140 * 141 * @param charset 142 * The character set to use for encoding/decoding bytes to/from text characters 143 * 144 * @return Returns a character set with the data read from the serial port. 145 */ 146 public CharBuffer read(Charset charset) throws IllegalStateException, IOException; 147 148 /** 149 * <p>Reads a length of bytes from the port/serial device and returns a CharBuffer from the decoded bytes.</p> 150 * 151 * @param length 152 * The number of bytes to get from the serial port/device. 153 * This number must not be higher than the number of available bytes. 154 * @param charset 155 * The character set to use for encoding/decoding bytes to/from text characters 156 * 157 * @return Returns a character set with the data read from the serial port. 158 */ 159 public CharBuffer read(int length, Charset charset) throws IllegalStateException, IOException; 160 161 /** 162 * <p>Reads all available bytes from the serial port/device into a provided Writer.</p> 163 * 164 * @param charset 165 * The character set to use for encoding/decoding bytes to/from text characters 166 * @param writer 167 * The Writer object to write to. 168 * 169 */ 170 public void read(Charset charset, Writer writer) throws IllegalStateException, IOException; 171 172 /** 173 * <p>Reads a length bytes from the serial port/device into a provided Writer.</p> 174 * 175 * @param length 176 * The number of bytes to get from the serial port/device. 177 * This number must not be higher than the number of available bytes. 178 * @param charset 179 * The character set to use for encoding/decoding bytes to/from text characters 180 * @param writer 181 * The Writer object to write to. 182 * 183 */ 184 public void read(int length, Charset charset, Writer writer) throws IllegalStateException, IOException; 185}