Binary File Writer Output Adapter

Introduction

The Binary File Writer is an embedded adapter that takes tuples from a stream and writes them to a structured binary file.

In general, you will use the Binary File Writer and Binary File Reader as an adapter pair to write a stream of tuples to a file, then read them back from that file at a different point in your application. The Binary File Reader and Writer adapters are much like the CSV File Reader and Writer adapter pair, except that reading and writing binary files is significantly faster than reading and writing text files in CSV format. You might use the Binary File Writer and Reader as part of a High Availability scenario to preserve the contents of a tuple stream to disk. As part of a failover event, the secondary server in a StreamBase Server cluster could restore the contents of a stream with a fast read of the saved file.

Ports

By default, an instance of the Binary File Writer adapter has a single input port.

You can add an optional Error Output Port, which outputs a StreamBase error tuple for any adapter error.

Properties

General Tab

The Binary File Writer Adapter has the following properties on the General tab in its Properties View in StreamBase Studio:

Property	Data Type	Description
Name	string	Specify a unique name for this adapter instance.
Adapter Name	read-only field	The formal name of the adapter.
Class	read-only field	The fully qualified class name that implements the functionality of the adapter. Use this class name when loading the adapter in StreamSQL programs with the APPLY JAVA statement.
Start with application	Checkbox	If enabled, this adapter instance starts as part of the containing StreamBase Server instance. The default and recommended setting is enabled.
Enable Error Output Port	Checkbox	Check this box to add an Error Port to this adapter instance. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams in the Authoring Guide to learn about Error Ports.
Description	string	Optional. Enter text that describes the purpose of this adapter instance in your application. Text entered in this field appears in the tooltip popup for the adapter's component in the EventFlow diagram.

Adapter Settings Tab

The Binary File Writer Adapter has the following properties on the Adapter Settings tab in its Properties View in StreamBase Studio:

Property	Data Type	Description	Default
File Name	string	Specify the name of a binary output file to write. If this adapter is configured with a maximum file size, then this filename is appended with a counter extension if the maximum file size is reached. For example, if you specify a file name of `output`, then the file is rolled over to `output.0000001`, then to `output.0000002` and so on. Normally, the file is written to the directory that contains the StreamBase application. To change the target directory, you can either add relative or absolute path information to the specified file name, or edit the launch configuration used with your application to change the working directory (as described in Editing Launch Configurations.)	None
Max File Size	int	Maximum size, in bytes, of the file on disk. If the file reaches this limit, it is renamed with the current timestamp and new data is written to the current name specified in the File Name property.	0 (no rollover)
Max Roll Seconds	int	The maximum number of seconds before file names are rolled over as described above.	0 (no rollover)
Flush Interval	int	How often, in seconds, to force tuples to disk. Set this value to zero to flush immediately.	1
Sync on flush	Checkbox	Syncs operating system buffers to the file system on flush, to make sure that all changes are written. Using this options incurs a large performance penalty.	false (unchecked)
If File Exists	Radio button selection	Action to take if the specified binary file already exists when the adapter is started: Truncate existing file, or Fail.	Truncate existing file
Throttle Error Messages	Checkbox	Only show a given error message once.	false (unchecked)

Concurrency Tab

The Binary File Writer Adapter has the standard Concurrency tab in its Properties View in StreamBase Studio, as described in the Execution Order, Concurrency, and Parallelism page of the Authoring Guide.

Typechecking and Error Handling

Typechecking fails in the following circumstances:

The File Name is null or zero length string.
The Flush Interval is less than zero.
The Max File Size is less than zero.

Suspend/Resume Behavior

On suspend, this adapter stops processing tuples and closes the current file.

On resumption, it reopens a new output file named according to the file name rollover logic described for the File Name parameter above, and resumes processing tuples. That is, if the output file is named output.bin, on resumption, the new output file is named output.bin.000000, then output.bin.000001, and so on.