Работа с файлами в системе

Содержание

Работа с файлами в системе#

Документ описывает общую логику работы с файлами в системе: где и как они хранятся, какие объекты и API участвуют в их создании и использовании, как файл проходит путь от загрузки до сохранения в файловом хранилище.

Сначала описаны общая схема работы с файлами и основные сущности, затем подробно рассматриваются файловые хранилища, сервис прикрепленных файлов, объект Btk_File, файловое API и связанные механизмы.

Общая схема работы с файлами#

Файлы в системе не хранятся в базе данных. Для их хранения используются файловые хранилища, доступные серверам приложений как внешние ресурсы. В зависимости от конфигурации системы такие хранилища могут быть подключены к серверу приложений и использоваться как доступные ему локальные диски или иные внешние файловые ресурсы.

Работа с файлами в системе строится вокруг нескольких уровней:

  • файловые хранилища — определяют, где физически хранится файл;

  • файловое API — используется в коде для создания, записи, чтения и проверки файлов;

  • сервис прикрепленных файлов — связывает файл с объектом системы и определяет режим работы с прикрепленными файлами. В его модели используются объекты Btk_Attach, Btk_AttachVer и Btk_AttachItem;

  • объект Btk_File — хранит метаинформацию о файле в базе данных.

Общая схема работы с файлом выглядит так:

  1. В коде или через пользовательский интерфейс инициируется операция работы с файлом. Это может быть прикрепление файла через интерфейс, а также вызов файлового API для создания, записи, чтения, скачивания, перемещения или удаления файла.

  2. Система определяет файловое хранилище, в которое должен быть записан файл.

  3. В базе данных создается запись о файле.

  4. Физическое содержимое файла записывается в файловое хранилище.

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

  6. При необходимости файл становится доступен пользователю через операции интерфейса и механизмы выдачи файлов, реализованные в системе.

Файловые хранилища#

База данных и файловое хранилище — это разные системы. Операция записи в базу данных и операция записи физического файла в файловое хранилище не образуют единую транзакцию.

Из-за этого в системе возможны ситуации рассинхрона, когда запись о файле в базе данных уже создана или удалена, а физический файл в файловом хранилище еще существует или уже удален.

Система использует справочник файловых хранилищ для классификации мест хранения файлов и для выбора конкретного хранилища при сохранении файла.

В системе реализованы следующие типы файловых хранилищ:

  • Локальное (FileStorageFileImpl) — использует файловый ресурс, доступный серверу приложений как локальный диск;

  • REST File Server (FileStorageRestImpl) — использует внешний файловый сервер, доступный по REST;

  • S3 протокол (S3FileStorageImpl) — использует объектное хранилище, доступное по протоколу S3.

Файловое хранилище в системе — это не только запись в справочнике, но и программная абстракция, через которую выполняются операции с физическими файлами. Для работы с физическим содержимым файла используются абстракции FileStorage и File, а также их реализации для разных типов файловых хранилищ, например локального хранилища, REST File Server и S3.

Настройка файловых хранилищ выполняется в приложении «Настройка системы» по пути Сущности > Файловые хранилища.

В системе должно быть настроено минимум два хранилища:

  • Default — хранилище по умолчанию;

  • btkAttach — хранилище прикрепленных файлов.

Распределение файлов по хранилищам#

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

При работе с файлами система может определять файловое хранилище автоматически или использовать файловое хранилище, явно заданное в коде. Разработчик указывает системное имя файлового хранилища в файловом API.

Общая логика выбора файлового хранилища следующая:

  1. Сначала система проверяет настройки распределения файлов.

  2. Если поля, участвующие в распределении, не заполнены или по настройкам распределения не удалось определить подходящее файловое хранилище, используется файловое хранилище, указанное в файловом API.

  3. Если файловое хранилище не указано в файловом API, используется файловое хранилище, объявленное в системе как хранилище по умолчанию.

Настройки распределения задаются на вкладке «Распределение файлов по типам» в карточке файлового хранилища. Эта вкладка используется для первого этапа выбора файлового хранилища — по параметрам документа.

Для распределения используются параметры тип документа, тип файла, класс, подкласс и модуль. Параметр модуль определяется по принадлежности класса объекта-источника модулю Btk_Class.idModule. Каждое поле в настройке файлового хранилища может быть задано сразу для нескольких значений.

Поиск подходящего файлового хранилища по настройкам распределения выполняется последовательно, от более точного условия к более общему. Приоритет поиска следующий:

  1. тип документа + тип файла;

  2. тип документа;

  3. подкласс + тип файла

  4. подкласс

  5. класс + тип файла;

  6. класс;

  7. модуль + тип файла;

  8. модуль.

Примечание

Если по алгоритму найдено несколько подходящих файловых хранилищ, используется файловое хранилище с минимальным id. На практике это соответствует выбору хранилища, созданного раньше остальных.

Если документ перемещен вручную, chooseFileStorage(...) использует файловое хранилище, переданное в параметрах, либо btkAttach, если хранилище не передано. В остальных случаях файловое хранилище подбирается по настройкам распределения файлов по типам.

Если требуется новое файловое хранилище или новое место расположения файлов, можно создать новое файловое хранилище, задать в нем нужные параметры распределения и, при необходимости, использовать его в файловом API или назначить файловым хранилищем по умолчанию. После этого файлы будут помещаться в него автоматически в соответствии с заданной логикой выбора.

Контекст подбора файлового хранилища#

Для точечного изменения стандартного подбора файлового хранилища используется метод withFileStorageContext. Заданные через него параметры учитываются операциями с файлами, поддерживающими файловый контекст, внутри переданного блока кода.

Логика работы метода:

  • Устанавливает переданные параметры в активный контекст для текущего потока выполнения.

  • Выполняет переданный блок кода с учетом параметров контекста.

  • Сбрасывает параметры контекста в None после завершения блока.

Метод поддерживает следующие параметры контекста:

Параметр

Описание

idSrcObjectType

Идентификатор типа исходного объекта. Соответствует параметру idpSrcObjectType файловой операции.

idAttachFileType

Идентификатор типа прикрепленного файла. Соответствует параметру idpAttachFileType файловой операции.

idClassDoc

Идентификатор класса документа. Соответствует параметру idpClassDoc файловой операции.

gidSrc

Глобальный идентификатор исходного объекта. Соответствует параметру gidpSrc файловой операции.

idFileStorage

Идентификатор файлового хранилища. При наличии значения хранилище определяется напрямую, без вызова chooseFileStorage.

Значения, заданные в файловом контексте, имеют приоритет над соответствующими параметрами файловой операции. Если значение в контексте отсутствует, используется параметр операции.

Пример принудительного выбора хранилища:

val idavFile = Btk_FileLib().withFileStorageContext(
  idpFileStorage = Wf_Lib().idFileStorageWf
) {
  Btk_FileLib().uploadFiles(
    idpFileStorage = idFileStorageWf,
    gidpSrc = gidpSrc,
    idpSrcObjectType = Btk_ObjectPkg().getIdObjectType(gidpSrc)
  )
}

В примере хранилище задается через withFileStorageContext. Поэтому значение idpFileStorage, переданное непосредственно в uploadFiles, не влияет на выбор хранилища.

Приоритет значений контекста реализован следующим образом:

val jFSCtx = getFileStorageContext()

val idvFileStorage = jFSCtx.idFileStorage.nvl(
  Btk_FilePkg().chooseFileStorage(
    idpAttachFileType = jFSCtx.idAttachFileType.nvl(idpAttachFileType),
    idpSrcObjectType = jFSCtx.idSrcObjectType.nvl(idpSrcObjectType),
    gidpSrc = jFSCtx.gidSrc.nvl(gidpSrc),
    idpFileStorage = idpFileStorage,
    idpClassDoc = jFSCtx.idClassDoc.nvl(idpClassDoc),
    bpManualMoved = bpManualMoved,
    bpTemp = bpTemp
  )
)

Если idFileStorage отсутствует в контексте, вызывается chooseFileStorage. Его параметры формируются из значений контекста, а при их отсутствии — из аргументов файловой операции.

В основе механизма находится метод setFileStorageContext, который записывает переданные параметры в активный контекст. Метод withFileStorageContext устанавливает и очищает контекст при выполнении блока кода.

Примечание

Файловый контекст применяется для отдельных операций, в которых требуется изменить стандартный подбор хранилища. Для постоянной маршрутизации файлов используются настройки распределения файлов по хранилищам.

Настройка очистки хранилища от устаревших файлов#

Для очистки устаревших файлов в системе используется настройка Btk_FileStorageCleanSetting. Она поддерживает два варианта работы:

  • удаление файла из хранилища;

  • перемещение файла в указанное файловое хранилище, используемое как архив.

Действие Удалить использует стандартное удаление с учетом настроек файловой корзины. Подробное описание результата удаления приведено в разделе Удаление файла, а настройки корзины — в разделе Файловая корзина.

Действие Переместить автоматически переносит файл в указанное файловое хранилище. Файлы, которые пользователь ранее переместил вручную, повторно автоматически не перемещаются. При этом к ним может применяться правило с действием Удалить.

Для настройки очистки файлового хранилища используется вкладка «Настройка очистки хранилища от устаревших файлов».

На вкладке можно задать:

  • Срок хранения в днях — количество дней с даты последнего изменения записи о файле, а при ее отсутствии — с даты создания записи;

  • Действие — действие, которое применяется при очистке хранилища. Возможны два варианта: Удалить или Переместить;

  • Хранилище для перемещения — файловое хранилище, в которое перемещается файл, если выбрано действие Переместить;

  • Тип вложения — тип прикрепленных файлов, для которых применяется указанное действие;

  • Тип объекта — тип объекта-источника файла;

  • Подкласс — подкласс объекта-источника файла;

  • Класс документа — класс документа-источника файла;

  • Модуль — модуль, к которому относится класс объекта-источника файла.

Пустое значение критерия означает, что настройка применяется к любому значению этого критерия. Система использует только настройки, в которых срок хранения больше 0 и задано действие. Для действия Переместить также должно быть задано хранилище для перемещения.

Если одному файлу соответствуют несколько настроек очистки, система применяет одно наиболее приоритетное правило. Приоритет определяют заполненные критерии в следующем порядке:

  1. Тип объекта.

  2. Подкласс.

  3. Класс документа.

  4. Модуль.

  5. Тип вложения.

Таким образом, настройка с заполненным критерием более высокого уровня имеет приоритет над настройкой, в которой этот критерий не задан.

Внимание

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

Администрирование файловых хранилищ#

Для контроля содержимого файловых хранилищ и выполнения операций с файлами используется раздел «Администрирование файловых хранилищ».

Путь: Приложение > Настройка системы > Сущности > Администрирование файловых хранилищ.

В левой части окна отображается список файловых хранилищ системы. При выборе файлового хранилища открывается список файлов, которые в нем находятся.

Для каждого файла отображаются:

  • имя файла;

  • тип объекта-источника;

  • объект-источник;

  • тип прикрепленного файла;

  • создатель;

  • дата создания;

  • наличие вложений;

  • размер.

В списке файлов доступны следующие операции:

  • Удалить — окончательно удаляет выбранный файл, находящийся в файловой корзине;

  • Открыть карточку объекта-источника — открывает карточку объекта, с которым связан файл;

  • Переместить в другое хранилище — перемещает выбранный файл в другое файловое хранилище.

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

Для выбранного файлового хранилища в меню «Дополнительно» доступны следующие операции:

  • Запуск задания по удалению/перемещению по расписанию — создает одноразовый запуск задания «Актуализация расположения файлов в файловых хранилищах». Очистка устаревших файлов выполняется в конце этого задания;

  • Отчет по планируемому удалению — открывает ограниченный отчет по файлам, для которых настроено действие Удалить.

Задание «Актуализация расположения файлов в файловых хранилищах» должно быть зарегистрировано в менеджере заданий.

Внимание

Отчет по планируемому удалению не показывает перемещения и не учитывает все критерии и правила приоритета, используемые актуальным механизмом очистки. Не используйте отчет как точный предварительный результат следующего запуска задания.

Сервис прикрепленных файлов#

Сервис прикрепленных файлов отвечает за прикрепление файлов к объектам системы и за режим работы с прикрепленными файлами.

Сервис прикрепленных файлов позволяет прикреплять к объектам класса произвольные файлы, которые сохраняются в файловом хранилище и сопоставляются с конечным объектом-владельцем.

Сервис прикрепления файлов определяет, как выполняется работа с прикрепленными файлами. Режим работы сервиса определяет, сохраняется ли история изменений файла.

Для минимизации объема хранилища используется алгоритм, позволяющий нескольким объектам ссылаться на один физический файл:

  • файл загружается в хранилище только один раз;

  • при копировании объектов создается символическая ссылка через btk_attachitem, а не физическая копия.

При создании прикрепленного файла формируются следующие объекты:

  • Btk_File — центральный объект, в котором хранится метаинформация о файле в базе данных. Физическое содержимое файла хранится не в самом Btk_File, а в файловом хранилище. Объект Btk_File связывает запись о файле в базе данных с его физическим хранением.

  • Btk_Attach — объект прикрепленного файла. Он относится к сервису прикрепленных файлов, хранит данные о прикрепленном файле и используется в логике отображения файла пользователю и работы сервиса прикрепленных файлов.

  • Btk_AttachVer — объект версии прикрепленного файла. Он ссылается на Btk_Attach и содержит ссылку на Btk_File, то есть на запись о физическом файле. Если для сервиса прикрепления файлов включена версионность, при каждом изменении файла создается новая запись Btk_AttachVer.

  • Btk_AttachItem — объект связи, который связывает прикрепленный файл Btk_Attach с объектом системы.

Таким образом, при загрузке файла в системе создается не одна запись, а набор связанных объектов. Btk_File отвечает за хранение сведений о физическом файле и его связи с файловым хранилищем, Btk_Attach представляет файл в сервисе прикрепленных файлов, Btk_AttachVer отвечает за версионность, а Btk_AttachItem связывает прикрепленный файл с объектом системы.

В режиме simple для прикрепленного файла всегда хранится одна версия. В режиме versioned при каждом изменении создается новая запись Btk_AttachVer.

Настройка сервиса прикрепления файлов#

По умолчанию сервис прикрепленных файлов для класса отключен. Для его подключения и выбора режима работы в ODM-файле класса указывается тип хранения:

<class xmlns="http://www.global-system.ru/xsd/global3-class-1.0"
       name="Gds_ControlDoc"
       caption="Документ контроля"
       cardEditor.representation="Card"
       listEditor.representation="List"
       viewOptions.openCardType="mdi"
       supertype="document"
       attachType="versioned"/>

Параметр attachType определяет режим работы сервиса прикрепления файлов для класса:

  • simple — простое хранение;

  • versioned — версионное хранение.

После генерации AVM-файла во все отображения (Card, List, Tree) автоматически добавляется закладка «Прикрепленные файлы».

Режимы работы сервиса прикрепления файлов#

Для сервиса прикрепления файлов (Attach) поддерживаются два режима работы:

  • простой;

  • версионный.

Режим работы настраивается не для конкретного файлового хранилища, а для сервиса прикрепления файлов у класса. Одно файловое хранилище может содержать файлы с разными режимами хранения. Это связано с тем, что файловое хранилище выбирается по правилам распределения, а режим работы с прикрепленными файлами настраивается отдельно — на уровне сервиса прикрепления файлов (Attach).

Простое хранение файлов#

Простое хранение — это режим работы сервиса прикрепления файлов (Attach) без хранения истории изменений. Это частный случай версионного хранения с одной версией: любое изменение приводит к перезаписи файла.

Доступные операции:

  • Прикрепить файл — в хранилище добавляется новый файл, в закладке отображается запись с флагом «Основной».

  • Удаление — удаляется запись из закладки. Если запись отмечена как основная, выполняется удаление связанного прикрепленного файла.

  • Скачать файл — из хранилища скачивается файл с именем и расширением, указанными в записи.

  • Сделать файл основным — устанавливается флаг «Основной». У предыдущей основной записи флаг снимается.

При копировании родительской записи копируются и записи прикрепленных файлов, но без флага «Основной».

Версионное хранение файлов#

Версионное хранение — это режим работы сервиса прикрепления файлов (Attach), при котором сохраняется история изменений. Любое изменение файла создает новую версию.

Доступны все операции простого хранения, а также:

  • Добавить новую версию — к записи добавляется версия; предыдущие сохраняются.

  • Удалить последнюю версию — удаляется последняя версия. Если версия одна, предлагается удалить всю запись.

  • Отобразить историю изменений — открывается список версий. Для каждой доступны операции скачивания и удаления.

При копировании родительской записи по умолчанию копируются и записи Btk_Attach. Вместе с ними копируются прикрепленные файлы, а для версионного хранения — все версии файла. Флаг «Основной» при этом не переносится.

Основные сценарии работы с файлами#

В системе с файлами выполняются три основных сценария:

  • загрузка файла;

  • просмотр, скачивание и получение файла для редактирования;

  • удаление файла.

Загрузка файла#

Загрузка файла через кнопку загрузки в сервисе прикрепленных файлов выполняется следующим образом:

  1. Пользователь нажимает кнопку загрузки файла в закладке «Прикрепленные файлы».

  2. Система получает файл и через файловое API определяет файловое хранилище, в которое его нужно сохранить.

  3. В базе данных создается запись Btk_File, в которой сохраняется метаинформация о файле.

  4. Для файла формируется полное имя и контекст хранения.

  5. Содержимое файла записывается в файловое хранилище.

  6. После записи файла создаются и связываются объекты сервиса прикрепленных файлов.

При загрузке прикрепленного файла формируются следующие объекты:

  • Btk_File — центральный объект, в котором хранится метаинформация о файле в базе данных. Физическое содержимое файла хранится не в самом Btk_File, а в файловом хранилище. Объект Btk_File связывает запись о файле в базе данных с его физическим хранением;

  • Btk_Attach — объект прикрепленного файла. Он относится к сервису прикрепленных файлов, хранит данные о прикрепленном файле и используется в логике отображения файла пользователю и работы сервиса прикрепленных файлов;

  • Btk_AttachVer — объект версии прикрепленного файла. Он ссылается на Btk_Attach и содержит ссылку на Btk_File, то есть на запись о физическом файле. Если для сервиса прикрепления файлов включена версионность, при каждом изменении файла создается новая запись Btk_AttachVer;

  • Btk_AttachItem — объект связи, который связывает прикрепленный файл Btk_Attach с объектом системы.

Таким образом, при загрузке файла через сервис прикрепленных файлов в системе создается не одна запись, а набор связанных объектов. Btk_File отвечает за хранение сведений о физическом файле и его связи с файловым хранилищем, Btk_Attach представляет файл в сервисе прикрепленных файлов, Btk_AttachVer отвечает за версионность, а Btk_AttachItem связывает прикрепленный файл с объектом системы.

В режиме simple для прикрепленного файла всегда хранится одна версия. В режиме versioned при каждом изменении создается новая запись Btk_AttachVer.

Ограничения на размер и формат файлов#

В системе можно настроить ограничения на размер и формат файлов. Эти ограничения используются для контроля загрузки файлов в файловое хранилище и получения файлов из него.

По умолчанию оба ограничения выключены.

Настройка ограничений выполняется в приложении «Настройка приложения» по пути Настройки и сервисы > Настройка модулей системы > Общие настройки модулей > Btk > Файлы.

Доступны следующие настройки:

  • Ограничение расширений загружаемых файлов — определяет ограничения на загрузку файлов по их расширению;

  • Ограничение размера загружаемых файлов — определяет максимально допустимый размер загружаемого файла.

Ограничения применяются только при загрузке файла в файловое хранилище и при получении файла из него. Если файл создается в прикладном коде и затем записывается в файловое хранилище, ограничения также применяются. Если файл формируется и используется внутри системы без загрузки в файловое хранилище, эти ограничения не срабатывают.

Для отдельных классов файлов можно настроить исключения из этих ограничений. Исключения задаются в классе Btk_FileRestrictionDisable по пути Сущности > Классы > Btk_FileRestrictionDisable.

Исключение настраивается для класса файла. Поддерживаются два варианта отключения ограничений:

  • Полное отключение — ограничения для указанного класса не применяются;

  • Отключение по скрипту — ограничения отключаются только при выполнении условий, заданных в процедуре.

При настройке отключения по скрипту можно указать процедуру, которая определяет, должно ли применяться исключение для конкретного файла.

Ограничения по размеру файлов особенно важны, потому что при работе с файлами система загружает файл в память целиком. Обработка файлов как потоков не используется.

При работе с файлами большого размера это может привести к исчерпанию памяти, превышению доступного лимита памяти и аварийному завершению работы приложения. Чтобы снизить этот риск, рекомендуется настраивать ограничения на размер загружаемых файлов.

Просмотр, скачивание и получение файлов для редактирования#

Для просмотра, скачивания и получения файлов для редактирования используется REST-пакет Btk_FileRestPkg.

Btk_FileRestPkg обеспечивает получение файлов из системы через REST-запросы. С его помощью можно решать следующие задачи:

  • открыть файл для просмотра;

  • скачать файл;

  • получить файл для последующего редактирования;

  • создать файл в указанном файловом хранилище через REST-запрос.

Btk_FileRestPkg используется:

  • для предпросмотра документов — getFileForView();

  • для скачивания — getFileForDownload();

  • для получения файла для редактирования — getFileForUpdate().

Для вызова методов Btk_FileRestPkg формируется REST-запрос, в который передается параметр ID_FILE с идентификатором файла. Например, для получения файла для редактирования может использоваться запрос:

/app/sys/rest/ss/pkg/Btk_FileRestPkg/getFileForUpdate?ID_FILE=28252

Этот пакет не связан напрямую с attach. Он взаимодействует с Btk_File и файловым хранилищем.

Удаление файла#

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

Если файл используется в сервисе прикрепленных файлов, удаление выполняется через связанные объекты: Btk_AttachItem, Btk_Attach, Btk_AttachVer и Btk_File.

При удалении документа с прикрепленными файлами:

  • удаляются его связи с прикрепленными файлами через Btk_AttachItem;

  • если прикрепленный файл отмечен как основной (bMain = 1), удаляются все связанные записи Btk_AttachItem и запись Btk_Attach;

  • при удалении Btk_Attach удаляются его версии;

  • при удалении версий выполняется стандартное удаление связанных файлов Btk_File;

  • если Btk_Attach имеет подписанные версии, его удаление запрещено.

Стандартное удаление Btk_File выполняется через Btk_FileApi().delete(...). Результат зависит от настроек файлового хранилища:

  • если для хранилища задан срок хранения удаленных файлов, файл помещается в файловую корзину;

  • если срок хранения не задан или равен 0, файл удаляется окончательно.

Окончательное удаление, минуя корзину, выполняют методы purge(...) и purgeBeforeFlush(...), а также регламент очистки файлов, срок хранения которых в корзине уже истек. Настройка очистки хранилища от устаревших файлов использует стандартное удаление с учетом параметров корзины.

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

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

Предпросмотр файлов#

Предпросмотр используется для открытия файла в интерфейсе системы без предварительного скачивания пользователем. В зависимости от формата система либо отображает исходный файл, либо использует PDF-файл предпросмотра. Момент создания PDF-файла зависит от настройки динамической генерации.

Поддерживаемые форматы предпросмотра#

Для форматов bmp, gif, jpg, jpeg, png, txt, pdf и stl предпросмотр поддерживается по умолчанию. Для таких файлов отдельный файл предпросмотра не создается: при нажатии кнопки Предпросмотр система выполняет REST-запрос, получает исходный файл из файлового хранилища и отображает его в интерфейсе.

Для форматов docx, doc, xls, xlsx, md, markdown и rtf прямой предпросмотр по умолчанию не поддерживается. Чтобы такие файлы можно было открыть через предпросмотр, система должна создать отдельный PDF-файл предпросмотра. При последующем открытии предпросмотра отображается не исходный файл, а созданный для него PDF-файл.

Примечание

Для файлов остальных форматов предпросмотр не поддерживается. Система не отображает такие файлы напрямую и не создает для них PDF-файл предпросмотра.

Настройки генерации PDF-файла предпросмотра#

Создание PDF-файла предпросмотра определяется двумя уровнями настроек: настройка класса или типа документа разрешает генерацию для соответствующего сценария, а общая настройка модуля btk задает момент создания файла.

Разрешение генерации#

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

Генерация разрешается характеристикой класса Создавать preview-файл для прикрепленных файлов. Система определяет класс объекта-источника по gidSrc.

Путь: Приложение «Настройка системы» > Сущности > Классы.

В карточке класса откройте вкладку Характеристики и найдите группу Группа настройки прикрепленных файлов.

Файлы документов Wf_Doc

Генерация разрешается флагом типа документа Wf_DocType.bCreatePDFForView — Создавать PDF для просмотра.

Настройку можно открыть одним из способов:

  • через приложение Документооборот > Настройки > Настройки документации > Типы документов;

  • через приложение Настройка системы > Сущности > Классы > Wf_Doc > Тип объекта > Настройки документа WF > Настройки.

Момент генерации#

Общая настройка модуля btk Динамическая генерация файлов предпросмотра определяет момент создания PDF-файла.

Путь: Приложение «Настройка системы» > Настройки и сервисы > Настройки модулей системы > Общие настройки модулей > btk > Файлы.

  • Если настройка включена, PDF-файл формируется при первом открытии предпросмотра.

  • Если настройка выключена, PDF-файл создается при загрузке исходного файла.

Настройка включена по умолчанию. Уже созданный PDF-файл используется повторно.

Хранение файла предпросмотра#

Отдельное файловое хранилище для предпросмотров не используется. Для документов Wf_Doc PDF-файл сохраняется в хранилище исходного файла, для прикрепленных файлов Btk_Attach — в стандартном хранилище прикрепленных файлов.

В файловом хранилище исходный файл и PDF-файл предпросмотра хранятся как отдельные файлы. В базе данных для них используются разные записи Btk_File.

Созданная для предпросмотра запись Btk_File помечается признаком Файл предпросмотра.

Очистка файлов предпросмотра#

Путь: Приложение «Настройка системы» > Настройки и сервисы > Настройки модулей системы > Общие настройки модулей > btk > Файлы.

Срок хранения PDF-файлов задается настройкой Срок хранения файлов предпросмотра в днях. Положительное значение включает автоматическую очистку. Если значение не задано, равно нулю или отрицательное, очистка не выполняется.

Регламентное задание Плановая очистка файлов предпросмотра запускается ежедневно в 01:00. После удаления файл предпросмотра может быть создан повторно при следующем обращении, если его генерация разрешена.

Открытие предпросмотра#

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

Для файлов прямого предпросмотра по кнопке Предпросмотр выполняется REST-запрос и отображается исходный файл. Для файлов, по которым уже создан PDF-файл предпросмотра, система открывает этот файл. Если PDF-файл предпросмотра еще не создан, система создает его при открытии. Если генерация запрещена настройкой класса или типа документа либо выполнить преобразование не удалось, система выводит соответствующее сообщение.

Связь между исходным файлом и файлом предпросмотра хранится в параметре PDF файл: в атрибуте idPdfFile версии прикрепленного файла Btk_AttachVer или в атрибуте idPDFFile версии документа Wf_DocVerFile.

Для получения файла при предпросмотре используется стандартный механизм выдачи файлов для просмотра, в том числе метод getFileForView() пакета Btk_FileRestPkg.

Нагрузка при генерации предпросмотра#

При включенной динамической генерации преобразование выполняется при первом открытии и может увеличить время ожидания предпросмотра. При выключенной динамической генерации преобразование выполняется при загрузке и может увеличить время обработки исходного файла.

Файловое API#

Для программной работы с файлами в системе используется файловое API. Оно применяется для создания записи Btk_File, выбора файлового хранилища, записи и чтения содержимого файла, а также для удаления или перемещения файлов.

Один из примеров использования файлового API — сохранение файла в системе с одновременным созданием записи Btk_File.

Например, если система уже получила входной поток файла, файл можно сохранить следующим образом:

val idFile = Btk_FilePkg().createAndFill(
    "test.pdf",
    inputStream
)

В этом сценарии файловое API:

  • создает запись Btk_File;

  • определяет файловое хранилище;

  • записывает физическое содержимое файла в файловое хранилище.

К основным компонентам файлового API относятся:

  • Btk_FileApi — API для работы с объектом Btk_File и его содержимым;

  • Btk_FileStorageApi — API для работы с файловыми хранилищами;

  • Btk_FileStorageTypeApi — API для работы с типами файловых хранилищ;

  • Btk_FilePkg — пакет с основной логикой работы с файлами: созданием записи Btk_File, записью содержимого файла, выбором файлового хранилища и вспомогательными операциями.

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

Основные методы создания и записи файла#

Для работы с файлами в системе используется пакет Btk_FilePkg. В нем реализованы следующие основные методы создания и записи файла:

  • createFile(...) — создает запись Btk_File и заполняет ее метаданные;

  • fill(...) — записывает содержимое в уже существующую запись файла;

  • createAndFill(...) — создает запись Btk_File и сразу записывает в нее содержимое файла;

  • createFileWithContent(...) — выполняет ту же операцию, что и createAndFill(...), но автоматически закрывает переданный поток.

Такое разделение нужно, потому что в системе создание записи Btk_File и запись физического содержимого файла — это разные операции.

Раздельное использование createFile(...) и fill(...) применяется в случаях, когда файл обрабатывается в несколько этапов. Например:

  • сначала нужно создать запись Btk_File, определить файловое хранилище и получить идентификатор файла;

  • затем связать этот файл с другими объектами системы;

  • после этого отдельным шагом записать физическое содержимое файла.

Такой подход полезен, если содержимое файла появляется не сразу либо если между созданием записи и загрузкой содержимого требуется выполнить дополнительную логику.

Метод fill(...) также можно использовать для перезаписи содержимого уже существующего файла. Например:

def updateFile(idpFile: NLong, bytes: Array[Byte]): Unit = {
    Btk_FilePkg().fill(idpFile, bytes)
}

createAndFill(...) используется в сценариях, когда запись Btk_File и физическое содержимое файла можно создать за один вызов.

Этот метод удобно применять, если файл сразу готов к сохранению. Если же система сначала создает запись о файле, связывает ее с другими объектами, а затем получает поток данных для записи, используются createFile(...) и fill(...) по отдельности.

Выбор файлового хранилища#

В файловом API выбор файлового хранилища выполняется методом chooseFileStorage(...) из пакета Btk_FilePkg.

Метод используется во внутренней логике файлового API и вызывается в сценариях, где системе нужно определить, в какое файловое хранилище сохранить или переместить файл. В частности, он применяется в методах создания и записи файла, например createFile(...) и createAndFill(...).

В метод передаются следующие параметры:

  • idpAttachFileType — тип прикрепляемого файла;

  • idpSrcObjectType — тип объекта-источника;

  • idpFileStorage — файловое хранилище, переданное явно; используется при ручном перемещении файла;

  • idpClassDoc — класс документа или объекта, для которого определяется файловое хранилище;

  • bpManualMoved — признак ручного перемещения файла. Если признак активен, используется файловое хранилище, переданное в idpFileStorage, а если оно не передано — файловое хранилище btkAttach;

  • bpTemp — признак временного файла, который участвует в логике выбора файлового хранилища.

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

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

val idFileStorage = Btk_FilePkg().chooseFileStorage(
    idpAttachFileType = idAttachType,
    idpSrcObjectType = idSrcObjectType,
    idpFileStorage = idStorage,
    idpClassDoc = idClassDoc,
    bpManualMoved = false,
    bpTemp = false
)

На практике этот метод обычно не вызывают отдельно в прикладной логике, а используют через более высокоуровневые методы файлового API, которые сами определяют файловое хранилище в процессе создания или записи файла.

Перемещение и удаление файлов#

В файловом API предусмотрены методы для перемещения и удаления файлов.

Для перемещения файлов используются:

  • autoMove() — автоматически перемещает файл в другое файловое хранилище в рамках внутренней логики системы. Метод применяется при изменении данных о файле, например типа прикрепления или типа объекта-источника, а также при очистке устаревших файлов с действием Переместить. Такое перемещение не считается ручным.

  • manualMove() — перемещает файл в другое файловое хранилище по явному действию пользователя и устанавливает признак, что файл был перемещен вручную. Этот метод используется в интерфейсе «Администрирование файловых хранилищ».

Разница между методами заключается в назначении:

  • autoMove() используется для автоматического перемещения файла по внутренним правилам системы;

  • manualMove() используется в сценариях, когда пользователь сам выбирает, в какое файловое хранилище нужно переместить файл.

Пример вызова manualMove():

val ropFile = Btk_FileApi().load(idpFile)
val idNewStorage = Btk_FileStorageApi().findByMnemoCode("customStorage")
Btk_FileApi().manualMove(ropFile, ropFile.get(_.idFileStorage), idNewStorage)

Пример для autoMove() будет аналогичным.

Для удаления файлов используются:

  • Btk_FileApi().delete(...) — выполняет стандартное удаление с учетом настроек файловой корзины;

  • Btk_FileApi().purge(...) — выполняет окончательное удаление записи Btk_File и содержимого файла;

  • Btk_FileApi().purgeBeforeFlush(...) — откладывает вызов окончательного удаления до beforeFlush.

Метод setbDeleted(...) изменяет значение признака bDeleted и самостоятельно не удаляет содержимое файла из файлового хранилища.

Пример стандартного удаления:

val ropFile = Btk_FileApi().load(idpFile)
Btk_FileApi().delete(ropFile)

Подробнее о порядке удаления см. в разделе Удаление файла. Внутренняя реализация механизма описана в разделе Файловая корзина.

Файловый контекст#

При работе с файлом файловое API использует служебный объект — файловый контекст. Он содержит дополнительные данные, которые используются при обработке файла, выборе файлового хранилища и выполнении связанной логики, например при проверке ограничений на загрузку файлов.

Файловый контекст представляет собой case class со следующими полями:

  • gidpSrc — источник;

  • spExt — расширение;

  • params — карта параметров [String, Any].

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

Поле params позволяет передавать в файловое API дополнительные параметры, которые не входят в фиксированный набор полей файлового контекста.

Вставка изображений в прикрепленные файлы типов Word и PDF#

Для вставки изображений в прикрепляемые файлы документа настройте нужные изображения в коллекции-расширении «Настройки вставки изображений» для типа объекта этого документа.

В коллекции доступны следующие настройки:

  • Активность — определяет, будет ли изображение вставлено в прикрепленный файл.

  • Печатная форма — указывается форма типа Jasper с форматом PNG. Передается один аргумент: IDDOC (ID документа).

  • Изображение — файл в формате PNG.

    Примечание

    Если указана печатная форма, файл изображения удаляется. При загрузке изображения ссылка на печатную форму удаляется.

  • Положение изображения по осям X, Y — определяет координаты. Точка отсчета — нижний левый угол документа.

  • Ширина и высота изображения — задают размер вставляемого изображения.

Как только в коллекции появится активное изображение, в отображении прикрепленных файлов для документов данного типа становятся доступны операции:

  • вставка изображения в один документ;

  • вставка изображения во все документы сразу.

Содержание