ContentLengthInputStream (HttpClient Library (Version 3.1))
Date: 2016-03-09

org.apache.commons.httpclient

## Class ContentLengthInputStream

- java.lang.Object
- - java.io.InputStream
  - - org.apache.commons.httpclient.ContentLengthInputStream

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class ContentLengthInputStream
      extends java.io.InputStream

  Cuts the wrapped InputStream off after a specified number of bytes.

  Implementation note: Choices abound. One approach would pass through the `InputStream.mark(int)` and `InputStream.reset()` calls to the underlying stream. That's tricky, though, because you then have to start duplicating the work of keeping track of how much a reset rewinds. Further, you have to watch out for the "readLimit", and since the semantics for the readLimit leave room for differing implementations, you might get into a lot of trouble.

  Alternatively, you could make this class extend `BufferedInputStream` and then use the protected members of that class to avoid duplicated effort. That solution has the side effect of adding yet another possible layer of buffering.

  Then, there is the simple choice, which this takes - simply don't support `InputStream.mark(int)` and `InputStream.reset()`. That choice has the added benefit of keeping this class very simple.

  Since:
    2.0
  Author:
    Ortwin Glueck, Eric Johnson, Mike Bowler

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ContentLengthInputStream(java.io.InputStream in, int contentLength)` Deprecated. use `ContentLengthInputStream(InputStream, long)` Creates a new length limited stream
    `ContentLengthInputStream(java.io.InputStream in, long contentLength)` Creates a new length limited stream

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `available()`
    `void` | `close()` Reads until the end of the known length of content.
    `int` | `read()` Read the next byte from the stream
    `int` | `read(byte[] b)` Read more bytes from the stream.
    `int` | `read(byte[] b, int off, int len)` Does standard `InputStream.read(byte[], int, int)` behavior, but also notifies the watcher when the contents have been consumed.
    `long` | `skip(long n)` Skips and discards a number of bytes from the input stream.

    - ### Methods inherited from class java.io.InputStream

      `mark, markSupported, reset`

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

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

- - ### Constructor Detail

    - #### ContentLengthInputStream

          public ContentLengthInputStream(java.io.InputStream in,
                                  int contentLength)

      Deprecated. use `ContentLengthInputStream(InputStream, long)` Creates a new length limited stream
      Parameters:
        `in` - The stream to wrap
        `contentLength` - The maximum number of bytes that can be read from the stream. Subsequent read operations will return -1.

    - #### ContentLengthInputStream

          public ContentLengthInputStream(java.io.InputStream in,
                                  long contentLength)

      Creates a new length limited stream
      Parameters:
        `in` - The stream to wrap
        `contentLength` - The maximum number of bytes that can be read from the stream. Subsequent read operations will return -1.
      Since:
        3.0

  - ### Method Detail

    - #### close

          public void close()
                     throws java.io.IOException

      Reads until the end of the known length of content.

      Does not close the underlying socket input, but instead leaves it primed to parse the next response.

      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.InputStream`
      Throws:
        `java.io.IOException` - If an IO problem occurs.

    - #### read

          public int read()
                   throws java.io.IOException

      Read the next byte from the stream
      Specified by:
        `read` in class `java.io.InputStream`
      Returns:
        The next byte or -1 if the end of stream has been reached.
      Throws:
        `java.io.IOException` - If an IO problem occurs
      See Also:
        `InputStream.read()`

    - #### read

          public int read(byte[] b,
                 int off,
                 int len)
                   throws java.io.IOException

      Does standard `InputStream.read(byte[], int, int)` behavior, but also notifies the watcher when the contents have been consumed.
      Overrides:
        `read` in class `java.io.InputStream`
      Parameters:
        `b` - The byte array to fill.
        `off` - Start filling at this position.
        `len` - The number of bytes to attempt to read.
      Returns:
        The number of bytes read, or -1 if the end of content has been reached.
      Throws:
        `java.io.IOException` - Should an error occur on the wrapped stream.

    - #### read

          public int read(byte[] b)
                   throws java.io.IOException

      Read more bytes from the stream.
      Overrides:
        `read` in class `java.io.InputStream`
      Parameters:
        `b` - The byte array to put the new data in.
      Returns:
        The number of bytes read into the buffer.
      Throws:
        `java.io.IOException` - If an IO problem occurs
      See Also:
        `InputStream.read(byte[])`

    - #### skip

          public long skip(long n)
                    throws java.io.IOException

      Skips and discards a number of bytes from the input stream.
      Overrides:
        `skip` in class `java.io.InputStream`
      Parameters:
        `n` - The number of bytes to skip.
      Returns:
        The actual number of bytes skipped. <= 0 if no bytes are skipped.
      Throws:
        `java.io.IOException` - If an error occurs while skipping bytes.
      See Also:
        `InputStream.skip(long)`

    - #### available

          public int available()
                        throws java.io.IOException

      Overrides:
        `available` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

Copyright (c) 1999-2005 - Apache Software Foundation