Перейти к основному содержанию
`Ctrl`+`K`

# Jexl через SOAP и REST

## Jexl через SOAP XML

В Global 3 SE Server реализован SOAP XML-сервис, позволяющий выполнять Jexl-скрипты в контексте пользовательской сессии.

### Аутентификация

Читайте в разделе Аутентификация в REST/SOAP-сервисах.

### Схемы

WSDL-описание сервиса доступно по адресу:

    http://{server:port}/app/sys/soap/sys-service-1.0.0?wsdl

XSD-схемы POJO запроса и ответа доступны по адресу:

    http://{server:port}/app/sys/soap/sys-service-1.0.0?xsd=1

### Передача бинарных данных с использованием MTOM

Сервис поддерживает оптимизированную передачу бинарных данных в сервис и обратно через поля `attachment` объектов `JexlSoapRequest` и `JexlSoapResponse`.

### Доступ к данным SOAP-запроса из прикладного кода

В прикладном коде Api-/Pkg-классов, выполняющемся в результате вызова Jexl-скрипта из SOAP-сервиса, доступен объект `SoapContext`. `SoapContext` предоставляет доступ к данным SOAP-запроса и SOAP-ответа.

Для получения контекста выполните:

    val soapContextOpt = SoapContext()

Методы, доступные в `SoapContext`:

- `hasInputAttachment: Boolean` — указывает на наличие у SOAP-запроса прикреплённых с использованием MTOM бинарных данных.

- `getInputData: String` — возвращает строковые данные SOAP-запроса.

- `forInputStream(foo: InputStream => Unit): Unit` — предоставляет доступ к прикреплённым бинарным данным.

- `setOutputData(data: String): Unit` — устанавливает строковые данные в SOAP-ответ.

- `forOutputStream(foo: OutputStream => Unit): Unit` — предоставляет доступ к выходному потоку бинарных данных, передаваемых средствами MTOM.

### Методы обработки данных SOAP-запроса из Jexl-скрипта

В пакете `Gtk_SoapPkg` хранятся методы, использующие `SoapContext`:

- `setOutputData(value: AnyRef): Unit` — устанавливает вывод результата выполнения SOAP-запроса.

- `inputStreamToTemp: File` — создаёт временный файл с данными из прикреплённых данных SOAP-запроса.

- `attachFile(file: File): Unit` — принимает файл, закачивает его данные в выходной поток бинарных данных SOAP-запроса.

Пример использования из Jexl-скрипта:

    var f = new("java.io.File", 'C:\users\userName\data.txt');
    Gtk_SoapPkg.setOutputData('Данные в прикрепленном файле');
    Gtk_SoapPkg.attachFile(f);

Данный скрипт, отправленный через SOAP-запрос, в ответ запишет:

- в `data` — строку `'Данные в прикрепленном файле'`;

- в `attachment` — закодированный base64 файл.

## Jexl через REST API сервис с использованием прикладных пакетов

В Global 3 SE Server реализован REST API-сервис, позволяющий выполнять Jexl-скрипты в контексте пользовательской сессии. В данной главе описывается выполнение Jexl-скриптов с использованием прикладных пакетов, наследуемых от `RestPkg`.

Выполнение Jexl в контексте главной выборки приложения описано в отдельной главе.

### Аутентификация

Читайте в разделе Аутентификация в REST/SOAP-сервисах.

### Адреса

Доступно с AS 1.14 RC7:

- `http://{server:port}/app/sys/rest/es/pkg/Btk_JexlGatePkg/execute`

- `http://{server:port}/app/sys/rest/ss/pkg/Btk_JexlGatePkg/execute`

где:

- `{server:port}` — адрес подключения к серверу;

- `app/sys` — системный прикладной модуль;

- `rest` — шлюз для REST-запросов;

- `es` / `ss` — группировка по времени жизни GTK-сессии (Exclusive Session) / Shared Session;

- `pkg` — узел для доступа к пакетам;

- `Btk_JexlGatePkg` — имя прикладного пакета, предназначенного для выполнения Jexl-скриптов (подробнее о REST-пакетах).

### Администрирование выполнения Jexl-скриптов

Администрирование выполнения Jexl-скриптов осуществляется через право роли на «Функции Jexl». Также можно отдельно ограничить доступ роли к `Btk_JexlGatePkg`.

### Структура запроса

Тело POST-запроса имеет вид:

    {
        "jexl": "jexl-скрипт"
    }

### Формат результата выполнения команды

Результатом выполнения команды является строка в формате JSON:

    {
        "exception": null,
        "exceptionStack": null,
        "data": null,
        "success": true,
        "exceptionName": null
    }

где:

- `exception` — сообщение возникшего исключения: `null` | `"string"`;

- `exceptionStack` — стек возникшего исключения: `null` | `"string"`;

- `success` — флаг успешности выполнения команды: `true` | `false`;

- `data` — результат выполнения команды: `null` | `"string"` | `JSON` | `Boolean`;

- `exceptionName` — имя класса исключения: `null` | `"string"`.

### Пример использования

Для выполнения Jexl-скрипта будем использовать пакет `Btk_JexlGatePkg` и Shared Session. Тогда адрес запроса будет выглядеть так:

    http://localhost:8080/app/sys/rest/ss/pkg/Btk_JexlGatePkg/execute

В качестве примера Jexl-скрипт будет выполнять проверку, является ли пользователь супер-пользователем:

    {
        "jexl": "Btk_UserApi.isSuperUser()"
    }

После выполнения POST-запроса сервер вернёт ответ:

    {
        "exception": null,
        "exceptionStack": null,
        "data": false,
        "success": true,
        "exceptionName": null
    }

Запрос выполнился без ошибок, и Jexl-скрипт вернул значение `false`.

### Ограничения

Время выполнения Jexl-скрипта ограничено временем жизни сессии.
Размер Jexl-скрипта не ограничен.