5.13.4. Изображения из файлового хранилища сервера

Added in version 1.29.0-ms1.

Application Server предоставляет API для работы с изображениями из файлового хранилища сервера.

See also

Конфигурация сервера
Метаданные Oracle решения
Метаданные Postgres решения
GTK Core API

5.13.4.1. Назначение

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

5.13.4.2. Хранение

Изображения располагаются в следующих местах:

  • В файловом хранилище сервера. В таком случае, доступ к изображениям осуществляется при помощи указания абсолютного пути к ним. Например: /mnt/share/images/*.png (Linux), C:/Global3/images/*.png (Windows).

  • В сетевом ресурсе (Только для Windows). В таком случае, доступ к изображениям осуществляется при помощи указания UNC-пути к ним. Например: //fileserver/share/global3/*.png.

5.13.4.3. Поддерживаемые расширения

  • .jpeg

  • .jpg

  • .png

  • .ico

Важно: Расширение и содержимое файла проверяются на соответствие друг другу. Например, если изображение имеет расширение .png, но его содержимое такое, будто это .php, то такое изображение не может быть получено.

5.13.4.4. Получение изображений

Доступ к изображениям из файлового хранилища сервера осуществляется при помощи EngineEndpoint.getImageFromFileStorage.

5.13.4.5. Использование в прикладном коде

Механизм работает как связка конфигурации сервера, метаданных выборки и HTTP-эндпоинта:

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

  • Метаданные выборки: Настройка атрибутов для вывода изображений.

  • HTTP-эндпоинт: Получение изображений из файлового хранилища сервера.

5.13.4.5.1. Конфигурация и настройка

Элементы механизма получения изображений из файлового хранилища:

Элемент

Что делает

Конфигурация сервера: Endpoints.ImageFromFileStorage.

Настраивает эндпоинт getImageFromFileStorage на стороне сервера.

Метаданные выборки: Icon.imageSource

Указывает источник изображения для редактора Icon. Для того, чтобы редактор был настроен на получение изображений из файлового хранилища сервера, нужно установить свойство imageSource в значение attribute.

Метаданные выборки: Opt.attrType

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

Метаданные выборки: Opt.hrefFieldName

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

Метаданные выборки: Opt.nvlBlobName

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

Метаданные выборки: Opt.brokenLinkEqNull

Определяет, будет ли отображаться запасное изображение из nvlBlobName, если в атрибуте из hrefFieldName указан путь к изображению, но его не удалось загрузить.

HTTP-эндпоинт: EngineEndpoint.getImageFromFileStorage

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

5.13.4.5.2. Логирование

Эндпоинт пишет лог через штатный механизм настроек логирования, источник лога - пакет ru.bitec.webserver.session.imagefromfilestorage.

Уровни перечислены от самого подробного к самому краткому: каждый следующий отсекает то, что писал предыдущий.

Уровень

Что попадает в лог

DEBUG

Всё, что пишет INFO, плюс исход каждого запроса: 200, 304, 400 и 404 по штатным причинам.

INFO

Всё, что пишет WARN, плюс старт и остановка эндпоинта и смена статуса доступности whitelist-группы.

WARN

Всё, что пишет ERROR, плюс попытка выйти за пределы whitelist’а, несоответствие сигнатуры файла расширению и обращение к недоступной группе.

ERROR

Только сбои сервера: ошибки ввода-вывода и непредвиденные исключения.

По умолчанию - INFO.

Чтобы увидеть исход отдельных запросов, задайте источнику уровень DEBUG:

Фрагмент logback-LoggerContext.xml
<logger name="ru.bitec.webserver.session.imagefromfilestorage" level="debug"/>

5.13.4.5.3. Примеры использования

Прикладной проект на Postgres

В данном примере табличное отображение показывает только колонку image. Основное изображение берётся из поля photo_path. Если основное изображение отсутствует или не загрузилось, используется запасное изображение из поля photo_preview_path. Если запасное изображение тоже отсутствует или не загрузилось, используется следующее запасное изображение из поля photo_default_path.

Фрагмент global3.config.xml
<endpoints>
    <imageFromFileStorageEndpoint>
        <whitelist>
            <embeddedSource>
                <group name="photos">
                    <entry pattern="/var/global3/photos/**/*.{png,jpg,jpeg}"/>
                </group>
                <group name="previews">
                    <entry pattern="/var/global3/previews/**/*.jpg"/>
                </group>
                <group name="defaults">
                    <entry pattern="/var/global3/defaults/**/*.png"/>
                </group>
            </embeddedSource>
        </whitelist>
    </imageFromFileStorageEndpoint>
</endpoints>
Фрагмент метаданных выборки
<attr name="image" caption="Фото" isVisible="true" editorType="icon">
    <editor>
        <icon imageSource="attribute" imageStretch="true"/>
    </editor>
    <opt attrType="hrefBlob"
         hrefFieldName="photo_path"
         nvlBlobName="image_preview"
         brokenLinkEqNull="true"/>
</attr>

<attr name="image_preview" isVisible="false">
    <opt attrType="hrefBlob"
         hrefFieldName="photo_preview_path"
         nvlBlobName="image_default"
         brokenLinkEqNull="true"/>
</attr>

<attr name="image_default" isVisible="false">
    <opt attrType="hrefBlob"
         hrefFieldName="photo_default_path"
         brokenLinkEqNull="false"/>
</attr>

<attr name="photo_path" isVisible="false"/>
<attr name="photo_preview_path" isVisible="false"/>
<attr name="photo_default_path" isVisible="false"/>

Фейковые данные выборки:

id

photo_path

photo_preview_path

photo_default_path

Результат

101

/var/global3/photos/101.png

/var/global3/previews/101.jpg

/var/global3/defaults/person.png

Отобразится 101.png

102

null

/var/global3/previews/102.jpg

/var/global3/defaults/person.png

Отобразится 102.jpg

103

/var/global3/photos/missing-103.png

/var/global3/previews/103.jpg

/var/global3/defaults/person.png

Отобразится 103.jpg

104

/var/global3/photos/missing-104.png

/var/global3/previews/missing-104.jpg

/var/global3/defaults/person.png

Отобразится person.png

105

/var/global3/photos/missing-105.png

/var/global3/previews/missing-105.jpg

null

Ячейка останется без изображения
Прикладной проект на Oracle

В данном примере табличное отображение показывает только колонку IMAGE. Основное изображение берётся из поля PHOTO_PATH. Если основное изображение отсутствует или не загрузилось, используется запасное изображение из поля PHOTO_PREVIEW_PATH. Если запасное изображение тоже отсутствует или не загрузилось, используется следующее запасное изображение из поля PHOTO_DEFAULT_PATH.

Фрагмент global3.config.xml
<endpoints>
    <imageFromFileStorageEndpoint>
        <whitelist>
            <embeddedSource>
                <group name="photos">
                    <entry pattern="/var/global3/photos/**/*.{png,jpg,jpeg}"/>
                </group>
                <group name="previews">
                    <entry pattern="/var/global3/previews/**/*.jpg"/>
                </group>
                <group name="defaults">
                    <entry pattern="/var/global3/defaults/**/*.png"/>
                </group>
            </embeddedSource>
        </whitelist>
    </imageFromFileStorageEndpoint>
</endpoints>
Свойства атрибута IMAGE
EDITORTYPE=etIcon
IMAGESOURCE=eisSelectionFieldBlob
IMAGESTRETCH=true
ADD.ATTRTYPE=attrHrefBlob
ADD.HREFFIELDNAME=PHOTO_PATH
ADD.NVLBLOBNAME=IMAGE_PREVIEW
ADD.BROKENLINKEQNULL=true
Свойства атрибута IMAGE_PREVIEW
ADD.ATTRTYPE=attrHrefBlob
ADD.HREFFIELDNAME=PHOTO_PREVIEW_PATH
ADD.NVLBLOBNAME=IMAGE_DEFAULT
ADD.BROKENLINKEQNULL=true
Свойства атрибута IMAGE_DEFAULT
ADD.ATTRTYPE=attrHrefBlob
ADD.HREFFIELDNAME=PHOTO_DEFAULT_PATH
ADD.BROKENLINKEQNULL=false
Свойства атрибута PHOTO_PATH
Visible=false
Свойства атрибута PHOTO_PREVIEW_PATH
Visible=false
Свойства атрибута PHOTO_DEFAULT_PATH
Visible=false

Фейковые данные выборки:

id

PHOTO_PATH

PHOTO_PREVIEW_PATH

PHOTO_DEFAULT_PATH

Результат

101

/var/global3/photos/101.png

/var/global3/previews/101.jpg

/var/global3/defaults/person.png

Отобразится 101.png

102

null

/var/global3/previews/102.jpg

/var/global3/defaults/person.png

Отобразится 102.jpg

103

/var/global3/photos/missing-103.png

/var/global3/previews/103.jpg

/var/global3/defaults/person.png

Отобразится 103.jpg

104

/var/global3/photos/missing-104.png

/var/global3/previews/missing-104.jpg

/var/global3/defaults/person.png

Отобразится person.png

105

/var/global3/photos/missing-105.png

/var/global3/previews/missing-105.jpg

null

Ячейка останется без изображения

5.13.4.6. Особенности

  • Механизм предназначен только для табличного представления.

  • Копирование, экспорт и печать не передают изображение как содержимое ячейки.

  • Внешние HTTP-URL не являются источником изображений для этого механизма.

  • Различия Linux и Windows определяются контрактами whitelist-паттернов и значений hrefFieldName.

5.13.4.7. Рекомендации

  • Описывайте файловое хранилище через небольшие whitelist-группы с понятными именами: это упрощает диагностику и анализ логов.

  • Используйте Opt.nvlBlobName только для осмысленных запасных изображений: например, оригинал -> предпросмотр -> изображение по умолчанию.

  • На промежуточных звеньях цепочки резервных изображений обычно полезно задавать brokenLinkEqNull="true", а на последнем звене оставлять значение по умолчанию.

  • Не используйте этот механизм для статичных пиктограмм интерфейса. Для них лучше подходят коллекции изображений или ресурсы прикладного проекта.

See also