Persistence class

The Persistence class should be used as a singleton (call Persistence.get) that can write and potentially read GpsPointsView instances to StreamSink respectively from Stream instances. Reading from streams requires the view to be modifiable, which not all views are.

The class relies on Persister subclasses, that are registered with it as supporting particular subclasses of GpsPointsView, to do the actual streaming conversions. These Persister instances must therefore be registered by the users of this library at runtime before trying to load/store data.

Throws a NoPersisterException if called upon to operate on a view type for which no Persister has been registered.

The persisted format is structured as follows:

  • 100 bytes: Header, consisting of:
    • 20 bytes: signature to recognize that this is indeed a file stored by the library. Default value may be overridden.
    • 2 bytes: Uint16 indicating the version number of the streaming method. This is independent of the versioning of the persisted data. Persistence will not read files that have a streaming method version newer than its own, thus ensuring that older versions don't crash or read incorrectly files that are written in a newer format.
    • 20 bytes: Persister signature header to recognize data type. Each registered Persister instance must have a unique signature. This will be validated at reading time against the Persister registered for the data currently being read.
    • 2 bytes: Uint16 indicating the version number of the persisted data, so that upgrades in format are possible and recognizable without changing the header. Persistence will not read files that have a persisted data version newer than the one supported by the relevant registered Persister. Again, this ensures old versions don't try to read new data and do so badly.
    • 1 byte: the number of bytes to be read from the following metadata sub-stream
    • 55 bytes: reserved for any kind of metadata a particular Persister may require.
  • unknown number of bytes: the streamed data. By having a fixed header size, we can determine numbers of points in a file without fully parsing it, by simply looking at the total file size minus the header and dividing the outcome by the storage size per point.

Constructors

Persistence()
Do not call this constructor directly (needed for unit tests).
Persistence.get()
Factory that returns the singleton instance.
factory

Properties

hashCode → int
The hash code for this object.
no setterinherited
maxMetadataLength → int
The maximum number of bytes allowed for the metadata of a Persister. Changing this requires changing the version number of the Persistence as well as compatibility/conversion code for reading older versions.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

getPersister(GpsPointsView<GpsPoint> view) → Persister
Returns the Persister registered to handled objects of the type of view or raises NoPersisterException if not found.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
read(GpsPointsView<GpsPoint> view, Stream<List<int>> sourceStream, [int? streamSizeBytesHint]) → Future<void>
Overwrites the contents of view with data read from sourceStream. Optionally a non-null streamSizeBytesHint may be provided to indicate how large the stream is, but see caveats in StreamReaderState.remainingStreamBytesHint on its use.
register(Persister persister) → Persister
Registers the specified persister as supporting its persister.supportedType, and returns persister as result.
toString() → String
A string representation of this object.
inherited
unregister(Persister persister) → void
Unregisters the specified persister.
write(GpsPointsView<GpsPoint> view, StreamSink<List<int>> targetSink) → Future<void>
Writes view to targetSink in binary format.

Operators

operator ==(Object other) → bool
The equality operator.
inherited