# JSClient

## Overview

The `JSClient` serves as a wrapper for a headless client, providing tools to interact with the headless client plugin. Constants like `CALLBACK_EVENT` and `CALLBACK_EXCEPTION_EVENT` help identify whether callback execution was successful or if an exception occurred.

The client enables several functionalities, such as retrieving its unique client ID, which can be used for identifying or managing the client. It supports accessing or modifying data provider values based on a specified context or active method call, ensuring precise value management.

The client allows for queuing method calls on the remote server, with / without a callbacks.Validation checks ensure that the client is still active and usable, while methods are available to gracefully or forcefully shut down the client as required.

## Constants Summarized

| Type                                                     | Name                                                    | Summary                                                                                             |
| -------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [String](/reference/servoycore/dev-api/js-lib/string.md) | [CALLBACK\_EVENT](#callback_event)                      | Constant that is returned as a JSEvent type when in the callback method when it executed normally.  |
| [String](/reference/servoycore/dev-api/js-lib/string.md) | [CALLBACK\_EXCEPTION\_EVENT](#callback_exception_event) | Constant that is returned as a JSEvent type when in the callback method when an exception occurred. |

## Methods Summarized

| Type                                                       | Name                                                                                                                                  | Summary                                                               |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [String](/reference/servoycore/dev-api/js-lib/string.md)   | [getClientID()](#getclientid)                                                                                                         | Gets the id of the client.                                            |
| [Object](/reference/servoycore/dev-api/js-lib/object.md)   | [getDataProviderValue(contextName, dataprovider)](#getdataprovidervalue-contextname-dataprovider)                                     | Get a data-provider value.                                            |
| [Object](/reference/servoycore/dev-api/js-lib/object.md)   | [getDataProviderValue(contextName, dataprovider, methodName)](#getdataprovidervalue-contextname-dataprovider-methodname)              | Get a data-provider value.                                            |
| [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) | [isValid()](#isvalid)                                                                                                                 | returns true if this client is still valid/usable.                    |
| void                                                       | [queueMethod(contextName, methodName, args)](#queuemethod-contextname-methodname-args)                                                | Queues a method call on the remote server, without a callback method. |
| void                                                       | [queueMethod(contextName, methodName, args, notifyCallBackMethod)](#queuemethod-contextname-methodname-args-notifycallbackmethod)     | Queues a method call on the remote server.                            |
| [Object](/reference/servoycore/dev-api/js-lib/object.md)   | [setDataProviderValue(contextName, dataprovider, value)](#setdataprovidervalue-contextname-dataprovider-value)                        | Set a data-provider value.                                            |
| [Object](/reference/servoycore/dev-api/js-lib/object.md)   | [setDataProviderValue(contextName, dataprovider, value, methodName)](#setdataprovidervalue-contextname-dataprovider-value-methodname) | Set a data-provider value.                                            |
| void                                                       | [shutdown()](#shutdown)                                                                                                               | closes the client.                                                    |
| void                                                       | [shutdown(force)](#shutdown-force)                                                                                                    | closes the client.                                                    |

## Constants Detailed

### CALLBACK\_EVENT

Constant that is returned as a JSEvent type when in the callback method when it executed normally.

**Type**\
[String](/reference/servoycore/dev-api/js-lib/string.md)

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	/*Queue a method where the callback can do something like this
	if (event.getType() == JSClient.CALLBACK_EVENT)
	{
		application.output("callback data, name: " + event.data);
	}
	else if (event.getType() == JSClient.CALLBACK_EXCEPTION_EVENT)
	{
		application.output("exception callback, name: " + event.data);
	}*/
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	// this calls a 'remoteMethod' on the server as a global method, because the context (first argument is set to null), you can use a formname to call a form method
	jsclient.queueMethod(null, "remoteMethod", [x], callback);
}
```

### CALLBACK\_EXCEPTION\_EVENT

Constant that is returned as a JSEvent type when in the callback method when an exception occurred.

**Type**\
[String](/reference/servoycore/dev-api/js-lib/string.md)

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	/*Queue a method where the callback can do something like this
	if (event.getType() == JSClient.CALLBACK_EVENT)
	{
		application.output("callback data, name: " + event.data);
	}
	else if (event.getType() == JSClient.CALLBACK_EXCEPTION_EVENT)
	{
		application.output("exception callback, name: " + event.data);
	}*/
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	// this calls a 'remoteMethod' on the server as a global method, because the context (first argument is set to null), you can use a formname to call a form method
	jsclient.queueMethod(null, "remoteMethod", [x], callback);
}
```

## Methods Detailed

### getClientID()

Gets the id of the client.

This client id can be used to find the client from the headless client plugin.\
Note that this client id is not the same id as the id displayed on the Aplicationb Server admin page.

**Returns:** [String](/reference/servoycore/dev-api/js-lib/string.md) The unique identifier of the client, which can be used to locate the client via the headless client plugin.

**Sample**

```js
var headlessClient = plugins.headlessclient.createClient("someSolution", "user", "pass", null);
var clientID = headlessClient.getClientID()
....
headlessClient = plugins.headlessclient.getClient(clientID);
if (headlessClient != null && headlessClient.isValid()) {
	 headlessClient.queueMethod(null, "someRemoteMethod", null, callback);
}
```

### getDataProviderValue(contextName, dataprovider)

Get a data-provider value.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **contextName** The context of the given method, null if it is global method or a form name for a form method
* [String](/reference/servoycore/dev-api/js-lib/string.md) **dataprovider** the data-provider name as seen in Servoy

**Returns:** [Object](/reference/servoycore/dev-api/js-lib/object.md) the value for the data-provider.

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	// only gets the globals.media when the 'remoteMethod' is currently executing for this client
	var value = jsclient.getDataProviderValue(null, "scopes.globals.number", 'remoteMethod');
	if (value != null)
	{
		application.output("value get from scopes.globals.number :: "+ value);
		scopes.globals.value = value+10;
		var returnValue = jsclient.setDataProviderValue(null, "scopes.globals.number", scopes.globals.value, 'remoteMethod');
		application.output("value set to scopes.globals.number previous value "+ returnValue);
	}
	else
	{
		application.output("value get from scopes.globals.number :: " + null);
	}
}
```

### getDataProviderValue(contextName, dataprovider, methodName)

Get a data-provider value.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **contextName** The context of the given method; null if it is global method or a form name for a form method.
* [String](/reference/servoycore/dev-api/js-lib/string.md) **dataprovider** the data-provider name as seen in Servoy.
* [String](/reference/servoycore/dev-api/js-lib/string.md) **methodName** if this is specified, the data-provider's value will only be returned if the specified method is running in this headless client because the currently running client requested it to. Otherwise undefined is returned.

**Returns:** [Object](/reference/servoycore/dev-api/js-lib/object.md) the value of the data-provider.

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	// only gets the globals.media when the 'remoteMethod' is currently executing for this client
	var value = jsclient.getDataProviderValue(null, "scopes.globals.number", 'remoteMethod');
	if (value != null)
	{
		application.output("value get from scopes.globals.number :: "+ value);
		scopes.globals.value = value+10;
		var returnValue = jsclient.setDataProviderValue(null, "scopes.globals.number", scopes.globals.value, 'remoteMethod');
		application.output("value set to scopes.globals.number previous value "+ returnValue);
	}
	else
	{
		application.output("value get from scopes.globals.number :: " + null);
	}
}
```

### isValid()

returns true if this client is still valid/usable.

**Returns:** [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) True if the client is still valid and usable; false otherwise.

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	/*Queue a method where the callback can do something like this
	if (event.getType() == JSClient.CALLBACK_EVENT)
	{
		application.output("callback data, name: " + event.data);
	}
	else if (event.getType() == JSClient.CALLBACK_EXCEPTION_EVENT)
	{
		application.output("exception callback, name: " + event.data);
	}*/
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	// this calls a 'remoteMethod' on the server as a global method, because the context (first argument is set to null), you can use a formname to call a form method
	jsclient.queueMethod(null, "remoteMethod", [x], callback);
}
```

### queueMethod(contextName, methodName, args)

Queues a method call on the remote server, without a callback method.\
Please note that calling queueMethod without a callback does not return anything: no result of the remote method or no exception if something went wrong.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **contextName** The context of the given method, null if it is global method or a form name for a form method.
* [String](/reference/servoycore/dev-api/js-lib/string.md) **methodName** The method name.
* [Array](/reference/servoycore/dev-api/js-lib/array.md) **args** The arguments that should be passed to the method.

**Returns:** void

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	// this calls a 'remoteMethod' on the server as a global method, because the context (first argument is set to null), you can use a formname to call a form method
	jsclient.queueMethod(null, "remoteMethod", [x]);
}
```

### queueMethod(contextName, methodName, args, notifyCallBackMethod)

Queues a method call on the remote server. The callback method will be called when the method is executed on the server\
and the return value is given as the JSEvent.data object with the JSEvent.getType() value of JSClient.CALLBACK\_EVENT.\
If an exception is thrown somewhere then the callback method will be called with\
the exception as the JSEvent data object with the JSEvent.getType() value of JSClient.CALLBACK\_EXCEPTION\_EVENT\
The second argument that is give back is the JSClient instance that did the call.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **contextName** The context of the given method, null if it is global method or a form name for a form method.
* [String](/reference/servoycore/dev-api/js-lib/string.md) **methodName** The method name.
* [Array](/reference/servoycore/dev-api/js-lib/array.md) **args** The arguments that should be passed to the method.
* [Function](/reference/servoycore/dev-api/js-lib/function.md) **notifyCallBackMethod** The callback method that is called when the execution is finished.

**Returns:** void

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	/*Queue a method where the callback can do something like this
	if (event.getType() == JSClient.CALLBACK_EVENT)
	{
		application.output("callback data, name: " + event.data);
	}
	else if (event.getType() == JSClient.CALLBACK_EXCEPTION_EVENT)
	{
		application.output("exception callback, name: " + event.data);
	}*/
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	// this calls a 'remoteMethod' on the server as a global method, because the context (first argument is set to null), you can use a formname to call a form method
	jsclient.queueMethod(null, "remoteMethod", [x], callback);
}
```

### setDataProviderValue(contextName, dataprovider, value)

Set a data-provider value.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **contextName** The context of the given method, null if it is global method or a form name for a form method.
* [String](/reference/servoycore/dev-api/js-lib/string.md) **dataprovider** the data-provider name as seen in Servoy.
* [Object](/reference/servoycore/dev-api/js-lib/object.md) **value** the value to set.

**Returns:** [Object](/reference/servoycore/dev-api/js-lib/object.md) the old value or null if no change.

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	// only gets the globals.media when the 'remoteMethod' is currently executing for this client
	var value = jsclient.getDataProviderValue(null, "scopes.globals.number", 'remoteMethod');
	if (value != null)
	{
		application.output("value get from scopes.globals.number :: "+ value);
		scopes.globals.value = value+10;
		var returnValue = jsclient.setDataProviderValue(null, "scopes.globals.number", scopes.globals.value, 'remoteMethod');
		application.output("value set to scopes.globals.number previous value "+ returnValue);
	}
	else
	{
		application.output("value get from scopes.globals.number :: " + null);
	}
}
```

### setDataProviderValue(contextName, dataprovider, value, methodName)

Set a data-provider value.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **contextName** The context of the given method, null if it is global method or a form name for a form method
* [String](/reference/servoycore/dev-api/js-lib/string.md) **dataprovider** the data-provider name as seen in Servoy
* [Object](/reference/servoycore/dev-api/js-lib/object.md) **value** the value to set
* [String](/reference/servoycore/dev-api/js-lib/string.md) **methodName** if this is specified, the data-provider's value will only be set if the specified method is running in this headless client because the currently running client requested it to. Otherwise the value is not set into the data-provider and undefined is returned.

**Returns:** [Object](/reference/servoycore/dev-api/js-lib/object.md) the old value or null if no change

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	// only gets the globals.media when the 'remoteMethod' is currently executing for this client
	var value = jsclient.getDataProviderValue(null, "scopes.globals.number", 'remoteMethod');
	if (value != null)
	{
		application.output("value get from scopes.globals.number :: "+ value);
		scopes.globals.value = value+10;
		var returnValue = jsclient.setDataProviderValue(null, "scopes.globals.number", scopes.globals.value, 'remoteMethod');
		application.output("value set to scopes.globals.number previous value "+ returnValue);
	}
	else
	{
		application.output("value get from scopes.globals.number :: " + null);
	}
}
```

### shutdown()

closes the client.

**Returns:** void

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	/*Queue a method where the callback can do something like this
	if (event.getType() == JSClient.CALLBACK_EVENT)
	{
		application.output("callback data, name: " + event.data);
	}
	else if (event.getType() == JSClient.CALLBACK_EXCEPTION_EVENT)
	{
		application.output("exception callback, name: " + event.data);
	}*/
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	// this calls a 'remoteMethod' on the server as a global method, because the context (first argument is set to null), you can use a formname to call a form method
	jsclient.queueMethod(null, "remoteMethod", [x], callback);
}
```

### shutdown(force)

closes the client.

**Parameters**

* [Boolean](/reference/servoycore/dev-api/js-lib/boolean.md) **force** ;

**Returns:** void

**Sample**

```js
if (jsclient && jsclient.isValid())
{
	/*Queue a method where the callback can do something like this
	if (event.getType() == JSClient.CALLBACK_EVENT)
	{
		application.output("callback data, name: " + event.data);
	}
	else if (event.getType() == JSClient.CALLBACK_EXCEPTION_EVENT)
	{
		application.output("exception callback, name: " + event.data);
	}*/
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	// this calls a 'remoteMethod' on the server as a global method, because the context (first argument is set to null), you can use a formname to call a form method
	jsclient.queueMethod(null, "remoteMethod", [x], callback);
}
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.servoy.com/reference/servoyextensions/server-plugins/headlessclient/jsclient.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.