DataObjectWriter

Description

The DataObjectWriter object holds common properties and provides common mechanisms for writing a set of DataObject objects to an external resource such as a file or database. Submission mode and interval can be configured through the submitMode and submitInterval properties. The number of written datasets can be retrieved using the datasetCount property.

DataObjectWriter is an abstract base object and thus can’t be used directly. Instead inheriting objects such as CsvWriter or DatabaseTable have to be instantiated.

› Inherits:Object
› Inherited by:CsvWriter

Properties

datasetCount

This property holds the current number of datasets stored in the destination resource, e.g. lines in a CSV file or rows in a database table. This number does not necessarily have to be equal to the number of datasets written in the current session.

› Type:SignedInteger
› Attributes:Readonly

objects

This property holds a list of DataObject objects which to write to the destination resource.

› Type:List<DataObject>
› Signal:objectsChanged()
› Attributes:Readonly

running

This property holds whether the periodical data submission via submitMode and submitInterval is enabled. This allows configuring a fixed interval and start or stop data submission using this property.

› Type:Boolean
› Default:true
› Signal:runningChanged()
› Attributes:Writable

submitChangedObjectsOnly

This property holds whether to submit only objects whose values have changed since the last submission. This flag is not supported by all DataObjectWriter implementations, e.g. CsvWriter always has to write all fields to keep the file structure consistent.

This property was introduced in InCore 2.5.

› Type:Boolean
› Default:false
› Signal:submitChangedObjectsOnlyChanged()
› Attributes:Writable

submitInterval

This property holds the interval in ms between automated calls of the submit() method when submitMode is set to DataObjectWriter.SubmitPeriodically. A value of 0 disables automatic data submission.

› Type:SignedInteger
› Default:0
› Signal:submitIntervalChanged()
› Attributes:Writable

submitMode

This property holds the mode which defines how and when to submit datasets to the destination resource.

› Type:SubmitMode
› Default:DataObjectWriter.SubmitManually
› Signal:submitModeChanged()
› Attributes:Writable

Methods

close()

This method closes the destination resource. When closed no more data can be submitted. This method usually doesn’t have to be called manually.

open()

This method opens the destination resource for writing. It returns true on success, otherwise false. Errors may be raised by the specific object implementation. This method is called automatically upon data submission and doesn’t have to be called manually in most cases.

› Returns:Boolean

submit()

This method submits a new dataset to the destination resource, i.e. a new row in the output file or a database table. A dataset consists of all configured objects and usually is represented as a row in the destination resource. Instead of calling this method manually one of the submit modes should be configured through the submitMode property. On success, true is returned, otherwise false.

› Returns:Boolean

sync()

This method synchronizes any pending data or buffers to the target resource or storage. It can be called before ejecting or unmounting the underlying storage, e.g. an USB drive. In case no buffering is desired at all, appropriate modes for the target resource should be configured instead, e.g. IoDevice.unbuffered for I/O devices and files.

truncate()

This method removes all previously written datasets from the destination resource, e.g. truncate an output file or remove all rows in a database table.

Signals

objectsDataChanged(SignedInteger index)

This signal is emitted whenever the List.dataChanged() signal is emitted, i.e. the item at index in the objects list itself emitted the dataChanged() signal.

submitted()

This signal is emitted when objects have been successfully submitted.

This signal was introduced in InCore 2.3.

truncated()

This signal is emitted when objects have been truncated.

This signal was introduced in InCore 2.3.

Enumerations

SubmitMode

This enumeration describes the mode which specifies when and under which circumstances data objects should be submitted to the target. Depending on the inheriting object this can be writing a data row to a CSV file or inserting a data row in a database table.

Name Value Description
DataObjectWriter.SubmitManually 0 Submit data objects manually whenever submit() is called.
DataObjectWriter.SubmitPeriodically 1 Submit periodically depending on submitInterval and running.
DataObjectWriter.SubmitOnAnyChange 2 Submit whenever any data object changes.
DataObjectWriter.SubmitOnCompleteDataset 3 Submit once a dataset is complete, i.e. all data objects have changed since last submission.