DiagnosticInputStream (EasyStream 1.2.16-SNAPSHOT API)

java.lang.Object
- java.io.InputStream
- - java.io.FilterInputStream
  - - com.gc.iotools.stream.is.debug.DiagnosticInputStream<T>

Type Parameters:

T - Type of the wrapped (contained) InputStream.

All Implemented Interfaces:

Closeable, AutoCloseable
```
public class DiagnosticInputStream<T extends InputStream>
extends FilterInputStream
```
A decorating InputStream that detects and log useful debug informations about the stream passed in the constructor, and detects wrong usage patterns.
- InputStream methods accessed after invocation of close().
- Multiple invocations of close() method.
- Missing close() invocation. Stream being garbage collected without close() being called.
It normally acts as a FilterInputStream simply forwarding all the calls to the InputStream passed in the constructor, but also keeping track of the usage of the methods.

Errors are both logged at WARN level and available through the standard class interface. Future version will allow the customization of this behavior disable the logging.

It is designed to detect also errors that happens during object finalization, but to detect these errors in tests you must be very careful on your test design (see example). Errors in finalizers are available trough the getFinalizationErrors() method.

It's an useful tool in unit tests to detect wrong handling of the streams, but it can be used in main applications too since it adds a very little overhead in standard situations.

Sample Usage (in Junit 4):
```
 @org.junit.Test
 public void testWarnDoubleClose() throws Exception {
  InputStream myTestData = ....
  DiagnosticInputStream<InputStream> diagIs =
            new DiagnosticInputStream<InputStream>(myTestData);
  //The class and the method under test
  MyClassUnderTest.myMethodUnderTest(diagIs);
  final String[] instanceWarnings = diagIs.getInstanceWarnings();
  assertTrue("No problems" + diagIs.getStatusMessage(),
                        instanceWarnings.length == 0);
 }
 
```
If your code free resources in finalize() methods, or the libraries you use do so you must use a more complex testing strategy because the references to to the active DiagnosticInputStream instance in your Junit prevents the class from being garbage collected. See the wiki for details and getFinalizationErrors().
Since:

1.2.6

Version:

$Id: DiagnosticInputStream.java 606 2016-05-21 10:24:36Z gcontini $

Author:

G.Contini

Field Summary
- Fields inherited from class java.io.FilterInputStream
  in

Constructor Summary

Constructors
Constructor and Description
`DiagnosticInputStream(T in)` Constructor for DiagnosticInputStream.
`DiagnosticInputStream(T inputStream, int logDepth)` Constructor for DiagnosticInputStream.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`available()`
`void`	`clearInstanceWarnings()` clearInstanceWarnings
`void`	`close()`
`void`	`finalize()`
`int`	`getCloseCount()` Returns the number of times that close was called on this stream.
`byte[]`	`getContent()` Return the current captured bytes, if capture was enabled.
`static String[]`	`getFinalizationErrors()` Returns an array of descriptions of finalization errors.
`String[]`	`getInstanceWarnings()` getInstanceWarnings
`String`	`getStatusMessage()` Returns a string representation of the usage errors of the stream until now.
`T`	`getWrappedInputStream()` Returns the wrapped (original) `InputStream` passed in the constructor.
`boolean`	`isMethodCalledAfterClose()` isMethodCalledAfterClose
`void`	`mark(int readlimit)`
`boolean`	`markSupported()`
`int`	`read()`
`int`	`read(byte[] b)`
`int`	`read(byte[] b, int off, int len)`
`void`	`reset()`
`static void`	`resetFinalizationErrors()` resetFinalizationErrors
`static void`	`setDefaultLogDepth(int defaultFrameDepth)` Setter for the field `defaultLogDepth`.
`long`	`skip(long n)`

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

- Constructor Detail
  - DiagnosticInputStream
```
public DiagnosticInputStream(T in)
```
    Constructor for DiagnosticInputStream.
    
    Parameters:
    
    in - the source InputStream.
  - DiagnosticInputStream
```
public DiagnosticInputStream(T inputStream,
                             int logDepth)
```
    Constructor for DiagnosticInputStream.
    
    Parameters:
    
    inputStream - the source InputStream
    
    logDepth - Number of stack frames to log. It overrides the default static value.
- Method Detail
  - getFinalizationErrors
```
public static String[] getFinalizationErrors()
```
    Returns an array of descriptions of finalization errors. For instance when the stream is finalized but it was not closed.
    
    Returns:
    
    Description of finalization erros as an array of String objects.
  - resetFinalizationErrors
```
public static void resetFinalizationErrors()
```
    resetFinalizationErrors
  - setDefaultLogDepth
```
public static void setDefaultLogDepth(int defaultFrameDepth)
```
    Setter for the field defaultLogDepth.
    
    Parameters:
    
    defaultFrameDepth - a int.
  - available
```
public int available()
              throws IOException
```
    Overrides:
    
    available in class FilterInputStream
    
    Throws:
    
    IOException
  - clearInstanceWarnings
```
public void clearInstanceWarnings()
```
    clearInstanceWarnings
  - close
```
public void close()
           throws IOException
```
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Overrides:
    
    close in class FilterInputStream
    
    Throws:
    
    IOException
  - finalize
```
public void finalize()
              throws Throwable
```
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - getCloseCount
```
public int getCloseCount()
```
    Returns the number of times that close was called on this stream.
    
    Returns:
    
    number of times that close was called on this stream.
  - getContent
```
public byte[] getContent()
```
    Return the current captured bytes, if capture was enabled.
    
    The capture buffer might be truncated if maxCapture is set.
    
    Returns:
    
    the current captured bytes.
    
    Since:
    
    1.2.9
  - getInstanceWarnings
```
public String[] getInstanceWarnings()
```
    getInstanceWarnings
    
    Returns:
    
    an array of String objects.
  - getStatusMessage
```
public String getStatusMessage()
```
    Returns a string representation of the usage errors of the stream until now. Null if no error happened yet.
    
    Returns:
    
    String message that represents the errors, null if no error.
  - getWrappedInputStream
```
public T getWrappedInputStream()
```
    Returns the wrapped (original) InputStream passed in the constructor. Any calls made to the returned stream will not be tracked by DiagnosticInputStream, so this method should be used with care, and close() and read() methods should'nt be called on the returned InputStream. Instead these methods should be called on DiagnosticInputStream that simply forwards them to the underlying stream.
    
    Returns:
    
    The original InputStream passed in the constructor
  - isMethodCalledAfterClose
```
public boolean isMethodCalledAfterClose()
```
    isMethodCalledAfterClose
    
    Returns:
    
    a boolean.
  - mark
```
public void mark(int readlimit)
```
    Overrides:
    
    mark in class FilterInputStream
  - markSupported
```
public boolean markSupported()
```
    Overrides:
    
    markSupported in class FilterInputStream
  - read
```
public int read()
         throws IOException
```
    Overrides:
    
    read in class FilterInputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b)
         throws IOException
```
    Overrides:
    
    read in class FilterInputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b,
                int off,
                int len)
         throws IOException
```
    Overrides:
    
    read in class FilterInputStream
    
    Throws:
    
    IOException
  - reset
```
public void reset()
           throws IOException
```
    Overrides:
    
    reset in class FilterInputStream
    
    Throws:
    
    IOException
  - skip
```
public long skip(long n)
          throws IOException
```
    Overrides:
    
    skip in class FilterInputStream
    
    Throws:
    
    IOException

Class DiagnosticInputStream<T extends InputStream>

Field Summary

Fields inherited from class java.io.FilterInputStream

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DiagnosticInputStream

DiagnosticInputStream

Method Detail

getFinalizationErrors

resetFinalizationErrors

setDefaultLogDepth

available

clearInstanceWarnings

close

finalize

getCloseCount

getContent

getInstanceWarnings

getStatusMessage

getWrappedInputStream

isMethodCalledAfterClose

mark

markSupported

read

read

read

reset

skip