rest_ws

(plugins.rest_ws)

Overview

The rest_ws client represents a REST-WS client instance, valid only during a running REST-WS request. It provides methods for managing HTTP cookies, accessing the current request and response, checking request status, and controlling the inclusion of user properties in response headers.

The createCookie(name, value) method creates an HTTP cookie using specified name and value parameters, which must conform to the cookie specification. The resulting WsCookie object can be added to a response using getResponse(). The getRequest() and getResponse() methods provide access to the current REST-WS request and its corresponding response. These methods throw exceptions if invoked outside a REST-WS context, ensuring accurate usage within valid workflows.

To determine if the client is running in a REST-WS context, isRunningRequest() returns a boolean value. When enabled, this facilitates conditional logic based on the REST-WS state.

Finally, the sendResponseUserPropertiesHeaders(send) method enables or disables the inclusion of user properties as response headers. By default, these headers are sent, but this behavior can be controlled using the send parameter.

Properties

Property	Description
rest_ws_plugin_authorized_groups	Only authenticated users in the listed groups (comma-separated) have access, when left empty unauthorised access is allowed
rest_ws_send_user_properties_headers	This is a global setting to specify if the user properties are generated as header values on the REST responses. It can also be set in the rest ws plugin ws_* methods. Default is true.
rest_ws_use_jsupload_for_binary_data	Convert binary uploads (multipart or pure byte uploads) to a JSUpload that is cached on disk if they are bigger then a threshold (servoy.ng_web_client.tempfile.threshold property), default 'true'
rest_ws_plugin_client_pool_size	Max number of clients per solution used (this defines the number of concurrent requests and licences used per solution), default = 5. The same value is used for maximum number of idle clients. In case of rest_ws_plugin_client_pool_exhausted_action=grow, the number of clients may become higher. When running in developer this setting is ignored, pool size will always be 1
rest_ws_plugin_client_pool_exhausted_action	The following values are supported for this setting:
block (default): requests will wait untill a client becomes available, when running in developer this value will be used
fail: the request will fail. The API will generate a SERVICE_UNAVAILABLE response (HTTP 503)
grow: allows the pool to grow, by starting additional clients. The number of clients per solution may become higher than defined by setting 'rest_ws_plugin_client_pool_size', but will shrink back to that value when clients in the pool become idle.
rest_ws_plugin_client_max_grow_pool_size	This value is only used when rest_ws_plugin_client_pool_exhausted_action=grow, and it defines the total number of clients to which the pool grows, after this value the pool will block. By default is not defined.

Methods Summarized

Type	Name	Summary
WsCookie	createCookie(name, value)	Create a http cookie.
WsRequest	getRequest()	Get the currently running REST-WS request.
WsResponse	getResponse()	Get the response for the currently running REST-WS request.
Boolean	isRunningRequest()	Check whether the client is currently running a REST-WS request.
void	sendResponseUserPropertiesHeaders(send)	Allow or block sending the user properties as response header values.

Methods Detailed

createCookie(name, value)

Create a http cookie. The cookie name and value allows only a sequence of non-special, non-white space characters, see the cookie spec https://tools.ietf.org/html/rfc2965

Parameters

• String name The name of the cookie

• String value The value of the cookie

Returns: WsCookie A `WsCookie` object representing the created HTTP cookie.

Sample

var cookie = plugins.rest_ws.createCookie('chocolate', 'chip');
var response = plugins.rest_ws.getResponse();
response.addCookie(cookie);

getRequest()

Get the currently running REST-WS request. If the client is not currently running in REST-WS, an exception is thrown.

Returns: WsRequest The currently active REST-WS request as a `WsRequest` object.

getResponse()

Get the response for the currently running REST-WS request. If the client is not currently running in REST-WS, an exception is thrown.

Returns: WsResponse The response associated with the currently active REST-WS request as a `WsResponse` object.

Sample

var response = plugins.rest_ws.getResponse();
resp.setHeader("My-Custom-Header", "42");

isRunningRequest()

Check whether the client is currently running a REST-WS request. If false, the rest-ws client-plugin features are not available.

Returns: Boolean true if the client is currently handling a REST-WS request, false otherwise.

sendResponseUserPropertiesHeaders(send)

Allow or block sending the user properties as response header values. By default the response headers contain the user properties.

Parameters

• Boolean send ;

Returns: void

---