org.apache.pdfbox.cos

## Class COSStream

- java.lang.Object
- - org.apache.pdfbox.cos.COSBase
  - - org.apache.pdfbox.cos.COSDictionary
    - - org.apache.pdfbox.cos.COSStream

All Implemented Interfaces:
  Closeable, AutoCloseable, COSUpdateInfo, COSObjectable

    public class COSStream
    extends COSDictionary
    implements Closeable

This class represents a stream object in a PDF document.

Author:
  Ben Litchfield

### Field Summary

### Fields inherited from class org.apache.pdfbox.cos.COSDictionary

`items`

### Constructor Summary

Constructors
Constructor and Description
`COSStream()` Creates a new stream with an empty dictionary.
`COSStream(ScratchFile scratchFile)` Creates a new stream with an empty dictionary.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`Object` `accept(ICOSVisitor visitor)` visitor pattern double dispatch method.
`void` `close()` Called by PDFBox when the PDDocument is closed, this closes the stream and removes the data.
`OutputStream` `createFilteredStream()` Deprecated. Use `createRawOutputStream()` instead.
`COSInputStream` `createInputStream()` Returns a new InputStream which reads the decoded stream data.
`COSInputStream` `createInputStream(DecodeOptions options)`
`OutputStream` `createOutputStream()` Returns a new OutputStream for writing stream data, using the current filters.
`OutputStream` `createOutputStream(COSBase filters)` Returns a new OutputStream for writing stream data, using and the given filters.
`InputStream` `createRawInputStream()` Returns a new InputStream which reads the encoded PDF stream data.
`OutputStream` `createRawOutputStream()` Returns a new OutputStream for writing encoded PDF data.
`OutputStream` `createUnfilteredStream()` Deprecated. Use `createOutputStream()` instead.
`InputStream` `getFilteredStream()` Deprecated. Use `createRawInputStream()` instead.
`COSBase` `getFilters()` This will return the filters to apply to the byte stream.
`long` `getLength()` Returns the length of the encoded stream.
`String` `getString()` Deprecated. Use `toTextString()` instead.
`InputStream` `getUnfilteredStream()` Deprecated. Use `createInputStream()` instead.
`void` `setFilters(COSBase filters)` Deprecated. Use `createOutputStream(COSBase)` instead.
`String` `toTextString()` Returns the contents of the stream as a PDF "text string".

### Methods inherited from class org.apache.pdfbox.cos.COSDictionary

`addAll, asUnmodifiableDictionary, clear, containsKey, containsKey, containsValue, entrySet, getBoolean, getBoolean, getBoolean, getCOSArray, getCOSDictionary, getCOSName, getCOSName, getCOSObject, getCOSStream, getDate, getDate, getDate, getDate, getDictionaryObject, getDictionaryObject, getDictionaryObject, getDictionaryObject, getEmbeddedDate, getEmbeddedDate, getEmbeddedDate, getEmbeddedDate, getEmbeddedInt, getEmbeddedInt, getEmbeddedInt, getEmbeddedInt, getEmbeddedString, getEmbeddedString, getEmbeddedString, getEmbeddedString, getFlag, getFloat, getFloat, getFloat, getFloat, getInt, getInt, getInt, getInt, getInt, getInt, getInt, getItem, getItem, getItem, getKeyForValue, getLong, getLong, getLong, getLong, getLong, getNameAsString, getNameAsString, getNameAsString, getNameAsString, getObjectFromPath, getString, getString, getString, getString, getValues, isNeedToBeUpdated, keySet, mergeInto, removeItem, setBoolean, setBoolean, setDate, setDate, setEmbeddedDate, setEmbeddedDate, setEmbeddedInt, setEmbeddedInt, setEmbeddedString, setEmbeddedString, setFlag, setFloat, setFloat, setInt, setInt, setItem, setItem, setItem, setItem, setLong, setLong, setName, setName, setNeedToBeUpdated, setString, setString, size, toString`

### Methods inherited from class org.apache.pdfbox.cos.COSBase

`getCOSObject, isDirect, setDirect`

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

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

### Constructor Detail

#### COSStream

    public COSStream()

Creates a new stream with an empty dictionary.

Try to avoid using this constructor because it creates a new scratch file in memory. Instead, use `document.getDocument().createCOSStream()` which will use the existing scratch file (in memory or in temp file) of the document.

#### COSStream

    public COSStream(ScratchFile scratchFile)

Creates a new stream with an empty dictionary. Data is stored in the given scratch file.

Parameters:
  `scratchFile` - Scratch file for writing stream data.

### Method Detail

#### getFilteredStream

    @Deprecated
    public InputStream getFilteredStream()
                                              throws IOException

Deprecated. Use `createRawInputStream()` instead.
This will get the stream with all of the filters applied.

Returns:
  the bytes of the physical (encoded) stream
Throws:
  `IOException` - when encoding causes an exception

#### createRawInputStream

    public InputStream createRawInputStream()
                                     throws IOException

Returns a new InputStream which reads the encoded PDF stream data. Experts only!

Returns:
  InputStream containing raw, encoded PDF stream data.
Throws:
  `IOException` - If the stream could not be read.

#### getUnfilteredStream

    @Deprecated
    public InputStream getUnfilteredStream()
                                                throws IOException

Deprecated. Use `createInputStream()` instead.
This will get the logical content stream with none of the filters.

Returns:
  the bytes of the logical (decoded) stream
Throws:
  `IOException` - when decoding causes an exception

#### createInputStream

    public COSInputStream createInputStream()
                                     throws IOException

Returns a new InputStream which reads the decoded stream data.

Returns:
  InputStream containing decoded stream data.
Throws:
  `IOException` - If the stream could not be read.

#### createInputStream

    public COSInputStream createInputStream(DecodeOptions options)
                                     throws IOException

Throws:
  `IOException`

#### createUnfilteredStream

    @Deprecated
    public OutputStream createUnfilteredStream()
                                                    throws IOException

Deprecated. Use `createOutputStream()` instead.
This will create an output stream that can be written to.

Returns:
  An output stream which raw data bytes should be written to.
Throws:
  `IOException` - If there is an error creating the stream.

#### createOutputStream

    public OutputStream createOutputStream()
                                    throws IOException

Returns a new OutputStream for writing stream data, using the current filters.

Returns:
  OutputStream for un-encoded stream data.
Throws:
  `IOException` - If the output stream could not be created.

#### createOutputStream

    public OutputStream createOutputStream(COSBase filters)
                                    throws IOException

Returns a new OutputStream for writing stream data, using and the given filters.

Parameters:
  `filters` - COSArray or COSName of filters to be used.
Returns:
  OutputStream for un-encoded stream data.
Throws:
  `IOException` - If the output stream could not be created.

#### createFilteredStream

    @Deprecated
    public OutputStream createFilteredStream()
                                                  throws IOException

Deprecated. Use `createRawOutputStream()` instead.
This will create a new stream for which filtered byte should be written to. You probably don't want this but want to use the createUnfilteredStream, which is used to write raw bytes to.

Returns:
  A stream that can be written to.
Throws:
  `IOException` - If there is an error creating the stream.

#### createRawOutputStream

    public OutputStream createRawOutputStream()
                                       throws IOException

Returns a new OutputStream for writing encoded PDF data. Experts only!

Returns:
  OutputStream for raw PDF stream data.
Throws:
  `IOException` - If the output stream could not be created.

#### getLength

    public long getLength()

Returns the length of the encoded stream.

Returns:
  length in bytes

#### getFilters

    public COSBase getFilters()

This will return the filters to apply to the byte stream. The method will return

- null if no filters are to be applied
- a COSName if one filter is to be applied
- a COSArray containing COSNames if multiple filters are to be applied

Returns:
  the COSBase object representing the filters

#### setFilters

    @Deprecated
    public void setFilters(COSBase filters)
                                throws IOException

Deprecated. Use `createOutputStream(COSBase)` instead.
Sets the filters to be applied when encoding or decoding the stream.

Parameters:
  `filters` - The filters to set on this stream.
Throws:
  `IOException` - If there is an error clearing the old filters.

#### getString

    @Deprecated
    public String getString()

Deprecated. Use `toTextString()` instead.
Returns the contents of the stream as a text string.

Returns:
  the string representation of this string.

#### toTextString

    public String toTextString()

Returns the contents of the stream as a PDF "text string".

Returns:
  the text string representation of this stream.

#### accept

    public Object accept(ICOSVisitor visitor)
                  throws IOException

Description copied from class: `COSDictionary`
visitor pattern double dispatch method.

Overrides:
  `accept` in class `COSDictionary`
Parameters:
  `visitor` - The object to notify when visiting this object.
Returns:
  The object that the visitor returns.
Throws:
  `IOException` - If there is an error visiting this object.

#### close

    public void close()
               throws IOException

Called by PDFBox when the PDDocument is closed, this closes the stream and removes the data. You will usually not need this.

Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Throws:
  `IOException`