# 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:
```delphi
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:
```delphi
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:
```delphi
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:
```pascal
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:
```delphi
Table.Query;
```

To filter data, following code can be used:

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

Or alternatively:

```delphi
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:
```delphi
 Table.SortOrder.Clear;
 Table.SortOrder.Add('NAME', soAscending);
 Table.SortOrder.Add('COMPANY', soDescending);
 Table.Query;
```
Or alternatively:
```delphi
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
```delphi
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
```delphi
Table.MetaData.Clear;
Table.MetaData.Add('NAME', ftWideString, 50);
Table.MetaData.Add('COMPANY', ftWideString, 50);
Table.MetaData.Add('BIN', ftBlob);
Table.SetMetaData;
```
Or alternatively
```delphi
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.||