Merge pull request #300 from doc4d/main

update prod with not collections

docs/API/DataClassClass.md

@@ -831,7 +831,7 @@ The `.query()` function <!-- REF #DataClassClass.query().Summary -->searches for
 
 If no matching entities are found, an empty `EntitySelection` is returned.
 
-**queryString parameter**
+#### queryString parameter
 
 The *queryString* parameter uses the following syntax:
 
@@ -843,7 +843,7 @@ attributePath|formula comparator value
 
 where:
 
-* **attributePath**: path of attribute on which you want to execute the query. This parameter can be a simple name (for example "country") or any valid attribute path (for example "country.name".) In case of an attribute path whose type is `Collection`, \[ ] notation is used to handle all the occurences (for example "children\[ ].age").
+* **attributePath**: path of attribute on which you want to execute the query. This parameter can be a simple name (for example "country") or any valid attribute path (for example "country.name".) In case of an attribute path whose type is `Collection`, `[]` notation is used to handle all the occurences (for example `children[].age`).
 
  >*You cannot use directly attributes whose name contains special characters such as ".", "\[ ]", or "=", ">", "#"..., because they will be incorrectly evaluated in the query string. If you need to query on such attributes, you must consider using placeholders, which allow an extended range of characters in attribute paths (see* **Using placeholders** *below).*
 
@@ -866,14 +866,14 @@ where:
  |---|---|---|
  |Equal to |=, == |Gets matching data, supports the wildcard (@), neither case-sensitive nor diacritic.|
  ||===, IS| Gets matching data, considers the @ as a standard character, neither case-sensitive nor diacritic|
- |Not equal to| #, != |Supports the wildcard (@)|
+ |Not equal to| #, != |Supports the wildcard (@). Equivalent to "Not condition applied on a statement" ([see below](#not-equal-to-in-collections)).|
  ||!==, IS NOT| Considers the @ as a standard character|
+ |Not condition applied on a statement| NOT| Parenthesis are mandatory when NOT is used before a statement containing several operators. Equivalent to "Not equal to" ([see below](#not-equal-to-in-collections)).|
  |Less than| <| |
  |Greater than| > ||
  |Less than or equal to| <=||
  |Greater than or equal to| >= ||
  |Included in| IN |Gets data equal to at least one of the values in a collection or in a set of values, supports the wildcard (@)|
- |Not condition applied on a statement| NOT| Parenthesis are mandatory when NOT is used before a statement containing several operators|
  |Contains keyword| %| Keywords can be used in attributes of string or picture type|
 
 * **value**: the value to compare to the current value of the property of each entity in the entity selection or element in the collection. It can be a **placeholder** (see **Using placeholders** below) or any expression matching the data type property.
@@ -894,7 +894,7 @@ When using a constant value, the following rules must be respected:
 * **order by attributePath**: you can include an order by *attributePath* statement in the query so that the resulting data will be sorted according to that statement. You can use multiple order by statements, separated by commas (e.g., order by *attributePath1* desc, *attributePath2* asc). By default, the order is ascending. Pass 'desc' to define a descending order and 'asc' to define an ascending order.
  >If you use this statement, the returned entity selection is ordered (for more information, please refer to [Ordered vs Unordered entity selections](ORDA/dsMapping.md#ordered-or-unordered-entity-selection)).
 
-**Using quotes**
+#### Using quotes
 
 When you use quotes within queries, you must use single quotes ' ' inside the query and double quotes " " to enclose the whole query, otherwise an error is returned. For example:
 
@@ -904,15 +904,15 @@ When you use quotes within queries, you must use single quotes ' ' inside the qu
 
 >Single quotes (') are not supported in searched values since they would break the query string. For example "comp.name = 'John's pizza' " will generate an error. If you need to search on values with single quotes, you may consider using placeholders (see below).
 
-**Using parenthesis**
+#### Using parenthesis
 
 You can use parentheses in the query to give priority to the calculation. For example, you can organize a query as follows:
 
 ```4d
 "(employee.age >= 30 OR employee.age <= 65) AND (employee.salary <= 10000 OR employee.status = 'Manager')"
 ```
 
-**Using placeholders**
+#### Using placeholders
 
 4D allows you to use placeholders for *attributePath*, *formula* and *value* arguments within the *queryString* parameter. A placeholder is a parameter that you insert in query strings and that is replaced by another value when the query string is evaluated. The value of placeholders is evaluated once at the beginning of the query; it is not evaluated for each element.
 
@@ -952,11 +952,11 @@ Using placeholders in queries **is recommended** for the following reasons:
 3. It allows the use of variables or expressions in query arguments. Examples:
 
  ```4d
-  $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
+ $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
  $result2:=$col.query("company.name = :1";"John's Pizzas")
  ```
 
-**Looking for null values**
+#### Looking for null values
 
 When you look for null values, you cannot use the placeholder syntax because the query engine considers null as an unexpected comparison value. For example, if you execute the following query:
 
@@ -970,7 +970,62 @@ You will not get the expected result because the null value will be evaluated by
  $vSingles:=ds.Person.query("spouse = null") //correct syntax
 ```
 
-**Linking collection attribute query arguments**
+#### Not equal to in collections
+
+When searching within dataclass object attributes containing collections, the "not equal to *value*" comparator (`#` or `!=`) will find elements where ALL properties are different from *value* (and not those where AT LEAST one property is different from *value*, which is how work other comparators). Basically, it is equivalent to search for "Not(find collection elements where property equals *value*"). For example, with the following entities:
+
+```
+Entity 1:
+ds.Class.name: "A"
+ds.Class.info:
+    { "coll" : [ {
+                "val":1,
+                "val":1
+            } ] }
+
+Entity 2:
+ds.Class.name: "B"
+ds.Class.info:
+    { "coll" : [ {
+                "val":1,
+                "val":0
+            } ] }
+
+Entity 3:
+ds.Class.name: "C"
+ds.Class.info:
+    { "coll" : [ {
+                "val":0,
+                "val":0
+            } ] }
+```
+
+Consider the following results:
+
+```4d
+ds.Class.query("info.coll[].val = :1";0) 
+// returns B and C
+// finds "entities with 0 in at least one val property"
+
+ds.Class.query("info.coll[].val != :1";0)
+// returns A only
+// finds "entities where all val properties are different from 0"
+// which is the equivalent to 
+ds.Class.query(not("info.coll[].val = :1";0)) 
+```
+
+If you want to implement a query that finds entities where "at least one property is different from *value*", you need to use a special notation using a letter in the `[]`:
+
+```4d
+ds.Class.query("info.coll[a].val != :1";0)  
+// returns A and B
+// finds "entities where at least one val property is different from 0"
+```
+
+You can use any letter from the alphabet as the `[a]` notation.
+
+
+#### Linking collection attribute query arguments
 
 :::info
 
@@ -1025,7 +1080,7 @@ ds.People.query("places.locations[a].kind= :1 and places.locations[a].city= :2";
 ... the query will only return "martin" because it has a "locations" element whose "kind" is "home" and whose "city" is "paris". The query will not return "smith" because the values "home" and "paris" are not in the same collection element.
 
 
-**Queries in many-to-many relations**  
+#### Queries in many-to-many relations
 
 ORDA offers a special syntax to facilitate queries in many-to-many relations. In this context, you may need to search for different values with an `AND` operator BUT in the same attribute. For example, take a look at the following structure:
 
@@ -1057,7 +1112,9 @@ $es:=ds.Movie.query("roles.actor.lastName = :1 AND roles.actor{2}.lastName = :2"
 // $es contains movies (You've Got Mail, Sleepless in Seattle, Joe Versus the Volcano)
 ```
 
-**formula parameter**
+
+
+#### formula parameter
 
 As an alternative to formula insertion within the *queryString* parameter (see above), you can pass directly a formula object as a boolean search criteria. Using a formula object for queries is **recommended** since you benefit from tokenization, and code is easier to search/read.  
 
@@ -1069,7 +1126,7 @@ The formula must have been created using the [`Formula`](FunctionClass.md#formul
 
  >For security reasons, formula calls within `query()` functions can be disallowed. See *querySettings* parameter description.
 
-**Passing parameters to formulas**
+#### Passing parameters to formulas
 
 Any *formula* called by the `query()` class function can receive parameters:
 
@@ -1087,7 +1144,7 @@ Additional examples are provided in example 3.
 
 **4D Server**: In client/server, formulas are executed on the server. In this context, only the `querySettings.args` object is sent to the formulas.
 
-**querySettings parameter**
+#### querySettings parameter
 
 In the *querySettings* parameter, you can pass an object containing additional options. The following properties are supported:
 
@@ -1101,7 +1158,7 @@ In the *querySettings* parameter, you can pass an object containing additional o
 |queryPlan| Boolean |In the resulting entity selection, returns or does not return the detailed description of the query just before it is executed, i.e. the planned query. The returned property is an object that includes each planned query and subquery (in the case of a complex query). This option is useful during the development phase of an application. It is usually used in conjunction with queryPath. Default if omitted: false. **Note**: This property is supported only by the `entitySelection.query()` and `dataClass.query()` functions.|
 |queryPath|Boolean| In the resulting entity selection, returns or does not return the detailed description of the query as it is actually performed. The returned property is an object that contains the actual path used for the query (usually identical to that of the queryPlan, but may differ if the engine manages to optimize the query), as well as the processing time and the number of records found. This option is useful during the development phase of an application. Default if omitted: false. **Note**: This property is supported only by the `entitySelection.query()` and `dataClass.query()` functions.|
 
-**About queryPlan and queryPath**
+#### About queryPlan and queryPath
 
 The information recorded in `queryPlan`/`queryPath` include the query type (indexed and sequential) and each necessary subquery along with conjunction operators. Query paths also contain the number of entities found and the time required to execute each search criterion. You may find it useful to analyze this information while developing your application(s). Generally, the description of the query plan and its path are identical but they can differ because 4D can implement dynamic optimizations when a query is executed in order to improve performance. For example, the 4D engine can dynamically convert an indexed query into a sequential one if it estimates that it is faster. This particular case can occur when the number of entities being searched for is low.
 

docs/API/WebSocketClass.md

@@ -68,6 +68,14 @@ WebSocket objects provide the following properties and functions:
 
 ## 4D.WebSocket.new()
 
+<details><summary>History</summary>
+
+|Version|Changes|
+|---|---|
+|v20 R3|Support of `headers` property in *connectionHandler*|
+
+</details>
+
 
 <!-- REF #4D.WebSocket.new().Syntax -->**4D.WebSocket.new**( *url* : Text { ; *connectionHandler* : Object } ) : 4D.WebSocket<!-- END REF -->
 
@@ -92,7 +100,7 @@ If the connection is not possible, a `null` object is returned and an error is g
 
 ### *connectionHandler* parameter
 
-In *connectionHandler*, you can pass an object containing callback functions to be called according to connection events, and data type to handle. 
+In *connectionHandler*, you can pass an object containing callback functions to be called according to connection events, as well as data type and headers to handle. 
 
 - Callbacks are automatically called in the context of the form or worker that initiates the connection. 
 - The WebSocket will be valid as long as the form or worker is not closed.
@@ -104,6 +112,8 @@ In *connectionHandler*, you can pass an object containing callback functions to
 |onTerminate|[Function](FunctionClass.md)|Callback function when the WebSocket is terminated. The callback receives the following parameters:<li>`$1`: WebSocket object</li><li>`$2`: Object</li><ul><li>`$2.code` (number, read-only): unsigned short containing the close code sent by the server.</li><li>`$2.reason` (text, read-only): Reason why the server closed the connection. This is specific to the particular server and sub-protocol.</li><li>`$2.wasClean` (boolean, read-only): Indicates whether or not the connection was cleanly closed.</li></ul>|
 |onOpen|[Function](FunctionClass.md)|Callback function when the websocket is open. The callback receives the following parameters:<li>`$1`: WebSocket object</li><li>`$2`: Object</li><ul><li>`$2.type` (text): always "open"</li></ul>|
 |dataType|Text|Type of the data received or sent. Available values: "text" (default), "blob", "object". "text" = utf-8|
+|headers|Object|Headers of the WebSocket.<li>Syntax for standard key assignment: `headers.<key>:=<value>` (*value* can be a Collection if the same key appears multiple times)</li><li>Syntax for Cookie assignment (particular case): `headers.Cookie:="<name>=<value> {; <name2>=<value2>{; ... } }"`</li>|
+
 
 Here is the sequence of callback calls:
 
@@ -115,6 +125,21 @@ Here is the sequence of callback calls:
 
 #### Example
 
+You want to set headers in the `WSConnectionHandler` user class:
+
+```4d
+// WSConnectionHandler class
+
+Class constructor($myToken:Text)
+
+// Creation of the headers sent to the server
+This.headers:=New object("x-authorization";$myToken)
+// We define two cookies
+This.headers.Cookie:="yummy_cookie=choco; tasty_cookie=strawberry"
+...
+
+```
+
 
 <!-- REF #WebSocketClass.dataType.Desc -->
 ## .dataType

docs/Notes/updates.md

@@ -11,7 +11,7 @@ Read [**What’s new in 4D v20 R3**](https://blog.4d.com/en-whats-new-in-4d-v20-
 
 #### Highlights
 
-
+- Support of `headers` property in *connectionHandler* parameter of [4D.WebSocket.new](../API/WebSocketClass.md#4dwebsocketnew).
 - 4D Language commands: [What's new page](https://doc.4d.com/4Dv20R2/4D/20-R2/What-s-new.901-6398284.en.html) on doc.4d.com.
 - 4D Write Pro: [What's new page](https://doc.4d.com/4Dv20R2/4D/20-R2/What-s-new.901-6390313.en.html) on doc.4d.com.
 - [**Fixed bug list**](https://bugs.4d.fr/fixedbugslist?version=20_R3): list of all bugs that have been fixed in 4D v20 R3.
@@ -43,13 +43,16 @@ Read [**What’s new in 4D v20 R2**](https://blog.4d.com/en-whats-new-in-4d-v20-
 Read [**What’s new in 4D v20**](https://blog.4d.com/en-whats-new-in-4d-v20/), the blog post that lists all new features and enhancements in 4D v20.
 
 
-#### Index rebuild warning 
+#### Index rebuild warning
 
 4D v20 includes an ICU library update (see below) which will force an automatic rebuild of indexes of type alpha, text, and object. Depending on the size of the data file, this operation can take a while and may require to be planned.
 
-:::caution 4D v20.1 index rebuild warning
+:::caution 4D v20.1 index rebuild and client/server versions
+
+4D v20.1 also includes an ICU library update, which has the following consequences:
 
-4D v20.1 includes a new ICU library update which will also force an automatic rebuild of indexes of type alpha, text, and object. 
+- It will force an automatic rebuild of indexes of type alpha, text, and object.
+- Because of sorting consistency, it requires that 4D remote clients and 4D Server use the same version: only remote 4D v20.1 can connect to 4D Server v20.1 and vice versa. 
 
 :::