api.utils Работа с файлами

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

Файлы, прикрепленные к атрибутам объекта типа "Текст в формате RTF", определяются по значению атрибута "Изображение из RTF-атрибута" (imgFromRTF).
Превью изображений на текущий момент времени определяются по заполненности атрибута "Оригинал" (original) у файла, прикрепленного к атрибуту типа "Текст в формате RTF".

Получение списка файлов

utils.files(obj)

Получение списка файлов, прикрепленных к объекту и атрибутам объекта типа "Файл" (кроме файлов, прикрепленных в атрибуте типа "Текст RTF").

Параметр метода:
- obj — объект, для которого отображается список файлов.
Возвращает список файлов, прикрепленных к объекту и атрибутам объекта типа "Файл", упорядоченных в хронологическом порядке (по времени добавления). При обращении к последнему элементу коллекции возвращается последний прикрепленный файл.

Не возвращает файлы, связанные с RTF-атрибутами объекта, включая превью изображений.

Пример: Получение списка файлов, прикрепленных к самому объекту, а не к его атрибутам типа "Файл" и "Текст в формате RTF":

def contentFiles = utils.files(obj).findAll{!it.relation};
utils.allFiles(obj)

Получение списка всех файлов, прикрепленных к объекту, атрибутам объекта типа "Файл" и атрибутам объекта типа "Текст в формате RTF".

Параметр метода:
- obj — объект или его uuid, для которого отображается список файлов.
Возвращает список всех файлов, прикрепленных к объекту, атрибутам объекта типа "Файл" и атрибутам объекта типа "Текст в формате RTF", упорядоченных в хронологическом порядке (по времени добавления).

При обращении к последнему элементу коллекции возвращается последний прикрепленный файл.

Не возвращает превью изображений из текста RTF.
utils.filesFromRtf(obj)

utils.filesFromRtf(obj, inPreview)

Получение списка файлов, связанных с RTF атрибутами объекта.

Параметры метода:
- obj — объект или его uuid, для которого отображается список файлов;
- inPreview:
  - true — возвращает файлы с превью изображений, если они имеются, вместо оригиналов;
  - false или параметр не указан — возвращает только файлы с изображениями в оригинальном размере.
Возвращает список всех файлов, связанных с RTF атрибутами объекта.
utils.filesFromRtf(obj, attrCode)

utils.filesFromRtf(obj, attrCode, inPreview)

Получение списка файлов, связанных с определенным RTF атрибутом объекта.

Параметры метода:
- obj — объект или его uuid, для которого отображается список файлов;
- attrCode — код атрибута типа "Текст в формате RTF";
- inPreview:
  - true — возвращает файлы с превью изображений, если они имеются, вместо оригиналов;
  - false или параметр не указан — возвращает только файлы с изображениями в оригинальном размере.
Возвращает список всех файлов, связанных с определенным RTF атрибутом объекта.

Преобразования

utils.convertFilesToBase64(text, failIfFileNotFound)

Преобразует текст, содержащий ссылки на файлы в тегах img, в список файлов в формате base64.

Размер файла ограничивается в конфигурационном файле dbaccess.properties, параметр ru.naumen.file.base64.limit (Файлы).

Параметры метода:
- text — текст картинками. String;
- failIfFileNotFound. Boolean.
  - true — возникает ошибка при отсутствии файла или при отсутствии соединения с файловым хранилищем;
  - false (по умолчанию) — ошибка не возникает. Параметр необязательный.
Возвращает текст с картинками в виде base64.

Текст возвращается как html страница (т.е. обернутым в теги <html> <body> ...</body> </html>).

Прикрепление файла

api.cache.create(name)

api.cache.create(name, limit)

api.cache.create(name, limit, lifetime)

Создать новый или получить уже имеющийся кеш с заданными параметрами.

Параметры метода:
- name — имя кеша. String;
- limit — максимальное количество элементов. Int;
- lifetime — время жизни элемента в кеше (в секундах) с момента добавления. Int.
Возвращает представление кеша в виде Map, отражает текущее состояние кеша и позволяет взаимодействовать с ним.

Пример:

def result = api.cache.create('test', 5, 15);

Поддерживаемые методы (совместимы с java.util.concurrent.ConcurrentMap):
- Object put(Object key, Object value) — добавляет значение в кеш по указанному ключу.
- Object get(Object key) — возвращает значение по ключу.
- Object remove(Object key) — удаляет значение по ключу.
- void clear() — удаляет все элементы из кеша.
Пример:
```
def cache = api.cache.create('test', 5, 15);
cache.put('key', 'value'); # добавить значение в кеш
def value = cache.get('key'); # получить значение из кеша
```
Особенности:
- Тайм-аут вытеснения будет срабатывать только после сохранения транзакции. До сохранения все объекты добавленные в кеш, включая просроченные, будут еще доступны.
- Вытеснение по максимальному размеру сработает после сохранения транзакции. До сохранения размер кеша может быть больше максимально установленного. После сохранения лишние элементы будут вытеснены.
- Объект, используемый в качестве ключа, должен корректно переопределять методы equals() и hashCode() и быть иммутабельным — то есть его состояние не должно изменяться после создания.
- Значение null не допускается.
- Не рекомендуется использовать метод clear(), если нет уверенности, что к кешу нет параллельных обращений.
- Не следует создавать кеш без ограничений по времени жизни и максимальному количеству элементов, так как это может привести к утечке памяти.

Получение содержимого файла

utils.readFileContent(file)

Получение содержимого файла (содержимое файла считывается как массив байтов).

Параметр метода:
- file — файл.
Файл не должен быть слишком большим, поскольку его содержимое загружается в оперативную память, что может негативно сказаться на производительности системы.

Рекомендации по использованию методов для прикрепления и скачивания файла в одном скрипте:
- Корректное использование.
  
  Для прикрепления файла следует использовать следующие методы:
  - utils.edit — для прикрепления файла (постоянного, временного) к атрибуту;
  - utils.attachFile(source, object) или utils.attachFile(source, attribute, object) — для прикрепления файла к указанному объекту или атрибуту объекта только в скриптах пользовательских действий по событию при обращении к файлу через параметры пользовательского действия по событию.
  В других случаях (отличных от вышеописанных) рекомендуется сначала получение содержимого файла методом utils.readFileContent, затем прикрепление этого файла методом utils.attachFile.
- Не рекомендуется: сначала прикрепление файла методом utils.attachFile, затем получение содержимого этого файла методом utils.readFileContent.
  
  После прикрепления файла его содержимое уже доступно в скрипте и повторное получение содержимого этого файла не требуется.
Особенности:
- В скрипте условия на вход в начальный статус "Зарегистрирован" (registered) содержимое файла получить нельзя, если file — это файл принадлежащий объекту, который находится в процессе создания.
Пример:
```
def file = fileList[0] // объект типа "Файл"
try
  {
  byte[] data = utils.readFileContent(file)
  }
catch(e)
  {
  logger.error "Ошибка при чтении содержимого файла из файлового хранилища"
  }
```

Получение источника данных

utils.getFileDataSource(file)

Получение источника данных (DataSource) для указанного файла.

Параметр метода:
- file — файл.