Skip to content

TTMSFNCCloudStellarDataStore (BETA)

Usage

A component that provides seamless access to the StellarDS.io service.

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 StellarDataStore.io is represented by the class TTMSFNCCloudStellarDataStoreTable. A table has metadata, entities, filters, and sort order. The table entities are represented by the class TTMSFNCCloudStellarDataStoreEntity. 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

The TTMSFNCCloudStellarDataStore component offers the choice to retrieve an access-token through authentication or use a pre-defined access-token as an API key.

  • Client ID, Client Secret, CallBack URL
  TMSFNCCloudStellarDataStore1.Authentication.ClientID := {client_id};
  TMSFNCCloudStellarDataStore1.Authentication.Secret := {client_secret};
  TMSFNCCloudStellarDataStore1.Authentication.CallBackURL := 'http://localhost:8888';
  TMSFNCCloudStellarDataStore1.Connect;
  • API key
  TMSFNCCloudStellarDataStore1.Authentication.Key := {access_token};

TTMSFNCCloudStellarDataStore

TTMSFNCCloudStellarDataStore is the class that wraps the StellarDS.io 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
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

Methods

Method name Description
GetProjects Retrieves the list of projects and makes these accessible via TTMSFNCCloudStellarDataStore.Projects
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 TTMSFNCCloudStellarDataStoreTable 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 TStellarDataStoreTable class
UpdateTable(ATable: TTMSFNCCloudStellarDataStoreTable) Updates a table name based on an existing TStellarDataStoreTable class
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
Method name Description
Insert(AValues: TStringList) Inserts a single 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(APageSize: Integer; APageIndex: Integer) Retrieves entities for a table specified by TTMSFNCCloudStellarDataStore.TableId, with a page size and page index specified
Query(ATable: TTMSFNCCloudStellarDataStoreTable) Retrieves entities for a table specified by ATable
Query(AFilters: TTMSFNCCloudStellarDataStoreFilters; ASortOrder: TTMSFNCCloudStellarDataStoreSortOrderList; AJoinQuery) Retrieves entities a table specified by TTMSFNCCloudStellarDataStore.TableId, with filter conditions, sort order and join query 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
Method name Description
GetUser Gets information about the currently authenticated user. Fills the User properties.

Events

Event name Description
OnAddMetaData Triggered when a new MetaDataItem is added
OnAddTable Triggered when a new Table is added
OnDelete Triggered when an Entity is deleted with the Delete method
OnDeleteAll Triggered when all Entities are deleted with the DeleteAll method
OnDeleteMetaData Triggered when a MetaData item is deleted
OnDeleteTable Triggered when a Table is deleted
OnDownload Triggered when blob field data is downloaded as a file
OnDownloadAsStream Triggered when blob field data is downloaded as a stream
OnGetMetaData Triggered when MetaData is retrieved
OnGetProjects Triggered when Projects are retrieved
OnGetTables Triggered when Tables are retrieved
OnGetUser Triggered when User is retrieved
OnInsert Triggered when a new Entity is inserted with the Insert method
OnQuery Triggered when the Query method is called
OnUpdate Triggered when an Entity is updated with the Update method
OnUpdateAll Triggered when all Entities are updated with the UpdateAll method
OnUpdateMetaData Triggered when a MetaDataItem is updated
OnUpdateTable Triggered when a Table is updated
OnUpload Triggered when blob field data is uploaded

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: TStellarDataStoreMetaData Access to the metadata of the table via a collection after calling GetMetaData
Entities: TStellarDataStoreEntities Access to the entities of the table via a collection after calling Query
Filters: TStellarDataStoreFilters Set the filter conditions for a query via a collection
SortOrder: TStellarDataStoreSortOrderList Set the sort order settings for a query via a collection
JoinQuery: string Set the join table settings for a query

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: TMSFNCCloudStellarDataStoreFilter;
begin
 Table.Filters.Clear; // removes all filter conditions
 filter := Table.Filters.Add('NAME', coLike, 'John', loNone);
 Table.Query;
end;

Or alternatively:

var
 filter: TMSFNCCloudStellarDataStoreFilter;
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 StellarDataStore 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;
    

TTMSFNCCloudStellarDataStoreConnection

Usage

Helper component that is used in combination with TTMSFNCCloudStellarDataStoreDataSetFMX and TTMSFNCCloudStellarDataStoreDataSetVCL.

Authorization information

The TTMSFNCCloudStellarDataStoreConnection component offers the choice to retrieve an access-token through authentication or use a pre-defined access-token as an API key.

  • Client ID, Client Secret, CallBack URL
  TMSFNCCloudStellarDataStoreConnection1.Authentication.ClientID := {client_id};
  TMSFNCCloudStellarDataStoreConnection1.Authentication.Secret := {client_secret};
  TMSFNCCloudStellarDataStoreConnection1.Authentication.CallBackURL := 'http://localhost:8888';
  TMSFNCCloudStellarDataStoreConnection1.Connect;
  • API key
  TMSFNCCloudStellarDataStoreConnection1.Authentication.Key := {access_token};

TTMSFNCCloudStellarDataStoreDataSet

Usage

TTMSFNCCloudStellarDataStoreDataSetFMX and TTMSFNCCloudStellarDataStoreDataSetVCL are the DataSet classes that provide seamless data connectivity with StellarDS.io 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.

Properties

Property name Description
ProjectId: Int64 Set the unique ID of the project the dataset can work on. (Required)
TableId: Int64 Set the unique ID of the table the dataset can work on. (Required if Table is not set)
Table: string Set the name of the table the dataset can work on. (Required if TableId is not set)

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.

Designer

With its strong design-time integration it's easy to start working with TTMSFNCCloudStellarDataStoreDataSet. Connect a TTMSFNCCloudStellarDataStoreDataSet to DB-aware controls and you are up & running. To initialize the dataset, invoke the design-time editor via the context menu:

TTMSFNCCloudStellarDataSet

And from here, you can add, delete, update tables and for each table, you can add, delete, update fields:

TTMSFNCCloudStellarDataSet

When you select a table and press the OK button, it will automatically initialize all fields in the dataset. Making it actually immediately ready to be used from DB-aware controls in native VCL Windows applications and FireMonkey (FMX) cross-platform applications.