TTMSFNCCloudStellarDataStore
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
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
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 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 |
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 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: String; ASelectQuery: String; ADistinct: Boolean) | Retrieves entities from a table specified by TTMSFNCCloudStellarDataStore.TableId , with optional filter conditions, sort order, join query, select query and distinct 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. |
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:
- Create a new entity in the cloud storage:
- Update an existing entity in the cloud storage:
- Delete an entity permanently from the cloud storage:
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 |
SelectQuery: string | Set the select field settings for a query |
Distinct: string | Set if the SelectQuery returns all unique values from a row |
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:
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;
ComparisonOperator
can be any of the following values:
coEqual
, coLike
, coLarger
, coSmaller
, coContains
, coSmallerThanOrEqual
, coLargerThanOrEqual
, coNotEqual
, coNull
, coNotLike
;
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;
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:
- Retrieval of meta data & list all fields in a listbox
- Creating meta data for a new table
Or alternatively
Table.MetaData.Clear; Table.MetaData.Add('NAME', ftWideString, 50); Table.MetaData.Add('COMPANY', ftWideString, 50); Table.MetaData.Add('BIN', ftBlob); Table.SetMetaData;
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
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:
And from here, you can add, delete, update tables and for each table, you can add, delete, update fields:
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.