Input ( Frame4J -- the Java framework de.frame4j... )

java.lang.Object
- java.io.InputStream
- - de.frame4j.io.Input

All Implemented Interfaces:

Closeable, AutoCloseable
```
@MinDoc(copyright="Copyright  1998 - 2009, 2016, 2019   A. Weinert",
        author="Albrecht Weinert",
        version="V.65",
        lastModified="3.06.2024",
        usage="use instead of an InputStream",
        purpose="a byte input with useful extra capabilities")
public class Input
extends InputStream
```
Handling and support for (byte-) Input.

This class facilitates the handling of reading bytes (8 bit data) from different types of sources comfortably. The sources can be
- Files,
- URLs,
- byte arrays or
- any source guised as InputStream
Some constructors and factory methods do an automatic choice between URL and file by reasonable criteria or by trial and error.

Input is an extension of InputStream with optional (build in) buffering. The ("rewind") methods mark() and reset() being at start without function (as usual) get their full effect if all input is recorded.
Methods read() and read(byte[], int, int) are overridden.

An Input object is itself an InputStream. The data source is set on construction being either a File (dataFile), a URL (url) (the not used choice is null) or another InputStream (like the standard input System.in or another process' normal or error output).

Besides all InputStream methods Input features:
- reading and buffering (recording) the content,
- (optionally) concurrent reading and buffering (recording) in an anonymous Thread,
- re activate the Input from an URL or a File.
The re-activating optimises the process of repeatedly reading from an URL or a file with dynamically changing content. It saves the otherwise needed re-creation of thwrowaway objects.

Concurrent buffering is quite useful and sometimes indispensable for loading via network connections or reading pipes form other processes. Those sources deliver asynchronously and block (otherwise) in arbitrary sequence. Input features this concurrent reading with all comfort and threadsafe (so avoiding the often seen home bread solutions).
Remark: This class Input is much older than Streams and delivered among others some of their features then, already. Now, as Frame4J requires Java8 Input might get obsolete. The removal of Input from Frame4J or the use of Stream in this class Input might be considered in future.

© Copyright 1998 - 2008, 2019, 2021 Albrecht Weinert.

Field Summary

Fields
Modifier and Type	Field and Description
`protected byte[]`	`buf` The result of recording.
`protected boolean`	`buffered` It's buffered.
`protected boolean`	`closed` Was closed.
`protected int`	`count` Total number of bytes of this Input or its buffer.
`File`	`dataFile` The File.
`protected long`	`date` Date and time of the last modification.
`protected InputStream`	`in` The (actual) underlying input stream.
`protected int`	`markPos` Reset position.
`String`	`name` The "pure" file name.
`protected boolean`	`partlyReadUnBuffered` Impossible to become totally buffered.
`protected int`	`pos` The number of bytes read from this Input.
`protected IOException`	`readError` Error while reading
`protected boolean`	`recording` Recording in progress.
`URL`	`url` The URL.
`protected URLConnection`	`urlConnection` The URL connection.

Constructor Summary

Constructors
Constructor and Description
`Input(byte[] ba, String name, long date)` Constructor for a named byte array.
`Input(File inFile)` Constructor for a File.
`Input(InputStream is)` Constructor for an InputStream.
`Input(InputStream is, String name)` Constructor for a named InputStream.
`Input(URL url, boolean open)` Constructor for an URL.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`available()`
`void`	`close()` Closing the Input.
`int`	`copyTo(OutputStream out)` Write / copy to an OutputStream.
`byte[]`	`getAsBytes()` Getting the Input's content as byte[].
`byte[]`	`getAsBytesAndClose(boolean reopen)` Getting the Input's content as byte[] and close.
`static InputStream`	`getAsResourceStream(String fileName, Class<?> baseClass)` Get an input stream for a file name as resource.
`String`	`getAsString(Charset encoding)` Getting the Input's content as String.
`String`	`getAsString(String encoding)` Getting the Input's content as String.
`int`	`getGesLen()` Total number of bytes of this Input or its buffer.
`String`	`getName()` The "pure" file name.
`IOException`	`getReadError()` Error while reading.
`boolean`	`isBuffered()` It's buffered..
`boolean`	`isClosed()` Was closed.
`boolean`	`isRecording()` Recording in progress.
`boolean`	`isTotallyBuffered()` It's totally buffered.
`long`	`lastModified()` Date and time of the last modification.
`String`	`listLine()` Generate a describing line.
`void`	`mark(int readlimit)`
`boolean`	`markSupported()`
`static Input`	`openFileOrURL(String path)` Fetch an Input object by complete path specification.
`static Input`	`openFileOrURL(String path, boolean threadRec)` Fetch an Input object by complete path specification.
`int`	`read()` Reading one byte.
`int`	`read(byte[] buf, int off, int len)` Reading multiple bytes.
`int`	`readStartOfContent(byte[] buf)` Reading the begin of the Input into a buffer.
`boolean`	`record(boolean multiThread)` Recording the input.
`Input`	`recycle(byte[] ba, long date)` Re-utilise with a byte array.
`boolean`	`reopen(boolean bufThread)` Re-open the source.
`void`	`reset()`
`long`	`skip(long n)`
`boolean`	`testDescribe(PrintWriter out)` Output a test description of this Input.
`boolean`	`wasActive()` The Input has delivered something.

Methods inherited from class java.io.InputStream
read

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - dataFile
```
public final File dataFile
```
    The File.
    
    There is at most either one File or one URL as Input's base (or none of both).
    
    See Also:
    
    url, urlConnection
  - url
```
public final URL url
```
    The URL.
    
    There is at most either one File or one URL as Input's base.
    
    See Also:
    
    dataFile, urlConnection
  - urlConnection
```
protected volatile URLConnection urlConnection
```
    The URL connection.
    
    If url is not null, the input is via an URL connection, reopened at every re-activation.
    
    See Also:
    
    url
  - name
```
public final String name
```
    The "pure" file name.
    
    See Also:
    
    getName()
  - in
```
protected volatile InputStream in
```
    The (actual) underlying input stream.
  - closed
```
protected volatile boolean closed
```
    Was closed.
  - recording
```
protected volatile boolean recording
```
    Recording in progress.
  - buffered
```
protected volatile boolean buffered
```
    It's buffered.
  - partlyReadUnBuffered
```
protected boolean partlyReadUnBuffered
```
    Impossible to become totally buffered.
  - count
```
protected int count
```
    Total number of bytes of this Input or its buffer.
    
    See Also:
    
    getGesLen()
  - date
```
protected volatile long date
```
    Date and time of the last modification.
    
    Since:
    
    04.05.2005
    
    See Also:
    
    lastModified()
  - buf
```
protected volatile byte[] buf
```
    The result of recording.
    
    If buffering was (fully) done by record() buff is no longer null.
    From then on further read operations of this InputStream use this buffer (with markSupport). Its length is is count.
  - pos
```
protected int pos
```
    The number of bytes read from this Input.
    
    This variable counts the read or skipped (read(), skip()) bytes. After buffering / recording it is the read index within the the buffer buf.
  - markPos
```
protected int markPos
```
    Reset position.
    
    In case of buffering only (isBuffered() true) this is the rewind position for reset().
  - readError
```
protected volatile IOException readError
```
    Error while reading
    
    Since:
    
    V00.07 (19.09.2002)
    
    See Also:
    
    getReadError()
- Constructor Detail
  - Input
```
public Input(File inFile)
      throws FileNotFoundException
```
    Constructor for a File.
    
    An Input object is made that reads from a File.
    
    Parameters:
    
    inFile - must represent a readable file
    
    Throws:
    
    FileNotFoundException - as by FileInputStream(File)
  - Input
```
public Input(URL url,
             boolean open)
      throws IOException
```
    Constructor for an URL.
    
    An Input object is made that reads from a URL (connection).
    
    Parameters:
    
    url - An URL object to get the input from
    
    open - true: try to open the connection at once (in the constructor)
    
    Throws:
    
    IOException - as by url.openStream
  - Input
```
public Input(InputStream is,
             String name)
```
    Constructor for a named InputStream.
    
    An Input object is made that reads from another InputStream.
    
    dataFile, url and urlConnection will be null.
    
    There will be no information on is's kind or date.
    
    Parameters:
    
    is - An InputStream to be used as input
    
    name - A simple name to tag to it; may be null
  - Input
```
public Input(InputStream is)
```
    Constructor for an InputStream.
    
    It is equivalent to Input(is, null).
  - Input
```
public Input(byte[] ba,
             String name,
             long date)
```
    Constructor for a named byte array.
    
    An Input object is made that reads from the supplied byte[] array.
    
    dataFile, url and urlConnection will be null.
    
    The Input is (not as surprise) buffered / recorded from the beginning.
    
    Parameters:
    
    ba - the content to read, must not be empty
    
    name - A simple name to tag to it; may be null
- Method Detail
  - getName
```
public final String getName()
```
    The "pure" file name.
    
    It will be tried to get the pure file name (without directory path) for the File dataFile respectively the URL url.
    
    A "FilterInputStream" constructor allows the direct setting of this name.
    This information "survives" a close().
  - isClosed
```
public boolean isClosed()
```
    Was closed.
  - isRecording
```
public boolean isRecording()
```
    Recording in progress.
    
    If a complete recording of the complete or remaining content was ordered this method returns true while this process is still running. During this time this Input object is not usable.
    Attention: Most read methods would block.
  - isBuffered
```
public final boolean isBuffered()
```
    It's buffered..
    
    If the whole input or an non empty part of it was buffered, this method returns true.
  - isTotallyBuffered
```
public final boolean isTotallyBuffered()
```
    It's totally buffered.
    
    If the whole input was buffered to the end and if no part of the content did escape buffering / this method returns true.
  - getGesLen
```
public final int getGesLen()
```
    Total number of bytes of this Input or its buffer.
    
    The total number of this Input's byte will be returned, if determinable, or -1.
    
    After buffering the whole input or of a non empty remaining part the returned value is the buffer's length.
  - lastModified
```
public long lastModified()
```
    Date and time of the last modification.
    
    For files as source of this Input's content their modification time is returned.
    
    For URLs the information is grabbed from the header. If available the modification date (last-modified)is returned or the date of delivery (date) as substitute.
    
    If indeterminable 0 (OL) is returned.
    
    Since:
    
    04.05.2005
  - getReadError
```
public final IOException getReadError()
```
    Error while reading.
    
    This method returns an exception that occurred to the methods record(), getAsString(), getAsBytes(), copyTo() etc. If all went well null is returned.
    
    Returns:
    
    null, if all went well or if an exception occurred has been re-thrown
    
    Since:
    
    V00.07 (19.09.2002)
  - openFileOrURL
```
public static Input openFileOrURL(String path)
                           throws IOException
```
    Fetch an Input object by complete path specification.
    
    Determined by the parameter path (stripped from surrounding white space) it will be tried to make an Input object.
    
    The first trial is to open a File of that name for reading.
    On failure the second try will be to use path as URL and open a connection.
    If path is empty System.in will be wrapped as Input object.
    
    The call is equivalent to openFileOrURL(path, false).
    
    Parameters:
    
    path - the name of the file or the URL
    
    Returns:
    
    an Input object
    
    Throws:
    
    IOException - no construction possible.
    
    See Also:
    
    name, dataFile, url, Input(File), Input(URL, boolean), Input(InputStream, String)
  - openFileOrURL
```
public static Input openFileOrURL(String path,
                                  boolean threadRec)
                           throws IOException
```
    Fetch an Input object by complete path specification.
    
    The method is equivalent to openFileOrURL(String path) with the extra function to immediately start reading and recording if thraedRec is true. (This is done by an anonymous inner Thread.)
    
    Parameters:
    
    path - names a file or resource for input (null gets standard in)
    
    threadRec - true: use an extra thread for reading and recording
    
    Returns:
    
    the input made
    
    Throws:
    
    IOException - file or stream problems
  - recycle
```
public Input recycle(byte[] ba,
                     long date)
```
    Re-utilise with a byte array.
    
    This method returns a (this) Input object, that reads from now on from the supplied byte[] array.
    
    dataFile, url keep their value. urlConnection will be null and date will be set by the parameter date.
    
    The Input is buffered / recorded from then on.
    
    Parameters:
    
    ba - the content to read, must not be empty. No copy is made. If null the the internal buffer used so far is taken. (Know what you do using this efficiency option.)
    
    date - the modification date to use (0L = undefined or invalid)
    
    Since:
    
    V02.32 (07.03.2008)
  - available
```
public int available()
              throws IOException
```
    Overrides:
    
    available in class InputStream
    
    Throws:
    
    IOException
  - mark
```
public void mark(int readlimit)
```
    Overrides:
    
    mark in class InputStream
  - markSupported
```
public boolean markSupported()
```
    Overrides:
    
    markSupported in class InputStream
  - reset
```
public void reset()
           throws IOException
```
    Overrides:
    
    reset in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read()
         throws IOException
```
    Reading one byte.
    
    A single byte (unsigned 0..255 as int) will be read from this Input.
    
    EOF returns -1.
    
    Specified by:
    
    read in class InputStream
    
    Returns:
    
    the unsigned 8-bit value or -1
    
    Throws:
    
    IOException - as by the underlying Stream (if any)
    
    See Also:
    
    read(byte[], int, int)
  - read
```
public int read(byte[] buf,
                int off,
                int len)
```
    Reading multiple bytes.
    
    Overrides:
    
    read in class InputStream
    
    See Also:
    
    Input.read(...)
  - skip
```
public long skip(long n)
```
    Overrides:
    
    skip in class InputStream
  - readStartOfContent
```
public int readStartOfContent(byte[] buf)
```
    Reading the begin of the Input into a buffer.
    
    The byte[] array buf will be filled with this Input's start of content respectively start of content not yet read.
    
    Reading by read(...) is used perhaps multiple times until either the array supplied is filled, EOF is reached or a problem occurred. The multiplicity of the tries may be necessary for some streams with diffuse buffering strategies or which never know how long the will be.
    
    returned is the number of bytes read. 0 if buf is ofzero length or null and -1 if the very first read shows EOF.
    
    The call is equivalent to (may be multiple) read(byte[], int, int.
    
    Parameters:
    
    buf - to put the read content in
    
    Returns:
    
    number of bytes read / put
    
    See Also:
    
    read(byte[], int, int), read(), close()
  - close
```
public void close()
```
    Closing the Input.
    
    The underlying stream / connection or what else if given is closed and forgotten. Exceptions occurring on that process are silently ignored. The underlying input is not more usable here anyway.
    
    Not forgotten are the name as well as all buffered content of gesLen bytes. That can be used and retrieved / copied as String or byte[].
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Overrides:
    
    close in class InputStream
  - reopen
```
public boolean reopen(boolean bufThread)
               throws IOException
```
    Re-open the source.
    
    This Input will be closed as by close().
    
    If it is based on a File dataFile or an URL url that will be re-opened for reading. This can be quite sensible for files and URLs having a dynamically changing content and it is than cheaper than the re-making of all objects involved. If that re-connecting / -opening succeeds true is returned.
    
    If bufThread is true, the "new" Input will be completely read / buffered by a concurrent anonymous thread.
    
    Parameters:
    
    bufThread - true: use an extra thread for reading and recording
    
    Returns:
    
    true if input is re-opened without errors (ready for use)
    
    Throws:
    
    IOException - file or stream problems
    
    See Also:
    
    record()
  - testDescribe
```
public boolean testDescribe(PrintWriter out)
```
    Output a test description of this Input.
    
    A multi-line (state) description of this Input will be sent to out.
    
    Parameters:
    
    out - the Writer to put the descriptive lines to
    
    Returns:
    
    true if backed by a File
  - listLine
```
public String listLine()
```
    Generate a describing line.
    
    In case of being backed up by a real file a line with its name, length, date and attributes is made; see dataFile.infoLine(dataFile,null, false, false).
    
    Otherwise "URL: " followed by url's description is returned, if url is not null.
    
    If neither can be made "Input: " + name or "Input: " + in.toString() is returned.
    
    Returns:
    
    the line
    
    See Also:
    
    FileHelper.infoLine(File), dataFile, url
  - wasActive
```
public boolean wasActive()
```
    The Input has delivered something.
    
    Returns true, if the input has delivered since the inquiry by this method.
  - copyTo
```
public int copyTo(OutputStream out)
```
    Write / copy to an OutputStream.
    
    If this Input was buffered() the whole content will be written to out. This works even if this Input was closed in between. That means multiple calls again transport the same content.
    
    If on the other hand this Input was not buffered() all content not yet read will be copied to out. This Input will be closed afterwards.
    
    Parameters:
    
    out - the stream to copy to
    
    Returns:
    
    >= 0 : number of bytes copied,
    -1: out is null.
    -3: broken by exception.
    
    See Also:
    
    close()
  - record
```
public boolean record(boolean multiThread)
```
    Recording the input.
    
    This Input's content respectively the yet unread rest will be buffered internally. Afterwards, the buffer content can be retrieved (even multiple times) by the methods getAsString(), getAsBytes() or copyTo().
    
    The buffering / recording can be ordered to be done in a concurrent thread by supplying setting multiThread as true). The method then returns immediately.
    
    Parameters:
    
    multiThread - true: use another thread for recording
    
    Returns:
    
    true if no concurrent buffering is running or if no further input is possible (due to empty, EOF or closed). The method getGesLen() then gives the number of read / buffered bytes.
    false if buffering / recording is still operating in a concurrent thread.
  - getAsString
```
public String getAsString(String encoding)
                   throws UnsupportedEncodingException,
                          IOException
```
    Getting the Input's content as String.
    
    This Input's content respectively the yet unread rest will be buffered internally using record(), if that was not yet done. If nothing is to be read and nothing was buffered null is returned.
    
    Otherwise the read bytes are converted to a not empty String using encoding. If encoding is empty or "defaultEncoding", ComVar.FILE_ENCODING will be used (most often ISO-8859-1 or Cp1252 on Windows).
    
    Parameters:
    
    encoding - the encoding from byte to Unicode
    
    Returns:
    
    the input bytes converted to a String
    
    Throws:
    
    UnsupportedEncodingException - if the parameter encoding is wrong
    
    IOException - if one happened during record()
    
    See Also:
    
    close(), copyTo(InputStream), ComVar.FILE_ENCODING
  - getAsString
```
public String getAsString(Charset encoding)
                   throws UnsupportedEncodingException,
                          IOException
```
    Getting the Input's content as String.
    
    This Input's content respectively the yet unread rest will be buffered internally using record(), if that was not yet done. If nothing is to be read and nothing was buffered null is returned.
    
    Otherwise the read bytes are converted to a not empty String using encoding. If encoding is null ComVar.FILE_ENCODING will be used (most often ISO-8859-1 or Cp1252 on Windows).
    
    Parameters:
    
    encoding - the encoding from byte to Unicode
    
    Returns:
    
    the input bytes converted to a String
    
    Throws:
    
    UnsupportedEncodingException - if the parameter encoding is wrong
    
    IOException - if one happened during record()
    
    See Also:
    
    close(), copyTo(InputStream), getAsString(String)
  - getAsBytes
```
public byte[] getAsBytes()
                  throws IOException
```
    Getting the Input's content as byte[].
    
    This Input's content respectively the yet unread rest will be buffered internally using record(), if that was not yet done. If nothing is to be read and nothing was buffered null is returned.
    
    Otherwise an non empty array with a copy of the input bytes is returned.
    
    Returns:
    
    the input as byte[] (copy)
    
    Throws:
    
    IOException - if one happened during record()
    
    Since:
    
    V00.04 19.09.2002
    
    See Also:
    
    close(), copyTo(InputStream)
  - getAsBytesAndClose
```
public byte[] getAsBytesAndClose(boolean reopen)
                          throws IOException
```
    Getting the Input's content as byte[] and close.
    
    If this Input is closed already and reopen is true, it will be tried to reopen it by reopen(true).
    
    This Input's content respectively the yet unread rest will be buffered internally using record(), if that was not yet done. If nothing is to be read and nothing was buffered null is returned.
    
    Otherwise an non empty array containing the input bytes is returned.
    Attention: This array is the internal buffer itself, not a copy.
    The contained must be processed or copied by the user before the next round (reopen()) should that be planned.
    Y
    
    Returns:
    
    the input as byte[] (no copy)
    
    Throws:
    
    IOException - if one happened during record()
    
    Since:
    
    V00.04 19.09.2002
    
    See Also:
    
    close(), copyTo(InputStream)
  - getAsResourceStream
```
public static InputStream getAsResourceStream(String fileName,
                                              Class<?> baseClass)
```
    Get an input stream for a file name as resource.
    
    It will be tried to determine an input stream (InputStream)from the fileName provided, that must contain no path (not even .\).
    
    It will will be tried to open:
    - a resource related to baseClass. (This would in effect be a file within the deployment .jar that class was loaded from),
    as InputStream.
    Returns:
    
    an input stream in case of success; null else

Class Input

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.io.InputStream

Methods inherited from class java.lang.Object

Field Detail

dataFile

url

urlConnection

name

in

closed

recording

buffered

partlyReadUnBuffered

count

date

buf

pos

markPos

readError

Constructor Detail

Input

Input

Input

Input

Input

Method Detail

getName

isClosed

isRecording

isBuffered

isTotallyBuffered

getGesLen

lastModified

getReadError

openFileOrURL

openFileOrURL

recycle

available

mark

markSupported

reset

read

read

skip

readStartOfContent

close

reopen

testDescribe

listLine

wasActive

copyTo

record

getAsString

getAsString

getAsBytes

getAsBytesAndClose

getAsResourceStream