QRunIO/qqq
2
0
Fork 0
mirror of https://github.com/Kingsrook/qqq.git synced 2025-07-17 20:50:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Checkpoint on qqq docs

Browse Source
This commit is contained in:
darin.kelkhoff
2023-12-15 18:41:30 -06:00
parent 9144754e74
commit d624a42dac
16 changed files with 1053 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
docs/Introduction.adoc
View File

@ -1,8 +1,176 @@
= Introduction
include::variables.adoc[]
QQQ is ...
QQQ is a Low-code Application Framework for Engineers.
Its purpose is to provide the basic structural elements of an application - things that every application needs - so that the engineers building an application on top of QQQ don't need to worry about those pieces, and can instead focus on the unique needs of the application that they are building.
- Framework
- Declarative
- Easy thing easy; Hard thing possible
- Customizable
== What makes QQQ special?
The scope of what QQQ provides is far-reaching, and most likely goes beyond what you may initially be thinking.
That is to say, QQQ includes code all the way from the backend of an application, through its middleware layer, and including its frontend.
For example, a common set of modules deployed in a QQQ application will provide:
* Backend RDBMS/Database connectivity and access.
* Frontend web UI (e.g., a React application)
* A java web server acting as middleware between the frontend web UI and the backend
That is to say - as an engineer deploying a QQQ application - you do not need to write a single line of code that is concerned with any of those things.
* You do not need to write code to connect to your database.
* You do not write any web UI code.
* You do not write any middleware code to tie together the frontend and backend.
Instead, QQQ includes *all* of these pieces.
QQQ knows how to connect to databases (and actually, several other kinds of backend systems - but ignore that for now).
Plus it knows how to do most of what an application needs to do with a database (single-record lookups, complex queries, joins, aggregates, bulk inserts, updates, deletes).
QQQ also knows how to present the data from a database - in table views, or single-record views, or exports, or reports or widgets.
And it knows how to present a powerful ad-hoc query interface to users, and how to show screens where users can create, update, and delete records.
It also provides the connective tissue (middleware) between those backend layers where data is stored, and frontend layers were users interact with data.
== What makes your application special?
I've said a lot about what does QQQ knows - but let's dig a little deeper.
What does QQQ know, and what does it not know?
Well - what it doesn't know is, it doesn't know the special or unique aspects of the application that you are building.
So, what makes your application unique?
Is your application unique because it needs to have screens where users can search for records in a table?
No!
QQQ assumes (as does the author of this document) that all applications (at least of the nature that QQQ supports) need what we call Query Screens.
So QQQ gives you a Query Screen for all of your tables - with zero code from you.
Is your application unique because you want users to be able to view, create, edit, and delete records from tables?
No!
QQQ assumes that all applications need these basic https://en.wikipedia.org/wiki/Create,_read,_update_and_delete[CRUD] capabilities.
So QQQ provides all of these UI screens - for view, create, edit, delete - along with the supporting middleware and backend code - all the way down to the SQL that selects & manages the data.
You get it all for free - zero code.
Is your application unique because you have a `fiz_bar` table, with 47 columns, and a `whoz_zat` table, with 42 columns of its own, that joins to `fiz_bar` on the `zizzy_ziz_id` field?
Yes!
OK - we found some of it - what makes your application unique is the data that you're working with.
Your tables - their fields - the connection info for your database.
QQQ doesn't know those details.
So - that's your first job as a QQQ application engineer - to describe your data to QQQ.
For the example above - you need to tell QQQ that you have a `fiz_bar` table, and that you have a `whoz_zat` table - and you need to tell QQQ what the fields or columns in thsoe tables are.
You can even tell QQQ how to join those tables (on that `zizzy_ziz_id` field).
And then that's it.
Once QQQ has this {link-table} meta data, it can then provide its Query screens, and full CRUD screens to your tables, in your database, with your fields.
And at the risk of repeating myself - you can do this (get a full Query & CRUD application) with zero lines of actual procedural code.
You only need to supply meta-data (which, at the time of this writing, is done in Java, but it's just creating objects - and in the future could be done in YAML files, for example).
== Beyond Basics
Going beyond the basic wiring as described above, QQQ also provides some of the more advanced elements needed in a modern data-driven web application, including:
* Authentication & Authorization
* ad-hoc Query engine for access to data tables
* Full CRUD (Create, Read, Update, Delete) capabilities
* Multistep custom workflows ("Processes" in QQQ parlance)
* Scheduled jobs
* Enterprise Service Bus
So what do we mean by all of this?
We said that basically every application needs, for example, Authentication & Authorization.
Login screens.
User & Role tables.
Permissions.
So, when it's time for you to build a new application for your _Big Tall Floor Lamp_ manufacturing business, do you need to start by writing a login screen?
And a Permissions scheme?
And throwing HTTP 401 errors?
And managing user-role relationships?
And then having a bug in the check permission logic on the _Light Bulb Inventory Edit_ screen, so Jim is always keying in bad quantities, even though he isn't supposed to have permission there?
No!
All of the (really important, even though application developers hate doing it) aspects of security - you don't need to write ANY code for dealing with that.
Just tell QQQ what Authentication provider you want to use (e.g., https://auth0.com/[Auth0]), and - to paraphrase the old https://www.youtube.com/watch?v=YHzM4avGrKI[iMac ad] - there's no step 2.
QQQ just does it.
''''
QQQ can provide this type of application using a variety and/or combination of backend data storage types.
And, whichever type of backend is used, QQQ gives a common interface (both user-facing and programmer-facing).
Backend types include:
* Relational Databases (RDBMS)
* File Systems
* Web APIs
* NoSQL/Document Databases (_Future_)
In addition, out-of-the-box, QQQ also goes beyond these basics, delivering:
* Bulk versions of all CRUD operations.
* Automatically generated JSON APIs.
* Auditing of data changes.
* End-user (e.g., non-engineer) customization via dynamic scripting capabilities
#todo say much more#
== QQQ Architecture
Like a house!
== Developing a QQQ Application
In developing an application with QQQ, engineers will generally have to define two types of code:
. *Meta Data* - This is the code that you use to tell QQQ the shape of your application - your unique Tables, Processes, Apps, Reports, Widgets, etc.
In general, this code is 100% declarative in nature (as opposed to procedural or functional).
That is to say - it has no logic.
It is just a definition of what exists - but it has no instructions, algorithms, or business logic.
* _In a future version of QQQ, we anticipate being able to define meta-data in a format such as YAML or JSON, or to even load it from a relational or document database.
This speaks to the fact that this "code" is not executable code - but rather is a simple declaration of (meta) data._
* A key function of QQQ then is to drive all of its layers of functionality - frontend UIs, middleware, and core backend actions (e.g., ORM operations) - based on this meta-data.
** For example:
... You define the meta-data for a table in your application - including its fields and their data types, as well as what backend system the table exists within.
... Then, the QQQ Frontend Material Dashboard UI's Query Screen loads that table's meta-data, and uses it to control the screen that is presented. Including:
**** The data grid shown on the screen will have columns for each field in the table.
**** The Filter button in the Query Screen will present a menu listing all fields from the table for the user to build ad-hoc queries against the table.
The data-types specified for the fields (in the meta-data) dictate what operators QQQ allows the user to use against fields (e.g., Strings offer "contains" vs Numbers offer "greater than").
**** Values for records from the table will be formatted for presentation based on the meta-data (such as a numeric field being shown with commas if it represents a quantity, or formatted as currency).
...
[start=2]
. *Meta Data* - declarative code - java object instances (potentially which could be read from `.yaml` files or other data sources in a future version of QQQ), which tell QQQ about the backend systems, tables, processes, reports, widgets, etc, that make up the application.
For example:
* Details about the database you are using, and how to connect to it.
* A database table's name, fields, their types, its keys, and basic business rules (required fields, read-only fields, field lengths).
* The description of web API - its URL and authentication mechanism.
* A table/path within a web API, and the fields returned in the JSON at that endpoint.
* The specification of a custom workflow (process), including what screens are needed, with input & output values, and references to the custom application code for processing the data.
* Details about a chart that summarizes data from a table for presentation as a dashboard widget.
// the section below is kinda dumb. like, it says you have to write application code, but
// then it just talks about how your app code gets for-free the same shit that QQQ does.
// it should instead say more about what your custom app code is or does.
// 2. *Application code* - to customize beyond what the framework does out-of-the box, and to provide application-specific business-logic.
// QQQ provides its programmers the same classes that it internally uses for record access, resulting in a unified application model.
// For example:
// * The same record-security model that is enforced for ad-hoc user queries through the frontend is applied to custom application code.
// ** So if your table has a security key defined, which says that users can only see Order records that are associated with the user's assigned Store, then QQQ's order Query Screen will enforce that rule.
// ** And at the same time - any custom processes ran by a user will have the same security applied to any queries that they run against the Order table.
// ** And any custom dashboard widgets - will only include data that the user is allowed to see.
// * Record audits are performed in custom code the same as they are in framework-driven actions.
// ** So if a custom process edits a record, details of the changed fields show up in the record's audit, the same as if the record was edited using the standard QQQ edit action.
// * Changed records are sent through the ESB automatically regardless of whether they are updated by custom application code or standard framework code.
// ** Meaning record automations are triggered regardless of how a record is created or edited - without you, as an application engineering, needing to send records through the bus.
// * The multi-threaded, paged producer/consumer pattern used in standard framework actions is how all custom application actions are also invoked.
// ** For example, the standard QQQ Bulk Edit action uses the same streamed-ETL process that custom application processes can use.
// Meaning your custom processes can take full advantage of the same complex frontend, middleware, and backend structural pieces, and you can just focus on your unique busines logic needs.
2. *Application code* - to customize beyond what the QQQ framework does out-of-the box, and to provide application-specific business-logic.
QQQ provides its programmers the same classes that it internally uses for record access, resulting in a unified application model.
For example:
== Lifecycle?
* define meta data
** enrichment
** validation
* start application
* for dev - hotSwap

59
docs/actions/QueryAction.adoc
View File

@ -1,34 +1,45 @@
== QueryAction
include::../variables.adoc[]
The `*QueryAction*` is the basic action that is used to get records from a {link-table}.
The `*QueryAction*` is the basic action that is used to get records from a {link-table}, generally according to a <<QQueryFilter,Filter>>.
In SQL/RDBMS terms, it is analogous to a `SELECT` statement, where 0 or more records may be found and returned.
=== Examples
==== Basic Form
[source,java]
----
QueryInput input = new QueryInput(qInstance);
input.setSession(session);
QueryInput input = new QueryInput();
input.setTableName("orders");
input.setFilter(new QQueryFilter()
.withCriteria(new QFilterCriteria("total", GREATER_THAN, new BigDecimal("3.50")))
.withOrderBy(new QFilterOrderBy("orderDate", false))
);
.withOrderBy(new QFilterOrderBy("orderDate", false)));
QueryOutput output = new QueryAction.execute(input);
List<QRecord> records = output.getRecords();
----
=== Details
`QueryAction`, in general, can be called in two different modes:
. The most common use-case case, and default, fetches all records synchronously, does any post-processing (as requested in the <<QueryInput>>), and returns all records as a list in the <<QueryOutput>>).
. The alternative use-case is meant for larger operations, where one wouldn't want all records matching a query in-memory.
For this scenario, a `RecordPipe` object can be passed in to the <<QueryInput>>.
This causes `QueryAction` to run its post-processing action on records as they are placed into the pipe, and to potentially block (per the pipe's settings).
This method of usage needs to be done on a separate thread from another thread which would be consuming records from the pipe.
QQQ's `AsyncRecordPipeLoop` class provides an implementation of doing such a dual-threaded job.
If the {link-table} has a `POST_QUERY_CUSTOMIZER` defined, then after records are fetched from the backend, that code is executed on the records before they leave the `QueryAction` (either through its `QueryOutput` or `RecordPipe`).
=== QueryInput
* `table` - *String, Required* - Name of the table being queried against.
* `filter` - *QQueryFilter object* - Specification for what records should be returned, based on *QFilterCriteria* objects, and how they should be sorted, based on *QFilterOrderBy* objects.
* `filter` - *<<QQueryFilter>> object* - Specification for what records should be returned, based on *<<QFilterCriteria>>* objects, and how they should be sorted, based on *<<QFilterOrderBy>>* objects.
If a `filter` is not given, then all rows in the table will be returned by the query.
* `skip` - *Integer* - Optional number of records to be skipped at the beginning of the result set.
e.g., for implementing pagination.
* `limit` - *Integer* - Optional maximum number of records to be returned by the query.
* `transaction` - *QBackendTransaction object* - Optional transaction object.
** Behavior for this object is backend-dependant.
In an RDBMS backend, this object is generally needed if you want your query to see data that may have been modified within the same transaction.
* `recordPipe` - *RecordPipe object* - Optional object that records are placed into, for asynchronous processing.
* `recordPipe` - *RecordPipe object* - Optional pipe object that records are placed into, for asynchronous processing.
** If a *recordPipe* is used, then records cannot be retrieved from the *QueryOutput*.
Rather, such records must be read from the pipe's `consumeAvailableRecords()` method.
** A *recordPipe* should only be used when a *QueryAction* is running in a separate Thread from the record's consumer.
@ -36,18 +47,21 @@ Rather, such records must be read from the pipe's `consumeAvailableRecords()` me
(e.g., to provide text translations in the generated records' `displayValues` map).
** For example, if running a query to present results to a user, this would generally need to be *true*.
But if running a query to provide data as part of a process, then this can generally be left as *false*.
* `shouldGenerateDisplayValues` - *boolean, default: false* - Controls whether if field level *displayFormats* should be used to populate the generated records' `displayValues` map.
* `shouldGenerateDisplayValues` - *boolean, default: false* - Controls whether field level *displayFormats* should be used to populate the generated records' `displayValues` map.
** For example, if running a query to present results to a user, this would generally need to be *true*.
But if running a query to provide data as part of a process, then this can generally be left as *false*.
* `queryJoins` - *List of QueryJoin objects* - Optional list of tables to be joined with the main *table* specified in the *QueryInput*.
* `shouldFetchHeavyFields` - *boolean, default: true* - Controls whether or not fields marked as `isHeavy` should be fetched & returned or not.
* `shouldOmitHiddenFields` - *boolean, default: true* - Controls whether or not fields marked as `isHidden` should be included in the result or not.
* `shouldMaskPassword` - *boolean, default: true* - Controls whether or not fields with `type` = `PASSWORD` should be masked, or if their actual values should be returned.
* `queryJoins` - *List of <<QueryJoin>> objects* - Optional list of tables to be joined with the main table being queried.
See QueryJoin below for further details.
==== QQueryFilter
A key component of *QueryInput*, a *QQueryFilter* defines both what records should be included in a query's results (e.g., an SQL `WHERE`), as well as how those results should be sorted (SQL `ORDER BY`).
A key component of *<<QueryInput>>*, a *QQueryFilter* defines both what records should be included in a query's results (e.g., an SQL `WHERE`), as well as how those results should be sorted (SQL `ORDER BY`).
* `criteria` - *List of QFilterCriteria* - Individual conditions or clauses to filter records.
* `criteria` - *List of <<QFilterCriteria>>* - Individual conditions or clauses to filter records.
They are combined using the *booleanOperator* specified in the *QQueryFilter*. See below for further details.
* `orderBys` - *List of QFilterOrderBy* - List of fields (and directions) to control the sorting of query results.
* `orderBys` - *List of <<QFilterOrderBy>>* - List of fields (and directions) to control the sorting of query results.
In general, multiple *orderBys* can be given (depending on backend implementations).
* `booleanOperator` - *Enum of AND, OR, default: AND* - Specifies the logical joining operator used among individual criteria.
* `subFilters` - *List of QQueryFilter* - To build arbitrarily complex queries, with nested boolean logic, 0 or more *subFilters* may be provided.
@ -69,7 +83,7 @@ In general, multiple *orderBys* can be given (depending on backend implementatio
)));
// which would generate the following WHERE clause in an RDBMS backend:
WHERE (first_name='James' AND last_name='Maes') OR (first_name='Darin' AND last_name='Kelkhoff')
// WHERE (first_name='James' AND last_name='Maes') OR (first_name='Darin' AND last_name='Kelkhoff')
----
===== QFilterCriteria
@ -79,19 +93,19 @@ In general, multiple *orderBys* can be given (depending on backend implementatio
* `operator` - *Enum of QCriteriaOperator, required* - Comparison operation to be applied to the field specified as *fieldName* and the *values* or *otherFieldName*.
** e.g., `EQUALS`, `NOT_IN`, `GREATER_THAN`, `BETWEEN`, `IS_BLANK`, etc.
* `values` - *List of values, conditional* - Provides the value(s) that the field is compared against.
The number of values (0, 1, 2, or more) be driven based on the *operator* being used.
The number of values (0, 1, 2, or more) required are based on the *operator* being used.
If an *otherFieldName* is given, and the *operator* expects 1 value, then *values* is ignored, and *otherFieldName* is used.
* `otherFieldName` - *String, conditional* - Specifies that the *fieldName* should be compared against another field in the records, rather than the values in the *values* property.
Only used for *operators* that expect 1 value (e.g., `EQUALS` or `LESS_THAN_OR_EQUALS` - not `IS_NOT_BLANK` or `IN`).
QFilterCriteria definition examples:
[source,java]
.QFilterCriteria definition examples:
----
// one-liners, via constructors that take (List<Serializable> values) or (Serializable... values) in 3rd position
new QFilterCriteria("id", IN, List.of(1, 2, 3))
// in-line, via constructors that take (List<Serializable> values) or (Serializable... values) as 3rd arg
new QFilterCriteria("id", IN, 1, 2, 3)
new QFilterCriteria("name", IS_BLANK)
new QFilterCriteria("orderNo", IN, orderNoList)
new QFilterCriteria("state", EQUALS, "MO");
new QFilterCriteria("state", EQUALS, "MO")
// long-form, with fluent setters
new QFilterCriteria()
@ -105,7 +119,7 @@ new QFilterCriteria()
.withOpeartor(QCriteriaOperator.EQUALS)
.withOtherFieldName("lastName");
// using otherFieldName to build a criterion that looks at two fields from join tables
// using otherFieldName to build a criterion that looks at two fields from two different join tables
new QFilterCriteria()
.withFieldName("billToCustomer.lastName")
.withOpeartor(QCriteriaOperator.NOT_EQUALS)
@ -118,9 +132,9 @@ new QFilterCriteria()
** Or, in the case of a query with *queryJoins*, a qualified name of a field from a join-table (where the qualifier would be the joined table's name or alias, followed by a dot)
* `isAscending` - *boolean, default: true* - Specify if the sort is ascending or descending.
QFilterCriteria definition examples:
[source,java]
.QFilterOrderBy definition examples:
----
// short-form, via constructors
new QFilterOrderBy("id") // isAscending defaults to true.
@ -129,7 +143,7 @@ new QFilterOrderBy("name", false)
// long-form, with fluent setters
new QFilterOrderBy()
.withFieldName("birthDate")
.withIsAscending(true);
.withIsAscending(false);
----
==== QueryJoin
@ -147,9 +161,8 @@ If given, must be used as the part before the dot in field name specifications t
If *true*, then the `QRecord` objects returned by this query will have values with corresponding to the (table-or-alias `.` field-name) form.
* `type` - *Enum of INNER, LEFT, RIGHT, FULL, default: INNER* - specifies the SQL-style type of join being performed.
QueryJoin definition examples:
[source,java]
.QueryJoin definition examples:
----
// selecting from an "orderLine" table - then join to its corresponding "order" table
queryInput.withTableName("orderLine");

25
docs/docinfo.html
View File

@ -1,27 +1,6 @@
<!--
~ QQQ - Low-code Application Framework for Engineers.
~ Copyright (C) 2021-2022. Kingsrook, LLC
~ 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
~ contact@kingsrook.com
~ https://github.com/Kingsrook/
~
~ This program is free software: you can redistribute it and/or modify
~ it under the terms of the GNU Affero General Public License as
~ published by the Free Software Foundation, either version 3 of the
~ License, or (at your option) any later version.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of
~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
~ GNU Affero General Public License for more details.
~
~ You should have received a copy of the GNU Affero General Public License
~ along with this program. If not, see <https://www.gnu.org/licenses/>.
-->
<style>
pre
.sect2 + .sect2
{
white-space: pre;
border-top: 1px solid #e7e7e9;
}
</style>

62
docs/index.adoc
View File

@ -1,17 +1,63 @@
= QQQ
:doctype: book
:doctype: article
:toc: left
:toclevels: 2
:source-highlighter: coderay
include::Introduction.adoc[leveloffset=+1]
== Meta Data
include::metaData/Tables.adoc[leveloffset=+1]
''''
include::metaData/Reports.adoc[leveloffset=+1]
// Organizational units
include::metaData/QInstance.adoc[leveloffset=+1]
include::metaData/Backends.adoc[leveloffset=+1]
include::metaData/Apps.adoc[leveloffset=+1]
== Actions
// Primary meta-data types
include::metaData/Tables.adoc[leveloffset=+1]
include::metaData/Processes.adoc[leveloffset=+1]
include::metaData/Widgets.adoc[leveloffset=+1]
// Helper meta-data types
include::metaData/Fields.adoc[leveloffset=+1]
include::metaData/PossibleValueSources.adoc[leveloffset=+1]
include::metaData/Joins.adoc[leveloffset=+1]
include::metaData/SecurtiyKeyTypes.adoc[leveloffset=+1]
include::metaData/Reports.adoc[leveloffset=+1]
include::metaData/Icons.adoc[leveloffset=+1]
include::metaData/PermissionRules.adoc[leveloffset=+1]
== Custom Application Code
include::misc/QContext.adoc[leveloffset=+1]
include::misc/QRecords.adoc[leveloffset=+1]
include::misc/QRecordEntities.adoc[leveloffset=+1]
include::misc/ProcessBackendSteps.adoc[leveloffset=+1]
=== Table Customizers
#todo#
== QQQ Actions
include::actions/QueryAction.adoc[leveloffset=+1]
''''
include::actions/RenderTemplateAction.adoc[leveloffset=+1]
''''
=== GetAction
include::actions/GetAction.adoc[leveloffset=+1]
=== CountAction
#todo#
=== AggregateAction
#todo#
=== InsertAction
include::actions/InsertAction.adoc[leveloffset=+1]
=== UpdateAction
#todo#
=== DeleteAction
#todo#
=== AuditAction
#todo#
// later... include::actions/RenderTemplateAction.adoc[leveloffset=+1]

92
docs/metaData/Apps.adoc Normal file
View File

@ -0,0 +1,92 @@
[#Apps]
== Apps
include::../variables.adoc[]
QQQ User Interfaces (e.g., Material Dashboard) generally organize their contents via *Apps*.
Apps are a lightweight construct in QQQ - basically just containers for other objects.
Specifically, Apps can contain:
* {link-widgets}
* {link-tables}
* {link-process}
* {link-reports}
* Other {link-apps} - to create a multi-tiered navigational hierarchy.
=== QAppMetaData
Apps are defined in a QQQ Instance in `*QAppMetaData*` objects. Apps must consist of either 1 or more {link-widgets}, or 1 or more *Sections*, which are expected to contain 1 or more {link-tables}, {link-processes}, or {link-reports}.
*QAppMetaData Properties:*
* `name` - *String, Required* - Unique name for the app within the QQQ Instance.
* `label` - *String* - User-facing label for the app, presented in User Interfaces.
Inferred from `name` if not set.
* `permissionRules` - *QPermissionRules* - Permissions to apply to the app. See {link-permissionRules} for details.
* `children` - *List of QAppChildMetaData* - Objects contained within the app. These can be {link-tables}, {link-processes}, {link-reports} or other {link-apps}.
** See the example below for some common patterns for how these child-meta data objects are added to an App.
* `parentAppName` - *String* - For an app which is a child of another app, the parent app's name is referenced in this field.
** Note that this is generally automatically set when the child is added to its parent, in the `addChild` method.
* `icon` - *QIcon* - An icon to display in a UI for the app. See {link-icons}.
* `widgets` - *List of String* - A list of names of {link-widgets} to include in the app.
* `sections` - *List of <<QAppSection>>* - A list of `QAppSection` objects, to create organizational subdivisions within the app.
** As shown in the example below, the method `withSectionOfChildren` can be used to fluently add a new `QAppSection`, along with its child objects, to both an app and a section all at once.
==== QAppSection
A `QAppSection` is an organizational subsection of a {link-app}.
* `name` - *String, Required* - Unique name for the section within its app.
* `label` - *String* - User-facing label for the section, presented in User Interfaces.
Inferred from `name` if not set.
* `icon` - *QIcon* - An icon to display in a UI for the section. See {link-icons}.
* `tables` - *List of String* - A list of names of {link-tables} to include in the section.
* `processes` - *List of String* - A list of names of {link-processes} to include in the section.
* `reports` - *List of String* - A list of names of {link-reports} to include in the section.
*Examples*
[source,java]
----
/*******************************************************************************
** Full example of constructing a QAppMetaData object.
*******************************************************************************/
public class ExampleAppMetaDataProducer extends MetaDataProducer<QAppMetaData>
{
/*******************************************************************************
** Produce the QAppMetaData
*******************************************************************************/
@Override
public QAppMetaData produce(QInstance qInstance) throws QException
{
return (new QAppMetaData()
.withName("sample")
.withLabel("My Sample App")
.withIcon(new QIcon().withName("thumb_up"))
.withWidgets(List.of(
UserWelcomeWidget.NAME,
SystemHealthLineChartWidget.NAME))
.withSectionOfChildren(new QAppSection().withName("peoplePlacesAndThings"),
qInstance.getTable(People.TABLE_NAME),
qInstance.getTable(Places.TABLE_NAME),
qInstance.getTable(Things.TABLE_NAME),
qInstance.getProcess(AssociatePeopleWithPlacesProcess.NAME))
.withSectionOfChildren(new QAppSection().withName("math").withLabel("Mathematics"),
qInstance.getProcess(ComputePiProcess.NAME),
qInstance.getReport(PrimeNumbersReport.NAME),
qInstance.getReport(PolygonReport.NAME)));
}
/*******************************************************************************
** Since this meta-data producer expects to find other meta-data objects in the
** QInstance, give it a sortOrder higher than the default (which we'll expect
** the other objects used).
*******************************************************************************/
@Override
public int getSortOrder()
{
return (Integer.MAX_VALUE);
}
}
----

150
docs/metaData/Backends.adoc Normal file
View File

@ -0,0 +1,150 @@
[#Backends]
== Backends
include::../variables.adoc[]
A key component of QQQ is its ability to connect to various backend data stores, while providing the same interfaces to those backends - both User Interfaces, and Programming Interfaces.
For example, out-of-the-box, QQQ can connect to:
* <<RDBMSBackendMetaData,RDBMS>> (Relational Database Management Systems, such as MySQL)
* File Systems (<<S3BackendMetaData,Amazon S3>> or <<FilesystemBackendMetaData,local disk>>)
* <<APIBackendMetaData,JSON Web APIs>> (_using a custom mapping class per-API backend_).
* In-Memory data stores
All {link-tables} in a QQQ instance must belong to a backend. As such, any instance using tables (which would be almost all instances) must define 1 or more backends.
=== QBackendMetaData
Backends are defined in a QQQ Instance in a `*QBackendMetaData*` object.
These objects will have some common attributes, but many different attributes based on the type of backend being used.
*QBackendMetaData Properties:*
* `name` - *String, Required* - Unique name for the backend within the QQQ Instance.
* `backendType` - *String, Required* - Identifier for the backend type being defined.
** This attribute is typically set in the constructor of a `QBackendMetaData` subclass, and as such does not need to be set when defining a backend meta data object.
* `enabledCapabilities` and `disabledCapability` - *Sets*, containing *Capability* enum values.
Basic rules that apply to all tables in the backend, describing what actions (such as Delete, or Count) are supported in the backend.
** By default, QQQ assumes that a backend supports _most_ capabilities, with one exception being `QUERY_STATS`.
** #TODO# fully explain rules here
* `usesVariants` - *Boolean, default false* - Control whether or not the backend supports the concept of "Variants".
** Supporting variants means that tables within the backend can exist in alternative "variants" of the backend.
For example, this might mean a sharded or multi-tenant database backend (perhaps a different server or database name per-client).
Or this might mean using more than one set of credentials for connecting to an API backend - each of those credential sets would be a "variant".
** A backend that uses variants requires additional properties to be set. #TODO complete variant documentation#
In a QQQ application, one will typically not create an instance of `QBackendMetaData` directly, but instead will create an instance of one of its subclasses, specific to the type of backend being used.
The currently available list of such classes are:
==== RDBMSBackendMetaData
The meta data required for working with tables in an RDBMS (relational database) backend are defined in an instance of the `*RDBMSBackendMetaData*` class.
*RDBMSBackendMetaData Properties:*
* `vendor` - *String, Required* - Database vendor. Currently supported values are: `aurora`, `mysql`, `h2`.
* `jdbcUrl` - *String, Optional* - Full JDBC URL for connecting to the database.
** If this property is provided, then following properties (which are the components of a JDBC URL) are ignored.
In other words, you can either provide the `jdbcUrl`, or the individual components that make it up.
* `hostName` - *String, Conditionally Required* - Hostname or ip address of the RDBMS server.
* `port` - *Integer, Conditionally Required* - Port used to connect to the RDBMS server.
* `databaseName` - *String, Conditionally Required* - Name of the database being connected to, within the RDBMS server.
* `username` - *String, Conditionally Required* - Username for authenticating in the database server.
* `password` - *String, Conditionally Required* - Password for authenticating in the database server.
*Examples*
[source,java]
----
/*******************************************************************************
** Full example of constructing an RDBMSBackendMetaData
*******************************************************************************/
public class ExampleDatabaseBackendMetaDataProducer extends MetaDataProducer<QBackendMetaData>
{
public static final String NAME = "rdbmsBackend";
/*******************************************************************************
** Produce the QBackendMetaData
*******************************************************************************/
@Override
public QBackendMetaData produce(QInstance qInstance)
{
///////////////////////////////////////////////////////////////////////
// read settings from either a .env file or the system's environment //
///////////////////////////////////////////////////////////////////////
QMetaDataVariableInterpreter interpreter = new QMetaDataVariableInterpreter();
String vendor = interpreter.interpret("${env.RDBMS_VENDOR}");
String hostname = interpreter.interpret("${env.RDBMS_HOSTNAME}");
String port = interpreter.interpret("${env.RDBMS_PORT}");
String databaseName = interpreter.interpret("${env.RDBMS_DATABASE_NAME}");
String username = interpreter.interpret("${env.RDBMS_USERNAME}");
String password = interpreter.interpret("${env.RDBMS_PASSWORD}");
return (new RDBMSBackendMetaData()
.withName(NAME)
.withVendor(vendor)
.withHostName(hostname)
.withPort(ValueUtils.getValueAsInteger(port))
.withDatabaseName(databaseName)
.withUsername(username)
.withPassword(password)
.withCapability(Capability.QUERY_STATS));
}
}
----
==== S3BackendMetaData
The meta data required for working with tables in an Amazon S3 backend are defined in an instance of the `*S3BackendMetaData*` class.
*S3BackendMetaData Properties:*
* `bucketName` - *String, Required* - Bucket name to connect to inside AWS S3.
* `accessKey` - *String, Required* - Access key for connecting to S3 inside AWS S3.
* `secretKey` - *String, Required* - Secret key for connecting to S3 inside AWS S3.
* `region` - *String, Required* - AWS region containing the Bucket in S3.
* `basePath` - *String, Required* - Base path to the files within the S3 bucket.
==== FilesystemBackendMetaData
The meta data required for working with tables in a (local) filesystem backend are defined in an instance of the `*FilesystemBackendMetaData*` class.
*FilesystemBackendMetaData Properties:*
* `basePath` - *String, Required* - Base path to the backend's files.
==== APIBackendMetaData
The meta data required for working with tables in a web API are defined in an instance of the `*APIBackendMetaData*` class.
QQQ provides a minimal, reasonable default implementation for working with web APIs, making assumptions such as using `POST` to insert records, and `GET` with a primary key in the URL to get a single record.
However, in our experience, almost all APIs are implemented differently enough, that a layer of custom code is required.
For example, query/search endpoints are almost always unique in how they take their search parameters, and how they wrap their output.
To deal with this, a QQQ API Backend can define a custom class in the `actionUtil` property of the backend meta-data, as a subclass of `BaseAPIActionUtil`, which ideally can override methods at the level where unique functionality is needed.
For example, an application need not define the full method for executing a Query against an API backend (which would need to make the HTTP request (actually multiple, to deal with pagination)).
Instead, one can just override the `buildQueryStringForGet` method, where the unique details of making the request are defined, and maybe the `jsonObjectToRecord` method, where records are mapped from the API's response to a QRecord.
#todo - full reference and examples for `BaseAPIActionUtil`#
*APIBackendMetaData Properties:*
* `baseUrl` - *String, Required* - Base URL for connecting to the API.
* `contentType` - *String, Required* - value of `Content-type` header included in all requests to the API.
* `actionUtil` - *QCodeReference, Required* - Reference to a class that extends `BaseAPIActionUtil`, where custom code for working with this API backend is defined.
* `customValues` - *Map of String → Serializable* - Application-defined additional name=value pairs that can
* `authorizationType` - *Enum, Required* - Specifies how authentication is provided for the API.
The value here, dictates which other authentication-related properties are required.
Possible values are:
** `API_KEY_HEADER` - Uses the `apiKey` property in an HTTP header named `API-Key`.
_In the future, when needed, QQQ will add a property, tentatively named `apiKeyHeaderName`, to allow customization of this header name._
** `API_TOKEN` - Uses the `apiKey` property in an `Authroization` header, as: `"Token " + apiKey`
** `BASIC_AUTH_API_KEY` - Uses the `apiKey` property, Base64-encoded, in an `Authroization` header, as `"Basic " + base64(apiKey)`
** `BASIC_AUTH_USERNAME_PASSWORD` - Combines the `username` and `password` properties, Base64-encoded, in an `Authroization` header, as `"Basic " + base64(username + ":" + password)`
** `OAUTH2` - Implements an OAuth2 client credentials token grant flow, using the properties `clientId` and `clientSecret`.
By default, the id & secret are sent as query-string parameters to the API's `oauth/token` endpoint.
Alternatively, if the meta-data has a `customValue` of `setCredentialsInHeader=true`, then the id & secret are posted in an `Authorization` header (base-64 encoded, and concatenated with `":"`).
** `API_KEY_QUERY_PARAM` - Uses the `apiKey` property as a query-string parameter, with its name taken from the `apiKeyQueryParamName` property.
** `CUSTOM` - Has a no-op implementation at the QQQ layer.
Assumes that an override of `protected void handleCustomAuthorization(HttpRequestBase request)` be implemented in the backend's `actionUtil` class.
This would be
* `apiKey` - *String, Conditional* - See `authorizationType` above for details.
* `clientId` - *String, Conditional* - See `authorizationType` above for details.
* `clientSecret` - *String, Conditional* - See `authorizationType` above for details.
* `username` - *String, Conditional* - See `authorizationType` above for details.
* `password` - *String, Conditional* - See `authorizationType` above for details.
* `apiKeyQueryParamName` - *String, Conditional* - See `authorizationType` above for details.

3
docs/metaData/Fields.adoc
View File

@ -1,4 +1,5 @@
== QQQ Fields
[#Fields]
== Fields
include::../variables.adoc[]
QQQ Fields define

17
docs/metaData/Joins.adoc Normal file
View File

@ -0,0 +1,17 @@
[#Joins]
== Joins
include::../variables.adoc[]
#TODO#
=== QJoinMetaData
Joins are defined in a QQQ Instance in a `*QJoinMetaData*` object.
#TODO#
*QJoinMetaData Properties:*
* `name` - *String, Required* - Unique name for the join within the QQQ Instance. #todo infererences or conventions?#
#TODO#

17
docs/metaData/PossibleValueSources.adoc Normal file
View File

@ -0,0 +1,17 @@
[#PossibleValueSources]
== Possible Value Sources
include::../variables.adoc[]
#TODO#
=== QPossibleValueSource
A Possible Value Source is defined in a QQQ Instance in a `*QPossibleValueSource*` object.
#TODO#
*QPossibleValueSource Properties:*
* `name` - *String, Required* - Unique name for the possible value source within the QQQ Instance.
#TODO#

216
docs/metaData/Processes.adoc Normal file
View File

@ -0,0 +1,216 @@
[#Processes]
== Processes
include::../variables.adoc[]
Besides {link-tables}, the other most common type of object in a QQQ Instance is the Process.
Processes are "custom" actions (e.g., defined by the application developers, rather than QQQ) that users and/or the system can execute against records.
Processes generally are made up of two types of sub-objects:
* *Screens* - i.e., User Interfaces (e.g., for gathering input and/or showing output).
* *BackendSteps* - Java classes (of type `BackendStep`) that execute the logic of the process.
=== QProcessMetaData
Processes are defined in a QQQ Instance in a `*QProcessMetaData*` object.
In addition to directly building a `QProcessMetaData` object setting its properties directly, there are a few common process patterns that provide *Builder* objects for ease-of-use.
See StreamedETLWithFrontendProcess below for a common example
*QProcessMetaData Properties:*
* `name` - *String, Required* - Unique name for the process within the QQQ Instance.
* `label` - *String* - User-facing label for the process, presented in User Interfaces.
Inferred from `name` if not set.
* `icon` - *QIcon* - Icon associated with this process in certain user interfaces.
See {link-icons}.
* `tableName` - *String* - Name of a {link-table} that the process is associated with in User Interfaces (e.g., Action menu).
* `isHidden` - *Boolean, default false* - Option to hide the process from all User Interfaces.
* `basepullConfiguration` - *<<BasepullConfiguration>>* - config for the common "Basepull" pattern, of identifying records with a timestamp greater than the last time the process was ran.
See below for details.
* `permissionRules` - *QPermissionRules object* - define the permission/access rules for the process.
See {link-permissionRules} for details.
* `steps` and `stepList` - *Map of String → <<QStepMetaData>>* and *List of QStepMetaData* - Defines the <<QFrontendStepMetaData,screens>> and <<QBackendStepMetaData,backend code>> that makes up the process.
** `stepList` is the list of steps in the order that they will by default be executed.
** `steps` is a map, including all steps from `stepList`, but which may also include steps which can used by the process if its backend steps make the decision to do so, at run-time.
** A process's steps are normally defined in one of two was:
*** 1) by a single call to `.withStepList(List<QStepMetaData>)`, which internally adds each step into the `steps` map.
*** 2) by multiple calls to `.addStep(QStepMetaData)`, which adds a step to both the `stepList` and `steps` map.
** If a process also needs optional steps, they should be added by a call to `.addOptionalStep(QStepMetaData)`, which only places them in the `steps` map.
* `schedule` - *<<QScheduleMetaData>>* - set up the process to run automatically on the specified schedule.
See below for details.
* `minInputRecords` - *Integer* - #not used...#
* `maxInputRecords` - *Integer* - #not used...#
#todo: supplementalMetaData (API)#
==== QStepMetaData
This is the base class for the two types of steps in a process - <<QFrontendStepMetaData,screens>> and <<QBackendStepMetaData,backend code>>.
There are some shared attributes of both of them, defined here.
*QStepMetaData Properties:*
* `name` - *String, Required* - Unique name for the step within the process.
* `label` - *String* - User-facing label for the step, presented in User Interfaces.
Inferred from `name` if not set.
* `stepType` - *String* - _Deprecated._
==== QFrontendStepMetaData
For processes with a user-interface, they must define one or more "screens" in the form of `QFrontendStepMetaData` objects.
*QFrontendStepMetaData Properties:*
* `components` - *List of <<QFrontendComponentMetaData>>* - a list of components to be rendered on the screen.
* `formFields` - *List of String* - list of field names used by the screen as form-inputs.
* `viewFields` - *List of String* - list of field names used by the screen as visible outputs.
* `recordListFields` - *List of String* - list of field names used by the screen in a record listing.
==== QFrontendComponentMetaData
A screen in a process may consist of multiple "components" - e.g., help text, and a form, and a list of records.
Each of these components are defined in a `QFrontendComponentMetaData`.
*QFrontendComponentMetaData Properties:*
* `type` - *enum, Required* - The type of component to display.
Each component type works with different keys in the `values` map.
Possible values for `type` are:
** `EDIT_FORM` - Displays a list of fields for editing, similar to a record edit screen.
Requires that `formFields` be populated in the step.
** `VIEW_FORM` - Displays a list of fields for viewing (not editing), similar to a record view screen.
Requires that `viewFields` be populated in the step.
** `HELP_TEXT` - Block of help text to be display on the screen.
Requires an entry in the component's `values` map named `"text"`.
** `HTML` - Block of custom HTML, generated by the process backend.
Expects a process value named `html`.
** `DOWNLOAD_FORM` - Presentation of a link to download a file generated by the process.
Expects process values named `downloadFileName` and `serverFilePath`.
** `GOOGLE_DRIVE_SELECT_FOLDER` - Special form that presents a UI from Google Drive, where the user can select a folder (e.g., as a target for uploading files in a subsequent backend step).
** `BULK_EDIT_FORM` - For use by the standard QQQ Bulk Edit process.
** `VALIDATION_REVIEW_SCREEN` - For use by the QQQ Streamed ETL With Frontend process family of processes.
Displays a component prompting the user to run full validation or to skip it, or, if full validation has been ran, then showing the results of that validation.
** `PROCESS_SUMMARY_RESULTS` - For use by the QQQ Streamed ETL With Frontend process family of processes.
Displays the summary results of running the process.
** `RECORD_LIST` - _Deprecated.
Showed a grid with a list of records as populated by the process._
* `values` - *Map of String → Serializable* - Key=value pairs, with different expectations based on the component's `type`.
See above for details.
==== QBackendStepMetaData
Process Backend Steps are where custom (at this time, Java, but in the future, potentially, from any supported language) code is executed, to provide the logic of the process.
QQQ comes with several common backend steps, such as for extracting lists of records, storing lists of records, etc.
*QBackendStepMetaData Properties:*
* `code` - *QCodeReference, Required* - Reference to the code to be executed for the step.
The referenced code must implement the `BackendStep` interface.
* `inputMetaData` - *QFunctionInputMetaData* - Definition of the data that the backend step expects and/or requires.
Sub-properties are:
** `fieldList` - *List of {link-fields}* - Optional list of fields used by the process step.
In general, a process does not _have to_ specify the fields that its steps use.
It can be used, however, for example, to cause a `defaultValue` to be applied to a field if it isn't specified in the process's input.
It can also be used to cause the process to throw an error, if a field is marked as `isRequired`, but a value is not present.
** `recordListMetaData` - *RecordListMetaData object* - _Not used at this time._
==== BasepullConfiguration
A "Basepull" process is a common pattern where an application needs to perform some action on all new (or updated) records from a particular data source.
To implement this pattern, one needs to store the timestamp of when the action runs, then query the source for records where a date-time field is after that timestamp.
QQQ helps facilitate this pattern by automatically retrieving and updating that timestamp field, and by building a default query filter based on that timestamp.
This is done by adding a `BasepullConfiguration` object to a process's meta-data.
*BasepullConfiguration Properties:*
* `tableName` - *String, Required* - Name of a {link-table} in the QQQ Instance where the basepull timestamps are stored.
* `keyField` - *String, Required* - Name of a {link-field} in the basepull table that stores a unique identifier for the process.
* `keyValue` - *String* - Optional value to be stored in the `keyField` of the basepull table as the unique identifier for the process.
If not set, then the process's `name` is used.
* `lastRunTimeFieldName` - *String, Required* - Name of a {link-field} in the basepull table that stores the last-run time for the process.
* `hoursBackForInitialTimestamp` - *Integer* - Optional number of hours to go back in time (from `now`) for the first time that the process is executed (i.e., if there is no timestamp stored in the basepull table).
* `timestampField` - *String, Required* - Name of a {link-field} in the table being queried against the last-run timestamp.
==== QScheduleMetaData
QQQ can automatically run processes using an internal scheduler, if they are configured with a `QScheduleMetaData` object.
*QScheduleMetaData Properties*
* `repeatSeconds` - *Integer, Conditional* - How often the process should be executed, in seconds.
* `repeatMillis` - *Integer, Conditional* - How often the process should be executed, in milliseconds.
Mutually exclusive with `repeatSeconds`.
* `initialDelaySeconds` - *Integer, Conditional* - How long between when the scheduler starts and the process should first run, in seconds.
* `initialDelayMillis` - *Integer, Conditional* - How long between when the scheduler starts and the process should first run, in milliseconds.
Mutually exclusive with `initialDelaySeconds`.
* `variantRunStrategory` - *enum, Conditional* - For processes than run against {link-tables} that use a {link-backend} with Variants enabled, this property controls if the various instances of the process should run in `PARALLEL` or in `SERIAL`.
* `variantBackend` - *enum, Conditional* - For processes than run against {link-tables} that use a {link-backend} with Variants enabled, this property specifies the name of the {link-backend}.
==== StreamedETLWithFrontendProcess
A common pattern for QQQ processes to exhibit is called the "Streamed ETL With Frontend" process pattern.
This pattern is to do an "Extract, Transform, Load" job on a potentially large set of records.
The records are Streamed through the process's steps, meaning, QQQ runs multiple threads - a producer, which is selecting records, and a consumer, which is processing records.
As such, in general, an unlimited number of records can be processed by a process, without worrying about exhausting server resources (e.g., OutOfMemory).
These processes also have a standard user-interface for displaying a summary of what the process will do (and has done), with a small number of records as a preview.
The goal of the summary is to give the user the big-picture of what the process will do (e.g., X records will be inserted; Y records will be updated), along with a small view of some details on the records that will be stored (e.g., on record A field B will be set to C).
This type of process uses 3 backend steps, and 2 frontend steps, as follows:
* *preview* (backend) - does just a little work (limited # of rows), to give the user a preview of what the final result will be - e.g., some data to seed the review screen.
* *review* (frontend) - a review screen, which after the preview step does not have a full process summary, but can generally tell the user how many records are input to the process, and can show a preview of a small number of the records.
* *validate* (backend) - optionally (per input on review screen), does like the preview step, but does it for all records from the extract step.
* *review* (frontend) - a second view of the review screen, if the validate step was executed.
Now that the full validation was performed, a full process summary can be shown, along with a some preview records.
* *execute* (backend) - processes all the rows - does all the work - stores data in the backend.
* *result* (frontend) - a result screen, showing a "past-tense" version of the process summary.
These backend steps are defined within QQQ, meaning they themselves do not execute any application-defined custom code.
Instead, these steps use the following secondary <<QBackendStepMetaData,backend steps>>:
* *Extract* - Fetch the rows to be processed.
Used by preview (but only for a limited number of rows), validate (without limit), and execute (without limit).
* *Transform* - Do whatever transformation is needed to the rows.
Done on preview, validate, and execute.
Always works with a page of records at a time.
Since it is called on the preview & validate steps, it should *NOT* ever store any data (unless it does a specific check to confirm that it is being used on an *execute* step).
* *Load* - Store the records into the backend, as appropriate.
Only called by the execute step.
Always works with a page of records at a time.
The meta-data for a `StreamedETLWithFrontendProcess` uses several input fields on its steps.
As such, it can be somewhat clumsy and error-prone to fully define a `StreamedETLWithFrontendProcess`.
To improve this programmer-interface, an inner `Builder` class exists within `StreamedETLWithFrontendProcess` (generated by a call to `StreamedETLWithFrontendProcess.processMetaDataBuilder()`).
*StreamedETLWithFrontendProcess.Builder methods:*
* `withName(String name) - Set the name for the process.
* `withLabel(String label) - Set the label for the process.
* `withIcon(QIcon icon)` - Set an {link-icon} to be display with the process in the UI.
* `withExtractStepClass(Class<? extends AbstractExtractStep>)` - Define the Extract step for the process.
If no special extraction logic is needed, `ExtractViaQuery.class` is often a reasonable default.
In other cases, `ExtractViaQuery` can be a reasonable class to extend for a custom extract step.
* `withTransformStepClass(Class<? extends AbstractTransformStep>)` - Define the Transform step for the process.
If no transformation logic is needed, `NoopTransformStep.class` can be used (though this is not very common).
* `withLoadStepClass(Class<? extends AbstractLoadStep>)` - Define the Load step for the process.
Several standard implementations exist, such as: `LoadViaInsertStep.class`, `LoadViaUpdateStep.class`, and `LoadViaDeleteStep.class`.
* `withTableName(String tableName)` - Specify the name of the {link-table} that the process should be associated with in the UI.
* `withSourceTable(String sourceTable)` - Specify the name of the {link-table} to be used as the source of records for the process.
* `withDestinationTable(String destinationTable)` - Specify the name of the {link-table} to be used as the destination for records from the process.
* `withSupportsFullValidation(Boolean supportsFullValidation)` - By default, all StreamedETLWithFrontendProcesses do allow the user to choose to run the full validation step.
However, in case cases it may not make sense to do so - so this method can be used to turn off that option.
* `withDoFullValidation(Boolean doFullValidation)` - By default, all StreamedETLWithFrontendProcesses will prompt the user if they want to run the full validation step or not.
However, in case cases you may want to enforce that the validation step always be executed.
Calling this method will remove the option from the user, and always run a full validation.
* `withTransactionLevelAutoCommit()`, `withTransactionLevelPage()`, and `withTransactionLevelProcess()` - Change the transaction-level used by the process.
By default, these processes are ran with a single transaction for all pages of their execute step.
But for some cases, doing page-level transactions can reduce long-transactions and locking within the system.
* `withPreviewMessage(String previewMessage)` - Sets the message shown on the validation review screen(s) above the preview records.
* `withReviewStepRecordFields(List<QFieldMetaData> fieldList)` -
* `withFields(List<QFieldMetaData> fieldList)` - Adds additional input fields to the preview step of the process.
* `withBasepullConfiguration(BasepullConfiguration basepullConfiguration)` - Add a <<BasepullConfiguration>> to the process.
* `withSchedule(QScheduleMetaData schedule)` - Add a <<QScheduleMetaData>> to the process.

3
docs/metaData/Reports.adoc
View File

@ -1,4 +1,5 @@
== QQQ Reports
[#Reports]
== Reports
include::../variables.adoc[]
QQQ can generate reports based on {link-tables} defined within a QQQ Instance.

17
docs/metaData/SecurtiyKeyTypes.adoc Normal file
View File

@ -0,0 +1,17 @@
[#SecurityKeyTypes]
== Security Key Types
include::../variables.adoc[]
#TODO#
=== QSecurityKeyType
A Security Key Type is defined in a QQQ Instance in a `*QSecurityKeyType*` object.
#TODO#
*QSecurityKeyType Properties:*
* `name` - *String, Required* - Unique name for the security key type within the QQQ Instance.
#TODO#

217
docs/metaData/Tables.adoc
View File

@ -1,15 +1,16 @@
== QQQ Tables
[#Tables]
== Tables
include::../variables.adoc[]
The core type of object in a QQQ Instance is the Table.
One of the most common types of object in a QQQ Instance is the Table.
In the most common use-case, a QQQ Table may be the in-app representation of a Database table.
That is, it is a collection of records (or rows) of data, each of which has a set of fields (or columns).
QQQ also allows other types of data sources ({link-backends}) to be used as tables, such as File systems, API's, Java enums or objects, etc.
QQQ also allows other types of data sources ({link-backends}) to be used as tables, such as File systems, API's, etc.
All of these backend types present the same interfaces (both user-interfaces, and application programming interfaces), regardless of their backend type.
=== QTableMetaData
Tables are defined in a QQQ Instance in a `*QTableMetaData*` object.
Tables are defined in a QQQ Instance in `*QTableMetaData*` objects.
All tables must reference a {link-backend}, a list of fields that define the shape of records in the table, and additional data to describe how to work with the table within its backend.
*QTableMetaData Properties:*
@ -19,14 +20,37 @@ All tables must reference a {link-backend}, a list of fields that define the sha
Inferred from `name` if not set.
* `backendName` - *String, Required* - Name of a {link-backend} in which this table's data is managed.
* `fields` - *Map of String → {link-field}, Required* - The columns of data that make up all records in this table.
* `primaryKeyField` - *String, Conditional* - Name of a {link-field} that serves as the primary key (e.g., unique identifier) for records in this table.
* `uniqueKeys` - *List of UniqueKey* - Definition of additional unique constraints (from an RDBMS point of view) from the table.
* `primaryKeyField` - *String, Conditional* - Name of a {link-field} that serves as the primary key (unique identifier) for records in this table.
** Whether a primary key field is required or not depends on the backend type that the table belongs to.
* `uniqueKeys` - *List of UniqueKey* - Definition of additional unique keys or constraints (from an RDBMS point of view) from the table.
e.g., sets of columns which must have unique values for each record in the table.
The properties of the `UniqueKey` object are:
** `fieldNames` - *List of String, Required* - List of field names from this table.
** `label` - *String* - Optional label to be shown to users with error messages (e.g., for violation of this unique key).
* `backendDetails` - *QTableBackendDetails or subclass* - Additional data to configure the table within its {link-backend}.
* `automationDetails` - *QTableAutomationDetails* - Configuration of automated jobs that run against records in the table, e.g., upon insert or update.
** For example, for an RDBMS-type backend, the name of the table within the database.
** vs. a FileSystem backend, this may be the sub-path where files for the table are stored.
** #todo - details on these#
* `automationDetails` - *<<QTableAutomationDetails>>* - Configuration of automated jobs that run against records in the table, e.g., upon insert or update.
* `customizers` - *Map of String → QCodeReference* - References to custom code that are injected into standard table actions, that allow applications to customize certain parts of how the table works.
** Allowed values for keys in this map come from the `role` property of the `TableCustomizers` enum.
** Based on the key in this map, the `QCodeReference` used as the value must be of the appropriate java type, as specified in the `expectedType` property of the `TableCustomizers` enum value corresponding to the key.
** Example:
[source,java]
----
// in defining a QTableMetaData, a customizer can be added as:
.withCustomizer(TableCustomizers.PRE_INSERT_RECORD, new QCodeReference(MyPreInsCustomizer.class))
// where MyPreInsCustomizer would be defined as:
public class MyPreInsCustomizer extends AbstractPreInsertCustomizer
----
* `isHidden` - *Boolean, default false* - Option to hide the table from all User Interfaces.
* `parentAppName` - *String* - Name of a {link-app} that this table exists within.
* `icon` - *QIcon* - Icon associated with this table in certain user interfaces.
** This field generally does not need to be set on the table when it is defined, but rather, is set when the table gets placed within an app.
* `icon` - *QIcon* - Icon associated with this table in certain user interfaces. See {link-icons}.
* `recordLabelFormat` - *String* - Java Format String, used with `recordLabelFields` to produce a label shown for records from the table.
* `recordLabelFields` - *List of String, Conditional* - Used with `recordLabelFormat` to provide values for any format specifiers in the format string.
These strings must be field names within the table.
@ -42,8 +66,181 @@ new QFieldMetaData("birthDate", QFieldType.DATE)
.withRecordLabelFormat("%s (%s)")
.withRecordLabelFields(List.of("name", "birthDate"))
----
* `sections` - *List of QFieldSection* - Mechanism to organize fields within user interfaces, into logical sections.
* `sections` - *List of <<QFieldSection>>* - Mechanism to organize fields within user interfaces, into logical sections.
If any sections are present in the table meta data, then all fields in the table must be listed in exactly 1 section.
If no sections are defined, then instance enrichment will define default sections.
* `associatedScripts` - *List of AssociatedScript* - Definition of user-defined scripts that can be associated with records within the table.
* `associatedScripts` - *List of <<AssociatedScript>>* - Definition of user-defined scripts that can be associated with records within the table.
* `enabledCapabilities` and `disabledCapabilities` - *Set of Capability enum values* - Overrides from the backend level, for capabilities that this table does or does not possess.
* `associations` - *List of <<Association>>* - tables whose records can be managed along with records from this table. See below for details.
* `recordSecurityLocks` - *List of <<RecordSecurityLock>>* - locks that apply to records in the table - e.g., to control what users can or cannot access records in the table.
See RecordSecurityLock below for details.
* `permissionRules` - *QPermissionRules object* - define the permission/access rules for the table.
See {link-permissionRules} for details.
* `auditRules` - *<<QAuditRules>> object* - define the audit rules for the table.
See QAuditRules below for details.
* `cacheOf` - *<<CacheOf>> object* - specify that this table serves as a "cache of" another table.
See CacheOf object below for details.
* `exposedJoins` - *List of <<ExposedJoin>> objects* - optional list of joined tables that are to be exposed in User Interfaces.
See ExposedJoin object below for details.
#todo: supplementalMetaData (API)#
==== QFieldSection
When users view records from a QQQ Table in a UI, fields are organized on the screen based on the `QFieldSection` objects in the table's meta-data.
*QFieldSection Properties:*
* `name` - *String, Required* - unique identifier for the section within its table.
* `label` - *String* - User-facing label for the section, presented in User Interfaces.
Inferred from `name` if not set.
* `tier` - *enum* - importance of the fields in section for the table.
Different tiers may be presented differently in UI's.
Only a single `T1` section is allowed per-table. Possible values are: `T1`, `T2`, and `T3`.
* `icon` - *QIcon* - Icon associated with this section in certain user interfaces. See {link-icons}.
* `isHidden` - *Boolean, default false* - Option to hide the table from all User Interfaces.
* `gridColumns` - *Integer* - Option to specify how many columns in a grid layout the section should use.
For the Material-Dashboard frontend, this is a grid of 12.
* `fieldNames` - *List of String, Conditional* - List of names of {link-fields} from this table to be included in this section.
* `widgetName` - *String, Conditional* - Name of a {link-widget} to be displayed in this section.
** Note that exactly one of `fieldNames` or `widgetName` must be used.
==== QTableAutomationDetails
Records in QQQ can have application-defined custom actions automatically asynchronously executed against them after they are inserted or updated.
The configuration to enable this functionality is assigned to a table in a `QTableAutomationDetails` object.
*QTableAutomationDetails Properties:*
* `statusTracking` - *AutomationStatusTracking object, Required* - define how QQQ should keep track, per record, its status (e.g., pending-insert-automations, running-update-automations, etc).
Properties of `AutomationStatusTracking` object are:
** `type` - *enum, Required* - what type of tracking is used for the table.
Possible values are:
*** `FIELD_IN_TABLE` - specifies that the table has a field which stores an `AutomationStatus` id.
*** _Additional types may be defined in the future, such as ONE_TO_ONE_TABLE or SHARED_TABLE._
** `fieldName` - *String, Conditional* - for `type=FIELD_IN_TABLE`, this property specifies the name of the {link-field} in the table that stores the `AutomationStatus` id.
* `providerName` - *String, Required* - name of an Automation Provider within the QQQ Instance, which is responsible for running the automations on this table.
* `overrideBatchSize` - *Integer* - optional control over how many records from the table are processed in a single batch/page.
For tables with "slow" actions (e.g., one that may need to make an API call per-record), using a smaller batch size (say, 50) may be required to avoid timeout errors.
* `actions` - *List of TableAutomationAction* - list of the actions to perform on new and updated records in the table.
Properties are:
** `name` - *String, Required* - unique identifier for the action within its table.
** `triggerEvent` - *enum, Required* - indicate which event type (`POST_INSERT`, `POST_UPDATE`, or `PRE_DELETE` (which is not yet implemented)) the action applies to.
** `priority` - *Integer, default 500* - mechanism to control the order in which actions on a table are executed, if there are more than one.
Actions with a smaller value for `priority` are executed first. Ties are broken in an undefined manner.
** `filter` - *QQueryFilter* - optional filter that gets applied to records when they match the `triggerEvent`, to control which records have the action ran against them.
** `includeRecordAssociations` - *Boolean, default false* - for tables that have associations, control whether or not a record's associated records are loaded when records are fetched and passed into the action's custom code.
** `values` - *Map of String → Serializable* - optional application-defined map of name=value pairs that can be passed into the action's custom code.
** `processName` - *String, Conditional* - name of a {link-processes} in the QQQ Instance which is executed as the custom-code of the action.
** `codeReference` - *QCodeReference, Conditional* - reference to a class that extends `RecordAutomationHandler`, to be executed as the custom-code of the action.
*** Note, exactly one of `processName` or `codeReference` must be provided.
==== Association
An `Association` is a way to define a relationship between tables, that facilitates, for example, a parent record having a list of its child records included in it when it is returned from a Query.
Similarly, associated records can automatically be inserted/updated/deleted if they are included in a parent record when it is stored.
*Association Properties:*
* `name` - *String, Required* - unique name for the association within this table.
Used as the key in the `associatedRecords` map within `QRecord` objects for this table.
* `associatedTableName` - *String, Required* - name of a {link-table}, which is the associated table.
* `joinName` - *String, Required* - name of a {link-join} in the instance, which defines how the tables are joined.
==== RecordSecurityLock
A `RecordSecurityLock` is the mechanism through which users can be allowed or denied access to read and/or write records, based on values in the record, and values in the user's session.
Record security locks must correspond to a {link-securityKeyType}.
For example:
* An instance may have a security key type called `clientId`.
* Users may have 1 or more `clientId` values in their Session, or, they may have an "All Clients" key in their session (e.g., for internal/admin users).
* For some tables, it may be required to limit visibility to records based on a user's `clientId` key.
To do this. a *RecordSecurityLock* would be applied to the table, specifying the `clientId` field corresponds to the `clientId` security key.
* With these settings in place, QQQ will prevent users from viewing records from this table that do not have a matching key, and will similarly prevent users from writing records with an invalid key value.
** For example, in an RDBMS backend, all `SELECT` statements generated against such a table will have an implicit filter, such as `AND client_id = ?` based on the user's security key values.
*RecordSecurityLock Properties:*
* `securityKeyType` - *String, Required* - name of a {link-securityKeyType} in the Instance.
* `fieldName` - *String, Required* - name of a {link-field} in this table (or a joined table, if `joinNameChain` is set), where the value for the lock is stored.
* `joinNameChain` - *List of String* - if the lock value is not stored in this table, but rather comes from a joined table, then this property defines the path of joins from this table to the table with the lock field.
* `nullValueBehavior` - *enum, default: DENY* - control how records with a `null` value in the lock field should behave.
Possible values are:
** `DENY` - deny all users access to a record with a `null` value in the lock field (unless the user has an all-access key - see {link-securityKeyType})
** `ALLOW` - allow all users access to a record with a `null` value in the lock field.
** `ALLOW_WRITE_ONLY` - allow all users to write records with `null` in the lock field, but deny reads on records with `null` in the lock field (also excepted by all-access keys).
* `lockScope` - *enum, default: READ_AND_WRITE* - control what types of operations the lock applies to.
Possible values are:
** `READ_AND_WRITE` - control both reading and writing records based on the user having an appropriate security key.
** `WRITE` - allow all users to read the record, but limit writes to users with an appropriate security key.
==== QAuditRules
The audit rules on a table define the level of detail that is automatically stored in the audit table (if any) for DML actions (Insert, Update, Delete).
*QAuditRules Properties:*
* `auditLevel` - *enum, Required* - level of details that are audited.
Possible values are:
** `NONE` - no automatic audits are stored for the table.
** `RECORD` - only record-level audits are stored for the table (e.g., a message such as "record was edited", but without field-level details)
** `FIELD` - full field-level audits are stored (e.g., including all old & new values as audit details).
==== CacheOf
One QQQ Table can be defined as a "cache of" another QQQ Table by assigning a `CacheOf` object to the table which will function as the cache.
_Note, at this time, only limited use-cases are supported._
*CacheOf Properties:*
* `sourceTable` - *String, Required* - name of the other QQQ Table that is the source of data in this cache.
* `expirationSeconds` - *Integer* - optional number of seconds that a cached record is allowed to exist before it is considered expired, and must be re-fetched from the source table.
* `cachedDateFieldName` - *String, Conditional* - used with `expirationSeconds` to define the field in this table that is used for storing the timestamp for when the record was cached.
* `useCases` - *List of CacheUseCase* - what caching use-cases are to be implemented.
Properties of *CacheUseCase* are:
* `type` - *Enum, Required* - the type of use-case. Possible values are:
** `PRIMARY_KEY_TO_PRIMARY_KEY` - the primary key in the cache table equals the primary key in the source table.
** `UNIQUE_KEY_TO_PRIMARY_KEY` - a unique key in the cache table equals the primary key in the source table.
** `UNIQUE_KEY_TO_UNIQUE_KEY` - a unique key in the cache table equals a unique key in the source table.
* `cacheSourceMisses` - *Boolean, default false* - whether or not, if a "miss" happens in the source, if that fact gets cached.
* `cacheUniqueKey` - *UniqueKey, conditional* - define the fields in the cache table that define the unique key being used as the cache key.
* `sourceUniqueKey` - *UniqueKey, conditional* - define the fields in the source table that define the unique key being used as the cache key.
* `doCopySourcePrimaryKeyToCache` - *Boolean, default false* - specify whether or not the value of the primary key in the source table should be copied into records built in the cache table.
* `excludeRecordsMatching` - *List of QQueryFilter* - optional filter to be applied to records before they are cached.
If a record matches the filter, then it will not be cached.
==== ExposedJoin
Query screens in QQQ applications can potentially allow users to both display fields from joined tables, and filter by fields from joined tables, for any {link-join} explicitly defined as an *Exposed Join*.
_The reasoning why not all joins are implicitly exposed is that in many applications, the full join-graph can sometimes be overwhelming, surprisingly broad, and not necessarily practically useful.
This could be subject to change in the future, e.g., given a UI that allowed users to more explicitly add additional join tables..._
*ExposedJoin Properties:*
* `label` - *String, Required* - how the joined table should be presented in the UI.
* `joinTable` - *String, Required* - name of the QQQ Table that is joined to this table, and is being exposed as a join in the UI.
* `joinPath` - *List of String, Required* - names of 1 or more QQQ Joins that describe how to get from this table to the join table.
==== AssociatedScript
A QQQ Table can have end-user defined Script records associated with individual records in the table by use of the `associatedScripts` property of the table's meta-data.
The "types" of these scripts (e.g., how they are used in an application) are wholly application-designed & managed.
QQQ provides the mechanism for UI's to present and manage such scripts (e.g., the *Developer Mode* screen in the Material Dashboard), as well as an interface to load & execute such scripts `RunAssociatedScriptAction`).
*AssociatedScript Properties:*
* `fieldName` - *String, Required* - name of a {link-field} in the table which stores the id of the associated script record.
* `scriptTypeId` - *Serializable (typically Integer), Required* - primary key value from the `"scriptType"` table in the instance, to designate the type of the Script.
* `scriptTester` - *QCodeReference* - reference to a class which implements `TestScriptActionInterface`, that can be used by UI's for running an associated script to test it.

17
docs/metaData/Widgets.adoc Normal file
View File

@ -0,0 +1,17 @@
[#Widgets]
== Widgets
include::../variables.adoc[]
#TODO#
=== QWidgetMetaData
A Widget is defined in a QQQ Instance in a `*QWidgetMetaData*` object.
#TODO#
*QWidgetMetaData Properties:*
* `name` - *String, Required* - Unique name for the widget within the QQQ Instance.
#TODO#

38
docs/variables.adoc
View File

@ -1,13 +1,25 @@
ifdef::env-name[:relfilesuffix: .adoc]
:link-backend: link:Backends{relfilesuffix}[QQQ Backend]
:link-backends: link:Backends{relfilesuffix}[QQQ Backends]
:link-table: link:Tables{relfilesuffix}[QQQ Table]
:link-tables: link:Tables{relfilesuffix}[QQQ Tables]
:link-join: link:Joins{relfilesuffix}[QQQ Join]
:link-joins: link:Joins{relfilesuffix}[QQQ Joins]
:link-field: link:Fields{relfilesuffix}[QQQ Field]
:link-fields: link:Fields{relfilesuffix}[QQQ Fields]
:link-process: link:Processes{relfilesuffix}[QQQ Process]
:link-processes: link:Processes{relfilesuffix}[QQQ Processes]
:link-app: link:Apps{relfilesuffix}[QQQ App]
:link-apps: link:Apps{relfilesuffix}[QQQ Apps]
:link-app: <<Apps,QQQ App>>
:link-apps: <<Apps,QQQ Apps>>
:link-backend: <<Backends,QQQ Backend>>
:link-backends: <<Backends,QQQ Backends>>
:link-field: <<Fields,QQQ Field>>
:link-fields: <<Fields,QQQ Fields>>
:link-icon: <<Icons,Icon>>
:link-icons: <<Icons,Icons>>
:link-instance: <<QInstance,QInstance>>
:link-join: <<Joins,QQQ Join>>
:link-joins: <<Joins,QQQ Joins>>
:link-permissionRule: <<PermissionRules,Permission Rule>>
:link-permissionRules: <<PermissionRules,Permission Rules>>
:link-possibleValueSource: <<PossibleValueSources,QQQ Possible Value Source>>
:link-possibleValueSources: <<PossibleValueSources,QQQ Possible Value Sources>>
:link-process: <<Processes,QQQ Process>>
:link-processes: <<Processes,QQQ Processes>>
:link-report: <<Reports,QQQ Report>>
:link-reports: <<Reports,QQQ Reports>>
:link-securityKeyType: <<SecurityKeyTypes,Security Key Type>>
:link-securityKeyTypes: <<SecurityKeyTypes,Security Key Types>>
:link-table: <<Tables,QQQ Table>>
:link-tables: <<Tables,QQQ Tables>>
:link-widget: <<Widgets,QQQ Widget>>
:link-widgets: <<Widgets,QQQ Widgets>>

26
pom.xml
View File

@ -317,6 +317,32 @@ fi
</plugins>
</build>
<!-- mvn javadoc:aggregate -->
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.6.2</version>
<reportSets>
<reportSet>
<id>aggregate</id>
<inherited>false</inherited>
<reports>
<report>aggregate</report>
</reports>
</reportSet>
<reportSet>
<id>default</id>
<reports>
<report>javadoc</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
<repositories>
<repository>
<id>github-qqq-maven-registry</id>