TTMSFNCCloudStellarDataStore

Usage

The service allows to create tables with meta data of choice to store data in the cloud. A user can have access to one or more tables. After login, the collection of tables available to the user is returned with GetTables and accessible via the Tables collection. A table on Stellar DataStore is represented by the class TTMSFNCCloudStellarDBTable. A table has metadata, entities, filters, and sort order. The table entities are represented by the class TTMSFNCCloudStellarDBEntity. The metadata for a table is retrieved via Table.GetMetaData. The entities are retrieved via the Table.Query function. The filter is accessible via the collection Table.Filters and the sort ordering can be setup via the collection Table.SortOrder.

Authorization information

Client ID, Client Secret, CallBack URL

TTMSFNCCloudStellarDataStore

TTMSFNCCloudStellarDataStore is the class that wraps the Stellar DataStore service.

Properties

Property name	Description
ProjectId: Int64	Gets or sets the unique ID of the project TTMSFNCCloudStellarDataStore can work on
TableId: Int64	Gets or sets the unique ID of the table TTMSFNCCloudStellarDataStore can work on

Methods

Project related methods

Method name	Description
GetProjects	Retrieves the list of projects and makes these accessible via TTMSFNCCloudStellarDataStore.Projects

Table related methods

Method name	Description
GetTables	Retrieves the list of tables and makes these accessible via TTMSFNCCloudStellarDataStore.Tables
TableByName(AName: string)	Retrieves a table based on its name
TableById(AId: Int64)	Retrieves a table based on its id
TableList	Retrieves a list of available tables
AddTable(ATable: TTMSFNCCloudStellarDataStoreTable)	Creates a new table from an existing TTMSFNCCloudStellarDataStore class
CreateTable(ATableName: string)	Creates a new table with name ATableName and returns an instance to the table
DeleteTable(AID: Int64)	Deletes a table based on its unique ID
DeleteTable(ATable: TTMSFNCCloudStellarDataStoreTable)	Deletes a table based on an existing TStellarDBTable class
UpdateTable(ATable: TTMSFNCCloudStellarDataStoreTable)	Updates a table name based on an existing TStellarDBTable class

Metadata related methods

Method name	Description
GetMetaData	Retrieves the metadata for the table specified by TTMSFNCCloudStellarDataStore.TableId
AddMetaData(AMetaData: TTMSFNCCloudStellarDataStoreMetaDataItem)	Sets new metadata for the table specified by TTMSFNCCloudStellarDataStore.TableId
UpdateMetaData(AID: Int64; AFieldName: string; ADataType: TFieldType = ftUnknown; ASize: integer = -1)	Modifies the meta data of a single field (specified by AID and limited to the field name, field datatype and field size) for a table specified by TTMSFNCCloudStellarDataStore.TableId
UpdateMetaData(AMetaDataItem: TTMSFNCCloudStellarDataStoreMetaDataItem)	Modifies all the meta data of a single field (specified by AMetaDataItem) for a table specified by TTMSFNCCloudStellarDataStore.TableId.
DeleteMetaData(AID: Int64)	Delete a field (specified by AID) from the meta data for a table specified by TTMSFNCCloudStellarDataStore.TableId
DeleteMetaData(AMetaDataItem: TTMSFNCCloudStellarDataStoreMetaDataItem)	Delete a field (specified by AMetaDataItem) from the meta data for a table specified by TTMSFNCCloudStellarDataStore.TableId

Entity related methods

Method name	Description
Insert(AValues: TStringList)	Inserts a singel entity based on the provided values via a stringlist
Insert(AEntities: TTMSFNCCloudStellarDataStoreEntities)	Inserts one or more entities based on the provided values via an TTMSFNCCloudStellarDataStoreEntities collection
Query	Retrieves entities for a table specified by TTMSFNCCloudStellarDataStore.TableId
Query(ATable: TTMSFNCCloudStellarDataStoreTable)	Retrieves entities for a table specified by ATable
Query(AFilters: TTMSFNCCloudStellarDataStoreFilters)	Retrieves entities with filter conditions
Query(ASortOrder: TTMSFNCCloudStellarDataStoreSortOrderList)	Retrieves entities with sort order specified
Query(AFilters: TTMSFNCCloudStellarDataStoreFilters; ASortOrder: TTMSFNCCloudStellarDataStoreSortOrderList)	Retrieves entities with filter conditions and sort order specified
Delete(AID: string)	Delete an entity with ID from a table specified by TTMSFNCCloudStellarDataStore.TableId
Delete(AIDList: TStringList)	Delete multiple entities from a table specified by TTMSFNCCloudStellarDataStore.TableId. Only entities with an ID specified in AIDList will be deleted.
DeleteAll	Delete all entities from a table specified by TTMSFNCCloudStellarDataStore.TableId
Update(AEntity: TTMSFNCCloudDataStoreEntity)	Update the entity in a table specified by TTMSFNCCloudStellarDataStore.TableId
Update(AIDList, AFieldValues: TStringList)	Update multiple entities in a table specified by TTMSFNCCloudStellarDataStore.TableId. Only entities with an ID specified in AIDList will be updated.
UpdateAll(AFieldValues: TStringList)	Update all entities in a table specified by TTMSFNCCloudStellarDataStore.TableId. Only fields specified in AFieldValues will be updated.
Download(ATableID, AEntityId: Int64; AFieldName: string; const TargetFile: string)	Download a blob to a file value from a specific entity in a specific table and fieldname
Download(ATableID, AEntityId: Int64; AFieldName: string; AStream: TStream)	Download a blob value in a stream from a specific entity in a specific table and fieldname
Upload(ATableID, AEntityId: Int64; AFieldName: string; FileName: string)	Upload a file to a blob field from a specific entity in a specific table and fieldname
Upload(ATableID, AEntityId: Int64; AFieldName: string; AStream: TStream)	Upload a stream to a blob field from a specific entity in a specific table and fieldname

User related methods

Method name	Description
GetUser	Gets information about the currently authenticated user. Fills the User properties.

Additional properties

Property name	Description
User: TTMSFNCCloudStellarDataStoreUser	Contains information about the currently authenticated user
PageIndex: Integer	When > 0, this specifies the page of entities to retrieve for the Query() methods
PageSize: Integer	When > 0, specifies the maximum number of entities to return for the Query() methods. The last page is retrieved when number of entities is smaller than PageSize.

TTMSFNCCloudStellarDataStoreEntity

The TTMSFNCCloudStellarDataStoreEntity class is the class that wraps an entity (in database terminology also often referred to as record). The TTMSFNCCloudStellarDataStoreEntity class has following methods & properties:

Properties

Property name	Description
Value[AName: string]: TValue	Retrieves the Field value based on the Field name referenced in AName
Blob[AName: string]: TTMSFNCCloudStellarDataStoreBlob	Retrieves the Blob value based on the Field referenced in AName

Methods

Method name	Description
Update	Update an existing Entity
Insert	Insert a new Entity
Delete	Delete an existing Entity

To get or set a value for a field within the entity, you can use Value[AName: string].

TTMSFNCCloudStellarDataStoreEntities

This is the collection of entities retrieved via Table.Query. Typical operations on entities are as such:

1. Create a new entity in the cloud storage:

var
  ent: TTMSFNCCloudStellarDataStoreEntity;
begin
  ent := Table.Entities.Add;
  ent.Value['NAME'] := 'John Doe';
  ent.Value['STATE'] := 'California';
  ent.Value['COMPANY'] := 'Software Company A';
  ent.Insert;
end;

2. Update an existing entity in the cloud storage:

var
  ent: TTMSFNCCloudStellarDataStoreEntity;
begin
  ent := Table.Entities[x];
  ent.Value['COMPANY'] := 'Software Company B';
  ent.Update;
end;

3. Delete an entity permanently from the cloud storage:

var
  ent: TTMSFNCCloudStellarDataStoreEntity;
begin
  ent := Table.Entities[x];
  ent.Delete;
end;

TTMSFNCCloudStellarDataStoreBlob

The TTMSFNCCloudStellarDataStoreBlob class is a wrapper class for binary data stored in a blob in the cloud service. The TTMSFNCCloudStellarDataStoreBlob class has the following properties and methods:

Properties

Property name	Description
Table: TTMSFNCCloudStellarDataStoreTable	Table to which the blob belongs
Entity: TTMSFNCCloudStellarDataStoreEntity	Entity to which the blob belongs
Field: string	Name of the field holding the blob

Methods

Method name	Description
LoadFromFile(AFileName: string);	Load data from AFileName into the blob field.
SaveToFile(AFileName: string);	Get data from the blob field and save it to a file.
LoadFromStream(AStream: TStream);	Load data from the stream into the blob field.
SaveToStream(AStream: TStream);	Get data from the blob field and save it to a stream.

A typical operation to store some binary data into a blob field in a new entity would be:

Example:

var
 ent: TTMSFNCCloudStellarDataStoreEntity;
begin
 blob: TTMSFNCCloudStellarDataStoreBlob;
 ent := Table.Entities.Add;
 blob := ent.Blob['BIN'];
 blob.LoadFromFile('mybinfile.bin');
end;

Note that for performance reasons, blobs are returned via the entity only and retrieved from the cloud storage at the time SaveToStream() or SaveToFile() is executed.

TTMSFNCCloudStellarDataStoreTable

This class represents the table in the cloud storage and is part of the set of tables in the collection Tables retrieved with GetTables.

A TTMSFNCCloudStellarDataStoreTable class has following properties and methods:

Properties

Property name	Description
ID: Int64	Read-only property returning the unique identifier of the table
OwnerID: Int64	Read-only property returning the unique owner identifier of the table
Name: string	Gets or sets the name of the table
MetaData: TStellarDBMetaData	Access to the metadata of the table via a collection after calling GetMetaData
Entities: TStellarDBEntities	Access to the entities of the table via a collection after calling Query
Filters: TStellarDBFilters	Access to the filter conditions for a query via a collection
SortOrder: TStellarDBSortOrderList	Access to the sort order settings for a query via a collection

Methods

Method name	Description
GetMetaData	Retrieves the metadata from a table, stored in MetaData
SetMetaData	Updates the metadata of the table on the cloud storage with Table.MetaData
Query	Simply query for all entities of the table, stored in Entities
Query(APageSize: Integer -1; APageIndex: Integer)	Query with specified page size and page index from fields to return, stored in Entities
Delete	Delete the table from the cloud storage

To perform a simple query, use:

Table.Query;

To filter data, following code can be used:

var
 filter: TMSFNCCloudStellarDBFilter;
begin
 Table.Filters.Clear; // removes all filter conditions
 filter := Table.Filters.Add('NAME', coLike, 'John', loNone);
 Table.Query;
end;

Or alternatively:

var
 filter: TMSFNCCloudStellarDBFilter;
begin
 Table.Filters.Clear; // removes all filter conditions
 filter := Table.Filters.Add;
 filter.FieldName := 'NAME';
 filter.ComparisonOperator := coLike;
 filter.Value := 'John';
 filter.LogicalOperator := loNone;
 Table.Query;
end;

Note that the ComparisonOperator can be any of the following values: coEqual, coLike, coGreater, coLess; The LogicalOperator that sets the logical operation between two sequential filter conditions can be: loAND, loOR, loNone

To specify the sort order for a query, the Table.SortOrder collection can be used:

 Table.SortOrder.Clear;
 Table.SortOrder.Add('NAME', soAscending);
 Table.SortOrder.Add('COMPANY', soDescending);
 Table.Query;

Or alternatively:

var
 sortorder: TTMSFNCCloudStellarDataStoreSortOrderItem;
begin
 Table.SortOrder.Clear;
 sortorder := Table.SortOrder.Add;
 sortorder.FieldName := 'NAME';
 sortorder.SortOrder := soAscending;
 sortorder := Table.SortOrder.Add;
 sortorder.FieldName := 'COMPANY';
 sortorder.SortOrder := soDescending;
 Table.Query;
end;

TTMSFNCCloudStellarDataStoreTables

This is the collection of all the tables a user has access to.

TTMSFNCCloudStellarDataStoreMetaDataItem

This class holds the information about a single meta data item in the meta data collection of a table. The meta data item class has following properties:

Properties

General Properties

These properties define the behavior of the MetaDataItem on the StellarDB server as well as in a client application.

Property name	Description
PropertyName: string	Gets or sets the field name
DataType: TFieldType	Gets or sets the field type. The field type can be any of following value: ftString, ftInt, ftBigInt, ftFloat, ftBlob, ftBoolean, ftDateTime
Size: integer	Optionally gets or sets the size of a field (only available for fields of type ftString)

The meta data item is part of the meta data collection TTMSFNCCloudStellarDataStoreMetaData accessible via Table.MetaData.

Typical operations on the meta data are:

1. Retrieval of meta data & list all fields in a listbox

var
  i: Integer;
begin
  Table.GetMetaData;
  for i := 0 to Table.MetaData.Count - 1 do
  begin
    listbox.Items.Add(Table.MetaData[i].PropertyName);
  end;
end;

2. Creating meta data for a new table

Table.MetaData.Clear;
Table.MetaData.Add('NAME', ftWideString, 50);
Table.MetaData.Add('COMPANY', ftWideString, 50);
Table.MetaData.Add('BIN', ftBlob);
Table.SetMetaData;

Or alternatively

var
  metadata: TTMSFNCCloudStellarDataStoreMetaDataItem;
begin
  Table.MetaData.Clear;
  metadata := Table.MetaData.Add;
  metadata.PropertyName := 'NAME';
  metadata.DataType := ftString;
  metadata.Size := 50;
  metadata := Table.MetaData.Add;
  metadata.PropertyName := 'COMPANY';
  metadata.DataType := ftString;
  metadata.Size := 50;
  metadata := Table.MetaData.Add;
  metadata.PropertyName := 'BIN';
  metadata.DataType := ftBlob;
  Table.SetMetaData;
end;

DataSet

Usage

TTMSFNCCloudStellarDataStoreDataSetFMX and TTMSFNCCloudStellarDataStoreDataSetVCL are the DataSet classes that provide seamless data connectivity with Stellar DataStore for data-aware controls.

The TTMSFNCCloudStellarDataStoreDataSetVCL class is intended for use in the VCL framework.

The TTMSFNCCloudStellarDataStoreDataSetFMX class is intended for use in the FireMonkey framework.

Authorization information

Client ID, Client Secret, CallBack URL

Properties

Property name	Description
ProjectId: Int64	Set the unique ID of the project TTMSFNCCloudStellarDataStoreDataSet* can work on
TableId: Int64	Set the unique ID of the table TTMSFNCCloudStellarDataStoreDataSet* can work on
Table: string	Set the name of the table TTMSFNCCloudStellarDataStoreDataSet* can work on

Only one value is required: TableId or Table.

Events

Event name	Description
OnGetBlobData	Triggered when the dataset is ready to download data from a blob field. Set AAllow to True to download the blob data. Default is False.
OnGetMetaData	Triggered when the dataset is retrieving fields. Set AAllow to False to ignore the field. Default is True.