# clientmanager

(plugins.clientmanager)

## Overview

The `clientmanager` plugin facilitates communication and management of connected clients in Servoy. It supports broadcasting messages using `createBroadcaster` and retrieving connected clients with `getConnectedClients`. Administrators can send messages to clients via `sendMessageToClient` or `sendMessageToAllClients` and shut down clients using `shutDownClient` or `shutDownAllClients`.

Record locks can be managed with `getLocks` and `releaseLocks`, while `isInMaintenanceMode` checks server maintenance status. The plugin also enables advanced messaging through channels with `getOrCreateBroadcaster`, making it a powerful tool for client-server management.

## **Returned Types**

[Broadcaster](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/broadcaster),[JSClientInformation](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/jsclientinformation),

## Methods Summarized

| Type                                                                                                                       | Name                                                                                                     | Summary                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Broadcaster](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/broadcaster)                 | [createBroadcaster(name, channelName, callback)](#createbroadcaster-name-channelname-callback)           | Create a broadcast object giving it a (nick)name and on a specific channel, the callback is used for getting messages of other clients on that channel The function gets 3 arguments (nickName, message, channelName) |
| [JSClientInformation](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/jsclientinformation) | [getClientInformation()](#getclientinformation)                                                          | Returns the current client JSClientInformation object.                                                                                                                                                                |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)                                                 | [getConnectedClients()](#getconnectedclients)                                                            | Returns an array of JSClientInformation elements describing the clients connected to the server.                                                                                                                      |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)                                                 | [getConnectedClients(clientInfoFilter)](#getconnectedclients-clientinfofilter)                           | Returns an array of JSClientInformation elements describing the clients connected to the server filtered by the a client info string.                                                                                 |
| [JSClientInformation](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/jsclientinformation) | [getLockedByClient(datasource, pks)](#getlockedbyclient-datasource-pks)                                  | Get client that locked the record from a specific datasource or null if record is not locked.                                                                                                                         |
| [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset)                               | [getLocks()](#getlocks)                                                                                  | Get a dataset will all locks on the server.                                                                                                                                                                           |
| [Broadcaster](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/broadcaster)                 | [getOrCreateBroadcaster(name, channelName)](#getorcreatebroadcaster-name-channelname)                    | Get a broadcast object giving it a (nick)name and on a specific channel var broadcaster = plugins.                                                                                                                    |
| [Broadcaster](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/broadcaster)                 | [getOrCreateBroadcaster(name, channelName, callback)](#getorcreatebroadcaster-name-channelname-callback) | Get a broadcast object giving it a (nick)name and on a specific channel, the callback is used for getting messages of other clients on that channel The function gets 3 arguments (nickName, message, channelName)    |
| [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date)                                                   | [getServerBuildDate()](#getserverbuilddate)                                                              |                                                                                                                                                                                                                       |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)                                             | [isInMaintenanceMode()](#isinmaintenancemode)                                                            | Returns true if the server is in maintenance mode, false otherwise.                                                                                                                                                   |
| void                                                                                                                       | [releaseLocks(clientId)](#releaselocks-clientid)                                                         | Release all locks acquired by a client WARNING: use with care                                                                                                                                                         |
| void                                                                                                                       | [sendMessageToAllClients(message)](#sendmessagetoallclients-message)                                     | Sends a message to all connected clients.                                                                                                                                                                             |
| void                                                                                                                       | [sendMessageToClient(clientId, message)](#sendmessagetoclient-clientid-message)                          | Sends a message to a specific client, identified by its clientId.                                                                                                                                                     |
| void                                                                                                                       | [shutDownAllClients()](#shutdownallclients)                                                              | Shuts down all connected clients.                                                                                                                                                                                     |
| void                                                                                                                       | [shutDownClient(clientId)](#shutdownclient-clientid)                                                     | Shuts down a specific client, identified by its clientId.                                                                                                                                                             |
| void                                                                                                                       | [shutDownClient(clientId, forceUnregister)](#shutdownclient-clientid-forceunregister)                    | Shuts down a specific client, identified by its clientId.                                                                                                                                                             |

## Methods Detailed

### createBroadcaster(name, channelName, callback)

Create a broadcast object giving it a (nick)name and on a specific channel, the callback is used for getting messages of other clients on that channel The function gets 3 arguments (nickName, message, channelName)

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** The nickname for this user on this channel
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **channelName** The channel name where should be listened to (and send messages to)
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **callback** The callback when for incomming messages

**Returns:** [Broadcaster](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/broadcaster) BroadCaster

**Sample**

```js
function callback(nickName, message, channelName) {
   application.output('message received from ' + nickName + ' on channel ' + channelName + ': ' + message)
}
var broadcaster = plugins.clientmanager.createBroadcaster("nickname", "mychatchannel", callback);
broadcaster.broadcastMessage("Hallo");
```

### getClientInformation()

Returns the current client JSClientInformation object. Note this is snapshot information, client information will not get updated.

**Returns:** [JSClientInformation](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/jsclientinformation) A JSClientInformation object containing snapshot information about the current client, or null if the information cannot be retrieved.

### getConnectedClients()

Returns an array of JSClientInformation elements describing the clients connected to the server. Note this is snapshot information on connected clients, client information will not get updated.

**Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) JSClientInformation\[]

**Sample**

```js
//Returns an array of JSClientInformation elements describing the clients connected to the server.
var clients = plugins.clientmanager.getConnectedClients();
application.output("There are " + clients.length + " connected clients.");
for (var i = 0; i < clients.length; i++)
	application.output("Client has clientId '" + clients[i].getClientID() + "' and has connected from host '" + clients[i].getHostAddress() + "'.");
```

### getConnectedClients(clientInfoFilter)

Returns an array of JSClientInformation elements describing the clients connected to the server filtered by the a client info string.\
This way you can ask for a specific set of clients that have a specific information added to there client information.\
Note this is snapshot information on connected clients, client information will not get updated.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **clientInfoFilter** The filter string

**Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) JSClientInformation\[]

**Sample**

```js
//Returns an array of JSClientInformation elements describing the clients connected to the server.
var clients = plugins.clientmanager.getConnectedClients();
application.output("There are " + clients.length + " connected clients.");
for (var i = 0; i < clients.length; i++)
	application.output("Client has clientId '" + clients[i].getClientID() + "' and has connected from host '" + clients[i].getHostAddress() + "'.");
```

### getLockedByClient(datasource, pks)

Get client that locked the record from a specific datasource or null if record is not locked.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **datasource** ;
* [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **pks** ;

**Returns:** [JSClientInformation](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/jsclientinformation) Client information

**Sample**

```js
var client = plugins.clientmanager.getLockedByClient(foundset.getDataSource(),record.getPKs());
```

### getLocks()

Get a dataset will all locks on the server. The dataset will have four columns: datasource, acquireDate, clientId, pkHash.\
Each row in the dataset will be a lock.

**Returns:** [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset) A dataset containing all locks on the server, with columns for datasource, acquireDate, clientId, and pkHash.

**Sample**

```js
var locks = plugins.clientmanager.getLocks();
```

### getOrCreateBroadcaster(name, channelName)

Get a broadcast object giving it a (nick)name and on a specific channel var broadcaster = plugins.clientmanager.getBroadcaster("nickname", "mychatchannel"); broadcaster.broadcastMessage("Hallo");

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** The nickname for this user on this channel
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **channelName** The channel name where should be listened to (and send messages to)

**Returns:** [Broadcaster](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/broadcaster) BroadCaster

### getOrCreateBroadcaster(name, channelName, callback)

Get a broadcast object giving it a (nick)name and on a specific channel, the callback is used for getting messages of other clients on that channel The function gets 3 arguments (nickName, message, channelName)

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **name** The nickname for this user on this channel
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **channelName** The channel name where should be listened to (and send messages to)
* [Function](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/function) **callback** The callback when for incomming messages

**Returns:** [Broadcaster](https://docs.servoy.com/reference/servoyextensions/server-plugins/clientmanager/broadcaster) BroadCaster

**Sample**

```js
function callback(nickName, message, channelName) {
   application.output('message received from ' + nickName + ' on channel ' + channelName + ': ' + message)
}
var broadcaster = plugins.clientmanager.getBroadcaster("nickname", "mychatchannel", callback);
broadcaster.broadcastMessage("Hallo");
```

### getServerBuildDate()

**Returns:** [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) The server build date as a Date object, or null if the information cannot be retrieved.

### isInMaintenanceMode()

Returns true if the server is in maintenance mode, false otherwise.

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) true if the server is in maintenance mode, false otherwise.

**Sample**

```js
//Returns true if the server is in maintenance mode, false otherwise.
if (plugins.clientmanager.isInMaintenanceMode())
 application.output("Server is in maintenance mode.");
else
 application.output("Server is not in maintenance mode.");
```

### releaseLocks(clientId)

Release all locks acquired by a client

WARNING: use with care

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **clientId** ;

**Returns:** void

### sendMessageToAllClients(message)

Sends a message to all connected clients.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **message** ;

**Returns:** void

**Sample**

```js
//Sends a message to all connected clients.
plugins.clientmanager.sendMessageToAllClients("Hello, all clients!");
```

### sendMessageToClient(clientId, message)

Sends a message to a specific client, identified by its clientId. The clientIds are retrieved by calling the getConnectedClients method.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **clientId** ;
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **message** ;

**Returns:** void

**Sample**

```js
//Sends a message to a specific client, identified by its clientId. The clientIds are retrieved by calling the getConnectedClients method.
var clients = plugins.clientmanager.getConnectedClients();
for (var i=0; i<clients.length; i++)
	plugins.clientmanager.sendMessageToClient(clients[i].getClientId(), "Hello, client " + clients[i].getClientID() + "!");
```

### shutDownAllClients()

Shuts down all connected clients. This method returns immediately, it does not wait until the client shuts down.

**Returns:** void

**Sample**

```js
//Shuts down all connected clients. This method returns immediately, it does not wait until the client shuts down.
plugins.clientmanager.shutDownAllClients();
```

### shutDownClient(clientId)

Shuts down a specific client, identified by its clientId. The clientIds are retrieved by calling the getConnectedClients method. This method returns immediately, it does not wait until the client shuts down.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **clientId** ;

**Returns:** void

**Sample**

```js
//Shuts down a specific client, identified by its clientId. The clientIds are retrieved by calling the getConnectedClients method. This method returns immediately, it does not wait until the client shuts down.
var clients = plugins.clientmanager.getConnectedClients();
for (var i=0; i<clients.length; i++)
	plugins.clientmanager.shutDownClient(clients[i].getClientId());
```

### shutDownClient(clientId, forceUnregister)

Shuts down a specific client, identified by its clientId. The clientIds are retrieved by calling the getConnectedClients method. This method returns immediately, it does not wait until the client shuts down.\
If forceUnregister is true, the client will unregister itself from server. Beware this should be used only if you are sure client is already closed (cannot connect anymore)

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **clientId** ;
* [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) **forceUnregister** client is forced to unregister from server

**Returns:** void

**Sample**

```js
//Shuts down a specific client, identified by its clientId. The clientIds are retrieved by calling the getConnectedClients method. This method returns immediately, it does not wait until the client shuts down.
var clients = plugins.clientmanager.getConnectedClients();
for (var i=0; i<clients.length; i++)
	plugins.clientmanager.shutDownClient(clients[i].getClientId());
```

***