ZipStream Component

Properties   Methods   Events   Config Settings   Errors  

The ZipStream component is used to perform compression or decompression.

Syntax

IPWorksZip.Zipstream

Remarks

The ZipStream component provides a way to compress and decompress streamed data.

Data may be operated on in multiple ways as discussed below. The StreamFormat property specifies the algorithm to us. Possible values are:

• Deflate
• Zlib
• Gzip

Compression and Decompression Streams

The GetDecompressionStream and GetCompressionStream methods are used to retrieve streams that read or write compressed data, as appropriate; the underlying stream should be passed to either method as a parameter.

CompressBlock and DecompressBlock

The CompressBlock and DecompressBlock methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as it becomes available.

Note that when using blocks of data the OutputData property is not applicable. Instead data is made available through the CompressedData and DecompressedData events.

If all data is available ahead of time CompressData and DecompressData may be called instead.

Compress Data

Set InputData to the current block to be compressed. Next call CompressBlock to compress the current block. Note that CompressBlock takes a LastBlock parameter. If the block of data is the final block to be compressed set this to True. For all other blocks set this to False.

During compression the CompressedData event will fire with the compressed data. Note that this event may not fire for every call to CompressBlock due to the way the compression algorithm operates. For example:

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data is accumulated inside the CompressedData event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that OutputData is not applicable when compressing block data.

Decompress Data

Set InputData to the current block to be decompressed. Next call DecompressBlock to decompress the current block.

During decompression the DecompressedData event will fire with the decompressed data. Note that this event may not fire for every call to DecompressBlock due to the way the decompression algorithm operates. For example:

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the DecompressedData event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that OutputData is not applicable when decompressing block data.

CompressData and DecompressData

The CompressData and DecompressData methods operate on the complete blob of data. The entire compressed or decompressed data must be set to InputData before calling either method.

To compress and decompress data in blocks (chunks) see CompressBlock and DecompressBlock.

Compress Data

Set InputData to the decompressed data. This should be the entire data to be compressed. Next call CompressData. After compression OutputData will hold the compressed data. For example:

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the CompressedData event.

Decompress Data

Set InputData to the compressed data. This should be the entire data to be decompressed. Next call DecompressData. After decompression OutputData will hold the decompressed data. For example:

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the DecompressedData event.

Property List

---

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

CloseBaseStream Property (ZipStream Component)

Whether or not to close the underlying stream.

Syntax

public boolean isCloseBaseStream();


public void setCloseBaseStream(boolean closeBaseStream);

Default Value

True

Remarks

If true, streams created by GetCompressionStream and GetDecompressionStream will close their underlying streams when their Close method is invoked. If false, the underlying streams will remain open.

CompressionLevel Property (ZipStream Component)

The compression level to use.

Syntax

public int getCompressionLevel();


public void setCompressionLevel(int compressionLevel);

Default Value

4

Remarks

The compression level to use, from 1 to 6. Higher values will cause the component to compress better; lower values will cause the component to compress faster.

When GetCompressionStream is invoked the stream will be created with the specified compression level. After a stream has been created it is independent of the control, and changing CompressionLevel will have no effect on existing streams.

InputData Property (ZipStream Component)

Specifies the data to compress or decompress.

Syntax

public byte[] getInputData();


public void setInputData(byte[] inputData);

Default Value

""

Remarks

This property specifies the data to compress or decompress.

When decompressing this should be set to the compressed data before calling DecompressData or DecompressBlock.

When compressing this should be set to the decompressed data before calling CompressData or CompressBlock.

OutputData Property (ZipStream Component)

The output data after compression or decompression.

Syntax

public byte[] getOutputData();

Default Value

""

Remarks

This property holds the compressed or decompressed data after CompressData or DecompressData is called.

This property is not applicable when calling CompressBlock or DecompressBlock.

This property is read-only and not available at design time.

StreamFormat Property (ZipStream Component)

The stream format to use.

Syntax

public int getStreamFormat();


public void setStreamFormat(int streamFormat);

Enumerated values:
  public final static int sfDeflate = 0;

  public final static int sfZlib = 1;

  public final static int sfGzip = 2;

Default Value

0

Remarks

The stream format to use, by default Deflate.

All three stream formats use the Deflate algorithm specified in RFC 1951, which is the same algorithm used by Zip. The Zlib stream format adds a two-byte header and an Adler-32 checksum; the Gzip format adds a longer header and a CRC checksum, and is identical to the Gzip file format.

Caution: The terms zlib and deflate are sometimes used interchangeably (which is technically incorrect).

CompressBlock Method (Zipstream Component)

Compresses a block of data.

Syntax

public void compressBlock(boolean lastBlock);

Remarks

This method compresses the block of data specified by InputData.

The CompressBlock and DecompressBlock methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as it becomes available.

Note that when using blocks of data the OutputData property is not applicable. Instead data is made available through the CompressedData and DecompressedData events.

If all data is available ahead of time CompressData and DecompressData may be called instead.

Compress Data

Set InputData to the current block to be compressed. Next call CompressBlock to compress the current block. Note that CompressBlock takes a LastBlock parameter. If the block of data is the final block to be compressed set this to True. For all other blocks set this to False.

During compression the CompressedData event will fire with the compressed data. Note that this event may not fire for every call to CompressBlock due to the way the compression algorithm operates. For example:

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data is accumulated inside the CompressedData event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that OutputData is not applicable when compressing block data.

Decompress Data

Set InputData to the current block to be decompressed. Next call DecompressBlock to decompress the current block.

During decompression the DecompressedData event will fire with the decompressed data. Note that this event may not fire for every call to DecompressBlock due to the way the decompression algorithm operates. For example:

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the DecompressedData event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that OutputData is not applicable when decompressing block data.

CompressData Method (Zipstream Component)

Compresses the specified data.

Syntax

public void compressData();

Remarks

This method compresses the data specified by InputData. After calling this method OutputData holds the compressed data.

The CompressData and DecompressData methods operate on the complete blob of data. The entire compressed or decompressed data must be set to InputData before calling either method.

To compress and decompress data in blocks (chunks) see CompressBlock and DecompressBlock.

Compress Data

Set InputData to the decompressed data. This should be the entire data to be compressed. Next call CompressData. After compression OutputData will hold the compressed data. For example:

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the CompressedData event.

Decompress Data

Set InputData to the compressed data. This should be the entire data to be decompressed. Next call DecompressData. After decompression OutputData will hold the decompressed data. For example:

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the DecompressedData event.

Config Method (Zipstream Component)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DecompressBlock Method (Zipstream Component)

Decompresses a block of data.

Syntax

public void decompressBlock();

Remarks

This method decompresses the block of data specified by InputData.

The CompressBlock and DecompressBlock methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as it becomes available.

Note that when using blocks of data the OutputData property is not applicable. Instead data is made available through the CompressedData and DecompressedData events.

If all data is available ahead of time CompressData and DecompressData may be called instead.

Compress Data

Set InputData to the current block to be compressed. Next call CompressBlock to compress the current block. Note that CompressBlock takes a LastBlock parameter. If the block of data is the final block to be compressed set this to True. For all other blocks set this to False.

During compression the CompressedData event will fire with the compressed data. Note that this event may not fire for every call to CompressBlock due to the way the compression algorithm operates. For example:

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data is accumulated inside the CompressedData event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that OutputData is not applicable when compressing block data.

Decompress Data

Set InputData to the current block to be decompressed. Next call DecompressBlock to decompress the current block.

During decompression the DecompressedData event will fire with the decompressed data. Note that this event may not fire for every call to DecompressBlock due to the way the decompression algorithm operates. For example:

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the DecompressedData event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that OutputData is not applicable when decompressing block data.

DecompressData Method (Zipstream Component)

Decompresses the specified data.

Syntax

public void decompressData();

Remarks

This method decompresses the data specified by InputData. After calling this method OutputData holds the decompressed data.

The CompressData and DecompressData methods operate on the complete blob of data. The entire compressed or decompressed data must be set to InputData before calling either method.

To compress and decompress data in blocks (chunks) see CompressBlock and DecompressBlock.

Compress Data

Set InputData to the decompressed data. This should be the entire data to be compressed. Next call CompressData. After compression OutputData will hold the compressed data. For example:

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the CompressedData event.

Decompress Data

Set InputData to the compressed data. This should be the entire data to be decompressed. Next call DecompressData. After decompression OutputData will hold the decompressed data. For example:

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the DecompressedData event.

GetCompressionStream Method (Zipstream Component)

Creates an output stream used to write compressed data.

Syntax

public java.io.OutputStream getCompressionStream(java.io.OutputStream baseStream);

Remarks

GetCompressionStream returns a java.io.OutputStream used to compress data as it is written to an underlying stream. The BaseStream parameter should be the java.io.OutputStream to which the compressed data will be written.

The format (zlib or gzip) is selected with the StreamFormat property; Deflate is the default. Note that the stream, once created, is independent of the component.

The return value provides the following standard java.io.OutputStream methods. Please see the official Java documentation for details.

public void close() throws IOException

Closes the stream. Also closes BaseStream if CloseBaseStream is set to true before this stream is created.

public void flush() throws IOException

Flushes the output stream, and forces all data to be compressed and written to the underlying stream. Caution: Flush only when necessary, as repeated flushing may degrade the compression ratio.

public void write(int b) throws IOException

Compresses and writes the byte b to the underlying stream.

public void write(byte[] b) public void write(byte[] b, int off, int len)

Compresses and writes the byte array b to the underlying stream.

GetDecompressionStream Method (Zipstream Component)

Creates an input stream used to read data from a compressed stream.

Syntax

public java.io.InputStream getDecompressionStream(java.io.InputStream baseStream);

Remarks

GetDecompressionStream returns a java.io.InputStream used to read the decompressed data from a compressed stream. The BaseStream parameter should be the java.io.InputStream providing the compressed data.

The format (zlib or gzip) is selected with the StreamFormat property; Deflate is the default. Note that the stream, once created, is independent of the component.

The return value provides the following standard java.io.InputStream methods. Please see the official Java documentation for details.

public void close() throws IOException

Closes the stream. Also closes BaseStream if CloseBaseStream is set to true before this stream is created.

public int read() throws IOException

Reads a single byte of data from the input stream. Returns -1 if no data was able to be read.

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

Reads decompressed data into the provided byte array, and returns the number of bytes actually read. Returns -1 if the stream was finished.

public long skip(long n) throws IOException

Attempts to skip n bytes of (decompressed) data, and returns the number of bytes actually skipped.

Other methods (such as reset) are defined, but do nothing special, and will return default values or throw exceptions as defined by the Java API.

Reset Method (Zipstream Component)

Resets the component.

Syntax

public void reset();

Remarks

Reset resets the state of the component. All properties will be set to their default values, and any files open will be closed.

CompressedData Event (Zipstream Component)

This event fires with compressed data.

Syntax

public class DefaultZipstreamEventListener implements ZipstreamEventListener {
  ...
  public void compressedData(ZipstreamCompressedDataEvent e) {}
  ...
}

public class ZipstreamCompressedDataEvent {
  public byte[] data;

}

Remarks

The CompressedData event fires as compressed data is available when CompressData or CompressBlock is called. This may fire one or more times when data is compressed.

Data holds the current block of compressed data.

DecompressedData Event (Zipstream Component)

This event fires with decompressed data.

Syntax

public class DefaultZipstreamEventListener implements ZipstreamEventListener {
  ...
  public void decompressedData(ZipstreamDecompressedDataEvent e) {}
  ...
}

public class ZipstreamDecompressedDataEvent {
  public byte[] data;

}

Remarks

The DecompressedData event fires as compressed data is available when DecompressData or DecompressBlock is called. This may fire one or more times as data is decompressed.

Data holds the current block of decompressed data.

Error Event (Zipstream Component)

Information about errors during data delivery.

Syntax

public class DefaultZipstreamEventListener implements ZipstreamEventListener {
  ...
  public void error(ZipstreamErrorEvent e) {}
  ...
}

public class ZipstreamErrorEvent {
  public int errorCode;

  public String description;

}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (Zipstream Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

No configuration settings defined.

Base Config Settings

Trappable Errors (Zipstream Component)

Note that the streams returned by GetCompressionStream and GetDecompressionStream will throw standard IOExceptions in case of error.

ZipStream Errors

	101   The data is of an invalid or unsupported format.
	111   Can't open file for read.
	150   An I/O error has occurred (details follow).