[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

blob::iter::sqlite(n) 1 doc "Blob. General content storage with deduplication"

Name

blob::iter::sqlite - Blob - Sqlite stored iterator

Table Of Contents

Synopsis

Description

Welcome to the Blob project, written by Andreas Kupries.

For availability please read Blob - How To Get The Sources.

This package provides a blob iterator which uses tables in an sqlite3 database to hold the associations.

Note and remember that sqlite databases may exist only in memory and not just with a backing file as usual. This is another way of getting an in-memory string storage.

Class API

::blob::iter::sqlite create obj db ?options...?

This constructor command creates a new instance obj of the class and returns the fully qualified name of that instance.

Please see section Options for information about the available configuration options.

::blob::iter::sqlite new db ?options...?

This constructor command creates a new instance of the class and returns the fully qualified name of that instance.

Please see section Options for information about the available configuration options.

Options

The iterator constructor takes a number of options with which to configure the behaviour of the new instance. These are:

-blob-table string

This option names the table in which to find the mapping from uuids to blob contents. This is used by the iterator to validate uuids, and further to avoid having to store its own copy of the uuids in question. They are instead stored as the integer foreign key to the blob table. It is assumed that the blob table has the columns id, and uuid.

The default value is blob.

If the blob table is set to the empty strng the iterator will configure itself to store the uuids in its own -iter-table, see below, instead of using a foreign key.

The table will be created if it does not exist. If it exists its schema will be verified instead and an error thrown if the schema is not as expected. This uses the same schema as the blob stores created by package blob::sqlite.

-iter-table string

This option names the table used by the iterator to store the mapping from uuid to property value.

The uuid is either stored as a integer foreign key reference, or directly, depending on the value given to option -blob-table. See above for the details.

The default of this option is blobiter

The table will be created if it does not exist. If it exists its schema will be verified instead and an error thrown if the schema is not as expected.

-type string

This option specifies the sqlite type to use for the storage of property values.

The default value of this option is TEXT.

-value-table string

This option names a table used by the iterator to store the values associated with uuids, if any.

The default value of this option is the empty string, causing the iterator to store the values in the -iter-table itself.

Setting a non-empty string on the other hand causes storage of the values in the named table instead, and the -iter-table uses an integer foreign key to reference it there. The main effect of using such a sidecar is the ability to reduce the amount of space needed to store values, especially if the number of different values is expected to be small.

-value-column string

This option provides the name of the column in the -value-table used to store the values. The option's value is ignored if no value table is specified (empty string).

The default value of this option is val.

-collation string

This option specifies the name of collation to use for the ordering of values.

The option's value is ignored when a -value-table is specified, as the user has full control over the definition of that table, including the collation applied to the -value-column.

The default value of this option is the empty string, indicating that the standard collation of sqlite (BINARY) is to be used.

The main use of this option is to impose a custom ordering on the values associated with uuids, and thus influence how they are stepped through by the iterator.

Standard API

As a derived class of blob::iter instances of this class provide the following methods to their users:

<instance> add uuid value

This method associates the property_value with the blob specified by its uuid. The result of the method is the empty string. An error is thrown if the uuid is already associated with a value. This means that each uuid can only be associated with a single value, although each value can have multiple uuids associated with it.

<instance> remove uuid

This method removes the specified uuids from the iterator. The result of the method is the empty string. Unknown uuids are ignored. If a removed uuid is the current uuid the iterator is stepped forward to the next entry in sequence, as per the iterator's direction and ordering configuration.

<instance> data! tuples

This method is a bulk variant of add, see above. It expects a list of (uuid,value) pairs as argument and makes the necessary associations.

The result of the method is the empty string. An error is thrown if any of the specified uuids is already associated with a value, before any changes are made.

<instance> clear

This method removes all uuid from the iterator. After the call the instance is empty. The result of the method is the empty string.

<instance> reset

This method resets the cursor of the iterator to the start position (as per the direction/ordering of the iterator). The result of the method is an empty string.

<instance> reverse

This method reverses the direction of the iterator. The result of the method is an empty string.

<instance> next n

This method moves the cursor forward by n entries, in the current direction. The result of the method is a boolean value which indicates if the step moved beyond the end of the iterator (true), or not (false). The step-length n must be an integer > 0.

<instance> previous n

This method moves the cursor backward by n entries, against the current direction. The result of the method is a boolean value which indicates if the step moved before the start of the iterator (true), or not (false). The step-length n must be an integer > 0.

<instance> to location

This method moves the cursor of the iterator to the specified absolute location. See method location below for the method which returns such locations, and their format.

<instance> direction! dir

This method sets the direction of iterator relative to the sorting order of the values. The possible arguments are increasing and descreasing. The result of the method is the empty string.

<instance> get uuid

This method locates the value associated with uuid and returns it as its result. An error is thrown if uuid is not known to the instance.

<instance> exists uuid

This method returns a boolean value indicating if the uuid is known to the iterator (true), or not (false).

<instance> size

This method determines the number of uuid/value associations stored in the iterator and returns that number as the result of the method.

<instance> at n

This method takes the n entries of the iterator starting at the cursor and going forward, and retrurns them as its result. The result is a list of entries, each entry represented by a (uuid,value) pair. The entries are stored in the order they were taken from the iterator.

The method does not move cursor. This is the responsibility of the methods next and previous.

<instance> direction

This method determines the current direction of the iterator relative to the sort order and returns it as its result. The two possible results are increasing and decreasing

<instance> location

This method determines the location of the cursor and returns it as its result. The format of the result is a pair of values, a location code, and details, in this order. The possible location codes are

start

The cursor is before the start of the content. The detail value is the empty string.

end

The cursor is behind the end of the content. The detail value is the empty string.

at

The cursor is at a specific entry in the iterator. The detail value specifies that entry. It is a pair denoting the current property value, and the uuid, in this order.

<instance> data

This method retrieves the iterator content and returns it as a list of (uuid,value)-pairs. This is the same format as taken by method data! as input.

<instance> --> dst

This method copies the contents of the instance to the iterator instance dst. Any preexisting content of the destination instance is replaced with the information from this iterator. The targeted instance has to support the methods reset, clear, direction!, data!, and to. The result of the method is the empty string.

<instance> := src

This method copies the contents of iterator src to this iterator. Any preexisting content of this iterator is replaced with the information from the source. The source instance has to support the methods direction, data, and location. The result of the method is the empty string.

Bugs, Ideas, Feedback

Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Blob Tickets.

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

Keywords

blob, blob storage, content deduplication, content storage, deduplication, storage