PGPCompressedDataGenerator
Date: 2016-06-23

org.bouncycastle.openpgp

## Class PGPCompressedDataGenerator

- java.lang.Object
- - org.bouncycastle.openpgp.PGPCompressedDataGenerator

- All Implemented Interfaces:
    CompressionAlgorithmTags

      public class PGPCompressedDataGenerator
      extends java.lang.Object
      implements CompressionAlgorithmTags

  Generator for producing compressed data packets.

  A PGPCompressedDataGenerator is used by invoking one of the open functions to create an OutputStream that raw data can be supplied to for compression:

  - If the data needs to written out in blocks, use `open(OutputStream, byte[])` to create a packet consisting of a series of compressed data objects (partials).

  A PGPCompressedDataGenerator is usually used to wrap the OutputStream `obtained` from a `PGPEncryptedDataGenerator` (i.e. to compress data prior to encrypting it).

  Raw data is not typically written directly to the OutputStream obtained from a PGPCompressedDataGenerator. The OutputStream is usually wrapped by a `PGPLiteralDataGenerator`, which encodes the raw data prior to compression.

  Once data for compression has been written to the constructed OutputStream, writing of the object stream is completed by closing the OutputStream obtained from the `#open()` method, or equivalently invoking `close()` on this generator.

- - ### Field Summary

    - ### Fields inherited from interface org.bouncycastle.bcpg.CompressionAlgorithmTags

      `BZIP2, UNCOMPRESSED, ZIP, ZLIB`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PGPCompressedDataGenerator(int algorithm)` Construct a new compressed data generator.
    `PGPCompressedDataGenerator(int algorithm, int compression)` Construct a new compressed data generator.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the compressed object - this is equivalent to calling close on the stream returned by the open() method.
    `java.io.OutputStream` | `open(java.io.OutputStream out)` Return an OutputStream which will save the data being written to the compressed object.
    `java.io.OutputStream` | `open(java.io.OutputStream out, byte[] buffer)` Return an OutputStream which will compress the data as it is written to it.

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

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

- - ### Constructor Detail

    - #### PGPCompressedDataGenerator

          public PGPCompressedDataGenerator(int algorithm)

      Construct a new compressed data generator.
      Parameters:
        `algorithm` - the identifier of the `compression algorithm` to use.

    - #### PGPCompressedDataGenerator

          public PGPCompressedDataGenerator(int algorithm,
                                    int compression)

      Construct a new compressed data generator.
      Parameters:
        `algorithm` - the identifier of the `compression algorithm` to use.
        `compression` - the `Deflater` compression level to use.

  - ### Method Detail

    - #### open

          public java.io.OutputStream open(java.io.OutputStream out)
                                    throws java.io.IOException

      Return an OutputStream which will save the data being written to the compressed object.

      The stream created can be closed off by either calling close() on the stream or close() on the generator. Closing the returned stream does not close off the OutputStream parameter out.

      Parameters:
        `out` - underlying OutputStream to be used.
      Returns:
        OutputStream
      Throws:
        `IOException,` - IllegalStateException
        `java.io.IOException`

    - #### open

          public java.io.OutputStream open(java.io.OutputStream out,
                                  byte[] buffer)
                                    throws java.io.IOException,
                                           PGPException

      Return an OutputStream which will compress the data as it is written to it. The stream will be written out in chunks (partials) according to the size of the passed in buffer.

      The stream created can be closed off by either calling close() on the stream or close() on the generator. Closing the returned stream does not close off the OutputStream parameter out.

      Note: if the buffer is not a power of 2 in length only the largest power of 2 bytes worth of the buffer will be used.

      Note: using this may break compatibility with RFC 1991 compliant tools. Only recent OpenPGP implementations are capable of accepting these streams.

      Parameters:
        `out` - the stream to write compressed packets to.
        `buffer` - a buffer to use to buffer and write partial packets. The returned stream takes ownership of the buffer and will use it to buffer plaintext data for compression.
      Returns:
        the output stream to write data to.
      Throws:
        `java.io.IOException` - if an error occurs writing stream header information to the provider output stream.
        `PGPException`
        `java.lang.IllegalStateException` - if this generator already has an open OutputStream.

    - #### close

          public void close()
                     throws java.io.IOException

      Close the compressed object - this is equivalent to calling close on the stream returned by the open() method.
      Throws:
        `java.io.IOException`