@cordova-plugin-agconnect/clouddb
Version:
Cordova AGC CloudDB Plugin
872 lines (796 loc) • 30.5 kB
text/typescript
/*
* Copyright (c) Huawei Technologies Co., Ltd. 2021-2021. All rights reserved.
*/
import { Injectable } from '@angular/core';
import { Cordova, IonicNativePlugin, Plugin } from '@ionic-native/core';
export class AGCCloudDBPlugin extends IonicNativePlugin {
/**
* Initializes AGConnectCloudDB.
*/
initialize(): Promise<void> {
return;
}
/**
* This method is called to create or modify an object type,
* define a set of CloudDBZoneObject storage objects,
* and store data generated by the application.
*/
createObjectType(): Promise<void> {
return;
}
/**
* Obtains all CloudDBZoneConfig lists in the AGConnectCloudDB instance on the device.
* @returns CloudDBZoneConfig object and configure Cloud DB zone information
* such as the synchronization property, access property, encrypted storage property,
* and data persistency property.
*/
getCloudDBZoneConfigs(): Promise<CloudDBZoneConfig[]> {
return;
}
/**
* Asynchronously creates or opens an object of a Cloud DB zone which represents a unique data storage zone.
* @param config The callback to execute when the Promise is rejected.
* @param isAllowToCreate Specifies whether to allow Cloud DB zone object creation.
* @returns Cloud DB zone object. Developers can use this object to add, delete, modify, query, and listen on data.
*/
openCloudDBZone2(config: CloudDBZoneConfig, isAllowToCreate: boolean): Promise<AGCCloudDBZone> {
return;
}
/**
* Asynchronously creates or opens an object of a Cloud DB zone which represents a unique data storage zone.
* @param config The callback to execute when the Promise is rejected.
* @param isAllowToCreate Specifies whether to allow Cloud DB zone object creation.
* @returns Cloud DB zone object. Developers can use this object to add, delete, modify, query, and listen on data.
*/
openCloudDBZone(config: CloudDBZoneConfig, isAllowToCreate: boolean): Promise<AGCCloudDBZone> {
return;
}
/**
* Listens to registered user key change events.
* @param callback Callback function to be called when listener is triggered.
*/
addEventListener(callback: (eventType: AGCCloudDBEventType) => void): Promise<void> {
return;
}
/**
* Registers a listener for data key changes.
* @param needFetchDataEncryptionKey Checks whether to update the data key.
* If the value is true: update is required, the value is false: update is not required.
* @param callback The callback to execute when the Promise is rejected.
*/
addDataEncryptionKeyListener(needFetchDataEncryptionKey: boolean, callback: (isDataKeyChange: boolean) => void): Promise<void> {
return;
}
/**
* Deletes the Cloud DB zone object that is no longer used on the device.
* @param zoneName The callback to execute when the Promise is rejected.
*/
deleteCloudDBZone(zoneName: string): Promise<void> {
return;
}
/**
* Closes the Cloud DB zone object opened on the device.
* @param id An id of Cloud DB zone to be closed.
*/
closeCloudDBZone(id: string): Promise<void> {
return;
}
/**
* Enables data synchronization between the device and cloud.
* @param zoneName Cloud DB zone name
*/
enableNetwork(zoneName: string): Promise<void> {
return;
}
/**
* Disables data synchronization between the device and cloud.
* @param zoneName Cloud DB zone name
*/
disableNetwork(zoneName: string): Promise<void> {
return;
}
/**
* A data key used to encrypt user data, which is automatically generated by the system.
* To prevent from being cracked when using one key for a long time,
* you can call this method to update the data key.
* @returns True if operation successful, otherwise false.
*/
updateDataEncryptionKey(): Promise<boolean> {
return;
}
/**
* Sets or modifies the user password for Cloud DB full encryption.
* @param userKey User password.
* @param userReKey New user password.
* @returns True if operation successful, otherwise false.
*/
setUserKey(userKey: string, userReKey: string): Promise<boolean> {
return;
}
}
export class AGCCloudDBQuery {
private readonly query: QueryObject;
private constructor(className: string) {
this.query = {
className: className,
queryElements: [],
}
}
/**
* Obtains a AGCCloudDBQuery object and specifies the object type to be queried.
* The AGCCloudDBQuery object does not provide any construction method.
* You can obtain an object type instance only by using the where method.
* @param className Cloud DB zone name
*/
static where(className: string) {
return new AGCCloudDBQuery(className);
}
/**
* Adds a query condition where the value of a field in an entity class
* is equal to a specified value.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
equalTo(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.EQUAL_TO,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field in an entity class
* is not equal to a specified value.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
notEqualTo(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.NOT_EQUAL_TO,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field in an entity class
* is greater than a specified value.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
greaterThan(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.GREATER_THAN,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field in an entity class
* is greater than or equal to a specified value.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
greaterThanOrEqualTo(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.GREATER_THAN_OR_EQUAL_TO,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field in an entity class
* is less than a specified value.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
lessThan(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.LESS_THAN,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field in an entity class
* is less than or equal to a specified value.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
lessThanOrEqualTo(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.LESS_THAN_OR_EQUAL_TO,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field in an entity class
* is contained in a specified array.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
in(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.IN,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field of the string or
* text type in an entity class starts with a specified substring.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
beginsWith(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.BEGINS_WITH,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field of the string or
* text type in an entity class ends with a specified substring.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
endsWith(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.ENDS_WITH,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where the value of a field of the string
* or text type in an entity class contains a specified substring.
* @param fieldName Name of a field in an entity class.
* @param value Specified value of the selected field.
* The data type of the value must be the same as that of the selected field value.
* Otherwise, an exception is thrown.
*/
contains(fieldName: string, value: any) {
this.query.queryElements.push({
operation: QueryOperation.CONTAINS,
fieldName: fieldName,
value: value,
})
return this
}
/**
* Adds a query condition where a field in an entity class is null.
* @param fieldName Name of a field in an entity class.
*/
isNull(fieldName: string) {
this.query.queryElements.push({
operation: QueryOperation.IS_NULL,
fieldName: fieldName,
})
return this
}
/**
* Adds a query condition where a field in an entity class is not null.
* @param fieldName Name of a field in an entity class.
*/
isNotNull(fieldName: string) {
this.query.queryElements.push({
operation: QueryOperation.IS_NOT_NULL,
fieldName: fieldName,
})
return this
}
/**
* Sorts the query results in ascending order by a specified field.
* @param fieldName Name of a field in an entity class.
*/
orderByAsc(fieldName: string) {
this.query.queryElements.push({
operation: QueryOperation.ORDER_BY_ASC,
fieldName: fieldName,
})
return this
}
/**
* Sorts the query results in descending order by a specified field.
* @param fieldName Name of a field in an entity class.
*/
orderByDesc(fieldName: string) {
this.query.queryElements.push({
operation: QueryOperation.ORDER_BY_DESC,
fieldName: fieldName,
})
return this
}
/**
* Add query conditions to specify the number of
* data records in the returned query result set.
* @param count Maximum number of data records that can be obtained.
* @param offset Specifies the start position of data records.
* You can specify whether to set the offset position based on the actual requirements.
*/
limit(count: any, offset?: number) {
if (offset) {
this.query.queryElements.push({
operation: QueryOperation.LIMIT_CONDITION,
value: count,
offset: offset
})
return this
} else {
this.query.queryElements.push({
operation: QueryOperation.LIMIT_CONDITION,
value: count,
})
return this
}
}
/**
* Set the start position of the data to be queried, and return to
* the data records with the corresponding records at the start position included.
* @param object The object corresponding to the start position.
*/
startAt(object: any) {
this.query.queryElements.push({
operation: QueryOperation.START_AT,
value: object
})
return this
}
/**
* Set the start position of the data to be queried, and return to
* the data records with the corresponding records at the start position not included.
* @param object The object corresponding to the start position.
*/
startAfter(object: any) {
this.query.queryElements.push({
operation: QueryOperation.START_AFTER,
value: object
})
return this
}
/**
* Set the end position of the data to be queried, and return to
* the data records with the corresponding records at the end position included.
* @param object The object corresponding to the start position.
*/
endAt(object: any) {
this.query.queryElements.push({
operation: QueryOperation.END_AT,
value: object
})
return this
}
/**
* Set the end position of the data to be queried, and return to
* the data records with the corresponding records at the end position not included.
* @param object The object corresponding to the start position.
*/
endBefore(object: any) {
this.query.queryElements.push({
operation: QueryOperation.END_BEFORE,
value: object
})
return this
}
/**
* This method is used to build the query.
* This method has to be called after query chain has been completed.
*/
build() {
Object.freeze(this);
return this.query;
}
}
export class AGCCloudDBTransaction {
private readonly transactions: Transaction[];
private constructor() {
this.transactions = [];
}
/**
* Initializes an AGCCloudDBTransaction object.
* @param zoneName Cloud DB zone name
*/
static function() {
return new AGCCloudDBTransaction();
}
/**
* Writes a group of objects to the Cloud DB zone in a transaction in batches.
* @param className A class object that represents the object type entity class defined by the developer.
* @param data A list, represents the data to be written.
*/
executeUpsert(className: string, data: any[]) {
this.transactions.push({
operation: Operation.UPSERT,
className: className,
data: data
})
return this
}
/**
* Deletes a group of objects from the Cloud DB zone in a transaction in batches.
* @param className A class object that represents the object type entity class defined by the developer.
* @param data A list, represents the data to be deleted.
*/
executeDelete(className: string, data: any[]) {
this.transactions.push({
operation: Operation.DELETE,
className: className,
data: data
})
return this
}
/**
* Queries a set of objects that meet specific conditions from the Cloud DB zone on the cloud in a transaction.
* @param className A class object that represents the object type entity class defined by the developer.
* @param data A QueryObject object, which indicates the query condition.
*/
executeQuery(className: string, data: QueryObject) {
this.transactions.push({
operation: Operation.QUERY,
className: className,
data: data
})
return this
}
/**
* This method is used to build the Transaction list.
* @returns Transaction list.
*/
build() {
Object.freeze(this);
return this.transactions;
}
}
export class AGCCloudDBZone {
private readonly _id: string;
private constructor(id: string) {
this._id = id;
}
/**
* Obtains the id of current Cloud DB zone instance.
*/
get id(): string {
return this._id;
}
/**
* Obtains the current configuration information of Cloud DB zone.
* @returns A CloudDBZoneConfig object.
*/
getCloudDBZoneConfig(): Promise<CloudDBZoneConfig> {
return;
}
/**
* Writes a group of objects to the current Cloud DB zone in batches.
* @param className Name of the object type.
* @param cloudDBZoneObjectArray Object datas to be written.
* @returns Number of objects that are successfully written.
*/
executeUpsert(className: string, cloudDBZoneObjectArray: any[]): Promise<number> {
return;
}
/**
* Deletes a group of Cloud DB zone objects whose primary key values are the same as those of the input object list in batches.
* @param className Name of the object type.
* @param cloudDBZoneObjectArray Object datas to be deleted.
* @returns Number of objects that are successfully deleted.
*/
executeDelete(className: string, cloudDBZoneObjectArray: any[]): Promise<number> {
return;
}
/**
* Queries objects that meet specified conditions in Cloud DB zone and encapsulates the query result set into a CloudDBZoneSnapshot.
* @param queryObject A QueryObject object, which indicates the query condition.
* @param queryPolicy Query policy, which specifies the data source to be queried.
* @returns CloudDBZoneSnapshot object that encapsulates the query result set.
*/
executeQuery(queryObject: QueryObject, queryPolicy: CloudDBZoneQueryPolicy): Promise<CloudDBZoneSnapshot> {
return;
}
/**
* Queries objects that meet specified conditions in Cloud DB zone and returns the average value of specified fields.
* @param queryObject A QueryObject object, which indicates the query condition.
* @param fieldName Specifies the name of the fields whose average value needs to be calculated in the query object.
* @param queryPolicy Query policy, which specifies the data source to be queried.
* @returns The avarage value.
*/
executeAverageQuery(queryObject: QueryObject, fieldName: string, queryPolicy: CloudDBZoneQueryPolicy): Promise<string> {
return;
}
/**
* Queries objects that meet specific conditions and returns the sum of data record values of specified fields in the Cloud DB zone.
* @param queryObject A QueryObject object, which indicates the query condition.
* @param fieldName Specifies the name of the fields whose sum value needs to be calculated in the query object.
* @param queryPolicy Query policy, which specifies the data source to be queried.
* @returns The sum result.
*/
executeSumQuery(queryObject: QueryObject, fieldName: string, queryPolicy: CloudDBZoneQueryPolicy): Promise<string> {
return;
}
/**
* Queries the objects that meet specific conditions and returns the maximum value of the data records in the specified fields in the Cloud DB zone.
* @param queryObject A QueryObject object, which indicates the query condition.
* @param fieldName Specifies the name of the fields whose max value needs to be calculated in the query object.
* @param queryPolicy Query policy, which specifies the data source to be queried.
* @returns The maximum value.
*/
executeMaximumQuery(queryObject: QueryObject, fieldName: string, queryPolicy: CloudDBZoneQueryPolicy): Promise<string> {
return;
}
/**
* Queries the objects that meet specific conditions in the Cloud DB zone and returns the minimum value of the data records in the designated fields.
* @param queryObject A QueryObject object, which indicates the query condition.
* @param fieldName Specifies the name of the fields whose min value needs to be calculated in the query object.
* @param queryPolicy Query policy, which specifies the data source to be queried.
* @returns The minimum value.
*/
executeMinimalQuery(queryObject: QueryObject, fieldName: string, queryPolicy: CloudDBZoneQueryPolicy): Promise<string> {
return;
}
/**
* Queries the objects that meet specific conditions in the Cloud DB zone and returns the number of data records of the specified fields.
* @param queryObject A QueryObject object, which indicates the query condition.
* @param fieldName Specifies the name of the fields whose count value needs to be calculated in the query object.
* @param queryPolicy Query policy, which specifies the data source to be queried.
* @returns The number of data result.
*/
executeCountQuery(queryObject: QueryObject, fieldName: string, queryPolicy: CloudDBZoneQueryPolicy): Promise<string> {
return;
}
/**
* Queries all object data that meets specified conditions in Cloud DB but has not been synchronized to the cloud, and encapsulates the query result set into a CloudDBZoneSnapshot.
* @param queryObject A QueryObject object, which indicates the query condition.
* @returns CloudDBZoneSnapshot object that encapsulates the query result set.
*/
executeQueryUnsynced(queryObject: QueryObject): Promise<CloudDBZoneSnapshot> {
return;
}
/**
* Executes a specified transaction operation.
* @param transactions You can encapsulate a group of operations in the array,
* and then use this interface to implement the functions of adding, deleting, modifying,
* and querying operations in a transaction.
* @returns An object, which encapsulates the execution status, result,
* and exception information of runTransaction().
* For example, you can call the isSuccessful property based on this
* object to check whether the query operation is successful.
*/
runTransaction(transactions: Transaction[]): Promise<TransactionResult> {
return;
}
/**
* Registers a listener for a specified object on the device or cloud.
* When the data of the object that is listened on is changed, the registered onSnapshotUpdate event is triggered.
* @param queryObject A QueryObject object, which indicates the query condition.
* @param queryPolicy Query policy, which specifies the data source to be queried.
* @param callback Callback function to be called when listener is triggered.
* @returns A ListenerHandler object that remains valid until the remove() method
* of the ListenerHandler class is explicitly called by the developer.
*/
async subscribeSnapshot(queryObject: QueryObject, queryPolicy: CloudDBZoneQueryPolicy, callback: (cloudDBZoneSnapshot: CloudDBZoneSubscribeSnapshot) => void): Promise<ListenerHandler> {
return;
}
}
export class ListenerHandler {
private readonly zoneId: string;
private readonly listenerId: string;
private constructor(zoneId: string, listenerId: string) {
this.zoneId = zoneId;
this.listenerId = listenerId;
}
/**
* Deregisters the snapshot listener.
*/
remove(): Promise<void> {
return;
}
}
/**
* Exception base interface of Cloud DB, which is inherited from AGCException.
* AGConnectCloudDBException provides methods for developers to obtain exception information,
* including error codes and detailed error information.
* @param message An error information.
* @param code An error code.
*/
export interface AGCCloudDBException {
message: string,
code: number
}
/**
* Transaction interface describes a transaction.
* The transaction provides the query, upsert, and delete methods to add,
* delete, modify, and query data in the Cloud DB zone on the cloud.
*/
export interface Transaction {
className: string,
operation: Operation,
data: any[] | QueryObject
}
/**
* This interface defines result object from the runTransaction() method.
* If the transaction array contains a query, than result of query will be
* returned on queryResult field, otherwise this field will be empty.
*/
export interface TransactionResult {
isSuccessful: boolean,
queryResult: {}
}
/**
* This interface is used to create a CloudDBZoneConfig object and configure
* Cloud DB zone information such as the synchronization property,
* access property, encrypted storage property, and data persistency property.
*/
export interface CloudDBZoneConfig {
cloudDBZoneName: string,
accessProperty: CloudDBZoneAccessProperty,
syncProperty: CloudDBZoneSyncProperty,
capacity?: number,
persistenceEnabled?: boolean,
isEncrypted: boolean,
key?: string,
reKey?: string
}
/**
* This interface defines object type which on the query will be executed and query conditions.
*/
export interface QueryObject {
className: string,
queryElements: QueryElement[]
}
/**
* This interface defines a single query condition.
*/
export interface QueryElement {
operation: QueryOperation,
fieldName?: string,
offset?: number,
value?: any
}
/**
* CloudDBZoneSnapshot interface is used to describe the queried snapshot data,
* including full object sets, added and modified object sets, and newly deleted object sets.
*/
export interface CloudDBZoneSnapshotData {
hasPendingWrites: boolean,
isFromCloud: boolean,
snapshotObjects: any[],
upsertedObjects: any[],
deletedObjects: any[]
}
/**
* CloudDBZoneSnapshot interface is used to including full object sets,
* added and modified object sets, and newly deleted object sets.
*/
export interface CloudDBZoneSnapshot extends CloudDBZoneSnapshotData {
}
/**
* CloudDBZoneSnapshot interface is used to describe the queried snapshot data.
*/
export interface CloudDBZoneSubscribeSnapshot {
id: string,
data?: CloudDBZoneSnapshotData,
error?: AGCCloudDBException
}
/**
* These enum values provides various predicates such as
* contains, equalTo, notEqualTo, and in to construct query conditions.
*/
export enum QueryOperation {
LIMIT_CONDITION = "limit",
START_AT = "startAt",
START_AFTER = "startAfter",
END_AT = "endAt",
END_BEFORE = "endBefore",
EQUAL_TO = "equalTo",
NOT_EQUAL_TO = "notEqualTo",
GREATER_THAN = "greaterThan",
GREATER_THAN_OR_EQUAL_TO = "greaterThanOrEqualTo",
LESS_THAN = "lessThan",
LESS_THAN_OR_EQUAL_TO = "lessThanOrEqualTo",
BEGINS_WITH = "beginsWith",
ENDS_WITH = "endsWith",
CONTAINS = "contains",
IS_NULL = "isNull",
IS_NOT_NULL = "isNotNull",
ORDER_BY_ASC = "orderByAsc",
ORDER_BY_DESC = "orderByDesc",
IN = "in"
}
/**
* These enum values provides which operation is going to be performed.
*/
export enum Operation {
UPSERT = "upsert",
DELETE = "delete",
QUERY = "query"
}
/**
* Synchronization property of the Cloud DB zone,
* which specifies whether to synchronize data of Cloud DB zone between
* the device and the cloud and the synchronization mode.
*/
export enum CloudDBZoneSyncProperty {
CLOUDDBZONE_LOCAL_ONLY = 0,
CLOUDDBZONE_CLOUD_CACHE = 1
}
/**
* Access property of the Cloud DB zone,
* which is used to define the security property when an application accesses Cloud DB zone.
*/
export enum CloudDBZoneAccessProperty {
CLOUDDBZONE_PUBLIC = 0
}
/**
* Query policy, which specifies the data source to be queried.
*/
export enum CloudDBZoneQueryPolicy {
POLICY_QUERY_FROM_LOCAL_ONLY = 1,
POLICY_QUERY_FROM_CLOUD_ONLY = 2,
POLICY_QUERY_DEFAULT = 3
}
/**
* Type of the change event.
*/
export enum AGCCloudDBEventType {
USER_KEY_CHANGED = 1
}