Merge pull request #157 from Kingsrook/feature/support-CE-2257-ice-logic

Feature/support ce 2257 ice logic

Author: darinkelkhoff

docs/actions/QueryAction.adoc

@@ -155,31 +155,88 @@ new QFilterOrderBy()
 ----
 
 ==== QueryJoin
-* `joinTable` - *String, required* - Name of the table that is being joined in to the existing query.
+* `joinTable` - *String, required (though inferrable)* - Name of the table that is being joined in to the existing query.
 ** Will be inferred from *joinMetaData*, if *joinTable* is not set when *joinMetaData* gets set.
-* `baseTableOrAlias` - *String, required* - Name of a table (or an alias) already defined in the query, to which the *joinTable* will be joined.
+* `baseTableOrAlias` - *String, required (though inferrable)* - Name of a table (or an alias) already defined in the query, to which the *joinTable* will be joined.
 ** Will be inferred from *joinMetaData*, if *baseTableOrAlias* is not set when *joinMetaData* gets set (which will only use the leftTableName from the joinMetaData - never an alias).
 * `joinMetaData` - *QJoinMetaData object* - Optional specification of a {link-join} in the current QInstance.
 If not set, will be looked up at runtime based on *baseTableOrAlias* and *joinTable*.
 ** If set before *baseTableOrAlias* and *joinTable*, then they will be set based on the *leftTable* and *rightTable* in this object.
 * `alias` - *String* - Optional (unless multiple instances of the same table are being joined together, when it becomes required).
 Behavior based on SQL `FROM` clause aliases.
 If given, must be used as the part before the dot in field name specifications throughout the rest of the query input.
-* `select` - *boolean, default: false* - Specify whether fields from the *rightTable* should be selected by the query.
+* `select` - *boolean, default: false* - Specify whether fields from the *joinTable* should be selected by the query.
 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.
 
 [source,java]
-.QueryJoin definition examples:
+.Basic QueryJoin usage example:
 ----
-// selecting from an "orderLine" table - then join to its corresponding "order" table
+// selecting from an "orderLine" table, joined to its corresponding (parent) "order" table
 queryInput.withTableName("orderLine");
 queryInput.withQueryJoin(new QueryJoin("order").withSelect(true));
 ...
 queryOutput.getRecords().get(0).getValueBigDecimal("order.grandTotal");
+----
+
+[source,java]
+."V" shaped query - selecting from one parent table, and two children joined to it:
+----
+// TODO this needs verified for accuracy, though is a reasonable starting point as-is
+// selecting from an "order" table, and two children of it, orderLine and customer
+queryInput.withTableName("order");
+queryInput.withQueryJoin(new QueryJoin("orderLine").withSelect(true));
+queryInput.withQueryJoin(new QueryJoin("customer").withSelect(true));
+...
+QRecord joinedRecord = queryOutput.getRecords().get(0);
+joinedRecord.getValueString("orderNo");
+joinedRecord.getValueString("orderLine.sku");
+joinedRecord.getValueString("customer.firstName");
+----
+
+[source,java]
+."Chain" shaped query - selecting from one parent table, a child table, and a grandchild:
+----
+// TODO this needs verified for accuracy, though is a reasonable starting point as-is
+// selecting from an "order" table, with a "customer" child table, and an "address" sub-table
+queryInput.withTableName("order");
+queryInput.withQueryJoin(new QueryJoin("customer").withSelect(true));
+queryInput.withQueryJoin(new QueryJoin("address").withSelect(true));
+...
+QRecord joinedRecord = queryOutput.getRecords().get(0);
+joinedRecord.getValueString("orderNo");
+joinedRecord.getValueString("customer.firstName");
+joinedRecord.getValueString("address.street1");
+----
+
+[source,java]
+.QueryJoin usage example where two tables have two different joins between them:
+----
+// TODO this needs verified for accuracy, though is a reasonable starting point as-is
+// here there's a "fulfillmentPlan" table, which points at the order table (many-to-one,
+// as an order's plan can change over time, and we keep old plans around).
+// This join is named:  fulfillmentPlanJoinOrder
+//
+// The other join is "order" pointing at its current "fulfillmentPlan"
+// This join is named:  orderJoinCurrentFulfillmentPlan
+
+// to select an order along with its current fulfillment plan:
+queryInput.withTableName("order");
+queryInput.withQueryJoin(new QueryJoin(instance.getJoin("orderJoinCurrentFulfillmentPlan"))
+   .withSelect(true));
+
+// to select an order, and all fulfillment plans for an order (1 or more records):
+queryInput.withTableName("order");
+queryInput.withQueryJoin(new QueryJoin(instance.getJoin("fulfillmentPlanJoinOrder"))
+   .withSelect(true));
+----
 
+[source,java]
+.QueryJoin usage example for table with two joins to the same child table, selecting from both:
+----
 // given an "order" table with 2 foreign keys to a customer table (billToCustomerId and shipToCustomerId)
 // Note, we must supply the JoinMetaData to the QueryJoin, to drive what fields to join on in each case.
+// we must also define an alias for each of the QueryJoins
 queryInput.withTableName("order");
 queryInput.withQueryJoins(List.of(
    new QueryJoin(instance.getJoin("orderJoinShipToCustomer")
@@ -190,11 +247,18 @@ queryInput.withQueryJoins(List.of(
        .withSelect(true))));
 ...
 record.getValueString("billToCustomer.firstName")
-   + " placed an order for "
+   + " paid for an order, to be sent to "
    + record.getValueString("shipToCustomer.firstName")
 
 ----
 
+[source,java]
+.Implicit QueryJoin, where unambiguous and required by QQueryFilter
+----
+// TODO finish and verify
+queryInput.withTableName("order");
+----
+
 === QueryOutput
 * `records` - *List of QRecord* - List of 0 or more records that match the query filter.
 ** _Note:  If a *recordPipe* was supplied to the QueryInput, then calling `queryOutput.getRecords()` will result in an `IllegalStateException` being thrown - as the records were placed into the pipe as they were fetched, and cannot all be accessed as a single list._

docs/actions/RenderTemplateAction.pdf

@@ -56,6 +56,37 @@ if the value in the field is longer than the `maxLength`, then one of the follow
 
 ----
 
+===== ValueRangeBehavior
+Used on Numeric fields.  Specifies min and/or max allowed values for the field.
+For each of min and max, the following attributes can be set:
+
+* `minValue` / `maxValue` - the number that is the limit.
+* `minAllowEqualTo` / `maxAllowEqualTo` - boolean (default true).  Controls if < (>) or ≤ (≥).
+* `minBehavior` / `maxBehavior` - enum of `ERROR` (default) or `CLIP`.
+** If `ERROR`, then a value not within the range causes an error, and the value does not get stored.
+** else if `CLIP`, then a value not within the range gets "clipped" to either be the min/max (if allowEqualTo),
+or to the min/max plus/minus the clipAmount
+* `minClipAmount` / `maxClipAmount` - Default 1.  Used when behavior is `CLIP` (only applies when
+not allowEqualTo).
+
+[source,java]
+.Examples of using ValueRangeBehavior
+----
+    new QFieldMetaData("noOfShoes", QFieldType.INTEGER)
+      .withBehavior(new ValueRangeBehavior().withMinValue(0));
+
+    new QFieldMetaData("price", QFieldType.BIG_DECIMAL)
+      .withBehavior(new ValueRangeBehavior()
+         // set the min value to be >= 0, and an error if an input is < 0.
+         .withMinValue(BigDecimal.ZERO)
+         .withMinAllowEqualTo(true)
+         .withMinBehavior(ERROR)
+         // set the max value to be < 100 - but effectively, clip larger values to 99.99
+         // here we use the .withMax() method that takes 4 params vs. calling 4 .withMax*() methods.
+         .withMax(new BigDecimal("100.00"), false, CLIP, new BigDecimal("0.01"))
+    );
+----
+
 ===== DynamicDefaultValueBehavior
 Used to set a dynamic default value to a field when it is being inserted or updated.
 For example, instead of having a hard-coded `defaultValue` specified in the field meta-data,

docs/metaData/Fields.adoc

@@ -288,33 +288,49 @@ all of the fields in you table in two places (the entity and the table meta-data
 If you are using `QRecordEntity` classes that correspond to your tables, then you can take advantage of some
 additional annotations on those classes, to produce more related meta-data objects associated with those tables.
 The point of this is to eliminate boilerplate, and simplify / speed up the process of getting a new table
-built and deployed in your application, with some bells and whistles added.
+built and deployed in your application.
+
+Furthermore, the case can be made that it is beneficial to keep the meta-data definition for a table as close
+as possible to the entity that corresponds to the table.  This enables modifications to the table (e.g., adding
+a new field/column) to only require edits in one java source file, rather than necessarily requiring edits
+in two files.
 
 === @QMetaDataProducingEntity
-This is an annotation to go on a QRecordEntity class, which you would like to be
-processed by `MetaDataProducerHelper`, to automatically produce some meta-data
-objects.  Specifically supports:
+This is an annotation meant to be placed on a `QRecordEntity` subclass, which you would like to be
+processed by an invocation of `MetaDataProducerHelper`, to automatically produce some meta-data
+objects.
+
+This annotation supports:
 
-* Making a possible-value-source out of the table.
+* Creating table meta-data for the corresponding record entity table. Enabled by setting `produceTableMetaData=true`.
+** One may customize the table meta data that is produced automatically by supplying a class that extends
+`MetaDataCustomizerInterface` in the annotation attribute `tableMetaDataCustomizer`.
+** In addition to (or as an alternative to) the per-table `MetaDataCustomizerInterface` that can be specified
+in `@QMetaDataProducingEntity.tableMetaDataCustomzier`, when an application calls
+`MetaDataProducerHelper.processAllMetaDataProducersInPackage`, an additional `MetaDataCustomizerInterface` can be
+given, to apply a common set of adjustments to all tales being generated by the call.
+* Making a possible-value-source out of the table.  Enabled by setting `producePossibleValueSource=true`.
 * Processing child tables to create joins and childRecordList widgets
 
 === @ChildTable
 This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to define
 child-tables, e.g., for producing joins and childRecordList widgets related to the table defined in the entity class.
 
-=== @ChildJoin
+==== @ChildJoin
 This is an annotation used as a value inside a `@ChildTable` inside a `@QMetadataProducingEntity` annotation,
 to control the generation of a `QJoinMetaData`, as a `ONE_TO_MANY` type join from the table represented by
 the annotated entity, to the table referenced in the `@ChildTable` annotation.
 
-=== @ChildRecordListWidget
+==== @ChildRecordListWidget
 This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to control
 the generation of a QWidgetMetaData - for a ChildRecordList widget.
 
 [source,java]
-.QRecordEntity with meta-data producing annotations
+.QRecordEntity with meta-data producing annotations and a table MetaDataCustomizer
 ----
 @QMetaDataProducingEntity(
+   produceTableMetaData = true,
+   tableMetaDataCustomizer = MyTable.TableMetaDataCustomizer.class,
    producePossibleValueSource = true,
    childTables = {
       @ChildTable(
@@ -326,13 +342,47 @@ the generation of a QWidgetMetaData - for a ChildRecordList widget.
 public class MyTable extends QRecordEntity
 {
    public static final String TABLE_NAME = "myTable";
-   // class body left as exercise for reader
+
+   public static class TableMetaDataCustomizer implements MetaDataCustomizerInterface<QTableMetaData>
+   {
+      @Override
+      public QTableMetaData customizeMetaData(QInstance qInstance, QTableMetaData table) throws QException
+      {
+         String childJoinName = QJoinMetaData.makeInferredJoinName(TABLE_NAME, MyChildTable.TABLE_NAME);
+
+         table
+            .withUniqueKey(new UniqueKey("name"))
+            .withIcon(new QIcon().withName("table_bar"))
+            .withRecordLabelFormat("%s")
+            .withRecordLabelFields("name")
+
+            .withSection(new QFieldSection("identity", new QIcon().withName("badge"), Tier.T1,
+               List.of("id", "name")))
+            // todo additional sections for other fields
+            .withSection(new QFieldSection("children", new QIcon().withName("account_tree"), Tier.T2)
+               .withWidgetName(childJoinName))
+
+            .withExposedJoin(new ExposedJoin()
+               .withLabel("Children")
+               .withJoinPath(List.of(childJoinName))
+               .withJoinTable(MyChildTable.TABLE_NAME));
+
+         return (table);
+      }
+   }
+
+   @QField(isEditable = false, isPrimaryKey = true)
+   private Integer id;
+
+   // remaining fields, constructors, getters & setters left as an exercise for the reader and/or the IDE
 }
 ----
 
 The class given in the example above, if processed by the `MetaDataProducerHelper`, would add the following
 meta-data objects to your `QInstance`:
 
+* A `QTableMetaData` named `myTable`, with all fields annotated as `@QField` from the `QRecordEntity` class,
+and with additional attributes as set in the `TableMetaDataCustomizer` inner class.
 * A `QPossibleValueSource` named `myTable`, of type `TABLE`, with `myTable` as its backing table.
 * A `QJoinMetaData` named `myTableJoinMyChildTable`, as a `ONE_TO_MANY` type, between those two tables.
 * A `QWidgetMetaData` named `myTableJoinMyChildTable`, as a `CHILD_RECORD_LIST` type, that will show a list of