Как не сломать XML-pipeline: peek, transform и работа с InputStream

В интеграционных системах часто возникает типовая задача: частично заглянуть в XML-документ, чтобы принять решение о дальнейшей обработке. Как правило, нужно проверить одно-два значения и, в отдельных случаях, скорректировать XML перед передачей его дальше по pipeline.

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

Важно подчеркнуть, что в подобных pipeline речь идет не столько о парсинге XML как формате, сколько о потоковой обработке данных. Ошибки здесь возникают не из-за XML, а из-за неправильного обращения с InputStream: неявного чтения, скрытой материализации, некорректного использования mark/reset и размытых границ ответственности между этапами обработки.

Эта статья — не про DOM, SAX или конкретные библиотеки. Она про то, как выстроить устойчивый XML-pipeline, в котором:

• peek используется только для принятия решения,
• transform выполняется осознанно и изолированно,
• а работа с InputStream не приводит к поврежденным документам и трудноуловимым багам под нагрузкой.

Чтение XML через строку

Самый прямолинейный подход в такой ситуации — прочитать весь XML целиком в строку, выполнить проверки и при необходимости создать новый поток:

String xml = IOUtils.toString(inputStream, charset);

if (xml.contains("<Tag>Value</Tag>")) {
    xml = xml.replace(
        "<ReportName>REP01</ReportName>",
        "<ReportName>REP02</ReportName>"
    );
}

InputStream result = IOUtils.toInputStream(xml, charset);

Этот вариант часто используется как стартовое решение и выглядит вполне разумно, особенно если документ невелик и логика проста.

Почему это кажется удобным

Код в этом случае получается максимально очевидным:

• Читается последовательно;
• Легко отлаживается;
• Не требует понимания особенностей работы потоков;
• Позволяет использовать стандартные строковые операции, регулярные выражения или XPath.

Для единичных документов или прототипов этого зачастую достаточно.

Какие проблемы это создает

При использовании такого подхода в реальном интеграционном pipeline начинают проявляться системные ограничения:

• XML полностью загружается в память, независимо от того, нужен ли весь документ;
• Данные несколько раз копируются между представлениями (byte[] → char[] → byte[]);
• Возрастает нагрузка на сборщик мусора;
• Производительность деградирует при росте размера документов или их количества.

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

Попытка оптимизации: mark / reset

После первого решения через строку обычно возникает логичная мысль: зачем читать весь XML, если нужно проверить только начало? Следующий шаг — попробовать использовать возможности самого InputStream:

• поставить mark();
• прочитать первые N байт;
• вызвать reset();
• передать поток дальше по pipeline.

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

Что здесь скрыто

Проблема в том, что у mark/reset есть ряд неочевидных ограничений, которые легко пропустить:

• не каждый InputStream вообще поддерживает mark/reset;
• mark() работает только в пределах указанного readLimit;
• поведение сильно зависит от того, какими обертками поток уже окружен;
• BufferedInputStream и другие декораторы меняют поведение потока.

В результате код может выглядеть корректно, компилироваться и даже работать в тестах — но ломаться в реальном pipeline.

Что на самом деле делает mark / reset

Проблема с mark/reset почти всегда возникает из-за неправильной ментальной модели. Обычно кажется, что мы управляем позицией чтения, но в реальности это не так.

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

Три разных сущности

1. Источник данных Файл, сокет, HTTP-соединение, BLOB из базы данных. В большинстве интеграционных сценариев источник: однонаправленный, не поддерживает «перемотку назад», не знает ничего про mark или reset.

2. InputStream Это не источник, а посредник между источником и кодом. Он читает байты у источника и отдает их потребителю.

3. Потребитель Код, который вызывает read(), read(byte[]), toString() и т. п.

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

Схематично это выглядит так:

[ источник данных ] ---> [ InputStream ] ---> [ ваш код ]
                             |
                          (внутренний буфер)

Что делает mark()

Вызов mark() не запоминает позицию в источнике. Он означает следующее:

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

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

Параметр readLimit — это обещание со стороны потребителя:

«Я не буду читать больше N байт, если захочу потом вернуться назад».

Что делает reset()

reset() не возвращает поток к источнику. Он означает:

«Перестань читать новые байты у источника и начни отдавать мне то, что ты сохранил в своем буфере».

То есть после reset():

• чтение идет из внутреннего буфера InputStream;
• источник данных в этот момент вообще не участвует;
• если буфер был очищен — возвращаться уже некуда.

Откуда берется ограничение readLimit

readLimit существует по простой причине: InputStream не может хранить бесконечное количество данных.

Если:

• прочитано ≤ readLimit байт → reset() возможен;
• прочитано > readLimit байт → старые данные выбрасываются;
• дальнейший reset() либо не работает, либо приводит к ошибке.

Поэтому mark/reset — это договор, а не гарантия.

Ключевой вывод

mark/reset — это механизм временного кэширования байт, а не управление позицией чтения:

• источник данных никогда не перематывается;
• InputStream всегда читает источник только вперед;
• иногда он может «проиграть» уже прочитанные байты повторно;
• но только в пределах своего буфера и по собственным правилам.

Именно это различие становится критичным, когда в цепочке появляются обертки (BufferedInputStream, TempInputStream и пр) и несколько потребителей одного потока.

Почему peek через обертки ломает pipeline

Теперь, когда понятно, что mark/reset — это работа внутри конкретного InputStream, становится ясно, откуда берется самая распространенная ошибка.

Типичный сценарий выглядит так:

• входящий InputStream оборачивается в BufferedInputStream;
• mark() и reset() вызываются на этой обертке;
• дальше по pipeline используется другой объект потока (или исходный поток).

С точки зрения кода все выглядит корректно:

• исключений нет;
• reset() успешно отрабатывает;
• методы возвращают ожидаемые значения.

Но фактически происходит следующее:

• исходный источник данных читается только один раз и только вперед;
• обертка (BufferedInputStream) читает часть байт и кладет их во свой внутренний буфер;
• downstream-код читает не тот же самый буфер, а поток, который уже продвинулся дальше.

Важно подчеркнуть ключевой момент:

reset возвращает чтение только для того InputStream, на котором был вызван mark.

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

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

Именно поэтому peek через обертки — не просто неудачное решение, а источник тихих и трудноотлавливаемых багов.

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

Когда речь идет о работе с потоками, ключевая ошибка — пытаться решить сразу все в одном месте: и заглянуть в XML, и что-то в нем поменять, и передать дальше как было. На практике это почти всегда приводит к неявным побочным эффектам.

Гораздо устойчивее подход, при котором ответственность разделяется на три разных шага: peek, transform и boundary.

Peek — только чтение

Peek — это этап, на котором поток только читается, но не изменяется. Типичный пример — нужно понять, стоит ли вообще что-то делать с документом:

String type = peekTagValue(inputStream, "Type", 8 * 1024);
if (!"REPORT".equals(type)) {
    // дальше идем по обычному пути
}

На этом этапе важно одно: поток после peek должен остаться в том же логическом состоянии, в каком он был до него.

Peek не должен модифицировать байты, менять кодировку, создавать новые версии потока или «случайно» продвигать чтение вперед. Если поток был использован для peek — это должно быть осознанное и локальное действие, а не побочный эффект.

Transform — отдельный шаг

Если после peek становится понятно, что XML нужно изменить, начинается другая задача — трансформация. Здесь допустимы только два честных подхода.

Первый — потоковая обработка «байт → байт», когда вход читается последовательно и на выход сразу пишется результат:

InputStream transformed =
        XmlStreamReplaceUtils.replaceSimpleTagValue(
                inputStream,
                "DocKind",
                "CUSTOM",
                charset
        );

Второй — явная материализация:

String xml = IOUtils.toString(inputStream, charset);
// изменения
InputStream transformed = IOUtils.toInputStream(xml, charset);

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

Peek и transform — это разные этапы с разными свойствами и разными рисками.

Boundary — явная граница потока

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

• старый поток больше не используется;
• создан новый источник данных;
• downstream-код читает чистый поток с позиции 0.

Пример boundary выглядит просто:

InputStream newStream = new ByteArrayInputStream(bytes);

или:

TempInputStream temp = CommonIOUtils.createTempInputStream(inputStream);

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

В таком виде pipeline становится предсказуемым:

1. Peek — быстрое и безопасное принятие решения.
2. Transform — осознанная модификация данных.
3. Boundary — чистый контракт между этапами.

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

End-to-end пример: peek → transform → boundary

Ниже — упрощенный, но целостный пример, который объединяет все три этапа в одном месте. Он показывает, где именно принимается решение, где происходит модификация, и где поток разрывается.

public InputStream processXml(
    InputStream input, 
    Charset charset
) throws IOException {

    // --- 1. Peek: принимаем решение ---
    String type = XmlPeekUtils.peekTagValue(input, "Type", 8 * 1024);

    if (!"REPORT".equals(type)) {
        // ничего не делаем — возвращаем исходный поток
        return input;
    }

    // --- 2. Transform: осознанно меняем данные ---
    InputStream transformed =
            XmlStreamReplaceUtils.replaceSimpleTagValue(
                    input,
                    "DocKind",
                    "CUSTOM",
                    charset
            );

    // --- 3. Boundary: downstream читает новый поток ---
    return transformed;
}

Здесь важно не то, что именно заменяется в XML, а как выстроен контроль над потоком:

• peek выполняется один раз и не влияет на дальнейшее чтение;
• transform всегда создает новый InputStream;
• boundary явно обозначен возвратом нового источника данных.

В таком виде код легко читать, отлаживать и сопровождать. Главное — он не зависит от неявных свойств mark/reset, оберток и внутреннего состояния потоков.

Если позже потребуется заменить потоковую трансформацию на DOM или SAX — это можно сделать, не ломая общую архитектуру.

DOM, SAX и другие альтернативы

После того как становится понятно, почему простые приемы с InputStream и mark/reset могут ломать pipeline, логично задать вопрос: а какие вообще есть альтернативы и когда их стоит использовать?

Ниже — разбор подходов с точки зрения памяти, скорости и контроля над обработкой.

String-подход

Самый простой и самый распространенный вариант — полностью прочитать поток в строку:

String xml = IOUtils.toString(inputStream, charset);
// анализ, замены, regex, XPath
InputStream out = IOUtils.toInputStream(xml, charset);

Плюсы:

• максимальная простота;
• удобно отлаживать;
• легко применять replace, regex, XPath.

Минусы:

• весь документ загружается в память;
• двойное копирование: byte[] → char[] → byte[];
• высокая нагрузка на GC;
• плохо масштабируется при большом потоке документов.

Этот подход допустим:

• для мелких XML;
• в оффлайн-задачах;
• там, где производительность не критична.

В интеграционных pipeline под нагрузкой — почти всегда плохой выбор.

DOM

DOM делает примерно то же самое, что и строковый подход, но с дополнительным шагом — построением дерева XML.

Document doc = DocumentBuilderFactory.newInstance()
        .newDocumentBuilder()
        .parse(inputStream);

Плюсы:

• полный контроль над структурой документа;
• удобная навигация по узлам;
• хорошо подходит для сложных изменений.

Минусы:

• потребление памяти растет пропорционально размеру XML;
• медленный старт (парсинг + построение дерева);
• непригоден для больших документов и высоких нагрузок.

DOM — хороший инструмент для:

• конфигурационных файлов;
• административных утилит;
• случаев, где важна выразительность, а не скорость.

SAX

SAX — событийная модель: XML читается последовательно, парсер вызывает callbacks.

parser.parse(inputStream, handler);

Плюсы:

• минимальное потребление памяти;
• высокая скорость;
• отлично подходит для больших XML.

Минусы:

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

SAX хорош, когда:

• нужно валидировать или агрегировать данные;
• структура XML стабильна;
• изменения минимальны или отсутствуют.

Для задач вида «посмотреть тег → заменить один элемент → передать дальше» SAX часто оказывается избыточным.

Потоковая обработка байт

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

InputStream out = XmlStreamReplaceUtils.replaceSimpleTagValue(
        inputStream,
        "tag",
        "newValue",
        charset
);

Плюсы:

• линейное чтение;
• минимальный overhead;
• практически нулевая нагрузка на GC;
• отлично масштабируется.

Минусы:

• ограничения на структуру XML;
• нет валидации;
• ответственность за корректность лежит на разработчике.

Этот подход оптимален, когда:

• нужно заменить 1–2 простых тега;
• важна производительность;
• XML проходит дальше по pipeline без сложных манипуляций.

Как выбрать подход

Короткое практическое правило:

• String / DOM — удобно, но дорого.
• SAX — быстро, но сложно.
• Streaming bytes — быстро и дешево, но требует дисциплины.

В интеграционных системах с большим потоком документов чаще всего выигрывает последний вариант — при условии, что архитектура четко разделяет peek, transform и boundary.

Типичные ошибки при работе с InputStream в XML‑pipeline

После того как базовая архитектура (peek → transform → boundary) выстроена, на практике чаще всего ломается не логика, а работа с потоками как таковыми. Ниже — набор типичных ошибок, которые регулярно всплывают в интеграционных системах.

Закрытие обертки закрывает источник

Одна из самых коварных проблем связана с тем, что большинство оберток делегируют close() внутрь:

InputStream original = ...;
BufferedInputStream bis = new BufferedInputStream(original);
bis.close(); // закрывает и original

Мы можем считать, что освободили буфер, но фактически:

• исходный поток закрыт;
• downstream больше не может читать данные;
• ошибка проявляется далеко от места закрытия.

Это особенно опасно, когда:

• BufferedInputStream создается временно для peek;
• close() вызывается в finally на всякий случай.

Правило: если поток будет использоваться дальше — не закрывай обертку.

Использование try-with-resources не в том месте

Конструкция try-with-resources отлично подходит для:

• файлов;
• сокетов;
• явных boundary.

Но она опасна в середине pipeline:

try (BufferedInputStream bis = new BufferedInputStream(input)) {
    // peek
}
// input уже закрыт

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

Rule of thumb:

Закрывает поток тот, кто его открыл как boundary.

Повторное использование InputStream после transform

Еще одна частая ошибка — продолжать использовать старый поток после трансформации:

InputStream transformed = transform(input);
// ...
use(input); // ошибка

После transform:

• старый поток может быть частично или полностью вычитан;
• его состояние больше не определено;
• поведение зависит от конкретной реализации.

Скрытая материализация «под капотом»

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

• IOUtils.toString();
• XML‑валидаторы;
• XPath;
• DOM‑парсеры.

Это не всегда ошибка, но это должно быть осознанным решением, а не побочным эффектом.

Надежда на mark/reset как на rewind

mark/reset часто воспринимаются как способ отмотать поток назад. Это неверно, эти методы не управляют источником данных, зависят от readLimit, могут работать в одной обертке и ломаться в другой.

Если нужен rewind — нужен boundary.

Как все это складывается в одну картину

Если обобщить, надежный XML‑pipeline выглядит так:

• поток читается один раз;
• peek выполняется локально и осознанно;
• transform либо потоковый, либо явно материализующий;
• boundary четко обозначает смену источника данных;
• закрытие потока происходит строго на границе ответственности.

Все остальные подходы рано или поздно приводят к багам, которые:

• сложно воспроизвести;
• проявляются только под нагрузкой;
• выглядят как битый XML без причины.