From 78847420853fb8357a4dc15c6a15fb11984a9e52 Mon Sep 17 00:00:00 2001 From: arnaud-4d Date: Tue, 5 May 2026 15:18:29 +0200 Subject: [PATCH 1/7] first commit --- docs/API/QuotaManagerClass.md | 191 ++++++++++++++++++++++++++++++++++ docs/API/SessionClass.md | 47 +++++++++ 2 files changed, 238 insertions(+) create mode 100644 docs/API/QuotaManagerClass.md diff --git a/docs/API/QuotaManagerClass.md b/docs/API/QuotaManagerClass.md new file mode 100644 index 00000000000000..31c83f41a76250 --- /dev/null +++ b/docs/API/QuotaManagerClass.md @@ -0,0 +1,191 @@ +--- +id: QuotaManagerClass +title: QuotaManager +--- + + +The `4D.QuotaManager` class provides you with an interface to configure and monitor the usage limits you apply to the server. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. + +Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. + + + +
History + +|Release|Changes| +|---|---| +|21 R4|Class added| + +
+ +### Example + + + +### QuotaManager Object + + +4D.QuotaManager objects provide the following properties and functions: + +|| +|---| +|[](#body)
| +|[](#headers)
| +|[](#setbody)
| +|[](#setheader)
| +|[](#setstatus)
| +|[](#status)
| + +:::note + +A 4D.OutgoingMessage object is a [non-sharable](../Concepts/shared.md) object. + +::: + + + + + + +## .body + +**body** : any + +#### Description + +The `.body` property contains the outgoing message body. The following data types are supported in the `.body` property: + +- text +- blob +- object +- image + +The `.body` property is read-write. + +You can also set the `.body` property using the [`setBody()`](#setbody) function, in which case the `content-type` header is automatically set. + + + + + +## .headers + +**headers** : Object + +#### Description + +The `.headers` property contains the current headers of the outgoing message as key/value pairs. + +The `.headers` property is read-only. To set a header, use the [`setHeader()`](#setheader) function. + + + + + +## .setBody() + +**.setBody**( *body* : any ) + + + +
+ +|Parameter|Type||Description| +|---|--- |---|------| +|body|any |->|Body of the outgoing message| +
+ + +#### Description + +The `.setBody()` function sets the outgoing message *body*. + + The following data types are supported in the *body*: + +- Text +- Blob +- Object +- Image + +When this function is used, the content-type header is automatically set depending on the *body* type: + +- Content-Type:text/plain if the body is a Text +- Content-Type:application/octet-stream if body is a Blob +- Content-Type:application/json if body is an Object +- Content-Type:image/jpeg, image/gif... if body is an Image + +If *body* is not of a supported value type, an error is returned. + + + + + +## .setHeader() + +**.setHeader**( *key* : Text ; *value* : Text ) + + + +
+ +|Parameter|Type||Description| +|---|--- |---|------| +|key|Text|->|Header property to set| +|value|Text|->|Value of the header property| +
+ + +#### Description + +The `.setHeader()` function sets the outgoing message header *key* with the provided *value*. If both parameters are not Text values, an error is raised. + +When returning a 4D.OutgoingMessage object instance, 4D automatically sets some headers (e.g. `Set-Cookie` with `4DSID__ProjectName_=....`). + +:::note + +If you set a *value* for the "Content-Type" header *key*, make sure you call this function after the call to [`setBody()`](#setbody), because `setBody()` automatically fills this header. For a list of "Content-Type" header values, please refer to the [`WEB SEND BLOB`](../commands/web-send-blob) documentation. + +::: + + + + + +## .setStatus() + +**.setStatus**( *status* : Integer ) + + + +
+ +|Parameter|Type||Description| +|---|--- |---|------| +|status|Integer|->|Status to set| +
+ + +#### Description + +The `.setStatus()` function sets the `status` property with the given *status*. + +If *status* is not an integer value, an error is raised. + +For a list of HTTP status codes, please refer the [HTTP status code list on Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). + + + + + + + +## .status + +**status** : Integer + +#### Description + +The `.status` property contains the current status of the outgoing message. This property can be set using the [`setStatus()`](setstatus) function. + + + diff --git a/docs/API/SessionClass.md b/docs/API/SessionClass.md index 04140e68c650c3..69aee60a5990e0 100644 --- a/docs/API/SessionClass.md +++ b/docs/API/SessionClass.md @@ -718,6 +718,53 @@ End if + +## .quotas + +
History + +|Release|Changes| +|---|---| +|21 R4|Added| + +
+ +**.quotas** : 4D.QuotaManager + +#### Description + + +The `.quotas` property contains a `4D.QuotaManager` object with current values (read-only) and updatable values for server thresholds in the current session. Server thresholds are used to control the requests to the server and help preventing excessive use of ORDA resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)). + +The following property values of the `4D.QuotaManager` object can be used: + +|Property||Type|Writable|Description| +|---|---|---|---|---| +|nbEntitySets||Integer|yes|Maximum allowed number of entity sets in memory for the session| +|defaultEntitySetTimeout ||Integer|yes|Default inactivity timeout for entity sets in memory for the session (seconds)| +|maxEntitySetTimeout ||Integer|yes|Maximum inactivity timeout for entity sets in memory for this session (seconds)| +|currentValues||Object|no|Current values of thresholds for the session| +||nbEntitySets|Integer|no|| +||defaultEntitySetTimeout|Integer|no|| +||maxEntitySetTimeout|Integer|no|| + + + + + +#### Example + +```4d + //set the maximum number oy entity sets in memory + //for the session to 50 +Session.quotas.nbEntitySets:=50 +``` + + + + + + ## .restore() From a58611a20c082f45c144de9e5d84a59b19fc661c Mon Sep 17 00:00:00 2001 From: arnaud-4d Date: Tue, 5 May 2026 18:51:23 +0200 Subject: [PATCH 2/7] class finished --- docs/API/QuotaManagerClass.md | 158 +++++++++------------------------- docs/API/SessionClass.md | 17 ++-- docs/Notes/updates.md | 11 +++ docs/REST/$entityset.md | 27 ++++++ docs/REST/$method.md | 13 ++- 5 files changed, 103 insertions(+), 123 deletions(-) diff --git a/docs/API/QuotaManagerClass.md b/docs/API/QuotaManagerClass.md index 31c83f41a76250..734d07d26ee09e 100644 --- a/docs/API/QuotaManagerClass.md +++ b/docs/API/QuotaManagerClass.md @@ -4,10 +4,10 @@ title: QuotaManager --- -The `4D.QuotaManager` class provides you with an interface to configure and monitor the usage limits you apply to the server. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. +The `4D.QuotaManager` class provides you with an interface to configure and monitor the usage limits you apply to the server. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. -Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. +`4D.QuotaManager` objects are instantiated by the [`quotas` property of a session](./SessionClass.md#quotas) object.
History @@ -25,167 +25,95 @@ Typically, the quota manager allows you to provide thresholds to ORDA resources ### QuotaManager Object -4D.QuotaManager objects provide the following properties and functions: +4D.QuotaManager objects provide the following properties: || |---| -|[](#body)
| -|[](#headers)
| -|[](#setbody)
| -|[](#setheader)
| -|[](#setstatus)
| -|[](#status)
| - -:::note - -A 4D.OutgoingMessage object is a [non-sharable](../Concepts/shared.md) object. - -::: - +|[](#defaultentitysettimeout)
| +|[](#maxentitysettimeout)
| +|[](#nbentitysets)
| - -## .body + +## .defaultEntitySetTimeout -**body** : any +**defaultEntitySetTimeout** : Integer #### Description -The `.body` property contains the outgoing message body. The following data types are supported in the `.body` property: - -- text -- blob -- object -- image - -The `.body` property is read-write. - -You can also set the `.body` property using the [`setBody()`](#setbody) function, in which case the `content-type` header is automatically set. - - +The `.defaultEntitySetTimeout` property contains the default inactivity timeout for REST entity sets stored in memory during the current session (in seconds). +By default, this value is 2 hours (7200 seconds). It can also be defined at the entity set creation using the [`$timeout` REST API](../REST/$timeout.md). - -## .headers +You can change this value dynamically using the [`quotas.defaultEntitySetTimeout` property of the Session](./SessionClass.md#quotas), so that it will be used for any entity set created afterward in the session (existing entity set default timeout values are not modified). -**headers** : Object +:::note -#### Description +If you define a value higher than the `maxEntitySetTimeout` property value, it will be aligned with the `maxEntitySetTimeout` value. -The `.headers` property contains the current headers of the outgoing message as key/value pairs. +::: -The `.headers` property is read-only. To set a header, use the [`setHeader()`](#setheader) function. - -## .setBody() + +## .maxEntitySetTimeout -**.setBody**( *body* : any ) - - - -
- -|Parameter|Type||Description| -|---|--- |---|------| -|body|any |->|Body of the outgoing message| -
- +**maxEntitySetTimeout** : Integer #### Description -The `.setBody()` function sets the outgoing message *body*. - - The following data types are supported in the *body*: +The `.maxEntitySetTimeout` property contains the maximum inactivity timeout value for REST entity sets stored in memory during the current session (in seconds). -- Text -- Blob -- Object -- Image +You can set this value using the [`quotas.maxEntitySetTimeout` property of the Session](./SessionClass.md#quotas), so that it will be used for any entity set created afterward in the session (existing entity set maximum timeout values are not modified). -When this function is used, the content-type header is automatically set depending on the *body* type: +Once the `.maxEntitySetTimeout` property is set, any entity set created afterward in the session could not have a timeout value longer than the `.maxEntitySetTimeout` value. -- Content-Type:text/plain if the body is a Text -- Content-Type:application/octet-stream if body is a Blob -- Content-Type:application/json if body is an Object -- Content-Type:image/jpeg, image/gif... if body is an Image +For example, assuming the maximum inactivity timeout is set to 40 minutes (2400 seconds), if an entity set is created with a required timeout which exceeds the maximum value: -If *body* is not of a supported value type, an error is returned. +``` +http://127.0.0.1/rest/People?$filter=ID>=4&$method=entityset&$timeout=3000 +``` - +then the timeout defined in the request is ignored and the entity set will be released after 40 minutes if not used during this period of time. +#### Example - -## .setHeader() +In some 4D code in a REST process: -**.setHeader**( *key* : Text ; *value* : Text ) +```4d +Session.quotas.maxEntitySetTimeout:=2400 +``` - -
- -|Parameter|Type||Description| -|---|--- |---|------| -|key|Text|->|Header property to set| -|value|Text|->|Value of the header property| -
-#### Description -The `.setHeader()` function sets the outgoing message header *key* with the provided *value*. If both parameters are not Text values, an error is raised. + +## .nbEntitySets -When returning a 4D.OutgoingMessage object instance, 4D automatically sets some headers (e.g. `Set-Cookie` with `4DSID__ProjectName_=....`). - -:::note - -If you set a *value* for the "Content-Type" header *key*, make sure you call this function after the call to [`setBody()`](#setbody), because `setBody()` automatically fills this header. For a list of "Content-Type" header values, please refer to the [`WEB SEND BLOB`](../commands/web-send-blob) documentation. - -::: - - - - - -## .setStatus() - -**.setStatus**( *status* : Integer ) - - - -
- -|Parameter|Type||Description| -|---|--- |---|------| -|status|Integer|->|Status to set| -
- +**nbEntitySets** : Integer #### Description -The `.setStatus()` function sets the `status` property with the given *status*. - -If *status* is not an integer value, an error is raised. - -For a list of HTTP status codes, please refer the [HTTP status code list on Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). +The `.nbEntitySets` property contains the maximum number of REST entity sets allowed in memory for the current session (in seconds). +By default, there is no limit for entity sets stored in memory by REST requests (the value is 0). You can set a limit to control the server payload. - +#### Example +In some 4D code in a REST process: +```4d + //max 50 entity sets +Session.quotas.nbEntitySets:=50 +``` - -## .status + -**status** : Integer -#### Description -The `.status` property contains the current status of the outgoing message. This property can be set using the [`setStatus()`](setstatus) function. - - diff --git a/docs/API/SessionClass.md b/docs/API/SessionClass.md index 69aee60a5990e0..e97d7b8eb9f93e 100644 --- a/docs/API/SessionClass.md +++ b/docs/API/SessionClass.md @@ -53,6 +53,7 @@ All session types can handle privileges, but only the code executed in a **web c |[](#info)
| |[](#isguest)
| |[](#promote)
| +|[](#quotas)
| |[](#restore)
| |[](#setprivileges)
| |[](#storage)
| @@ -571,6 +572,8 @@ Since `.info` is a computed property, it is recommended to call it once and then ::: +This property is **read only**. + @@ -736,21 +739,21 @@ End if The `.quotas` property contains a `4D.QuotaManager` object with current values (read-only) and updatable values for server thresholds in the current session. Server thresholds are used to control the requests to the server and help preventing excessive use of ORDA resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)). -The following property values of the `4D.QuotaManager` object can be used: +This property is **read only**. + +The following property values of the `4D.QuotaManager` object are available for the session: |Property||Type|Writable|Description| |---|---|---|---|---| -|nbEntitySets||Integer|yes|Maximum allowed number of entity sets in memory for the session| -|defaultEntitySetTimeout ||Integer|yes|Default inactivity timeout for entity sets in memory for the session (seconds)| -|maxEntitySetTimeout ||Integer|yes|Maximum inactivity timeout for entity sets in memory for this session (seconds)| +|nbEntitySets||Integer|yes|Maximum allowed number of entity sets in memory| +|defaultEntitySetTimeout ||Integer|yes|Default inactivity timeout for entity sets in memory (seconds)| +|maxEntitySetTimeout ||Integer|yes|Maximum inactivity timeout for entity sets in memory (seconds)| |currentValues||Object|no|Current values of thresholds for the session| ||nbEntitySets|Integer|no|| ||defaultEntitySetTimeout|Integer|no|| ||maxEntitySetTimeout|Integer|no|| - - - +When you modify a value, it is immediately taken into account by the server and will be applied to sessions created afterwards. #### Example diff --git a/docs/Notes/updates.md b/docs/Notes/updates.md index d559cde17643c6..b6b9ee20be283b 100644 --- a/docs/Notes/updates.md +++ b/docs/Notes/updates.md @@ -3,6 +3,17 @@ id: updates title: Release Notes --- +## 4D 21 R4 + +Read [**What’s new in 4D 21 R4**](https://blog.4d.com/whats-new-in-4d-21-r4/), the blog post that lists all new features and enhancements in 4D 21 R4. + +#### Highlights + +- New [`4D.QuotaManager`](../API/QuotaManagerClass.md) class to handle threshold objects for protecting the server. +- New session `.quotas` property to configure thresholds for sessions. +- New [`$entityset/$release`](../REST/$entityset.md#entitysetrelease) REST request to delete entity sets from memory (the [previous syntax](../REST/$method.md#methodrelease) is deprecated). + + ## 4D 21 R3 Read [**What’s new in 4D 21 R3**](https://blog.4d.com/whats-new-in-4d-21-r3/), the blog post that lists all new features and enhancements in 4D 21 R3. diff --git a/docs/REST/$entityset.md b/docs/REST/$entityset.md index cf88b6ac9739ea..8b7245521cc4dd 100644 --- a/docs/REST/$entityset.md +++ b/docs/REST/$entityset.md @@ -12,6 +12,7 @@ After [creating an entity set]($method.md#methodentityset) by using `$method=ent |---|---|---| |[**$entityset/\{entitySetID\}**](#entitysetentitysetid)|`/People/$entityset/0ANUMBER`|Retrieves an existing entity set| |[**$entityset/\{entitySetID\}?$logicOperator...&$otherCollection**](#entitysetentitysetidlogicoperatorothercollection)|`/Employee/$entityset/0ANUMBER?$logicOperator=AND&$otherCollection=0ANUMBER`|Creates a new entity set from comparing existing entity sets| +|[**$entityset/$release**](#entitysetrelease)|`/Employee/$entityset/$release`|Releases one or more existing entity sets from the 4D Server's cache| @@ -98,3 +99,29 @@ If there is an intersection, this query returns true. Otherwise, it returns fals In the following example we create a new entity set that combines all the entities in both entity sets: ` GET /rest/Employee/$entityset/9718A30BF61343C796345F3BE5B01CE7?$logicOperator=OR&$otherCollection=C05A0D887C664D4DA1B38366DD21629B&$method=entityset` + + +## $entityset/$release + +Releases on or more existing entity set(s) stored in [4D Server's cache](../ORDA/client-server-optimization.md#orda-cache). + +### Description + +You can use this command to release a collection of entity sets, which you created using [`$method=entityset`](#methodentityset), from 4D Server's cache. + +### Example + +Release two entity sets from the server's cache: + +`POST /rest/Employee/$entityset/$release` + +The body must contain a collection with the entity sets ids to release: + +**POST data**: + +```json +[ +"552AE0C8329045FDB65A8C151AEBC532", "9D0617688D7540C090D7675CAF21D7C8" +] +``` + diff --git a/docs/REST/$method.md b/docs/REST/$method.md index 81c619bc05a291..2b4ea31620e521 100644 --- a/docs/REST/$method.md +++ b/docs/REST/$method.md @@ -11,11 +11,14 @@ This parameter allows you to define the operation to execute with the returned e |---|---|---| |[**$method=delete**](#methoddelete)|`POST /Employee?$filter="ID=11"& $method=delete`|Deletes the current entity, entity collection, or entity selection| |[**$method=entityset**](#methodentityset)|`GET /People/?$filter="ID>320"& $method=entityset& $timeout=600`|Creates an entity set in 4D Server's cache based on the collection of entities defined in the REST request| -|[**$method=release**](#methodrelease)|`GET /Employee/$entityset/?$method=release`|Releases an existing entity set stored in 4D Server's cache| |[**$method=subentityset**](#methodsubentityset)|`GET /Company(1)/staff?$expand=staff& $method=subentityset& $subOrderby=lastName ASC`|Creates an entity set based on the collection of related entities defined in the REST request| |[**$method=update**](#methodupdate)|`POST /Person/?$method=update`|Updates and/or creates one or more entities| +:::warning Deprecated +As of 4D 21 R4, the **`GET /Employee/$entityset/?$method=release`** syntax is **deprecated** and should no longer be used. You must now use [`/$entityset/$release` with a POST verb](./$entityset.md). + +::: @@ -88,6 +91,14 @@ __ENTITYSET: "http://127.0.0.1:8081/rest/Employee/$entityset/9718A30BF61343C7963 ## $method=release +:::warning Deprecated + +As of 4D 21 R4, the **`GET /Employee/$entityset/?$method=release`** syntax is **deprecated** and should no longer be used. You must now use [`/$entityset/$release` with a POST verb](./$entityset.md). + +::: + + + Releases an existing entity set stored in 4D Server's cache. ### Description From e95af783b69c14eb3d43a372719008d14ea2679f Mon Sep 17 00:00:00 2001 From: arnaud-4d Date: Wed, 6 May 2026 10:33:55 +0200 Subject: [PATCH 3/7] Update session.md --- docs/language-legacy/Processes/session.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/language-legacy/Processes/session.md b/docs/language-legacy/Processes/session.md index 540214e6309334..3f71ee2efb24f0 100644 --- a/docs/language-legacy/Processes/session.md +++ b/docs/language-legacy/Processes/session.md @@ -43,6 +43,12 @@ For more information, see the [Session types](../../API/SessionClass.md#session- The command returns *Null* if it is called in a web process and scalable sessions are disabled on the web server. +:::note + +There is always one REST session on the server, even if scalable sessions are disabled. Thus, the `Session` command always returns a REST session object when called in a REST process. + +::: + ### Web sessions The `Session` object of web sessions is available from any web process: From 18809a948a2d6853e372bb41d9ebd8290e8ae90d Mon Sep 17 00:00:00 2001 From: arnaud-4d Date: Wed, 6 May 2026 10:46:02 +0200 Subject: [PATCH 4/7] Update session.md --- docs/language-legacy/Processes/session.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/language-legacy/Processes/session.md b/docs/language-legacy/Processes/session.md index 3f71ee2efb24f0..aaa2b1a57004dd 100644 --- a/docs/language-legacy/Processes/session.md +++ b/docs/language-legacy/Processes/session.md @@ -34,7 +34,7 @@ The `Session` command returns the `Sessio Depending on the process from which the command is called, the current session can be: -- a web session (when [scalable sessions are enabled](../../WebServer/sessions.md#enabling-web-sessions)), +- a web session (when [scalable sessions are enabled](../../WebServer/sessions.md#enabling-web-sessions)), which includes REST sessions, - a remote user session (on the server or on the client), - a stored procedures session, - a standalone session. @@ -45,7 +45,7 @@ The command returns *Null* if it is called in a web process and scalable session :::note -There is always one REST session on the server, even if scalable sessions are disabled. Thus, the `Session` command always returns a REST session object when called in a REST process. +There is always at least one REST session on the server, even if [scalable sessions are disabled](../../WebServer/sessions.md#enabling-web-sessions). Thus, the `Session` command always returns a REST session object when called from a REST process. ::: From 533bd6c56a22e22d7f4dbf55e5d49b5771bd650a Mon Sep 17 00:00:00 2001 From: arnaud-4d Date: Wed, 6 May 2026 17:24:15 +0200 Subject: [PATCH 5/7] final for current spec --- docs/API/QuotaManagerClass.md | 29 ++++++++++++++++++++++++++--- docs/API/SessionClass.md | 23 ++++++++++++----------- docs/Notes/updates.md | 4 ++-- docs/REST/$info.md | 13 +++++++------ docs/REST/$method.md | 10 ++++++++-- docs/REST/$timeout.md | 6 ++++++ 6 files changed, 61 insertions(+), 24 deletions(-) diff --git a/docs/API/QuotaManagerClass.md b/docs/API/QuotaManagerClass.md index 734d07d26ee09e..326bd6786b29a2 100644 --- a/docs/API/QuotaManagerClass.md +++ b/docs/API/QuotaManagerClass.md @@ -4,7 +4,7 @@ title: QuotaManager --- -The `4D.QuotaManager` class provides you with an interface to configure and monitor the usage limits you apply to the server. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. +The `4D.QuotaManager` class provides you with an interface to configure and monitor the usage limits you apply to the REST server. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. `4D.QuotaManager` objects are instantiated by the [`quotas` property of a session](./SessionClass.md#quotas) object. @@ -29,12 +29,25 @@ The `4D.QuotaManager` class provides you with an interface to configure and moni || |---| +|[](#currentvalues)
| |[](#defaultentitysettimeout)
| |[](#maxentitysettimeout)
| |[](#nbentitysets)
| + +## .currentValues + +**currentValues** : Object + +#### Description + +The `.currentValues` property contains the current values related to the defined quotas properties. + + + + ## .defaultEntitySetTimeout @@ -55,6 +68,14 @@ If you define a value higher than the `maxEntitySetTimeout` property value, it w ::: +#### Example + +In some 4D code in a REST process: + +```4d +Session.quotas.defaultEntitySetTimeout:=1200 +``` + @@ -78,7 +99,7 @@ For example, assuming the maximum inactivity timeout is set to 40 minutes (2400 http://127.0.0.1/rest/People?$filter=ID>=4&$method=entityset&$timeout=3000 ``` -then the timeout defined in the request is ignored and the entity set will be released after 40 minutes if not used during this period of time. +... then the timeout defined in the request is ignored and the entity set will be released after 40 minutes if not used during this period of time. #### Example @@ -101,7 +122,9 @@ Session.quotas.maxEntitySetTimeout:=2400 The `.nbEntitySets` property contains the maximum number of REST entity sets allowed in memory for the current session (in seconds). -By default, there is no limit for entity sets stored in memory by REST requests (the value is 0). You can set a limit to control the server payload. +By default, there is no limit for entity sets [stored in memory by REST requests](../REST/$info.md) (the value is 0). You can set a limit to control the server payload for a specific session. + +When the maximum number of allowed entity sets is reached, a REST request that need to create an entity set will get a [**429** HTTP status code and an error response](../REST/REST_requests.md#rest-status-and-response), until at least one entity set is released. You can release an entity set from the cache using the [`$release` REST command](../REST/$entityset.md#entitysetrelease). #### Example diff --git a/docs/API/SessionClass.md b/docs/API/SessionClass.md index e97d7b8eb9f93e..f0ffbca457e4cb 100644 --- a/docs/API/SessionClass.md +++ b/docs/API/SessionClass.md @@ -737,28 +737,29 @@ End if #### Description -The `.quotas` property contains a `4D.QuotaManager` object with current values (read-only) and updatable values for server thresholds in the current session. Server thresholds are used to control the requests to the server and help preventing excessive use of ORDA resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)). +The `.quotas` property contains a `4D.QuotaManager` object with current values (read-only) and default values (writable) for server thresholds in the current session. Server thresholds are used to control the requests to the server and help preventing excessive use of ORDA resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)). This property is **read only**. -The following property values of the `4D.QuotaManager` object are available for the session: +The following properties of the `4D.QuotaManager` object are available for the session: |Property||Type|Writable|Description| |---|---|---|---|---| -|nbEntitySets||Integer|yes|Maximum allowed number of entity sets in memory| -|defaultEntitySetTimeout ||Integer|yes|Default inactivity timeout for entity sets in memory (seconds)| -|maxEntitySetTimeout ||Integer|yes|Maximum inactivity timeout for entity sets in memory (seconds)| -|currentValues||Object|no|Current values of thresholds for the session| -||nbEntitySets|Integer|no|| -||defaultEntitySetTimeout|Integer|no|| -||maxEntitySetTimeout|Integer|no|| +|[nbEntitySets](./QuotaManagerClass.md#nbentitysets)||Integer|yes|Maximum allowed number of entity sets in memory| +|[defaultEntitySetTimeout](./QuotaManagerClass.md#defaultentitysettimeout) ||Integer|yes|Default inactivity timeout for entity sets in memory (seconds)| +|[maxEntitySetTimeout](./QuotaManagerClass.md#maxentitysettimeout) ||Integer|yes|Maximum inactivity timeout for entity sets in memory (seconds)| +|currentValues||Object|no|| +||nbEntitySets|Integer|no|Number of entity sets [currently in cache](../REST/$info.md)| +||defaultEntitySetTimeout|Integer|no|Default inactivity timeout| +||maxEntitySetTimeout|Integer|no|Maximum inactivity timeout| + +When you modify a value, it is immediately taken into account by the server (no need to restart) and will be applied to further REST requests. -When you modify a value, it is immediately taken into account by the server and will be applied to sessions created afterwards. #### Example ```4d - //set the maximum number oy entity sets in memory + //set the maximum number of entity sets in memory //for the session to 50 Session.quotas.nbEntitySets:=50 ``` diff --git a/docs/Notes/updates.md b/docs/Notes/updates.md index b6b9ee20be283b..a7e40eb451d9f1 100644 --- a/docs/Notes/updates.md +++ b/docs/Notes/updates.md @@ -9,9 +9,9 @@ Read [**What’s new in 4D 21 R4**](https://blog.4d.com/whats-new-in-4d-21-r4/), #### Highlights -- New [`4D.QuotaManager`](../API/QuotaManagerClass.md) class to handle threshold objects for protecting the server. - New session `.quotas` property to configure thresholds for sessions. -- New [`$entityset/$release`](../REST/$entityset.md#entitysetrelease) REST request to delete entity sets from memory (the [previous syntax](../REST/$method.md#methodrelease) is deprecated). +- New [`4D.QuotaManager`](../API/QuotaManagerClass.md) class to handle threshold objects for protecting the server. +- New [`$entityset/$release`](../REST/$entityset.md#entitysetrelease) REST request to delete entity sets from server cache (the [previous syntax](../REST/$method.md#methodrelease) is deprecated). ## 4D 21 R3 diff --git a/docs/REST/$info.md b/docs/REST/$info.md index 6b44ea8919d83d..1f4eac250775e9 100644 --- a/docs/REST/$info.md +++ b/docs/REST/$info.md @@ -12,27 +12,28 @@ When you call this request for your project, you retrieve information in the fol |---|---|---| |cacheSize| Number |4D Server's cache size.| |usedCache |Number |How much of 4D Server's cache has been used.| -|entitySetCount |Number |Number of entity selections.| -|entitySet |Collection|A collection in which each object contains information about each entity selection.| +|entitySetCount |Number |Number of entity sets.| +|entitySet |Collection|A collection in which each object contains information about each entity set.| |ProgressInfo| Collection |A collection containing information about progress indicator information.| |sessionInfo| Collection |A collection in which each object contains information about each user session.| |privileges| Object |An object with a "privileges" property (collection of objects). Each object of the collection has a "privilege" property with a privilege name of the user session as value.| ### entitySet -For each entity selection currently stored in 4D Server's cache, the following information is returned: + +For each entity set currently stored in 4D Server's cache, the following information is returned: |Property| Type| Description| |---|---|---| |id|Text| A UUID that references the entity set.| |dataClass|Text |Name of the dataclass.| -|selectionSize| Number| Number of entities in the entity selection.| +|selectionSize| Number| Number of entities in the entity set.| |sorted|Boolean|Returns true if the set was sorted (using `$orderby`) or false if it's not sorted.| |refreshed|Date|When the entity set was created or the last time it was used.| -|expires|Date|When the entity set will expire (this date/time changes each time when the entity set is refreshed). The difference between refreshed and expires is the timeout for an entity set. This value is either two hours by default or what you defined using `$timeout`. +|expires|Date|When the entity set will expire (this date/time changes each time when the entity set is refreshed). The difference between refreshed and expires is the timeout for an entity set. This value is either two hours by default or what you defined using `$timeout`. It can also be modified for the session through the [`Session.quotas`](../API/SessionClass.md#quotas) property. | -For information about how to create an entity selection, refer to `$method=entityset`. If you want to remove the entity selection from 4D Server's cache, use `$method=release`. +For information about how to create an entity set, refer to [`$method=entityset`](./$method.md#methodentityset). If you want to remove the entity selection from 4D Server's cache, use [`$entityset/$release`](./$entityset.md#entitysetrelease). >4D also creates its own entity selections for optimization purposes, so the ones you create with `$method=entityset` are not the only ones returned. diff --git a/docs/REST/$method.md b/docs/REST/$method.md index 2b4ea31620e521..7b8a8ef8f68d9f 100644 --- a/docs/REST/$method.md +++ b/docs/REST/$method.md @@ -9,7 +9,7 @@ This parameter allows you to define the operation to execute with the returned e |Syntax|Example|Description| |---|---|---| -|[**$method=delete**](#methoddelete)|`POST /Employee?$filter="ID=11"& $method=delete`|Deletes the current entity, entity collection, or entity selection| +|[**$method=delete**](#methoddelete)|`POST /Employee?$filter="ID=11"& $method=delete`|Deletes the current entity, entity collection, or entity set| |[**$method=entityset**](#methodentityset)|`GET /People/?$filter="ID>320"& $method=entityset& $timeout=600`|Creates an entity set in 4D Server's cache based on the collection of entities defined in the REST request| |[**$method=subentityset**](#methodsubentityset)|`GET /Company(1)/staff?$expand=staff& $method=subentityset& $subOrderby=lastName ASC`|Creates an entity set based on the collection of related entities defined in the REST request| |[**$method=update**](#methodupdate)|`POST /Person/?$method=update`|Updates and/or creates one or more entities| @@ -63,10 +63,16 @@ Creates an entity set in 4D Server's cache based on the collection of entities d ### Description -When you create a collection of entities in REST, you can also create an entity set that will be saved in 4D Server's cache. The entity set will have a reference number that you can pass to `$entityset/\{entitySetID\}` to access it. By default, it is valid for two hours; however, you can modify that amount of time by passing a value (in seconds) to $timeout. +When you create a collection of entities in REST, you can also create an entity set that will be saved in 4D Server's cache. The entity set will have a reference number that you can pass to `$entityset/\{entitySetID\}` to access it. By default, it is valid for two hours; however, you can modify that amount of time by passing a value (in seconds) to [`$timeout`](./$timeout.md). It can also be modified for the session through the [`Session.quotas`](../API/SessionClass.md#quotas) property. If you have used `$savedfilter` and/or `$savedorderby` (in conjunction with `$filter` and/or `$orderby`) when you created your entity set, you can recreate it with the same reference ID even if it has been removed from 4D Server's cache. +:::note + +By default, you can create as many entity sets as you want. However, the total number of entity sets in the 4D Server cache can be limited for a session through the [`Session.quotas`](../API/SessionClass.md#quotas) property. + +::: + ### Example To create an entity set, which will be saved in 4D Server's cache for two hours, add `$method=entityset` at the end of your REST request: diff --git a/docs/REST/$timeout.md b/docs/REST/$timeout.md index 0463f12e19b760..2f6be153cae4ea 100644 --- a/docs/REST/$timeout.md +++ b/docs/REST/$timeout.md @@ -14,6 +14,12 @@ Once the timeout has been defined, each time an entity set is called upon (by us If an entity set is removed and then recreated using `$method=entityset` along with [`$savedfilter`]($savedfilter.md), the new default timeout is 10 minutes regardless of the timeout you defined when calling `$timeout`. +:::note + +The timeout can also be modified for a session using the [`Session.quotas`](../API/SessionClass.md#quotas) property. + +::: + ## Example In our entity set that we're creating, we define the timeout to 20 minutes: From b2957a6b9c3caccb86ba2a8057ef7fedcc214dc2 Mon Sep 17 00:00:00 2001 From: arnaud-4d Date: Wed, 6 May 2026 17:29:55 +0200 Subject: [PATCH 6/7] Update $entityset.md --- docs/REST/$entityset.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST/$entityset.md b/docs/REST/$entityset.md index 8b7245521cc4dd..e5330a59ced842 100644 --- a/docs/REST/$entityset.md +++ b/docs/REST/$entityset.md @@ -103,7 +103,7 @@ In the following example we create a new entity set that combines all the entiti ## $entityset/$release -Releases on or more existing entity set(s) stored in [4D Server's cache](../ORDA/client-server-optimization.md#orda-cache). +Releases on or more existing entity set(s) stored in [4D Server's cache](./$info.md). ### Description From 7694de299caaa666b58c03ca0b18058d72b4d4a8 Mon Sep 17 00:00:00 2001 From: arnaud-4d Date: Mon, 8 Jun 2026 18:31:38 +0200 Subject: [PATCH 7/7] after closure - BLOG POST TITLE TO BET UPDATED --- docs/API/QuotaManagerClass.md | 18 ++++++---- docs/API/SessionClass.md | 17 ++++++--- docs/Notes/updates.md | 4 +++ docs/REST/$method.md | 49 -------------------------- docs/preprocessing.conf | 65 ++++++++++++++++++----------------- 5 files changed, 61 insertions(+), 92 deletions(-) diff --git a/docs/API/QuotaManagerClass.md b/docs/API/QuotaManagerClass.md index 326bd6786b29a2..dac7c5f63e38c9 100644 --- a/docs/API/QuotaManagerClass.md +++ b/docs/API/QuotaManagerClass.md @@ -4,10 +4,10 @@ title: QuotaManager --- -The `4D.QuotaManager` class provides you with an interface to configure and monitor the usage limits you apply to the REST server. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. +The `4D.QuotaManager` class provides you with an interface to configure and monitor some usage limits you apply to your 4D application. Thresholds are useful for example to protect the server from poorly optimized requests or excessive use of server resources. Typically, the quota manager allows you to provide thresholds to ORDA resources a REST server session can access. -`4D.QuotaManager` objects are instantiated by the [`quotas` property of a session](./SessionClass.md#quotas) object. +`4D.QuotaManager` objects can be instantiated by the [`quotas` property of a session](./SessionClass.md#quotas) object.
History @@ -18,8 +18,6 @@ The `4D.QuotaManager` class provides you with an interface to configure and moni
-### Example - ### QuotaManager Object @@ -43,7 +41,7 @@ The `4D.QuotaManager` class provides you with an interface to configure and moni #### Description -The `.currentValues` property contains the current values related to the defined quotas properties. +The `.currentValues` property contains the current values related to the defined quotas properties. This object is automatically updated by the server. @@ -60,7 +58,7 @@ The `.defaultEntitySetTimeout` property contains a `4D.QuotaManager` object with current values (read-only) and default values (writable) for server thresholds in the current session. Server thresholds are used to control the requests to the server and help preventing excessive use of ORDA resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)). +The `.quotas` property contains a `4D.QuotaManager` object with current values and set values for server thresholds in the current session. Server thresholds are used to control the requests to the server and help preventing excessive use of resources (see [`4D.QuotaManager` class](./QuotaManagerClass.md)). This property is **read only**. @@ -745,16 +745,19 @@ The following properties of the `4D.QuotaManager` object are available for the s |Property||Type|Writable|Description| |---|---|---|---|---| -|[nbEntitySets](./QuotaManagerClass.md#nbentitysets)||Integer|yes|Maximum allowed number of entity sets in memory| +|[nbEntitySets](./QuotaManagerClass.md#nbentitysets)||Integer|yes|Maximum allowed number of entity sets in server's memory| |[defaultEntitySetTimeout](./QuotaManagerClass.md#defaultentitysettimeout) ||Integer|yes|Default inactivity timeout for entity sets in memory (seconds)| |[maxEntitySetTimeout](./QuotaManagerClass.md#maxentitysettimeout) ||Integer|yes|Maximum inactivity timeout for entity sets in memory (seconds)| |currentValues||Object|no|| -||nbEntitySets|Integer|no|Number of entity sets [currently in cache](../REST/$info.md)| -||defaultEntitySetTimeout|Integer|no|Default inactivity timeout| -||maxEntitySetTimeout|Integer|no|Maximum inactivity timeout| +||nbEntitySets|Integer|no|Number of entity sets currently in memory| When you modify a value, it is immediately taken into account by the server (no need to restart) and will be applied to further REST requests. +:::tip Related blog post + +[Make your REST server at the top of its game ... Forget throttling or crashing and tune yourself the memory usage](https://blog.4d.com/make-your-rest-server-at-the-top-of-its-game-forget-throttling-or-crashing-and-tune-yourself-the-memory-usage). + +::: #### Example @@ -767,6 +770,10 @@ Session.quotas.nbEntitySets:=50 +#### See also + +[QuotaManager class](./QuotaManagerClass.md) + diff --git a/docs/Notes/updates.md b/docs/Notes/updates.md index a7e40eb451d9f1..18e37ce6650220 100644 --- a/docs/Notes/updates.md +++ b/docs/Notes/updates.md @@ -13,6 +13,10 @@ Read [**What’s new in 4D 21 R4**](https://blog.4d.com/whats-new-in-4d-21-r4/), - New [`4D.QuotaManager`](../API/QuotaManagerClass.md) class to handle threshold objects for protecting the server. - New [`$entityset/$release`](../REST/$entityset.md#entitysetrelease) REST request to delete entity sets from server cache (the [previous syntax](../REST/$method.md#methodrelease) is deprecated). +#### Behavior changes + +- The **`GET /Employee/$entityset/?$method=release`** REST syntax is **deprecated** and should no longer be used. To delete entity sets, you must now use [`/$entityset/$release` with a POST verb](./$entityset.md). + ## 4D 21 R3 diff --git a/docs/REST/$method.md b/docs/REST/$method.md index 7b8a8ef8f68d9f..9e7be729e0bb27 100644 --- a/docs/REST/$method.md +++ b/docs/REST/$method.md @@ -14,12 +14,6 @@ This parameter allows you to define the operation to execute with the returned e |[**$method=subentityset**](#methodsubentityset)|`GET /Company(1)/staff?$expand=staff& $method=subentityset& $subOrderby=lastName ASC`|Creates an entity set based on the collection of related entities defined in the REST request| |[**$method=update**](#methodupdate)|`POST /Person/?$method=update`|Updates and/or creates one or more entities| -:::warning Deprecated - -As of 4D 21 R4, the **`GET /Employee/$entityset/?$method=release`** syntax is **deprecated** and should no longer be used. You must now use [`/$entityset/$release` with a POST verb](./$entityset.md). - -::: - ## $method=delete @@ -95,49 +89,6 @@ __ENTITYSET: "http://127.0.0.1:8081/rest/Employee/$entityset/9718A30BF61343C7963 -## $method=release - -:::warning Deprecated - -As of 4D 21 R4, the **`GET /Employee/$entityset/?$method=release`** syntax is **deprecated** and should no longer be used. You must now use [`/$entityset/$release` with a POST verb](./$entityset.md). - -::: - - - -Releases an existing entity set stored in 4D Server's cache. - -### Description - -You can release an entity set, which you created using [`$method=entityset`](#methodentityset), from 4D Server's cache. - -### Example - -Release an existing entity set: - -`GET /rest/Employee/$entityset/4C51204DD8184B65AC7D79F09A077F24?$method=release` - -#### Response: - -If the request was successful, the following response is returned: - -```json -{ - "ok": true -} -If the entity set wasn't found, an error is returned: - -{ - "__ERROR": [ - { - "message": "Error code: 1802\nEntitySet \"4C51204DD8184B65AC7D79F09A077F24\" cannot be found\ncomponent: 'dbmg'\ntask 22, name: 'HTTP connection handler'\n", - "componentSignature": "dbmg", - "errCode": 1802 - } - ] -} -``` - ## $method=subentityset diff --git a/docs/preprocessing.conf b/docs/preprocessing.conf index 84c2a0c7191049..964d8ab9ae72e6 100644 --- a/docs/preprocessing.conf +++ b/docs/preprocessing.conf @@ -1,47 +1,48 @@ -Transporter -POP3Transporter -IMAPNotifier -IMAPTransporter -SMTPTransporter -MailAttachment -Email -File -ZipFile -ZipFolder -ZipArchive -Document -Folder -CryptoKey -Function -Formula -Method +Class Collection +CryptoKey +DataClass +DataStore Directory -Signal -Session -SystemWorker +Document +Email Entity EntitySelection -DataClass -DataStore -Class -WebServer +File +FileHandle +Folder +Formula +Function HTTPAgent HTTPRequest -FileHandle -WebSocket -WebSocketServer -WebSocketConnection -WebForm -WebFormItem +IMAPNotifier +IMAPTransporter IncomingMessage +MailAttachment +Method OutgoingMessage -UDPEvent -UDPSocket +POP3Transporter +QuotaManager +Session +Signal +SMTPTransporter +SystemWorker TCPConnection TCPEvent TCPListener +Transporter +UDPEvent +UDPSocket Vector +WebForm +WebFormItem +WebServer +WebSocket +WebSocketConnection +WebSocketServer +ZipArchive +ZipFile +ZipFolder