Introduction

This document describes Java APIs for writing serverless functions. This document uses class and table for the same concept.

Terminology

Trillo data layer is designed to be generic and independent of the type of database such as relational, document, graph, etc. Therefore, some of the API use generic terms from UML (Unified Modelling Language). In the context of particular database technology, a UML concept may not support all the features for simplicity. The following table describes the mapping of common terms (they may be used interchangeably).

Equivalent Terms	Concept
data source	It corresponds to a database. Trillo Workbench creates two default data sources common and vault. The corresponding database names are cloud_common and cloud_vault.
table, class, collection	Represents a structure with attributes. In a relational DB, it is a table.
column, attribute	A column of a table, an attribute of a class, a property of an object, etc.
association, relation	Relationship between tables or association between classes.
object, record	An instance of a class or a database record.

The following note is very important for the use of API.

When you create a class (using Trillo Workbench), it corresponds to a DB table. The table name is by default <class name>_tbl (i.e. the name of class suffixed by _tbl).

In APIs, the className is used as parameter.

For example, a finance data base may have name as, "Finance DB" or "Finance-DB". In Trillo Workbench it may be represented by data source, name 'FinanceDB" or "Finane_DB". Since data source name has to be a valid identifier, its name is different from database (which is not a valid identifier). A data source name may be same as its db name if the db name is a valid identifier.

Schema

If the database type is Microsoft SQL or Postgres, Trillo Workbench permits creation of schema under data source. Its logical-name is a valid identifier. Like data source, the logical-name may be different than name in the database.

Class

A class corresponds to a table. It is created under a data source (MySQL) or schema (Postgres, Microsoft SQL). Its logical-name is a valid identifier. Like data source, the logical-name may be different than name in the database.

Similarly, the term attribute is used for a column.

Fully Qualified Names

Trillo Workbench API uses name of data source, schema and class name in APIs. Since two different databases can have a table with the same name. The class name needs to be fully qualified name in APIs. A fully qualified class name is give by dot (.) notation as follows.

<appName>.<dsName>.<schemaName>.<className>

• appName: application name. For the default database of workbench, it is either "shared" or "auth". It is a logical folder to indicate the source application to which the database belongs.

• dsName: it is data source name.

• schemaName: DB schema (required in case of Postgres, MySQL).

• className: class name.

Example 1, shared.finance.financeSchema.Invoice: Invoice table of financeSchema of finance data source. (Postgres and Microsoft SQL).

Example 2, shared.common.AuditLog: AuditLog table of common data source (MySql)

The following 3 APIs can be used to extract application name, data source name, class name.

• BaseApi.app(qualifiedClassName): returns app name.

• BaseApi.ds(qualifiedClassName): returns data source / database name.

• BaseApi.cls(qualifiedClassName): return class name. A class name is always returned with the schema name with a dot inbetween. It means, cls("shared.financeDB.financeSchema.Invoice") will return "financeSchema.Invoice".

Default Databases

Trillo Workbench by default provisions Cloud SQL in Google Cloud (MySQL). It uses it for storing data, metadata. It can also used for the new tables. By default it creates the following two databases:

• cloud_vault: this is used as the user, tenant store. Its tables can be customized (while retaining a few important attributes as they are). You can't add new tables to this database using the workbench UI. This is referred to in the restful/SDK API by vault and in any SQL statement by cloud_vault.

• cloud_common: this is used for several system tables that can be customized (while retaining a few important attributes as they are). Any new table specified in the application is created inside this database. This is referred to in the API by common and in any SQL statement by cloud_common.

In addition, Trillo Workbench can connect any existing database. It can discover metadata of an external database by introspecting it.

Result Class

Several Trillo Workbench APIs return object of a class Result. The actual API response is wrapped inside it. It is useful since, in case of error its status can indicate failure and its other attributes have details of failure. There are a few APIs that return the response directly (without wrapping in Result).

1. data: this is the actual response of API. In case of success it contains a valid JSON (object or list).

2. _rtag: It is always set to _r_. Its presence can be used to infer that the response if of Result type.

public class Result {
  public static final String SUCCESS = "success";
  public static final String FAILED = "failed";
  public static final String UNKNOWN = "unknown";
  
  private String status = UNKNOWN; // see other values above
  private String message = null; // error or success message
  private Map<String, Object> props = null; // functions may use for more info
  private Object data = null; // In case of success it is the actual value of API
  private int code = 0; // HTTP code when applicable
  private String _rtag = "_r_"; // a flag indicating result object (useful for JS)
  private boolean failed = false; // true if failed else false
  private boolean success = true; // true if success else false
}

"failed" and "success" are redundant. They are provided for convenience.