.. _gs3_images_file_storage_images:

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

.. versionadded:: 1.29.0-ms1

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

.. seealso::

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

        - :xsd:attr:`Параметры эндпоинтов (Endpoints) -> Эндпоинт получения изображений из файлового хранилища (imageFromFileStorageEndpoint) <Configuration.Endpoints.imageFromFileStorageEndpoint>`

    .. dropdown:: Метаданные Oracle решения

        - :ref:`Редактор-изображение (Icon) -> Свойство imageSource <oracle_attribute_properties_image_source>`
        - :ref:`Редактор-изображение (Icon) -> Свойство imageStretch <oracle_attribute_properties_image_stretch>`
        - :ref:`Группа дополнительных свойств (Opt) -> Свойство attrType <oracle_attribute_properties_add_attrtype>`
        - :ref:`Группа дополнительных свойств (Opt) -> Свойство hrefFieldName <oracle_attribute_properties_add_hreffieldname>`
        - :ref:`Группа дополнительных свойств (Opt) -> Свойство nvlBlobName <oracle_attribute_properties_add_nvlblobname>`
        - :ref:`Группа дополнительных свойств (Opt) -> Свойство brokenLinkEqNull <oracle_attribute_properties_add_brokenlinkeqnull>`

    .. dropdown:: Метаданные Postgres решения

        - :xsd:attr:`Редактор-изображение (Icon) -> Свойство imageSource <View.Representation.Attributes.Attribute.Editor.Icon.imageSource>`
        - :xsd:attr:`Редактор-изображение (Icon) -> Свойство imageStretch <View.Representation.Attributes.Attribute.Editor.Icon.imageStretch>`
        - :xsd:attr:`Источник изображения (ImageSource) <View.Representation.Attributes.Attribute.Editor.ImageSource>`
        - :xsd:attr:`Группа дополнительных свойств (Opt) -> Свойство attrType <View.Representation.Attributes.Attribute.Opt.attrType>`
        - :xsd:attr:`Группа дополнительных свойств (Opt) -> Свойство hrefFieldName <View.Representation.Attributes.Attribute.Opt.hrefFieldName>`
        - :xsd:attr:`Группа дополнительных свойств (Opt) -> Свойство nvlBlobName <View.Representation.Attributes.Attribute.Opt.nvlBlobName>`
        - :xsd:attr:`Группа дополнительных свойств (Opt) -> Свойство brokenLinkEqNull <View.Representation.Attributes.Attribute.Opt.brokenLinkEqNull>`
        - :xsd:attr:`Типы атрибута (AttributeTypes) <View.Representation.Attributes.Attribute.Opt.AttributeTypes>`

    .. dropdown:: GTK Core API

        - :java:type:`Редактор-изображение (Icon) -> Свойство imageSource <Icon.imageSource>`
        - :java:type:`Редактор-изображение (Icon) -> Свойство imageStretch <Icon.imageStretch>`
        - :java:type:`Источник изображения (ImageSource) <ImageSource>`
        - :java:type:`Группа дополнительных свойств (Opt) -> Свойство attrType <Opt.addAttrType>`
        - :java:type:`Группа дополнительных свойств (Opt) -> Свойство hrefFieldName <Opt.hrefFieldName>`
        - :java:type:`Группа дополнительных свойств (Opt) -> Свойство nvlBlobName <Opt.nvlBlobName>`
        - :java:type:`Группа дополнительных свойств (Opt) -> Свойство brokenLinkEqNull <Opt.brokenLinkEqNull>`
        - :java:type:`Типы атрибута (AttributeTypes) <ru.bitec.gtk.core.gl.meta.pojo.attrs.AttributeTypes>`

Назначение
----------

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

Хранение
--------

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

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

.. _gs3_images_file_storage_images_extensions:

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

- ``.jpeg``
- ``.jpg``
- ``.png``
- ``.ico``

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

.. _gs3_images_file_storage_images_receiving:

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

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

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

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

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

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

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

.. list-table::
    :header-rows: 1

    * - Элемент
      - Что делает
    * - Конфигурация сервера: :xsd:class:`Endpoints.ImageFromFileStorage<Configuration.Endpoints.ImageFromFileStorage>`.
      - Настраивает эндпоинт :ref:`getImageFromFileStorage <uri_endpoint_reference_get_image_from_file_storage>` на стороне сервера. 
    * - Метаданные выборки: :xsd:attr:`Icon.imageSource<View.Representation.Attributes.Attribute.Editor.Icon.imageSource>`
      - Указывает источник изображения для редактора :xsd:class:`Icon <View.Representation.Attributes.Attribute.Editor.Icon>`.
        Для того, чтобы редактор был настроен на получение изображений из файлового хранилища сервера, нужно установить свойство :xsd:attr:`imageSource <View.Representation.Attributes.Attribute.Editor.Icon.imageSource>` в значение :xsd:attr:`attribute<View.Representation.Attributes.Attribute.Editor.ImageSource.attribute>`.
    * - Метаданные выборки: :xsd:attr:`Opt.attrType<View.Representation.Attributes.Attribute.Opt.attrType>`
      - Устанавливает тип атрибута, в котором будет отображаться изображение из файлового хранилища сервера.
        Для того, чтобы атрибут был настроен на отображение изображений из файлового хранилища сервера, нужно установить свойство :xsd:attr:`attrType <View.Representation.Attributes.Attribute.Opt.attrType>` в значение :xsd:attr:`hrefBlob<View.Representation.Attributes.Attribute.Opt.AttributeTypes.hrefBlob>`.
    * - Метаданные выборки: :xsd:attr:`Opt.hrefFieldName<View.Representation.Attributes.Attribute.Opt.hrefFieldName>`
      - Указывает в каком атрибуте выборки будет храниться путь к изображению из файлового хранилища сервера.
    * - Метаданные выборки: :xsd:attr:`Opt.nvlBlobName<View.Representation.Attributes.Attribute.Opt.nvlBlobName>`
      - Указывает в каком атрибуте выборки будет храниться запасное изображение из файлового хранилища сервера.
    * - Метаданные выборки: :xsd:attr:`Opt.brokenLinkEqNull<View.Representation.Attributes.Attribute.Opt.brokenLinkEqNull>`
      - Определяет, будет ли отображаться запасное изображение из :xsd:attr:`nvlBlobName<View.Representation.Attributes.Attribute.Opt.nvlBlobName>`,
        если в атрибуте из :xsd:attr:`hrefFieldName<View.Representation.Attributes.Attribute.Opt.hrefFieldName>` указан путь к изображению, но его не удалось загрузить.
    * - HTTP-эндпоинт: :ref:`EngineEndpoint.getImageFromFileStorage <uri_endpoint_reference_get_image_from_file_storage>`
      - Позволяет получить изображение из файлового хранилища сервера.

Логирование
~~~~~~~~~~~

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

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

.. list-table::
    :header-rows: 1

    * - Уровень
      - Что попадает в лог
    * - ``DEBUG``
      - Всё, что пишет ``INFO``, плюс исход каждого запроса: ``200``, ``304``, ``400`` и ``404``
        по штатным причинам.
    * - ``INFO``
      - Всё, что пишет ``WARN``, плюс старт и остановка эндпоинта и смена статуса доступности
        whitelist-группы.
    * - ``WARN``
      - Всё, что пишет ``ERROR``, плюс попытка выйти за пределы whitelist'а, несоответствие
        сигнатуры файла расширению и обращение к недоступной группе.
    * - ``ERROR``
      - Только сбои сервера: ошибки ввода-вывода и непредвиденные исключения.

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

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

.. code-block:: XML
    :caption: Фрагмент logback-LoggerContext.xml

    <logger name="ru.bitec.webserver.session.imagefromfilestorage" level="debug"/>

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

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

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

    .. code-block:: XML
        :caption: Фрагмент 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>

    .. code-block:: XML
        :caption: Фрагмент метаданных выборки

        <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"/>

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

    .. list-table::
        :header-rows: 1
        :widths: 10 28 28 28 18

        * - 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``
          - Ячейка останется без изображения

.. dropdown:: Прикладной проект на Oracle

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

    .. code-block:: XML
        :caption: Фрагмент 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>

    .. code-block::
        :caption: Свойства атрибута IMAGE

        EDITORTYPE=etIcon
        IMAGESOURCE=eisSelectionFieldBlob
        IMAGESTRETCH=true
        ADD.ATTRTYPE=attrHrefBlob
        ADD.HREFFIELDNAME=PHOTO_PATH
        ADD.NVLBLOBNAME=IMAGE_PREVIEW
        ADD.BROKENLINKEQNULL=true

    .. code-block::
        :caption: Свойства атрибута IMAGE_PREVIEW

        ADD.ATTRTYPE=attrHrefBlob
        ADD.HREFFIELDNAME=PHOTO_PREVIEW_PATH
        ADD.NVLBLOBNAME=IMAGE_DEFAULT
        ADD.BROKENLINKEQNULL=true

    .. code-block::
        :caption: Свойства атрибута IMAGE_DEFAULT

        ADD.ATTRTYPE=attrHrefBlob
        ADD.HREFFIELDNAME=PHOTO_DEFAULT_PATH
        ADD.BROKENLINKEQNULL=false

    .. code-block::
        :caption: Свойства атрибута PHOTO_PATH

        Visible=false

    .. code-block::
        :caption: Свойства атрибута PHOTO_PREVIEW_PATH

        Visible=false

    .. code-block::
        :caption: Свойства атрибута PHOTO_DEFAULT_PATH

        Visible=false

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

    .. list-table::
        :header-rows: 1
        :widths: 10 28 28 28 18

        * - 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``
          - Ячейка останется без изображения

Особенности
------------

- Механизм предназначен только для табличного представления.
- Копирование, экспорт и печать не передают изображение как содержимое ячейки.
- Внешние HTTP-URL не являются источником изображений для этого механизма.
- Различия Linux и Windows определяются контрактами :xsd:attr:`whitelist-паттернов<Configuration.Endpoints.ImageFromFileStorage.Whitelist.EmbeddedSource.WhitelistGroup.Entry.pattern>` и значений :xsd:attr:`hrefFieldName<View.Representation.Attributes.Attribute.Opt.hrefFieldName>`.

Рекомендации
------------

- Описывайте файловое хранилище через небольшие :xsd:attr:`whitelist-группы<Configuration.Endpoints.ImageFromFileStorage.Whitelist.EmbeddedSource.WhitelistGroup>` с понятными именами: это упрощает диагностику и анализ логов.
- Используйте :xsd:attr:`Opt.nvlBlobName<View.Representation.Attributes.Attribute.Opt.nvlBlobName>` только для осмысленных запасных изображений: например, оригинал -> предпросмотр -> изображение по умолчанию.
- На промежуточных звеньях цепочки резервных изображений обычно полезно задавать ``brokenLinkEqNull="true"``, а на последнем звене оставлять значение по умолчанию.
- Не используйте этот механизм для статичных пиктограмм интерфейса. Для них лучше подходят :ref:`коллекции изображений <gs3_images_image_collections>` или :ref:`ресурсы прикладного проекта <gs3_images_scala_images>`.

.. seealso::

    - :ref:`Спецификация сервиса изображений - Коллекции изображений <gs3_images_image_collections>`
    - :ref:`Спецификация сервиса изображений - Изображения ресурсов прикладного проекта <gs3_images_scala_images>`