org.eclipse.ecf.provider.filetransfer.util

## Class PollingInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - org.eclipse.ecf.provider.filetransfer.util.PollingInputStream

All Implemented Interfaces:
  Closeable, AutoCloseable

    public class PollingInputStream
    extends FilterInputStream

Polls a progress monitor periodically and handles timeouts over extended durations. For this class to be effective, a high numAttempts should be specified, and the underlying stream should time out frequently on reads (every second or so). Supports resuming partially completed operations after an InterruptedIOException if the underlying stream does. Check the bytesTransferred field to determine how much of the operation completed; conversely, at what point to resume.

Since:
  3.0

### Field Summary

### Fields inherited from class java.io.FilterInputStream

`in`

### Constructor Summary

Constructors
Constructor and Description
`PollingInputStream(InputStream in, int numAttempts, org.eclipse.core.runtime.IProgressMonitor monitor)` Creates a new polling input stream.
`PollingInputStream(InputStream in, int numAttempts, org.eclipse.core.runtime.IProgressMonitor monitor, String readTimeoutMessage, String closeTimeoutMessage)` Creates a new polling input stream.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `close()` Wraps the underlying stream's method.
`int` `read()` Wraps the underlying stream's method.
`int` `read(byte[] buffer, int off, int len)` Wraps the underlying stream's method.
`protected void` `readPendingInput()` Reads any pending input from the input stream so that the stream can savely be closed.
`void` `setIsCancellable(boolean cancellable)` Called to set whether cancellation will be checked by this stream.
`long` `skip(long count)` Wraps the underlying stream's method.

### Methods inherited from class java.io.FilterInputStream

`available, mark, markSupported, read, reset`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### PollingInputStream

    public PollingInputStream(InputStream in,
                              int numAttempts,
                              org.eclipse.core.runtime.IProgressMonitor monitor)

Creates a new polling input stream.

Parameters:
  `in` - the underlying input stream
  `numAttempts` - the number of attempts before issuing an InterruptedIOException, if 0, retries indefinitely until canceled
  `monitor` - the progress monitor to be polled for cancellation

#### PollingInputStream

    public PollingInputStream(InputStream in,
                              int numAttempts,
                              org.eclipse.core.runtime.IProgressMonitor monitor,
                              String readTimeoutMessage,
                              String closeTimeoutMessage)

Creates a new polling input stream.

Parameters:
  `in` - the underlying input stream
  `numAttempts` - the number of attempts before issuing an InterruptedIOException, if 0, retries indefinitely until canceled
  `monitor` - the progress monitor to be polled for cancellation
  `readTimeoutMessage` - message to go with InteruptedIOException if read timeout
  `closeTimeoutMessage` - message to go with InteruptedIOException if close timeout
Since:
  3.1

### Method Detail

#### close

    public void close()
               throws InterruptedIOException

Wraps the underlying stream's method. It may be important to wait for an input stream to be closed because it holds an implicit lock on a system resource (such as a file) while it is open. Closing a stream may take time if the underlying stream is still servicing a previous request.

Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Overrides:
  `close` in class `FilterInputStream`
Throws:
  `org.eclipse.core.runtime.OperationCanceledException` - if the progress monitor is canceled
  `InterruptedIOException` - if the underlying operation times out numAttempts times

#### read

    public int read()
             throws IOException

Wraps the underlying stream's method.

Overrides:
  `read` in class `FilterInputStream`
Returns:
  the next byte of data, or -1 if the end of the stream is reached.
Throws:
  `org.eclipse.core.runtime.OperationCanceledException` - if the progress monitor is canceled
  `InterruptedIOException` - if the underlying operation times out numAttempts times and no data was received, bytesTransferred will be zero
  `IOException` - if an i/o error occurs

#### read

    public int read(byte[] buffer,
                    int off,
                    int len)
             throws IOException

Wraps the underlying stream's method.

Overrides:
  `read` in class `FilterInputStream`
Parameters:
  `buffer` - - the buffer into which the data is read.
  `off` - - the start offset of the data.
  `len` - - the maximum number of bytes read.
Returns:
  the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Throws:
  `org.eclipse.core.runtime.OperationCanceledException` - if the progress monitor is canceled
  `InterruptedIOException` - if the underlying operation times out numAttempts times and no data was received, bytesTransferred will be zero
  `IOException` - if an i/o error occurs

#### skip

    public long skip(long count)
              throws IOException

Wraps the underlying stream's method.

Overrides:
  `skip` in class `FilterInputStream`
Parameters:
  `count` - - the number of bytes to be skipped.
Returns:
  the actual number of bytes skipped.
Throws:
  `org.eclipse.core.runtime.OperationCanceledException` - if the progress monitor is canceled
  `InterruptedIOException` - if the underlying operation times out numAttempts times and no data was received, bytesTransferred will be zero
  `IOException` - if an i/o error occurs

#### readPendingInput

    protected void readPendingInput()
                             throws IOException

Reads any pending input from the input stream so that the stream can savely be closed.

Throws:
  `IOException` - if some problem reading

#### setIsCancellable

    public void setIsCancellable(boolean cancellable)

Called to set whether cancellation will be checked by this stream. Turning cancellation checking off can be very useful for protecting critical portions of a protocol that shouldn't be interrupted. For example, it is often necessary to protect login sequences.

Parameters:
  `cancellable` - a flag controlling whether this stream will check for cancellation.